code-review Handoff Supplement

Apply Review limitations and additional review: publish all supported source findings and explicitly disclose material review limits. Missing reviewer coverage, unavailable checks and provenance gaps do not create finding/blocker rows. A declined or dismissed optional extra review disappears from final actions and recommendations; retain only its factual coverage limitation.

An explicit coverage waiver is a recorded scope change, never a validation override. Identify the completed revised scope and actual limitations; never certify the preserved original scope or claim waived work passed. With no source defect and limited verification, use the supported null source recommendation without a synthetic action table. All normal artifact, promotion and completion gates still apply.

New assessed code-review result.candidate.json promotion and current schema-3 result.json validation require a nonempty reviewer assessment list and exactly one matching attributed snapshot for its scope, including the bound aggregate summary. Schema-2 results and schema-3 results without retained proof remain readable as unverified archives and cannot certify completion or remediation intake.

This is a breaking requirement for newly built non-PR assessed results: they previously promoted with no snapshot table at all and must now carry a Review Snapshot. Rejection is code-review-final-handoff-candidate-attribution-missing. Current schema-3 candidate and promoted results are gated; historical schema-2 artifacts remain readable.

Wherever a Review Snapshot is present, assessed validation binds its rows exactly as it binds PR Snapshot: fields Scope, Revision, CI, Type, Suggestion in that order, and a Suggestion matching the canonical recommendation. For current schema-3 non-PR results, Scope equals normalized metadata.scope (working-tree, path, or commit) and Revision is exactly diff sha256:<digest> from retained diff.patch; validation rehashes the file against metadata.review_input_sha256. This identifies reviewed diff bytes, not a target path or commit identity; the collector has no structured coordinate for those values. Mismatches raise the corresponding snapshot field, value, suggestion, or retained-diff errors. The heading is new in this release, so no stored artifact predates the binding. Existing attribution shape, author binding, terminal exceptions and caller-contract rules remain unchanged.

New assessed code reviews add reviewers to PR Snapshot (or Review Snapshot for non-PR scope), copied exactly from metadata.reviewer_assessments: ordered {role, rating, evidence} records with unique readable participant labels, versioned source ratings 1–5 or explicit null for a returned undecidable assessment, and retained assessment pointers. Snapshot summary copies review_decision.summary and remains aggregate prose above the table. Snapshot tables copy source_rating_version:1 and verification_readiness from metadata.review_validation. The presentation-8 renderer appends Reviewers | Role [rating], Role [rating]. and the current legend Legend: 1 = Approve · 2 = Minor changes · 3 = Major revision · 4 = Insufficient, but a good initiative · 5 = Block. Historical tables without the family marker retain Legend: 1 = Approve · 2 = Minor changes · 3 = Changes required · 4 = Insufficient evidence · 5 = Block / Reject. In presentation 8, displayed reviewer names and finding authors omit the internal (parent substitute) suffix; null ratings display as [no source judgment]. Earlier presentation profiles retain their original reviewer names, parenthesized ratings and author labels. Keep exact machine labels for evidence validation. Do not add this derived row to machine rows. Findings and operational blockers add ordered nonempty authors lists, matching reviewer labels and canonical record authors exactly. The renderer inserts Author after the ID column without changing existing machine cells or removing any summary, verdict, evidence, confidence or finding content. List all contributors to deduplicated findings. Never fabricate skipped reviewers or average ratings. Historical artifacts without attribution remain readable; terminal unassessed branches keep their no-table rules.

New review-findings and remediation tables use layout=concise. Exact machine columns, row identities, source coverage, detail bindings stay unchanged. Attributed review overview: ID | Author | Finding | Resolution proposal | Status; historical unattributed overview: ID | Finding | Resolution proposal | Status; required_change supplies a short concrete proposal. New assessed reviews use presentation_version=8 and require overview_only=true for concise finding tables. Terminal output ends each finding table after its overview; keep full context, evidence and closure criteria in the saved review-notes.md and complete canonical machine records. The renderer extracts every file path from every displayed table cell into - <item>: <file-path> lines immediately below that table, including paths mixed with evidence or action prose; all non-path prose remains in place. Historical review profiles retain their ID-only supporting groups and original confidence rendering. Finding names the problem; Context explains its mechanism, not a second Issue field. Review rows carry their canonical title, summary, closure_evidence; shared validator binds these and action/evidence cells to the enriched review record. Operational blockers carry canonical id, descriptive title, required_change, evidence, and omit summary/closure. Other skills, PR Snapshot and Review Snapshot don't support concise or grouped layout. Historical grouped/legacy rendering and ID-only blockers stay readable; never retroactively rewrite validated handoffs.

New code-review unavailable results occur before PR verification: every canonical PR gate must be not-applicable with a nonempty reason, and the versioned handoff mirrors those records as checks not run. A successful diagnostic command is not a passing PR check; retain recovery diagnostics separately. Generic gate execution retains normal exit-code semantics. Historical schema-v1 results and presentation-v1 rendered bytes keep their compatibility contract; new results can't use that path to bypass applicability validation.

For v2 unavailable review, bind outcome.summary to the actual metadata.collection_failure.code and listed safe diagnostic artifacts. It begins with a bounded plain-English stage explanation, then Reason: <code>, then only present safe command, checkout, or worktree-preflight diagnostics. When no safe collector reason exists, state once that a more specific cause was not retained; never make that statement when a safe reason is present. Known collection labels use the static stage map; unknown label uses Source collection stopped before I could verify which PR revision to review. local-pr-checkout says checkout did not complete; checkout-paths says local files could not be compared. Never infer checkout failure from missing evidence. pr-error.txt is always listed; command-failure.json, checkout-state.json, worktree-preflight.json are listed only when present and validated. A preflight may expose only validated current and expected head identifiers, never its path lists. The single remaining/next_steps record has an arbitrary stable row ID, owner=code-review, the exact failure code in item, nonempty recovery action containing the classified operation token plus exact resume condition Resume only after a fresh collector run produces and validates the PR source bundle. This permits richer evidence-backed recovery or protected-state decision while rejecting generic repair-only and unrelated CI actions. An unavailable run must not contain local-checkout.json.

An assessed code-review may use PR Snapshot with Field | Value and Review Findings and Merge Blocks with Finding / area | Required change | Evidence | Status. PR scope requires the snapshot; nonzero findings require the findings table.

New source judgments use metadata.review_validation.schema_version=1, source_rating_version=1, and finding_records_version=2. Snapshot tables copy source_rating_version:1 and verification_readiness; ratings are 1 Approve, 2 Minor changes, 3 Major revision, 4 Insufficient but a good initiative, 5 Block, or null for a returned undecidable assessment. The current legend is Legend: 1 = Approve · 2 = Minor changes · 3 = Major revision · 4 = Insufficient, but a good initiative · 5 = Block. Null renders as no source judgment. Absent family marker preserves the explicitly historical 1–5 legend above; old 4 always remains insufficient evidence. Keep unverified concerns in the durable candidate collection with exact prerequisite, owner, next check and closure. Each open candidate has a remaining entry with row_id equal to candidate ID, identical owner, item containing its exact claim and missing prerequisite, and next_action containing its exact next check and observable closure condition. Current review remaining entries may name candidate IDs outside finding-table rows; result validation binds them to the retained candidate. Do not treat them as confirmed findings or automatic edits. Open required checks prevent unconditional approval and merge readiness.

For presentation 8, both PR Snapshot and Review Snapshot append the display-only row | Report | [Markdown report](<path>) |, targeting the owning run’s nonempty review-notes.md with a portable absolute Markdown destination. The renderer moves that file path out of the table and lists it immediately below the table as - Report: <path>; never add it to machine rows or link it to compact final.md. Missing, unreadable, empty or symlinked reports block rendering. Each confidence limit and gap appears in a separate Markdown bullet, preserving its exact text, status, evidence/rationale and deduction label. New unavailable and closed reviews use presentation 8 and keep their existing no-table terminal contracts; historical presentation 3 remains byte-exact.

For presentation 8 with findings or blockers, the saved report includes one ## Finding Details section derived by final_handoff.render_review_report_details from its canonical handoff rows. It contains each ID, title, context, required change, evidence and closure criterion where applicable. remediation_finalize.py synchronizes this section, marked <!-- codex-rig:review-details -->, without rewriting surrounding authored prose; an existing unmarked or duplicate section stops derivation before any notes rewrite; rendering and completion reject missing or changed detail content. Direct producers must include the same derived section before rendering. Historical profiles do not acquire this requirement.