code-remediate 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.

Before every status or final answer, reconcile the requested remediation with its retained selection, closure ledger, gates and canonical result.

• A completed nested review, prepared branch receipt or passing tests proves no finding was fixed.
• If implementation has not begun, say Remediation remains incomplete; zero implemented, name the first unmet checkpoint, confirmed open findings and next owner/action.
• Distinguish evidence-only closure, rejection, user-authorized deferral and actual code changes.
• A no-change completion needs evidence-backed dispositions for every required finding and the normal remediation closing gates; open confirmed findings cannot become rejected or resolved because checkout failed.
• Before selection, report confirmed findings as awaiting selection rather than inventing selected counts.
• Keep any early blocked handoff explicitly incomplete without manufacturing a completed result or final resolution ledger.

Never use bare Blocked or a generic incomplete status as the opening outcome. Both outcome.title and outcome.summary must name the specific current blocker when remediation is blocked. In the summary, cite current-run gate or unresolved-item evidence and state the next owner/action needed to proceed; do not reuse a stale intake-review outcome or substitute a commit-only blocker for the remediation cause. For example: Remediation is blocked because the required documentation build could not run; gates.json records the missing dependency. The environment owner must restore that dependency before verification can finish. Keep this explanation in the existing outcome fields; historical rendering and the separate commit disposition stay unchanged.

Code-remediate has one explicit continuation before promotion and final output: prepare its commit disposition and any eligible plan, render and validate the candidate, then execute its step-12 commit decision. Exception: an explicit user commit request may execute step 12 after applicable verification and shared commit checks, before final report validation; record the request and remaining report checkpoint, then return with actual hashes/disposition to complete validation and promotion. Standing approval or grouping alone does not invoke this sequencing override. A pending required authorization or explicitly deferred decision keeps commit work pending; optional grouping under standing approval uses its documented default; a blocked or inapplicable commit still needs an explicit disposition. Refresh the handoff and revalidate after an answer or execution changes that disposition, then promote and emit it. Result validation alone must never skip this continuation.

New code-remediate handoffs additionally require commit_disposition with exactly three nonempty string fields: status, reason, evidence. Status is pending (choice or authorized execution outstanding), blocked (verification/closure/ownership/destination/execution prevents committing), not-applicable (no remediation-owned tracked or untracked changes), declined (explicit matching leave-unstaged answer), or committed (all authorized units and post-commit checks finished). Reason explains the actual disposition, next owner/action for blocked work, and remaining unstaged work; evidence points to the existing plan, decision, gate or closure record. Pending and committed require commit-plan.md and an existing evidence file declared as a run-relative POSIX path without symlink components, traversal or fragments. Commit disposition describes local execution, not passing quality. Ordinary readiness retains the passing-gate and selected-closure requirements, with explicit user-deferred work outside the plan recorded consistently. A failed or timed-out result may permit a local snapshot after an explicit user request, including an answered commit-mode choice, even with failed canonical checks, incomplete verification or a genuine regression. Require nonempty ## Explicit Commit Request and ## Remaining Verification sections, no open security/critical finding and accurate selected/open/local counts; an open local defect cannot be relabeled external or closed. Preserve the failed or timed-out result, every failed check and unresolved row. A standing grant or default grouping alone does not supply the explicit request. Selected commit mode additionally requires zero task-owned staged, unstaged or untracked residue in source and destination before delivery and at final output; unrelated baseline changes remain excluded. The workflow owner must verify user authorization, excluded plan paths, actual staged paths, and that the commit message discloses the missing verification or review under Residual limits:. Automated checks establish file existence and metadata consistency, not the truth of plan prose, user consent, or Git ownership. Record earlier authorization and created hashes in the plan; a pending disposition never authorizes staging or proves a question was delivered.

The renderer requires this record for every new remediation write and emits it once after verification; candidate validation rejects its omission. Historical check and canonical-result reads preserve older records without it. Other skills cannot add it. Explicit caller-contract output retains its exact bytes while the machine handoff still records the disposition. Validation proves structure and gate/result consistency, not the truth of consent or Git ownership; existing workflow preflight and actual control calls remain mandatory.

Name the commit's local branch and absolute checkout path in commit_disposition.reason; distinguish local commit creation from remote publication. Scope each clean, staged, unstaged, or untracked claim to the checkout whose Git status was inspected. When the invoking checkout differs, identify its path and branch separately and explain which changes remain there. Report promotion and Git commit creation are separate states. The finalizer also derives a clickable Source checkout: artifact from the schema-2 prepared branch receipt, preferring remediation-branch-recovered.json over remediation-branch.json; invalid existing receipts fail derivation rather than falling back. Local-only runs without a receipt still record their observed location in the reason. Historical saved reports retain their bytes; the derived link proves the recorded location, not current Git status.

New remediation handoffs use presentation_version=8, independently of selection inventory/scope version 5. Finalizer derives selected as Yes, No, or Closed from confirmed selected_indexes and intake eligibility, counting only selectable items. Nonselectable items already resolved or informational show Closed; actionable unselected items show No; selected items show Yes, regardless of resolution status. All selects every actionable item; already-closed and informational items remain visible as Closed. The canonical validator rejects mismatched selection and fresh scope-5 candidates using older handoff versions. Historical validated reports retain their exact rendering.

New review-findings and remediation tables use layout=concise. Exact six machine columns, row identities, source coverage and O/E detail bindings stay unchanged. Version-8 remediation overview: ID | Severity | Finding | Selected | Outcome; Outcome shows the bound disposition label. Require overview_only=true; keep resolution reasons, sources and detailed evidence in linked action-items.md, without repeated item blocks in chat. The renderer moves every file path from every terminal table cell into - <item>: <file-path> lines immediately below that table, including paths mixed with evidence or action prose; machine cells and linked reports retain complete pointers. Older concise handoffs retain their Resolution column and saved rendering. Other skills, PR Snapshot and Review Snapshot retain their own layouts.

Before remediation scope selection, final_handoff.py selection validates selection.json, renders resolution-scope.md; --check verifies exact existing bytes without writes. The inventory contains schema_version=1, presentation_version=5, selected_indexes=null (pending) or a confirmed numeric list, and ordered items with input_item_id, item_name, severity, selectable, summary, closure_evidence, full sources. Selectable items also require resolution_proposal. The overview includes a short proposal and derived source-kind counts (report ×1; online ×2); full pointers appear once below in the saved scope document. Terminal selection displays only the heading/state/counts and complete table, then lists each table path as - <item>: <file-path>, followed by the available PR Relevance Summary and Full report link; omit per-item detail groups from chat while preserving them in saved reports. Repeated report views belong in source related_mentions, with finding_id when known — not independent sources. Duplicate item/source/canonical-finding identities or incorrect declared counts fail before any prompt. Record matching resolution_scope.presentation_version=5; final validation binds confirmed selection and source inventory to the outcome ledger. Version-2/3/4 selection rendering and legacy artifacts stay readable.

For version-3 and later remediation outcomes, resolved_how starts with a reasoned disposition using exact <label>: <concrete reason> syntax. Historical concise overviews display the reason as Resolution; versions 5, 6 and 8 keep the reason in the linked ledger and display the label as Outcome; internal status/counts and O/E bindings stay unchanged.

Internal resolution_status	Allowed visible label
implemented	Implemented
resolved, already-fixed, already-applied	Verified without code changes
rejected	Rejected
not-applicable	Not applicable or Rejected
duplicate	Duplicate or Rejected
needs-clarification	Needs clarification
unresolved	Blocked, Deferred, or Not selected

Deferral and nonselection require the actual user decision, not a substitute for investigating valid selected work. Never label blocked work rejected, or evidence-only closure implemented. Record finding-specific change evidence for implementation, actual closure evidence for verification without edits, concrete owner/action for open work. Zero implementations must be explicit in the opening; target integration and green CI are not review fixes. Passing gates stay separate from whether all selected remediation is complete. Historical grouped/legacy output retains its bytes.

stale is not a current remediation triage or resolution status. Outdated anchors and conflict-resolution line changes require reassessing the original concern against current code, never dismissal or automatic conversion to rejected. Other dispositions retain their existing evidence requirements. Legacy count keys remain for historical compatibility, must be zero in current results.

Selection items also retain nonempty item_type; report-origin review-gate and confidence-gap types determine gate intake counts. Report identity is the review run: sources under one pr-<n>/run-<NNN>/ directory share it, including the report root, so separate runs may reuse finding IDs. Other paths default to the full source file path; explicit shared report_id is required for verified cross-file aliases there. Shared closure text never establishes finding equivalence. Input/output paths must be distinct; output must not be a symlink.

code-remediate rows are value-bound to metadata.final_resolution_table.items: cells are exactly input_item_id, severity, item_name, ordered compact report [<report-file>:<line>], report [<report-json>#<finding-id>], or online [<comment|thread|review-id>] or online [<parent-id>#finding-<ordinal>] pointers, resolution_status — [O<n>], and [E<n>] — owner/status: owner_status. Ordered table details bind each O<n> to resolved_how, each E<n> to evidence; row IDs, kind:source_id values, source evidence, full source records in metadata and expanded ledger items must also match exactly.

Apply Worktree lifecycle for remediation: prominently identify the current delivery checkout and branch, link its delivery evidence, and distinguish a historical temporary source from the current destination. Announce isolation before source work; return finished committed or uncommitted work to the invoking checkout unless explicitly worktree-only. Incomplete delivery stays explicit even when commits exist.