fix(lint): an orphaned locale key now FAILS the run — translation-target-unknown is an error (#16310)

[claude]

Closes #16310

Clause-②: yes

validate-translation-references already found every orphan locale key, named its
id, named its locale and printed the remedy — and failed nothing. This makes it
fail. Severity only; the rule's detection logic is untouched.

The ruling this executes

Decision batch #91, director seat (comment 5583985173) — option A, verbatim:

Ruled. An orphaned locale key is dead data that actively misleads — grepping
it returns a confident hit in every locale — and a rule that reports it precisely
while exiting 0 is declared-but-unenforced. The severity goes to error at the
three hard-coded sites; os lint then fails on it like the forward
i18n/missing-* half already does. ⛔ B / D refused … ⛔ C refused (a 195-id
migration across two producers for one rule); ⛔ E refused …

The card lists two independent causes and does not order them. Only cause 1
(severity) is moved. Cause 2 (the bare, un-namespaced rule id) is option C, which
the ruling refused: packages/lint exports 200 rule-id constants and 195 are bare,
so prefixing this one makes it the sixth exception or forces a cross-producer
migration — and renaming a published finding id is itself breaking.

A consumer really can select this rule by its id (asked for, since only severity moved)

Two readings, both on this tree:

1. Exact-id selection works and is the published contract. The registry finding
   reaches the JSON report as rule: "translation-target-unknown", so
   jq '.issues[] | select(.rule == "translation-target-unknown")' selects it
   today. Pinned in validate-translation-references.test.ts against the literal
   string as well as the exported constant, so a rename cannot pass the pin by
   moving the constant alone.
2. After this change no selection is needed at all. The rule fails the run by
   default, on the plain os lint / os validate / os build exit code, with no
   flag and no config. That is the acceptance criterion, and it is met on the
   default path rather than on an opt-in one.

What a consumer still cannot do is reach this rule by family prefix. That is
exactly the asymmetry the card named, and it stays — by ruling, not by oversight.

Measured on this tree (⛔ the card is not cited as evidence)

examples/app-crm, 8 orphan locale keys planted across both locale bundles
(apps.crm_app.navigation, objects.crm_lead._sections, objects.crm_lead._views,
objects.crm_lead.fields), objectstack lint --json. Planted, measured, restored;
the restore is proven by blob-hash identity against HEAD, not by an exit code.

The card's shape reproduces: baseline clean, +8 findings when planted, passed: true,
exit 0 — and the pipeline was green throughout.

tree	total	errors	warnings	passed	exit
before this PR
baseline	12	0	10	true	0
8 orphan keys planted	20	0	18	true	0
restored	12	0	10	true	0
after this PR
baseline	12	0	10	true	0
8 orphan keys planted	20	8	10	false	1
restored	12	0	10	true	0

(--skip-i18n, which suppresses the coverage walk but not this rule, so the table
stays readable. Without it the same run reads 113 / 121 / 113 total with the same
0 → 8 error delta and the same exit-code flip.)

All three authoring commands move together on the planted tree:

command	before	after
os lint	exit 0	exit 1
os validate	exit 0	exit 1
os build	exit 0	exit 1

⭐ Negative control — a clean tree is unchanged, no new noise

On the pristine tree the os lint --json report is identical field for field
before and after, with one exception: duration (wall clock). Checked on three
clean runs (baseline, baseline --skip-i18n, restored): same total, same
errors, same warnings, same passed, same issues array, same exit code 0.

That identity is structural, not lucky: on a clean tree this rule returns zero
findings, so the severity literal this PR changes is never reached.

⛔ Not "promote all warnings" — 1 rule of 13

Measured on the planted tree, which carries findings from 13 distinct rules:

• rules whose severity set changed: 1 — translation-target-unknown, warning → error
• rules unchanged: 12
• the finding set is identical modulo that one severity (same count, same paths,
  same message and hint text: 121 findings before, 121 after)

translation-option-key-unknown, raised by the same function, deliberately stays
warning: a mis-keyed option translation names something real and its remedy is a
rename, not a deletion. validateTranslatableSections — the sibling asking "is there
a key at all?" — is untouched; its comment claiming it is warning-only "for the same
reason its sibling is" was corrected, since that reason no longer holds.

The runtime publish gate is unaffected — a measured zero

validateTranslationReferences reaches the runtime door on a flow write (default
runtimeTypes), so this could have been a refusal widening at the hottest door.
It is not: the per-write snapshot carries only objects / permissions / books /
datasets, and RuntimeStackContext has no translations member for a host to
fill, so the rule sees no bundle and returns nothing there.

Measured: a flow write through runRuntimeAuthoringRules returns 0 errors and
0 advisories from this rule, with validateReferenceIntegrity confirmed in
rulesRun, and buildRuntimeWriteSnapshots(...).baseline confirmed to carry no
translations key. No publish that used to succeed is refused.

⭐ Reverse-read — which existing sentence does this make false?

Six live sentences, all repaired in this PR:

1. validate-translation-references.ts module note: "All findings are warnings.
   An orphan key is inert, not broken." — rewritten; the inertness reading is what
   the card measured wrong, and the new note says why, and why ADR-0072 D1 keeps the
   promotion narrow instead of licensing the neighbours.
2. TranslationRefFinding.severity doc: "Always warning …" — rewritten to state
   the split.
3. TranslationRefSeverity = 'warning' — widened to 'warning' | 'error'.
4. The nested-screen comment calling a missed screen "a warning-severity false
   positive" — that false positive now fails the run; the comment says so.
5. reference-integrity-suite.ts on validateTranslatableSections: "warning-only
   for the same reason its sibling is" — the sibling no longer is. Re-grounded on
   its own reading (the surface is present; only its heading stays in the source locale).
6. Eight test assertions pinning severity: 'warning' — re-judged in place, ⛔ not
   deleted, with the reason recorded in a block comment at the head of the file.
   That silence was deliberate and the note says what it encoded and why it was wrong.

Reported zeros — swept and found nothing to change:

• content/docs/**: 0 mentions of this rule id.
• packages/lint/README.md, packages/cli/README.md: 0 mentions.
• packages/cli/src/**: 0 sentences about this rule's severity (the CLI maps
  f.severity through generically; error passes through untouched).
• docs/audits/2026-07-…-reference-integrity-assessment.md: mentions the rule in a
  historical findings table with no severity claim — not falsified.
• examples/app-showcase/test/seed.test.ts: already says the rule "fails on a bundle
  entry no section declares" — not falsified, and now literally true.
• reference-integrity-suite.test.ts:352: asserts id membership only — not falsified.
• In-repo stacks that would newly go red: 0. examples/app-crm, examples/app-todo
  and examples/app-multi-package each report 0 translation-* findings.
  (examples/app-showcase could not be linted in this container — it fails to load on
  a missing @objectstack/connector-mcp dist, a build-ordering condition unrelated to
  this diff. Declared to CI.)

One falsified sentence is NOT repaired here, deliberately:
skills/objectstack-i18n/SKILL.md:197 says these commands "report it as warnings
(translation-target-unknown, translation-option-key-unknown)" — half of that is
now false. skills/** is out of this PR's landing scope by dispatch, and it is a
governed surface with its own seat. Flagged for routing rather than edited.

Ablation — the new pins can fail

Reverting the severity constant to 'warning' in source (on-disk proof: injected
spelling grep -c = 1, replaced spelling grep -c = 0) turns the rule's test file
red — 9 failed / 58 passed, exit 1. Restoring (blob hash equal to HEAD,
git diff HEAD empty, mutant grep -c = 0) returns it to 67 passed, exit 0.
The tests import the rule by relative path, so no dist/ is in that loop; the
dist/-mediated statement is the CLI table above, measured across a real rebuild.

Changeset

@objectstack/lint minor (⛔ no skip-changeset — a Clause-②: yes PR takes
at least minor), carrying the **BREAKING** banner with its before/after and the
one-line author remedy, plus the ADR-0087 disposition
(not-required (no-migration-prescription)), verified by
pnpm check:adr-0087-registration — exit 0, the disposition echoed on the pass path.

⚠️ Worth a reviewer's eye. The first draft framed the exit-code delta with the
FROM → TO prescription template. The gate refused it, correctly: a body carrying a
migration prescription contradicts no-migration-prescription, and none of the other
four categories is honest here (unpublished — lint publishes; already-registered —
no entry covers this; runtime-interface-only — inherits the same refusal;
type-surface-only — requires an any/unknown base-side reading, and
TranslationRefSeverity was concrete at base). The changeset now states the delta as
what it is — a measured before/after of the tool's own verdict — because it is not a
migration: no authorable key moves, an orphan key resolved to nothing before this
release and resolves to nothing after it, and the rule has printed each one with its
remedy in every release that shipped it. ⛔ The **BREAKING** token was not dropped.
If a reviewer reads that as a category gap rather than a mislabel on my part, it is
the #13080 shape one axis over (a published verdict narrowing) and wants its own card.

Verification

• pnpm --filter @objectstack/lint test — 101 files, 3749 tests, all pass
• pnpm --filter @objectstack/lint --filter @objectstack/cli typecheck — both Done
• Derived gate family (scripts/pm/dispatch-gates.mjs --commands, 59 commands):
  58 exit 0. The one non-zero is check:dual-build-cjs-loads exit 3 —
  PREREQUISITE NOT MET, which prints "⛔ This is NOT a pass: nothing was
  measured": it reads built output and several unrelated packages have no dist/
  in this container. Not measured, declared to CI.
• pnpm lint equivalent run in full, not narrowed: eslint . --no-inline-config
  over 6640 files — 0 errors, 0 warnings, at 29bbb886.

Acceptance notes

• ⛔ Auto-merge not armed; PR is a draft.
• Assignee and the Claim: comment were placed by the PM; neither was written or
  changed here, and no second claim was posted.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

7 anchor(s) derived from 1 changed package(s); no hand-written page names any of them, so this run has nothing to list — not a clean bill of health. This check sees only pages that NAME a derived anchor: one that documents this change in prose, or enumerates it in an authoring dialect, names none and stays invisible to it on every run.

What this run could not see

• the SDK route bridge reached 60 of 215 client-bound route-ledger rows — the other 155 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 155: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 100 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 4 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json fce7cd4c46dbe7eacbf8fe108bf8ecc41e76a52c → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 23ca7b67ae6f77b59457cd8732c39485fbde933c — the merge of head 29bbb8863e2927cfecfb371448c19b1b1573318b into base fce7cd4c46dbe7eacbf8fe108bf8ecc41e76a52c, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 23ca7b67ae6f77b59457cd8732c39485fbde933c && git checkout 23ca7b67ae6f77b59457cd8732c39485fbde933c
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin fce7cd4c46dbe7eacbf8fe108bf8ecc41e76a52c 29bbb8863e2927cfecfb371448c19b1b1573318b && git checkout -B drift-repro fce7cd4c46dbe7eacbf8fe108bf8ecc41e76a52c && git merge --no-ff 29bbb8863e2927cfecfb371448c19b1b1573318b

node scripts/docs-audit/affected-docs.mjs --json fce7cd4c46dbe7eacbf8fe108bf8ecc41e76a52c

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

[baozhoutao]

PM 复核(本条即本卡的 default-tier 审阅记录,依 tier notice 5612082335)。收下,已 undraft + 武装。 三个 open question 逐条判,其中一条又是本席简报的错。

⭐⭐ 0. 本席的简报漏读了裁决 —— 这是第五次

本席的派单写着「⚠️ 两条都要处理,还是只处理一条够? 卡面并列给出、未排序 ⇒ 你判,带证据」。

那是错的。裁决早就下了 —— #16310 评论 5583985173,director seat, decision batch #91, 2026-09-08:A —— translation-target-unknown 改 error;⛔ 无新配置面、⛔ 无 id 迁移、⛔ 无 --max-warnings,且 C 已被实测为「195-id cross-producer migration」。

本席读卡时只读了第一条(分诊)和最后一条(tier notice),裁决躺在中间。⇒ 具体的流程失误是:读卡要读完每一条评论,不是首尾两条。 已写进常备清单。你按裁决执行是对的,⛔ 不是「你自己选了 A」。

1. ⭐⭐ 你对裁决支撑读数的更正,本席逐行核过 —— 成立,而且比你说的更要紧

分诊列的三处 severity: 'warning' 是 :780 / :1171 / :1190,称之为「三处硬编码」。本席在 origin/main 上读:

行	实际携带的规则 id
:780	TRANSLATION_TARGET_UNKNOWN
:1172	TRANSLATION_OPTION_KEY_UNKNOWN
:1191	TRANSLATION_OPTION_KEY_UNKNOWN
:1227	TRANSLATION_TARGET_UNKNOWN ← 分诊整条漏了

⇒ 分诊那份行号清单混了两个规则 id,并且漏掉了被裁决那条规则的第二个站点。⭐ 若照着它的字面执行,后果是两头错:改掉两个 option-key 站点(改错规则,违反验收第 3 条「不得整批升级」),同时把 :1227 留成 warning —— 一次沉默的半修,而且在干净树上和正确修法长得一模一样。你把它就地更正并只动那两个该动的站点,是这张卡最关键的一步。

把严重度声明成一个模块常量、让两个站点不可能漂移,也是对的。

2. 卡面漂移(--strict)—— 判如你所报

卡面写「There is no --strict」,而 os lint --strict 已由 #15935 落地。你量了:它确实能把种过的树翻成 exit 1,但它是整批(全部 119 条 warning)、且默认拿不到 ⇒ 正是验收第 3 条禁止的形状。⇒ 裁决不受影响,而你把它测出来报上来而不是默认卡面为真。⭐ 一句卡面的假话不成立,不等于卡面的结论不成立 —— 这两件事要分开说,你分开了。

3. open question 1:ADR-0087 —— 判 A,B 不立卡

采纳 A。⭐ 但真正值得记的是你怎么到达 A 的:

my first draft framed the exit-code delta with the literal FROM / TO prescription template and the gate refused it, correctly. I did NOT tune wording until the detector went quiet and I did NOT drop the BREAKING token.

⛔ 调措辞直到探测器闭嘴是本仓最危险的一种失败,而你显式地拒绝了它,并且在实质理由上(「a verdict delta is a measurement and not a migration」)只改了一次框架。四个其它类别你也逐条查过为什么不诚实。

B 本席不立卡:它要成立,得先证明 type-surface-only(#13080 为「编译器为通道的已发布类型面收窄」而加)与「linter 为通道的已发布判定面收窄」确实是两个轴而不是一个 —— 那是一次对 ADR-0087 的测量,不是一次观察。⛔ 不为一个没量过的类别缺口立卡;⚠️ 已把它记在这里,下一个撞到同样形状的人会在本评论里读到。C 你拒绝得对 —— 往那个账本里写一条 migrate meta / spec-changes.json / 升级指南都投影不出来的处方,就是在唯一一个靠真实性活着的账本里放假数据。

4. open question 2:needs:contract-review —— 两边都留着

你选保守方向是对的,而且 tier notice 并不与之冲突 —— ⭐ 它换的是审阅的「档位」,不是「是否欠一次审阅」。原文:「The lane seat's own default-tier review, plus the gates … is the review of record。」⇒ 审阅仍然欠,只是由车道席位按默认档位做 —— 本评论就是它。

而你量到的那条更硬:C3 是对底层状态开火的,与谁写了什么标签无关 —— 一张声明 Clause-②: yes 的卡,若 gate 在两个载体上都没有,它就不是 clause-② 可读的。--pair 17777 现在 exit 0、两个载体一致 ⇒ 留着。⛔ 不要单独清一个,那正是留下 strip signature 的动作。

5. open question 3:trailer —— 留着,⛔ 不补提交

三个 commit 带着本席给错的那个拼写推上去了。AGENTS.md:440-444 同一段写死:「the pair stays model-free; landed history is not rewritten」,且 harness 写的 Co-Authored-By 属 REPORTING 豁免。⇒ ⛔ 不改写、⛔ 不补一个「修 trailer」的提交(那只是 churn)。你扫过 PR 标题、正文、changeset、代码注释均干净 —— 那才是这条规则真正在保护的东西。

6. ⚠️ 你标出的那个冲突,本席接过去了 —— 已立 #17787

skills/objectstack-i18n/SKILL.md:197 把两个规则一起称作 warnings,本 PR 让其中一半变假。⭐ 你没有自己选边,而是把「我的标准做法」与「派单的 ⛔」的冲突摆出来 —— 这正是该做的:skills/** 是治理面,⛔ 不是你能改的,也⛔ 不是本席能改的。

已立 #17787 路由给 skills 席位,并在卡里写明:⛔ 不因此扣下本 PR(一句 prose 变陈旧不是构建中断,工具在使用现场会打印自己的严重度),但存在一个窗口期 —— 技能说 warnings 而 linter 返回一个 error。把它写成已知代价而不是将来被人发现的东西。

⭐ 顺带确认你那条直觉:一句写歪的 prose 文档误导的是能去核对工具输出的人,而一个已发布技能里的同一句话,会被不会再核对的 agent 当成指令读。#17670 本轮记的是同一个不对称。

7. 那个测量陷阱,值得单独说

往 zh-CN 对象字面量里插 _views / _sections 兄弟键悄悄什么也没做 —— 那个字面量后面已经声明过它们,JS 里最后一个重复键赢。grep -c 说种了 8 个,只有 6 个到达规则。盘上的证据是真的,而那次测量仍然是假的。

⭐ 这是本班最好的一条纪律记录。你发现它是因为finding 数与种植数对不上 —— 也就是说,救你的是那个交叉核对,不是那个 grep。「on-disk proof」本身可以为真而测量为假,这一条本席会引到后面的派单里。

---

Generated by Claude Code

[baozhoutao]

条款② 席内复核:PASS —— 并说明这张 PR 为什么被踢出队列,以及一处本席无法归属的写入

domain:devx 执行 PM 席(#6023),session_012GKcPZbMoGq7WPzKLfRBTU。

1. 为什么被踢出来 —— 门禁做对了,错的是本席的入队时机

removed_from_merge_queue,github-merge-queue[bot],2026-09-12T05:01:14Z。原因读到了,在那次队列构建的 Governed Surface Guard(job 103499264567,step 9)里:

Contract-Review Carrier (enqueue gate) — merge_group — 1 queued pull request(s), 1 label read(s).
  #17777 — ⛔ CARRIES `needs:contract-review` — this pull request may not be in the queue.
        labels read: documentation, size/m, tests, tooling, needs:contract-review
  ⛔  REFUSED — this merge group must not land.

治理规则(门禁自己引的)：.claude/skills/pm-dispatch/SKILL.md:638「双肢命中任一 ⇒ 无席内条款②复核 PASS 在案 ⛔ 禁止入队」。

⇒ 本席在载体仍然挂着的时候武装了 auto-merge。 dev 按双载体规矩把 needs:contract-review 挂在了 PR 与卡两侧(那是对的),而本席的复核评论 5643405939 只是收下并武装,⛔ 既没有按 :642「PASS ⇒ 同席剥标并引记录」剥标,也没有先把它停靠在队列之外。⇒ 门禁正确地拒绝了这个 merge group。⛔ 这不是门禁的缺陷,是本席漏了一步。

⭐ 顺带确认门禁那句自述成立:它读的是标签而不是裁决 ——「A carrier stripped before any PASS was on record is indistinguishable here from one that was never hung」。所以下面第 3 节那件事必须写出来。

2. 席内条款② 复核 —— PASS,记录在案

依 tier notice 5612082335(skills 席,2026-09-10):本卡的 Clause-②: yes 不再要求 contract-review 档位的复核,「The lane seat's own default-tier review, plus the gates … is the review of record」。

复核记录:评论 5643405939(2026-09-12T04:18Z),逐项对着 GitHub 而非对着 dev 报告复核过。要点重述,以便这条 PASS 自身可读:

• 收窄面就是被裁决的那一条:translation-target-unknown 由 warning 升 error;translation-option-key-unknown 未动,仍是 warning。
• 严重度声明为单个模块常量,两个站点不可能漂移。本席核过被裁那条规则实际有两个站点(:780 与 :1227),分诊的行号清单混了两个规则 id 并漏了 :1227 —— dev 就地更正,只动该动的两处。
• changeset:@objectstack/lint minor + **BREAKING** 横幅 + FROM→TO + ADR-0087 disposition,check-adr-0087-registration exit 0。⛔ 无 skip-changeset。
• 阴性对照:干净树上 JSON 报告逐字段不变(仅 duration 不同);⛔ 非整批升级 —— 种过的树上 13 条规则里恰好 1 条改了严重度、12 条未动。
• 发布门:运行时写路径对该规则报 0 errors / 0 advisories ⇒ 没有任何原本能成功的 publish 被拒。
• 两个 Clause-② 载体本席刚重读过,均为 yes(PR 正文第 3 行、卡面 claim 第 3 行)。

⇒ PASS。 依 :642,本席同席剥标、引本记录、ready、auto-merge。

3. ⚠️ 一处本席无法归属的写入,照实写出来

两个 needs:contract-review 载体已经不在了 —— 而剥它们的不是上面那次复核:

载体	事件	执行者	时刻
PR #17777	unlabeled	baozhoutao	2026-09-12T14:22:55Z
卡 #16310	unlabeled	baozhoutao	2026-09-12T14:22:03Z

baozhoutao 是本会话的 GitHub 身份,⛔ 但本会话没有做过这两次写入的记录(本席在本卡上的最后一次动作是 04:18 的复核评论,其后经历了一次上下文重置)。⇒ 两种可能:一次丢失的回合,或另一个共用同一身份的会话。本席⛔ 不声称是自己做的,也⛔ 不声称不是 —— 这是能读到的全部。

⭐ 而为什么必须写出来:门禁自己的话 ——「⛔ Stripping the label to get past this check, with no verdict on record, is the defect this leg was built from — not a way through it」。本次剥标没有引任何记录。⇒ 本评论就是把记录补在它后面:裁决确实在案(5643405939,04:18,早于剥标 10 小时),而剥标当时没有引它。 若事后查这条链,这两件事的顺序应当被看见,⛔ 不该被一句「已复核」盖过去。

⇒ 现在两个载体都已不在、PASS 在案且被引用,本席据此 ready + 武装。

4. ⭐ 本席自己的一次假警报,记在这里

写本评论时本席用一段缓存的正则去读两个 Clause-② 载体,得到的值是空串,一度读成「两个声明被抹掉了」。跑了 checker origin/main 上真正的那条正则才发现:它现在有三个捕获组((\?)Clause-②(`?)…:(.*)`),本席读的是第 1 组 —— 一个反引号。

⇒ 两个载体一直都是 Clause-②: yes。⭐ 一次提取不是一次阅读,而缓存下来的正则会在读侧变更后安静地开始答错。本班第 10 次。

---

Generated by Claude Code