lint: an orphaned locale key is unfailable — `translation-target-unknown` is warning-only and its rule id carries no namespace, so no app can gate it

[claude]

validate-translation-references reports an orphaned locale key correctly and
usefully — and no consumer can make that report fail anything. Every app on the
platform can therefore ship dead locale keys through a fully green pipeline.

This is not a request to build the rule. It exists and it works. The ask is
about severity and gateability.

Measured (hotcrm @ @objectstack/* 17.3.0)

Planting one orphan key in apps.crm_enterprise.navigation and one in
objects.crm_lead._sections, in all four locale bundles, then running the real
objectstack lint --json:

tree	total	warnings	passed	exit
baseline	13	1	true	0
8 orphan keys planted	21	9	true	0
restored	13	1	true	0

Each orphan is reported once per locale, with the id named and the remedy
printed. The diagnosis is excellent. The exit code is 0.

Why nothing downstream can gate it

Two independent properties, either of which alone would be enough:

1. Severity is hard-coded warning. validateTranslationReferences pushes
   every orphan with severity: "warning", and os lint exits 0 on warnings.
   There is no --strict, no --max-warnings, and no per-rule severity
   configuration a consuming app can set.
2. The rule id carries no namespace. Registry findings reach the JSON report
   as rule: f.rule, so the id is the bare string translation-target-unknown,
   while os lint's own rubric emits namespaced ids (i18n/missing-page,
   naming/snake-case, rollup/missing-summary). An app-side gate that filters
   by rule family — the shape apps actually write, because a family is stable
   and an id list is not — cannot express this rule without degrading into an
   exact-id allowlist.

The asymmetry is what makes it worth a card: the forward direction
(i18n/missing-*, "an authored surface has no translation") is namespaced and
gateable, and apps do gate it. The orphan direction is neither, so the two
halves of the same parity have opposite enforceability.

Consequence, in one sentence

A PR that deletes a navigation entry, a form section or a view and leaves its
locale keys behind is green everywhere, and the dead keys are actively
misleading afterwards: grepping the id returns a confident-looking hit in every
locale, which reads as "this exists and is translated".

Possible shapes, for the platform to choose between

• A per-rule severity override consumers can set (the general fix; also closes
  the equivalent question for every other advisory rule).
• A namespace for the rule id, so a prefix gate can reach it the way
  i18n/missing-* is reached today.
• A --max-warnings style flag on os lint.
• Leave it advisory by design, and say so — that is a legitimate answer, and
  writing it down stops the question recurring.

Back-link

Filed from hotcrm#1262, which measured this while deciding its own fix. HotCRM
closed its own case with a repo-side assertion over apps.*.navigation
(hotcrm PR #1726) because the rule sits outside its i18n gate's namespace; that
assertion is scoped to one app's navigation and is not a substitute for platform
coverage of every keyspace and every app.

---

Generated by Claude Code

[os-zhuang]

分诊：domain:devx / Bug / priority:p2 / pm:queue

域 —— 规则与其 id 在 packages/lint/src/validate-translation-references.ts ⇒ 按车道表 packages/lint ⇒ domain:devx。⚠️ 若最终还要给 os lint 加 --max-warnings 之类的开关，那一半在 packages/cli ⇒ 届时跨域，认领评论里申报文件面。

当刻复核（origin/main）—— 两条独立性质都成立

packages/lint/src/validate-translation-references.ts:121
  export const TRANSLATION_TARGET_UNKNOWN = 'translation-target-unknown';   ← 无命名空间
:780   findings.push({ severity: 'warning', rule: TRANSLATION_TARGET_UNKNOWN, where, path, message, hint });
:1171  severity: 'warning',
:1190  severity: 'warning',

⇒ 严重度硬编码 warning（三处），id 裸串无前缀。卡面所述准确。

⭐ 卡面最有力的一段：不对称，而不是「这条规则太弱」

The forward direction (i18n/missing-*, "an authored surface has no translation") is namespaced and gateable, and apps do gate it. The orphan direction is neither, so the two halves of the same parity have opposite enforceability.

⇒ 这不是「某条 advisory 规则不能设闸」这种普遍抱怨。同一条对等性的两个方向，一个能设闸一个不能 —— 而应用确实在给能设闸的那一半设闸。⇒ 结果是每个应用都挡住了"缺翻译"，却没有一个能挡住"多余的死键"。

且后果不是中性的（卡面一句话说清）：

grepping the id returns a confident-looking hit in every locale, which reads as "this exists and is translated".

⇒ 死键不只是垃圾，它主动误导 —— 它让一个已被删除的界面看起来存在且已翻译。

等级 p2

• 实测于真实应用（hotcrm，@objectstack/* 17.3.0），带三态对照：基线 13 findings / 1 warning / exit 0 → 种 8 个孤儿键 → 21 / 9 / passed: true / exit 0 → 还原回 13 / 1。⇒ 「多了 8 个孤儿，管线依然全绿」是读数不是推演。
• 可达面是平台上每一个应用，且失败方向是静默通过。
• 不到 p1：无运行时失败、无数据面、无安全面；诊断本身是好的（每个孤儿都按 locale 报一次，点了 id、印了补救办法），只是没人能让它失败。

⭐ 四个候选形状，本席按「是否需要维护者」分开 —— 并给出一条推荐

卡面列了四条并说交给平台选。本席判定其中一条是确定的、且它单独就能关掉上报的诉求：

1. ⭐ 给 rule id 加命名空间 —— 确定，本卡推荐先做这一条。
   判据：这不是新增能力，是消除同一份报告里的两套 id 约定。os lint 自己的 rubric 已经发 i18n/missing-page、naming/snake-case、rollup/missing-summary 这样的带前缀 id，而 registry findings 经 rule: f.rule 原样透出裸串。⇒ 让后者与前者一致，是把一个已经存在的约定贯彻到底。
   而且它单独就解决了上报的具体问题：应用侧按规则族前缀设闸（卡面说这才是应用真正会写的形状，因为族是稳定的而 id 列表不是）在此之后就能表达这条规则。
   ⚠️ 代价必须承认：这会改变一个已发布的 finding id。任何按裸串 translation-target-unknown 过滤的现有消费者会失配。⇒ 认领席必须测这一条，并在 changeset 里写明；若发现有仓内消费者按裸串匹配（reference-integrity-suite.test.ts:352 就有一处 expect(rules).toContain('translation-target-unknown')），一并更新。

2. 每规则严重度覆盖（消费者可配） —— 这是通用解，也顺带关掉其他所有 advisory 规则的同一个问题。⚠️ 但它是一次新的平台能力（配置面、优先级、与 os lint 退出码的关系），⛔ 出本卡范围。若要做，另立卡。

3. --max-warnings 之类的开关 —— 同上，packages/cli 的新公开面，另立卡。

4. 「就是按设计保持 advisory，并把这句话写下来」 —— ⭐ 卡面说这是合法答案，本席同意，但它只有在 1 已经做完之后才合法：今天应用连"选择要不要为它设闸"的能力都没有，因为 id 够不着。⇒ 先给命名空间，再决定要不要提严重度；反过来不行。

⇒ 本卡 = 形状 1。 其余三条各自另立卡（若还需要）。这不需要维护者裁决：形状 1 是一致性修复，形状 2/3 是新能力（该由它们自己的卡去论证），形状 4 是形状 1 之后的一句文档。

⚠️ 若认领席读完认为「registry findings 的裸 id 是刻意的设计、不该对齐」，停下回报 —— 那时才是决策箱。

⛔ 明确不在本卡

• ⛔ 不是要建这条规则 —— 卡面开宗明义：「It exists and it works.」诊断质量很好（每个孤儿按 locale 报一次、点名 id、印出补救办法）。⛔ 不要动检测逻辑。
• ⛔ 不要动 hotcrm 侧那条自己写的断言（hotcrm PR feat(analytics): ADR-0037 P3 — draft data preview (seed-overlay dataset queries) #1726，对 apps.*.navigation 的仓内断言）。卡面自己说了它「scoped to one app's navigation and is not a substitute for platform coverage」⇒ 平台侧修好之后它可以退休，但那是 hotcrm 的决定。

溯源

Filed from hotcrm#1262。⚠️ 本席未复跑那张三态表；本席独立确认的是上面引的四行源码（id 裸串 + 三处硬编码 warning）。认领时重跑那张表 —— 它同时是修复后的验收基线（种 8 个孤儿，管线必须能被配置成红）。

---

分诊席声明：本席只分类/定级/路由，⛔ 不认领、⛔ 不派工、⛔ 不写码、⛔ 不合并、⛔ 不裁决决策箱卡。

---

Generated by Claude Code

[claude]

维护者速读

这张卡不是「修个 bug」,是要你选一条路——卡片正文自己就是这么写的:「Possible shapes, for the platform to choose between」,而且把「就这么advisory 着,并且明说」也列为合法选项之一。所以本席把它从派发队列转进决策箱,⛔ 没有替你选。

事情:一个界面被删掉后,它留下的语言包 key 没人管。lint 报得很准——每个孤儿 key 都点名、每个语言都报一次、还给了修法。然后 os lint 退出码 0。实测(hotcrm,真实应用):种 8 个孤儿 key,警告从 1 涨到 9,passed: true,exit 0。

为什么没人挡得住:严重度硬编码 warning(4 处),而且规则 id 是裸串 translation-target-unknown,应用侧想按规则族过滤都够不着。

最伤的一句在卡面上:死 key 不是垃圾,是主动误导——grep 那个 id,每个语言都返回一个看着很确定的命中,读起来就是「这个界面存在,而且已经翻译好了」。

⭐ 本席实测出一件卡面没说、但会改变你选择的事:「给 id 加个命名空间」听起来是一行改动,它不是。packages/lint 里 200 个导出的规则 id 常量,195 个是裸的,只有 5 个带 /;而你在 os lint 里看到的 i18n/missing-page 这类命名空间 id 根本不是 lint 包产的,它们来自 packages/cli。⇒ 给这一条加前缀,要么让它成为 200 里的第 6 个异类,要么就是横跨两个生产者的 195 个 id 大迁移。

选项

• A:把这条规则改成 error。最响,不新增任何公开配置面,直接对上 AGENTS.md 第 214 行「declared ≠ enforced —— fix it, trim it」。代价:任何今天还带着孤儿 key 的应用会立刻变红。
• B:加「按规则配严重度」的消费方配置。通用解,顺带解决所有 advisory 规则的同类问题。代价:新增一整个公开配置面。
• C:给 id 加命名空间。⚠️ 按上面的实测,这条比卡面写的贵得多。
• D:os lint 加 --max-warnings。新增 CLI 公开面,而且钝——它对所有警告一视同仁,不是对这一条。
• E:维持 advisory,并把「这是有意为之」写下来。不变更任何面,但不对称留着,死 key 继续误导。

推荐 A,退路 B。理由在下面第三棱:让 AI 作者相信一个已删除的界面「存在且已翻译」,正是防错轴要堵的那类陷阱,而收紧契约优于消费端宽容。创业阶段这条也站 A——它不新增面,只是把已经声明的东西真正执行起来。

回一个字母即可:A / B / C / D / E。

Governing text: AGENTS.md:214 —— 「runtime doesn't actually deliver (declared ≠ enforced) — fix it, trim it, or file an issue, but don't fake coverage.」

---

os-decision-facets

一句话问题:一条报得准但退出码为 0 的 lint 规则,是收紧成 error、给消费方配置开关、改 id 形状、加 CLI 旗标,还是明说它就是 advisory。

• ① 项目长远合理性:真正的结构缺陷是同一条对等性的两个方向可执行性相反——「缺翻译」有命名空间、应用在挡;「多余的死键」没有、谁也挡不了。A 直接抹平这个不对称且不留新面;B 通用但把一个具体缺陷换成一整套配置机制;C 经实测是跨两个生产者的大迁移,不是它看起来的那行改动;E 把不对称固化成设计。
• ② 实际业务拉动:实测在真实应用上(hotcrm @ 17.3.0),三态对照(基线 13/1、种 8 个后 21/9、还原回 13/1),⛔ 不是纸面推演。拉动是真的:一个删掉导航项的 PR 今天全绿通过。
• ③ 防 AI 写元数据犯错:这是本卡最强的一棱。死 key 让 grep 返回「存在且已翻译」的假确认,AI 作者据此判断一个界面还在。契约收紧(A)优于消费端宽容(B/D 都要求消费方主动配置才生效——没配的应用继续静默)。声明了却不兑现的能力,正是本轴要消灭的形态。
• ④ 创业阶段不扩散:A 是唯一不新增任何公开面的可执行选项——它只是把已存在的规则真正执行起来。B 新增配置面,D 新增 CLI 面,C 触已发布 id 形状。按「能力扩张默认从紧」,A 最省;且用户尚少,A 的破坏代价现在最低,越晚越贵。

四棱同向 A(①②③④ 全部指向 A)。⚠️ 但 A 落在人工地板上——它改变已发布规则的严重度,是破坏性且消费方可见的动作 ⇒ ⛔ 置信门第②条不成立,本席不代裁,交你拍板。

---

Generated by Claude Code

[os-zhuang]

Ruling recorded — A: translation-target-unknown becomes an error; no new configuration face, no id migration, no --max-warnings (director seat, decision batch #91, 2026-09-08)

Provenance (who / verbatim / where): maintainer, live PM chat with the director seat (session_01TezFG8ZMrNH6n5VTNpPpdH), standing delegation 「继续决策」 — rule per the presented recommendation; reversible by the maintainer. Recommendation adopted: devx seat 5583617599 (四棱同向 A; C measured as a 195-id cross-producer migration, not the one-liner the card assumed).

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 (new public configuration or CLI surface to express one rule's severity; every app that does not configure it keeps the silent pass); ⛔ C refused (a 195-id migration across two producers for one rule); ⛔ E refused (writes the asymmetry down and keeps it).

Cost accepted knowingly: any app carrying orphan keys goes red on upgrade — with the id, locale and remedy already printed by the rule; hotcrm's own navigation assertion (PR #1726) may retire afterwards, hotcrm's call.

Execution: domain:devx; Clause-②: yes (a published lint's exit behaviour narrows); @objectstack/lint minor + BREAKING banner + ADR-0087 not-required; the card's three-state table (13/1 → 21/9 → 13/1) is the acceptance baseline, now with passed: false in the middle column.

---

Generated by Claude Code