spec: guard the `confirmText` + `params` PAIR at authoring time, once the 20 shipped sites have migrated to `action.description`

[os-zhuang]

Follow-up split out of #7367 item 5, filed with the census measured rather than folded into that PR. Filed unassigned.

Blocked-by: #7278
Blocked-by: #7309

The structural fix

An action that declares both confirmText and a non-empty params shows the user two sequential dialogs for one decision — the confirm, then the param prompt. That is the defect class #7278 and #7309 are migrating away from, and the maintainer's 2026-08-10 ruling on #7278 gives the correct shape: carry the confirm question in description (now authorable, #7367) so one decision is one dialog.

Migrating the sites fixes today's instances. It does not stop the next one being written. The structural version is an authoring-time guard on the PAIR — the thing that would have prevented all 20 rather than repairing them — which is why #7367's item 5 raised it. This card carries it.

Why it is NOT in #7367, and why it is blocked rather than ready

Censused across the repo on origin/main @ 18ff1dab1: 20 shipped sites declare confirmText beside a non-empty params. (#7309 counts 16 in platform-objects; the four examples/app-showcase actions below are additional, and plugin-approvals contributes the two from #7278.)

File	Line	Action
examples/app-showcase/src/ui/views/project.view.ts	50	set_labels
examples/app-showcase/src/ui/views/project.view.ts	72	assign_team
examples/app-showcase/src/ui/views/project.view.ts	89	reassign_account
examples/app-showcase/src/ui/views/project.view.ts	105	reschedule
packages/platform-objects/src/identity/sys-account.object.ts	84	unlink_account
packages/platform-objects/src/identity/sys-oauth-application.object.ts	69	disable_oauth_application
packages/platform-objects/src/identity/sys-oauth-application.object.ts	89	enable_oauth_application
packages/platform-objects/src/identity/sys-oauth-application.object.ts	141	rotate_client_secret
packages/platform-objects/src/identity/sys-oauth-application.object.ts	166	delete_oauth_application
packages/platform-objects/src/identity/sys-organization.object.ts	151	change_slug
packages/platform-objects/src/identity/sys-sso-provider.object.ts	198	delete_sso_provider
packages/platform-objects/src/identity/sys-team-member.object.ts	70	remove_team_member
packages/platform-objects/src/identity/sys-two-factor.object.ts	93	disable_two_factor
packages/platform-objects/src/identity/sys-two-factor.object.ts	109	regenerate_backup_codes
packages/platform-objects/src/identity/sys-user.object.ts	99	ban_user
packages/platform-objects/src/identity/sys-user.object.ts	364	delete_my_account
packages/platform-objects/src/identity/sys-user.object.ts	403	disable_two_factor
packages/platform-objects/src/identity/sys-user.object.ts	420	generate_backup_codes
packages/plugins/plugin-approvals/src/sys-approval-request.object.ts	291	approval_reject
packages/plugins/plugin-approvals/src/sys-approval-request.object.ts	387	approval_recall

Consequences, which is the whole reason this is a separate card:

• A refusal shipped today breaks 20 shipped declarations before their migration, including the platform's own objects — every project fails to build on metadata it does not own.
• A warn-severity arm does not escape this either. Add description to the action contract (ActionSchema + actionTranslationSchema + i18n extractor) — the maintainer-ruled mechanism for #7278/#7309 #7367's dispatch allowed a warn arm to ride if it caused zero shipped-metadata breakage. It does not: it would fire on all 20, 16 of them platform-objects, i.e. warnings on every build of an untouched project. That is the permanently-noisy-check shape — a check nobody reads.

So the guard is correct and its timing is not. It becomes shippable — refuse or warn — once #7278 and #7309 have migrated their sites and the census reaches zero. Standalone rather than a sub-issue because it merely depends on those cards; the fix does not fall inside either one's completion scope.

Design questions left open for whoever picks this up

Not decided here — they shape the authoring contract and deserve their own read:

1. Severity. Refuse (a .refine on ActionSchema) vs a lint rule. A refusal is contract-first and declared = enforced; a lint rule is recoverable for third-party metadata already in the wild. The census reaching zero in-repo says nothing about third-party stacks.
2. Scope of the predicate. Is confirmText + non-empty params always wrong, or is there a legitimate shape — e.g. a destructive action whose params are all optional? Worth measuring against the migrated sites before encoding, rather than presuming.
3. Whether the guard should also require description when params is present, or only forbid the pair. The ruling's "one condition, one wording" argues the former; that is a strictly bigger authoring demand and should be measured.

Verification note for the eventual fix

The census above was produced by a brace-balanced scan for confirmText inside an object literal carrying a non-empty params: array, excluding node_modules, dist and test files. Re-run it as the acceptance check: the guard is ready to ship when it returns 0.

Refs: #7367 (the description key this depends on), #7278 (ruling + the two approvals actions), #7309 (the platform-objects census), objectui#3126 (renderer-side precedent).

---

Generated by Claude Code

[claude]

Findings triage: reclassified — finding removed, now pm:blocked + domain:spec (the body already carries the machine half: Blocked-by: #7278 / #7309).

• Why blocked rather than held: this is not an open observation — the direction is ruled (the maintainer's 2026-08-10 approvals: sys_approval_request.approval_reject / approval_recall declare both confirmText and params, so one decision opens two sequential dialogs #7278 ruling: the confirm question moves into description, one decision one dialog) and the work is fully specified (authoring-time guard on the confirmText + non-empty params pair, 20-site census in the body). Its only precondition is the migration itself: a guard landed before platform-objects: 16 more actions declare both confirmText and params, so one click opens two sequential dialogs (same shape as #7278) #7309's sites move would go red on 20 shipped declarations. That is pm:blocked's exact shape, and it puts the card on the unlock sweep's reverse index instead of in a hold comment nobody greps.
• Routing: an authoring-time guard on the pair changes which author declarations are accepted ⇒ the acceptance-surface red line ⇒ domain:spec. If the lane lands it lint-only (no zod/gate acceptance change), flag for re-route rather than relabeling.
• Unlock note: when platform-objects: 16 more actions declare both confirmText and params, so one click opens two sequential dialogs (same shape as #7278) #7309 closes, re-verify the 20-site census at the merged ref — the migration is exactly the commit most likely to have changed the file face.
• Dedup: Add description to the action contract (ActionSchema + actionTranslationSchema + i18n extractor) — the maintainer-ruled mechanism for #7278/#7309 #7367 (the description key, queued), approvals: sys_approval_request.approval_reject / approval_recall declare both confirmText and params, so one decision opens two sequential dialogs #7278 (ruled), platform-objects: 16 more actions declare both confirmText and params, so one click opens two sequential dialogs (same shape as #7278) #7309 (census/migration, blocked) — this is the guard card that family explicitly split out. Clean.

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

---

Generated by Claude Code

[os-zhuang]

⚠️ Correction to this card's census AND its acceptance check — measured on #7309, not inferred

#7309 landed as PR #7827 (accepted, awaiting merge). The packages/platform-objects half is done: 14 sites migrated, that census is now 0. But its dev measured something that changes this card's target set and its exit condition, and it needs to be fixed here before anyone builds the guard.

The 4 examples/app-showcase rows in the table above are NOT this defect

set_labels, assign_team, reassign_account, reschedule in project.view.ts are bulkActionDefs, validated by BulkActionDefSchema — not ActionSchema. Two independent measurements, both with bogus-key controls so a green line proves the slot exists rather than the probe missing:

BulkActionDef: confirmText+params (today)    => success=true
BulkActionDef: description (the #7278 slot)  => success=false  unrecognized_keys `description`
BulkActionDef: bogus key (control)           => success=false  unrecognized_keys

(a) The remedy has no slot — description is not a recognised key on that schema, so the migration this card presumes cannot be performed on those 4 sites.

(b) They are not the defect. Per the schema's own contract a bulk def renders one dialog: params are "inputs collected once before the run", confirmText is "shown above the affected-record summary", and decisively, a required param "blocks the Confirm button until a value is present." A param cannot block a button in a dialog that has not opened yet — so params and confirm are one dialog, and confirmText + params is the intended pairing on that surface.

Three consequences for this card

1. The census table above overcounts. Its 20 = 14 platform-objects + 4 showcase + 2 plugin-approvals. The plugin-approvals 2 are gone (approvals: sys_approval_request.approval_reject / approval_recall declare both confirmText and params, so one decision opens two sequential dialogs #7278 merged) and the platform-objects 14 are gone (fix(platform-objects): one decision, one dialog — carry identity confirm questions on description (#7309) #7827). The 4 showcase rows should be struck from the guard's target set, not left pending.

2. The stated acceptance check is unsatisfiable as written. "The guard is ready to ship when [the census] returns 0" can never be true, because those 4 sites are correct and will not migrate. Re-specify it as: the ActionSchema census returns 0 — which, once fix(platform-objects): one decision, one dialog — carry identity confirm questions on description (#7309) #7827 merges, it does.

3. The guard must be scoped to ActionSchema and must not fire on bulkActionDefs. A predicate written against the raw confirmText + params: [ key-pair — exactly the scan this card specifies as its acceptance check — lands red on 4 correct sites on day one. That is the permanently-noisy-check shape this card was explicitly filed to avoid.

This also answers open design question 2, with a measurement

The card asks: "Is confirmText + non-empty params always wrong, or is there a legitimate shape — worth measuring against the migrated sites before encoding, rather than presuming."

Measured answer: there is a legitimate shape, and it is the bulk-action surface. The distinction is not "params all optional" as the card guessed — it is which schema renders the pair into how many dialogs. Encode the guard on the schema boundary, not on a heuristic about param optionality.

Design questions 1 (refuse vs lint — third-party stacks are not covered by an in-repo census reaching zero) and 3 (whether to also require description when params is present) are untouched by this and remain open for whoever takes the card.

Status

Staying pm:blocked until #7827 merges — that is the trigger, and at that point Blocked-by: #7278 and Blocked-by: #7309 are both satisfied.

Two more notes from #7309's scan, useful when writing the predicate: the raw key-pair search over-reports on schema definition files (action.zod.ts, bulk-action.zod.ts, translation.zod.ts all declare both keys) and on generated translation bundles (where params is a record, not an array). Requiring params: [ separates them.

---

Generated by Claude Code