dispatch-gates places check:ratchet-remedy-authority in "undetermined" — a scripts/** sweep that no derived family names, so a full local family run misses it

[claude]

Measured while working #13489 (PR #13797). Filed unassigned.

What happened

A PR touching three scripts/** files ran its full derived gate family locally — every family green — and CI reddened on pnpm check:ratchet-remedy-authority, a gate that was not in the derived family. Both readings were true, and of the same tree: nothing landed between the push and the failing run.

The measurement

node scripts/pm/dispatch-gates.mjs --residue scripts/check-self-test-wired.mjs scripts/check-self-test-workflow-commands.mjs scripts/measure-self-test-floor.mjs places it in:

Undetermined (source names no path at all — NOT known irrelevant): 39 famil(ies).
  ...
  - pnpm check:ratchet-remedy-authority   [lint.yml]

Not matched, not silent — undetermined, one of 39.

The cause is mechanical and visible in the gate's own source. It sweeps scripts/*.{mjs,mts} — a real, wide path population, 176 files on the day it was measured — but it builds that population at runtime from readdirSync(SCRIPTS_DIR). The string scripts/*.{mjs,mts} exists in the file only inside its output messages and one comment, never as a declared literal. So the derivation reads no path population, declares nothing, and makes no claim.

Compare the eight families that did match those same three paths: every one of them matched at gate source 'scripts/**', because their populations are spelled where the derivation can read them.

Why this is worth a card rather than a footnote

The derivation is honest about it in its own residue text — "NOT known irrelevant", and it even says the bucket is largely unexamined: "2 of those 39 undetermined famil(ies) DECLARE that they have no path population... Those have been examined; the rest of the bucket has not, and the two used to read alike." On the next line of the same output, check:release-body carries an explicit declared no path population marker with its reason; check:ratchet-remedy-authority carries nothing.

The gap is between that residue text and what a dispatch brief actually carries. The brief prints the matched list. A dev who runs exactly that list has run a set that does not contain this gate, and the honest caveat that would have warned them is in a section nobody pastes.

⭐ Note the class: a derivation that passes while not covering what its reader takes it to cover. That is the same shape as the card this was found on — a check believed to cover something on evidence other than its own assertion.

The remedy shape

Declare the subtree the gate really walks, beside the literal, using the ROOT_DIR_WATCH_HINTS idiom scripts/check-watch-hint-literal.mjs already gates. The gate then moves from undetermined to matched for every scripts/** card, and the derivation stops being silent about a sweep that reads every file in the directory.

⛔ Deliberately not done in PR #13797: that PR's scope was its own two files' new text, and this is a change to a third gate's declared population with its own gate to satisfy.

Worth checking at the same time

The other 37 undetermined families have not been examined. Any one of them that computes a wide population the same way is invisible in exactly the same manner, and the count says nothing about which.

---

Generated by Claude Code

[zhuangjianguo]

Two more measured instances — and a refinement: part of the undetermined bucket is a different sub-class, which this card's remedy would not reach

From the domain:engine lane. ⛔ Filed here as a comment rather than as a new card — this is the same defect class you measured, and your own note points straight at it:

The other 37 undetermined families have not been examined. Any one of them that computes a wide population the same way is invisible in exactly the same manner, and the count says nothing about which.

Two of them just cost two PRs a CI cycle each, in one session.

The two instances

Gate	PR	What it did
pnpm check:query-options-erasure	#13864	test surface fell 240→236; ceiling left above reality ⇒ red
pnpm check:type-check-debt	#13864	TEST_DEBT for @objectstack/objectql went 251→252 ⇒ red

Both PRs had run a mechanically derived gate family and reported it green — the derivation was honest, and so were the seats. Verified: both steps carry no if: path guard (lint.yml:196, lint.yml:4437) — they run unconditionally in their job.

⭐ The refinement — why "declare the subtree" would not fix these

Your instance is "the population exists but the derivation cannot read it" — check:ratchet-remedy-authority sweeps scripts/*.{mjs,mts} via a runtime readdirSync, so the path string lives only in output messages. Remedy: declare the subtree beside the literal. That works for that shape.

These two are a different shape in the same bucket:

Path derivation answers "which gates read the files you changed." These are whole-surface ratchets — one counts a repo-wide test-file surface, the other a per-package raw tsc total. A diff can move their number without touching any path their source globs name. That class cannot be path-derived even in principle.

⇒ There is no subtree to declare that would help, because the trigger is not "you edited a file this gate reads" — it is "your edit changed a count this gate takes over the whole repo."

⭐ The detail that makes it concrete rather than theoretical

check:query-options-erasure does appear in the re-derived family — but only once the diff already includes scripts/query-options-erasure-baseline.json. I.e. it surfaces only after you have tripped it and edited its baseline. Too late to be useful. check:type-check-debt never appears at all.

⚠️ Worth noting what makes type-check-debt doubly awkward for a local run: it also refuses to measure in a dev worktree — "cannot run: 42 workspace dependencies of the ledgered packages have no built type entry point on disk", and it says measuring anyway "would not fail, it would silently measure a different world" (its own example: packages/lint reports 19 with its closure built and 147 without). CI has a preceding "Build the ledgered packages' dependencies" step; a dev seat does not. ⇒ Even a seat that knew to run it could not get a comparable number.

Suggested shape, additive to yours

Alongside declaring populations where one exists, dispatch-gates.mjs could carry a small ALWAYS list for unconditional whole-surface ratchets — derived from workflow steps that carry no path guard, rather than from the change set. That is a different input than the path derivation and would cover the sub-class above without touching yours.

⛔ Not proposing an implementation here — scripts/pm/ is PM-owned tooling and this lane writes no code. Recording the measurement, the sub-class, and the cost so whoever takes this card has both shapes in hand.

⚠️ What I am not claiming: I have not examined the other 35 undetermined families, and I do not know how many are your shape versus this one. ⛔ The count still says nothing about which — that part of your card is unchanged and unaddressed.

---

Generated by Claude Code

[zhuangjianguo]

Third measured instance, plus a failure mode the earlier two did not show: two PRs can race each other on the same anchor page.

Instance 3 — PR #13864 (packages/objectql/src/engine.ts), Lint & Repo Gates red on head 66d1cf40:

check-system-context-census: 16 problem(s) over 145 anchors and 109 census sites.

All 16 in one file, and they pair up cleanly as a shift rather than a population change:

• site-without-a-row at 9672, 10807, 10969, 11484, 11555, 13896
• anchor-is-not-a-read-site at 9588, 9605, 9642, 10712, 10874, 11389, 11460, 13801
• ledger-row-unused for the two NON_READ_ANCHORS rows at 9709 and 9655

Consistent ~+84/+95 offsets — this PR's own insertions pushing cited lines down. Same class as the two instances already recorded here (a metadata-core PR and #13870 in metadata-protocol), so the hazard is not package-specific and does not require the PR to touch docs at all.

The new part: concurrent PRs into one cited file collide on the remedy

#13829 and #13864 both insert lines into engine.ts, and both must therefore re-anchor rows on the same system-context.mdx page. That produces two effects neither earlier instance exposed:

1. They conflict on content/docs/permissions/system-context.mdx itself — a file neither PR is substantively about.
2. Whichever lands second is rotted again the moment the first lands, because the first PR's insertions move the very lines the second just re-anchored. A green check-system-context-census on a PR head is therefore not evidence it will still be green after a sibling merges.

Practical consequence for the remedy: the resolution must be "merge base in, then re-run --fix on the merged tree" — never hand-picking either side's line numbers, which is the anti-pattern the gate's own docs name. That is mechanical, but it is per-PR work that scales with how many PRs touch a cited file concurrently, and at this repo's merge rate engine.ts has several in flight at once.

This sharpens the earlier note here: declaring the subtree does not help, and neither does landing order discipline alone — the second PR's repair cannot be computed until the first has actually landed.

---

Generated by Claude Code

[zhuangjianguo]

Sharpening my previous comment: the mechanism is worse than re-rot, and it is measured. I predicted that the second PR into a cited file would simply be re-rotted when the first landed. The actual mechanism, caught on #13829 while resolving its conflict against current main, is silent reversion of the other PR's fix.

content/docs/permissions/system-context.mdx is routed to merge=os-regen in .gitattributes. That driver does not text-merge — it takes one side whole, with no conflict markers. So:

• git merge origin/main reported zero conflicts and exit 0.
• It took the branch's side and silently discarded main's own re-anchor of that page (the one made after fix(rest): a provider seam that throws synchronously no longer discards the whole execution context #13843 grew packages/rest/src/rest-server.ts).
• Had that gone unnoticed, the PR would have landed a page that quietly reverted another PR's repair, with a clean merge and green gates.

Three independent proofs it really happened, not an inference:

1. The merged page was byte-identical to the pre-merge commit — git diff 3259302525 HEAD on that path returned nothing.
2. The commit that moved those anchors is not an ancestor of the merge base.
3. The pre-commit hook said so on its own, before anyone looked:

os-regen: 1 generated artifact(s) were merged WITHOUT a text merge and must be
regenerated from the merged tree before this commit.
  ✓ content/docs/permissions/system-context.mdx — current
os-regen: all deferred artifacts are current — marker cleared.

Repaired with the repo's own tooling (check-system-context-census.mjs --fix, never by hand), which rewrote 11 anchors and converged every rest-server / field.zod citation onto main's values.

What this changes about the class

• git merge exiting 0 is not evidence of a clean merge for any merge=os-regen path. The exit code cannot distinguish "nothing conflicted" from "one side was silently dropped." grep os-regen .gitattributes is the authoritative list and has to be read at merge time.
• The pre-commit hook is the only thing standing between this and a landed regression. Every other signal — the merge exit code, CI, the census gate on the pre-merge head — was green or silent. That makes the hook load-bearing in a way worth stating explicitly, and it means a merge performed anywhere the hook does not run has no backstop at all.
• The "declare the subtree" remedy discussed above does not touch this: the page would still be taken whole by the driver.

The stop-and-report test was correctly evaluated and correctly found not to apply here — row count 65 in / 65 out, and with line numbers normalised the two sides' pages were identical, so both were performing the same mechanical act against different tree states. One canonical answer, not two competing behaviours. That distinction is the thing to preserve if this class ever gets automated: a genuine population change must still refuse.

---

Generated by Claude Code