feat(certify): machine-checkable review certification (v0.4.0)

[macblackstuff]

What changes

A matrix report can now prove it was reviewed. --certify LEDGER validates an identity-keyed review ledger against the input and writes a hash-bound certification record shipped with the report (report + record + input + ledger, plus the source file under --source) — so a consumer holding the files can re-run certification, and a report without its record is a draft. Reviews that skip the loop, on any model or harness, no longer produce an artifact that reads as finished.

Release v0.4.0. Sibling PR follows in system-adoption-pipeline re-vendoring this tag and requiring certification in its pass-3 done-check.

Why

The review loop was prose-only ("human review is mandatory"), so one-shot runs shipped unresolved-gap reports indistinguishable from reviewed ones (SKILL.md:145-166 at base). The gate machine-checks what the prose asked for: every ledger finding — candidates, gaps, boundary findings, unstated pairs, uncited spans — dispositioned (open-parked gaps and accepted candidates ride as visible advisories), none drifted; the stamped record is a verified replay anchor (input/source sha drift re-opens the review; flags replay exactly); feedback loops, self-dependencies and the class-rule audit stay human-reviewed by design. Review becomes separation of duties: an independent reviewer of record, distinct from the input's drafter — a model reviewer only via the new optional, experimental model pins.

Design decisions

• Certification certifies review-completeness, not gap-zero — gaps may legitimately remain open; disposition, not closure, is what exit 0 demands.
• Two-phase gate — generation behavior and exit codes 0/1/2 are byte-identical to v0.3.0 (the shipped example's output is unchanged); exit 3 (refusal, blockers named) and new exit-1 classes exist only under --certify.
• The refusal record doubles as the review worksheet — certify once against a header-only ledger and every finding returns with its paste-able fingerprint.
• Model pins are metadata-only, default off — experimental keys (decision/thinker/reviewer/judge) under frontmatter metadata:; the Python reads no configuration.

Checklist

• Tests pass, with and without -O (125 tests; red-first: 14 then 22 then 11 observed failures before each implementation pass)
• A test fails without this change, or the change is documentation-only (10 regression tests pin the validated review findings)
• CHANGELOG.md has a line under Unreleased (dated 0.4.0 heading per release convention)
• SKILL.md / references/ updated if behaviour the agent sees changed
• Commits use a GitHub noreply email

Validation

• python3 scripts/test_interface_matrix.py → 125 tests OK; same under -O; skills-ref validate → valid.
• Generation regression: v0.3.0 examples/example-output.md reproduced byte-identically; a 180-run differential fuzz over rules/classes/--sample/--source variants found zero mismatches.
• Certified example shipped: examples/example-ledger.md + .cert.md — certify exits 0 with 4 visible advisories (accepted candidate, parked gap, 2 boundary acceptances); re-run is idempotent.
• Multi-agent code review (6 lenses + independent validation) run on this branch: verdict Ready with fixes; all 8 validator-confirmed findings — including the stamped-record-not-verified, citing-input-skips-spans, overclaim, and silent-candidate holes — fixed on-branch with tests.

Session-settled decisions carried from planning: enforcement via script gates AND prose (user-directed, over either alone); model-agnostic default with optional explicit pinning (user-directed, over built-in model requirements); both existing repos, this one as source of truth (user-directed, over a new repo).

Unapplied review findings

• P2 — skills/interface-matrix/scripts/interface_matrix.py:984 — Derivation wiring duplicated between report() and certify(): extract derive(built, rules) returning the shared bundle, called by both. Deferred: behavior-neutral refactor after a validated release.
• P2 (report-only) — certification layer (~320 lines) pushes the script past 1000 lines (897 → ~1200): extract scripts/certify.py + scripts/test_certification.py; decide together with the next vendored sync in system-adoption-pipeline so pinned sha256s and docs move in one change.
• Residual risks accepted at review: the flags pin and record stamp live inside the trusted ledger (same trust domain as dispositions — the gate verifies presence, not honesty); each run overwrites <ledger>.cert.md (consumer-side sha diffing before any re-run, documented in RUNBOOK); settle() returns a 6-tuple indexed [1] by certify() until derive() lands.

Review run 20260930-030735-c0aa86ef; artifact retained on the author's machine.

---