-
planner 骨架（brd→prd→sdd→goal-benchmark→validator）复现：三个 planning 节点 声明了 produces 却没真落盘，executor 没抛异常就被引擎判 success；goal-benchmark 的入边 needs:[brd,prd,sdd] 只用来拼提示词里的 ⚠️ 提示，agent 视而不见照样产出 合法 acceptance。下游 validator 永远读不到三份文档，backward 重试撞循环硬顶后 只能人工兜底。 settleNode 判 success 之前新增两道闸门（均只对 agent_call 节点生效，subgraph/org 节点的契约由子 work run 自己的节点过闸）： - unsatisfiedRequiredProduces：声明的 required produces 一个候选文件都没落盘 → fail_reason=produces_missing，不再放行 - requiredInputsMissing：声明的 required needs 在 graph_files 里查不到实例 → fail_reason=missing_required_input，不采信 agent 自报的 success 两者都只判「有没有」，不判「分类对不对」——ambiguous 归类留给下游 ⚠️ 提示词处理， 避免把「写了东西但引擎猜不出对应哪个 kind」误判成没执行。 包含此前已完成但未提交的 27-P4 T3（graph_runs.max_concurrency 落库）及配套 advance-batch 测试。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
-
按任务表逐条 grep 代码，发现这份文档落后于实现相当多： · **T1 已完成**（P3C §15.5-2）：SessionPool.maxSessions + scope key，两条守卫盯着。 · **T3 后半已完成**（P3C 批 4）：单 active root run 的唯一索引已 DROP， 换成四步事务内准入（BEGIN IMMEDIATE → 重读 → 计数 → 条件更新），8 进程实测零超发。 · **阶段 C 整个已完成，但形态换了**：产物索引做成了 graph_files **表**而不是 files.json。 表比文件多拿到两样：部分唯一索引保证「同一路径只有一个当前版本」， superseded_by 让历史版本可共存。守卫 graph-files-index.test.js 七条。 · 产物也早就按 run/node 分目录了（runs/{rootRunId}/nodes/{nodeRunId}/）， §3.6 里「按 agent 分目录、同一 agent 不同任务混在一起」那条已不成立。 §3.6 那两个 ❌ 改成校准块 —— 保留原文（它记录了当时的判断依据）， 但当前状态以校准块为准。 **真正剩下的只有阶段 B**：max_concurrency 列、advanceBatch、三层额度取小、 并行执行与部分失败降级，以及 T10 的控制台可视化。 > 这是「文档落后于代码」的又一例。判断一个阶段还剩多少工作量时， > **先照着任务表逐条 grep 代码**，别照文档估 —— 照文档估会把已完成的三项当成待办。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
-
设计见 docs/done/system-design/28-agent-registry-unification.md。 改造前 Agent 本体散在三处（system/agents/ 11 个、system/templates/ 50 个、 data/companies/{id}/agents/ 17 个），同一个 AgentScaffold 被三个 baseDir 实例化。 后果是同一角色在 N 家公司下有 N 份互不相干的副本，模板更新不会同步； org-coder / org-planner 这类走 hireFromBaseMetaAgent 造出来的本体 legacy_path 指回自己公司目录，永远无法被第二家公司复用。 本次： - G1 单一注册表：system/templates/ 整体并入 system/agents/，base → _base。 7 个同名 id 逐个裁决，被丢弃的一份归档到 docs/_archive/ 而非删除。 source_kind(template/global_agent/company_hired) → origin(builtin/created)。 - G2 运行态下沉：CLI 的 cwd 从本体根改为 system/agents/{aid}/{cid}/{taskId}/。 memory / conversations 落公司态 {aid}/{cid}/，按公司隔离不串。 sessionPool 的 key 含 (companyId, taskId)，两家公司调同一 agent 不复用会话。 - G2b 产物不下沉：交付物仍落 data/companies/{cid}/，system/agents/ 只留运行痕迹。 写入边界按链路分叉——graph 节点走节点私有目录（被 indexNodeOutputs 索引）， chat 走公司 workspace，同一提示词里不再出现两条互斥指令。 - G3 公司只存引用：data/companies/{id}/agents/ 删除，新增 company_agents 关联表。 不复用 org_graph_nodes——后者是执行流图，work 层本体被雇时不写它，天生覆盖不全。 - G4 缺则创建：本体缺失时从 _base 复制骨架进 system/agents/{id}/， agent-creator 填 agent.md/soul.md 后才从 draft 转 active（哨兵判据， 骨架未填时哨兵仍在，不许被 hire）。产物即刻是全系统可复用的本体。 新增 server/services/agent-locator.js 收编原先散在 6 处的寻址逻辑。 边界守卫（graph-engine）的豁免从「本体根上五个文件名」放宽为整棵 system/agents/： 新本体的骨架本来就要进 git，gitignore 挡不住 ?? system/agents/{newId}/， 旧判据会把一个真正成功的招聘节点判成 boundary_escape fail。 存量迁移见 scripts/migrate-agent-registry.js（幂等，备份到 data/_migration-backup-*）。 真 Claude CLI E2E 已验证：新建公司 → orggraph-planning 自动规划 → 自动招聘 org-planner/org-coder/org-validator 三节点流水线； data/companies/{cid}/agents/ 不存在，company_agents 4 行， system_agents 56→56（零新建私有本体，纯复用），git status 零增量。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
-
第六次真 CLI 冒烟 gapClosed=true：org 层契约落库 4 行（此前恒 0）， 且那段文字真的进了 workgraph-planning 收到的提示词（52677 字节，第 746 行起）。 ## workflow 四路并行的产出 - **org 层两半一起接**（关键顺序）：先接读回方 buildPlanningPrompt 的 ③bis 段 （org 边入边 → 上游绝对路径；出边 produces → 「你规划的子图必须有节点产出这些」）， 再接声明方 orggraph-planning 模板。只补模板的话就是又一次「声明了没人读」—— org 图节点全是 subgraph，而 describeInputs 对 subgraph 直接返回空。 resolveInboundLines 从 describeInputs 抽出共用，两侧口径物理上不可能漂移。 - **清掉 404 死路径**：模板三处教的 POST /api/company/:id/work-graphs 从未注册。 真跑复验：agent 侧零调用，改为按新 Step 7 写项目根绝对路径，还自己 require validateWorkGraph 预检了一遍才交回，round=1 一次过。 - **四张骨架补 produces/needs**：从「靠模板文字施压」变成结构保证，每张过规则 6。 真跑里 agent 照抄了 planner.json 并跟着任务删掉 sdd 节点——是改编不是复制。 - **graph-seed 顺序依赖**：靠生产代码里已有的 GRAPH_SEED_ROOT 缝隙指向冻结快照。 不是「跑几次都绿」结案：构造了原先必红的 churn，修前 12 次 3 红、修后 15 次 0 红。 ## 我自己收的 4 条 major + 1 条 minor（都在 graph-engine.js） 复验挖出「引擎自己拼的提示词在教 agent 做模板明令禁止的事」，同一条提示词里对立： 1. 「已自行落库成功时回一行 workGraphId: wg_xxx」vs 模板「你永远拿不到真的 wg_ id， 永远别写」。agent 没有任何受支持的落库途径，写出来必是编的，而 extractPlannedGraph 优先匹配那个形状、查库查不到就整轮作废。删掉邀请，保留引擎解析真实 wg_ 的能力。 2. 内联图示例的边一个 produces 都没有——agent 唯一见过的「边长什么样」是零声明的。 3. 「端点尚未上线」暗示将来会上线，于是它还想去试一次。改成「不存在、也不会上线」。 4. indexNodeOutputs 收集 declared 不按 role 过滤，把出边的 needs 当成本节点的产出。 Chrome 走查实测：产品需求文档.md 落成 artifact，下游 prd 输入变 ⚠️。 更坏的一面是错标（brd_notes.md 命中中继 needs[brd] → 归因给错的产出方）。 1ea9efa 加的 role 列，这里正是它存在的理由。 5. (minor) contract.prev.json（retryNode 的契约快照）被索引成 artifact 噪声。 新增 guard：引擎提示词不许与模板对立（静态读源码，剔掉注释行—— 第一版把「解释为什么不许说某句话」的注释也扫进去了，量错了对象）。 测试 850 全绿（83 文件），既有断言未改。5 处变异精确变红后逐字还原。 Chrome 走查确认控制台正常分支（此前只验过降级分支）：契约药丸、绝对路径、 needs 中继说明、tab 上的 ⚠️ 计数全部渲染，零 console 报错。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
-
第五次真 CLI 冒烟（gapClosed=true）暴露的两条，都是「这轮成立是侥幸」型。 1) indexNodeOutputs 靠文件名定 kind 真跑成立纯属 brd 节点恰好把文件命名成 `brd.md`。换写 `业务需求文档.md` 就落成 kind=artifact → 下游入边声明的 brd 查不到实例 → 提示词退化成 「⚠️ 索引里查不到实例」，即刚关掉的断点换个形式重现。agent 给产物起中文名 是完全正常的行为，不该由它决定索引对不对。 改成两遍：先按文件名认领，再在**一对一无歧义**时（还差一个 kind 没人产、 正好还剩一个认不出的文件）按声明认领。有歧义不猜 —— 猜错比留 artifact 更坏， 错的 kind 让下游读到一份不是它要的文件，artifact 只是查不到、会如实报 ⚠️。 2) describeInputs 任务级共享不去重 真跑里 brd 与 prd 两个节点各写了一份 contract.json，都是 kind=contract， 于是往后每个节点的提示词里「contract（任务级共享）」逐个累加。节点一多是噪声， 且给 agent 两个同类路径等于把一个我们自己都没定的选择推给它。 按 kind 保留最新那份，与沿边那一半的 byKind.set 同口径。 ponytail 标了根因（节点私有目录的文件也会按文件名落成 task-shared 的 kind） 与真正的修法（任务级产物只认 tasks/{taskId}/），后者要动 R-9.3 现有语义， 归到那条线一起定。 测试 829 全绿（+3），既有断言未改。4 处变异精确变红后逐字还原。 含 verify agent 回填的 §4.6「第五次真 CLI 冒烟」小节。 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> -
第四次真跑的断点：org-planner-prd 失败，它自己的归因原话是 「不是上游没产出，是它的产出**结构上到不了我手上**」。核实属实 —— 上游 brd.md / contract.json 落在**节点私有目录**，prd 的提示词只有它自己的私有目录 + 只读 artifacts/，而 brd--success-->prd 这条边**不携带任何文件引用**。 边一直只承载控制流（condition/edge_kind/fail_reason），R-4 要的「边的输入输出」 被落成了从 output_ref **推断**的 UI 展示、没有实体，而推断的那一端下游读不到。 ## 定案（27-REQ R-19） - 建 sqlite 表而不是 files.json：JSON 会重演 _registry.json 的并发重写与 git 冲突 （本轮刚被它咬过，W13 只能把 usedCount 挪去另一个被 ignore 的文件） - **两类数据流都要**：纯边绑定表达不了 R-9.3 的「planner 生成、validator 执行」—— org graph 是 planner→coder→validator，acceptance 跳过 coder，这两点之间没有边 - workspace 根**代码推导不入库**：存绝对路径会烂，W13 清的那 10 条 legacy_path 悬空行就是这个病。表里只存相对公司根的路径 - 路径走 tasks/{taskId}/，不走 workspace/：后者语义是「Agent 自治领地、框架不干预」 （06-沙盒自治），与「框架管着、可检索的交付物区」是两种所有权 - 契约(kind)与实例(path)分规划时/运行时两阶段 → 引擎可在节点跑之前校验 「你声明要吃 brd，但上游没人产 brd」，这类图结构错误此前只能等跑到那步才发现 ## 实现 work-graph-db：graph_files（实例）+ graph_edge_contracts（契约）两张表。 graph_files 的当前版本走**部分唯一索引** WHERE superseded_by IS NULL —— 与 idx_org_graph_nodes_company_role_active 同一模式：要「同键只有一个活的」 又要留历史，条件得写进索引而不是靠删行。API：recordFile / findFiles / declareEdgeContract / edgeContracts / inboundContracts / rebuildFilesFromNodes。 graph-engine 两侧都接： - 输入侧 describeInputs：按**入边声明的 kind** + **本 task 共享产物** 查实例， 把绝对路径拼进提示词。声明了却查不到的**明说缺哪个 kind**，不静默省略。 刻意不是「注入一句『索引在某文件，自己去检索』」—— 那仍靠 agent 自觉拼路径， 真跑已证明它拼不出来；引擎直接递到手上，不给它猜的机会 - 产出侧 indexNodeOutputs：节点 success 时登记落盘文件，kind 先看出边声明、 再按文件名兜底；attempt-*.json 是引擎自读的归因文件，不当产物登记 文档：27-REQ 新增 R-19（四条，含两段原话）；27-P4 §4.6 按定案重写 （原「公司根一个 files.json」作废）。 测试 788/788 全绿。后续（下一轮）：规划侧声明契约、goal-contract 路径归并、 前端「输入输出」tab 展示解析结果、真 CLI 复验 prd 能拿到输入。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
-
■ 关于编号 原「P4 回退 + Loop-Validator」已并入 P3 实现完毕（c3abf4a：双层熔断、五项结构 校验含 fail-fallback-edge、三层暂停级联、contract_hash 重试判据）。本文档回收 这个空出来的编号，装 P3 明确排除、现在成为最大能力缺口的内容。 ■ 核心：fan-out 并行 P3 把图结构和 join 语义都做好了，唯独没做并行本身： - graph-engine.js:1078 出边评估「所有入边满足才置 ready」——fan-in join 正确 - graph-engine.js:908 拾取 SQL 是 LIMIT 1——三个并行分支只会一个个串行跑掉 设计为 advanceBatch(runId, {maxConcurrency})，不新增第二个推进原语： 手动模式 maxConcurrency=1 时行为与今天的 advanceOne 完全一致，P3 已有调用方 和测试不用改；自动模式一次拾取整批。批量拾取必须在一个事务里一次性置 running， 否则两个并发 advanceBatch 会拾取到重叠集合。 ■ 走查发现的关键事实：隔离挂载点已经存在 session-pool.js:29 的 getKey(agentName, agentConfig, workDir, scope) 签名里 早就预留了 scope 参数，但第 45 行实际调用时没传。所以「同一 agent 多实例隔离」 这个并行前置条件的改动量比预想小得多——用 graph_run_nodes.id 作 scope 即可。 连带要放宽 CONVENTIONS §12 第一条不变量：(pid, agent) → (pid, agent, scope)。 这是 P4 里唯一要动 DevLoop 规格的地方，且 _spec/ 是生成物，必须改 HTML 后跑 npm run spec:extract。该放宽同时是 P6 的前置——DevLoop runProject 波内串行 （loop-controller.js:609 注释「串行跑」）正是被同一条不变量挡住的。 ■ 产物统一目录 + files.json 这是此前提出但一直未实现的需求。按 task 分目录 data/companies/{cid}/tasks/{taskId}/，根目录 files.json 作统一检索索引， 由引擎在产物落盘后自动追加（不靠 agent 自觉写，否则索引必然漂移）， 并支持从 graph_run_nodes 行 rebuild。与 output_ref 不重复：后者是节点级指针， 前者是公司级聚合视图，由前者派生。 ■ 三个阶段，C 完全独立 A 隔离(T1-T2) → B 并行(T3-T6,T10)；C 产物索引(T7-T9) 与 A/B 无依赖，可最先做。 并发上限对齐 plan-cost-concurrency.md §④ 的既有数字（run≤5 / 公司≤3 / 单机≤20 session），不另立一套。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>