Record a merge disposition for every generator, and gate the ones nobody judged

[claude]

Fixes #13731
Fixes #13335

Every generator-owned artifact now has a recorded disposition — routed to merge=os-regen, or NOT_DRIVER_MANAGED with a per-path reason — and check:merge-driver gained a third reconciliation so that generator number 12 is met by a red gate instead of by a merge conflict.

Re-derived census (⛔ not the card's figures — measured on this tree)

Command, and the numbers it produced at merge base 8c6a7fc0b:

node scripts/git-merge-regen.mjs --self-test
  -> all 21 generator(s) across 79 manifest(s) have a recorded disposition

	card (d32b0f501)	this tree
workspace manifests + root	79 + root	78 + root = 79
generator-ish scripts (gen:* key, or a --fix/--update mode)	21	21
named as a driver-managed row's gen	10	10
in NEITHER ledger	11	11

The split reproduces exactly; only the manifest count differs (the card's "79 workspace manifests plus the root" reads as 80 against this tree's 79).

⭐ One correction that changed the shape of the work: the census is by SCRIPT, but a disposition is per PATH. Resolving each of the 11 to what it actually writes collapses them to 9 artifact groups, and two of those turn out not to be in git at all.

The dispositions — one per path, each with its recorded reason

Routed (merge=os-regen) — 3 paths

path	generator	why routing is right
skills/*/references/_index.md	gen:skill-refs	#13335. Generated whole, one row per spec module, no hand-written region. Two branches' correct-for-themselves projections merge to a file describing neither. 9 tracked files today; a SEGMENT glob so a tenth skill arrives routed.
skills/objectstack-ui/contracts/react-blocks.contract.json	gen:react-blocks	Generated whole from the REACT_BLOCKS definition. Two PRs adding different blocks are a set union git reports as a conflict.
skills/objectstack-ui/references/react-blocks.md	gen:react-blocks	Same, and generated whole including its frontmatter and its "do not edit by hand" banner — verified in the generator, so there is no hand-written region a deferral could launder.

⚠️ Routing is the CHEAP half and is never the protection — the driver is a LOCAL facility, so it does nothing for a merge-queue rebuild. What protects these paths is server-side, and it is already wired: check:skill-refs and check:react-blocks run in lint.yml on pull_request and merge_group with no paths: filter, and both RE-DERIVE the artifact from source rather than reading it back — so they also catch the silent case. This follows #13646's ruling (the CI regeneration check is load-bearing, the driver incidental) rather than re-litigating it.

NOT_DRIVER_MANAGED — 7 paths, each with its own reason

path	generator	recorded reason (abridged)
skills/README.md	gen:skill-docs	MIXED — the generator rewrites only the BEGIN/END GENERATED: skills region: 17 of 114 lines. The other 97 are hand-written prose, and the driver defers the WHOLE file. Routing would launder a sibling's prose edit — the exact trade migrations/registry.ts is kept out for.
content/docs/ai/skills-reference.mdx	gen:skill-docs	MIXED, same shape — one spliced block inside 267 lines of guide prose.
packages/client/test-typecheck-debt.json	gen:test-typecheck-debt	Shrink-only ratchet. Recomputing mid-merge records whatever the half-merged tree compiles to, and a file that GAINED errors enters the ledger as merge noise instead of as red.
packages/rest/test-typecheck-debt.json	gen:test-typecheck-debt	Same. Listed separately on purpose — see the keying note below.
packages/sdui-parser/objectui-lockstep.json	gen:sdui-lockstep	A vendored record of ANOTHER repository. --update needs an objectui checkout; a merge driver has no network, no build and no sibling checkout, so "recompute from the merged sources" names sources not in this tree. And the pinned .objectui-sha records which revision a human ported to — an act, not a projection.
packages/spec/json-schema/**	gen:openapi	Gitignored (.gitignore:61) — git never merges it, so it has no merge semantics to decide. Recorded because it looks like the routed json-schema.manifest/** beside it and invites the symmetry.
sbom.json	gen:sbom	Gitignored (.gitignore:73) — release-time output; nothing merges it and no check: proves it current.

Already accounted for — no change beyond making it visible

gen:migration-registry and the packages/spec copy of gen:test-typecheck-debt were already NOT_DRIVER_MANAGED by path; they gain a gen field so the new accounting can see them. gen:authorable-surface-base is deliberately not any row's gen (the reasoning already sits beside the authorable-surface.base.json row); it gains an alsoWrittenBy entry so it reads as judged rather than as unaccounted.

What the instrument fails on

reconcileGenerators() in scripts/git-merge-regen.mjs. Population is enumerated from the manifests themselves — never a hand-kept list — so generator 12 enters it by existing. It fails, in both directions, when:

• a generator-ish script is in neither ledger; and
• a recorded disposition names a generator no manifest defines (a rename leaves a reason covering nothing).

Accounting is keyed by (owner, script), never by bare name: gen:test-typecheck-debt exists in three manifests writing three different ledgers, and a name-keyed check would have let the packages/spec entry account for the client and rest copies — which were 2 of the 11 gaps, so it would have been born unable to see its own motivating case.

Two more reconciliations came with it:

• reconcileAttributeSemantics() — entryForPath and git must read a declared path the same way, measured against git check-attr itself over all 7614 tracked files. This closes a latent bug the segment glob would otherwise have walked into: reconcileAttributes compares bytes, so a pattern git matches but entryForPath does not reconciles green and is then REFUSED by the driver mid-merge, blaming a table row that is present. A row matching nothing is a failure too.
• reconcileUntrackedDispositions() — the two "git never merges it" reasons are expiring claims, so they are asserted rather than asserted once. The day sbom.json is committed, a gate reddens instead of a merge conflict surfacing later.

The false-positive bound (⚠️ stated, because a bound nobody writes down is a bound nobody checks)

• The --fix/--update limb currently adds zero members beyond the gen:* keys — measured: all 21 members carry a gen: key. It is kept because it fails closed; its false-positive class is a transform like eslint --fix, whose remedy is one ledger line. A gate asking for one line is not a noisy gate.
• ⛔ What it cannot see: a generator that no manifest script names. scripts/*.mjs invoked directly by a workflow is that shape, and that population belongs to check:ratchet-remedy-authority, which builds its own from readdirSync.

#13335's reproduced conflict, and what this PR does to it

The card's exact rows, replayed in a temp repo — control (unrouted, today's main) against this PR:

===== CONTROL (unrouted — today's main)
  git merge exit=1
  RESULT: CONFLICT MARKERS in skills/objectstack-ui/references/_index.md
  conflicted-in-index: UU skills/objectstack-ui/references/_index.md
  pending marker: (none)
  | CONFLICT (content): Merge conflict in skills/objectstack-ui/references/_index.md

===== THIS PR (skills/*/references/_index.md merge=os-regen)
  git merge exit=0
  RESULT: no conflict markers
  conflicted-in-index: none
  pending marker: skills/objectstack-ui/references/_index.md
  |   ⟳ skills/objectstack-ui/references/_index.md
  |      not text-merged — it is generated. Regenerate from the merged tree:
  |        pnpm --filter @objectstack/spec gen:skill-refs

The resolution #13335 records by hand — take either side, commit the merge, regenerate, let check:skill-refs prove it — is what this row plus os-regen-merge.sh step 4 now do mechanically. os-regen-merge.sh also stops reporting the file as a conflict in a NON-generated file, which is what it did on that card.

Reverse verification — 4 ablations, all RED in the predicted direction

Each mutation was proven on disk before the run (occurrence counts, not a bare git diff --stat), and each restore proven by git diff HEAD empty and a blob-hash match against the HEAD blob. No build step: these are plain .mjs run directly by node, with no dist/ resolution between the edit and the run.

ablation	expected	observed
A. delete the sdui-lockstep disposition	red	exit=1 · ✗ generator(s) with NO recorded merge disposition
B. add a 12th generator nobody has judged	red	exit=1 · same refusal, naming it
C. revert the glob matcher only	red	exit=1 · ✗ git routes these to merge=os-regen but entryForPath does not resolve them and ✗ declared path(s) matching no tracked file
D. point a disposition at a generator no manifest defines	red	exit=1 · ✗ disposition(s) naming a generator that no manifest defines

C is the one worth reading: it confirms the latent bug is real. Without the segment-glob support, routing skills/*/references/_index.md would have reconciled green and then failed at merge time.

Gates

Derived with node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack (13 families + 2 convention-triggered for editing a gate script), all run on final commit dc492c701:

PASS pnpm check:merge-driver              PASS pnpm check:ratchet-remedy-authority
PASS pnpm check:agent-test-spelling       PASS pnpm check:bash32-floor
PASS pnpm check:cli-command-ids           PASS pnpm check:cross-package-test-inputs
PASS pnpm check:entry-guard               PASS pnpm check:parse-guard
PASS pnpm check:pnpm-filter-targets       PASS pnpm check:watch-hint-literal
PASS node scripts/check-ci-filter-parity.mjs
PASS node scripts/check-cross-package-test-inputs.mjs
PASS node scripts/check-shard-attestation.mjs
PASS node scripts/pm/bare-root-worklist.mjs --self-test
PASS pnpm check:pm-dispatch-gates         (1048 cases)
PASS pnpm check:nul-bytes                 (7607 files, 0 raw control bytes)
PASS pnpm --filter @objectstack/spec check:generated --reconcile-only
PASS check:skill-refs · check:react-blocks · check:skill-docs · check:sdui-lockstep

node scripts/check-test-completeness.mjs exits 3 when run bare — it requires a test-run log CI tees in, so it is NOT MEASURED locally rather than failed.

ESLint — narrowed, with the evidence the narrowing needs: the changed files lint clean (--format json: 2 files, 0 errors, 0 warnings). Population read from eslint's own --print-config, which reports parserOptions.project = null and projectService = null ⇒ type-aware linting is not enabled, so no untouched file's verdict can depend on this diff, and the diff changes no eslint config. The repo-wide sweep remains CI's run.

Changeset

None, and skip-changeset applied. Measured, not assumed: all three touched paths live at the repo root, owned by the private @objectstack/spec-monorepo; of 69 publishable workspace packages, zero are rooted at the repo root and zero have a files[] entry reaching scripts/ or .gitattributes. Nothing publishes.

Governed surface

⛔ No skills/** file is edited. GOVERNED_SURFACES is docs/adr/, .claude/, skills/, AGENTS.md, CLAUDE.md; this diff is .gitattributes + two root scripts/*.mjs. The fence stays intact and this is not a governed PR — confirming the devx seat's 03:29Z measurement on #13335.

---

Generated by Claude Code

---

Generated by Claude Code