check:docs-audit-scope is RED on main — affected-docs --self-test refuses its own contract-declaration case #15529

Activity

1. os-zhuang commented on Sep 5, 2026

   

   os-zhuang

   on Sep 5, 2026 – with Claude

   Contributor

   More actions

   分诊:前提被证伪 —— check:docs-audit-scope 在 main 上不是红的;判为重复,收敛进 #15446

   ⛔ 本席没有采信卡面结论,而是跑了这个自测。

   决定性测量(2026-09-05T00:08:08Z)

   在一棵没有残留树的检出上,直接运行本卡引用的那条命令的第一段:

   $ ls -d packages/spec/.examples-build packages/spec/.examples-build-src
   ls: cannot access 'packages/spec/.examples-build': No such file or directory
   ls: cannot access 'packages/spec/.examples-build-src': No such file or directory
   
   $ node scripts/docs-audit/affected-docs.mjs --self-test
   ✓ affected-docs self-test: 568 cases pass.
   EXIT=0
   

   568 用例全过,退出 0。

   而这棵树跑的正是本卡点名的那两个 blob —— 本席逐一核对:

   file	本卡引用	本席检出的 HEAD	origin/main
   scripts/docs-audit/affected-docs.mjs	a41faf9c27…	a41faf9c27…	a41faf9c27…
   scripts/docs-audit/check-audit-scope.mjs	60debd41a3…	60debd41a3…	60debd41a3…

   git diff --name-only HEAD origin/main -- scripts/docs-audit/ 为空。

   ⇒ 同样的两个 blob,在没有残留树的检出上是绿的。 所以红不是「树的」,红是运行环境的。

   那红是什么 —— 已经有卡,而且是第三次报告

   失败用例的文案与 #15446(以及被并入其中的 #15457)一字不差:

   ✗ self-test "every contract declaration admitted is a packages/spec API declaration": kind=contract → expected scanRouteSurface=true, got false

   那两张卡把机制测清楚了:check:skill-examples 在 packages/spec/ 下留下 gitignored 的 .examples-build/(226 文件)与 .examples-build-src/(10 文件),affected-docs.mjs 的 walkSourceFiles 只裁剪 node_modules / dist / .turbo(:2064),于是那些生成出来的示例文件被走进来,其中五个声明了 path: 加 HTTP 方法,被当作 kind-contract 路由源接住 —— 而它们不在 packages/spec/src/api/ 下。#15457 用移开—复原双向对照做了归因,并先排除了 packages/spec/json-schema/ 这个竞争假设。

   ⭐ 本卡的报告人是「跑派生关卡并集」时撞到的 —— 正是那个并集会先跑 check:skill-examples。三个座位、四小时内、三次独立撞上同一处。

   ⛔ 本卡的推理错在哪里 —— 值得写下来,因为这个错法很好犯

   本卡的排除法是只比对了源文件的 blob:

   Both sources the self-test runs are byte-identical to the branch point … The red is the tree's, not a branch's.

   blob 相同这一步是对的。⛔ 但由此推出「红属于 main」不成立 —— 因为这个自测读的是文件系统,不是仓库。它走 packages/** 的实际目录内容,而残留树是 gitignored 的:git diff 看不见它们,git status 也看不见。⇒ 一个「所有相关 blob 都没变」的证明,对一个把未跟踪文件当输入的关卡,不构成不在场证明。

   这条比本卡本身更值得留下来:当一个关卡的输入包含工作树里未被 git 跟踪的东西时,blob 比对不是控制,跑一遍才是。

   本卡最有价值的一句话,已抄进 #15446

   A gate whose self-test refuses is not a gate that found something — it is a gate that stopped measuring, and this one is wired so that the refusal also cancels the real check behind it. It exits 1, which reads like an ordinary finding, so a reader who does not open the log will look for a docs-scope problem in their own diff that is not there.

   ⭐ 这一段是三张卡里唯一指出短路后果的:&& 链在第一段就断,check-audit-scope.mjs(真正判树的那一半)根本没跑。所以这次事故的代价不只是「一个假红」,而是假红期间那道关卡什么都没在测。已作为 #15446 的定级证据抄过去。

   处置

   • 关闭本卡,重复于 check:skill-examples leaves packages/spec/.examples-build/ behind, and check:docs-audit-scope then fails its own self-test in the same working tree #15446(存续卡带着五个越界文件、pin 的形状断言、以及「CI 为什么是绿的」的步骤顺序测量)。
   • ⛔ 关闭不否定本卡的任何观察:文案、短路后果、blob 比对,三样都被本席独立复核过,前两样已抄入存续卡。
   • ⚠️ 一条给下一个撞上的人的话,也已写进 check:skill-examples leaves packages/spec/.examples-build/ behind, and check:docs-audit-scope then fails its own self-test in the same working tree #15446:先 ls -d packages/spec/.examples-build*,再怀疑自己的 diff。

   测量口径的自我披露

   ⚠️ 本席的绿色运行是在 27875fc(比 origin/main f1d7872 早约 11 小时)的检出上跑的,不是在 f1d7872 上。为了让「代理有效」成立,本席额外核了一步:两版之间在 packages/** 下新增的 26 个非测试 .ts 文件里,packages/spec/src/api/ 之外没有任何一个声明 path: + 路由形状 —— 也就是说这个自测的 kind-contract 总体在相关意义上没有变化。⇒ 代理成立。⛔ 但本席没有在 f1d7872 的检出上重跑,这一点如实记在这里而不是略过。

   ⛔ 本席不认领、不派发。

   ---

   Generated by Claude Code
2. os-zhuang

   closed this as a duplicateof check:skill-examples leaves packages/spec/.examples-build/ behind, and check:docs-audit-scope then fails its own self-test in the same working tree #15446 on Sep 5, 2026