spec(governance): rename body-level status on check_governance and report_plan_outcome (#4897)

[bokelley]

Closes #4897.

Summary

Frees the top-level status key for envelope task-status (TaskStatus) under MCP flat-on-the-wire serialization. The body-level governance field and the envelope share a root key but carry different enums; whichever wins on the wire, the other is silently destroyed and no validator catches it.

WG-recommended Option A per the issue triage (both ad-tech-protocol-expert and adtech-product-expert converged):

• check-governance-response.json: status → verdict (enum unchanged: approved | denied | conditions)
• report-plan-outcome-response.json: status → outcome_state (enum unchanged: accepted | findings)
• get-plan-audit-logs-response.json: entries[].status → entries[].verdict (vocabulary cascade)

Other status fields on the same response shapes (plans[].status, governed_actions[].status) are lifecycle states, not verdicts — left unchanged.

Scope

Surface	Files
Schemas	static/schemas/source/governance/{check-governance,report-plan-outcome,get-plan-audit-logs}-response.json
Docs (~25 example bodies + tables + prose)	docs/governance/overview.mdx, docs/governance/campaign/{audit-trail,specification}.mdx, docs/governance/campaign/tasks/{check_governance,report_plan_outcome,get_plan_audit_logs}.mdx
Migration note	docs/reference/whats-new-in-3-1.mdx (Final-spec clarifications batch)
Storyboards	static/compliance/source/specialisms/governance-{spend-authority,delivery-monitor}/*.yaml, static/compliance/source/protocols/governance/index.yaml
Test fixture	tests/composed-schema-validation.test.cjs

Storyboard sweep correction: the issue triage scoped storyboards as "no yaml renames needed." During implementation found four storyboards with field_present / field_value assertions keyed on path: "status" against check-governance-response.json — updated to path: "verdict". Also corrected one stale expected block in protocols/governance/index.yaml that referenced status: recorded (not in the schema enum) → now outcome_state: accepted.

Adopter impact

Wire-shape change on three experimental governance schemas (x-status: experimental). Buyers and sellers rename one property name per emitter / consumer; enum values are unchanged. SDK regen required for @adcp/client, adcp-go, and the Python client. Per the experimental-surface contract, this is a sanctioned 3.1 pre-GA adjustment.

Test plan

• npm run build:schemas — clean
• npm run build:compliance — clean (all storyboard lints that key on the verdict path now resolve)
• npm run test:schemas — 8/8
• npm run test:examples — 36/36
• npm run test:composed — 43/43 (one pre-existing failure on report_plan_outcome accepts replayed fixed by updating the fixture to use outcome_state)
• npm run test:json-schema — 270/270
• npm run test:rejection-arm-mutex — 4/4
• npm run test:docs-nav — 15/15
• npm run test:storyboard-doc-parity — 0 fail
• npm run test:storyboard-contradictions — 0 fail
• npm run test:storyboard-validations-paths — 1 pre-existing failure unrelated to this change (brand-rights/governance_denied.yaml; verified on origin/main)
• npm run test:storyboard-context-output-paths — 1 pre-existing failure on main (sales-guaranteed)
• npm run test:storyboard-sample-request-schema — 1 pre-existing failure on main (native_in_feed)

Related

• spec(envelope): require status on every task response envelope (closes #4832) #4876 — envelope status REQUIRED (beta.2)
• Envelope status (TaskStatus) collides with payload status (MediaBuyStatus) at the same top-level key on create/update/cancel_media_buy #4895 — companion media-buy status/MediaBuyStatus collision (separate PR)
• spec: fold protocol-envelope into per-task response schemas (closes #4878) #4896 — per-task envelope fold; carve-outs for check-governance-response.json and report-plan-outcome-response.json can be dropped once this merges — both schemas pick up the standard envelope fold cleanly

🤖 Generated with Claude Code

[aao-release-bot]

LGTM. Clean rename, comprehensive sweep, sound rationale. Frees status for the envelope task-status while preserving the lifecycle status fields on plans[] and governed_actions[] — that disambiguation is the load-bearing part.

Things I checked

• check-governance-response.json:11-74 — all three if/then discriminator blocks rekeyed on verdict; every if.properties.verdict paired with verdict in if.required; original conditions → require conditions+minItems:1, denied → require findings+minItems:1, approved|conditions → require expires_at semantics reproduced exactly. No stale status keys leftover.
• check-governance-response.json:216 — required: [check_id, verdict, plan_id, explanation] correctly carries the renamed field.
• report-plan-outcome-response.json:18-25,89-92 — outcome_state (right shape — accepted | findings is a state, not a verdict; reusing verdict would have been wrong), enum unchanged, required[] updated.
• get-plan-audit-logs-response.json:258 — entries[].verdict cascade with $ref to /schemas/enums/governance-decision.json. plans[].status and governed_actions[].status correctly preserved as lifecycle states.
• verdict choice cross-checked against existing AdCP idiom — content-standards/calibrate-content-response.json and enums/binary-verdict.json use the same vocabulary.
• Changeset type minor against x-status: experimental on all three schemas — consistent with prior experimental-surface renames (#4196, #4796) and with the documented contract at docs/reference/experimental-status.mdx.
• Storyboard sweep — governance-spend-authority/{index,denied}.yaml, governance-delivery-monitor/index.yaml, protocols/governance/index.yaml all consistent; the stale status: recorded block in protocols/governance/index.yaml:601 (value never in the enum) correctly corrected to outcome_state: accepted.
• docs/reference/whats-new-in-3-1.mdx:202 covers the rename, calls out the experimental-surface justification, lists migration steps.
• CI: Storyboards (/governance) and Server integration tests both green at current floors.

Follow-ups (non-blocking — file as issues)

• Cascade miss: entries[].outcome_status. get-plan-audit-logs-response.json:346 still defines a free-string outcome_status on outcome entries — surfaces the same concept as the renamed outcome_state on report_plan_outcome. The PR rationale explicitly invokes vocabulary consistency for the entries[].verdict cascade; the symmetric outcome-side cascade is missing. Either rename to outcome_state and constrain to the same enum, or add one sentence to the schema description naming the deliberate divergence.
• summary.statuses is now misleading. get-plan-audit-logs-response.json:91 keeps the property name statuses but its keys are approved | denied | conditions | human_reviewed — i.e. it counts verdicts. After this PR, the rest of the file calls those "verdicts." summary.verdicts (or verdict_counts) restores consistency; the doc table at get_plan_audit_logs.mdx:229 inherits the same word-overload.
• Training-agent server still emits the old field names. server/src/training-agent/governance-handlers.ts:1312 (handleReportPlanOutcome → status:), :1498 (handleGetPlanAuditLogs entries → status:), :1641 (buildCheckResponse → status:). CI is green because the runtime validates against SDK-bundled schemas, not in-repo source — but once @adcp/sdk regens off this PR, the server stops conforming. Sequence: rename in the SDK regen, then flip the three emission sites and the ~25 assertion sites in server/tests/unit/training-agent.test.ts. Worth a tracking issue so it doesn't fall through the cracks between SDK and server.
• 6-week notice anchor. Experimental-surface contract requires notice; the changeset should cite the date or the issue (#4897) as the clock-start. Reads as wire-shape change with no notice attestation today.

Minor nits (non-blocking)

1. Status values heading survived. docs/governance/campaign/tasks/check_governance.mdx:88 still reads ## Status values and the table column header at L90 is | Status |. The prose underneath (L95, L102) was correctly migrated to "verdict" — the heading and column header are the stragglers.
2. Triage scope. The issue triage initially scoped storyboards as "no yaml renames needed" — four storyboards needed renames. Worth noting for future spec-rename triages; the wire-shape change always cascades into field_present / field_value assertions, even when the storyboard runner's lint suite doesn't catch them upfront.

Approving. The cascade miss on outcome_status is the one I'd want resolved before 3.1 GA — file it as a follow-up so the experimental-surface contract isn't paying down a second rename later.