Use the v1 baseline to finalize and preregister the review v2 graph

[shaug]

Parent epic: #49

Blocked by: #58

Goal

Interpret the frozen v1 corpus and baseline from #58, select the smallest evidence-backed v2 interventions, preregister the scored-v2 gates and ablations, and turn #51–#57 into a final implementation-ready graph before any review behavior changes begin.

This is a planning/definition gate. It changes repository design records and live issue contracts, not review runtime behavior.

Required inputs

Do not start unless #58 provides:

• immutable corpus version and provenance/retention audit;
• calibrated private grading expectations and disagreement record;
• exact v1 suite commit and runtime/model stratum;
• frozen executor, run-count, timeout/retry, and cost configuration;
• per-case and aggregate v1 results;
• quality, stability, failure, latency, and available cost metrics; and
• documented baseline limitations and uncertainty.

Return blocked if results are not comparable, contamination is suspected, retention authority is incomplete, or runtime failures make a proposed intervention unmeasurable.

Failure taxonomy

Classify every material v1 miss and false positive by the smallest evidenced cause, such as:

• missing or contradictory deterministic contract enforcement;
• incomplete reviewer-visible evidence;
• weak change/consumer/negative-space traversal;
• failure to test verification sufficiency;
• domain-specific reasoning miss;
• stochastic search-order or anchoring failure;
• unvalidated plausible finding;
• rubric ambiguity or overbreadth;
• grader/corpus ambiguity; or
• runtime/tooling failure rather than reviewer behavior.

Do not prescribe a prompt, schema, explorer, validator, or rule-registry change until the failure is separated from corpus, grader, and runtime defects.

Mechanism decision record

For each proposed mechanism in #51–#57, record:

• baseline cases and metrics demonstrating the problem;
• why existing behavior or a smaller change is insufficient;
• the smallest proposed intervention and canonical owner;
• exact contract/version and compatibility impact;
• deterministic positive and negative fixtures;
• scored corpus slice expected to change;
• preregistered quality/stability/non-regression target;
• maximum acceptable latency and cost impact;
• required ablation and removal rule; and
• disposition: retain, narrow, split, merge, defer, or close.

Known deterministic contradictions in #51 may be retained without a stochastic recall delta, but their exact invariant and migration must still be specified and the v1 baseline must be frozen first.

Downstream ticket revision

Before closing this ticket:

• replace every Definition status: provisional section in retained children with the approved evidence, exact contract, and implementation boundary;
• remove speculative structures and mechanisms not supported by the decision record;
• split tickets that cannot fit one coherent reviewable PR;
• eliminate duplicate ownership across the canonical review suite, lens skills, callers, and corpus workflow;
• identify expected files, tests, failure behavior, compatibility, non-goals, and validation for every retained child;
• update prose blocker references and native blockedBy edges together;
• close superseded children as not_planned only when their disposition and replacement are explicit; and
• keep production/external workflow mutations outside the read-only review suite.

Preregistered v2 gate manifest

Commit a versioned manifest before any scored v2 output is visible. It must bind:

• corpus and grader versions;
• comparable runtime/model stratum;
• executor and suite configuration;
• run count, timeout/retry policy, and cost ceiling;
• deterministic invariants;
• per-case and aggregate quality/stability/non-regression thresholds;
• mechanism ablations;
• efficiency bounds; and
• rules for invalid runs, missing data, runtime drift, and threshold changes.

Thresholds must be justified from baseline uncertainty and operator value, not selected to make a preferred architecture pass.

Required graph audits

Run three separate review-only audits over the revised live graph and iterate material findings to clean:

1. Scope/completeness audit — every demonstrated failure and required invariant has one owner; no sibling duplicates it; adjacent product/tooling work is excluded.
2. Dependency/sequencing audit — native edges match artifact prerequisites; only genuine leaves are actionable; no child can implement an unapproved mechanism or integrate a contract that does not exist.
3. Shovel-readiness audit — every actionable/retained child has a settled observable outcome, change surface, compatibility/failure behavior, positive and negative tests, validation, non-goals, and one-PR boundary.

Record each audit’s findings and resulting issue/edge changes. A combined checklist does not satisfy this criterion.

Expected change surface

• Versioned v1 failure taxonomy and v2 mechanism decision record under review-suite/.
• Preregistered scored-v2 gate manifest.
• Evidence-backed revisions, splits, closures, and native edges for Make clean verdicts require passing validation and current-head lens evidence #51–Run the preregistered review v2 ablation and integration closeout #57.
• Epic Epic: Make review-clean verdicts evidence-backed and empirically evaluated #49 status/sequence updates.
• README/CHANGELOG only where the evaluation workflow becomes user-facing.

Validation and delivery boundary

• Commit the failure taxonomy, mechanism decision record, and preregistered gate manifest as one coherent reviewable repository candidate before applying final live issue/edge changes.
• Run just format, just lint, and just test for the committed artifacts.
• Apply the approved issue-body and native-graph mutations only after the decision record is review-clean, then read parent, subIssues, blockedBy, and blocking back through GraphQL.
• Run the three named audits independently against that live graph. Record pass-specific findings, mutations, and final clean reruns in the decision record or an attached audit artifact.
• If an audit requires a materially different architecture or ticket split, revise the repository candidate and live graph, rerun repository validation, and rerun all three audits before closing.

Acceptance criteria

• Every material baseline outcome is classified as reviewer, evidence, rubric, grader/corpus, or runtime/tooling behavior.
• Every retained mechanism maps to demonstrated cases, a smallest intervention, negative controls, an ablation, and a cost bound.
• Mechanisms without demonstrated need are narrowed, deferred, or removed.
• Exact v2 quality, stability, non-regression, and efficiency gates are committed before scored v2 outputs exist.
• Every retained child has an exact contract/version boundary and one coherent reviewable-PR outcome.
• All provisional markers are removed from retained children before they become unblocked.
• Prose dependencies and native GitHub edges agree.
• Scope/completeness audit finishes with no material findings.
• Dependency/sequencing audit finishes with no material findings.
• Shovel-readiness audit finishes with no material findings for every actionable/retained child.
• Audit records distinguish findings and fixes from the final clean pass.
• Make clean verdicts require passing validation and current-head lens evidence #51 is the only next implementation leaf unless the evidence-backed graph explicitly proves safe parallel work.
• just format, just lint, and just test pass for committed design/evaluation artifacts.

Non-goals

• Change review prompts, schemas, rubrics, orchestration, or caller runtime behavior.
• Choose mechanisms before reading the baseline.
• Preserve the current Make clean verdicts require passing validation and current-head lens evidence #51–Run the preregistered review v2 ablation and integration closeout #57 shapes merely because issues already exist.
• Tune gates after seeing scored v2 outputs.
• Treat a combined structural checklist as three independent audits.
• Implement downstream tickets inside this planning gate.