spec: rename body-level status discriminator on check_governance and report_plan_outcome (3.1 GA)

[bokelley]

Surfaced during the per-task schema fold in #4896.

Problem

Two task response schemas have body-level `status` fields whose enums collide with envelope `status` (task-status enum from `enums/task-status.json`):

• `governance/check-governance-response.json` — body `status` enum: `[approved, denied, conditions]`. Governance verdict.
• `governance/report-plan-outcome-response.json` — body `status` enum: `[accepted, findings]`. Outcome accept state.

Envelope `status` enum (A2A task lifecycle): `[submitted, working, input-required, completed, canceled, failed, rejected, auth-required, unknown]`.

Why it matters

Per `protocol-envelope.json` notes: under flat-on-the-wire MCP serialization, envelope-level fields and body-level fields occupy the same root key. Two distinct fields named `status` cannot coexist at the same root.

#4896 excluded these two schemas as carve-outs to avoid breaking conformance immediately, but the conflict needs resolution before 3.1 GA.

Fix

Rename the body-level discriminator on both schemas:

• `check_governance`: `status` → `verdict` (or `decision`). "approved / denied / conditions" is a verdict, not a task-lifecycle state.
• `report_plan_outcome`: `status` → `outcome_state` (or fold into a discriminated oneOf via `findings.length`).

After the rename:

• The carve-out from spec: fold protocol-envelope into per-task response schemas (closes #4878) #4896 reverts (both schemas pick up the standard envelope fold).
• Adopters migrate one field name on the schemas they implement.

Adopter impact

Wire-shape change. SDK regen required. Pre-GA window is the right time — once 3.1 ships GA with the current shape, the rename becomes a major-version migration.

Suggested approach

1. Settle on the new field name per schema (WG discussion).
2. Update each schema: rename property, update enum, update conditional if/then blocks that key on `status`.
3. Update docs in `docs/governance/` task references with the new field name.
4. Update SDK codegen tests and any compliance storyboards that assert on this field.
5. Revert the carve-out in spec: fold protocol-envelope into per-task response schemas (closes #4878) #4896's protocol-envelope fold.
6. Mark in `whats-new-in-3-1.mdx` as a pre-GA wire-shape adjustment.

Related

• spec(envelope): require status on every task response envelope (closes #4832) #4876 — envelope status REQUIRED (merged in beta.2)
• spec: fold protocol-envelope into per-task response schemas (closes #4878) #4896 — per-task envelope fold (this PR; carved both schemas out)
• adcp-client: emit status on auto-registered get_adcp_capabilities handler #4877 — adcp-client SDK companion

[bokelley]

Concrete inventory (from PR #4896 carve-out analysis)

Schemas to rename:

• static/schemas/source/governance/check-governance-response.json — properties.status ($ref to governance-decision.json, enum: approved | denied | conditions). Used in 3 if/then conditionals.
• static/schemas/source/governance/report-plan-outcome-response.json — properties.status (inline enum: accepted | findings).

Enum file: static/schemas/source/enums/governance-decision.json — filename can stay; the rename is on the property that uses it, not the enum name.

Docs files with example bodies that need the field rename (verified file:line):

• docs/governance/overview.mdx:135 (1 occurrence)
• docs/governance/campaign/tasks/report_plan_outcome.mdx (5 occurrences at lines 60, 78, 131, 140, 180)
• docs/governance/campaign/tasks/get_plan_audit_logs.mdx (2 occurrences at lines 138, 154 — these are nested check_governance results inside audit log entries)
• docs/governance/campaign/tasks/check_governance.mdx (7 occurrences at lines 291, 307, 323, 337, 361, 386, 407)
• docs/governance/campaign/audit-trail.mdx (7 occurrences)
• docs/governance/campaign/specification.mdx (3+ occurrences)

Storyboards: none reference the body status as a hardcoded value — all are narrative-level mentions of the task name. No yaml renames needed.

Cascade surface to check during rename:

• get-plan-audit-logs-response.json summary.statuses — aggregates governance-decision values into a counter (with the human_reviewed extension). The aggregator keys probably stay as the existing enum values; only the response property name changes. Verify during the actual rename.

Proposal for WG (decide field names before sweep)

Option A — descriptive verbs:

• check_governance.status → verdict
• report_plan_outcome.status → outcome_state

Option B — neutral nouns:

• check_governance.status → decision
• report_plan_outcome.status → acknowledgment

Option C — drop report_plan_outcome.status entirely:

• Use findings: [] array presence (length > 0) as the implicit discriminator. check_governance still needs a rename (Option A or B).

My weakest preference: Option A for clarity and parallelism with existing protocol vocabulary ("verdict" reads naturally for a yes/no/conditional decision; "outcome_state" is awkward but accurate). Open to either A or B at WG sync.

Migration steps (once field names are settled)

1. Schema rename: properties.status → new name on both schemas, including any if/then blocks that key on the discriminator.
2. Enum file: keep governance-decision.json as-is; rename only the property that $ref's it.
3. Docs sweep: ~25 example bodies across 6 mdx files.
4. Revert carve-out in spec: fold protocol-envelope into per-task response schemas (closes #4878) #4896 — both schemas can now $ref protocol-envelope.json cleanly.
5. Mark in whats-new-in-3-1.mdx as a pre-GA wire-shape adjustment with old → new field mapping.
6. SDK regen + adopter migration note.

Total touch: ~10 files + the 2 schemas. Bounded but WG sign-off required on the field names before sweep. Filing for the next WG sync.

[bokelley]

Triage

Classification: Spec change — body-level discriminator rename on experimental governance schemas
Bucket(s): spec / protocol, governance
Status: ready-for-human
Milestone: 3.1.0 (experimental surface → minor bump, targets main)

What the experts said:

• ad-tech-protocol-expert: Option A — verdict is load-bearing AdCP vocabulary already in calibrate-content-response.json and validate-content-delivery-response.json; using decision would introduce an orphan synonym for the same concept. outcome_state is novel but unambiguous; acknowledgment misrepresents a field that carries severity-graded findings, not a simple receipt. Option C is structurally unsound: breaks the existing if/then discriminator pattern and forces every consumer to inspect payload depth to determine state. Blocker on C; nit on A vs B.
• adtech-product-expert: Option A — verdict maps cleanly to the legal/regulatory register operators use in ad approval flows (if verdict == approved, proceed reads naturally); acknowledgment (Option B) is semantically sharper for a receipt-style response but risks opening a "should this be a boolean?" debate the WG doesn't need pre-GA. Option C creates silent misclassification risk (array presence vs empty array vs missing key are three different states). Blocker on C; nit on A vs B.

My take: Option A is the clear recommendation. Option C is off the table (two expert blockers: protocol-structural regression + operator misclassification risk). The one soft open is whether report_plan_outcome.status should be outcome_state (A) or acknowledgment (B) — protocol coherence slightly favors outcome_state since acknowledgment undersells the severity signal; product usability slightly favors acknowledgment for the receipt mental model. Once the name is settled, scope is bounded: 2 schemas + ~25 doc occurrences across 6 MDX files + revert the carve-out in #4896.

@bokelley, your call: Option A (verdict + outcome_state) or Option B (decision + acknowledgment)?

---

Option A — experts' recommendation:

// check_governance response
- "status": "conditions"  // old — collides with envelope status
+ "verdict": "conditions" // new — aligns with content-standards corpus

// report_plan_outcome response
- "status": "findings"      // old
+ "outcome_state": "findings" // new

Option B — neutral nouns:

// check_governance response
- "status": "conditions"
+ "decision": "conditions"

// report_plan_outcome response
- "status": "findings"
+ "acknowledgment": "findings"

(Option C — drop report_plan_outcome.status — rejected by both experts as a blocker.)

---

Triaged by Claude Code. Session: https://claude.ai/code/session_01LMwMPFAR2GonDHRQZz3YVA

---

Generated by Claude Code

[bokelley]

Diff drafts ready — recommending Option A

Picked up alongside #4895 (same envelope-fold root cause). Drafted both schema diffs against current main.

governance/check-governance-response.json

@@ "allOf" if/then blocks @@
-          "status": { "const": "conditions" }
+          "verdict": { "const": "conditions" }
-        "required": ["status"]
+        "required": ["verdict"]
   (repeat for "denied" and the approved/conditions enum block)

@@ properties @@
-    "status": {
-      "$ref": "/schemas/enums/governance-decision.json"
+    "verdict": {
+      "$ref": "/schemas/enums/governance-decision.json",
+      "description": "Governance verdict: approved | denied | conditions. Renamed from `status` in 3.1 to free the top-level `status` key for the envelope task-status (TaskStatus). The enum values are unchanged; only the property name moved."
     },

@@ required @@
-    "status",
+    "verdict",

Prose refs to "Present when status is …" on findings (l.97), conditions (l.148), expires_at (l.174) need status → verdict in description text — same line, no structural impact.

governance/report-plan-outcome-response.json

-    "status": {
+    "outcome_state": {
       "type": "string",
       "enum": ["accepted", "findings"],
-      "description": "'accepted' means state updated with no issues. 'findings' means issues were detected."
+      "description": "Outcome state. 'accepted' means state updated with no issues. 'findings' means issues were detected. Renamed from `status` in 3.1 to free the top-level `status` key for the envelope task-status (TaskStatus)."
     },

-      "description": "Issues detected. Present only when status is 'findings'.",
+      "description": "Issues detected. Present only when outcome_state is 'findings'.",

@@ required @@
-    "outcome_id",
-    "status"
+    "outcome_id",
+    "outcome_state"

Side note: prose refs to "Present for 'completed' and 'failed' outcomes" on committed_budget (l.28) and plan_summary (l.64) look stale — those values aren't in the outcome_state enum. Worth filing separately; out of scope for this rename.

Sweep scope (verified)

• 2 schemas (above)
• ~25 doc occurrences across 6 MDX files in docs/governance/ (per inventory in spec: rename body-level status discriminator on check_governance and report_plan_outcome (3.1 GA) #4897 first comment)
• Revert spec: fold protocol-envelope into per-task response schemas (closes #4878) #4896 carve-out → both schemas can $ref protocol-envelope.json cleanly
• Note in whats-new-in-3-1.mdx as pre-GA wire-shape adjustment
• No storyboard YAML changes (verified)
• governance-decision.json enum file stays as-is — rename is on the property, not the enum

Open ask

Confirm Option A (verdict + outcome_state) over Option B (decision + acknowledgment). Both experts recommended A. Once confirmed I'll file the PR.

[bokelley]

Triage — update

Option A confirmed. Schema inspection validates the diffs:

• Both schemas carry "x-status": "experimental" — ships as minor on main, no further WG gate needed.
• check-governance-response.json has 3 allOf if/then blocks keying on status (conditions branch at lines 12–31, denied branch at lines 32–53, approved/conditions branch at lines 54–74). Your diff's "(repeat)" note is correct — verify all three are covered in the sweep. Missing one would leave the conditional logic pointing at a field that no longer exists in required.
• report-plan-outcome-response.json has no if/then conditionals — simpler property + required rename. Diffs look structurally complete.
• Both schemas use additionalProperties: true, so pre-rename status payloads won't hard-reject during the migration window — worth a one-liner in the PR body as an adopter grace note.

Stale committed_budget / plan_summary prose ("Present for 'completed' and 'failed' outcomes") is confirmed out of scope — those values aren't in the outcome_state enum. Agree: file separately.

Removing needs-wg-review — the call is made. Good to file.

---

Triaged by Claude Code. Session: https://claude.ai/code/cse_01QhvErLoPNfZFLb3BZZT1hM

---

Generated by Claude Code