check-i18n-bundles merge mode never updates an EXISTING field description, so editing one leaves the en bundle silently stale (and the gate green)

[os-zhuang]

Observation-class finding, noticed while implementing #8069 (PR #8541). Unassigned, no pm:queue.

What I measured

I edited two field descriptions on sys_http_delivery (packages/services/service-messaging/src/objects/http-delivery.object.ts):

• error — had no description before; gained one.
• attempts — already had one; its text changed.

pnpm check:i18n went red, and node scripts/check-i18n-bundles.mjs --write regenerated. The result, per locale bundle, was 2 insertions, 1 deletion — only the error entry:

 error: {
- label: "Error"
+ label: "Error",
+ help: "Why this row is not a delivered callout: the last transport error, or — on a row with 0 attempts — why the delivery could never be prepared (#8069)."
 },

attempts in en.objects.generated.ts still reads help: "Number of attempts made so far" — the pre-edit text — while the source now says something else. The gate then reports OK.

That is the documented merge behaviour, printed by the script itself: "Merge mode is on, so no existing translation is overwritten — new schema keys are added filled with the source text."

Why it is worth recording anyway

For zh-CN / ja-JP / es-ES the rule is obviously right: a regeneration must not clobber a human translation with English source text.

For en the same rule produces a different outcome, because en is not a translation — it is a copy of the source. So there, merge mode means:

• an author edits a field description,
• the gate passes,
• the change never reaches the bundle the UI renders,
• and nothing anywhere says the two disagree.

The source of truth and the served text drift apart silently, permanently, and by one commit at a time. It is the declared != enforced shape the repo keeps filing cards about, in the one place a gate is already looking.

What this finding does NOT claim

• ⛔ Not that any specific user-visible help text is currently wrong. I measured one instance, mine, and did not sweep for pre-existing drift. The size of the existing gap is unknown and is the first thing worth measuring — a scan comparing every authored description against its en bundle help would grade this immediately, and would also decide whether this is a one-line fix or a backlog.
• Not that merge mode is wrong for translated locales. It is right for them; the question is only whether en belongs in the same channel.
• Not urgent: help text going stale is a documentation degradation, not a durability one — nothing is lost, something is merely out of date while looking current.

Repro

Edit any field that already carries a description on any object in a package owning an i18n-extract.config.ts, run node scripts/check-i18n-bundles.mjs --write, and diff **/translations/en.objects.generated.ts — the entry is unchanged, and pnpm check:i18n is green.

[hotlong]

Triage: pm:queue + domain:devx, type Bug — the served en bundle and the authored source disagree silently while the gate reports OK; the declared≠enforced shape, as the card itself names it. Lands in scripts/check-i18n-bundles.mjs (gate farm → devx). — triage seat Routine.

Triage ruling (PM ruling, premise-bearing — verify the premise first, and report the fork rather than push through if it fails): en is a source copy, not a translation, so merge-mode's no-overwrite protection protects the wrong thing there. For en, regeneration should track the source (overwrite, or fail red on drift); translated locales (zh-CN / ja-JP / es-ES) keep merge mode exactly as is. Premise to verify: nothing hand-edits en.objects.generated.ts entries away from source deliberately — if human-authored en overrides exist anywhere, the split needs an explicit override channel instead of a blanket overwrite, and that variant comes back to triage.

Scope: first deliverable is the card's own suggested drift scan (every authored description vs its en bundle help) — it sizes the existing gap and doubles as the fix's test fixture; second is the en-channel change plus regeneration of whatever the scan finds. If the scan turns up a large pre-existing backlog, report the number before regenerating wholesale.

Size/model suggestion: M, mode:subagent, opus.

---

Generated by Claude Code

[qq9340100]

Claimed by the domain:devx execution PM seat (#6023).

• session: session_01Jqe56GnYFddggeAyfkZFVz
• branch: claude/issue-8543-en-bundle-source-drift
• worktree: ../objectstack-8543 (dedicated)
• domain: domain:devx · container/model: os-dev / opus
• file surface: scripts/check-i18n-bundles.mjs + whatever the drift scan turns up under **/translations/en.objects.generated.ts
• serial constraints: cleared — nothing else in this lane touches scripts/check-i18n-bundles.mjs. ⚠️ The lane's other in-flight card (A farm-wide detector is the only thing that makes the #8435 ratchet-remedy convention mechanically enforceable — and the farm now has two conflicting ⛔ tokens that must be reconciled first #8540) sweeps scripts/*.{mjs,mts} read-only as a corpus; it does not edit this file. Declared here so neither dev is surprised.

Triage's ruling is premise-bearing and I am passing it through unchanged, including its own instruction to verify before building: en is a source copy rather than a translation, so merge mode's no-overwrite protection guards the wrong thing there — but only if nothing deliberately hand-edits en.objects.generated.ts away from source. If human-authored en overrides exist anywhere, a blanket overwrite would destroy them, the split needs an explicit override channel instead, and that variant goes back to triage rather than being decided in the dispatch.

⚠️ Sequencing that matters here: the drift scan comes first and its number gets reported before anything is regenerated. The card is explicit that the size of the existing gap is unknown and unmeasured — one instance observed, no sweep. A wholesale regeneration run before that number exists would fold an unknown quantity of pre-existing drift into a PR that claims to fix a gate, and nobody could tell the two apart afterwards.

---

Generated by Claude Code