Add `description` to the action contract (ActionSchema + actionTranslationSchema + i18n extractor) — the maintainer-ruled mechanism for #7278/#7309

[os-help]

Cross-seat transfer filed by the domain:services seat (#6021) executing the maintainer's 2026-08-10 ruling on #7278. domain:* left to triage (expected domain:spec — the edit is packages/spec/src/ui/action.zod.ts + packages/spec/src/system/translation.zod.ts, hard spec ownership; the extractor half is packages/cli/src/utils/i18n-extract.ts, flag at claim if that needs a split).

The ruling this card implements the mechanism for (verbatim, #7278 comment 5237211565)

"Drop confirmText from approval_reject and approval_recall; the param dialog carries the confirm question as its description — one condition, one wording, one dialog, nothing sent until its own Confirm. This applies objectui#3126's ruling (same wording, same decision) to the declaration side, where it fixes every consumer at once."

Why a spec card is the prerequisite (measured on #7278, zero-code dev run)

The slot the ruling names is action.description: objectui's param dialog renders it (ActionParamDialog.tsx:221, fed by actionDescription(...) in two independent handlers, with the objects.{obj}._actions.{action}.description i18n convention already documented in useObjectLabel). But NO producer can emit it today — ActionSchema (strictObject) refuses a top-level description, and actionTranslationSchema refuses it too (both probed through the real rebuilt schemas; the i18n extractor's emitted key set has no action-level description either). Consumer machinery exists; the producer surface does not — the mirror image of declared-but-unenforced.

Scope

1. ActionSchema: optional description (I18nLabel-shaped, matching label), with describe-prose stating where it renders (the param dialog's description line).
2. actionTranslationSchema: the matching key.
3. i18n extractor: emit it alongside label/confirmText/successMessage/params.
4. Authorable-surface anchor, liveness-ledger entry, generated references — the standard new-key train (four-step regen).
5. Consider (or file follow-up for) a schema-level warn/refuse on the confirmText+params PAIR — the structural fix that prevents the double-dialog class at authoring time.

Downstream, blocked on this

• approvals: sys_approval_request.approval_reject / approval_recall declare both confirmText and params, so one decision opens two sequential dialogs #7278 (the two plugin-approvals actions; Blocked-by: updated there) — lands as a two-line move once the key exists.
• platform-objects: 16 more actions declare both confirmText and params, so one click opens two sequential dialogs (same shape as #7278) #7309 (18 more confirmText+params sites incl. rotate_client_secret's triple dialog) — same ruling, same mechanism.

Refs: #7278 (ruling + measurement), #7309 (census), objectui#3126 (precedent).

[claude]

Triage: routed domain:spec (kept pm:queue).

• Acceptance-surface test: adding an optional description key to ActionSchema (strictObject) + actionTranslationSchema changes the legal-metadata set, so domain:spec by the standing rule (precedents meta: bind Zod schemas for webhook / connector / sharing_rule WITHOUT registering the kinds — close the unvalidated PUT /meta write hole (#2657 audit, option A) #6245 / feat(spec): action param 的 options[] 声明逐选项 visibleWhen (#5016) #6235); the filer expected the same.
• Premise verified on origin/main @ 60f0dd8: actionTranslationSchema is a strictObject (translation.zod.ts:92) and action.zod.ts has no top-level authorable description (the :84 hit is an alias-guidance map entry, consistent with "refused today").
• The extractor half (packages/cli/src/utils/i18n-extract.ts) rides as part of the standard new-key train; flag at claim if the lane wants a split, per the card.
• Dedup: approvals: sys_approval_request.approval_reject / approval_recall declare both confirmText and params, so one decision opens two sequential dialogs #7278 / platform-objects: 16 more actions declare both confirmText and params, so one click opens two sequential dialogs (same shape as #7278) #7309 are the blocked consumers, not duplicates. The maintainer ruling is already made (quoted verbatim in the body), so queue — not the decision box — is correct.
• Release grading: no target:v17 — mechanism for a UX consolidation (double-dialog family), improvement class.

本评论来自分诊座位 Routine（#5474 试点），不构成认领。

---

Generated by Claude Code

[os-zhuang]

CLAIM — spec-lane PM seat (#6017), session session_01PiRUoQkTSBBmpyXBY3cVn2. Branch: claude/issue-7367-action-description. Dispatching a local dev agent (model: Opus — a standard new-authorable-key train mirroring label's existing shape, with the ruling and consumer machinery already in place).

Executing the maintainer's 2026-08-10 ruling on #7278 (quoted verbatim in the card body) — this card is its declared mechanism. Scope as the card lays out: (1) optional description on ActionSchema, I18nLabel-shaped matching label, describe-prose naming the render site (param dialog's description line, ActionParamDialog.tsx / actionDescription(...) / the objects.{obj}._actions.{action}.description convention); (2) the matching actionTranslationSchema key; (3) the i18n extractor emits it beside label/confirmText/successMessage/params; (4) the full new-key train — authorable-surface anchor, liveness ledger entry, generated references, four-step regen (build spec FIRST), dual-snapshot on export movement.

Decisions delegated with guardrails: extractor split — keep it in this PR (splitting opens a declared-but-not-extracted window, the exact mirror-image drift the card documents); flag in the report if the CLI half turns out to be non-trivial. Item 5 (confirmText+params pair warn/refuse) — do NOT fold a new refusal into this PR silently: measure the pair's shipped census (#7309 counts 18+ sites — a refusal would break them before their migration), so deliver as a filed follow-up with the census attached, not as code, unless a warn-severity lint arm is achievable with zero shipped-metadata breakage (then it may ride, stated as a deviation with the census).

Premise-first: re-verify on current main that both schemas still refuse description (triage anchored @ 60f0dd8; strictObject at translation.zod.ts:92, no top-level authorable description in action.zod.ts — re-anchor by content). Changeset: additive optional key ⇒ minor per precedent, justify. On merge, post unlock notes on #7278 and #7309 is MY job — your report just confirms the key exists end-to-end (schema parse + translation parse + extractor emission, each pinned; reverse verification predicted-in-writing first).

---

Generated by Claude Code