Skip to content

Commit 1708115

Browse files
docs(scripts): two comments stop describing the pre-#22927 system-context census (#26611) (#26899)
<!-- claude-projects-attribution: {"github_login":"os-warren"} --> _Requested by **Warren** · [project thread](https://claude.ai/code/project/chan_01U5RdnAAmkSQmZbqh6FtqZ8?thread=cmsg_01U5RdnAAmkSQmZbqh6FtqZ83E4C5pqznRerdLyMs7ArET)_ Fixes #26611 ## What changes Two code comments, no code. 1. `scripts/doc-line-anchors.mjs`, header section "Today, since #15921": it said the `line-anchors` comparator is "selected by that page's `mixed` field" and that the census `--fix` "regenerates only the page's declared counts". It now says the comparator is the one a `REGEN_ARTIFACTS` row *would* select with `mixed: 'line-anchors'`, that no row carries `mixed` since the page left the driver at #22927, and that `check-system-context-census.mjs --fix` is retired (exit 2, names `--write`, which rebuilds the #26442 site register and touches no anchor). 2. `scripts/regen-artifacts.mjs`, `NOT_DRIVER_MANAGED` entry `docs/audits/**`: it called the strictness counts "The ONE exception". It now names both generated-whole files under `docs/audits/`: the strictness ledger's `.counts/` shards (routed, the row above; the old text's `.counts.md` spelling predates their sharding) and `2026-08-tenant-audit-write-call-sites.counts.md` (not routed), with the reason. ## Why Item 2 asked for a decision: route the tenant-audit `.counts.md` like the strictness one, or record why not. **Not routed, recorded.** A `REGEN_ARTIFACTS` row needs a `gen:`/`check:` pair in the manifest it names as owner, and no manifest declares one for this census (it runs straight from `lint.yml`, step `tenant-audit-census-matches-the-tree`); the driver runs only in a local merge, never in GitHub's server-side merge or the queue's; and `check-tenant-audit-census.mjs` already holds the file to its `--write` output on every PR, so a clean-and-wrong text merge is red, never silent. That is the reasoning the file's own generated header (`renderCountsFile` in `scripts/tenant-audit-census.mjs`) already prints; the ledger entry now agrees with it instead of contradicting it. Routing would be a manifest + `.gitattributes` + row change with the regen gate in the PR, which is a separate, larger card if anyone wants it. ## Verification - `node scripts/pm/dispatch-gates.mjs --commands scripts/doc-line-anchors.mjs scripts/regen-artifacts.mjs` derived 35 commands. 31 exit 0, plus `node scripts/git-merge-regen.mjs --self-test` (exit 0) and `node --check` on both files (exit 0). - 4 derived gates exit 3 (PREREQUISITE NOT MET, no `dist/` in this container): `check:dts-closure`, `check:dual-build-cjs-loads`, `check:lean-entry-closure`, `check:sourcemap-no-sources-content`. They read built package output, which comment edits in two root `scripts/` files cannot change; CI runs them after its build. - `skip-changeset`: both files are root tooling and publish from no released package. Clause-②: no Metadata-protocol: none ## Human Minimum - [x] 1. Schemas start as Zod; `packages/spec` holds no runtime logic. (not touched) - [x] 2. Every name I added uses the casing for its kind. (no names added) - [ ] 3. No formatter ran; `pnpm lint` passes. (no formatter ran; `pnpm lint` not run locally, CI's lint job is the verdict) - [x] 4. One issue, one branch off an up-to-date `main`, one pull request. - [x] 5. A change that publishes carries a changeset, and both declaration lines are filled in here and in the changeset. (publishes nothing: `skip-changeset`) - [x] 6. `packages/spec` touched: its generated artifacts are regenerated and committed. (not touched) - [x] 7. No hand edits to `content/docs/references/`, `packages/*/CHANGELOG.md` or `content/docs/releases/`. - [x] 8. Title, body and comments are in English. - [x] The *Before Submitting* list in CONTRIBUTING.md is done. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01JQwxbXz4CLkqrp9ANVLuPH Co-authored-by: Claude <noreply@anthropic.com>
1 parent 247a088 commit 1708115

2 files changed

Lines changed: 23 additions & 14 deletions

File tree

‎scripts/doc-line-anchors.mjs‎

Lines changed: 11 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -30,15 +30,17 @@
3030
* `blankAnchorLineNumbers(page) === page`.
3131
*
3232
* The one in-tree importer is `scripts/git-merge-regen.mjs`: its `'line-anchors'`
33-
* comparator is `blankAnchorLineNumbers`, selected by that page's `mixed` field in
34-
* `scripts/regen-artifacts.mjs`. The identity is the intended answer there, not a
35-
* broken one. The driver proves a deferral lossless only when the incoming side
36-
* equals the ancestor or ours byte for byte, so every real edit to the page takes
37-
* the text-merge branch, or conflicts loudly, by design -- and the field stays,
38-
* because it is what sends the page through that check at all (that row's comment
39-
* carries the measurement). The account of `--fix` in `blankAnchorLineNumbers`'s
40-
* docblock below is the pre-#15921 one: the census `--fix` no longer touches
41-
* anchors, and regenerates only the page's declared counts.
33+
* comparator is `blankAnchorLineNumbers`, the one a `REGEN_ARTIFACTS` row would
34+
* select with `mixed: 'line-anchors'` in `scripts/regen-artifacts.mjs`. No row
35+
* carries `mixed` today: that page was the one that did, and it left the driver at
36+
* #22927, when its census totals came off it. The comparator is kept for the next
37+
* `file:line` mixed artifact (its docblock in `git-merge-regen.mjs` says so), and
38+
* the driver's mixed-row self-test reports nothing to prove while no row names it.
39+
* The account of `--fix` in `blankAnchorLineNumbers`'s docblock below is the
40+
* pre-#15921 one, and that flag is now retired outright:
41+
* `check-system-context-census.mjs --fix` refuses with exit 2 and names `--write`,
42+
* the one writer, which rebuilds the page's site register (#26442) and touches no
43+
* anchor.
4244
*
4345
* ## The three anchor shapes, all of which were real on that page
4446
*

‎scripts/regen-artifacts.mjs‎

Lines changed: 12 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -866,11 +866,18 @@ export const NOT_DRIVER_MANAGED = Object.freeze([
866866
{
867867
path: 'docs/audits/**',
868868
why:
869-
'hand-written audit ledgers — Class verdicts, evidence, findings logs. The ONE exception is '
870-
+ 'the strictness ledger\'s `.counts.md`, declared above: #5107 split the ledger\'s numbers out '
871-
+ 'precisely so the prose could keep text-merging (it always merged cleanly) while the numbers '
872-
+ 'stopped (they merged clean and WRONG). Regenerating a ledger would discard evidence, which is '
873-
+ 'the opposite trade — so this exclusion covers the prose and must stay.',
869+
'hand-written audit ledgers — Class verdicts, evidence, findings logs. Two files here are '
870+
+ 'generated whole instead. The strictness ledger\'s `.counts/` shards are the ROUTED one, '
871+
+ 'declared above: #5107 split the ledger\'s numbers out precisely so the prose could keep '
872+
+ 'text-merging (it always merged cleanly) while the numbers stopped (they merged clean and '
873+
+ 'WRONG). `2026-08-tenant-audit-write-call-sites.counts.md` (`node '
874+
+ 'scripts/tenant-audit-census.mjs --write`) is NOT routed: a row needs a `gen:`/`check:` pair '
875+
+ 'in the manifest it names as owner, and no manifest declares one for that census, which runs '
876+
+ 'straight from the lint workflow; the driver runs only in a local merge anyway, and '
877+
+ '`check-tenant-audit-census.mjs` holds the file to its `--write` output on every PR, so a '
878+
+ 'clean-and-wrong text merge is red, never silent (the file\'s own header says the same). '
879+
+ 'Regenerating a ledger would discard evidence, which is the opposite trade — so this '
880+
+ 'exclusion covers the prose and must stay.',
874881
},
875882
// ── the objectui tree under ui/ (objectstack#25677) ──────────────────────────
876883
{

0 commit comments

Comments
 (0)