宜博 / lemonboss

## 一、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>

起因是「全量测试偶发挂一条」。查下来既不是回归、也不是那 45 个孤儿进程（它们 CPU 早归零、
不再写任何东西），而是**还活着的心跳在测试扫描 system/agents/ 的同时往里建目录**：

    locator.taskDir() 的落点是 system/agents/<agent>/<companyId>/<taskId>，
    运行态目录落在本体目录里属既定设计；但心跳每 5 分钟建一个新的
    （cto/_global/ 已 263 个子项且在涨），于是扫描 system/agents/ 的守卫测试
    （no-dead-path-references 那一类）会撞上瞬时竞态：列到了目录名，进去时那一层还没写完。

症状是偶发假失败、重跑就好 —— 这类最费人，因为第一反应总是去怀疑自己刚改的代码。

改法：server/index.js 启动的那个 setTimeout 块里，恰好装着全部「会自己起 agent 的东西」
（两处中断恢复 + 任务队列扫描 + 两路心跳），所以一条早退就够，不必在五个地方各加一个判断。

    DISABLE_BACKGROUND_AGENTS=1 bash start.sh

实测：127 文件 / 1226 用例全绿，跑前跑后 cto/_global 子项数都是 263。

**验证它生效不能只看日志里的 ⏸** —— 那只证明代码走到了早退。硬判据是目录数前后相等，
也就是真的没有东西在写。文档 §七 把这条写成了可粘的三行。

排掉的两个坑，都记在文档和 .env.example 里：

1. `.env` 里不能给这个键赋空值。start.sh 是 `set -a; source .env` 加载的，.env 里只要
   存在同名键（哪怕空的）就会盖掉命令行传进来的 =1，而且不报错。所以 .env.example 里
   它只以注释形式出现 —— 一个「示例文件顺手写全」的习惯会直接让开关失效。

2. 开关生效后 `[TaskQueue] 🚀 已启动` 仍会打印，那是另一个模块：services/task-queue.js
   （ArenaSK 时代 /api/claude-chat 的队列，routes/claude-chat.js 模块加载时起），
   和批 3 的 services/task-scheduler.js 同名不同物。它的心跳只扫内存里的 this.tasks，
   不碰 system/agents/，不是干扰源。名字撞车，容易误判成开关没生效。

文档同步：
  - docs/done/claude-cli-session-leak.md §七 重写（原文写的是「得让测试隔离，或跑前停心跳」，
    现在后者已实现，改成开关的用法 + 硬判据 + 上面两个坑）；原第 2 条降为 §七之二
  - CLAUDE.md 测试命令块加一行（这是找「怎么跑测试」的人真正会看的地方）
  - docs/README.md 索引行补上开关

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

泄漏被修过一次（310a2b2 / 3e718aa），修完照样漏。第二次排查发现原因不是修错了，而是：

    系统里有两个互相独立的会话池，上一次只修了其中一个；而被修的那个，还漏了一条分支。

    池 A  routes/agent-chat.js 的 sessions       ← /api/agent/:id/chat，含两路心跳
    池 B  src/core/session-pool.js 的 SessionPool ← AgentManager.callAgent，图执行 / DevLoop

两者没有任何共享代码，回收逻辑各写各的。这个结构性事实此前没有任何一处记着，
所以第二个人查到同一个症状时会重走一遍全程 —— 这份文档就是为了让第三个人不必再走。

正文八节，除了两个洞各自的成因与修法（b0b2b62 / 2092a2e），有三处是排查方法而非结论：

§三 按 cwd 第三层判断孤儿归属的对照表。两个池子都把 cwd 下沉到运行态目录，
     `_global` / `_no-task` 是 agent-locator 的保留缺省值、两边都会出现，不能靠它区分。

§四 为什么上一版守卫是瞎的。dropSession 和 closeSession 都会让会话从池子里消失，
     黑盒探针两种情况都返回 false —— 差别只在子进程死没死，而那是探针看不见的维度。
     选探针要问的不是「能不能测出正确行为」，而是「能不能区分正确行为和这个具体的错误行为」。

§八 三步定位脚本，外加一条：先确认跑着的服务器进程是什么时候启动的，再去看代码。
     本次排查中，正在跑的实例比修复 commit 早 18 秒启动，代码里有的修复它并没有。

线上验证（PID 63099，13 分钟窗口两轮心跳）：触发 5 / 完成 5 / 回收 5，峰值子进程 3、稳态 0。
17:13:32 那个 3 正是泄漏时代的签名（cto+coo+qa-judge 同秒触发），清理前那批孤儿一个都不回收，
现在 30 秒内全部释放。窗口内没有失败心跳，所以 2092a2e 那条 catch 路径是靠单测的变异检验
保证的、不是靠线上观察 —— 文档 §六 里写明了，没算成已验证。

docs/README.md 同步加索引条目（no-dead-path-references 守卫 4 条全绿）。

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

用户授权清理 system/templates/ 的过期引用。全仓库核了 34 处，
结论与预期相反：没有该删的死代码，但有两处正在静默失效。

真正坏掉的（demo-harness-company.js）：
  path.join(ROOT, 'system/templates/base/agent.md')   → system/agents/_base/
  path.join(ROOT, 'system/templates/base/config.json') → system/agents/_base/
两处都包在 fs.existsSync() 里，所以目录消失后**不报错**，只是
静默跳过 base 本体的挂载 —— demo 跑出来的 agent 没有四段式骨架，
但脚本照常打印成功。又一个静默降级。

顺带：real-pm-smoke.js 的提示文案、migrate-agent-naming.js 里
已失效的遍历项、docs/README.md 的 qa-judge 落点。

CLAUDE.md 目录速查表原来只有 `system/templates/devloop-*/` 一行，
连 system/agents/ 都没列。换成两行并写清三个容易踩的点：目录才是
数据源头（seedAgents 直接扫目录）、_registry.json 只补
benchmark_score、_ 前缀是保留 id 会被跳过。

**刻意不动的**：server/tests/ 下 30 处引用。它们分两类，都得留 ——
① 记录迁移过程的注释；② 断言目录已不存在的守卫
（`expect(git(['ls-files','--','system/templates'])).toBe('')`、
`expect(fs.existsSync(...)).toBe(false)`）。删掉后者等于删掉
「迁移已完成」的证明。legacy_path 那几个测试夹具同理，是历史数据形态。

验证：三个脚本 node --check 通过；改后的四个路径实测存在。

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

按 docs/README.md 既有约定（done/ 放「已实现/当前有效」），把两份已落地的
阶段设计文档移入 done/system-design/：

- 27-p1-virtual-reference.md  P1 虚拟引用寻址，commit 226489d
- 27-p2-org-graph.md          P2 Org Graph，70a4727 + f20d0d8，真实建公司端到端验证过

用 git mv 保留历史（R098 / R087）。移动断掉的 33 处相对链接已全部修复：
moved 文件内的出向链接改 ../../todo/system-design/，todo/ 下 6 个文件的入向链接
改 ../../done/system-design/。全 docs/ 扫描无断链。

README 此前严重过时——只列了 2 份 27 文档，实际已有 11 份。本次补全 todo/ 表格，
每份标注状态与作用（总纲 / 需求源头 / 命名规范 / 端到端 / 参考场景 /
P3+P4 已实现 / 验收契约 / P4 设计中），并在 done/ 表格补上 P1、P2 两行。

■ 刻意没有移动 27-p3-p4-work-graph-console.md
它虽然已实现（c3abf4a），但文档正被另一进程持续修改（工作区 M 状态）。
移动会打断它的编辑路径，等它收尾后再归档。

■ 三份文件的链接修复留在工作区未提交
27-naming-conventions.md / 27-p3-p4-work-graph-console.md / 27-requirement.md
里，我的链接修复与另一进程的在途编辑混在同一文件中，单独拆分风险大于收益。
工作区内容是正确的（链接已指向新路径），会随它下次提交一并带上。

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

- New docs/README.md indexes the tree: done/ (shipped features + reference manuals),
  todo/ (current focus — Graph Agent architecture), todo/future/ (deprioritized
  roadmaps: FDE pipeline todo list, stale v1.1 milestones, harness engineering
  proposal — orthogonal to the Graph Agent work, not blocking it)
- Move completed/reference docs into docs/done/ (LEMONBOSS-SYSTEM-DESIGN, architecture-v5,
  claude-code-cron, open-api-manual, qa_judge_req, task_timeline_design, user-guides/,
  system-design/01-26 minus the three moved to todo/future/) — verified against actual
  code (qa-judge template, Task Timeline route/service/view) before filing as done
- Fix the two TOC links in LEMONBOSS-SYSTEM-DESIGN.md that would otherwise point at the
  old paths after the move
- docs/todo/system-design/27-graph-agent-architecture.md: add the P2 Org Graph doc link
  in the roadmap table and 关联文档 section
- Add docs/todo/system-design/27-p2-org-graph.md (P2 requirements & design, drafted in
  parallel while P0/P1 landed)

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>