宜博 / lemonboss

29-DREAM §四 的五步里先落两步。

## 步骤 4：本体定义文件的 git 历史闸门（决策 B.3）

用户定案：soul.md / agent.md **直接落盘**，但写之前必须确认这份文件已经在
git 历史里 —— 别导致直接修改而没有历史。

definition-write-gate.js 两条判据都满足才放行：
① 文件被 git 跟踪；② 该文件没有未提交改动。
判不出来（不在仓库 / git 不可用）一律拒绝 —— fail-closed。

**为什么是「拒绝并报告」而不是「脏就先替它提交一把」**：后者看着更顺手，
但那正是本仓库记过的一类事故 —— 多会话共用同一个 worktree（27-P3C §15.4）。
一份未提交的改动很可能是**另一个会话正在写的东西**，替它提交等于把别人的
半成品写进 main 且署错名。把「要不要提交」留给人。

守卫 5 例，含「拒绝时必须给出下一步」那条 —— 撞上闸门的人（或 agent）
要能照着做，否则只能猜。

## 步骤 1：memory.md 的自动写入不再冒充「关键事实」

原实现取任务与结果的第一行、砍到 80/100 字符，写进 `## 关键事实`。
那不是提炼，是搬运 + 截断。实测产物（cto/_global/memory/memory.md）：

    - [2026-08-20] [SYSTEM HEARTBEAT] → 🔧 [TOOL_CALL] Bash (ID: toolu_01RsQ3gh...)

**工具调用 id 被当成了「关键事实」**，而 memory.md 会被注入每一轮提示词。
28 §5.6b 点名的错误版本是「自动把原文写进共享 SKILL.md」——
这套已经是那个错误的单公司版，只是还没跨公司共享所以还没造成泄漏。

改法：
· 换段 —— 自动写入落到「原始记录（未提炼）」，`## 关键事实` 只由提炼产物填。
  读的人和 agent 一眼分得清「日志」和「结论」；这一段同时是 dream 的输入面。
· 滤掉确定的噪声（工具调用标记 / 空结果 / 只有心跳标记的任务），
  但**不猜「哪条重要」**——猜重要性需要理解内容，那是 dream 的活，
  在这里做等于把提炼下放到一个正则里。
· 不再截成半句：上限放宽到 200 并取完整第一行。截断残渣读起来像事实、
  其实缺主语，比不留更坏。

⚠️ 踩到一条：噪声判据初版有「任务与结果都短于 8 个字符就丢」。那是按英文长度
想出来的阈值 —— 中文 8 个字是一句完整的话，实测「结果甲甲甲甲甲」（7 字）
整条被丢。已删该规则。**凡是拿长度当信息量代理的判据，先问一句这是按哪种文字算的。**

全量：143 文件 / 1310 测试全绿。

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

28-followups §1.1 一直是「方向已定、设计未定」。这份把取舍摆出来并记下拍板结果。

## 先看清原料：它现在是脏的（全部实查，不是推测）

· **写进 memory 的不是「事实」，是截断的日志行**。appendToMemoryMd 的全部逻辑是
  「取第一行、砍到 80/100 字符」。cto/_global 的实际内容里，三条「关键事实」是
  `🔧 [TOOL_CALL] Bash (ID: toolu_01RsQ...)` —— 工具调用 id。
  §5.6b 点名的错误版本是「自动把原文写进共享 SKILL.md」；**现在这套已经是那个错误的
  单公司版**，只是还没跨公司共享，所以还没造成泄漏。
· 长期记忆是一个 3000 字符的滚动窗口，没有按重要性保留的机制。
· 96 个「公司态目录」里混着 train/ workspace/ 和**带时间戳的测试残留**
  （tmp-w7-*-1786986291739-*、qroute-co-13/14）。dream 第一步「枚举所有公司」
  现在没有可靠答案 —— 可靠的答案在 company_agents 表里，目录只能用来定位文件。
· 75 份 memory.md 里只有 7 份有非模板内容。**dream 现在几乎没有原料。**

## 四条拍板（2026-08-20）

A 去敏 = 独立判定 agent + 写作要求。失效方向是「少沉淀」不是「泄漏」——
  两种错代价不对称时判据偏向贵的那侧，与 P3B §八 FAILING_VERDICTS 同一条经验。
B 落点 = memory/ 与 SKILL.md 都写，**必要时迭代 soul.md / agent.md**。
C 触发 = 定时每日一次。
D 顺序 = 上游修复与 dream 一起做。

## B 把范围扩大了，随之而来的约束单列一节

「本体只有一份」意味着写 agent.md / soul.md 影响**所有雇了它的公司**，
而不是提炼出这条经验的那一家。所以四个落点按可逆性分层，并记了四条硬约束：
· agent.md 有一处 2000 字符截断 —— **作用点要说准**：那是给规划 agent 看的
  「角色定义摘录」（graph-engine.js:915），agent 自己那条装配链不截断。
  判据因此是「保证前 2000 字符仍然自足」，不是「不许追加」。
  （初稿我按记忆写成「装配时只读前 2000 字」，查了代码才改对。）
· 这四个里三个是 git 跟踪的**定义**，不是运行态 —— dream 改它们会进 git status。
· 毕业闸门读这些文件，写坏会让本体雇不进任何公司。
· 必须能分别回滚：经验写坏只影响上下文，agent.md 写坏影响所有公司。

## 还没定的

决策 D（提炼质量怎么评）；B.2 里「定义文件直接写还是走提案」——
我建议走提案并写进了推进步骤，但那是建议不是拍板。

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

## 病症（真跑实测）

2026-08-20 那条 run 的 timeline 里，**每个节点**的产物索引写入都失败：

    node.output | 产物索引写入失败 contract.json: UNIQUE constraint failed: index 'idx_graph_files_path'
    node.output | 产物索引写入失败 sdd.md:       UNIQUE constraint failed: index 'idx_graph_files_path'

19 次 agent 调用、每次两三个文件，无一成功。

## 根因：加了新索引、没删旧索引

产物索引加「版本」之前，唯一索引是无条件的
`UNIQUE(company_id, COALESCE(task_id,''), rel_path)`。加版本之后建表块换成了
带谓词的 idx_graph_files_current（WHERE superseded_by IS NULL），**但没人删旧的那条** ——
`CREATE ... IF NOT EXISTS` 只管不重复建，不会删已有的。

于是 recordFile 那套「先把旧行 superseded_by 指向新行、再插新行」的版本化写法
在存量库上整个失效：旧索引不认 superseded_by，同路径第二行直接撞。
而重试恰恰会让同一条 rel_path 被产出第二次。

## 失效方向：静默

writeFileIndex 把 recordFile 的抛降级成一条 timeline，**节点照样 success**。
后果是产物索引在任何有重试的 run 上都不全 —— 而下游节点正是靠这份索引
按 kind 找上游产物。不报错、不影响测试、git status 干净。

## 为什么没有任何测试照到

新建库压根没有那条索引（建表块里早就只剩 current 那条），**只有存量库会踩**。

这是同一类问题的**第三次**（tasks 加列的索引顺序、墙钟锚点迁移、这次）。
判据固定成一句话：**凡是碰 schema，「存量库重启」那条路必须单独走一遍。**

## 修 + 验

迁移里一句 DROP INDEX IF EXISTS idx_graph_files_path。
守卫 graph-files-stale-index.test.js 走存量库重启那条路，并验版本化语义没被削弱
（同路径两行、当前版本恰好一条、旧行指向新行）。反向验过：不删就红。

生产库已实跑验证：删索引后同路径连产两次不再抛，graph_files 24 行未受影响
（备份 /tmp/graph.sqlite.pre-idxdrop）。

全量：141 文件 / 1300 测试全绿。

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

28-followups §3.1。**审计结论与那条待办原来的写法不一样，两列要分开处理。**

## source_kind：删

与 origin 一一映射（global_agent↔builtin / company_hired↔created），
实查生产库 76 行零例外。全仓唯一读侧是 migrate() 里那条 origin 回填，
而那是给「origin 列出现之前写下的行」用的一次性迁移。

顺序：**先回填、再删列**，两步都用 hasColumn 守着（幂等）。反过来做不报错 ——
库能开、测试能过，只是那几行 origin 悄悄是错的。守卫
source-kind-drop-migration.test.js 走存量库重启那条路，专门钉这个顺序，
反向验过：弄反立刻红。

写侧散在 3 处生产 INSERT + 35 个测试文件。批量改的时候正则误伤了 4 处
（吃掉了 JS 默认参数、位置占位符、ON CONFLICT 的赋值行），逐个修回并复查了 diff ——
**这种跨几十个文件的机械改动，靠「全量跑一遍」兜底比靠正则写得对更可靠**。

## legacy_path：不能删，它还没死

原待办说「所有读取点都已改成从 id 推导」——那半句对新行成立，对存量行不成立：
· 新行 legacy_path 恒等于 system/agents/{id}（确实冗余）；
· **存量行里存着批次 4 之前的公司侧路径**，而 graph-seed-service 判「悬空行 / 孤儿行」
  靠的正是这个路径指向的目录还在不在。从 id 推导出来的路径永远指向 system/agents/，
  那条判据会整个失效。

实查生产库：76 行里还有 2 行是老路径（org-planner / org-coder 指着已不存在的
data/companies/mycompany/agents/）—— 正是这条判据要认出来的那种行。

退出条件写进了 graph-db.js 的建表注释（不只留在文档里）：
库里不再有 legacy_path <> 'system/agents/' || id 的行。

## 顺带记一条：getDb() 会就地迁移生产库

删列那次，生产库的列是被一条**查状态用的**一行 node -e 删掉的 ——
服务当时没重启，人也没打算迁移。结果是对的（幂等；与备份逐行核对 76 行一致、
origin 全部按映射回填正确），但「读一下状态」不该顺手改 schema 这件事值得知道。
闸门只挡测试进程，故意不挡普通脚本（挡了服务自己也起不来）。
注释里给了只读的正确姿势。

全量：140 文件 / 1299 测试全绿。

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

## 验收 4：从「静态成立」变成真的跑过一次

原状态是 🟡「静态成立，未真跑」—— 人读代码把
fixture verdict → FAILING_VERDICTS → readNodeProduct → callAgentNode 判 fail
这条链读通了，但没有任何一次真跑或真链路证据。

现在 graph-real-chain-smoke ⑥ 走完整条：fixture 产出 verdict="attributed"
→ 节点 fail、fail_reason=input_underspecified、沿 fail 边点亮下游、
判词落在**下游节点**行上（判词的载体是「点亮它的那次状态转换」，不是失败节点自己）。
反向验过：verdict 改成 passed 立刻红。

写 fixture 时踩到一条值得记的：fail_reason 是封闭域 ATTRIBUTION_REASONS，
第一版编了个 contract_invalid，被**按设计降级成 null** 并留一条 timeline ——
引擎不认识的归因一律不信。判据没错，是 fixture 错。

## 验收 2 / 8：由 2026-08-20 那次真跑验掉（§六ter）

· 2 —— 19 次真 agent 调用之后 `git status --porcelain` 完全为空，交付物都在项目根内。
  这正是 §六bis「后半被并行 agent 打破」那条的干净环境重验。
· 8 —— 判据取「它引用了只可能来自提示词的内部 id」：triager 判词原文写着
  「org-coder-impl 私有目录 rn_96a8cd696dcc 下只有 _research.md」，
  rn_96a8cd696dcc 是 graph_run_nodes.id，agent 没有别的途径知道它。

## 验收 9：产出端通了，消费端没等到那个形状

真跑里 triager **确实产出了两半地址**（orgNode + workNode）——
这一条本身有分量：27-P3/P4 §八.22 第 13 处记的正是「引擎四环全通，
但产出方 agent.md 里根本没有这个键」，那半条现在通了。

紧接着「忽略跨层地址」那条**不是缺陷，是判据在正常工作**：这次回退发生在
work 层内部，edge.to 本身就是 agent_call 节点，已是最细粒度，没有跨层可言。
缺的是**那个形状**：一次 org 层回退边、且目标是 subgraph 节点。

别把「机制没验」和「机制没有」混为一谈 —— 定点重置的逻辑侧有
graph-cross-layer-address.test.js 三例注入式覆盖，缺的只是真跑里发生过一次。

## 顺带

· template-verdicts 的样本非空那条补 ENOENT 容忍。它扫**活目录**，
  而 graph-real-chain-smoke 会在 system/agents/{aid}/{cid}/ 下建了又清运行态 ——
  文件在「列出名字」和「读它」之间消失是正常的。walk() 与 violations() 早就容忍了，
  只有这一处漏了，实测偶发红过一次。**扫活目录的守卫，每一处读都要容忍 ENOENT。**
· 真跑 timeline 里发现一条未修的：每个节点的产物索引写入都撞
  UNIQUE idx_graph_files_path 失败并被降级成日志（重试时同路径再写一次）。
  后果是 files.json 产物索引在有重试的 run 上静默不全 —— 归 P4 一起处理，记在 §六ter。

全量：139 文件 / 1297 测试全绿。

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

agent_call 与 subgraph 是**两段不同的默认实现**（defaultAgentExecutor /
defaultPlanWorkGraph），各有各的 onAcpEvent 累加、各有各的守卫开关分支。
上一轮只覆盖了前者，「规划子图」那半条链仍然是零真实覆盖。

现在走完：defaultPlanWorkGraph → AgentManager → ClaudeCliProtocol(mock)
→ extractPlannedGraph 解析回复 → createWorkGraphSafely → 建子 run。

断言两处假 planner 天然绕开的接线：
· 子 run 的定义确实来自 fixture 那张图（节点名 / systemAgentId 逐个对）
· 规划那一轮烧的 token 也进了预算 —— 走的是 defaultPlanWorkGraph 自己那条
  onAcpEvent，与 agent_call 那条不是同一段代码
③ 的守卫断言补上 subgraph 分支的正反对照。

新增 fixture workgraph-planning.json：图 JSON 同时放进 chunks 与 result
（mock 下 output 取哪一半由 AgentManager 决定，不该由 fixture 来赌）。

反向验过：抽掉 fixture 里的图 JSON、或把它的 usage 归零，对应用例分别变红。

**覆盖边界写在用例注释里**：跳过 resolvePlanningAgentName 里的按需 hire
（预塞一行 company_agents）—— hire 要一条真实公司记录，那条路径另有
company-hire-org-layer.test.js 盯着；这条 smoke 验的是规划链路，不是招聘。

全量：139 文件 / 1296 测试全绿。

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

## 一、W7「零边图」不是待办 —— 它早修了，是注释在骗人

`company-service.js` 的判据注释仍写着「判据用**有没有边**」，并留着一段
「已知残留：单 org node 的最小图没有边，判据③不生效……真跑到那一步再看」。

**那个残留在 `58a2865`（08-17）就修掉了**：`orgGraphMembership` 现在的主判据是
`authored_by='planner'` 的节点存在（「orggraph-planning 提交过一张图」的直接证据，
零边也认），边数降为存量行的回落判据；守卫 `company-hire-org-layer.test.js` 的
`CO_ZEROEDGE` + `W7-fix` 两条盯着。

注释没跟着改，于是它把读的人**引向一个已经修好的缺陷**去重修一遍 —— 我就是这么被
带偏的：读到那段注释就没再往 `orgGraphMembership` 里跟，还据此往待办清单里写了一条。
这是「指路牌失效」那一族，和 CLAUDE.md 死链同型，只是方向相反（那边指向不存在的东西，
这边描述已不存在的洞）。

判据的措辞也改了：**「成型」的判据在 graph-service.orgGraphMembership()，不在这里**，
免得下一个人照注释理解。P3B 文档与 docs/README.md 的对应条目一并更正。

## 二、还上「真实路径 smoke 进 CI」那笔欠账的一半（27-P3/P4 §十 硬规矩 2）

原话是「凡是靠注入点验的能力，都要有一条真实路径的 smoke 进 CI 才算验收完成 ——
这条欠账仍未还」。此前唯一走真实路径的 `scripts/real-pm-smoke.js` 要真 API 额度、
人工跑、而且验的是 DevLoop 不是图执行。

做法是把「真 LLM」和「真代码路径」拆开：**只把最外层的 CLI 子进程换成 fixture 回放**，
setAgentExecutor / setPlanWorkGraph 一个都不调。链路完整走
advanceOne → defaultAgentExecutor → AgentManager → ClaudeCliProtocol
→ onAcpEvent → 落盘 → readNodeProduct → settleNode → spendBudget → 边界守卫。

三条断言各盯一处**假 executor 天然绕开**的接线：
· ① mock/files 真的落到节点产物目录（假 executor 直接 return，这一环整个不存在）
· ② token 用量真的从 session/result.usage 数进预算 —— **就是 §六 验收 10 卡了两轮的那一维**
· ③ boundaryGuardApplicable 在这条路径上为真（注入假 executor 时它恒为假，
     那条唯一有实际后果的分支实际零覆盖）；带反向对照，注入后必须变假

反向验过：断掉①的落盘、断掉②的累加，对应用例分别变红。

为此改了一处 mock：session/result 的 usage 原来硬编码 {input:0,output:0}，
现在 fixture 可指定（缺省仍是 0，既有 fixture 行为一个字不变）。
**不改这一处，token 那一维在 CI 里永远产不出数** —— 验收 10 当初就是卡在这儿。

**没还清的部分写在文档里，别当成还清了**：真 LLM 仍进不了 CI；
subgraph 那一支（defaultPlanWorkGraph）仍只有注入式覆盖；
多节点 / 回退边 / 熔断没进这条 smoke，它只推一个节点。

afterAll 清掉真实链路建出的公司态目录（gitignore 挡着不进库，但留着会让别的
用例遍历 system/agents/ 时多扫一份）。

全量：139 文件 / 1295 测试全绿。

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

## 移进 done/

· 27-p3c-goal-task-model.md —— 五批实施完毕，§15.5 / §16.8 的后续项也全部收掉。
  新增 **§十七**：欠账清单对账、边界守卫从「乱扣帽子」改成「留证据不判罚」、
  测试污染生产图库（第四次踩同一族，但换了个方向进来）、那条卡了两天的 run，
  以及 **§17.5 真跑验收** —— org-planner-sdd/benchmark/validator 全 success、
  work run completed、父节点自动拉回、org-coder 起实现层子图、
  org-coder-validator 判 fail 走回退边打回 impl（loopCount 1）。
  **返工闭环第一次由真 agent（不是注入的假 executor）走通。**

· 27-p3c-batch3-handover.md —— 四条复核结论全修完、§五 那条 run 已解开，
  §七 待办全部打勾。从待办转为**事故记录归档**：§六 那几条多会话协作规则是真踩出来的。

两份的相对链接都已重指（done/ ↔ todo/ 跨目录），no-dead-path-references 守卫通过。

## 留在 todo/ 的，状态说清楚

· 27-graph-agent-architecture.md —— 状态行校准。那一行是别人判断「能不能搬 done」的依据。
· 27-p3b-real-run-runway.md —— 加状态行：验收 7 ⛔ 真跑不成立（readme-writer 混进
  org graph，**未修**）、2/4/8/9 未在干净环境验。缺陷② 的**根因**今天修了，
  但特意写明「**根因修了不等于验收点验了**」—— 不然下一个人会照着状态行当成验过。
· 27-p3-p4-work-graph-console.md —— 在索引里写明留 todo 的原因：
  §十 那笔「真实路径 smoke 进 CI」的欠账未还。
· 28-followups.md —— §3.3 标已修（含「GET /info 的 404 闸门仍没修，别当成修过」）；
  §五 守卫表加两行（graph-db-prod-guard / heartbeat-company-scoped），
  并补第七条的来历。

## docs/README.md

索引补上新增的 done 条目与 P3B / 28-followups 行，主线说明改成
「当前未完成的是哪几件」——原来只说完成了什么，读的人得自己推。

全量：138 文件 / 1292 测试全绿。

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

记三件这一批换来的东西：

§16.5 第 3 步怎么做到不碰契约：dispatch 的九步副作用里只有第 ⑧ 步是存储，
把 saveTaskMeta/loadTaskMeta 变成表的适配器、其余八步一行不动，URL 与请求体
形态天然不可能变。字段落点的三个判断也记了（objectiveId 可推导所以不存、
sourceConvId 零读取方所以删、没选 JSON blob 因为 R-19.2 否过那个形态）。

§16.6 删掉的是「猜」不是「记录」：122 行的三策略启发式换成 parent_task_id
显式记录；getTaskTimeline 保留，树从表来、正文仍读 agent 的一手会话记录。

§16.7 两次「测试全绿 ≠ 没坏」：routes/tasks.js 漏改（没有测试走那条路）、
控制台栏宽（构建/单测/探针都不会报）。与 §16.2 那个「存量库一启动就炸」
（测试能覆盖但没人写）合起来是一条经验 —— 新建库的路径、纯逻辑的路径由单测
天然覆盖；「存量数据」「真实接口」「肉眼可见」这三类必须另外安排人走一遍。

§16.8 留了三条：tasklog 目录改名待做、tools-base.md 的端口仍是 3000（实际
3010，已真咬过人）、TaskTimeline.vue 的两处字段语义变了。

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

记两条这一批换来的东西：

1. 加列时把 CREATE INDEX 写进建表块，会让**所有存量库一启动就炸** ——
   建表块先于迁移块执行，存量库上 CREATE TABLE IF NOT EXISTS 是 no-op，
   索引引用的那一列还不存在。而新建库（单测默认路径）完全正常。
   由此得到一条可复用的规矩：凡是加列，必须同时测「存量库重启」那条路 ——
   新建库的路径由每个单测天然覆盖，存量库那条没人走，而生产上只有存量库。

2. 回填沿用原 taskId 而不是新发：conversations/task-{taskId} 是目录名、
   汇报链路按它查找、summary 里互相引用。换 id 等于把引用全断掉，
   而回填的目的恰恰是别让历史消失。

并记下第 3 步动手前的前提：/task/dispatch 的 URL 与请求体印在
tools-base.md 里（所有 agent 的工具说明），一个字不能改；而 agent-chat.js
在 8-19 被另一个会话大改过，预研写在那之前，所以要重新读现状再动手。

顺带记一处过期且已咬过人的：tools-base.md 印的是 localhost:3000，
实际端口是 3010 —— 回填出来的派单正文里有人手写「端口 3010，不是 3000」
在纠正它。

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

## 批 4：解除「一家公司同时只有一个 active root run」
- DROP idx_graph_runs_one_active_root（建表块删掉 + 迁移块显式 DROP，
  CREATE ... IF NOT EXISTS 对存量库不生效）
- max_parallel_tasks 从 company.json 调用时读（不是模块加载时快照，
  否则改配置要重启才生效且不报错）；缺省 1、非法回落 1 并留声、硬上限 20
- 准入判据「从活跃集外进入活跃集」按额度计数

**生死线用 8 个真进程并发抢坑实测**（不是纸面论证）：max=1/2/3/5 四组，
每组恰好抢到 max 个、库里活跃数 = max，落选进程各吃 40 次 RunSlotBusyError，
零 other 错误。唯一索引没了之后，准入事务是真守卫。

## 批 3 对抗复核的四条遗留
- N1 🔴 cancelQueuedRun 的前提被批 3 自己的 requeueBlockedRootRun 改没了：
  queued 的 run 现在可以是跑过一半的。探针实测取消后子 run 残留
  paused/stop_requested=0 —— 那条 running 的子 run 继续调 agent 烧 token。
  改为无条件走 engine.stopRun
- L1 ⚠️ 恢复路径对 manual 只兑现一半：注释写着「T1 永远回不来这个后果因此
  消失」，但调度器故意不碰 manual → 退回队列后没人接。定案：「manual 不自动
  出队」约束的是首次起跑的授权，已被人亲手起过的不算新授权。
  判据用 attempt>0 而不是 started_at —— 后者会被 requeue 清成 NULL，
  恰好在需要它的那一刻是空的（实测踩过）
- N2 🟠「退回队列」对用户完全不可见：200 + ok:true + 按钮全灰 + 图消失 +
  一句「节点状态一律 pending」的假提示。加 notice 明说
- N3 🟠 isSlotRaceError 把 InvalidTransitionError 当竞态吞掉，而探针证伪了
  那条注释：被推走时条件更新返回 0 不抛，真正抛它的只有「调用方声明了非法
  转换」。删掉该分支，让它吵起来

四条里三条是同一个模式：注释承诺的前提被本轮自己的改动改没了，注释还留着。
文档 §十三.3 / §十四.4 已就这个模式立过两次案，这是第三、四、五次。

## 文档
§十五 实施记录，含 §15.4 一次流程事故：87b776c 由第三方会话在对抗复核完成
前误提，提交说明的「1201 用例全绿」压在一份尚未通过复核的代码上。

全量：128 文件 / 1240 测试全绿，web:build 通过。

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

lemonboss-78 已补齐 §二 的 4 条（均带探针实跑证据），§七 第一条待办随之过期。
把它勾掉，并把 N1/L1/N2/N3 各自拆成一条待办，附优先级判断：
N1（取消排队留下还在烧 token 的孤儿子 run）是唯一有直接金钱成本的一条。

顺带提一条给 lemonboss-78 判断的提议：「注释承诺的前提被本轮自己的改动改没了、
注释还留着」这个模式已经第三次立案（§十三.3 / §十四.4 / 本次），
第三次或许不该再只当个案记。提议不代表已立案。

只提交本文件；docs/README.md 与 docs/done/claude-cli-session-leak.md
是 lemonboss-89 的在途工作，未动。

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

lemonboss-68 写交接文档时只确知 1 条，其余 3 条刻意留「待补」而不是
凭二手转述硬写 —— 那个判断是对的，记错了反倒会变成新的事实来源。
这里由批 3 作者按 17:00 那次对抗复核的原文补齐，每条都有探针实跑证据。

四条：
- N1 🔴 取消排队留下还在烧 token 的孤儿子 run（唯一有直接金钱成本的）
- L1 ⚠️ 恢复路径对 manual 不成立（调度器故意不碰 manual，于是坑空着没人接）
- N2 🟠「退回队列」对用户完全不可见（200 + 按钮全灰 + 图消失 + 一句假提示）
- N3 🟠 isSlotRaceError 的判据注释被探针证伪，且吞真错误不打日志

其中 3 条是同一个模式：注释承诺的前提被本轮自己的改动改没了，注释还留着。
27-P3C §十三.3 / §十四.4 已就这个模式立过两次案，这是第三次。

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

87b776c 把 lemonboss-78 还在等对抗复核的批 3 提进了 main（提交者是我，未经作者同意），
复核随后给出 4 条问题。这份文档记下：时间线、main 上各笔提交的归属与状态、
那笔提交说明里「1201 用例全绿」的更正、待决策项，以及这次踩实的多会话协作规则。

顺带把最初那条卡住的 run（T-msyu6u9b-939c，boundary_escape 误伤）的诊断与
界面重跑步骤一并留档 —— 它至今没动，等工作区收敛干净才能跑。

只提交本文件，其余 13 个在途文件原样留在工作区未动。

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

goal 从「人写一句话」变成「agent 拆成一张 task DAG、人确认后下达」，
收敛时由 org-validator 在 goal 层再验一次。

## 交付
- task-planning 本体（毕业判据实测通过：agent.md + soul.md 一次写完、
  不带 _base 哨兵、路径按 cwd 深度 3 实算核对）
- 拆分链路：3 轮 errors 原样回喂 → 不过就降级成 1 条同描述 task，
  goal 绝不卡在 planning；token 记 goals.planning_tokens
- goal 级 org-validator 验收：≥2 条 task 全 completed 才调，单 task 跳过，
  有 failed 直接 failed 不调（省一次真花钱的调用）
- 控制台四栏 + GoalTaskPane 两级树 + 两步表单（拆分中给逃生口）
- 中断恢复：启动时补跑验收与汇报

## 三条跨进程竞态，全部用真探针实跑复现后才判定修好
1. runGoalSplit 无条件把 goal 写回 draft，抹掉逃生口刚下达的 active ——
   而触发它的正是表单自己推荐的那个逃生口。后果是一个正在烧钱的 goal
   显示成「草稿」，且从此永不收敛（OKR 不写、上级不唤醒、无日志）
2. CAS 把最终态提前写进库，验收窗口内重启即丢，且 verdict=NULL 与
   「单 task 合法跳过」形态相同，查不出来 → 占位判词 + 启动重推
3. 认领语句 SET verdict=RESUMING WHERE verdict IN (PENDING, RESUMING)
   —— 写进去的值就在 WHERE 里，changes 恒为 1。而函数注释白纸黑字
   写着「认领写的是另一个占位值」。注释是对的，代码没兑现。
   实测：org-validator 调 2 次 / OKR 写 2 条 / token 双记
   → claim 带唯一 token + 时间戳租约，回写条件更新决胜，主路径同闸门

## 与设计正文的偏离（已记进文档 §十四）
拆分后 goal 落 draft 而非 active（active 的语义已被 markGoalDispatched
钉死为「已下达」）；mode 三级继承对显式 tasks[] 同样生效；占位判词不出
API；新增 planning_error / reported_at 两列，后者迁移带回填（否则升级后
第一次启动会把历史终态 goal 全部重报一遍）。

## 过程
四轮 26 个 agent，复核报出 22 条缺陷，其中 6 条是修复自己引入的。
第四轮修完挂了 3 条测试，全是测试在钉住缺陷本身 —— 其中一条的注释
写着「模拟进程死后重启」，构造的却是新鲜占位值：注释描述 A 场景、
代码构造 B 场景、断言按 A 场景写。

全量：118 文件 / 1112 测试全绿，web:build 通过。

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

手工扫了两轮，扫出的是三类会持续复发的失真，不是零星笔误：
  ① package.json 里 12 处引用指向从未在 git 历史存在过的文件（server/src/cli/auto-dev.js 一族）
  ② CLAUDE.md 的 docs/ 那行列了 5 个文件名，文档移进 done/ 之后全成死链
  ③ 数据存储整节把两个不同的 data 根当成一个写，server/conversations/ 这个路径根本不存在

共性是**不报错、不影响测试、git status 干净**，只有照着做的人（或 agent）撞墙才发现。
而 CLAUDE.md 是每个会话都会加载进上下文的文件 —— 写错等于把错误信息直接灌给每一个后来者。

四条扫描：
  - CLAUDE.md 里的仓库路径都存在
  - CLAUDE.md 里出现的每条 npm run 都在 package.json 里（守反方向：删脚本忘改文档）
  - package.json 的 scripts / bin / main 指向的文件都存在
  - docs/README.md 的相对链接都指向真实文件

判据刻意窄（本仓库有过「防线被整条注释掉」的教训）：路径只认「以仓库顶层目录开头 + 含 /」，
且跳过 gitignored 的 —— 那是运行态产物（web/dist/、data/companies/、skills/），在干净机器上
本来就不存在，缺席不是文档错误；这与 no-stale-templates-path.test.js 用的是同一条判据。
上下文里的相对片段（_base/、todo/future/）、glob、<repo>/… 示意写法一律不判。

四条各带「样本非空」下限断言（当前 26 路径 / 16 script 名 / 6 入口引用 / 22 链接），
下限取当前值一半左右：正则一写错就会以「零违例」全绿，那和没有这条测试是一回事。

验证：把同一套判据跑在旧 revision 的文件内容上（只读 git，不碰工作区）——
  3e718aa：路径 ❌3 条、入口 ❌10 条
  d6214f8：路径 ❌4 条、入口 ❌10 条
  HEAD   ：全绿
顺带修掉自己写的一处假路径占位符（`data/xxx` → 「以 `data/` 开头的路径」），
文档里本来就不该出现假路径。

28-followups 守卫清单补到第六条，并写明后两条与前四条的形状差异。
npm run test:unit 1061/1061 绿。

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

新增 §十三，体例照 27-P3/P4 §十：设计正文不改写，只在这里与实现对账，
冲突处以实施记录为准（正文是设计时的判断，本节是跑出来的事实）。

记了与设计的四处偏离，其中两处是设计正文写错了：

① blocked 在 task/goal 两层都不是终态。正文 §四.3 把它与
   completed/failed 并列画成终态，实现时实跑复现出后果：预算耗尽后
   加预算恢复、跑完，两次条件更新静默命中 0 行，最终 run=completed
   而 task=blocked/goal=failed/OKR=failed 永久对不上。RUN_TRANSITIONS
   里 blocked: ['running','stopped'] —— 对 run 它是可恢复态，
   reviveParentFromChild 还会自动拉回。

② goal 级是唯一汇报出口，reportRunOutcome 已删除（零其它调用方）。
   1 goal:1 task 形态下 run 级与 goal 级会把上级就同一件事唤醒两次。
   from 的口径同时修正为实际交付者（terminalAgentId 搬进
   org-graph-service 当唯一持有者），不再用 created_by ——
   那是「谁下的单」，默认字面量 'human'，下游会静默落空。

③ dispatch 挑第一条可跑的 draft，连带补上 PATCH 改 seq —— 原先 409
   的 hint 写着「改依赖或 seq」，而那个端点从不读 body.seq。

正文里三处提到 reportRunOutcome 的地方一并标注：§四.7 加了「本节写于
实施之前」的前置说明，§十二（批 5）的前提改成「函数换了、依赖关系
没变」—— A 的回调链路仍长在 B 身上，只是出口从 company.js 的 run 级
换成了 task-settle 的 goal 级。

过程也记了：三轮编排 21 个 agent，对抗复核报 19 条，其中 4 条是
第二轮修复自己引入的。结论：对抗复核不能只做一轮 —— 修复和实现
一样会出错，而且更隐蔽，它长得像在解决问题。

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

把「人类提的一个需求」与「机器执行的一件活」拆成两级。这不是新概念：
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>

承接 310a2b2 的两个遗留：

① 四类被错标成心跳
   company-heartbeat-service._sendAgentChat 给五类调用（心跳巡检 / Pipeline 步骤 /
   日程 / 告警 / 日报）无差别打 isHeartbeat:true，于是对话列表里全都显示成
   「⏱️ 自主心跳巡检」、meta.type 一律 'heartbeat'。改成显式传 kind，五类各自标注。
   isHeartbeat 仍然发，但只对真心跳为真，老消费方行为不变。

② 310a2b2 让 Pipeline 重试变成了冷启动
   Pipeline 步骤的 convId 是 `pipeline-{runId}-step-{i}`，被驳回重做时**复用同一个**。
   310a2b2 按 isHeartbeat 一刀切回收，等于每次重试都要走 buildPrompt 场景 C 重注入历史。
   现在回收策略挂在 CALL_KINDS 表上，判据只有一条：**convId 会不会被下一轮复用** ——
   会复用的（pipeline / 人类对话）留着走 TTL，不复用的（心跳 / 日程 / 告警 / 日报）跑完即回收。
   不按「是不是后台调用」分：五类后台调用里 pipeline 就是要留的那一类。

守卫补到 12 条（原 3 + kind 标注 5 + 回收策略 4）。对 310a2b2 跑过：8 红 4 绿。
convId 一律用固定字面量而非拼时间戳 —— 撞上 test-id-stability 那道防线后按它的判据改的，
固定之后第二次跑还顺带走了「复用已有对话」那条分支。

文档：
  - CLAUDE.md 注意事项加一条（新增会话创建路径时必须同时定回收路径，附症状与守卫位置）
  - 28-followups 守卫清单补第五条，并把「前四条守单一持有者」与第五条「守资源生命周期」
    的形状差异写明；顺手修掉表格已有 4 行、结尾却仍写「这三条」的失配
  - .env.example 补 AGENT_SESSION_IDLE_MS

全量单测 667/667 绿。重启后 /api/health 正常，心跳照常挂载。

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

27-P3C 批 1 沉淀的不变式测试，与前三条守的是同一件事：同一个事实
只能有一处持有者。断言的是「凡是把 process.env.GRAPH_RUNS_DIR 绑到
标识符上的模块，那个标识符必须在代码里真正被用到」。

来历一并记下：goal-contract.js 里曾有一行 RUNS_ROOT，注释写着
「与 graph-engine.RUNS_ROOT 是同一个变量（测试隔离在用）」，全文件
却零引用。声明了意图、代码不兑现的常量比没有更容易骗人 —— 读的人
会据此认为该模块认这个覆盖，然后写侧写进临时目录、读侧去仓库里找，
两个方向都静默错位。

四条共有的「样本非空」前置断言仍是重点：扫不到文件时这类测试会以
「零违例」的形式全绿，那正是它自己变成零调用方的方式。

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

主文档新增 §11.4b，记 dd319bb 那轮清掉的内容与「不清会怎样」：
四份本体提示词、三个 skill js、两份图模板 README 的 CI 防线规则、
DevLoop PRD 13 份 HTML（连带重生成的 52 份 _spec + manifest + search-index）。

其中两条值得单独记：
- innovator-hunt/collect_seed.js 是真 bug 且已发作过 —— 裸相对路径相对 cwd 解析，
  在 agent 自己目录下造出一棵野生嵌套树。
- DevLoop PRD 写的 system/templates/devloop-pm.md 根和形状都错
  （实际是 system/agents/{agentName}/prompt.md），由此推出一条方法论：
  批量替换字符串时，替换的正确性取决于替换后的整体是否成立，
  而不是被替换的那一段是否过期。

同时订正两处早于本次改造就已过期的内容（「6 个命名冲突 id」清单里四个 id
根本不存在；orggraph-planning 被告知的真相源仍是 company.json.agents[]），
并写明刻意不动的三类：历史说明 / 迁移完成的证明 / 运行态记录。

followups 新增 §五，登记本轮立起来的三条不变式测试
（agents-root-single-holder / no-stale-templates-path / repo-hygiene），
写明它们共有的「样本非空」前置断言为什么不能省，以及改动它们前要想清楚的事。
§四 那条「脚本路径需要跟着更新」已在 cd2066a 完成，改成实跑结论。

交付状态从「未 commit、未 push」更新为已推送（ca468ab..dd319bb）。

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

并行会话指出 graph-engine.js 的 indexNodeOutputs 注释里早就写着
「goal-contract 零调用、setPlanWorkGraph 零调用、三值透传只接了读
那一半」。顺着查下去，这个模式在仓库里被记录过至少 7 处，而且证据
本身就是结论：

- graph-engine.js 跨层判据处：「（『实现在、零调用方』的第五次）」
- graph-run-route-io.test.js 文件头：「这一路踩了十几次的
  『实现在、零调用方』换个方向再来一次」
- graph-run.js:243：「等于又一次『实现在、零调用方』」
- 27-goal-contract-format.md:101：「T0 交付后有四轮时间里，全仓库
  唯一提到 goal-contract.js 的是一句注释 —— 实现完整、零调用方、
  零单测，验收 1 从未被执行过」

有人数到第五次，有人写「十几次」，然后它继续复发。这些记录证明的
不是「有这个问题」，而是「发现了也没人回来收」。

本文档的三处要求是同一个惯犯的三个实例：砍掉 goals.budget_json
（§四.1）、report_to 必须落库（§四.7 禁令二）、处理 goal-contract
那个声明了却零使用的 RUNS_ROOT（验收 12c）。写明它们是硬要求，
不是可以留到下一轮的整洁度问题。

批 1 一并加不变式测试「凡是声明了 GRAPH_RUNS_DIR 覆盖的模块，该
覆盖必须真的被用到」，形状照抄 agents-root-single-holder.test.js。
「样本非空」前置断言别省 —— 扫不到文件时会静默全绿，那正是这类
测试自己变成零调用方的方式。

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

并行会话指出我上一版归因错了，逐条复验后确认它是对的：

【纠正】runRootDir 与 companyRootDir 不是同一事实的两种拼法，是两个
不同的事实：
  runRootDir     → run 目录，覆盖态 {RUNS_ROOT}/{rootRunId}，
                   扁平即可（rootRunId 全局唯一）
  companyRootDir → 公司根，覆盖态 {RUNS_ROOT}/_companies/{cid}，
                   那层 _companies 是必须的（公司 id 不是全局唯一坐标，
                   扁平放会和 run 目录撞名）
company-paths.js 的注释本身写着「理由与 runRootDir 那处 override
一致」，作者是有意区分的。我上一版写成「三种拼法争权威、实施前先定
哪个权威」，会让批 1 实施者去做一个根本不存在的设计决策。真正错的
只有一处：writeTaskGoalArtifact 自己拼路径。修法一行级。

【新增缺陷 B】goal-contract.js:75 声明了 RUNS_ROOT、注释还写着「与
graph-engine.RUNS_ROOT 是同一个变量、测试隔离在用」——然后全文件
一次都没用过，同文件的 resolveRunDir 照旧自己拼。而且 resolveRunDir
全仓库零调用方（只有定义、exports 和一行文档）。

它今天不会出错，危害是注释在撒谎：声明了意图、代码不兑现的常量比
没有这个常量更容易骗人，第一个接上去的人直接踩。批 1 一并处理 ——
要么真的用上，要么连函数带常量删掉（零调用方，删更省）。

【验收】12b 补上必须「先设 env 再 require」的姿势要求，12c 新增。
第六个实例登记：graph-engine:84 / goal-contract:75 / graph-run-sse:34
三处都在模块加载时快照 GRAPH_RUNS_DIR，而 company-paths:14 的注释
恰恰记着相反的教训，既有测试已在为此做变通。教训在一个模块里学会
了没传出去 —— 不是事实被复述，是「事实该怎么读取」的约定只传一半。

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

并行会话把 system/agents 那一族收敛到 locator.AGENTS_ROOT 之后
（e120645，13 处跨 5 文件，我复验 3/3 通过），顺着同一个模式查
company.js 里的 data/companies 那一族，撞见一个真的分叉：

  写 company.js:writeTaskGoalArtifact
     path.resolve(__dirname,'../..','data','companies',...)   不认 GRAPH_RUNS_DIR
  读 graph-engine.js:runRootDir（describeTask / goal-contract 都走它）
     RUNS_ROOT ? path.join(RUNS_ROOT, root_run_id) : ...      认
  三 company-paths.js:companyRootDir
     runsRoot ? path.join(runsRoot,'_companies',cid) : ...    认，但形状又不同

同一个事实三种拼法。GRAPH_RUNS_DIR 一旦设上（目前只有测试在用），
写进 A 处、从 B 处读，describeTask 拿到 null 后静默退回兜底文案
「执行图节点任务」—— agent 从此拿不到真实任务描述，且没有任何报错。
goal-contract.test.js 的注释佐证读取方那套形状才是约定。

生产环境两边恰好都退到同一个默认分支，所以今天不发作。但批 1 会把
artifact 落盘点从「下达时」前移到「入队时」，正好要动这个函数 ——
修的时机就是那时。新增验收 12b 专门验它。

方法论也记一条：我第一次只 grep 了 TEMPLATES_DIR 这个名字，因此漏
掉同一文件里语义相同但叫 DATA_DIR 的 3 处。同义异名的副本按名字
grep 永远找不到，要按值 grep。

这是本文档攒到的第五个同类实例。同一个事实只能有一处持有者 ——
路径也是事实。

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

并行会话提醒 company-service.js 的 TEMPLATES_DIR 名字过期（实指
system/agents）。查调用点时发现更值得记的是 company.js：同一个
路径常量在这个文件里被重复定义了 7 次，6 处硬编码
path.resolve(__dirname,'../../system/agents')，只有 1 处用了权威
访问器 locator.AGENTS_ROOT。

这个路径 2026-08-18 刚被 agent 目录重构搬过一次 —— 下次再搬，
改 6 处漏 1 处就是静默 bug。批 1 本来就要大改 company.js（全部新
端点挂这里），顺手收敛成模块级一份，不是为改而改。

这与本文档反复点名的是同一个病：canDispatch 的取值域被前端复述过
一份、ACTIVE_ROOT_RUN_STATUS 在两个文件里逐字重复、
isUngraduatedStatus() 的取值域不许在别处复述。同一个事实只能有
一处持有者，路径也是事实。

同时登记一条刻意不做的：company-service.js 那个 TEMPLATES_DIR
改名要动 50 处、跨 6 个文件、零功能收益，不值得。留记录是为了
说明它是已知的，不是没人看见。

顺带独立复验：template-refs.test.js 4/4 通过，27-P3/P4 的
blocker 21（CI 因骨架悬空引用而红）确实已关闭。

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

刚提醒过并行会话「27-graph-agent-architecture 的状态行落后两个阶段，
会连累每一次迁移判断」，回头看自己这份也有同类问题：文档名叫 p3c、
自述「P3 收尾」，但内容已经溢出 P3 的边界。

补清楚三件事：
- 批 1-3 才是真正的 P3 收尾，是本文档主体
- 批 4（并行）归 27-P4 §一.3，那边是设计权威（§五.2 已有警示块）
- 批 5（两套任务体系统一）不属于任何既有 phase，是跨阶段技术债清理

以及最要紧的一行：五批全部未开工，0 行代码。判断能否搬 done 时
按批看，别按文档名看。

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

两处都是实测校准，不是凭印象改：

1. 27-graph-agent-architecture.md 的状态行落后两个阶段。
   原写「P2 起 📝 设计中/未实现」，实际 P2 的设计已归档在
   docs/done/system-design/27-p2-org-graph.md，P3 主体也已实现
   （27-p3b 自述「P3 主体已实现并提交 c3abf4a 起七轮，719/719 全绿」，
   27-p3-p4 有完整的 §十 实现记录 + 第六轮终验回填）。
   校准为 P0/P1/P2/P3主体 ✅、P4 📝 未实现。

   这一行是别人判断「哪些文档能从 todo 搬去 done」的依据，
   过期会连累后面每一次迁移判断，所以补了一句提醒。

2. 27-p3-p4 的 blocker 21（骨架悬空引用，CI 红）已由 28 号改造顺带关闭。
   实测：六个 id 全部登记在 system/agents/_registry.json；
   template-refs.test.js 4/4 通过（全量 999/999）。
   原文登记为「未修」的第二个隐患（_registry.json 被 usedCount 原地改写）
   也已关闭 —— usedCount 已挪到 data/template-usage.json（27-P3B W13），
   跑完真 CLI E2E 后该文件 git status 干净。
   原始记录保留备查。

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

27-P4 §一.3 的目标逐字写着「解除『一家公司同时只有一个 active
root run』约束 —— P3 v1 用一个唯一索引强制它，并行能力具备后应
放开」。本文档的批 4 在做同一件事。

划清边界：放开约束的设计归 27-P4，本文档只负责在它之上定义
「谁来排队、按什么序出队」。两边各写一版会产生两套并发守卫 ——
而这次要删的正是最后一道 DB 兜底，守卫分裂的代价特别高。

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>

并行的 agent 重构那条线同步来的，已核实三个函数都在：
- agent-locator.js  missingBodyDefinition()   判什么算没填完
- graph-service.js  promoteDraftIfComplete()  转正动作
- graph-service.js  isUngraduatedStatus()     hire() 挡人的判据

关键是最后一个只挡 draft / training 两个状态，不是「≠ active 就挡」。
库里有 36 个本体的 status 是 enabled/idle/ready/trained，按「不等于
active」判会被全部误判成没填完 —— 这个坑已经被踩过一次。

取值域的唯一持有者是 graph-service，不要在别处复述 —— 与本文档
§六.3 记的 canDispatch 教训（前端复述了一份取值域还多写一个
blocked，导致公司失败一次后再也下不了任务）是同一个病。

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

另一条工作线正在做 agent 目录结构重构（system/templates 并入
system/agents），约 900 个变更尚未提交。逐条核实交集：

好消息 —— 本文档引用的全部函数/常量（settleRun / markRunReady /
stopRun / defaultPlanWorkGraph / PLAN_MAX_ROUNDS /
writeTaskGoalArtifact / reportRunOutcome / ACTIVE_ROOT_RUN_STATUS /
saveTaskMeta / getAggregatedTasks）在 650 行改动后全部存活，五条
行为性结论逐条复验仍成立，work-graph-db.js 完全没被碰（第二轮
复核最关键的那批发现不受影响）。27-P3/P4 那条「只写函数名不写
行号」的体例在这里直接兑现了价值。

坏消息 —— §四.9 有一条写反了，已纠正并留档：
- system/templates/ 彻底取消，本体落 system/agents/task-planning/
- _registry.json 不再是数据源头（seedAgents 直接 readdirSync 扫
  目录当真相，registry 只按 id 补 benchmark_score），所以「不登记
  会把 CI 跑红」不成立 —— 建目录才是关键动作，登记是可选的
- 真正的闸门是新增的「毕业」判据：agent.md + soul.md 非空且不带
  _base 骨架哨兵，否则 status 停在 draft、hire() 返回
  body_not_ready。「先建骨架后填」的中间态雇不进公司
- 本体正文路径三条硬规矩（cwd 深度 3）：自身文件 ../../、仓库根
  ../../../../../、交付物必须用 $W 绝对路径。写错全都不报错、
  只静默降级 —— 静默故障家族的最新成员

排期影响：批 1 照常（work-graph-db.js 无人触碰）；批 2 的
task-planning 本体等重构落地后再建，否则要按旧形态做一遍再改；
批 5 开工前重新核 agent-chat.js（+455 行）。

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

companyService.get 已经在读这个文件，零新增读路径；建表要多一张表、
一套读写、一次迁移，而目前公司级配置项只有这一个。涨到 3 个以上时
再考虑建表。

这是 P3C 最后一个开放问题，§十一 至此全部关闭。

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

R-20.6：
1. 退役 /api/goals 与 /api/company/:cid/goals 两个 OKR 别名，确认执行
2. goal 级验收仍用 org-validator，在 goal 层再调一次同一个本体。
   不复用 task 级结论 —— 两次验的是基数不同的东西：task 级问
   「这一个 task 的 task-goal 达成没有」，goal 级问「N 个 task
   合起来人要的东西做出来没有」。单 task 的 goal 跳过这次调用。
   goal 状态机加 failed，判词落 goals.verdict
3. 预算先不考虑，不做 goal 级闸门；但 planning_tokens /
   validation_tokens 两个记账字段保留 —— 它们不是闸门，是让
   goal 层那两次 agent 调用的花费可见
4. queued 开放改 depends_on。当初担心的「改完位次怎么算」不成立：
   queuePosition 只按 priority→seq→created_at 排，depends_on 决定
   的是够不够格出队，两者正交
5. 两套任务体系统一到 tasks 表，新增 §十二（批 5）

定案 5 核实出一个反直觉的前提：两套不是并列的，新体系的回调链路
长在旧体系身上 —— reportRunOutcome 收敛后调的正是
/api/agent/task/report。所以「删掉另一套」= 删存储与会话反推
（system/tasklog + TaskService.getAggregatedTasks），不能删入口
与回调：/task/dispatch 的 URL 与请求体写在 tools-base.md 里，
改它等于同时改所有 agent 的提示词。

tasks 表为此吸收三个字段（executor / assignee_agent_id /
parent_task_id）：agent 派单与 graph 执行的载体确实不同，
硬说成一回事是骗自己；调度器只管 executor='graph'。
顺带修好：派单去重从扫目录变一条 SQL，两套 T- id 合一。

开放问题 2/4/6/7 全部关闭，只剩 5（max_parallel 放哪）。

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

上游失败时下游自动转 blocked 已定案，开放问题里还留着同一个问题
的疑问句 —— 这正是「代码改了、文档停在上一轮」那类漂移。

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

R-20.5 四条：
1. task-planning agent 提进 v1（原计划 v2 人手拆）。产出一律 draft
   清单，人确认编辑后才下达 —— 那一步是唯一一道成本闸门，
   拆出 5 条 task 就是 5 份 DEFAULT_TASK_BUDGET
2. 并行仍留批 4，v1 只排队（max_parallel_tasks=1，唯一索引不动）
3. manual 任务不参与自动出队：startRun(manual) 只点亮入口就停下等
   /next，而 run 已经是 running 占着坑，自动拉起会堵死队头
4. 上游失败 → 下游自动推导为 blocked 并标红，给「重跑上游」和
   「强制放行」两个出路。blocked 每次 tick 重算而不落死，
   上游重跑成功后下游自己回 queued

定案 1 牵出一处新缺陷：task-planning 跑在 goal 层、任何 run 存在
之前，它烧的 token 没有预算池可扣 —— 正是 defaultPlanWorkGraph
注释里点名的「隐形的一半花费」在 goal 层的新实例。上一轮刚以
「零消费方」为由砍掉的 goal 级预算字段，以记账字段 planning_tokens
的形式回来（闸门仍不做）。

链路照抄 defaultPlanWorkGraph 不另造：调 agent → 校验 → errors
原样回喂，最多 3 轮；3 轮不过降级成 1 条同描述的 task，绝不能把
goal 卡在 planning。新本体必须与 _registry.json 登记同 commit，
否则 template-refs.test.js 当场把 CI 跑红（§八.21 有前科）。

验收 19-24 新增：拆分正常 / 失败降级 / 记账 / 不该花钱的路径不花钱
/ 上游失败下游标红且可恢复。

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

逐条对着代码核初稿，最要命的一条是基础事实搞错了：

- createRun 在建行的事务里就按 readDefGraph 把 graph_run_nodes 全插好了。
  初稿三处基于「queued run 没有节点行、进去就是空指针」的论证全部作废。
  真实情况是 queued run 与 ready run 在数据上只差 run_status 一个字段，
  所以「靠没有节点行自然报错」那道想象中的防线根本不存在，
  唯一的闸门是 advanceOne 里 run_status !== 'running' 那一句，必须加断言钉死。

由此派生出一个既存、但被排队从毫秒窗口放大成必然事件的缺陷：
节点行在 createRun 时快照，而 getRunState 每次读都取当前定义。
排队期间点「重新规划组织」→ 新节点没有 run 行 → 出队即卡死。
补 syncRunNodesToDef，出队前对齐。

其余六处：
- 出队原语写错：markRunReady 把 from 写死成 planning，复用不了；
  正解是 updateRunStatus(runId,'queued','ready') 这一条条件更新
- 唯一索引冲突是 throw 不是 changes=0，初稿的错误处理只覆盖一半
- 触发点枚举本身是漏的：stopRun 与预算耗尽→blocked 两条最常见的
  释放路径都不走 settleRun。改为挂在唯一漏斗 transitionRun 上，
  一个钩子覆盖全部路径（枚举法在这里靠不住，而漏的症状是静默的）
- report_to 只活在请求闭包里，排队后回调链路静默断掉 → 必须落库
- okr_node_id 逐 task 下发会反复覆写同一个 OKR 节点，
  done 会被后来的 failed 翻掉 → task 的 run 一律不带 okr_node_id
- manual 任务占着 running 等人点「下一步」，会永久堵住队头
  → 不参与自动出队

补漏：存量回填脚本（不做的话批 1 反而让历史任务更看不见）、
任务级 rerun 与节点级 retry 的命名撞车、queuePosition 排序口径
必须与调度器同源、砍掉没有消费方的 goals.budget_json。

错误结论留档不删（§三 ⚠️ 块 / §五.1 / §九.1 开头）——
它们是最容易再犯一次的那类。验收从 12 条涨到 19 条。

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

控制台走查暴露的「一个 company 只能有一个任务」，根因不是并发约束，
是「人类提的需求」和「机器执行的单元」被压在同一条 root graph_run 上。

三个实地核实的前提，让这次不是发明新概念：
- 27-NAMING §四 早就定义了 goal 1 : task N 的基数
- graph_runs.goal_id / task_id 两列早就在，company.js 注释也写着
  「三者基数不同不可混用」—— 但全仓库没有任何写入方，goal_id 是悬空外键
- G- 前缀已被 OKR 正名释放；/api/goals 与 /api/company/:cid/goals 这两个
  OKR 向后兼容别名全仓库零调用方，可以退役后把路径要回来

设计要点：
- goals / tasks 两张新表 + graph_runs 新增 run_status='queued'
- queued 的唯一理由是把出队的并发临界区交给既有唯一索引兜底：
  idx_graph_runs_one_active_root 覆盖 ready/running/paused 而不覆盖 queued，
  超发会被索引直接拒绝，不需要应用层的「先查后插」
- 排队推翻了 P3「拒绝而不排队」的定案，但那条定案的理由（没有出队 worker =
  静默丢任务）今天仍成立，所以调度器的四个触发点是功能主体而非收尾
- 已下达的描述冻结：入队即写 task-goal.json 并被 describeTask 消费，
  改库不改 artifact 会让两份对不上，两份都改等于篡改审计输入
- 现有 T-${Date.now().toString(36)} 在「一个 goal 批量建 N 个 task」下
  同毫秒必撞，且 tasks.id 是主键 —— 改用仓库既有约定的 4hex 后缀

R-20 四条定案回记至 27-requirement.md。

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>