Repository navigation
Commit d2ca707
docs(gates): take the re-typed counts out of the docs and retire the two gates that only held them (#26511)
<!-- claude-projects-attribution: {"github_login":"os-steve"} -->
_Requested by **Steve** · [project
thread](https://claude.ai/code/project/chan_01FdL1XeUyvVNxLreh3F4Qi9?thread=cmsg_01FdL1XeUyvVNxLreh3F4Qi95YovdFSHTxz132KjPG4TAa)_
Fixes #26441
Part of #26431
Clause-②: no
Metadata-protocol: none
## 维护者速读
- 改了什么:文档里五处手抄的数字删掉了,句子改成不写数也成立的说法。lockstep「110 packages」和
quick-reference「(N of M schemas)」各自的门禁连同别名和 lint
步骤一起退役。overlay-whitelist 只删第 3 腿。docs-spec-enumerations
留着,因为它守的三处名单本身就是事实。route-ledger-census 也留着:实测有 3 行删掉后,只有它会红。
- 为什么改:#26441 要求删掉这些手抄数字,或者改成生成的;没有数字的句子不会漂移,只守这个数字的门禁也就可以退了。分诊行
6434325953 要求不削弱检查本身证明的东西,所以下面逐个写了真正的不变量由谁守,并演示了它对原缺陷仍会红。
- 风险与回滚:退掉的两个门禁只读文字,不读代码。真正的不变量(lockstep 成员、白名单完整性、命名空间名单)仍由
`check-changeset-fixed`、overlay 第 1 和第 2
腿、`check-docs-spec-enumerations` 守着。回滚就是 revert。
- 先看:`quick-reference.mdx` 的新导语、`metadata-lifecycle.mdx` 第 123
行、`check-docs-spec-enumerations.mjs` 的 `SECTIONS_HEADING`(数字变成可选),以及下面
route-ledger 的删行实测。
- 两分钟验证:`node scripts/check-overlay-whitelist-table.mjs
--self-test`、`node scripts/check-docs-spec-enumerations.mjs
--self-test`、`node scripts/check-changeset-fixed.mjs`,都是 exit 0。
- 需要你做的:Tier H(改了 `.github/workflows/lint.yml`),要
GOVERNED_APPROVERS(os-zhuang 或 hotlong)批准。
## What changes
| Holder | What the prose says now | Gate | Who holds the real invariant
|
|---|---|---|---|
| `check-lockstep-package-count` | "one `major` would promote every
published package"; "every package published from this repository
belongs to a single Changesets `fixed` group"; `publish-smoke-pack.mjs`
header: "enumerates the same names" | **retired** (script,
`check:lockstep-package-count`, lint step) | `check-changeset-fixed`
(membership of the `fixed` group against the public workspace, on PRs
from `validate-deps` and in both release lanes) |
| `check-quick-reference-counts` | the 13 headings read `## <Name>
Protocol`. The intro says each table is curated and points at the
generated [reference index](/docs/references) for the full set. The
"Categories Without a Section" table loses its `Pages` column |
**retired** (script, `check:quick-reference-counts`, lint step) | the
page states no count, so #6319 and #6530 have nothing left to drift.
What it still states is links: Check Documentation Links (lychee) and
`check-doc-anchors` hold those |
| `check-overlay-whitelist-table`, leg 3 | "The types in the ✅ row are
the **complete** `allowEnvironmentOverlay: true` set: every other type
in `DEFAULT_METADATA_TYPE_REGISTRY` is `false`." | **leg 3 removed**:
the prose-count reader, `parseCountToken`, `compareProse`, batteries
13a–13g, roster floor 19 → 12. Legs 1–2 untouched | leg 2 (every `true`
type has a row) and leg 1 (every row's ✅/❌ matches the registry).
Together they make the "complete" sentence true |
| `check-docs-spec-enumerations` | the glossary drops "15" from three
sentences and the `## The 15 Protocol Namespaces` heading | **kept**.
The lists it holds are facts, not counts, and cannot be derived into
hand-written prose. The required count floor is gone, and
`SECTIONS_HEADING` takes the heading with or without a number. The sweep
stays, so a count written back in anywhere is still held to the exports
map | itself |
| `check-route-ledger-census` | unchanged | **kept**, per the seat's
measure-first ruling (below) | itself |
**Route-ledger, measured before deciding.** On `c91544a4`, rows were
deleted from `ROUTE_LEDGER` (105 rows) and the three suites that read
the ledger were run, restoring the file after each run:
| Ablation | `runtime` route-ledger.conformance | `client`
client-url-conformance | `qa/dogfood` live-mount parity |
`check-route-ledger-census` |
|---|---|---|---|---|
| 26 contiguous rows (`/approvals/act` … `/actions/_activation`) | red
(whole domains lost) | — | — | red |
| 26 non-last rows, every domain keeps one | **6/6 green** | red (8 SDK
URLs) | — | red |
| 28 non-sdk non-last rows | **6/6 green** | **3/3 green** | red (26
mounts unledgered, 2 stale pins) | red |
| 3 rows: `GET /meta/types`, `POST /actions/global/:action`, `POST
/actions/_activation/:object/:action` | **6/6 green** | **3/3 green** |
**8/8 green** | **red** |
The last row is the #16758 shape: the rows are absorbed by another
ledger in the union, or they are `servedBy` specializations whose
pattern nothing registers. Nothing but the census sees them go, so it
stays. The real fix is a route-granularity reverse check in the runtime
suite, which is #17041's open question. It is reported to the seat as an
out-of-scope finding, not built here.
**Prose made false by the retirement, and only that:**
- the `PRIVATE_FIXED_MEMBERS` docblock in `check-changeset-fixed.mjs`,
which named the retired reader;
- the census header in `check-route-ledger-census.mjs`, which credited
its shape to the retired script;
- the overlay gate's header line about "all 27 types";
- the spec-enumerations lint comment, which said "16 … and the 15 of
those". The real numbers are 18 and 15.
Historical mentions of the retired scripts are left as they are: the
`docs/audits/*` census tables, the `scripts/ui-import/README.md` cutover
log, the #16325 list in `check-docs-spec-enumerations.mjs`'s header, and
a quoted principle in `packages/spec/scripts/check-llms-txt.ts`.
## Tests
- **Every guardian still reds on the defect, shown on this tree with the
change reverted after each run:**
- `check-changeset-fixed`: `@objectstack/client` removed from
`.changeset/config.json` `fixed[0]` → exit 1, `Public packages missing
from "fixed" … @objectstack/client`.
- Overlay leg 2: `action` flipped to `allowEnvironmentOverlay: true` in
the registry → exit 1, `[missing-row] \`action\` is
\`allowEnvironmentOverlay: true\` … and is named nowhere in the table`.
- `check-docs-spec-enumerations`: `## The 14 Protocol Namespaces`
written back into the glossary → exit 1, `[count-drift] the glossary
claims 14 protocol namespace(s); the exports map publishes 15`.
- `check-route-ledger-census`: the 3-row ablation above → exit 1, every
other suite green.
- **Self-tests.**
- `check-overlay-whitelist-table --self-test`: the 12 remaining
batteries hold, and the positive control still reproduces the 4 known
divergences.
- `check-docs-spec-enumerations --self-test`: 79 cases over 10
batteries. Two new cases in battery 7: a count-free glossary is green
with its sections still read. The drain-refusal case in battery 8 goes,
since the floor it tested is gone.
- **Card acceptance.**
- `grep -rnE "110 (published )?packages|\*\*110\*\*|of [0-9]+
schemas?\)|[0-9]+ types in .DEFAULT_METADATA|Those five are|[0-9]+
protocol namespaces|The [0-9]+ (Protocol )?[Nn]amespaces" content/docs`
(outside `releases/`) prints nothing.
- `check:lockstep-package-count` and `check:quick-reference-counts` are
gone from `package.json` and `lint.yml`. The overlay alias stays,
because only its leg went.
- `check:doc-anchors` exit 0 (598 fragments). `check:docs-audit-scope`
exit 0.
- **Gate run, standard order.**
- `dispatch-gates --commands` derived 105 commands on `5f82434c`, and
all 105 exit 0. `dispatch-gates --ran` reports 0 NOT-MEASURED and 0
UNRUN.
- `@objectstack/spec`'s `check:docs` and `check:skill-examples` first
refused on an unbuilt `json-schema/` and `dist/` (exit 1 and 3,
prerequisites, not findings). Both exit 0 after `pnpm --filter
@objectstack/spec build`.
- After merging `main` (`fffcf347`) the derivation is the same 105, and
the gates that read `package.json` (`check-self-test-wired`,
`check:aggregator-roster`, `check:ci-filter-parity`,
`check-self-test-workflow-commands`, `check:select-gate-families`) exit
0 again.
<details><summary>Gate log (105 commands: exit code, seconds,
command)</summary>
```
0 0s node scripts/check-adr-links.mjs
0 0s node scripts/check-adr-links.mjs --self-test
0 3s node scripts/check-closing-keyword-parity.mjs
0 5s node scripts/check-closing-keyword-parity.mjs --self-test
0 184s node scripts/check-comment-mask-corpus.mjs
0 0s node scripts/check-declaration-mirrors.mjs
0 0s node scripts/check-declaration-mirrors.mjs --self-test
0 0s node scripts/check-doc-route-spelling.mjs --advisory
0 0s node scripts/check-doc-route-spelling.mjs --self-test
0 0s node scripts/check-docs-section-name.mjs
0 0s node scripts/check-docs-section-name.mjs --self-test
0 1s node scripts/check-dts-emitted.mjs --self-test
0 0s node scripts/check-merged-branch-reaper-outcome.mjs
0 0s node scripts/check-merged-branch-reaper-outcome.mjs --self-test
0 0s node scripts/check-osv-exemptions.mjs
0 0s node scripts/check-osv-exemptions.mjs --self-test
0 0s node scripts/check-section-landing-index.mjs
0 0s node scripts/check-section-landing-index.mjs --self-test
0 2s node scripts/check-self-test-wired.mjs
0 5s node scripts/check-self-test-wired.mjs --self-test
0 115s node scripts/check-self-test-workflow-commands.mjs
0 4s node scripts/check-self-test-workflow-commands.mjs --self-test
0 0s node scripts/check-step-collectors.mjs
0 4s node scripts/check-step-collectors.mjs --self-test
0 2s node scripts/check-whole-set-label-write.mjs
0 0s node scripts/check-whole-set-label-write.mjs --self-test
0 1s node scripts/ci/assert-turbo-remote-cache.mjs --self-test
0 0s node scripts/ci/plan-test-core-shards.mjs --self-test
0 0s node scripts/ci/prune-turbo-cache.mjs --self-test
0 0s node scripts/ci/scheduled-full-run.mjs --self-test
0 1s node scripts/docs-audit/check-drift-comment.mjs
0 0s node scripts/osv-base-relative.mjs --self-test
0 28s node scripts/pm/bare-root-worklist.mjs --self-test
0 0s node scripts/pm/ci-failure.mjs --self-test
0 8s pnpm --filter @objectstack/lint run check:doc-formula-expressions
0 3s pnpm --filter @objectstack/lint run check:doc-security-posture
0 2s(rerun after spec build) pnpm --filter @objectstack/spec run check:docs
0 2s pnpm --filter @objectstack/spec run check:empty-state
0 3s pnpm --filter @objectstack/spec run check:liveness
0 4s(rerun after spec build) pnpm --filter @objectstack/spec run check:skill-examples
0 4s pnpm --filter @objectstack/spec run check:strictness-ledger
0 4s pnpm --filter @objectstack/spec run check:variant-docs
0 6s pnpm --filter @objectstack/spec run check:yaml-examples
0 3s pnpm check:agent-test-spelling
0 2s pnpm check:aggregator-roster
0 2s pnpm check:bash32-floor
0 1s pnpm check:changeset-fixed
0 2s pnpm check:ci-filter-parity
0 17s pnpm check:cli-command-ids
0 4s pnpm check:closed-ceremony-text
0 1s pnpm check:corpus-claim-drift
0 35s pnpm check:cross-package-test-inputs
0 39s pnpm check:declared-population-live
0 2s pnpm check:doc-anchors
0 8s pnpm check:doc-authoring
0 1s pnpm check:doc-frontmatter
0 5s pnpm check:docs-audit-scope
0 1s pnpm check:docs-redirects
0 1s pnpm check:docs-single-h1
0 2s pnpm check:docs-spec-enumerations
0 1s pnpm check:docs-transcript-drift
0 5s pnpm check:driver-memory-census
0 1s pnpm check:dts-closure
0 23s pnpm check:dual-build-cjs-loads
0 38s pnpm check:entry-guard
0 2s pnpm check:gitlink-declared
0 2s pnpm check:lean-entry-closure
0 1s pnpm check:manifest-repository-directory
0 23s pnpm check:merge-driver
0 1s pnpm check:node-version
0 5s pnpm check:nul-bytes
0 1s pnpm check:overlay-whitelist-table
0 2s pnpm check:override-consistency
0 3s pnpm check:parse-guard
0 387s pnpm check:pm-dispatch-gates
0 6s pnpm check:pm-expected-skips
0 9s pnpm check:pm-governed-merges
0 1s pnpm check:pm-post-stamped
0 4s pnpm check:pm-record-recognisers
0 1s pnpm check:pnpm-acquisition
0 3s pnpm check:pnpm-filter-targets
0 6s pnpm check:pnpm-flag-spellings
0 0s pnpm check:publish-smoke-pin
0 2s pnpm check:published-readme-links
0 4s pnpm check:ratchet-remedy-authority
0 1s pnpm check:react-page-adapter-contract
0 24s pnpm check:refd-timer-probe
0 4s pnpm check:required-contexts
0 2s pnpm check:role-word
0 1s pnpm check:route-ledger-census
0 7s pnpm check:scripts-symbol-anchors
0 5s pnpm check:select-gate-families
0 3s pnpm check:shard-attestation
0 12s pnpm check:skill-identifier-liveness
0 1s pnpm check:sourcemap-no-sources-content
0 2s pnpm check:stall-guard-budget
0 3s pnpm check:stall-guard-headroom
0 1s pnpm check:turbo-task-graph
0 5s pnpm check:type-check-coverage
0 387s pnpm check:type-check-debt
0 21s pnpm check:vendor-export-contract-resolve
0 11s pnpm check:vendor-version-stamps
0 7s pnpm check:watch-hint-literal
0 1s pnpm check:workflow-status-functions
0 1s pnpm check:workflow-step-name-quoting
```
</details>
## Acceptance notes
- Two of the five `check:*` keys stay, both inside the dispatch's own
exception. `check-docs-spec-enumerations` holds lists that are facts,
and `check-route-ledger-census` holds a number that is the guard itself,
as the ablation shows. Both decisions were put to the seat before the
work, and the seat ruled the second one measure-first.
- Size: +80/−1822, of which 1356 lines are the two deleted scripts. The
hand-edited diff is about 550 lines, so it stays one PR rather than a
chain.
- `ci.yml` is not touched, and no `ui/` path is touched. Docs and repo
tooling only, so `skip-changeset`.
## Verification
```sh
node scripts/check-overlay-whitelist-table.mjs --self-test && node scripts/check-overlay-whitelist-table.mjs
node scripts/check-docs-spec-enumerations.mjs --self-test && node scripts/check-docs-spec-enumerations.mjs
node scripts/check-changeset-fixed.mjs --self-test && node scripts/check-changeset-fixed.mjs
node scripts/check-route-ledger-census.mjs
```
Tier H (`.github/workflows/lint.yml`): draft until a GOVERNED_APPROVERS
approval (os-zhuang, hotlong).
---
_Generated by [Claude
Code](https://claude.ai/code/session_01ADHkmQq9EYQdTQwmRutQTS)_
🤖 Generated with [Claude Code](https://claude.com/claude-code)
https://claude.ai/code/session_01ADHkmQq9EYQdTQwmRutQTS
Co-authored-by: Claude <noreply@anthropic.com>1 parent 3fcafcd commit d2ca707
13 files changed
Lines changed: 80 additions & 1822 deletions
File tree
- .github/workflows
- content/docs
- concepts
- getting-started
- protocol
- scripts
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
2265 | 2265 | | |
2266 | 2266 | | |
2267 | 2267 | | |
2268 | | - | |
2269 | | - | |
2270 | | - | |
2271 | | - | |
2272 | | - | |
2273 | | - | |
2274 | | - | |
2275 | | - | |
2276 | | - | |
2277 | | - | |
2278 | | - | |
2279 | | - | |
2280 | | - | |
2281 | | - | |
2282 | | - | |
2283 | | - | |
2284 | | - | |
2285 | 2268 | | |
2286 | 2269 | | |
2287 | 2270 | | |
| |||
2291 | 2274 | | |
2292 | 2275 | | |
2293 | 2276 | | |
2294 | | - | |
2295 | | - | |
| 2277 | + | |
| 2278 | + | |
2296 | 2279 | | |
2297 | 2280 | | |
2298 | 2281 | | |
| |||
2998 | 2981 | | |
2999 | 2982 | | |
3000 | 2983 | | |
3001 | | - | |
3002 | | - | |
3003 | | - | |
3004 | | - | |
3005 | | - | |
3006 | | - | |
3007 | | - | |
3008 | | - | |
3009 | | - | |
3010 | | - | |
3011 | | - | |
3012 | | - | |
3013 | | - | |
3014 | | - | |
3015 | | - | |
3016 | | - | |
3017 | 2984 | | |
3018 | 2985 | | |
3019 | 2986 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
120 | 120 | | |
121 | 121 | | |
122 | 122 | | |
123 | | - | |
| 123 | + | |
124 | 124 | | |
125 | 125 | | |
126 | 126 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
9 | 9 | | |
10 | 10 | | |
11 | 11 | | |
12 | | - | |
| 12 | + | |
13 | 13 | | |
14 | 14 | | |
15 | | - | |
| 15 | + | |
16 | 16 | | |
17 | 17 | | |
18 | 18 | | |
19 | 19 | | |
20 | 20 | | |
21 | | - | |
| 21 | + | |
22 | 22 | | |
23 | 23 | | |
24 | 24 | | |
| |||
30 | 30 | | |
31 | 31 | | |
32 | 32 | | |
33 | | - | |
| 33 | + | |
34 | 34 | | |
35 | 35 | | |
36 | 36 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
11 | 11 | | |
12 | 12 | | |
13 | 13 | | |
14 | | - | |
15 | | - | |
16 | | - | |
17 | | - | |
18 | | - | |
19 | | - | |
20 | | - | |
21 | | - | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
22 | 19 | | |
23 | 20 | | |
24 | 21 | | |
25 | | - | |
| 22 | + | |
26 | 23 | | |
27 | 24 | | |
28 | 25 | | |
| |||
44 | 41 | | |
45 | 42 | | |
46 | 43 | | |
47 | | - | |
| 44 | + | |
48 | 45 | | |
49 | 46 | | |
50 | 47 | | |
| |||
61 | 58 | | |
62 | 59 | | |
63 | 60 | | |
64 | | - | |
| 61 | + | |
65 | 62 | | |
66 | 63 | | |
67 | 64 | | |
| |||
85 | 82 | | |
86 | 83 | | |
87 | 84 | | |
88 | | - | |
| 85 | + | |
89 | 86 | | |
90 | 87 | | |
91 | 88 | | |
| |||
108 | 105 | | |
109 | 106 | | |
110 | 107 | | |
111 | | - | |
| 108 | + | |
112 | 109 | | |
113 | 110 | | |
114 | 111 | | |
| |||
126 | 123 | | |
127 | 124 | | |
128 | 125 | | |
129 | | - | |
| 126 | + | |
130 | 127 | | |
131 | 128 | | |
132 | 129 | | |
| |||
150 | 147 | | |
151 | 148 | | |
152 | 149 | | |
153 | | - | |
| 150 | + | |
154 | 151 | | |
155 | 152 | | |
156 | 153 | | |
| |||
160 | 157 | | |
161 | 158 | | |
162 | 159 | | |
163 | | - | |
| 160 | + | |
164 | 161 | | |
165 | 162 | | |
166 | 163 | | |
| |||
170 | 167 | | |
171 | 168 | | |
172 | 169 | | |
173 | | - | |
| 170 | + | |
174 | 171 | | |
175 | 172 | | |
176 | 173 | | |
| |||
181 | 178 | | |
182 | 179 | | |
183 | 180 | | |
184 | | - | |
| 181 | + | |
185 | 182 | | |
186 | 183 | | |
187 | 184 | | |
| |||
194 | 191 | | |
195 | 192 | | |
196 | 193 | | |
197 | | - | |
| 194 | + | |
198 | 195 | | |
199 | 196 | | |
200 | 197 | | |
| |||
207 | 204 | | |
208 | 205 | | |
209 | 206 | | |
210 | | - | |
| 207 | + | |
211 | 208 | | |
212 | 209 | | |
213 | 210 | | |
| |||
219 | 216 | | |
220 | 217 | | |
221 | 218 | | |
222 | | - | |
| 219 | + | |
223 | 220 | | |
224 | 221 | | |
225 | 222 | | |
| |||
229 | 226 | | |
230 | 227 | | |
231 | 228 | | |
232 | | - | |
| 229 | + | |
233 | 230 | | |
234 | | - | |
235 | | - | |
| 231 | + | |
236 | 232 | | |
237 | | - | |
238 | | - | |
239 | | - | |
| 233 | + | |
| 234 | + | |
| 235 | + | |
240 | 236 | | |
241 | 237 | | |
242 | 238 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
116 | 116 | | |
117 | 117 | | |
118 | 118 | | |
119 | | - | |
| 119 | + | |
120 | 120 | | |
121 | 121 | | |
122 | 122 | | |
| |||
196 | 196 | | |
197 | 197 | | |
198 | 198 | | |
199 | | - | |
| 199 | + | |
200 | 200 | | |
201 | 201 | | |
202 | 202 | | |
| |||
0 commit comments