From d91d352f9da253577d662c303194c6b2f3139189 Mon Sep 17 00:00:00 2001 From: yibo Date: Tue, 18 Aug 2026 16:41:01 +0800 Subject: [PATCH] docs(28): 守卫清单补第四条 runs-root-single-holder --- docs/todo/system-design/28-followups.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/todo/system-design/28-followups.md b/docs/todo/system-design/28-followups.md index d2e7203..e3ee9c5 100644 --- a/docs/todo/system-design/28-followups.md +++ b/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 是同一个变量（测试隔离在用）」，**全文件却零引用**。 +> 一个声明了意图、代码却不兑现的常量，比没有这个常量更容易骗人 —— 读的人会据此认为该模块认这个覆盖。 +> 它同时也是「实现在、零调用方」这个惯犯模式的又一例（本仓库有人数到第五次，有人写「十几次」）。 **改动它们之前先想清楚**：这三条的价值全在于「红了才有用」。 放宽判据、加例外、或者把断言改成永远成立的形式，等于把守卫拆掉 —— -- libgit2 0.21.4