sdr-grader 1.1.1__tar.gz

sdr_grader-1.1.1/.claude-plugin/plugin.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://claude.ai/schemas/plugin.json",
+  "name": "sdr-grader",
+  "version": "1.0.0",
+  "description": "Follow-up question support for sdr-grader's --json grade output. Filter findings, look up remediations, and compare two grades from inside Claude Code.",
+  "author": {
+    "name": "Brian Au",
+    "url": "https://github.com/brian-a-au/sdr-grader"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/brian-a-au/sdr-grader",
+  "skills": ["skills/sdr-grader"]
+}

sdr_grader-1.1.1/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,73 @@
+name: Bug report
+description: A rule grades incorrectly, the CLI crashes, or output is wrong.
+title: "[bug] "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to file a bug. A reproducible snapshot
+        is the single most useful thing you can attach.
+
+        **Do not paste a real production snapshot.** Use
+        `scripts/sanitize_sdr.py` to scrub tenant identifiers, then trim
+        to the smallest shape that still reproduces the bug. If the
+        snapshot is sensitive even after scrubbing, open a
+        [private security advisory](https://github.com/brian-a-au/sdr-grader/security/advisories/new)
+        instead.
+
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened
+      description: What did the grader do? What did you expect it to do?
+      placeholder: |
+        Ran `sdr-grader snapshot.json --output grade.html`. SCH-003 fired
+        with "170 components lack descriptions" but the snapshot has
+        descriptions on every component.
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Reproduction
+      description: |
+        Minimal command + minimal snapshot. Inline the snapshot in a code
+        block if it's small, or attach it.
+      render: shell
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: sdr-grader version
+      description: Output of `sdr-grader --version` (or commit SHA if running from source).
+      placeholder: "1.0.0"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: platform
+    attributes:
+      label: Platform
+      options:
+        - CJA (cja_auto_sdr snapshot)
+        - AA (aa_auto_sdr snapshot)
+        - Both / not platform-specific
+    validations:
+      required: true
+
+  - type: input
+    id: pack
+    attributes:
+      label: Rubric pack
+      description: Which pack was active? Default is `strict`.
+      placeholder: "strict"
+
+  - type: textarea
+    id: extra
+    attributes:
+      label: Anything else
+      description: Logs, screenshots of the rendered report, related issues.

sdr_grader-1.1.1/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/brian-a-au/sdr-grader/security/advisories/new
+    about: Please report security issues privately via a GitHub Security Advisory, not a public issue.
+  - name: False positive on a private snapshot
+    url: https://github.com/brian-a-au/sdr-grader/security/advisories/new
+    about: If a rule fires incorrectly on a snapshot you cannot share publicly, open a private advisory and we'll work out a sanitized reduction together. See SECURITY.md.

sdr_grader-1.1.1/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,65 @@
+name: Feature or rule proposal
+description: Propose a new rule, new check kind, or other enhancement.
+title: "[feature] "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Open an issue **before** opening a PR for new rules or structural
+        changes — it saves us both time vs. arriving at the same
+        conclusion through review feedback. See `CONTRIBUTING.md` for
+        what's PR-able directly vs. maintainer-gated.
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: What are you proposing
+      description: One paragraph. New rule? New check kind? New CLI flag? Something else?
+    validations:
+      required: true
+
+  - type: textarea
+    id: motivation
+    attributes:
+      label: Motivation
+      description: |
+        What broken-implementation pattern does this catch? Why does the
+        current rule set miss it?
+    validations:
+      required: true
+
+  - type: dropdown
+    id: shape
+    attributes:
+      label: If this is a new rule, what does it measure?
+      description: |
+        See `CONTRIBUTING.md` invariants. Cardinality rules ("you have
+        more than N segments") are rejected by default — the same number
+        is healthy for one tenant and pathological for another.
+      options:
+        - Shape (structure of a definition, e.g. nesting depth)
+        - Ratio (e.g. % of components missing descriptions)
+        - Correctness (e.g. formula references a deleted component)
+        - Cardinality (raw count — likely to be rejected)
+        - Not applicable (not a new rule)
+    validations:
+      required: true
+
+  - type: textarea
+    id: example
+    attributes:
+      label: Example
+      description: |
+        Synthetic fixture or sketch of what the firing condition looks
+        like. If this needs calibration data, say so — provisional
+        thresholds are fine in an initial PR.
+      render: shell
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: |
+        Existing rules that almost cover this? Other ways to surface the
+        same signal (e.g. supplementary input vs. core rule)?

sdr_grader-1.1.1/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,30 @@
+## Summary
+
+<!-- What does this PR do, in 1-3 sentences? Link the issue it closes. -->
+
+## Type of change
+
+- [ ] Bug fix (incorrect grading, adapter crash, renderer regression)
+- [ ] New rule (also opened an issue first per CONTRIBUTING.md)
+- [ ] Threshold / severity tweak (requires maintainer recalibration — explained in the issue)
+- [ ] Docs / examples / CI
+- [ ] Other (describe)
+
+## Invariant check
+
+These are non-negotiable per CONTRIBUTING.md. Confirm:
+
+- [ ] No randomness or `datetime.now()` in graded output (determinism contract)
+- [ ] No new cardinality rules (`len(X) > k` shapes are rejected)
+- [ ] `render/` does not import from `rules/` or `core/grader.py`
+
+## Tests + examples
+
+- [ ] `uv run pytest` passes locally
+- [ ] `uv run ruff check` passes
+- [ ] If rules or renderer changed, examples regenerated via `scripts/generate_*.py` and the diff is committed (the `examples-drift` CI gate will fail otherwise)
+
+## Notes for the reviewer
+
+<!-- Anything non-obvious: a tricky calibration choice, a subtle invariant
+relied on, a fixture that needed updating, a follow-up issue you opened. -->

sdr_grader-1.1.1/.github/workflows/release.yml

@@ -0,0 +1,79 @@
+name: release
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+
+# Minimal default; each job opts into exactly the scopes it needs.
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write   # create the GitHub release and attach the dist assets
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Sync dependencies
+        run: uv sync --all-extras --dev
+
+      - name: Lint
+        run: uv run ruff check
+
+      - name: Test
+        run: uv run pytest --cov=src/sdr_grader --cov-report=term
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Drop uv's stray dist/.gitignore
+        # `uv build` writes a `.gitignore` (containing `*`) into dist/. Left
+        # in place it rides along into the uploaded artifact and shows up as
+        # a `default.gitignore` release asset.
+        run: rm -f dist/.gitignore
+
+      - name: Upload built distributions as a workflow artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+      - name: Upload distributions to GitHub release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: |
+            dist/*.whl
+            dist/*.tar.gz
+          generate_release_notes: true
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    # The `pypi` environment gates this job. Configure it on GitHub
+    # (Settings -> Environments -> pypi) with a required reviewer so the
+    # irreversible PyPI upload waits for a manual approval, and keep the
+    # matching "Environment name: pypi" on the PyPI trusted publisher.
+    environment:
+      name: pypi
+      url: https://pypi.org/p/sdr-grader
+    permissions:
+      id-token: write   # OIDC token for PyPI trusted publishing; nothing else
+    steps:
+      - name: Download built distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

sdr_grader-1.1.1/.github/workflows/test.yml

@@ -0,0 +1,82 @@
+name: test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+          # The default prune strips pre-built wheels from the saved cache,
+          # so every run re-downloaded them from PyPI despite a "cache hit".
+          prune-cache: false
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Sync dependencies
+        run: uv sync --all-extras --dev
+
+      - name: Lint
+        run: uv run ruff check
+
+      - name: Test
+        run: uv run pytest --cov=src/sdr_grader --cov-report=term --cov-report=xml
+
+      - name: Upload coverage XML
+        if: matrix.python-version == '3.12'
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-xml
+          path: coverage.xml
+          if-no-files-found: warn
+
+  examples-drift:
+    # Regenerate every example artifact and fail if anything changed.
+    # Catches commits that change rules / fixtures / renderer without
+    # refreshing the committed examples/ directory.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+          # The default prune strips pre-built wheels from the saved cache,
+          # so every run re-downloaded them from PyPI despite a "cache hit".
+          prune-cache: false
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Sync dependencies
+        run: uv sync --all-extras --dev
+
+      - name: Regenerate fixtures
+        run: uv run python scripts/build_cja_fixtures.py
+
+      - name: Regenerate examples
+        run: |
+          uv run python scripts/generate_examples.py
+          uv run python scripts/generate_grade_examples.py
+          uv run python scripts/generate_trend_example.py
+
+      - name: Fail on diff
+        run: |
+          if ! git diff --exit-code -- examples/ tests/fixtures/; then
+            echo "::error::Generated examples or fixtures drifted from committed copies."
+            echo "Run the relevant generator scripts locally and commit the result."
+            exit 1
+          fi

sdr_grader-1.1.1/.gitignore

@@ -0,0 +1,70 @@
+# Local reference artifacts (kept in working directory, not tracked).
+# These are the inputs the SPEC describes — the visual contract reference and
+# the spec itself. Phase 1 will copy them into src/sdr_grader/render/ paths.
+/render.py
+/report.css
+/report.html.j2
+/sample-report.html
+/templated-report.html
+/SPEC.md
+
+# macOS
+.DS_Store
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+.eggs/
+*.egg
+MANIFEST
+
+# uv / virtualenvs
+.venv/
+venv/
+env/
+
+# Testing
+.pytest_cache/
+.hypothesis/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+.tox/
+
+# Linters / type checkers
+.ruff_cache/
+.mypy_cache/
+.pyre/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Local-only generated artifacts
+/grade-*.html
+/grade-*.json
+
+# Environment
+.env
+.env.local
+
+# Claude Code "superpowers" plugin artifacts and plans — local tooling only,
+# never committed. Matches any `superpowers/` directory at any depth
+# (e.g. `/superpowers/`, `docs/superpowers/plans/`), including the
+# dot-prefixed `.superpowers/` working directory the plugin writes to.
+**/superpowers/
+.superpowers/
+
+# Private production SDR snapshots used for rubric calibration.
+# Real customer data; never committed. See the calibration plan in
+# `docs/superpowers/plans/` for the loader contract.
+/tests/fixtures/private/

sdr_grader-1.1.1/CHANGELOG.md

@@ -0,0 +1,237 @@
+# Changelog
+
+All notable changes follow the [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
+spirit. The version numbers follow [Semantic Versioning](https://semver.org/).
+
+## 1.1.1 — 2026-07-13
+
+A packaging-only release. No rules, checks, or grades change, so grades
+are identical to 1.1.0.
+
+### Fixed
+
+- **Local working artifacts no longer ship in the source distribution.**
+  The `.superpowers/` and `.hypothesis/` directories were bundled into the
+  sdist because `.gitignore` did not cover them, and hatchling reads
+  `.gitignore` to decide what the sdist contains. They are now ignored,
+  and `pyproject.toml` excludes them from the sdist target as a second
+  guard. The sdist is uploaded to PyPI and is world-readable regardless of
+  the git repository's visibility, so these never belonged in it. The
+  wheel was already clean and is unchanged.
+
+### Changed
+
+- **Richer PyPI metadata.** Added trove classifiers and keywords to
+  `pyproject.toml`. No runtime change.
+
+## 1.1.0 — 2026-07-11
+
+This release adds six rules, removes two rules that a corpus audit showed
+could not tell a good implementation from a bad one, and fixes a wide set
+of bugs in the adapters, the input pipeline, and the renderer. The default
+packs now hold 30 rules across the same 6 categories. Grades can shift
+from 1.0.0 because the default packs changed.
+
+### Added
+
+- **Six new rules** in both default packs:
+  - `SCH-007` and `ATTR-004` grade CJA Data View settings.
+  - `SCH-008` finds cycles between CJA derived fields.
+  - `SCH-009` finds CJA derived fields that reference components that do
+    not exist.
+  - `GOV-007` and `GOV-008` flag calculated metrics and segments that are
+    shared but never approved.
+- **Default output filenames keyed to the report id.** When you do not
+  pass `--output`, the CLI names the file `grade-<report id>.html`. The
+  old default used a timestamp, so a batch run that graded several
+  instances within the same second wrote them all to one file. (#2)
+- **Capped component lists in the report.** A finding now shows at most
+  50 affected components plus a line with the count of the hidden ones.
+  The `--json` output keeps the full list. (#5)
+- **Full inventory in shell-out mode.** Runs started with `--dataview` or
+  `--rsid` now pass `--include-all-inventory` to the snapshot tool.
+
+### Changed
+
+- **`ATTR-001` and `ATTR-002` are out of the default packs.** A corpus
+  audit (`docs/RUBRIC_AUDIT.md`) showed that `ATTR-001` fired on 100% of
+  the metrics it watched, and that every fixture scored the same on
+  `ATTR-002`, so its threshold could not separate anything. Both check
+  functions stay registered for custom packs.
+- **`NAME-001` and `NAME-003` grade again.** The CJA adapter now parses
+  tags that arrive as JSON-encoded strings, which is what real snapshots
+  contain. Before this fix the two rules matched nothing.
+- **Faster rendering of large reports.** The renderer caches compiled
+  templates and CSS, and the report skips layout work for findings that
+  are off-screen.
+- **Docs reorganized.** Reference material moved out of the README into
+  `docs/`, including a customization hub, platform coverage, supplementary
+  inputs, leaderboards, and the rubric audit.
+
+### Fixed
+
+- **HTML escaping.** The report and trend templates rendered values
+  without escaping, and the comparison chart did not escape category
+  labels in its SVG. Both are fixed, so snapshot content can no longer
+  inject markup into a report.
+- **Input handling.** Snapshot files with a UTF-8 BOM load. Timestamps
+  with UTC offsets or fractional seconds parse. A snapshot whose platform
+  cannot be determined raises a clear error instead of being guessed.
+  Directory mode ranks all snapshots on one timestamp scale.
+- **Shell-out mode.** The subprocess call has a timeout, decodes output
+  as UTF-8, surfaces warnings from the snapshot tool, and reports decode
+  failures as the standard invalid-snapshot error.
+- **Rule engine.** Pattern and target params are validated when the
+  rubric loads instead of failing mid-run. Cycle detection for `SCH-008`
+  and `SEG-004` is iterative and deterministic. Expiration blocks with
+  NaN or Infinity `numPeriods` no longer crash.
+- **AA adapter.** It rejects exports whose dimension, metric, calculated
+  metric, or segment sections are missing or not lists. It guards against
+  wrongly typed tags, reference lists, and numbers. It counts nesting
+  depth the same way the CJA adapter does. It renders nested formula text
+  readably and skips blank classification tags.
+- **CJA adapter.** Derived-field deduplication normalizes IDs before
+  comparing them.
+- **CLI.** `--fail-below` works in trend mode, and trend mode rejects
+  flags it does not support.
+
+### Discipline
+
+- 402 tests pass and ruff is clean.
+- Determinism holds. The same snapshot and rubric still produce
+  byte-identical HTML and JSON.
+
+## 1.0.0 — 2026-05-20
+
+First public release. The grader covers the full surface the design SPEC
+laid out, plus a Claude Code skill bundle for follow-up question support.
+Default rubric thresholds are calibrated against a 108-snapshot corpus of
+real CJA + AA production implementations — see
+[`docs/threshold_calibration.md`](docs/threshold_calibration.md) for the
+distributions and the per-rule confidence rating behind each threshold.
+
+### Added
+
+- **Deterministic, rule-based linter** for Adobe CJA and AA implementations.
+  Reads `cja_auto_sdr` / `aa_auto_sdr` JSON snapshots; emits a single
+  self-contained HTML report card and a parallel machine-readable JSON.
+- **26 rules across 6 categories**: schema hygiene, naming consistency,
+  segment complexity, calc metric maintainability, attribution coverage,
+  governance posture. Every rule in the default packs grades against
+  data the snapshot itself carries; check functions that need external
+  evidence (Launch exports, cardinality, ownership, downstream usage,
+  SDR docs) ship registered but unwired so operators can include them
+  in a forked pack.
+- **No cardinality rules.** Rules measure shape, ratio, or correctness —
+  never raw counts. See SPEC §11 for the principle and rationale.
+- **Two bundled rubric packs (v1.0)**: `strict` (master-cert-grade,
+  calibrated p75–p90 thresholds) and `pragmatic` (sanity-check,
+  calibrated p90–p95 thresholds, same rule IDs).
+- **Four input modes**: file path, snapshot directory (with
+  `--at TIMESTAMP` and `--trend`), shell-out via `--dataview` /
+  `--rsid`, and stdin.
+- **Trend reports**: `--trend` walks a snapshot directory chronologically
+  and renders an HTML trajectory with sparklines, per-category deltas,
+  and a findings churn summary.
+- **Distribution context**: `--distribution-data PATH` (or `bundled`)
+  populates the report's overall histogram and category comparison
+  charts from a percentile data file.
+- **Project-level suppression**: `.sdr-grader.yaml` lets operators
+  suppress rules, override severities, and rebalance category weights.
+  Skipped rules surface in the rendered methodology section.
+- **Supplementary inputs**: `--extra-input KEY=PATH` attaches arbitrary
+  JSON files under `Implementation.supplementary_data[KEY]`. The shape
+  and key are entirely the rule's contract; the default packs don't
+  consume them. Operators who want to grade external evidence write a
+  custom rubric pack that targets the registered check functions.
+- **JSON output**: `--json PATH` writes the full Report data structure
+  for CI dashboards and downstream tooling. Datetimes normalize to UTC
+  ISO-8601 with `Z` suffix.
+- **CI integration**: `--fail-below GRADE` exits 2 when the grade drops
+  below the threshold letter, suitable for PR gates.
+- **Claude Code skill bundle** at `skills/sdr-grader/`: SKILL.md plus a
+  bundled `query_grade.py` helper for filtering findings, looking up
+  remediations, and comparing two grade JSONs from inside Claude Code.
+- **Documentation set**: `docs/RUBRIC_FORMAT.md`, `docs/CHECK_FUNCTION_GUIDE.md`,
+  `docs/ADAPTER_GUIDE.md`, `docs/CI_INTEGRATION.md`, plus README quickstart.
+- **Examples**: clean and messy grade cards per platform
+  (`examples/grade-cja-clean.html` A 100%, `examples/grade-cja-messy.html`
+  F 44%, `examples/grade-aa-clean.html` A 100%, `examples/grade-aa-messy.html`
+  F 39%), a multi-snapshot `examples/trend-example.html`, the original
+  visual-contract reference `examples/sample-report.html`, and the
+  renderer-output golden `examples/templated-report.html`.
+
+### Discipline
+
+- **Determinism is testable.** The same snapshot + rubric produces
+  byte-identical HTML and JSON; tests assert this across two runs.
+- **261 tests** cover adapters, rules, engine, grader, CLI, trend
+  pipeline, distribution context, supplementary inputs, and the skill
+  helper. All pass; ruff clean.
+- **Phase discipline preserved**: each commit produced a working,
+  reviewable artifact. The full commit graph from scaffold to 1.0.0 is
+  visible in the git history.
+
+### Calibration-driven design decisions
+
+Calibration against a 108-snapshot corpus of real CJA + AA production
+implementations exposed three rule design problems that this release
+addresses:
+
+- **Adobe APIs don't expose `owner` on inline dimensions / metrics.**
+  Every tenant in the corpus measured 100% missing owners even after
+  normalizing the `"Unknown User"` sentinel. `GOV-004 missing_owners`
+  has been moved out of the default packs (still registered for
+  operators with their own ownership data).
+- **SDR snapshots don't carry downstream usage.** "Orphan" detection
+  for segments and calculated metrics in the corpus showed every
+  tenant at 100% — segments and calc metrics in production are
+  referenced by Workspace projects, dashboards, and alerts, none of
+  which the SDR captures. `SEG-003 orphan_segments` and
+  `CALC-005 orphan_calc_metrics` have been moved out of the default
+  packs.
+- **Description discipline is universally poor.** ≥90% of real
+  segment-bearing tenants and ≈100% of calc-metric-bearing tenants
+  have 100% of those components missing descriptions.
+  `SEG-005 segments_missing_descriptions` and
+  `CALC-001 calc_metrics_missing_descriptions` are kept in the default
+  packs at low severity with near-saturation thresholds (0.95 strict,
+  1.0 pragmatic) — they flag the most egregious tenants without
+  swamping the grade.
+
+### Registered but not in the default packs
+
+These check functions are registered and tested, but the default
+`strict` / `pragmatic` packs don't reference them — they require
+evidence the snapshot itself doesn't carry. Operators with that
+evidence can include them in a custom rubric pack:
+
+- `orphan_segments` (slot `SEG-003`) and `orphan_calc_metrics` (slot
+  `CALC-005`) — require downstream Workspace / dashboard usage data.
+- `missing_owners` (slot `GOV-004`) — requires owner attribution data
+  that Adobe's APIs don't expose on dims/metrics.
+- `doc_drift` (slot `GOV-006`) — reads `last_sdr_update_at` (param),
+  `supplementary_data['sdr']['last_updated_at']`, or
+  `metadata['SDR Last Updated']`.
+- `cardinality_concerns` (slot `SCH-006`) — reads
+  `supplementary_data['cardinality']` (a `component_id -> int` map).
+- `launch_required_data_elements` (slot `LAUNCH-001`) — reads
+  `supplementary_data['launch']`; the canonical worked example for the
+  `--extra-input` extension pattern.
+- `calc_deprecated_allocations` (slot `CALC-022`) — needs a concrete
+  `deprecated_allocations` set via params; default ships placeholder
+  values.
+
+### Known limitations
+
+- `cja_auto_sdr` / `aa_auto_sdr` are required to produce the JSON
+  snapshots the grader consumes; they are separate projects.
+- The bundled `data/distribution.json` ships seed percentile data.
+  `scripts/aggregate_distributions.py` lets teams build their own
+  internal leaderboards from a directory of grade JSONs;
+  `--distribution-data PATH` plugs the result into the report. A
+  centralized opt-in submission service is out of scope for this repo.
+- README screenshots require manual capture (open
+  `examples/grade-cja-messy.html` in a browser and screenshot the page).
+  Embedded SVG sparklines + the inlined CSS make the report itself a
+  high-fidelity preview when rendered.