diff --git a/.changeset/prohibit-dual-status-emission.md b/.changeset/prohibit-dual-status-emission.md new file mode 100644 index 0000000000..6d161cc030 --- /dev/null +++ b/.changeset/prohibit-dual-status-emission.md @@ -0,0 +1,5 @@ +--- +"adcontextprotocol": patch +--- + +Clarify that v3 agents MUST NOT emit legacy status fields (`task_status`, `response_status`, or any alias) alongside the v3 `status` field. Adds a migration checklist row, a conformance warning in the task-lifecycle reference, and extends the protocol envelope schema's `status` description with the prohibition. Closes #2987. diff --git a/.changeset/triage-ship-more.md b/.changeset/triage-ship-more.md index 2b6ba3a2c3..7cddbb3ee3 100644 --- a/.changeset/triage-ship-more.md +++ b/.changeset/triage-ship-more.md @@ -1,4 +1,4 @@ --- --- -Flip the triage routine's default from "flag unless obviously a small bug" to "execute unless the change is breaking, ambiguous, or high-risk." Drops the <150-line scope cap, the classification-only-Bug-or-Doc gate, and the blanket prohibition on `static/schemas/source/**` edits. Adds a crisp non-breaking-vs-breaking definition as the primary Execute/Flag binary, adds evergreen content as a first-class always-PR-able bucket, and guards `infra/agents` bucket as always-Flag (self-modification risk). CODEOWNERS + human review still gate every merge. +Flip the triage routine's default from "flag unless obviously a small bug" to "execute unless the change is breaking, ambiguous, or high-risk." Drops the under-150-line scope cap, the classification-only-Bug-or-Doc gate, and the blanket prohibition on `static/schemas/source/**` edits. Adds a crisp non-breaking-vs-breaking definition as the primary Execute/Flag binary, adds evergreen content as a first-class always-PR-able bucket, and guards `infra/agents` bucket as always-Flag (self-modification risk). CODEOWNERS + human review still gate every merge. diff --git a/docs/building/implementation/task-lifecycle.mdx b/docs/building/implementation/task-lifecycle.mdx index 8b36be7b41..ba0395d795 100644 --- a/docs/building/implementation/task-lifecycle.mdx +++ b/docs/building/implementation/task-lifecycle.mdx @@ -45,6 +45,10 @@ Every AdCP response uses a **flat structure** where task-specific fields are at } ``` +:::warning Single status field required +Agents MUST NOT emit the legacy `task_status` or `response_status` fields alongside `status`. The `status` field is the single authoritative task state. Agents emitting either alongside `status` are non-conformant. +::: + ## Status Handling ### Basic Pattern diff --git a/docs/reference/migration/index.mdx b/docs/reference/migration/index.mdx index bd50572302..6eec78545d 100644 --- a/docs/reference/migration/index.mdx +++ b/docs/reference/migration/index.mdx @@ -27,6 +27,7 @@ Each row is a breaking change. **Effort** indicates the typical work involved: - **Rename** — Field name changed, same semantics. Find-and-replace. - **Restructure** — Shape changed (e.g., string → object, single → array). Requires code changes. +- **Remove** — Field existed in v2, removed in v3. Find-and-delete. - **New requirement** — Didn't exist in v2. Requires new implementation. | Area | Change | Effort | Details | @@ -50,6 +51,7 @@ Each row is a breaking change. **Effort** indicates the typical work involved: | Products | `buying_mode` required on every `get_products` request | New requirement | [get_products reference](/docs/media-buy/task-reference/get_products) | | Media buy status | `pending_activation` → `pending_start` | Rename | [Media buys](/docs/media-buy/media-buys) | | Media buy status | `pending_creatives` added (no creatives assigned yet) | New requirement | [Media buys](/docs/media-buy/media-buys) | +| Task status | Legacy `task_status` and `response_status` fields MUST NOT be emitted alongside v3 `status` — remove both | Remove | [Task lifecycle](/docs/building/implementation/task-lifecycle) | | Capabilities | `compliance_testing` capability block on `get_adcp_capabilities` | Additive | [Capability discovery](/docs/protocol/get_adcp_capabilities#compliance_testing) | | Idempotency | `idempotency_key` required on all mutating requests (UUID v4) | New requirement | [Security § Idempotency](/docs/building/implementation/security) | | Request signing | RFC 9421 Ed25519 signing profile (optional in 3.0, mandatory under AdCP Verified) | Additive | [Security § Request signing](/docs/building/implementation/security) | diff --git a/static/schemas/source/core/protocol-envelope.json b/static/schemas/source/core/protocol-envelope.json index b22ab14f40..3650217134 100644 --- a/static/schemas/source/core/protocol-envelope.json +++ b/static/schemas/source/core/protocol-envelope.json @@ -16,7 +16,7 @@ }, "status": { "$ref": "/schemas/enums/task-status.json", - "description": "Current task execution state. Indicates whether the task is completed, in progress (working), submitted for async processing, failed, or requires user input. Managed by the protocol layer." + "description": "Current task execution state. Indicates whether the task is completed, in progress (working), submitted for async processing, failed, or requires user input. Managed by the protocol layer. Agents MUST NOT emit the legacy task_status or response_status fields alongside this field — the status field is the single authoritative task state." }, "message": { "type": "string",