review: fold in failure scenarios, the change-provenance gate, and orchestrator cost fixes

[jwbron]

Summary

One release folding eight changes into the shared PR reviewer (workflows/review/): five quality disciplines and three measured cost fixes. Smoke-set gated; no eval cycle needed.

cc @jeresig

Quality fold-ins

• Failure scenario required. Every finding (not just blocking ones) now carries a concrete failure_scenario: the specific inputs or state and the wrong outcome they produce. The field is required in the structured finding schema (FINDING_SCHEMA_VERSION bumped to 2), emitted by every producer (label-shape reviewers and all 11 specialist lenses), and carried verbatim into claims.json. The claim-validator now attacks exactly that stated scenario: confirmed means the named scenario occurs on the cited lines, and a scenario too vague to check caps at plausible.
• Quote-the-rule discipline. A skill or conventions violation may only be flagged when the exact rule text and the exact violating line can both be quoted (skill-auditor, conventions reviewer, and every lens-owned skill application); the validator never confirms a skill claim that cannot quote its rule. No spirit-of-the-doc inference.
• Amplification nuance. A claim about a mechanism that predates the diff confirms only when the diff materially amplifies its consequence, and the finding must say so explicitly; the correctness reviewer states introduce-vs-amplify on every pre-existing-bug finding.
• Method-angle procedures. The correctness reviewer works the diff through three named procedures instead of one flat checklist: a line scan (what input or state makes each line wrong), a removed-behavior audit (name the invariant every deleted line enforced; find where the new code re-establishes it), and a cross-file trace (callers and callees of every changed symbol).
• Change-provenance gate, enforced in code. New lib/diff.ts (unified-diff parsing) and lib/provenance.ts (gate + CLI) compute a per-file changed-line map (provenance.json). A finding whose anchor is not an added or modified line of the diff cannot carry a blocking label, and pre-existing observations collapse into at most one non-blocking collapsed note (renderPreExistingNote). Deletion findings pass via removedAdjacent lines. The gate fails open (gates nothing, with a review-body note) whenever the parsed map cannot be trusted: an unparseable diff, hunk headers not attributable to any file section, or a changed file whose patch is missing from the parse (files.json now carries a hasPatch flag so binary/too-large files do not false-positive the check). Wired through the no-post eval runner and covered by unit tests plus a new smoke corpus case.

Measured cost fixes

• Generated-stripped whole-change diffs. The provenance CLI also stages full-stripped.diff (the full diff minus files the router classifies linguist-generated; routing.json now exposes generatedFiles). Every whole-change reviewer and specialist lens reads it instead of the full diff; pattern-triage keeps the full diff since classification is its job.
• Graceful budget exhaustion. Nearing the AI-credits cap, the orchestrator sheds remaining work in a fixed order (opt-in reviewers/lenses first, then the risks/patterns comment, then validation) and submits the verdict from findings validated so far plus skipped-dimension notes, instead of dying at the cap with everything spent and nothing posted.
• Batched safe-output tail. The orchestrator emits same-kind safe outputs together in as few calls and turns as possible; thread resolutions especially, which previously went out one turn apiece.

Notes

• FINDING_SCHEMA_VERSION is now 2 (a required field invalidates previously serialized findings, per the schema module's own rule); every corpus fixture is migrated with a hand-written failure scenario.
• No trigger config or consumer files touched. Prompt text carries no plan identifiers.
• Changeset: "review": minor.

Testing

• npx vitest run workflows/review: 447 tests green, including the smoke set and a new end-to-end smoke case for the provenance gate (provenance-pre-existing-collapses).
• New unit suites: lib/diff.test.ts, lib/provenance.test.ts, plus renderPreExistingNote rendering tests and router generatedFiles coverage.
• lib/diff.ts and lib/provenance.ts type-check clean under the repo's strict compiler options.

[changeset-bot]

🦋 Changeset detected

Latest commit: 6381656

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
review	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[jwbron]

Split into a stack of three for reviewability and independent revert: #226 (failure_scenario schema v2 + corpus migration), #227 (change-provenance gate + generated-stripped diffs), #228 (prompt disciplines + cost fixes). The stack's tip is byte-identical to this branch apart from the changeset files.