Skip to content

Optional: fold #4040's unique sections into how-grading-works.mdx #4410

@bokelley

Description

@bokelley

Context

PR #4040 (`docs(compliance): add compliance grading model reference page`) was closed because its core content overlapped substantially with merged #4044 (`how-grading-works.mdx`) — specialism declaration, capability gates, scenario resolution all duplicated. It also had the same `capability_unsupported` vs canonical `not_applicable` skip-reason bug that killed #4042.

Unique sections worth preserving

If we want to expand `docs/building/verification/how-grading-works.mdx` later, these were the non-overlapping sections in #4040:

  1. Three-layer scenario resolution table (universal / protocol / specialism). Useful as a quick reference for adopters figuring out which storyboards apply to them.
  2. `--json` output field guide + CLI examples for diagnosing failing runs (`storyboard run`, `storyboard step --debug`).
  3. Invariants section (`status.monotonic`) — `invariant_failures` axis is currently undocumented; useful when a run shows `partial` with no obvious step-level failures.
  4. "JS test helpers vs storyboard runner" clarification — the storyboard runner is the authoritative grader, JS helpers in `src/lib/testing/` use a narrower scenario set. Was the actual motivation for docs(compliance): single doc explaining how compliance grading works end-to-end #4036 / docs(compliance): add compliance grading model reference page #4040.

Not urgent

#4044 already covers the load-bearing concepts. Folding these in is a nice-to-have, not a gap. Pick this up only when someone else asks "what does `--json` give me?" or "what's an invariant failure?" and the docs don't answer.

When picking up

Use the canonical skip-reason vocabulary (`not_applicable`, not `capability_unsupported`) per #4042 / #4044 audit.

Metadata

Metadata

Assignees

No one assigned

    Labels

    claude-triagedIssue has been triaged by the Claude Code triage routine. Remove to re-triage.documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions