docs(28): 补记 system/templates 清理这一轮，并登记已立起来的三条守卫

主文档新增 §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>

docs(28): 补记 system/templates 清理这一轮，并登记已立起来的三条守卫
主文档新增 §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>
yibo
1 parent dd319bbd
Showing 2 changed files with 53 additions and 3 deletions
docs/done/system-design/28-agent-registry-unification.md
docs/todo/system-design/28-followups.md
@@ -612,9 +612,41 @@ echo OK
 - **`source_kind` / `legacy_path` 删列**（验收 2 后半）：两列仍在，见批次 1-5 的实际注记。
 - **任务态清理策略**（§5.6）：仍然只有设计、没有实现。实现时**必须**先读 §5.6b —— 公司态是 dream 的原料，不是缓存。
  
+### 11.4b 收尾：清掉活定义里所有已死的 `system/templates` 引用（`dd319bb`）
+
+批次 1 把目录并走之后，**目录本身在磁盘和 git 里都已不存在**（`git ls-files system/templates` 返回空），
+但引用还散在各处。这一轮把「agent 运行时真会照着读写的那些」全部清掉：
+
+| 位置 | 处理 | 不清会怎样 |
+|------|------|-----------|
+| 四份本体提示词（`workgraph-planning` / `orggraph-planning` 的 `agent.md`+`tools.md`、`org-innovator/agent.md`） | 9 处路径 + 4 条产出落点 | agent 读不到就**静默降级**，不报错 |
+| `evolver-youtube-crawler` 的三个 skill js | 4 处硬编码目标 | 同上 |
+| `innovator-hunt/collect_seed.js` | 裸相对路径改为按 `__dirname` 推导 | **真 bug，已发作过**：相对 cwd 解析，在 agent 自己目录下造出一棵野生嵌套树 `system/agents/innovator-hunt/system/templates/…` |
+| `work-graph-templates` / `org-graph-templates` 的 README | CI 防线三条规则 | 文档写的规则与实际执行的检查对不上（测试早改对了，只有 README 没跟上） |
+| DevLoop PRD（13 份 HTML → 重生成 52 份 `_spec` + manifest + search-index） | 按真实形状改 | **根和形状都错**：写的是 `system/templates/devloop-pm.md`（扁平 `.md`），而 `loop-controller.js:166` 读的是 `system/agents/{agentName}/prompt.md`（目录 + `prompt.md`） |
+
+最后一行推出一条值得记的方法论：
+**批量替换字符串时，替换的正确性取决于替换后的整体是否成立，而不是被替换的那一段是否过期。**
+无脑把 `templates` 换成 `agents` 会把一个错路径改成另一个错路径。
+
+顺带订正两处**早于本次改造就已过期**的内容：
+
+- 「避开 6 个命名冲突 id」列的 `digester` / `evolver` / `hunter` / `innovator` **四个 id 根本不存在**（早已改名），
+  而它的理由（两个目录下各有一份、内容不同步）也已随合并消失。约束保留（元 agent 本来就不该进执行流），
+  理由与清单按实际本体重写。
+- `orggraph-planning/agent.md` 里「真相源是 `company.json.agents[]`」—— 28 号起真相源是 `company_agents` 表。
+
+**刻意不动的三类**（改了是净损失）：① 解释迁移历史的注释、`docs/done/`、`tasks/` 下的执行记录；
+② `server/tests/` 里断言该目录已不存在的守卫（删掉等于删掉「迁移已完成」的证明）；
+③ 未跟踪的 `workspace/` `conversations/` 与 `train/` 下的历次训练报告（那是记录，不是定义）。
+
+新增 `server/tests/unit/no-stale-templates-path.test.js` 守住「活定义」这一档，**零例外**。
+判据是「**git 跟踪的才是人工维护的定义，未跟踪的是运行态产物**」——
+这条判据本身就把上面三类自动排除掉了，不需要写脆弱的例外规则。
+
 ### 11.5 交付状态
  
-**改动全部在工作区，未 commit、未 push。** 提交时注意：测试过程中在真实
+**改动已全部提交并推送**（`ca468ab..dd319bb`，四个提交）。当时的提交注意事项保留备查：测试过程中在真实
 `system/agents/` 下建出来的 agent 本体（`zz-*` 这类，当前工作区里共 **17 个**，如 `zz-tenant-ceo` / `zz-draft-role` / `zz-heartbeat-scoped` …）
 **是正式注册表条目，一并进版本库** ——
 它们不是测试垃圾，而是可被后续任何公司复用的本体，agent 复用得越多、积累的历史与经验越多。
@@ -80,9 +80,9 @@
 ## 四、验证口径提醒
  
 主文档 §11.3 留了一段「文档与代码一致性检查」的 shell（常量改名同步）。
-它引用的三份文档路径里，28 号那份已移入 `docs/done/system-design/` —— **那段脚本的路径需要跟着更新**。
+路径已随文档迁移更新完毕（`cd2066a`），实跑三份文档全部命中当前常量名 `AGENT_REGISTRY_TREE_RE`。
  
-另外，取值域**不要**抄进文档。毕业闸门的权威判据只有三处：
+取值域**不要**抄进文档。毕业闸门的权威判据只有三处：
 - `server/services/agent-locator.js` 的 `missingBodyDefinition()`
 - `server/services/graph-service.js` 的 `promoteDraftIfComplete()`
 - `server/services/graph-service.js` 的 `isUngraduatedStatus()`（只挡 `draft` / `training`）
@@ -90,3 +90,21 @@
 文档里复述取值域会产生第二份真相 —— 这个坑本仓库踩过：
 一度按「≠ active 就挡」判，把库里 36 个 `enabled`/`idle`/`ready`/`trained` 的本体全判成「没填完」，
 `workgraph-planning` / `master` / `qa-judge` 全部雇不进来。
+
+---
+
+## 五、已经立起来的守卫（别重复造，也别删）
+
+这三条是本轮沉淀的不变式测试。它们守的都是「同一个事实只能有一处持有者」，
+而且都带**「样本非空」前置断言** —— 少了那一条，扫描路径一写错就会以「零违例」的形式全绿，
+一条永远通过的不变式测试和没有这条测试是一回事。
+
+| 测试 | 守什么 | 违例时 |
+|------|--------|--------|
+| `agents-root-single-holder.test.js` | 本体根路径只能由 `locator.AGENTS_ROOT` 持有 | 精确点名到文件行号 |
+| `no-stale-templates-path.test.js` | 活定义里不许出现已死的 `system/templates`（判据：git 跟踪的才是定义，未跟踪的是运行态产物） | 同上 |
+| `repo-hygiene.test.js` | tracked 与 ignored 不重叠 | 列出越界文件 |
+
+**改动它们之前先想清楚**：这三条的价值全在于「红了才有用」。
+放宽判据、加例外、或者把断言改成永远成立的形式，等于把守卫拆掉 ——
+本仓库有过「隔离是表演」的测试污染前科。