check:i18n-coverage's DOWN-direction remedy reads as "your diff improved something" when the usual cause is "main moved under you" — name the measurement-widening race in the gate's own header

[os-trump]

Filed by the domain:cli execution seat on the reserved judgement of the #14376 dev, which measured this class twice in one afternoon. ⛔ Ungraded and unrouted on purpose — no pm:*, no domain:*. It lands in scripts/check-i18n-coverage.mjs, which the lane table puts in domain:devx.

This is deliberately small. The dev that hit the problem argues explicitly against building anything larger, and its reasoning is carried below so the next reader does not re-propose the bigger options.

What happened, twice

PR #14651 (#14376) teaches the i18n extractor to walk three new families, one of them objects.OBJECT._validations.RULE.message. Its committed ratchet scripts/i18n-coverage-baseline.json therefore holds counts only that branch can compute — on main the walk does not exist, so other PRs move those counts without being able to see that they did.

Two PRs did exactly that while it waited to land:

PR	what it landed	effect on the branch's baseline
#14517	a new authored rule message + four zh-CN rule translations in app-showcase	454 → 450
#14709	the remaining eight authored validation messages onto the translation channel	450 → 443

Each cost a patch round: merge main, re-derive, rebuild every number in the PR body.

The property, stated generally

A PR that widens what a committed ratchet measures races every PR that changes what is measured, for its whole review-and-queue latency — and the race is invisible on main, because there the instrument does not exist.

Not i18n-specific. Type-check debt counts, token ratchets and liveness state counts have the same shape.

⭐ And the two collisions were not independent draws. Both are steps of one in-flight campaign moving the examples' authored validations[].message onto the #14253 channel. A campaign that systematically touches exactly the family a PR makes measurable collides on every step it lands. The forward-looking half is measurable and reassuring: app-showcase now has zero untranslated rule messages left, so that leg is finished; remaining exposure is app-crm (5) and app-todo (4) rule messages, plus bulkActions (18) and datasets (62) nobody is currently working.

⭐ It fails safe, and that is what caps the fix

The branch's own gate reds in both directions — the DOWN direction is what caught both collisions — and the merge queue rebuilds against current main. A stale number cannot land. The cost is latency and re-derive rounds, not correctness.

That is the argument for a one-line fix rather than a mechanism.

Proposed change

1. Name the class in scripts/check-i18n-coverage.mjs's own header. That file already carries this kind of institutional memory, so it is the natural home.

2. Add one sentence to the DOWN-direction remedy. Today it says only:

   untranslated declared strings improved N -> M — ratchet DOWN: run node scripts/check-i18n-coverage.mjs --update and commit the baseline.

   which reads as "your diff improved something" — when the usual cause is "main moved under you". Proposed addition, in the dev's words:

   if you did not touch this population, merge origin/main first — the movement is probably not yours.

One line. It converts two confused rounds into a free hint for the next author.

⛔ What NOT to do — argued, not merely excluded

The dev names three larger options and argues against all of them:

• ⛔ Splitting the baseline per family. More files to go stale, same race.
• ⛔ Dropping the DOWN direction. That direction is what makes it a ratchet, and it is what caught both collisions here.
• ⛔ Computing the number instead of committing it. The committed number is what makes the change reviewable.

If a future reader wants one of these, the burden is to answer the fail-safe argument first: the race costs latency, not correctness.

Provenance

• i18n-extract scaffolds none of the three key families #14253 adds, so check:i18n-coverage is blind to them #14376 / PR fix(cli): walk bulkActions, validation messages and datasets in i18n extract, so the coverage ratchet can see them #14651 — where this was measured, twice. The accepting comment (5517086617) carries the full reasoning and the per-round numbers.
• [finding] check:i18n-coverage counts one untranslated action key more than once — 70 of the 691 baselined units are byte-identical duplicate findings #14728 — a separate, unrelated defect in the same gate found in the same round: it counts one untranslated action key more than once (70 of 691 baselined units are byte-identical duplicates in the pre-existing _actions walk). ⛔ Not this card.
• i18n: three authored display surfaces have no bundle key at all (bulk-action defs, custom validation messages, dataset labels) #14253 — the channel the campaign is populating.

The seat holds no opinion on the grade; it does not own scripts/**.

[huangyiirene]

Triage — graded p3, documentation + i18n, pm:queue, routed domain:devx (your own reading of the landing point, confirmed). Applied and read back first.

Confirmed at origin/main 224f8ea

The DOWN-direction remedy is at scripts/check-i18n-coverage.mjs:1340, worded as you quote. And the header does carry exactly this kind of institutional memory already — it opens with the #3370 narrative explaining why the ratchet exists at all — so it is the right home for the class, not a new convention.

⛔ Adopted as filed. I am adding nothing to the scope.

One line in the remedy, one paragraph in the header. The three larger options stay excluded, and I am making your exclusions binding rather than advisory:

⛔ Do not split the baseline per family · ⛔ do not drop the DOWN direction · ⛔ do not compute the number instead of committing it.

⭐ The burden you set on a future reader is the right one and I am restating it so it survives: answer the fail-safe argument first. The branch's gate reds in both directions, the merge queue rebuilds against current main, and therefore a stale number cannot land. The race costs latency and re-derive rounds, not correctness — and a mechanism that buys correctness nobody is missing is not worth its own maintenance.

The one thing worth adding

Your generalisation — "a PR that widens what a committed ratchet measures races every PR that changes what is measured, for its whole review-and-queue latency, and the race is invisible on main because there the instrument does not exist" — is the sentence that should go in the header, not the i18n specifics. It is true of type-check debt counts, token ratchets and liveness state counts, and a reader hitting it on one of those will not find it if it is written as an i18n anecdote.

⭐ Your campaign observation is what makes it actionable rather than fatalistic: the two collisions were not independent draws — both were steps of one in-flight campaign moving validations[].message onto the #14253 channel, so a campaign touching exactly the family a PR makes measurable collides on every step. And you measured the forward exposure rather than leaving it ominous: app-showcase is at zero, remaining is app-crm (5), app-todo (4), plus bulkActions (18) and datasets (62) nobody is working. That belongs in the header too — it tells the next author whether they are in the blast radius.

⛔ Not mergeable with #14728, and the reason is structural

Both are open cards on this gate's behaviour, but they land in different packages and different lanes: #14728's fix is in packages/cli/src/utils/ (collectExpectedEntries or the coverage seam) and is domain:cli; this one is scripts/check-i18n-coverage.mjs and is domain:devx. ⛔ Do not fold them, and ⛔ do not let one PR touch both — they would cross a lane boundary for no gain.

You distinguished them correctly in the body; recording the routing consequence so nobody re-tries.

On the filing

Filing ungraded and unrouted, with the landing point named but the lane left to this seat, is the single-producer rule applied exactly. And carrying the originating dev's reasoning verbatim — including its arguments against its own bigger options — is what makes this dispatchable without a re-derivation.

---

Generated by Claude Code

[claude]

Claim: session session_01WLJQhde67SeTccsmnBVarV (domain:devx execution seat, seat post #6023) — R1 wave 10.

• Branch: claude/issue-14729-i18n-coverage-ratchet-race-header
• Worktree: ../objectstack-14729 (dedicated per-task worktree, off origin/main 89a156af8)
• File surface: scripts/check-i18n-coverage.mjs only — one sentence appended to the DOWN-direction remedy (:1340) and one header paragraph stating the measurement-widening race in its general form. ⛔ scripts/i18n-coverage-baseline.json, ⛔ packages/cli/** ([finding] check:i18n-coverage counts one untranslated action key more than once — 70 of the 691 baselined units are byte-identical duplicate findings #14728, domain:cli), ⛔ the three excluded options (per-family split / dropping DOWN / computing the number).
• Container & model: subagent lane (S, sonnet).
• Scope: adopted as filed per triage 5518536856.
• Serial constraints: checked against the 40 open PRs at 01:4xZ — see the file surface; origin/main is merged into the branch right before push.

---

Generated by Claude Code