refactor(tooling): shard the ADR-anchor registry one file per anchor

[os-help]

Part of #6957 — this is the scripts/adr-anchors.json half only. packages/spec/src/migrations/registry.ts belongs to the domain:spec seat and is the file their in-flight retirement cards are appending to right now; restructuring it from this lane mid-window would cause the exact collision the card documents. It is being transferred to that seat separately, so Part of rather than Fixes.

Ruling this implements

Maintainer ruling of 2026-08-10, quoted verbatim and untranslated:

hybrid — batch now, split the append surface as the durable fix.
Now: the PM landing relay batches same-window retirement cards into one PR … Queued: implement per-card registry entry files concatenated by a generator, the .changeset/*.md shape that already de-conflicted this repo's other hottest file; scripts/adr-anchors.json is in the same fix space and may ride the same mechanism. Option B (uncommitted build-time artifacts) is rejected — the review diff of spec-changes.json / the upgrade guide is worth the laps it costs.

Option (a) adopted, (b) rejected, (c) is the interim mitigation. None re-opened here.

What changed

scripts/adr-anchors.json — a single 343-line append-only array that every card adding an anchor had to edit — becomes scripts/adr-anchors/, one JSON file per anchor, 47 of them, named for the path each anchors (packages/objectql/src/engine.ts → packages__objectql__src__engine.ts.json). A new module scripts/adr-anchors.mjs assembles them in id order at read time; scripts/check-adr-anchors.mjs consumes that instead of parsing one file.

Also updated: the three live pointers at the old path (AGENTS.md PD #13, the lint.yml step comment, two runtime code comments). Records under docs/adr/, historical changesets and content/docs/releases/ are deliberately untouched — and the path prefix scripts/adr-anchors still resolves for a reader who greps it.

Consumer verdict is unchanged

	before	after
check:adr-anchors verdict	OK	OK
anchored files checked	47	47
decision numbers audited	118	118
ambiguous-number note	4	4 (same four, now id-ordered)
--self-test assertions	39	52

The only figures that move are the citation-scan denominators (20837 → 20853 across 3418 → 3469 files): the same anchor text now lives in 47 tracked files instead of 1, which is inherent to the split and not a verdict change. Every failure message is byte-for-byte the same except that each now names the exact entry file to edit instead of the shared blob.

The de-conflicting claim, demonstrated rather than asserted

Two simulated concurrent appends, replayed under both layouts with git merge-tree --merge-base — old base origin/main, new base this branch:

== OLD layout: two cards each append a DIFFERENT anchor ==
  adr-anchors.json (single file) -> CONFLICT (rc=1)
       CONFLICT (content): Merge conflict in scripts/adr-anchors.json
== NEW layout: the SAME two appends ==
  adr-anchors/ (one file per anchor) -> CLEAN
== NEW layout CONTROL: two cards edit the SAME anchor (must NOT merge clean) ==
  same shard, two different edits -> CONFLICT (rc=1)
       CONFLICT (add/add): Merge conflict in scripts/adr-anchors/packages__proof__alpha.ts.json

The control is the half that is easy to skip and cannot be: a layout in which two edits to one entry also merge clean is a layout that silently loses one of them. Harness proven non-blind before any of this was believed — split-then-reassemble is byte-identical over all 47 entries, and flipping a single character in one invariant breaks that equality.

Reverse verification of the gate itself: deleting ADR-0091 from packages/core/src/security/grant-validity.ts turns check:adr-anchors red with the invariant text and the shard path; restoring it returns green.

Why a sharded directory and not a committed concatenated artifact

Because the card's subject is the merge queue, and this repo has already measured what that rules out. merge=os-regen (#4675) is a local git facility; the GitHub merge queue rebuilds each PR server-side where no custom merge driver runs, which is why #5837 had to shard the three hottest spec artifacts one file per category rather than merely route them. A checked-in aggregate here would be exactly that server-side conflict surface, and it would carry no review information the entry files do not already carry.

⚠️ To be explicit, since it is adjacent to the rejected option (b): nothing left version control and no reviewable diff was traded away. Every byte of the old file is still committed, one entry per file. The review diff improves — a new anchor is a new file rather than a hunk in a shared blob — and spec-changes.json / the upgrade guide are not touched by this PR at all.

Two properties enforced, not assumed

• The shard filename is a pure function of the entry id. Different anchors ⇒ different files ⇒ clean merge; the same anchor ⇒ the same file ⇒ git conflict, as it must. assembleAnchors rejects a shard whose name disagrees with its file, so a rename cannot quietly re-open the losing half.
• Order is derived (sort by id), never declared. No index file: an index would itself be the single append-only file every card must edit, reintroducing the conflict being removed (PM decision on Protocol-17 retirement cards all append to the same two registries, so they serialize badly under the merge queue — three consecutive re-merge laps measured on one PR #6957). Order is not contractual for this registry in any case — the gate iterates to accumulate errors and never compares positions.

Verification

$ node scripts/check-adr-anchors.mjs --self-test
✓ check-adr-anchors --self-test: 52 assertions over the real auditAdrDirectory() / auditCitedNumbers() / assembleAnchors() paths.
$ node scripts/check-adr-anchors.mjs
check-adr-anchors: OK (47 anchored file(s), every governing ADR still referenced; 118 decision number(s), each naming one decision or an allowlisted pair; 20853 citation(s) across 3469 file(s) resolve).
$ node scripts/check-adr-links.mjs
✅ check-adr-links: 531 relative link destination(s) under docs/adr/ resolve (8 frozen on the shrink-only baseline)
$ node scripts/check-nul-bytes.mjs
check-nul-bytes: OK (scanned 6701 text file(s) — 6701 tracked, 0 untracked-not-ignored; skipped 5 binary; no raw ASCII control bytes)

All four re-run after merging origin/main (no commit on main since the fork point touched the old registry, so nothing was dropped). No check:/gen: script entry was added or renamed, so the #4203 meta-gate surface is untouched; .gitattributes and regen-artifacts.mjs are likewise unchanged — this registry is hand-authored, not generator-owned.

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 10, 2026 5:31am

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/runtime.

20 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/api/client-sdk.mdx (via packages/runtime)
• content/docs/api/index.mdx (via @objectstack/runtime)
• content/docs/api/wire-format.mdx (via @objectstack/runtime)
• content/docs/automation/hook-bodies.mdx (via @objectstack/runtime)
• content/docs/concepts/metadata-lifecycle.mdx (via @objectstack/runtime)
• content/docs/concepts/north-star.mdx (via packages/runtime)
• content/docs/data-modeling/drivers.mdx (via @objectstack/runtime)
• content/docs/deployment/index.mdx (via @objectstack/runtime)
• content/docs/deployment/production-readiness.mdx (via @objectstack/runtime)
• content/docs/deployment/single-project-mode.mdx (via @objectstack/runtime)
• content/docs/deployment/vercel.mdx (via @objectstack/runtime)
• content/docs/getting-started/your-first-project.mdx (via @objectstack/runtime)
• content/docs/kernel/cluster.mdx (via @objectstack/runtime)
• content/docs/permissions/authentication.mdx (via @objectstack/runtime)
• content/docs/permissions/authorization.mdx (via packages/runtime)
• content/docs/permissions/system-context.mdx (via packages/runtime)
• content/docs/plugins/packages.mdx (via @objectstack/runtime)
• content/docs/protocol/kernel/http-protocol.mdx (via @objectstack/runtime)
• content/docs/protocol/kernel/index.mdx (via @objectstack/runtime)
• content/docs/protocol/kernel/lifecycle.mdx (via @objectstack/runtime)

⛔ 2 release-owned page(s) also reference the affected code. These are read-only:

• content/docs/releases/implementation-status.mdx (via @objectstack/runtime)
• content/docs/releases/v17.mdx (via @objectstack/runtime)

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.