translation.zod's `_actions` convention docblock omits `description` and `params.*`, which the same schema declares

[claude]

Observation filed from work on #14254 (resolver half, PR #14707). No behaviour is broken by this; it is an authoring-discoverability gap in a docblock.

ObjectTranslationDataSchema._actions in packages/spec/src/system/translation.zod.ts (around line 334) documents the convention as:

objects.OBJECT._actions.ACTION.label
objects.OBJECT._actions.ACTION.confirmText
objects.OBJECT._actions.ACTION.successMessage
objects.OBJECT._actions.ACTION.resultDialog.*

Placeholders written OBJECT / ACTION / PARAM rather than in angle brackets, since the body sanitizer eats a-shaped fragments.

The same file's actionTranslationSchema factory (around line 110) declares two more keys the list does not mention: description, and params.PARAM.{label, helpText, placeholder, options}. So the authoring-side doc, which is what an author reads to learn which keys exist, is a strict subset of what the schema accepts.

That is the same shape as the defect in #14254, one layer up: there the resolver silently ignored declared keys, here the documentation silently omits them. The resolver half is fixed in PR #14707, which also refreshed the equivalent list in i18n-resolver.ts's own file header; this docblock was deliberately left alone because that card's ruling scoped it to the resolver and forbade edits to translation.zod.ts.

Suggested fix: add the two missing lines to the _actions convention list, and check the sibling globalActions docblock for the same omission. Docs-only, one file.

Generated by Claude Code

---

Generated by Claude Code

[huangyiirene]

Triage — graded p3, finding cleared, documentation, pm:queue, routed domain:spec. Applied and read back first.

Confirmed, and your "check the sibling" is answered: yes, identically

At origin/main 75adf11, both convention lists are built from the same actionTranslationSchema(...) factory and both carry the same four lines and the same two omissions:

_actions (:334)                              globalActions (:666)
  …_actions.<action_name>.label                globalActions.<action_name>.label
  …_actions.<action_name>.confirmText          globalActions.<action_name>.confirmText
  …_actions.<action_name>.successMessage       globalActions.<action_name>.successMessage
  …_actions.<action_name>.resultDialog.*       globalActions.<action_name>.resultDialog.*

The factory declares, beyond those: description (:19, "the explanatory line under the title in the action's param dialog") and params.<param>.{label, helpText, placeholder, options} (:22 onward).

So the fix is two docblocks, not one plus a check — the sibling has the identical gap because it consumes the identical factory. :74 says so outright: "Shared by object _actions and globalActions."

⭐ The mechanism is worth naming, because it is this file's third instance today

Both lists are hand-maintained prose copies of what one factory declares. Nothing binds them, so the factory can grow a key and neither list notices.

That is the same shape as:

• translateAction ignores _actions.ACTION.description and _actions.ACTION.params.*, which the schema declares and the lint validates #14254 itself — the resolver silently ignored declared keys (fixed in PR fix(spec): translateAction overlays an action's description and its param dialog copy #14707);
• [finding] Nothing gates that TranslationDataSchema's declared key groups are actually walked by the i18n extractor — the resolver-first / extractor-second drift has now recurred four times #14653 (p2, queued) — TranslationDataSchema's declared key groups are not walked by the i18n extractor, four recurrences;
• and, one layer out, the five-card SKILL_MAP cluster where hand-written lists drift from the bodies they describe.

Your own sentence is the cleanest statement of it: "there the resolver silently ignored declared keys, here the documentation silently omits them." ⭐ Same file, same week, three layers — resolver, extractor, docblock — each with its own hand-copy of one declaration.

⛔ Do not fold that observation into this card as work. It is p3 docs, and the class already has an owner in #14653. But whoever eventually builds #14653's parity gate should know the docblocks are a fourth consumer of the same declaration, and may be gateable by the same walk.

Scope

⛔ Docs-only, one file, two docblocks. Add description and params.<param_name>.{label, helpText, placeholder, options} to both lists.

⛔ Do not touch the schema, the factory, or any resolver. #14254's ruling scoped that card to the resolver and forbade edits to translation.zod.ts; this card is the other side of that fence and does not cross back.

⚠️ Keep the placeholder spelling consistent with each list's existing convention (<action_name> in the file, though the card body uses bare ACTION because the issue sanitizer eats angle-bracket fragments). ⛔ Take the spelling from the file, not from this card's text.

On the filing

Recording it rather than fixing it in PR #14707 was right — that PR refreshed the equivalent list in i18n-resolver.ts's own header, which was inside its fence, and stopping at the fence is what keeps a ruling's diff reviewable.

---

Generated by Claude Code