Skip to content

docs(spec): prohibit dual-emission of legacy status fields alongside v3 status#3021

Merged
bokelley merged 6 commits intomainfrom
claude/issue-2987-prohibit-dual-status-emission
Apr 24, 2026
Merged

docs(spec): prohibit dual-emission of legacy status fields alongside v3 status#3021
bokelley merged 6 commits intomainfrom
claude/issue-2987-prohibit-dual-status-emission

Conversation

@bokelley
Copy link
Copy Markdown
Contributor

Closes #2987

Summary

AdCP v3 defines status as the single authoritative task state, but the spec said nothing about agents that continue emitting a legacy task_status (or similar) field alongside it during migration. Scope3 flagged this as an active ambiguity: buyers were assuming v3 status wins on terminal states but had no normative text to cite.

This PR closes the gap with explicit MUST NOT language in three places:

  • Migration checklist (docs/reference/migration/index.mdx): adds a "Task status" row so migrating agents have a concrete action item.
  • Task lifecycle reference (docs/building/implementation/task-lifecycle.mdx): adds a :::warning callout immediately after the Response Structure section — the primary reference implementors consult from code.
  • Protocol envelope schema (static/schemas/source/core/protocol-envelope.json): extends the status property description with the prohibition (sibling keywords on $ref nodes are ignored by draft-07 validators; description is the correct channel for this).

Non-breaking justification

Adds optional normative text and documentation only. No field added, removed, renamed, or made required. No enum values changed. No existing clients need to change code to keep working — the prohibition targets behavior that was already incorrect per intent.

Pre-PR review

Two rounds of review were completed (cap: 2). Both experts approved the substantive conformance language.

  • code-reviewer: approved — all three prior blockers confirmed fixed; changeset description updated to remove stale x-adcp-conformance reference.
  • ad-tech-protocol-expert: approved content; raised one open question on effort label taxonomy (see below).

Open nit for reviewers: The migration table effort label is Restructure. The protocol expert argues the closest match for a field-removal prohibition is Rename ("find-and-replace semantics"); the code reviewer considers Restructure ("requires code changes") equally valid. Neither Rename nor Restructure is a perfect fit — the table legend has no Remove category. Please pick whichever reads more accurately to you; either is fine. I stopped at the 2-iteration cap rather than introducing a third loop over taxonomy.

Session: https://claude.ai/code/session_01XeNaS3wfWQApdBpDsU5gC7


Generated by Claude Code

@github-actions
Copy link
Copy Markdown
Contributor

IPR Policy Agreement Required

Thank you for your contribution! Before we can accept your pull request, you must agree to our Intellectual Property Rights Policy.

By making a Contribution, you agree that:

  • You grant the Foundation a perpetual, irrevocable, worldwide, non-exclusive, royalty-free copyright license to your Contribution
  • You grant a patent license under any Necessary Claims
  • You represent that you own or have sufficient rights to grant these licenses

To agree, please comment below with the exact phrase:

I have read the IPR Policy

You can read the full IPR Policy here.


I have read the IPR Policy


You can retrigger this bot by commenting recheck in this Pull Request. Posted by the CLA Assistant Lite bot.

---
---

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.
Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

fix or other changeset entry? spec?

@bokelley bokelley marked this pull request as ready for review April 24, 2026 14:32
Copy link
Copy Markdown
Collaborator

@nastassiafulconis nastassiafulconis left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed: docs-only change adding normative prohibition against dual-emission of legacy status fields alongside v3 status. Placement in the envelope's status description (rather than the shared task-status.json enum) is correct given draft-07 $ref sibling-keyword limitations. Changeset and conventions look good.

Non-blocking suggestions:

  • Migration row uses Restructure effort label which is a weak fit per the legend — consider a Remove row.
  • Prohibition is only human-discoverable; worth a follow-up conformance check asserting no envelope property matches /^(task|response)_status$/.
  • "or any alias" is undefined across the three surfaces — enumerate known aliases or tighten the rule.

claude and others added 5 commits April 24, 2026 11:33
…v3 status

Closes #2987. Adds explicit MUST NOT conformance language so migrating agents know the v3 `status` field is the sole authoritative task state.

https://claude.ai/code/session_01XeNaS3wfWQApdBpDsU5gC7
- Correct effort classification Rename → Restructure in migration table
- Remove unsupported storyboard-testing claim from conformance warning
- Replace x-adcp-conformance annotation (ignored on $ref nodes in draft-07) with prose in description field

https://claude.ai/code/session_01XeNaS3wfWQApdBpDsU5gC7
Per @bokelley comment: PR touches static/schemas/source/core/protocol-envelope.json
(a published protocol schema), so the changeset should bump the spec package,
not be empty. Description-only schema change = patch per SemVer guidance in
.agents/playbook.md.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…ify parse

Blocks the broken-links workflow: Mintlify's MDX parser hits
./.changeset/triage-ship-more.md:4:156 with
"Unexpected character \`1\` (U+0031) before name" because \`<150-line\` looks
like a malformed JSX tag opener. Replace with "under-150-line" — same
meaning, MDX-safe. Same fix shipped by @bokelley on bokelley/issue-3010
(ce11b32); cherry-picking here so this PR's CI isn't gated on that
unrelated PR landing first.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…e aliases

- Add `Remove` effort label to migration legend; apply to the Task status row.
- Drop vague "or any alias" from all three surfaces (migration table, task
  lifecycle warning, envelope schema description) — enumerate only the
  concrete pre-v3 names (`task_status`, `response_status`). Broader
  semantic overlap is covered by the prose, not by an open-ended
  prohibition.
- Follow-up conformance check tracked in #3041.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@bokelley bokelley merged commit 4614f4d into main Apr 24, 2026
17 checks passed
@bokelley bokelley deleted the claude/issue-2987-prohibit-dual-status-emission branch April 24, 2026 16:04
bokelley added a commit that referenced this pull request Apr 24, 2026
Conflict in .changeset/triage-ship-more.md — both sides independently
fixed the `<150-line` MDX parse error: this branch wrapped as
`<150`-line in backticks, main (via #3021) rephrased to
`under-150-line`. Took main's version as the cleaner prose fix
(no `<` character at all, simpler than a code span).

The workflow-level `.changeset/` shuffle + React-crash-tolerant grep
filter in .github/workflows/broken-links.yml are retained — they
protect against future changesets reintroducing `<anything>` patterns
and against the upstream Mintlify React hook-call crash tracked in
#2983.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
bokelley added a commit that referenced this pull request Apr 24, 2026
…loses #3041) (#3044)

PR #3021 added MUST NOT prose against dual-emitting legacy `task_status`
and `response_status` alongside v3 `status`. Reviewer flagged that the
rule was only human-discoverable. This lifts the prohibition into the
JSON Schema itself via the existing `not: { anyOf: [{ required: [...] }] }`
idiom (used by `core/catchment.json`).

Any envelope containing `task_status` or `response_status` now fails
draft-07 validation against `/schemas/core/protocol-envelope.json` — no
runner-side primitive required. The prose MUST NOT in the `status`
description remains for implementors reading the schema by eye; the
`not` constraint is what validators act on.

Verified with ajv:
- clean envelope → valid
- envelope with task_status → invalid
- envelope with response_status → invalid
- envelope with both → invalid
- envelope with unrelated additional properties → valid (additionalProperties: true unchanged)

Non-breaking: the prohibition targets behavior that was already incorrect
per #3021. No conformant v3 agent emits these fields.

Runtime conformance — a storyboard-level `field_absent` primitive plus
@adcp/client implementation — is out of scope here and will be tracked
as a follow-up on @adcp/client once the schema-level enforcement has
shipped.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@github-actions github-actions Bot mentioned this pull request Apr 24, 2026
bokelley added a commit that referenced this pull request Apr 25, 2026
…ard for #3041 (#3045)

Formalises the normative MUST NOT on task_status / response_status envelope
fields (established in PRs #2987 / #3021) as machine-checkable constraints.

Changes:
- static/schemas/source/core/protocol-envelope.json: adds "task_status": { "not": {} }
  and "response_status": { "not": {} } to the properties block. Any schema-aware
  validator operating on the full v3 protocol envelope will now detect these
  legacy field names without consulting the prose migration guide.

- static/compliance/source/universal/v3-envelope-integrity.yaml: new universal
  storyboard (interaction_model: "*") asserting the canonical v3 status field is
  present. field_absent checks for the two prohibited fields are included as
  commented-out TODO steps pending @adcp/client runner support for that check type.

Non-breaking justification: adds new forbidden-property constraints to two field
names that were already normatively prohibited (MUST NOT). No conformant v3
implementation uses these fields; existing v3 consumers are unaffected.

https://claude.ai/code/session_0144VBMThUyhomU346keD32C

Co-authored-by: Claude <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Task status: prohibit dual-emission of legacy status fields alongside v3 status

3 participants