docs(conformance, catalog): refresh universal-storyboards tables#3099
Merged
bokelley merged 2 commits intoApr 25, 2026
Conversation
Both docs/building/conformance.mdx and docs/building/compliance-catalog.mdx had stale universal-storyboards tables. static/compliance/source/universal/ now contains 9 graded storyboards; the docs listed 5–7. Drift accumulated as new storyboards landed without back-filling the index pages. - Add webhook-emission (universal since #2417 / 3.0; never indexed) - Add pagination-integrity (recently landed; missing from both) - Add idempotency to compliance-catalog (had it in conformance.mdx only) - Add signed-requests to compliance-catalog (had it in conformance.mdx only, added there in #3077) Framing fix in compliance-catalog: the lead-in claimed every agent runs every universal storyboard regardless of claims — true in scope, but confusing on capability-gated rows. Reworded to acknowledge the gating (deterministic-testing, signed-requests) plus a closing paragraph that gated storyboards can't be partially implemented (advertise false rather than ship a partial surface). Both index pages now reflect the same 9 graded universal storyboards in the same order, matching the published /compliance/{version}/universal/ directory. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
4 tasks
…tem (#3102) * chore(compliance): lint that universal-storyboard doc tables match the filesystem Prevents the drift #3099 just fixed from re-accumulating. Every graded universal storyboard MUST appear in both docs/building/conformance.mdx and docs/building/compliance-catalog.mdx; every backtick-quoted slug in those tables MUST resolve to a real graded storyboard on disk. Catches: - New universal storyboard ships without a doc-table row (forward). - Doc keeps a row for a renamed/deleted storyboard (reverse). - Either index page loses its "Universal" heading. Wiring: - scripts/lint-universal-storyboard-doc-parity.cjs — new module exporting lint({ sourceDir, repoRoot }) plus helpers, with a CLI entrypoint. - scripts/build-compliance.cjs — calls lint inside generateIndex, so the compliance build fails loudly on drift. - tests/lint-universal-storyboard-doc-parity.test.cjs — 10 tests: source-tree guard, clean fixture, non-graded fixtures filtered out, forward parity (both docs), reverse parity (both docs), missing heading, helper unit tests. - package.json — test:storyboard-doc-parity wired into the umbrella test target alongside other storyboard lints; CI picks it up automatically via npm run test. "Graded" = YAML has a phases:[] array. Filters out the three non-graded fixtures (storyboard-schema.yaml, runner-output-contract.yaml, fictional-entities.yaml) that live alongside graded storyboards. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore(compliance): apply DX-review nice-to-haves to doc-parity lint Two cheap improvements from the DX-expert review: 1. Forward-parity error message now mentions the slug form (kebab-case filename slug for compliance-catalog, snake_case YAML id for conformance). Parallels the reverse error which already had this hint. Helps a contributor adding a brand-new storyboard pick the right form without comparing existing rows. 2. JSX comment above each universal-storyboards table pointing at the lint script. Discoverability for contributors editing the docs directly — they see the rule before the build fails. Tests still pass 10/10; build clean. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
bokelley
deleted the
bokelley/compliance-catalog-universal-table-refresh
branch
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
1 participant
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.
Summary
Both
docs/building/conformance.mdxanddocs/building/compliance-catalog.mdxcarry an index of universal storyboards. Both had drifted from the truth instatic/compliance/source/universal/— the directory has 9 graded storyboards, the docs listed 5–7. Caught while sweeping for post-#3077 cleanup.Changes
conformance.mdx — adds two missing rows:
webhook_emission— outbound webhook conformance. Universal since spec(webhooks): require idempotency_key on all webhook payloads (#2416) #2417 / 3.0, never indexed in this table.pagination_integrity—cursor↔has_moreinvariant. Recently landed.compliance-catalog.mdx — adds four missing rows (the catalog was further behind than
conformance.mdx):idempotency— somehow missing entirely.webhook-emission,pagination-integrity— same as above.signed-requests— added toconformance.mdxin patch: complete signed-requests reclassification (specialism → universal capability-gated storyboard) #3077 but the parallel catalog entry was missed.compliance-catalog framing fix — the lead-in said "Every agent runs every storyboard… regardless of which protocols or specialisms it claims," which reads incorrectly against capability-gated rows (
deterministic-testing,signed-requests). Reworded to acknowledge the gate explicitly, plus a closing paragraph: gated storyboards cannot be partially implemented; declare the capabilityfalseif you don't ship the full surface.Why this is a docs PR
No new normative content. Both pages now reflect the 9 graded universal storyboards in matching order. The truth lives in
static/compliance/source/universal/; this PR brings the index pages back into sync.Out of scope
Test plan
node scripts/build-compliance.cjspasses (✓ 12 universal, 6 protocols, 19 specialisms— the 12 includes 3 non-graded files:fictional-entities,runner-output-contract,storyboard-schema).🤖 Generated with Claude Code