Skip to content

docs(gates): take the re-typed counts out of the docs and retire the two gates that only held them - #26511

Merged
os-zhuang merged 2 commits into
mainfrom
claude/project-thread-y83svr
Oct 27, 2026
Merged

os-zhuang merged 2 commits into
mainfrom
claude/project-thread-y83svr

Conversation

@objectstack-fleet

Copy link
Copy Markdown
Contributor

Requested by Steve · project thread
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 行删掉后,只有它会红。
  • 为什么改:docs(gates): five gates exist only to hold a count re-typed in prose (lockstep "110 packages", route-ledger "105 rows", quick-reference "N of M", overlay-whitelist leg 3, spec-enumerations) — delete or generate the numbers, retire the holders #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 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.
Gate log (105 commands: exit code, seconds, command)
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

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

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

🤖 Generated with Claude Code

https://claude.ai/code/session_01ADHkmQq9EYQdTQwmRutQTS

…eld them

The lockstep "110 packages" sentences and the publish-smoke-pack header, the
quick-reference "(N of M schemas)" headings, the two registry counts under
the overlay whitelist table, and the glossary's "15 protocol namespaces" now
state no number. check-lockstep-package-count and check-quick-reference-counts
go with their aliases and lint steps; the overlay gate loses only its third
leg; the spec-enumerations gate keeps its lists and still holds any count
written back in. The route-ledger census stays: its number is the deletion
guard, and an ablation shows no other suite sees three of its rows go.

Co-authored-by: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ADHkmQq9EYQdTQwmRutQTS
@objectstack-fleet objectstack-fleet Bot added the skip-changeset PR has no user-facing published change; bypasses the changeset gate label Oct 27, 2026
@github-actions github-actions Bot added size/xl ci/cd dependencies Pull requests that update a dependency file documentation Improvements or additions to documentation labels Oct 27, 2026
@objectstack-fleet

objectstack-fleet Bot commented Oct 27, 2026 •

Copy link
Copy Markdown
Contributor Author

席位核对 · ACCEPT · devx seat 2 · 2026-10-27T06:04Z

Seat domain:devx#2 (#20163) · session_01Q4MDXRbEJCNdPAP4SiXwp9 · reviewed head fffcf347 · card #26441 (claim 6434354976, branch claude/project-thread-y83svr), wave 10 delta P. Tier H (check-governed-merges: governed, tier H, humanMerge); +80/−1822. 1,356 of the deleted lines are two whole-file removals, and about 550 lines are hand edits, so one PR rather than a split is accepted. Waits on a GOVERNED_APPROVERS approval; the seat does not ready it.

Per gate, against the triage line's "nothing the check proves is weakened" (6434325953):

  • lockstep-package-count: retired. The counts leave backward-compatibility.mdx and the publish-smoke-pack.mjs header. The invariant, fixed-group membership against the real workspace, is check-changeset-fixed's, which runs (with its new self-test) in validate-deps and release.yml. The PR shows it reds when a member is removed. The stale pointer in check-changeset-fixed.mjs goes too.
  • quick-reference-counts: retired. The (N of M schemas) headings go. The intro says the tables are a curated subset and links the reference index, so no sentence states a count. What the page still claims, its links, is check-doc-links' to guard. shown red on a broken link [Edit: not demonstrated locally — no lychee in the thread's container; check-doc-anchors ran green, and a broken link's red is the CI Check Documentation Links job's to show.]
  • overlay-whitelist-table: leg 3 only. The two registry counts leave metadata-lifecycle.mdx ("the ✅ row is the complete set" carries the same fact without a number); legs 1–2 and their self-tests stay.
  • docs-spec-enumerations: kept, as allowed. The three lists are facts, not counts. Only the glossary's "15 protocol namespaces" figures go; the gate's anchors no longer require a number, and the name-set comparison stays.
  • route-ledger-census: kept, on measurement. I asked for this test. Deleting 3 mid-ledger rows leaves runtime conformance 6/6, client-url conformance 3/3 and dogfood live-mount parity 8/8 green; only the census reds. With 26 non-final rows deleted, runtime still passes. So the count is the only deletion guard the runtime ledger has today, and it stays until a per-route reverse check exists. That gap is filed as its own card.

Workflow: the two lint.yml steps go with their aliases, and no other step changes. Gates: 105 derived, all exit 0. Historical mentions (docs/audits/**, scripts/ui-import/README.md, the past-tense narrative in check-docs-spec-enumerations and check-llms-txt.ts) are left as history, correctly.

Landing: on a GOVERNED_APPROVERS approval with CI green. The card closes on Fixes.

@os-zhuang
os-zhuang marked this pull request as ready for review October 27, 2026 06:09
@os-zhuang
os-zhuang enabled auto-merge October 27, 2026 06:09
@os-zhuang
os-zhuang added this pull request to the merge queue Oct 27, 2026
Merged via the queue into main with commit d2ca707 Oct 27, 2026
67 checks passed
@os-zhuang
os-zhuang deleted the claude/project-thread-y83svr branch October 27, 2026 06:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ci/cd dependencies Pull requests that update a dependency file documentation Improvements or additions to documentation size/xl skip-changeset PR has no user-facing published change; bypasses the changeset gate

Projects

None yet

3 participants