48-task-acceptance-contract-binding.md 19.6 KB

Edit Raw Blame History


48 · Task/Subtask 验收契约 1:1 强绑定

状态: ✅ 已实现（主力机制，decomposed_work 链路）。安全网仍只是原则，未写代码。
日期: 2026-09-02
触发场景: 46 号文档 Phase 3 v2 真实回归时，org-validator 在轻量子任务图（org-coder 实现 → org-validator 验证，跳过公司完整 org graph 的 org-planner 规划仪式）里卡死——goal-contract.js validate --run-dir 报 input_underspecified（没有 acceptance.json），org-validator 按它自己的硬指令"退 org-planner 重跑"，但这张轻量图里压根没有 org-planner 节点，退无可退。追问下去牵出一个更根本的问题："验收契约由谁产出"这件事目前完全绑死在"公司完整 org graph 一定会跑到 org-planner"这个假设上，任何不满足这个假设的执行路径都会撞上同一类死锁。


讨论纪要（结构化复述，不是单条原话，是几轮讨论收敛出的结论）
用户最初的观察："org validator 因为没 org planner 的产出就卡死了？而不是按照 task 的要求去 validator？" ——直觉是 validator 应该"以 task 为主"，文件只是参考物，不该是硬性评判标准。

讨论过程中的几个关键转折：


查证后发现"卡死"是设计使然，不是疏漏——org-validator/tools.md 第 45 行原文："跑不出判决：没契约/契约非法/参数错 → input_underspecified，退 org-planner。不是「那就跳过这条」"。这条硬约束背后的理由是这个系统这几个月反复验证过的教训（43/44/47 号文档）：让 agent 拿自然语言 task 描述自由判断"算不算做完"不可靠，所以验收必须走结构化契约，不能自由心证。这条纪律本身不该改。
真正该改的是"契约从哪来"——用户提炼："硬约束的产生应该是自由灵活的，不至于被卡死"。也就是说：消费端（validator 只认结构化契约、不自由判断）该保持硬约束；产出端（谁来写这份契约）不该被锁死在单一角色（org-planner）身上。
讨论过一个"运行时兜底级联"方案（用户提出）：org-planner 写 → 没有则 subtask-planning 写 → 都没有则 code 节点自己写 → 都没有则 validator 自己补一份再判、有问题就把 bug + 自己写的验收标准一起打回给上游重做。这个逻辑本身站得住，但有两个问题：


对 decomposed_work 这条链路，第 3/4 层永远不会被触发——decomposed_work 子任务只有一个产生入口（materializeDecomposedSubtasks，只在 subtask-planning 成功产出 steps 之后才会被调用），所以"没有 planner、也没有 subtask-planning"这个前提在这条链路上不可能成立。给一条不可达的路径写实现，是在为不存在的场景预先建模。
更本质的问题：同一个 agent 既写验收标准、又拿着自己刚写的标准去判自己/别人刚做完的东西，跟"先出考卷再考试"比，可信度天然打折——即便格式上仍是结构化契约，也更容易"照着已经做出来的答案凑标准"。运行时兜底能保证流程不会永久卡死，但不能同等程度地保证补出来的东西和事先写好的一样可信。

收敛到的方案：创建时强绑定（预防性，主力机制）+ 运行时兜底（纠正性，安全网，仅记录原则，本轮不实现）。具体："每一个 task/subtask 天然带着自己的验收契约，这在创建那一刻就必须有，写在 tasks 表的字段上，1:1 强绑定"——用户原话："这样是不是更简单？"。确认：是，比"在某个特定图形状里临时补数据"更彻底，因为约束点提到了 createTask 这个所有创建路径的公共入口，不用每条路径各自记得要不要造契约。


现状调研（本次讨论核实的代码事实）
acceptance.json / acceptance.md / goal-benchmark.json 是三个不同的东西（讨论中容易混用，需要先分清）


产物
落点
产出方
消费方
格式


acceptance.json（R19-B 契约）
tasks/{taskId}/acceptance.json，goal-contract.js
goal-benchmark 节点（唯一真正调 put 的 agent）
org-validator/coder-validator/benchmark-validator/testdata-validator/planner-validator/validator-triager
结构化 JSON，{benchmark, test_data, test_script} 三段


acceptance.md
org-planner 私有目录
org-planner/agent.md 硬约束要求的四份产物之一
43 号文档的 maybeMaterializeItemizedSubtasks（首选数据源）
Markdown 验收表格


goal-benchmark.json
runs/{rootRunId}/artifacts/（共享区）
goal-benchmark 节点
goal-contract.js（被 $ref 指到）+ maybeMaterializeItemizedSubtasks 兜底数据源（47 号文档新增）
结构化 JSON，dimensions[]/traceability[]


本文档只关心第一个（acceptance.json，org-validator 真正用来判卷的那份）。跟 43/47 号文档的"子任务物化"是两回事，不要混。
契约产出链是 workgraph-planning 现场展开出的子图节点，不是独立体系
org-planner 执行时，workgraph-planning 依据 planner.json 骨架（brd → prd → sdd → benchmark → validator）+ 一套裁剪判据现场规划出子图。benchmark 节点被标注"不可裁"——理由是它产的 acceptance 被另一张图（org-validator 宿主的 validator.json）跨图消费，裁了就是跨图断供。也就是说，现有机制里"契约一定会被产出"这件事，本身建立在"workgraph-planning 一定会把 goal-benchmark 节点规划进图里"这个假设上——这个假设只在完整 org graph 路径里成立，46 号文档的轻量子任务图完全绕开了 workgraph-planning，这个假设自然不成立。
写入 API 已经是现成的、可直接程序化调用的函数
server/services/goal-contract.js 导出 writeContract(runDir, contract) 和 writeContractSection(runDir, {section, content, goalId, createdBy})——后者是"产出侧唯一该用的入口"（文件内注释原话），CLI 的 put 子命令只是它的一层包装。两者都是纯函数、不依赖 CLI 进程，可以直接从 enqueueTaskRun（Node.js 代码）里调用，不需要 shell 出去跑 goal-contract.js put。

test_script 段的形状要求：{runner: 'node', path: <artifacts/ 内相对路径>, args?, timeout_ms?}——runner 白名单目前只有 node。


设计决策
主力机制：tasks 表新增 1:1 字段，createTask 统一校验（预防性）
新增列（暂定名 acceptance_contract，TEXT，JSON blob，形状复用 goal-contract.js 的 {benchmark, test_data, test_script}，走应用层校验、不新造格式——跟 acceptance_mode/subtask_kind 同一套迁移写法，ALTER TABLE ADD COLUMN，新建库有 CHECK、存量库应用层守）。createTask 用 goal-contract.js 已经导出的 validateContract 做形状校验，不重写一遍规则。


⚠️ 这段的具体形状被真实回归推翻了一半，见下方「实现记录」§「与原设计的出入」：最终落地的 acceptance_contract 存的是 benchmark 段本身（{dimensions, overall_pass_threshold?}），不是这里写的三段式 wrapper——校验/写入时才现套一层。本段留着不改是为了如实记录设计过程，别照这段的字面形状抄代码。


本轮范围只收在 decomposed_work 这条链路（subtask-planning → materializeDecomposedSubtasks → enqueueTaskRun 的轻量图分支），不动 task-planning、org-planner 的 acceptance_item 物化、人类/CEO 快速派单（POST /:companyId/tasks）这几条创建路径——task-planning 在 46 号文档 Phase 1 设计时就明确保护过"职责不变、极简、3 轮内、不碰磁盘"，把"必须交结构化验收契约"这个要求推给它，值得单独起一轮讨论，不该这次顺手带上。
安全网（仅记原则，本轮不写代码）：发现缺失时就地补一份，但不与判卷同一次完成
如果以后出现另一种既没有 subtask-planning 也没有 org-planner 的图形状，撞上契约缺失时的兜底原则：发现者退一步，先独立于已完成的产出补一份契约，再判——不要在同一次调用里"边写标准边照着标准判"，尽量保住"先立标准、后判"这个顺序。这条原则不需要现在写成代码，decomposed_work 这条链路走主力机制就已经完全覆盖，留给以后真的出现新图形状时再决定怎么接。
与既有机制的边界

org-coder、org-validator、goal-benchmark 等所有既有 agent 的 agent.md/tools.md 不需要改一行——它们不关心契约从哪来，enqueueTaskRun 把契约落到它们熟悉的 artifacts/acceptance.json 位置，对它们来说和平时公司完整 org graph 产出的契约没有区别。
43/47 号文档的物化机制（acceptance.md/goal-benchmark.json → acceptance_item 子任务）完全不受影响，是另一套东西。


开发规划：需要改动的 agent 和代码（盘点）
Agent（提示词层面，只有一个要改）


Agent
改动
为什么


subtask-planning
agent.md 输出契约新增字段——每个 step 除了 title/why/depends_on_hint，还要交一份最小验收标准（形状对齐 goal-contract.js 的某个 section，具体哪个见下"待定"）。这需要真的理解"这一步做完该长什么样"，不能用代码从 why 字段机械转写（转出来的东西大概率是"尽量/基本可用"这类不可度量措辞，goal-contract.js/org-validator 明确拒收）
这是本轮唯一需要改提示词的 agent


org-coder、org-validator、goal-benchmark、coder-validator 等
不改
见上"与既有机制的边界"


代码


文件
改动


server/services/work-graph-db.js
tasks 表加 acceptance_contract 列（批 7 迁移）；createTask 新增同名参数 + 用 goal-contract.validateContract 校验；TASK_FROZEN_FIELDS 收进这个字段（排队后不许再改，跟 budgetJson 那几个字段同待遇）


server/services/subtask-planning.js
解析 LLM 输出里新增的验收字段，materializeDecomposedSubtasks 建每条 decomposed_work 行时把它写进 acceptance_contract


server/routes/company.js（enqueueTaskRun）
decomposed_work 分支：起 run 之前，读 taskRow.acceptance_contract，调 goal-contract.writeContractSection（或 writeContract），把它落进这条新 run 目录的 artifacts/acceptance.json，登记进 graph_files（writeContractSection 内部已经做，不用额外重复登记，需确认）


server/services/goal-contract.js
大概率不用改——writeContract/writeContractSection/validateContract/SECTIONS 已经导出，直接复用


测试
createTask 校验（新增/非法值拒绝）；materializeDecomposedSubtasks 正确落 acceptance_contract 字段；enqueueTaskRun 正确把它写进新 run 的 artifacts/acceptance.json（可以直接读文件断言）；一条端到端回归——真的走一遍轻量图，确认 org-validator 这次能读到契约、不再 input_underspecified


一处待定，写实现前要先定案 —— ✅ 已定案：benchmark 段
subtask-planning 该交哪个 section（benchmark/test_data/test_script）取决于怎么落地最自然：test_script 形状是 {runner:'node', path, args?, timeout_ms?}——直觉是指向 org-coder 会写的测试文件（这次真实回归里 org-coder 确实主动写了 test/convert.test.js），但 subtask-planning 在 org-coder 动手之前就要交契约，那时候还不知道 org-coder 最终会把测试文件放在哪个路径——需要要么给 org-coder 约定一个固定的测试文件路径（比如统一要求 test/<task 相关名>.test.js），要么改用 benchmark 段（不依赖具体文件路径，走"维度+及格线"这套已经验证过的格式，org-validator 自己想办法判）。这个选择直接决定 org-coder 的 tools.md 要不要跟着补一条"测试文件固定放哪"的约定——如果选 benchmark 段，org-coder 也可以维持"不改一行"。建议选 benchmark 段，避免牵连 org-coder，但最终定案留到真正实现这一步时再拍板。

按建议定案：选 benchmark 段，org-coder 全程未改一行（见「实现记录」）。


明确不做（本轮范围外）

task-planning、org-planner 的 acceptance_item 物化、人类/CEO 快速派单三条创建路径的契约强制——留到以后单独讨论，不在这次改动里。
"发现者就地补一份"的运行时兜底代码——只记原则，decomposed_work 链路走主力机制已完全覆盖，不为不可达的场景写代码。
不改 org-coder/org-validator/goal-benchmark 等既有 agent 的提示词（除非"待定"那条最终选了 test_script 段，才需要给 org-coder 补一条测试文件路径约定）。

验收标准（后续实现完要检查的）

createTask 不给 acceptance_contract 直接创建 decomposed_work 子任务——应该被拒绝（如果按主力机制彻底做，decomposed_work 这个类型应该强制要求这个字段非空）。
真实回归：重复 46 号文档 Phase 3 v2 那次卡死的场景（单位换算任务的轻量图），这次 org-validator 应该能读到 artifacts/acceptance.json、真正跑一次 goal-contract.js validate + run，不再是 input_underspecified。
确认 org-coder/org-validator 全程不需要感知这份契约是"这次由 subtask-planning 供的"还是"平时 org-planner 供的"——两条路径对它们完全透明。


实现记录（2026-09-02）
落地清单


文件
改动


server/services/work-graph-db.js
tasks 表加 acceptance_contract 列（批 7 迁移，ALTER TABLE ADD COLUMN）；createTask 新增 acceptanceContract 参数，subtaskKind==='decomposed_work' 时强制非空，套一层 {version, goal_id, benchmark: acceptanceContract} 走 goal-contract.validateContract 校验（不重写规则，见下方「与原设计的出入」）；acceptanceContract 收进 TASK_FROZEN_FIELDS（queued_at 非空后不许再改，同 budgetJson 待遇）；materializeDecomposedSubtasks 把 step.acceptance 原样递给 createTask，单步校验失败（try/catch）只跳过那一步、不作废整批，延续既有"宽松解析"哲学


system/agents/subtask-planning/agent.md
硬约束新增第 10 条：每个 step 必须带 acceptance（benchmark 段本身），不许从 why 机械转写；输出形状（约束 1）、字段数（约束 5）同步改；补一节说明"轻量派发链路上 acceptance 会被直接拿去判卷"


server/services/subtask-planning.js
normalizeSteps 原样透传 acceptance（不在这一层做形状校验，深层校验留给 createTask）；buildSubtaskPlanningPrompt 的交回格式示例、字段说明同步加 acceptance


server/routes/company.js（enqueueTaskRun）
isDecomposedSubtask 分支：writeTaskGoalArtifact 之后（goal-contract 靠 task-goal.json 推 {companyId,taskId}），把 taskRow.acceptance_contract 套一层 {benchmark: ...} 通过 goal-contract.writeContract 落进新 run 的 artifacts/acceptance.json；best-effort（写失败只 console.error，不阻塞入队——失败时行为退回改动前的 input_underspecified，不比原来更差）


server/services/goal-contract.js
未改一行——writeContract/validateContract/CONTRACT_VERSION/resolveRunDir 全部复用既有导出


测试
task-decomposition-dispatch.test.js 新增 8 个用例（createTask 四种校验分支、materializeDecomposedSubtasks 两种单步失败场景、路由层两个契约落盘/存量缺口场景）；task-decomposition-validator-gate.test.js 补 1 处 acceptanceContract（存量夹具需要跟着改）


与原设计的出入（重要，别照着「设计决策」一节里的形状抄）
设计决策里写的是"形状复用 goal-contract.js 的 {benchmark, test_data, test_script}"——这句话在写文档时想的是"契约的三段式 wrapper"。真实起 subtask-planning agent 验证后发现这是错的：agent.md 教的提示词是"acceptance 对齐 benchmark 段"，真实 LLM（不是注入桩）老老实实交回的是 benchmark 段内容本身（{dimensions:[...], overall_pass_threshold?}），不会自己再包一层 benchmark 键——这符合直觉：没有人会在被要求"对齐 X 的格式"时，自己又发明一层 {X: ...} 包装。

第一版实现是照着设计决策的字面意思写的（acceptanceContract 直接当三段式契约展开），过了单测（因为单测的假数据也是我自己按错误理解造的），但拿真实 agent 输出一测就在 validateContract 那步报错（unknown top-level field: dimensions）——这正是本轮反复强调"真实回归优于只信单测"的又一次验证。修法：acceptance_contract 列存 benchmark 段本身，createTask/enqueueTaskRun 校验/落盘时现套一层给 goal-contract.validateContract/writeContract 用。agent.md/buildSubtaskPlanningPrompt 的提示词从一开始写的就是裸段格式，不用改。
真实验证（不是只信单测）

单测：npx vitest run server/tests/unit，1198/1200 通过（2 个失败是与本次改动无关的既有失败：env-example-secrets.test.js/test-id-stability.test.js，均未涉及本次改动的文件）；ps aux | grep claude 确认零残留 CLI 子进程。
真实起 p2verify0902 公司里已雇佣的 subtask-planning agent（真实 Claude CLI 调用，不是注入桩），给一条真实 task（"实现摄氏度转华氏度的转换函数"），验证 agent 真的会按新 agent.md 交出 acceptance 字段——交了，且格式如上一节所述（暴露了设计文档与真实产出的形状分歧，已修正）。
用真实 LLM 那次调用的原始产出（未修改一个字）跑一遍完整链路：materializeDecomposedSubtasks → createTask（校验+落库）→ 模拟 enqueueTaskRun 的写入段 → goal-contract.readContract + validateContract，结果 {"ok":true,"errors":[]}——这就是"org-validator 不会再撞 input_underspecified"这件事的直接证据（验收标准 2 的核心机制）。

仍未做的（遗留，按「明确不做」的既有边界）

没有重跑一次完整的真实 org-coder → org-validator 轻量图（46 号文档 Phase 3 v2 撞见死锁的那条完整链路）。已验证的是"契约会被正确产出、正确落盘、goal-contract.validateContract 判为合法"——这是 org-validator 卡死的根因链条上唯一改动的环节，其余环节（org-coder/org-validator 怎么读契约、怎么判卷）本次未改一行，46 号文档 Phase 3 v2 的真实回归已经验证过 org-coder 这一段能正常工作。如果想要不留死角的确认，需要用户手动挑一个任务，让 CEO 心跳把新物化的 decomposed_work 子任务真派发一遍，全程跑完（含真实 org-coder/org-validator CLI 调用，成本较高，未在本轮自动跑）。
安全网（"发现缺失时就地补一份"）仍然只是原则，未写代码——decomposed_work 链路走主力机制已完全覆盖，原设计判断不变。
task-planning/org-planner 的 acceptance_item 物化/人类快速派单三条创建路径的契约强制——本轮范围外，未动。