Skip to content

docs(compliance): add compliance grading model reference page#4040

Draft
bokelley wants to merge 1 commit intomainfrom
claude/issue-4036-compliance-grading-model-doc
Draft

docs(compliance): add compliance grading model reference page#4040
bokelley wants to merge 1 commit intomainfrom
claude/issue-4036-compliance-grading-model-doc

Conversation

@bokelley
Copy link
Copy Markdown
Contributor

@bokelley bokelley commented May 4, 2026

Closes #4036

Adds docs/building/verification/grading-model.mdx — a single reference page explaining the AdCP compliance grading model end-to-end. The page is placed in the "Verification & trust" nav group, after "Validate Your Agent".

Motivation: An SDK contributor (implementing seller-side framework in adcp-client-python) spent over an hour misreading the system — looking at JS test helpers (src/lib/testing/scenarios/media-buy.ts) instead of the authoritative YAML storyboards. This caused an incorrect architectural claim that the proposal lifecycle wasn't being exercised when it was. A single doc page closes that discoverability gap.

What's covered:

  1. Specialism declarationspecialisms field in get_adcp_capabilities, kebab-case enum IDs, parent-protocol requirement
  2. Scenario resolution — three-layer taxonomy (Universal → Protocol → Specialism), two-phase merge of protocol baseline + specialism requires_scenarios, deduplication and capability-gate application; explicit callout that the YAML storyboard runner is authoritative, not the JS test helpers
  3. Capability gatesrequires_capability YAML block, capability_unsupported skip semantics with --json output example sourced from proposal_finalize.yaml; "(or omit)" default behavior sourced directly from sales-guaranteed/index.yaml:49
  4. Reading results — accurate overall_status values (passing/failing/partial from compliance-db.ts:13), tracks_passed, steps_passed/steps_total, storyboard_id; debug CLI examples
  5. Invariantsstatus.monotonic as a separate failure axis from step-level validations, with pointer to invariant_failures in --json output

Non-breaking justification: New MDX page added to existing nav group; no existing content removed or modified. Zero wire impact.

Pre-PR review:

  • code-reviewer: approved — blocker (wrong storyboard ID in CLI example) fixed; all CLI examples now use valid storyboard IDs consistent with validate-your-agent.mdx
  • docs-expert: approved — dual-audience framing works; three-layer resolution table and requires_scenarios YAML match source files; related links non-orphaned

Triage-managed PR. This bot does not currently iterate on
review comments or PR conversation threads (only on the source
issue). To unblock:

  • Push fixup commits directly: gh pr checkout <num>
    fix → push.
  • Or re-trigger: comment /triage execute on the source
    issue.

See #3121
for context.

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


Generated by Claude Code

Adds docs/building/verification/grading-model.mdx — a new reference
page explaining the AdCP compliance grading model end-to-end for both
adopters and SDK contributors.

https://claude.ai/code/session_01CPn4oJdWTTVZ2L8WCD4pDg
@bokelley bokelley added the claude-triaged Issue has been triaged by the Claude Code triage routine. Remove to re-triage. label May 4, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

claude-triaged Issue has been triaged by the Claude Code triage routine. Remove to re-triage.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs(compliance): single doc explaining how compliance grading works end-to-end

2 participants