docs(task-decomposition): 46号文档 Phase 3 v2 真实端到端回归

真实 CEO 心跳发现并派发 decomposed_work 子任务，递归防护、依赖阻塞都验证生效。org-coder 在没有 brd/prd/sdd 的轻量图里产出质量真实达标（正确的单位换算实现 + 完整边界测试），但 org-validator 卡在硬依赖的 acceptance.json 上（只有 org-planner 会产出）——轻量图执行没问题，验证这一半有真实的结构性缺口，摆了三个方向留给下一步讨论。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01H85SS5hVC4u1PbVhjmrhH8

docs(task-decomposition): 46号文档 Phase 3 v2 真实端到端回归
真实 CEO 心跳发现并派发 decomposed_work 子任务，递归防护、依赖阻塞都验证生效。org-coder 在没有 brd/prd/sdd 的轻量图里产出质量真实达标（正确的单位换算实现 + 完整边界测试），但 org-validator 卡在硬依赖的 acceptance.json 上（只有 org-planner 会产出）——轻量图执行没问题，验证这一半有真实的结构性缺口，摆了三个方向留给下一步讨论。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01H85SS5hVC4u1PbVhjmrhH8
yibo
1 parent 5d095609
Showing 1 changed file with 18 additions and 3 deletions
docs/todo/system-design/46-mandatory-planning-and-task-decomposition.md
 # 46 · Planning 应作为每个任务的默认前置步骤，覆盖三类信息来源
-> **状态**: 📝 设计中——四个关键决策已拍板。**Phase 0 已完成**（2026-09-01 真实回归验证）：链路能收敛、44 号文档修复确认生效，发现的独立缺陷已拆到 [47 号文档](./47-itemized-subtask-materialization-goal-benchmark-fallback.md) 并修复。**Phase 1 代码已实现**（2026-09-02，见「Phase 1 实现记录」）：新 agent `subtask-planning` + `enqueueTaskRun` 挂钩（收窄为显式 opt-in）+ 复用 R-9.3 任务级共享索引对接下游，单测覆盖，**但还没做真实端到端回归**（且过程中出过一次真实 CLI 子进程泄漏事故，已修复并加了测试环境防护，见该节）。**Phase 2 已实现且已做真实端到端回归（收窄版，2026-09-02，见「Phase 2 实现记录」）**：经验检索（新查询能力，扫已雇 agent 的 dream 沉淀）+ 按需 deep research（图外调用 org-hunt，默认关闭）。真实回归第一次就跑出一个真缺陷（关键词打分噪音压过信号，导致"经验库有答案"分支误触发）并已修复验证；两条真实任务的分解内容质量都好，但 deep research 分支目前更接近"多问一个角色的第二意见"而非真的做了外部检索（org-hunt 那次调用没有工具调用痕迹），如实记在实现记录里。"历史同类 goal 检索"这条来源本轮明确收窄未做。**Phase 3 走过一轮推翻重来（2026-09-02）**：v1（"认领"pull 语义 + CAS）已实现并做过真实回归，但回归本身就暴露出"认领后没有触发源"的真问题，讨论后发现"认领"要解决的"多方竞争"场景根本不存在（只有 CEO 一人拍板要不要派）——**v2 改成 CEO 心跳直接发现+派发（push），删掉了 v1 的整套认领机制**，改为 CEO 判断节奏后调现成的 `/enqueue`，子任务默认走一张现造的轻量 work graph（`org-coder` 实现 + `org-validator` 验证两个节点，跳过公司完整 org graph 的规划仪式），效果不理想再升级成完整 org graph（见「Phase 3 v2」）。v1 设计和实现记录原样保留、标了废弃（留作决策过程的第一手记录，不是白做）。v2 单测覆盖，**但还没做真实端到端回归**——尤其"org-coder/org-validator 在轻量图里没有 brd/prd/sdd 上游产物时表现如何"是一条明确写清楚、没验证过的假设。Phase 4（独立开发验证循环）、Phase 5（看板 UI）仍未设计，留给后续
+> **状态**: 📝 设计中——四个关键决策已拍板。**Phase 0 已完成**（2026-09-01 真实回归验证）：链路能收敛、44 号文档修复确认生效，发现的独立缺陷已拆到 [47 号文档](./47-itemized-subtask-materialization-goal-benchmark-fallback.md) 并修复。**Phase 1 代码已实现**（2026-09-02，见「Phase 1 实现记录」）：新 agent `subtask-planning` + `enqueueTaskRun` 挂钩（收窄为显式 opt-in）+ 复用 R-9.3 任务级共享索引对接下游，单测覆盖，**但还没做真实端到端回归**（且过程中出过一次真实 CLI 子进程泄漏事故，已修复并加了测试环境防护，见该节）。**Phase 2 已实现且已做真实端到端回归（收窄版，2026-09-02，见「Phase 2 实现记录」）**：经验检索（新查询能力，扫已雇 agent 的 dream 沉淀）+ 按需 deep research（图外调用 org-hunt，默认关闭）。真实回归第一次就跑出一个真缺陷（关键词打分噪音压过信号，导致"经验库有答案"分支误触发）并已修复验证；两条真实任务的分解内容质量都好，但 deep research 分支目前更接近"多问一个角色的第二意见"而非真的做了外部检索（org-hunt 那次调用没有工具调用痕迹），如实记在实现记录里。"历史同类 goal 检索"这条来源本轮明确收窄未做。**Phase 3 走过一轮推翻重来（2026-09-02）**：v1（"认领"pull 语义 + CAS）已实现并做过真实回归，但回归本身就暴露出"认领后没有触发源"的真问题，讨论后发现"认领"要解决的"多方竞争"场景根本不存在（只有 CEO 一人拍板要不要派）——**v2 改成 CEO 心跳直接发现+派发（push），删掉了 v1 的整套认领机制**，改为 CEO 判断节奏后调现成的 `/enqueue`，子任务默认走一张现造的轻量 work graph（`org-coder` 实现 + `org-validator` 验证两个节点，跳过公司完整 org graph 的规划仪式），效果不理想再升级成完整 org graph（见「Phase 3 v2」）。v1 设计和实现记录原样保留、标了废弃（留作决策过程的第一手记录，不是白做）。**v2 已做真实端到端回归**：真实 CEO 心跳确实发现并派发了子任务（顺手还修了一个真实的、影响面更大的 bug——两套心跳系统的自环调用一直缺内部令牌、暗中 401），递归防护、依赖阻塞都验证生效；`org-coder` 在没有 brd/prd/sdd 的轻量图里产出质量真实达标，但 `org-validator` 卡在硬依赖的 `acceptance.json`（只有 org-planner 会产出）上——**轻量图的执行没问题，验证这一半有真实的结构性缺口**，需要另外决定怎么补（见「Phase 3 v2」结尾三个方向）。Phase 4（独立开发验证循环）、Phase 5（看板 UI）仍未设计，留给后续
 > **日期**: 2026-09-01
 > **触发场景**: 用户复盘 [43 号文档](./43-task-decomposition-granularity.md)（goal 分解粒度）时，追问"为什么本地和线上所有公司的任务看板都没有子任务分解"。核实后发现：不是巧合或配置遗漏，`acceptance_mode='itemized'` 在当前系统里**从未被真正触发并落库过一次**——追问引出了比 43 号文档更大的架构缺口：43 号文档只解决"验收要不要拆细"，而用户认为**规划（把一件事拆成第一步/第二步/第三步）本身应该是每个任务默认必经的前置步骤，不是一个可选的、可以被判"不需要"的例外**。
 > **格式对齐** `27-requirement.md`/`43-task-decomposition-granularity.md`：原话照搬 + 结构化复述，现状调研另起一节。
@@ -468,6 +468,21 @@ v1 真实回归跑完，用户追问&quot;认领后没有触发源，谁来触发&quot;—
 `org-coder`/`org-validator` 平时**只在"公司完整 org graph 的 subgraph 节点"这个上下文里被调用过**——它们的 `agent.md`/`tools.md` 有没有隐含"前面一定有 brd/prd/sdd 产物"这种假设，直接当轻量图里的裸 `agent_call` 节点调用，会不会读不到预期上下文、表现异常——**没有实测过**。图的机制本身（建图、起 run、CAS 判据不冲突）单测覆盖了，但"跑起来输出好不好"是内容问题，机制通不通答不了这个问题。这正是用户拍板"先跑轻量版看效果"这句话里"看效果"的意思——下一步真实回归要验的就是这个。
-### 还没做真实端到端回归
+### 真实端到端回归（2026-09-02，已完成，机制全部验证通过，效果发现一个真实结构性缺口）
-机制层面（物化→ CEO 心跳发现→ `/enqueue` →轻量图跑起来→状态收敛）已经用单测验证，但**没有一次真实的 CEO 心跳发现并派发过一条真实的 `decomposed_work` 子任务**。真实回归要检查：① CEO 读了 `heartbeat.md` 新加的这段指令后，是否真的会去查、去判断节奏、去调 `/enqueue`（提示词有没有写清楚，是纯 prompt 工程问题，不是这次代码改动能保证的）；② 轻量图跑完，`org-coder`/`org-validator` 在没有 brd/prd/sdd 上游产物的情况下产出质量如何（就是上面那条没验证过的假设）；③ 一条 task 拆出多条子任务、CEO 一次性全部 `enqueue` 后，`task-scheduler` 的依赖阻塞和并发槽位是否真的像讨论时判断的那样"自动处理好节奏"，不需要 CEO 操心。这次不建议顺手跑（吸取 Phase 1/2 的教训），留给用户后续决定何时验证。
+用真实公司 `p2verify0902` 走完一次真实链路——真实 goal→task→dispatch → `subtask-planning` 产出 2 步分解并物化成 `decomposed_work` 草稿 → **真实 CEO 心跳**（不是模拟）读到 `heartbeat.md` 新加的指令后，真的查了 `?subtaskKind=decomposed_work&status=draft`、真的判断了节奏、真的调了 `/enqueue`——不只是这两条，CEO 还顺带自己发现并处理了一条与本次测试无关的历史遗留卡住的 run（证明心跳修复后其余巡检逻辑也正常了）。触发过程中确认 `triggerSubtaskPlanning` 的递归防护在真实场景下正确拦下了对子任务本身再拆一层的尝试（8 条 `decomposed_work` 行全部被正确跳过）。
+
+**一处真实的额外发现（与 Phase 3 无关，但直接堵住了这次验证，顺手修了）**：触发 CEO 心跳时先撞上 401——`company-heartbeat-service.js`/`heartbeat-service.js` 里所有自环调用 `/api/agent/:agentId/chat`（`agent-chat.js` 挂了 `requireAuthOrInternal`）**都没有带内部令牌**，而 `company.js`/`task-settle.js` 的同类自环调用早就在带。也就是说**心跳系统的两条自触发路径（含 CEO 心跳）一直在暗中 401**，失败只落一行 `console.warn`，界面上什么都看不出来。已按现成模式补上 `INTERNAL_TOKEN_HEADER`（两个文件），修完确认心跳能正常跑完整段推理会话。这条影响面比 Phase 3 大得多，值得单独跟进核实生产环境是否也受影响。
+
+**"看效果"的真实结果——机制通，内容质量分裂**：
+
+- `org-coder`（impl 节点）**表现完全达标**：给单位换算任务真实产出了 `src/convert.js`（正确的换算因子：km=1000/m=1/mi=1609.344/ft=0.3048）+ 一份质量相当好的测试文件（含同单位恒等、非法单位报错、往返精度、浮点容差等边界情况），**完全没有 brd/prd/sdd 上游产物，产出依然靠谱**——这条验证了"轻量图跳过 org-planner 规划仪式"这个核心假设成立。
+- `org-validator`（validate 节点）**卡死，`input_underspecified`**：它调用的 `goal-contract.js validate --run-dir` 硬性要求 `artifacts/acceptance.json` 存在，而这份文件只由 org-planner 的 work graph（`goal-benchmark`/`goal-test-data`/`goal-test-script` 三个节点）产出——轻量图完全跳过了 org-planner，这份文件天然不存在。**org-validator 自己给出的诊断相当精确**：明确写"本次上游 coder 节点已产出 src/convert.js + test/convert.test.js，属正常交付，不是本次失败的责任方"，把根因准确指向 org-planner 缺位，`target_org_node` 字段也写对了。
+- 依赖阻塞也验证了：第二个子任务（依赖第一个）在第一个卡在 `blocked`（不是 `completed`）后，正确地没有被调度器放行，一直停在 `queued`——`task-scheduler` 的既有依赖推导对 `decomposed_work` 子任务同样生效，不需要 CEO 自己算顺序，讨论时的判断成立。
+
+### 结论：轻量图的"实现"这一半跑通了，"验证"这一半有一个真实的结构性缺口
+
+不是 agent 表现不好，是图的构成本身缺一块——`org-validator` 依赖的验收契约只能来自 org-planner，轻量图里没有任何节点能产出它。**这不是"再调一下提示词"能解决的**，是"要不要跳过 org-planner"这条设计决策本身的直接代价。摆几个方向留给下一步讨论：
+1. 轻量图加一个第三节点，专门产出一份最小的 `acceptance.json`（不跑 org-planner 整套 brd/prd/sdd，只把 `subtask-planning` 已经写好的"这一步要做什么"转成 goal-contract 认的验收格式）；
+2. `org-validator` 之外找一个不依赖 `goal-contract.js`/`acceptance.json` 的轻量验证方式（比如直接跑 `org-coder` 自己写的测试文件、看退出码）；
+3. 按用户原话的退路——这条子任务级别就不追求跑通 `org-validator`，直接升级成完整 org graph（这就是当初讨论"先跑轻量版看效果，不行再走完整 org graph"里"不行"的具体触发条件）。