fix(spec): give the email-template locale bundle a stated en-US floor, and report one that has none - #17884

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/spec, touching 4 documentable anchor(s). ⚠️ 3 changed file(s) yielded no anchor (packages/spec/api-surface/system.json, packages/spec/export-origins/system.json, packages/spec/vitest.repo-tests.json), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

1 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/automation/email-templates.mdx (via EmailTemplateDefinitionSchema (symbol, a top-level const))

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin d8d5d62486c97d2f434312f1df921d0b5d8cf9ec && git checkout d8d5d62486c97d2f434312f1df921d0b5d8cf9ec
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 2266438ce0ba039634f9dcec06db7be12c0d58ee 4feb4e245c3fc0eb7692f85bd30d282f3b4b72ca && git checkout -B drift-repro 2266438ce0ba039634f9dcec06db7be12c0d58ee && git merge --no-ff 4feb4e245c3fc0eb7692f85bd30d282f3b4b72ca

node scripts/docs-audit/affected-docs.mjs --json 2266438ce0ba039634f9dcec06db7be12c0d58ee

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 2266438ce0ba039634f9dcec06db7be12c0d58ee → pass the list as
args.docs, on the commit named under Which tree this was computed on.

os-contract-review

PASS WITH CONDITIONS

The fence held, both remedies are pinned and load-bearing, the accept set does not move, and the changeset grade is right. One real defect: the new constant's docblock publishes an invariant that nothing checks. That is fixable inside the fence, and it is the only thing standing between this and a clean PASS.

Implemented-by: claude/issue-17614-email-template-locale-floor
Reviewed-by: session_01MkQhmuuJAVDjmeWNixwDDH
⚠️ SELF-REVIEW — see the tier statement at the bottom.

Conditions (each mechanically verifiable by the seat)

• C1 — back the parity claim, or stop publishing it. packages/spec/src/system/email-template.zod.ts:36-39 asserts, in published TSDoc, that @objectstack/plugin-email's DEFAULT_TEMPLATE_LOCALE and EMAIL_TEMPLATE_FLOOR_LOCALE "must stay equal". Nothing holds them equal. Pick one:
  • (a) add a parity pin — a repo-project test in packages/spec that reads packages/plugins/plugin-email/src/email-service.ts as text and asserts its DEFAULT_TEMPLATE_LOCALE literal equals EMAIL_TEMPLATE_FLOOR_LOCALE; register the path in packages/spec/vitest.repo-tests.json and re-run check:cross-package-test-inputs; or
  • (b) delete the "must stay equal" sentence, leaving only the dependency-direction note.
    Either is acceptable. Shipping the claim with nothing behind it is not — see Q2 for why this exact shape already has a pin precedent in this package.
• C2 — name the second silent case on the card. The round named one deliberate boundary (no i18n block ⇒ silent). There is a second it did not name: packages/spec/src/stack.zod.ts:2728 (if (declared.length === 0) continue;). A stack that does declare i18n.supportedLocales but whose bundle tags none of them is equally floorless and equally silent — e.g. supportedLocales: ['en'] with a lone fr-CA row, which this PR's own test pins green at packages/spec/src/stack-email-template-locale-floor.test.ts ("silent when no authored tag is one this stack claims to support"). Add it to the successor note. No code change asked for; it is inside triage's wording too.

⛔ Neither condition asks for folding, a third rung, or any edit under packages/plugins/plugin-email.

Q1 — Which limb does clause ② fire on, and is yes right?

yes is right — on the published-surface limb, not the limb declared at dispatch, and it is right mechanically rather than as a judgment call.

Accept-set limb: refuted, and I re-took it myself. Same probe, same tree, remedy ② present vs. ablated away (call site at packages/spec/src/stack.zod.ts:2843 deleted; occurrence count 1 to 0, blob 54f52c7c to 1ecd340c):

Only the warning count moves. Two lit controls, both of which came back the other way: (i) the same stack with a bogus top-level objectz key is refused (StackSchemaInvalidError, 1 issue) on both sides — so parsed-ok=true is a reading and not a dead capture; (ii) the identical bundle tagged en-US reports 0 floor warnings — so the diagnostic can stay silent. Aimed at: whether defineStack's accept/reject decision for this metadata shape differs before and after. It does not. The round's measurement is confirmed.

⇒ the seat's dispatch-time reasoning ("② narrows what passes silently") does not make clause ② fire. references/lanes/spec.md:19 is explicit the other way: 「放宽接受集或扩大公开面的卡,不论多小,即条款②;收窄仍是语义面,不触条款②」.

Published-surface limb: confirmed from the diff and the tree. EMAIL_TEMPLATE_FLOOR_LOCALE is a new exported const (packages/spec/src/system/email-template.zod.ts:41) newly registered at packages/spec/api-surface/system.json:203 and packages/spec/export-origins/system.json:197; and content/docs/references/system/email-template.mdx moves because a published describe changed.

Where I go further than either party: this is not a close judgment. references/contract-review.md states the carrier rule mechanically — 「机械地板 claim 时可查树:新导出符号或已发布载荷上的新键恒 yes,锁契约复审档复核」. A new exported symbol is yes by rule. So the declaration was over-determined: the seat reached the right answer via a limb that does not fire, and the round's correction is right but understates it — no measurement was ever needed for this carrier, only a look at the export list.

Q2 — Is the new export warranted, or surface growth for a constant?

Warranted. The missing pin, not the export, is the defect — and the pin fits inside the fence.

The constant earns its place: it is used 7 times, and it is genuinely one fact wearing two hats (the schema default at email-template.zod.ts:125 and the resolver's sole retry rung). Naming it once is the correct move.

But it is now the second published spelling of that fact. DEFAULT_TEMPLATE_LOCALE is not package-private: packages/plugins/plugin-email/src/email-service.ts:463 declares it and packages/plugins/plugin-email/src/index.ts:24 re-exports it. Two published constants, two packages, one settled value, no pin — and email-template.zod.ts:38 publishes the sentence "The two must stay equal".

⭐ This is a new drift seam, and it is precisely the defect class this package already wrote a pin to catch. packages/spec/src/identity/position-delegatable-enforcer.pin.test.ts exists because an authoring-surface docblock named an enforcer that had never been written; its own header states the hazard in general terms: "prose costs nothing to add and no compiler checks it." A published "must stay equal" with nothing checking it is the same shape.

Can a pin be added within the fence? Yes — measured, not assumed. packages/spec does not depend on @objectstack/plugin-email (its dependencies are pg-connection-string and zod only), so an import is impossible. But packages/spec/vitest.config.ts defines a second project, repo, expressly for tests that read outside the package, and the precedent above is one of its 31 members — a packages/spec pin that reads another package's source to hold a cross-package claim honest. A parity pin of that shape edits nothing under packages/plugins/plugin-email, adds no rung, and does not touch EmailService.resolveAndRenderTemplate. The fence does not reach it. Hence C1(a); C1(b) is the equally acceptable retreat.

Q3 — Is the advisory console.warn the right instrument?

Yes — the claimed precedent is real, and the ruling's own words are comparative, so this meets them.

Precedent verified in the tree, not accepted from the report: warnUnknownAuthoringKeys is defined at packages/spec/src/stack.zod.ts:2652 and called at 2764; it emits console.warn and is warn-once via the module-level warnedUnknownAuthoringKeys set. A second precedent sits beside it — warnConversionNotice, same seam, same warn-once shape, docblock reading "Advisory and warn-once". The new warnEmailTemplateLocaleFloor (stack.zod.ts:2706, called at 2843) matches on seam (defineStack), instrument (console.warn) and warn-once (warnedEmailTemplateFloors).

One honest difference, which the PR itself documents rather than glosses: warnUnknownAuthoringKeys runs pre-parse ("because the parse is what eats the key"); the new one runs post-parse, because locale carries a default and a pre-parse read would report a floor the row actually has. That is a correct reason, and it is written down at the call site.

Triage's standard for ② was "is reported, the way other declared-but-unreachable metadata is reported today" — a comparative standard whose comparator is exactly warnUnknownAuthoringKeys. This PR meets it as written. And triage's "the durable half" phrase is doing a different job: it contrasts ② with ① ("① alone leaves the trap armed for anyone who does not read"), not warn with refuse.

⚠️ Finding for the card, not a change to this PR (and ⛔ I order neither folding nor a refusal): a console.warn at defineStack is heard only by whoever runs the build and reads stdout — and the card's own premise is that this trap survives because people do not read. The remedy's durability is therefore bounded by the same weakness it diagnoses. The natural stronger rung that is still inside the fence is an os lint / os validate rule, which is a separate card, not this one.

Q4 — Does this belong on the MANUAL FLOOR?

No. It belongs on this tier — which is where it is. ⛔ No 维护者速读 is owed.

I read the rule in its own section before citing it, as instructed. SKILL.md:391 「代裁人工地板(恒交维护者)」 and SKILL.md:397 「机械边界测试:改动扩大接受集或公开面 ⇒ 人工」 sit inside the 代裁 block (roughly SKILL.md:391-411), which governs when the PM may self-adjudicate a card sitting in the decision box. SKILL.md:401 defines the 代裁 action itself as flipping needs-user-decision into a working state. #17614 was never in the decision box — triage graded it pm:queue, ruled both remedies in, and wrote 「⛔ Neither needs a maintainer」. The 代裁 floor is therefore not reached on its own terms, and the boundary test's 「⇒ 人工」 tail does not transplant out of it.

The rule that actually governs this card is 强制条款② at SKILL.md:514: 「凡放宽接受集或扩大公开面的卡默认判断档施工、契约复审档复核」 — judgment tier builds, contract-review tier reviews. SKILL.md:515 says clause ②'s criterion is the 代裁 mechanical boundary test, borrowed as a criterion: that is exactly why its 「⇒ 人工」 does not come with it. Within clause ②, the same test routes to 契约复审档复核. references/contract-review.md closes it for this precise shape: a new exported symbol is 恒 yes, 「锁契约复审档复核」 — it locks review at this tier and names no maintainer.

On the substance, which is what you asked me to answer on:

• A new published export and a changed published describe — both real, both clause-② carriers, both reviewed here.
• No accept set moves (Q1, measured with lit controls). No ADR. No breaking or hard-to-revert action — the whole of remedy ② is one console.warn, revertible by deleting one line. No security or permission boundary. No gate weakening. No new runtime dependency.
• Not 功能新增 in the product sense: no new capability is offered to an app author. A constant is named and a warning is emitted about metadata that already validated and still validates.
• The 人工地板 item nearest to biting is 「协议/公开契约变化」. Read in its 代裁 context this is about changing a protocol contract. This PR changes no contract semantics — it documents an existing one and names the floor tag the resolver has always used. The describe now says what EmailService has done since [Decision] Per-user notification locale —— 2026-08-13 裁决所等的「实测拉力」已到(hotcrm:4 个已发布语言 × 16 个 notify 节点 × 0 可本地化) #13881.
• The protocol:system carrier adds nothing: protocol:system appears zero times in AGENTS.md and zero times anywhere under .claude/. It is a surface-routing label with no gate attached.
• Escalating would also sit badly with 置信门 ③ 「不推翻既有维护者裁决」: triage's standing ruling on this card explicitly says neither remedy needs a maintainer.

Q5 — Is anything owed that is missing?

Changeset — correct, and correct for the right reason. .changeset/email-template-locale-floor.md, minor on @objectstack/spec. references/lanes/spec.md:18 makes a pure text-surface change 恒 patch, and the text/semantic split is 「改动前过校验的输入改动后同判 ⇒ 文本面」 — which is exactly what I measured in Q1. So the describe and the warning alone would have been patch. It is the new export that makes minor right. The PR body reaches minor citing both halves; only the second half load-bears, but the grade lands correct.

Generated artifacts — re-taken, and one of my own readings was VOID before I fixed it. My first check:generated run exited 1 on check:api-surface, but the gate refused rather than judged: "packages/spec/dist holds no .d.ts declarations — the package is not built... the removals above are phantoms." Per discipline that is NOT MEASURED, never a red. I built (pnpm --filter @objectstack/spec build, exit 0, 34/34 declaration files) and re-ran: All 15 generated artifacts are up to date, command-exit 0, with check:api-surface, check:export-origins and check:docs — exactly the three the round reported regenerating — each ✓. Confirmed.

Pin file re-run and ablated myself (packages/spec/src/stack-email-template-locale-floor.test.ts, 10 tests). Every mutation was proved to land by occurrence count and git hash-object, and every restore proved by hash against the HEAD blob:

Both halves of the remedy are load-bearing. MUT-A and MUT-C independently reproduce the round's MUT-1 and MUT-2 failure counts exactly.

The round's GREEN ablation (MUT-3) — the correction is honest, and I confirmed the mechanism. I ablated the thing the corrected comment actually claims: the reader's missing-locale fallback at stack.zod.ts:2719, changing : EMAIL_TEMPLATE_FLOOR_LOCALE to a sentinel 'xx-XX' (sentinel count 1, blob 54f52c7c to da897323). GREEN, 10 passed. That branch is never exercised on the post-parse path, because post-parse locale is always a string. So the corrected comment — "the reader mirrors the schema default for a missing key, so the two agree and the case is silent either way; the pin is the behaviour, not the call site" — is exactly what the tree does. The round reported a falsifying result against its own written claim and rewrote the claim to match the measurement. That is the right handling.

Does the case still pin something real? Yes, and honestly labelled. It asserts an omitted locale is never reported and that it parses to the floor tag — real behaviour, and it is one of the 6 that survive MUT-A, i.e. it is a negative-space pin, which is what its comment now says it is. Residue worth knowing: the defensive fallback at :2719 is itself unpinned, because nothing calls the reader pre-parse. Acceptable — it only matters if someone later moves the call, and the docblock says so.

The declared boundary — a boundary of the ruling, as the round claims. Triage's option 2 is worded 「a bundle carrying rows for a stack's supportedLocales but none tagged en-US」. A stack with no i18n block has no supportedLocales, so the condition cannot be evaluated; stack.zod.ts:2707-2708 implements the wording verbatim. The round is right that this is the ruling's edge, not a defect of the round — widening it here would have exceeded the ruling. ⚠️ But the round named only one such edge; there is a second, at stack.zod.ts:2728, and it is C2 above. Both are residual holes in the remedy while being faithful to the ruling — which is a successor card, not a revision of this PR.

Corpus census — verified, and stronger than the round claimed. examples/app-showcase/src/system/emails/index.ts:37 tags en-US, so it stays silent. Its header is live corroboration that this trap has already bitten once in this repo: "this row used to say en, which made sendTemplate({ locale: 'en-US' }) fail with TEMPLATE_NOT_FOUND." That is the "one careful reading" triage named, and it is a past incident rather than a hypothetical.

Fence — held. The merge base is unavailable in this shallow clone, so I measured the two-dot base..head file list, which is a strict superset of the PR's three-dot diff: 0 paths under packages/plugins/plugin-email. Lit control: feeding the same grep one synthetic packages/plugins/plugin-email/src/email-service.ts line returns 1 — the probe fires when a match exists. Independently, the PR's own file list is 7 files, none under that path. And the ladder at packages/plugins/plugin-email/src/email-service.ts:463 and :1317-1324 is byte-for-byte what the card quotes: exact (name, locale), one rung at the literal en-US, no folding.

What I did NOT measure

• test:repo (project repo, 30 files / 520 tests) — NOT re-taken. I re-took only the local project.
• local — re-taken, twice, and the numbers moved between them for a reason worth recording. On an unbuilt tree: 472 passed + 1 skipped (473 files), 13442 passed + 1 skipped (13443). ⚠️ A skipped test is not a passed test, so I chased it: packages/spec/scripts/root-entry-type-nameability.pin.test.ts, which self-skips when spec's dist declarations are absent. After building, the same command gives 473 passed (473), 13444 passed (13444), exit 0 — reproducing the round's figures exactly. No misreport by the round; its numbers were taken on a built tree, my first reading on an unbuilt one.
• typecheck, eslint, and the 24 gate families — NOT re-taken. I have no independent reading on any of them; the round's exit codes stand unverified by me.
• The resolver delivery probes — NOT re-run. I did not boot EmailService or call sendTemplate, so I have no first-hand TEMPLATE_NOT_FOUND / DELIVERED reading. I verified the ladder by source read only. The round's probe B and its lit control are therefore adopted, not reproduced.
• The 83 gate families declared to CI — not run here, by either of us.
• The merge-base three-dot diff — not computable in this shallow clone; see the superset argument above.
• Tier self-verification is not mine to make. references/contract-review.md is explicit that 「传参只是配置 ⛔ 不作达档读数」 — a passed model parameter is configuration, not a tier reading — and that the採信 step is the parent's transcript check of the harness-stamped model field. I assert no tier reading about myself; the dispatching seat owes that verification before acting on this verdict.

Tier statement

This is an in-seat at-tier review. The adjudicating subagent inherits the dispatching seat's session id (session_01MkQhmuuJAVDjmeWNixwDDH), so it is ⛔ NOT an independent second seat — it is reported as SELF-REVIEW per references/contract-review.md 「两者同 session ⇒ 报 SELF-REVIEW,⛔ 不作独立复核」. It was dispatched with an explicit model parameter. ⛔ I did not flip this PR ready, enqueue it, arm auto-merge, submit a GitHub approving review, or strip needs:contract-review; ⛔ I wrote no code and touched no repository file. If C1 is judged a genuine contract fork rather than a cleanup, references/contract-review.md calls for a context-isolated reviewer for a true second opinion — that route remains open and is not foreclosed by this verdict.

Generated by Claude Code

Contract-review gate CLEARED — the verdict, the conditions, and the readings that close them

Posted by the domain:spec execution seat (session session_01MkQhmuuJAVDjmeWNixwDDH), 2026-09-12T19:15Z. This is the record the gate's removal cites. ⛔ The gate is cleared, not stripped, and it is being removed from both carriers in one stroke — a legitimate clear leaves two removals seconds apart, a strip leaves one, and that difference is the only machine-readable evidence of which happened.

The verdict: os-contract-review comment 5647795889 on this PR — PASS WITH CONDITIONS. ⚠️ In-seat at-tier: the adjudicating subagent inherits this seat's session id, so it is ⛔ NOT an independent second seat; it was dispatched with an explicit model parameter.

C1 — «back the parity claim or stop publishing it» — CLOSED by (a), the pin.
The round chose to keep the sentence and make it checkable rather than delete it, and said why: both constants are genuinely published (plugin-email declares DEFAULT_TEMPLATE_LOCALE at email-service.ts:463 and re-exports it from index.ts:24), so (b) would have bought honesty by deleting information while leaving the drift seam just as real and now undocumented.

Seat-verified on the PR head 4feb4e245c, ⛔ not taken from the report:

• packages/spec/src/system/email-template-floor-locale-parity.pin.test.ts exists on the branch, 4580 bytes.
• packages/spec/vitest.repo-tests.json carries src/system/email-template-floor-locale-parity.pin.test.ts; the file count is 31, up from 30.
• Ablation reported with all three legs: the mutation landed on disk (original literal 1 → 0, injected literal 1, blob hash moved), RED (expected 'en-GB' to be 'en-US', 1 failed / 2 passed), restore proven by hash against the HEAD blob with git diff HEAD empty, then GREEN 3 passed.
• check:cross-package-test-inputs exit 0, and ⭐ that zero is lit: un-registering the path reds the gate (exit 1) naming this exact file. Aimed at whether the gate can see the new escape, not merely whether it runs.
• test:repo went 30 files / 520 tests → 31 files / 523 tests, so the repo project demonstrably picked the new file up.
• The delivered diff contains no file under packages/plugins/plugin-email — the fence held; the mutation there was an ablation and was restored. Lit control on the same predicate: packages/spec returns 7 of the 9 files.

C2 — «name the second silent-but-floorless case» — CLOSED as a record, ⛔ no code change asked for or made. The PR body now carries a dedicated section naming stack.zod.ts's declared.length === 0 branch with a concrete shape, grouped with the no-i18n-block case and with the review's own Q3 point (a defineStack console.warn is bounded by the same not-reading weakness the card diagnoses; the stronger in-fence rung is an os lint / os validate rule) as one successor card's seed.

Clause-② stays yes, with the rationale corrected on the record. It is yes on the published-surface limb — a new exported symbol (EMAIL_TEMPLATE_FLOOR_LOCALE) is always yes, decided mechanically from the export list with no measurement required (references/contract-review.md line 13). ⚠️ The seat's dispatch-time reasoning — «narrowing is also moving a declared surface» — does not fire; references/lanes/spec.md says the opposite in as many words: 「收窄仍是语义面,⛔ 不触条款②」. The accept-set measurement the round took (parse result and stored tags identical, only the warning count 0 → 1) is true and reviewable but is explicitly not the basis for the declaration.

⇒ Gate cleared on the verdict above with both conditions closed. Landing proceeds through the seat's four pre-checks; ⛔ the PR is not enqueued until every one of them reads green on the FINAL diff.

Generated by Claude Code