Repository navigation
Commit 5d2935a
docs(devpath): merge-driver comments say system-context.mdx has a generated register again, and why neither census page is routed (#26610)
<!-- claude-projects-attribution: {"github_login":"os-warren"} -->
_Requested by **Warren** · [project
thread](https://claude.ai/code/project/chan_01U5RdnAAmkSQmZbqh6FtqZ8?thread=cmsg_01U5RdnAAmkSQmZbqh6FtqZ8FiD8VYiNjD9zPG48Gh7MbM)_
Fixes #26535
Clause-②: no
Metadata-protocol: none
## 维护者速读
-
改了什么:只改注释。`.gitattributes`、`scripts/regen-artifacts.mjs`、`scripts/git-merge-regen.mjs`
里说 `system-context.mdx`「没有生成内容」「`--fix` 会改 `file:line`
锚点」的几段注释,改成现在的事实:这页自 #26442 起有一个生成区(site register,由
`check-system-context-census.mjs --write` 重建),`tenant-audit-census.mdx`
也有一个生成区,两页都不走合并驱动,原因写进 `NOT_DRIVER_MANAGED` 那一条。
- 为什么改:#26522 让这页重新有了生成区,但三处注释还说它是纯手写文字,下一个读注释的人会据此做错判断(比如以为合并后不用跑
`--write`)。卡片还要求在同一个 PR 里决定这两页要不要交给合并驱动:结论是不要,理由已写进代码注释。
- 风险与回滚:零行为变化,没有改任何路由、脚本逻辑或发布内容;`git check-attr merge` 对两页仍答
`unspecified`。回滚即 revert。
- 先看:`scripts/regen-artifacts.mjs` 中 `content/docs/permissions/**` 条目的
`why`(不路由的四条理由);其次 `.gitattributes` 第 97 行起的那段;最后
`scripts/git-merge-regen.mjs` 的 `MIXED_COMPARATORS` 注释。
- 两分钟验证:`git check-attr merge
content/docs/permissions/system-context.mdx
content/docs/permissions/tenant-audit-census.mdx`,预期两行都是 `merge:
unspecified`(路由没变)。
- 需要你做的:无,席位落地。
## What changes
Comments only, in three files. No routing, no code path and no published
file changes.
1. **`.gitattributes` (the block from L97):** no longer says "nothing on
it is generated" / "It text-merges like its prose neighbours now". It
now tells the history through #22927 (which removed this row and
`gen:system-context-census`), then says #26442 gave the page a generated
site register again (rebuilt by `node
scripts/check-system-context-census.mjs --write`). It also says the page
stays unrouted, like `tenant-audit-census.mdx`, and that each page's
gate catches a merge that leaves its region wrong.
2. **`scripts/regen-artifacts.mjs`, the `NOT_DRIVER_MANAGED`
`content/docs/permissions/**` entry:** the `why` no longer calls every
page in the directory hand-written prose. It names the two MIXED pages
and their `--write` commands, and records the routing decision with its
reasons (below). Its last sentence used to say "Should a generated page
arrive here, route that FILE", which the two unrouted mixed pages
contradicted. It now says "a page generated WHOLE". The same file also
had two passages that repeated the stale claim, and the new entry would
have contradicted them: the `mixed` header paragraph ("its last
generated half") and the retired-row comment ("Nothing on it is
generated"). Both now point to the entry.
3. **`scripts/git-merge-regen.mjs` `MIXED_COMPARATORS`:** no longer says
`check-system-context-census.mjs --fix` rewrites `file:line` numbers.
That flag is retired: it refuses with exit 2 and names `--write`
(`scripts/check-system-context-census.mjs` header, section "`--fix` is
retired"). The comment now says the comparator was written for that
page's old line anchors, is the identity on the page today, and is
carried by no row. It also says the marker-region register is something
this comparator does not blank. In the same file, `deferralIsLossless`'s
case 1 said "numbers `--fix` will re-derive" and "24 of the last 25 main
commits" in the present tense. It now says the row's `gen:` re-derives
the half, and gives the 24-of-25 figure as the measurement taken back
then.
### Bounded in-place fix, declared
The two extra passages in `scripts/regen-artifacts.mjs` and the
`deferralIsLossless` sentence in `scripts/git-merge-regen.mjs` are
outside the three locations the card names. All three are in files the
claim already covers, have the same defect (a comment saying the page
has no generated half, or that `--fix` re-derives it), are comment-only,
and are read by the same gates. Leaving them would have made each file
contradict itself.
## Why — the routing decision: record why not (no routing)
Card's Wanted: "Decide in the same PR whether `system-context.mdx` (and
`tenant-audit-census.mdx`) should be routed through the regen driver now
that part of each is generated, or record why not in item 2's reason."
**Decision: not routed. The reason is recorded in item 2's `why`.**
Evidence, measured on `origin/main` 9dc8fba:
- **A whole-side deferral would drop prose.** Both pages are
hand-written prose around one region between BEGIN/END GENERATED
markers. `system-context.mdx` has its register at L517–654 of 661 lines.
`tenant-audit-census.mdx` has its region at L230–319 of 319 lines. An
unconditional `merge=os-regen` row keeps OURS whole, which is the exact
failure #14064 measured on this page.
- **The `mixed` limb would buy nothing.** The only comparator is
`line-anchors` (`blankAnchorLineNumbers`). Measured on both pages:
`extractLineAnchors(page).length === 0` and
`blankAnchorLineNumbers(page) === page`, so it is the identity. With it,
`deferralIsLossless` defers only when THEIRS is byte-equal to the
ancestor or to OURS. Every real edit, register-only ones included, would
take `textMergeInPlace`, which is the same text merge git does today,
plus a pre-commit regeneration debt. A comparator that blanks a marker
region does not exist.
- **No `gen:` script exists.** A `REGEN_ARTIFACTS` row needs a `gen:`
and `check:` pair in its owner manifest, and the self-test verifies the
names. Root `package.json` has `check:system-context-census` and no
`gen:` for either page. #22927 removed `gen:system-context-census`, and
the tenant-audit census has no manifest script at all; its gate runs
straight from `lint.yml`. Routing would mean adding scripts, which goes
beyond this card's comment-only scope.
- **The driver is local.** GitHub's server-side merge and the merge
queue run no custom driver (AGENTS.md, Multi-agent discipline §11), so
routing would not change the merges where a conflict blocks a PR.
- **The page does not lose merges unrouted.** Git text-merges both
sides' prose. The register has one line per symbol and no total, so two
read-adding branches change different lines. A merge that leaves either
region wrong turns its gate red: `check-system-context-census.mjs`
section F holds the register byte-equal to `--write`'s output, and
`check-tenant-audit-census.mjs` check A does the same for its region,
masking only the dated corpus-scale rows. Both gates run in
`lint-repo-tooling`, behind the required `Lint & Repo Gates`, on
`pull_request` and `merge_group`.
`scripts/check-system-context-census.mjs`'s own header already says the
page "is still not `merge=os-regen` routed: like
`tenant-audit-census.mdx`, it text-merges".
Routing would change merge behaviour beyond this card's comment-only
path. Nothing measured here argues for it, so it is not proposed.
## Tests
No behaviour changed, so no test was added and no ablation applies. The
edited scripts' own suites: `pnpm check:merge-driver` (`git-env`,
`git-merge-regen` and `check-regen-pending` `--self-test`; the
`git-merge-regen` self-test reconciles `scripts/regen-artifacts.mjs`)
ran with exit 0. `node --check` passes on both scripts. The two
`packages/spec` test files that name these scripts mention them only in
comments, so they are not owed.
Census gates, run on the base tree and unchanged by this diff: `node
scripts/check-system-context-census.mjs` exit 0, ending "the generated
register (132 symbol(s)) matches the tree." `node
scripts/check-tenant-audit-census.mjs` exit 0.
## Verification
Head `07bd64c8`. Local subset from `node scripts/pm/dispatch-gates.mjs
--commands --repo objectstack-ai/objectstack` (38 families), reconciled
with `--ran`: "38 derived famil(ies) accounted for — 34 run, 4
NOT-MEASURED".
<details><summary>Local gate readings (exit codes captured before any
pipe)</summary>
- 34 families exit 0. Among them: `check:merge-driver`,
`check:nul-bytes`, `check:entry-guard`, `check:scripts-symbol-anchors`,
`check:ratchet-remedy-authority`, `check:cross-package-test-inputs`,
`check:ci-filter-parity`, `check-self-test-wired` (scan and
`--self-test`), `check-declaration-mirrors` (scan and `--self-test`),
`check-comment-mask-corpus`, and `check:pm-dispatch-gates`. That last
one ran detached as its header requires and ended "dispatch-gates
self-test (fast tier): 1935 cases pass". Its exit code came from the
log's pass line, with no ELIFECYCLE line.
- NOT MEASURED (exit 3, PREREQUISITE NOT MET: no `dist/` without a full
`pnpm build`): `check:dts-closure`, `check:dual-build-cjs-loads`,
`check:lean-entry-closure`, `check:sourcemap-no-sources-content`. This
is a declared narrowing. These gates read built `dist/` output, which a
comment edit in root `scripts/` and `.gitattributes` cannot change. CI's
`Lint & Repo Gates` runs them on a fresh build.
</details>
`pnpm lint` and every family outside the derived list are left to CI.
## Acceptance notes
- `scripts/doc-line-anchors.mjs`'s header ("Today, since #15921") still
says the `'line-anchors'` comparator is "selected by that page's `mixed`
field" and that the census `--fix` "regenerates only the page's declared
counts". Both stopped being true at #22927. This is the same
stale-comment family, but outside this card's file list, so it is left
for the seat.
- `scripts/regen-artifacts.mjs`'s `docs/audits/**` entry calls the
strictness ledger's `.counts.md` "The ONE exception". But
`docs/audits/2026-08-tenant-audit-write-call-sites.counts.md` is also
generated whole (by `scripts/tenant-audit-census.mjs --write`) and
unrouted, and its own header explains why. Same family, outside this
card.
## Human Minimum
- [x] 1. Schemas start as Zod; `packages/spec` holds no runtime logic.
(n/a: no schema touched.)
- [x] 2. Every name I added uses the casing for its kind. (n/a: no names
added.)
- [x] 3. No formatter ran; `pnpm lint` passes. (No formatter ran; `pnpm
lint` is CI's.)
- [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: root `scripts/` and `.gitattributes`, so `skip-changeset`.)
- [x] 6. `packages/spec` touched: its generated artifacts are
regenerated and committed. (n/a)
- [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_01JQwxbaFpnMwgpCgneKe2qS
Co-authored-by: Claude <noreply@anthropic.com>1 parent 804a2b0 commit 5d2935a
3 files changed
Lines changed: 57 additions & 27 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
95 | 95 | | |
96 | 96 | | |
97 | 97 | | |
98 | | - | |
99 | | - | |
100 | | - | |
101 | | - | |
102 | | - | |
103 | | - | |
104 | | - | |
105 | | - | |
106 | | - | |
107 | | - | |
108 | | - | |
| 98 | + | |
| 99 | + | |
| 100 | + | |
| 101 | + | |
| 102 | + | |
| 103 | + | |
| 104 | + | |
| 105 | + | |
| 106 | + | |
| 107 | + | |
| 108 | + | |
| 109 | + | |
| 110 | + | |
| 111 | + | |
| 112 | + | |
| 113 | + | |
| 114 | + | |
| 115 | + | |
| 116 | + | |
109 | 117 | | |
110 | 118 | | |
111 | 119 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
174 | 174 | | |
175 | 175 | | |
176 | 176 | | |
177 | | - | |
178 | | - | |
179 | | - | |
| 177 | + | |
| 178 | + | |
| 179 | + | |
| 180 | + | |
| 181 | + | |
| 182 | + | |
| 183 | + | |
| 184 | + | |
| 185 | + | |
180 | 186 | | |
181 | 187 | | |
182 | 188 | | |
| |||
298 | 304 | | |
299 | 305 | | |
300 | 306 | | |
301 | | - | |
302 | | - | |
303 | | - | |
| 307 | + | |
| 308 | + | |
| 309 | + | |
| 310 | + | |
304 | 311 | | |
305 | 312 | | |
306 | 313 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
54 | 54 | | |
55 | 55 | | |
56 | 56 | | |
57 | | - | |
58 | | - | |
| 57 | + | |
| 58 | + | |
| 59 | + | |
59 | 60 | | |
60 | 61 | | |
61 | 62 | | |
| |||
237 | 238 | | |
238 | 239 | | |
239 | 240 | | |
240 | | - | |
241 | | - | |
242 | | - | |
243 | | - | |
| 241 | + | |
| 242 | + | |
| 243 | + | |
| 244 | + | |
| 245 | + | |
| 246 | + | |
244 | 247 | | |
245 | 248 | | |
246 | 249 | | |
| |||
418 | 421 | | |
419 | 422 | | |
420 | 423 | | |
421 | | - | |
422 | | - | |
423 | | - | |
| 424 | + | |
| 425 | + | |
| 426 | + | |
| 427 | + | |
| 428 | + | |
| 429 | + | |
| 430 | + | |
| 431 | + | |
| 432 | + | |
| 433 | + | |
| 434 | + | |
| 435 | + | |
| 436 | + | |
| 437 | + | |
| 438 | + | |
424 | 439 | | |
425 | 440 | | |
426 | | - | |
| 441 | + | |
427 | 442 | | |
428 | 443 | | |
429 | 444 | | |
| |||
0 commit comments