宜博 / lemonboss

把「人类提的一个需求」与「机器执行的一件活」拆成两级。这不是新概念：
27-NAMING §四 早就定义了 goal 1 : task N，graph_runs.goal_id / task_id
两列从 P3 起就一直在写，却没有任何表接得住 —— 本次补上那两张缺席的表。

## 交付
- goals / tasks 两张表 + CRUD + depends_on 环检测 + ID 生成器
  T-{base36}-{4hex}：原格式同毫秒必撞，而 tasks.id 是主键，
  「一个 goal 拆 N 条 task」是循环建行，撞了就是 500
- goal / task 全套端点；POST /:cid/tasks 向后兼容（不带 goal_id 自动
  建 goal）；退役 /api/goals 与 /:cid/goals 两个 OKR 别名（零调用方）
- 终态回写 + goal 收敛 + OKR 写一次：钩子挂在唯一漏斗
  graph-run-sse.transitionRun 上，而不是枚举路径 —— stopRun 与
  「预算耗尽 → blocked」两条最常见的释放路径都不走 settleRun，
  枚举一次漏一次。goal 收敛用 CAS 闸门，并行完成的 N 个 task 只有
  一个赢家做不可重放的副作用（写 OKR / 唤醒上级）
- blocked 在 task/goal 两层都不是终态：它是「挂起等人介入」，
  与 completed/failed/cancelled 不同类。否则预算耗尽后加预算恢复、
  跑完，两次条件更新静默命中 0 行，最终 run=completed 而
  task=blocked/goal=failed/OKR=failed 永久对不上（实跑复现过）
- goal 级是唯一汇报出口：删掉 run 级 reportRunOutcome（零其它调用方），
  1 goal:1 task 形态下它会把上级 agent 就同一件事唤醒两次
- dispatch 挑第一条可跑的 draft，而不是恒取 seq 最小那条 ——
  否则「第 1 条依赖第 2 条」这种合法输入会让 goal 永远下达不了
- 路径缺陷：writeTaskGoalArtifact 不认 GRAPH_RUNS_DIR 而读侧认，
  设了 env 就写进 A 处、从 B 处读，describeTask 拿到 null 后静默退回
  兜底文案「执行图节点任务」；三处模块加载时快照改为调用时读
- 存量回填脚本（幂等 + --dry-run）：不做的话批 1 反而让历史任务
  更看不见 —— 正是本批要修的问题的反向放大

## 过程
三轮多 agent 编排 + 每轮对抗复核，共报出 19 条缺陷（10 条首轮实现的、
4 条第二轮修复引入的、5 条判定为非问题）。全部已修并有用例覆盖。
新增测试 4 个文件，含不变式测试 runs-root-single-holder（凡是声明了
GRAPH_RUNS_DIR 覆盖的模块，该覆盖必须真的被用到）。

全量：116 文件 / 1057 测试全绿。

## 未做（属批 2-5）
task-planning 与 goal 级 org-validator 验收（批 2）、调度器与
run_status='queued'（批 3）、并行（批 4）、两套任务体系统一（批 5）。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

R-19.A 把 declareEdgeContract 的调用方补上之后，inboundContracts 终于非空，
「沿边传递」这类数据流在真跑里生效了（真实规划 agent 自己在边上写出了
produces/needs 声明）。本次收掉它留下的三个缺口。

1) role 落库（第 14 次「四环漏一环」）
   normalizeContracts 产出 role，declareEdgeContract 入参没有它、表也没这列 ——
   产生 → 传递(丢) → 落库 → 读回。后果不止是控制台不精确：规则 6（data-contract）
   靠「有人 needs 但没人 produces」判错，只存 kind 就没法从库里重算，而
   patchGraph 第 5 步的重新校验读的正是库 —— 增量 PATCH 又恰恰是
   「此前满足的 needs 失去产出方」的唯一发生地，校验偏偏在最该生效的通道上失效。
   - graph_edge_contracts 加 role 列（CHECK + 老库 ALTER 后回填 produces：
     NULL 在规则 6 里既不算产出也不算需求，会误拒一张合法的图；闸门宁可漏判不可错拦）
   - 两层调用点透传 role；readGraph 把 contracts 读回来并递进 validateGraph

2) 控制台三字段（前端在、后端没喂）
   GET /api/graph-runs/:id 补 edges[].contracts / companyRoot / taskFiles，
   否则 R19-C 那三块界面整块降级：声明和索引都在库里，界面上看不见。
   contracts 只在非空时出现，与 failReason 同一个约定。

3) 收拢 companyRootDir/taskDirRel 镜像
   goal-contract.js 里那份镜像靠注释约定「与 graph-engine 逐字同构」维持，
   控制台路由成为第三个调用方时这个约定就不成立了。抽到 company-paths.js，
   GRAPH_RUNS_DIR 改为调用时读（原先两个模块各自在加载时快照，
   加载顺序不同会算出不同的根）。goal-contract 那条「镜像漂了就报警」的用例
   按其自身预告改成比函数返回值。

测试 826 全绿（+11：role 8 / 路由 3），既有断言未改。
11 处变异逐一验证精确变红后逐字还原；其中一条断言初版在 fixture 上永远自洽
（图里没有无声明的边），补了一条无声明的边才真正有判别力。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

界面走查（真 server + HTTP + 真 AgentManager，底层 mock 协议）已把
manual 模式全流程点通：org 节点起子图 → 下钻 work graph → 单步 →
第 3 步触发回退（徽标 0/3→1/3、run 级 1/5 双层计数同时可见）→
归因记录与 remediation_note 完整送达 → 收敛后父节点结算、左栏前移。

mock 侧补两处缺失接线（都是「四环漏一环」，非新功能）
- ClaudeCliProtocol._sendMockPrompt 按 agent 类型查 fixture：图执行侧的
  agent 名带公司前缀（resolveAgentName 返回 {cid}:{id}），fixture 不该
  按公司复制一份。DevLoop 侧名字不含冒号，行为不变
- graph-engine.defaultAgentExecutor 接住 mock/files 事件：此前只有
  DevLoop 的 loop-controller 接，图执行侧没接，于是 mock 下
  readNodeProduct 永远找不到 attempt-{n}.json，validator 系节点恒 blocked。
  写入限制在节点产物目录内，越界丢弃并留痕

新增 5 份 P3 fixture（workgraph-planning / prd-planning / sdd-planning /
coder-validator / validator-triager），coder-validator 用 sequence 演示
一次回退。图必须放 chunks 不能只放 result——callAgent 的 output 来自
流式 chunks，session/result 的文本不进 output。

控制台入口：CompanyDashboard 加「🕸️ 执行控制台」按钮（路由早已注册，
此前无任何入口，只能手敲 URL）。

scripts/p3-demo-setup.js：手工测试准备脚本（雇人+写图+起 run），头部
写明它是两个已知缺口的绕行，缺口修好后第 1 步即可删。

_registry.json 补齐 6 条本体登记（brd/prd/sdd-planning、goal-benchmark、
benchmark/testdata-validator）——同轮新增的 template-refs 防线测试正是
因为缺这 6 条而变红，防线抓到了「交付与报告不符」。

文档
- 27-REQ R-18：招聘归 workgraph-planning（方案 a）、停用 mock 改真 CLI
- 27-P3B 真实运行前置（新增）：11 个工作项分三批，含现状核实 10 条证据
  （seedTemplates 无运行时调用方、10 条悬空 company_hired 行、
   FAILING_VERDICTS 不含 "fail" 导致验收假放行等）

测试 719/719 全绿（66 文件）。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

按 27-p3-p4-work-graph-console.md v0.3 实现，三轮开发+校验后测试全绿
（693/693，P2 26/26、DevLoop 230/230 未被打破，web:build 干净）。

服务层
- work-graph-db.js  定义层(work_graph_*) + 运行时层(graph_runs/graph_run_nodes/
  graph_run_loop_records) 五张表；状态转换表照 unit-registry 模式；
  复用 org-graph-service 四项校验 + 新增第五项 fail-fallback-edge
- graph-engine.js   advanceOne 幂等原语；agent_call / subgraph 两种 executor；
  手动与自动共用同一原语；双层熔断（单边 loop_count + 按 root_run_id 共池的
  backward_count）；任务级预算挂 root run；三层暂停/停止级联；
  重试按 contract_hash unchanged 判据
- graph-run-sse.js  按 run_id 广播，状态转换+timeline+SSE 三者原子化
- goal-contract.js  验收契约格式与执行器（R-15.6 验收先行）

引擎泛化（R-15.4）：org graph 与 work graph 走同一套 advanceOne，
定义层两套、运行时层一套，三层下钻用 parent_run_id 链。

R-16 失败归因：validator-reflection 专职归因节点；fail_reason 多边路由
（精确匹配→兜底边→死路）；子 run 收敛透传 success/fail + fail_reason +
remediation_note 三值；infra_flake 不烧任何计数。

路由 / 前端 / 模板
- routes/graph-run.js 八个端点；company.js 任务入口
- WorkGraphCanvas.vue 扩展 UnitsDAG（subgraph 角标、backward 虚线曲线、
  N/3 循环徽标、异常流程视觉降权）；GraphConsole.vue 三栏 + 四 tab 详情
- 五个新 agent 模板：validator-reflection / org-validator / planner-validator /
  coder-validator / workgraph-planning

命名统一（R-15.3 + NAMING §三）：org 节点改为 org-{职能}，
三个 org-graph 模板末节点收敛到 org-validator；org_graph_edges 加 fail_reason
列并把唯一索引补上该列（避免精确边与兜底边互相吞掉）。

三轮校验修掉的主要缺陷：subgraph 重跑不起新子 run 导致永久死锁；
SSE/timeline 零调用方；org 侧 fail_reason 写入被丢弃；fail-fallback-edge
只做了一层；backward_count 跨 run 树重置架空熔断外层；
seedEntryNodes 误点亮只有 fail 入边的节点。

已知缺口见后续提交：remediation_note 仅在 backward 边落库、
total_tokens 预算维度无生产方。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>