fix(compliance): clarify MCP envelope binding in v3_envelope_integrity storyboard#4005
Merged
bokelley merged 1 commit intoMay 3, 2026
Merged
Conversation
…y storyboard The no_legacy_status_fields step narrative didn't explain that for MCP transport, status must appear at the top level of structuredContent alongside task-specific fields — not at the JSON-RPC result level. Agent implementors reading only the task response schema (get-adcp-capabilities- response.json) could omit status and still pass response_schema validation, creating a confusing false-negative from the envelope_field_present check. Add explicit MCP transport note to the narrative and expected block, referencing the normative extraction algorithm in docs/building/implementation/mcp-response-extraction. Refs #3999. https://claude.ai/code/session_017QfEu3mAJG9SQk6JUiBGrx
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Refs #3999
The
v3_envelope_integrity/no_legacy_status_fieldsstep narrative andexpectedblock did not explain wherestatuslives in MCP transport responses. Agent implementors reading onlyget-adcp-capabilities-response.jsoncould include only the task-specific fields in their MCPstructuredContent, omitstatus, pass theresponse_schemavalidation check, and then be confused by a failingenvelope_field_present: statuscheck.Root cause (from expert review): The reporter's agent is non-conformant — it returns only the task payload in
structuredContentwithout the required protocol envelope fields. Theresponse_schemacheck passes becauseget-adcp-capabilities-response.jsonvalidates only the task-specific fields;statusis a protocol envelope field not covered by that schema. Theenvelope_field_presentcheck is correctly detecting the non-conformance. The fix is narrative clarification, not weakening the check.The normative extraction algorithm at
docs/building/implementation/mcp-response-extractionalready showsstatusat the top level ofstructuredContent, but the storyboard didn't cross-reference it.Non-breaking justification: Changes only
narrative:andexpected:text fields in the storyboard YAML. No check types, validation paths, or runner-contract fields are modified. The check remainsseverity: required— the conformance requirement is unchanged.Pre-PR review:
content[0].text→content[].textto match the normative extraction algorithm iterating all content items in order, not just item 0)structuredContentshape description is accurate perstatic/test-vectors/mcp-response-extraction.jsonandmcp-response-extraction.mdxline 87; nit noted (the merge step of envelope+payload into a flat object is not explained) as follow-up documentation debtFollow-up items (not in this PR):
Sibling-repo-fix-needed: adcp-client— the code reviewer noted thatenvelope_field_presentmay not correctly implement MCP extraction semantics (checking the extracted envelope vs. the raw JSON-RPC result). Should be verified in@adcp/clientto confirm the check traverses the extractedstructuredContentobject permcp-response-extraction.mdx. If the runner has a separate bug, aseverity: advisoryannotation may be needed in a follow-up.lint-storyboard-validations-paths.cjs—envelope_field_presentis absent fromPATH_BEARING_CHECKS; a typo in anenvelope_field_presentpath would not be caught. Follow-up lint improvement.Session: https://claude.ai/code/session_017QfEu3mAJG9SQk6JUiBGrx
Generated by Claude Code