docs(28): 守卫清单补第四条 runs-root-single-holder

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>

docs(28): 守卫清单补第四条 runs-root-single-holder
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>
yibo
1 parent 7764f081
Showing 1 changed file with 7 additions and 1 deletions
docs/todo/system-design/28-followups.md
@@ -95,7 +95,7 @@
  
 ## 五、已经立起来的守卫（别重复造，也别删）
  
-这三条是本轮沉淀的不变式测试。它们守的都是「同一个事实只能有一处持有者」，
+这几条是沉淀下来的不变式测试（前三条出自 agent 目录重构那一轮，第四条出自 27-P3C 批 1）。它们守的都是「同一个事实只能有一处持有者」，
 而且都带**「样本非空」前置断言** —— 少了那一条，扫描路径一写错就会以「零违例」的形式全绿，
 一条永远通过的不变式测试和没有这条测试是一回事。
  
@@ -104,6 +104,12 @@
 | `agents-root-single-holder.test.js` | 本体根路径只能由 `locator.AGENTS_ROOT` 持有 | 精确点名到文件行号 |
 | `no-stale-templates-path.test.js` | 活定义里不许出现已死的 `system/templates`（判据：git 跟踪的才是定义，未跟踪的是运行态产物） | 同上 |
 | `repo-hygiene.test.js` | tracked 与 ignored 不重叠 | 列出越界文件 |
+| `runs-root-single-holder.test.js` | 凡是把 `process.env.GRAPH_RUNS_DIR` 绑到标识符上的模块，那个标识符必须在**代码里**（不是注释里）真正被用到 | 精确点名到文件行号 |
+
+> 第四条的来历值得记：`goal-contract.js` 里曾有一行 `const RUNS_ROOT = process.env.GRAPH_RUNS_DIR || null`，
+> 注释白纸黑字写着「与 graph-engine.RUNS_ROOT 是同一个变量（测试隔离在用）」，**全文件却零引用**。
+> 一个声明了意图、代码却不兑现的常量，比没有这个常量更容易骗人 —— 读的人会据此认为该模块认这个覆盖。
+> 它同时也是「实现在、零调用方」这个惯犯模式的又一例（本仓库有人数到第五次，有人写「十几次」）。
  
 **改动它们之前先想清楚**：这三条的价值全在于「红了才有用」。
 放宽判据、加例外、或者把断言改成永远成立的形式，等于把守卫拆掉 ——