code-remediate

Before asking, read User Questions.

Code Remediate

When independently reviewing applied fixes in a cycle, read ../../shared/adversarial-loop.md for convergence and stop rules. A clean loop never replaces selection, implementation evidence, or this skill's normal completion gates; after authorized recovery, resume them.

See the fixed recurrence and root-cause policy and reasoning-progress escalation policy for repeated-obstacle handling; record and validate reasoning-progress.json before another cycle after escalation trigger.

Run linear code remediation to close findings.

Input Schema

{
  "findings_source": "optional path, explicit list, review for the current-session assessed review, or +review/+report/report/latest to auto-select the newest matching PR review report; omit with a bare PR target to use current online review items",
  "mode": "optional report|pr|auto; infer pr for bare number, #number, or PR URL",
  "target": "optional shorthand target number, issue/PR URL, path, or current branch",
  "pr_target": "optional PR number, PR URL, or current branch PR when mode=pr",
  "approve_gh": "optional boolean; default false; --approve-gh means the user has already approved required GitHub operations; use managed host preapproval to run without another prompt",
  "remediation_scope": "optional all|critical|high|medium|low|comma-separated severities|comma-separated selection indexes; ask before editing when omitted",
  "target_scope": "required path/module",
  "done_when": "selected findings are fixed/resolved and unselected critical/high findings are explicitly deferred"
}

Workflow (Exact Commands)

For --approve-gh, apply Managed Host Preapproval to the helper actually used. Reuse the loaded matching host allow rule and execute directly; do not introduce a workflow confirmation or a wrapper that breaks matching. Diagnose unexpected prompts with the exact command and applicable rules. Missing or stricter host permissions remain authoritative.

01: Create Run Directory

Run create_run.py --skill code-remediate per ../../shared/helper-cli-contract.md.

02: Normalize input and optional report findings

Shorthand rules:

• Normalize a standalone --approve-gh before target or report parsing: set approve_gh=true. Remove --approve-gh before invoking collect_pr.py; it is a skill flag, not a collector option. Never infer it from PR evidence; only direct user invocation may supply it. Repeated exact --approve-gh is idempotent. Reject --approve-gh=<value> as approve-gh-invalid-value.
• $code-remediate 123 --approve-gh => mode=pr, PR_TARGET=123, REQUESTED_REPORT=false, approve_gh=true. Existing explicit report aliases remain report-backed. Outside mode=pr, fail approve-gh-requires-pr before collection. Without --approve-gh, preserve existing PR collection approval behavior. --approve-gh never selects remediation_scope=all; continue normal scope selection.
• Canonical in-session report: $code-remediate review => mode=report, REQUESTED_REPORT=true, FINDINGS_SOURCE=latest-assessed-current-session-review. It resolves to the latest assessed code-review result created in the current session. Reuse the exact prior artifact path recorded in this session; do not scan reports or infer a PR target. Do not collect PR evidence or fetch online review comments. If no assessed current-session review result is available, fail with current-session-review-report-required and instruct the user to run $code-review <target> first or supply a report path.
• Canonical online-only PR: $code-remediate #123 => mode=pr, PR_TARGET=123, REQUESTED_REPORT=false, FINDINGS_SOURCE=none. Accepted bare PR forms are: bare number, #number, PR URL, and natural-language bare PR targets; they collect current online items and verified local checkout without a prior review report.
• Natural-language online-only aliases: remediate 123, remediate #123, remediate PR 123, and remediate <github-pr-url> use same bare-PR route.
• Canonical report-backed PR: $code-remediate #123 +review => mode=pr, PR_TARGET=123, REQUESTED_REPORT=true, FINDINGS_SOURCE=latest-matching-review-report.
• matching-review-incomplete:<run-directory> means identified review retained notes but never produced promoted result or candidate. First explain in plain English that preliminary evidence exists but review did not complete; then state Review handoff blocked, link that retained run, and name exact failed checkpoint with evidence-backed next action. Return to producer completion checkpoint and perform permitted diagnosis yourself; do not claim no review was performed, consume notes as validated result, select older verdict, or switch to online-only intake. This applies across sessions as well as within one session. A newer malformed result similarly blocks stale assessed fallback.
• Compatibility alias: $code-remediate #123 +report => mode=pr, PR_TARGET=123, REQUESTED_REPORT=true, FINDINGS_SOURCE=latest-matching-review-report; $code-remediate #123 +report compatibility alias has same report lookup.
• Natural-language aliases: remediate 123 report, remediate #123 report, and remediate PR 123 report => mode=pr, PR_TARGET=123, REQUESTED_REPORT=true, FINDINGS_SOURCE=latest-matching-review-report.
• remediate <github-pr-url> report => mode=pr, PR_TARGET=<github-pr-url>, REQUESTED_REPORT=true, FINDINGS_SOURCE=latest-matching-review-report.
• An explicit review result path combined with PR target sets REQUESTED_REPORT=true; bare PR target has no implicit report path.
• Bare PR and report-backed PR routing are distinct: explicit +review, +report, report aliases, and report paths retain report-plus-online behavior; absence of report source selects online-only intake and never falls back to report lookup.
• If +review, +report, report, latest, latest-report, or review-report replaces path, find newest matching result across canonical .reports/codex/code-review/pr-<number>/run-<NNN>/result.json and legacy flat .reports/codex/code-review/<timestamp>/result.json artifacts whose sibling pr.json has same PR number/URL as PR_TARGET.
• When REQUESTED_REPORT=true, no matching code-review report means the requested assessed findings are missing. Explain that first, then ask for an existing report path or permission to run $code-review <target> if not already authorized. A matching-review-unavailable-rerun-code-review result means PR collection failed before any assessed review; do not use it as findings input. Inspect that run's classified error and retained checkout diagnostics, perform permitted recovery, and rerun collection only when the diagnosed cause or external state supports it; ask only for the specific missing access or decision. A matching-review-closed-not-remediable result is a terminal close disposition with no source findings; do not remediate it or fall back to an older assessed report. A matching-review-candidate-unpromoted:<path> result requires the bounded same-session recovery below; do not fall back to an older assessed report.
• When canonical matching PR runs exist, select greatest parsed numeric run-<NNN> index. Otherwise select greatest parsed legacy flat timestamp. Never rely on lexical glob order, modification time, or directory traversal order; record selected path in <run-directory>/findings-input.txt.

When FINDINGS_SOURCE=latest-matching-review-report, inspect python PLUGIN_ROOT/shared/find-review-report.py --help, resolve PR_TARGET against .reports/codex/code-review, and assign printed path to FINDINGS_SOURCE. The helper searches explicit canonical nested PR runs plus legacy flat timestamped runs; no migration is required. It filters explicit review_status=unavailable diagnostics, so older assessed review remains eligible when newer collection failure exists. A newer review_status=closed result instead blocks older findings because close disposition is current and non-remediable. Before accepting explicit review result path as findings input, invoke same helper with --result <path>; it rejects unavailable results with rerun instruction, closed results with matching-review-closed-not-remediable, and candidate paths with matching-review-candidate-unpromoted:<path>. A bare PR target must not run this helper, scan prior review reports, or require a code-review artifact.

Explicit local working-tree, path and commit intake requires canonical result.json and reruns both producer artifact validators, including source/provenance and final-handoff bindings, before returning its path. A plausible recommendation or filename alone is not validation. For a report produced in another session, pass its recorded producer thread through the existing --parent-thread-id option; use --codex-home only for the actual retained rollout root when needed. These identify evidence for validation, never waive it. Without overrides the helper uses current runtime defaults. Missing or invalid evidence stops intake; retain the validation diagnostic and return to the producer checkpoint without falling back to an older report. PR-only automatic discovery remains unchanged.

For matching-review-candidate-unpromoted:<path>, recover only when the candidate's specialist-manifest.json names the same parent thread as the current remediation session. Run the review-specific validator, then the shared validator, against that exact candidate and its review run directory; promote it to result.json only after both validators pass, then rerun the finder and use the promoted result. Never consume result.candidate.json directly. If either validator fails, persist its exact stderr code in <run-directory>/review-candidate-validation.txt, including manifest-invalid-attempt-count:<role> when applicable, and return to the code-review manifest preflight checkpoint for one evidence-preserving repair from retained specialist and rollout records. Never invent missing attempt provenance or retry a specialist for artifact bookkeeping. After a repaired manifest passes --manifest-only, rerender/rewrite the candidate as required and retry both validators once. If exact evidence cannot repair the run or either validator still fails, do not promote the candidate, rerun the full review, or fall back to an older assessed report; stop this candidate-repair operation with the exact error and candidate path. Explain the failed proof in plain English and use Code Review's Reviewer validation recovery guidance to propose a return to the producer for fresh sequential inspection or a supported independent route; do not launch that new review without existing authorization or the user's choice. Remediation resumes only after the producer completes and validates the requested review. This recovery has no waiting loop and makes no remote mutation.

When FINDINGS_SOURCE exists, copy its exact bytes to <run-directory>/findings-input.txt with filesystem tool. Do not depend on shell variable retaining that source path. For bare PR online-only intake, do not create <run-directory>/findings-input.txt; set CODE_REMEDIATE_METADATA.review_report_intake.requested_report=false and every report-item counter to 0.

For mode=pr, inspect python PLUGIN_ROOT/shared/collect_pr.py --help; collect PR_TARGET into <run-directory>/pr with --checkout --checkout-mode remediate for current online evidence, target/head refresh, and local checkout. Remediation first invokes gh pr checkout <canonical PR URL>, including when the current HEAD already equals the PR head. If that command fails, only a verified same-repository PR may use direct Git checkout of its actual PR branch; fork PRs use the bounded recovery loop below.

On resume, inspect an existing <run-directory>/remediation-branch.json before collection. If <run-directory>/remediation-branch-recovered.json exists, use it for all continuation checks; never replace it or fall back after a failed check. Otherwise, a schema-1 receipt uses the legacy recovery procedure below. Check the selected receipt against the last recorded authorized revision with remediation_branch.py check; never recollect with checkout merely to replace local remediation commits or edits with the original PR head. Reuse still-valid source receipts and closure evidence. If fresh PR metadata changes the source contract, preserve the current branch and work and resolve that integration decision before further edits.

When approve_gh=true, treat required GitHub operations as already approved by the user. Do not ask for another workflow confirmation. Apply PR Collection Preapproval before collector execution, including the direct command and exact PR URL prefix. Do not create or modify runtime approval rules files.

In runtimes with network sandboxing, execute the complete collector command with approved external network access from its first attempt under ../../shared/native-skill-contract.md. Before requesting it, state:

• Action and purpose: collect current PR evidence before remediation.
• External capability: read-only GitHub access plus documented local checkout.
• Credential behavior: gh is opaque local credential broker.
• Filesystem and worktree effects: write collection artifacts and may update local checkout.
• Retry policy and safe denial outcome: one classified recovery only, otherwise remediation uses its core collection-failure path.
• For Codex exec, set sandbox_permissions="require_escalated" on the collector with a narrow read-only GitHub justification; never request a broad python approval prefix. Apply the other shared runtime and denial boundaries. A direct approval for gh pr view does not cover gh spawned by the collector: the outer collector command owns its nested GitHub CLI, HTTPS fallback, checkout, and Git fetch traffic. Completed user authorization through --approve-gh removes workflow reconfirmation, never runtime permission checks.
• If an agent-caused unapproved attempt returns github-network before any user approval request or denial, rerun that same complete collector command once through the runtime's external-network approval mechanism before treating collection as terminal. This recovery exists only for that pre-denial sandbox mistake; after the user denies approval, the current turn stops and the retry is forbidden. Only after that approved collector attempt fails, external-network approval is unavailable, or the user denies it may remediation apply its core collection-failure path; never repeat more than one approved recovery attempt.

github_read.py is plugin-wide GitHub data boundary: do not invoke gh outside it.

• It uses gh as opaque local credential broker, never invokes gh auth, reads token/keychain state, or persists GitHub CLI failure output.
• It permits only audited built-in view groups (gist, issue, pr, project, release, repo, ruleset, run, workflow), REST GET, and GraphQL queries; no remote mutation is permitted.
• Its public HTTPS fallback cannot establish private PR evidence.

Core and supplemental evidence:

• collect_pr.py treats PR identity/body plus exact local source as core evidence. In remediation mode it must first record the canonical gh pr checkout <canonical PR URL> attempt, checkout_mode=remediate, an attached local branch, and the exact verified PR head; a matching HEAD does not skip that command. After a failed command, only a same-repository PR may record direct checkout of the actual headRefName branch, with local branch name, exact SHA, merge tracking, and effective destination identity all verified. Fork recovery must end in a successful attached gh checkout. It derives diff.patch locally. Its worktree-preflight.json preserves unrelated tracked edits but blocks unresolved index entries, edits to PR-changed files, and paths checkout would overwrite; matching HEAD does not bypass these checks.
• Retain checkout force_policy and classified failure evidence: no forced checkout, manual tracking repair, reset, rebase, stash, or discarded user changes. A failed remediation checkout stops before edits or commits unless the verified same-repository branch route or the bounded fork recovery loop completes.
• GraphQL review-thread resolution status is supplemental; if unavailable, collector writes empty normalized thread arrays plus review-threads-error.txt and continues.
• Record that online-triage coverage gap in action-items.md, result confidence gaps, and unresolved/deferred closure rationale; never treat it as code finding or silently claim complete thread triage.
• On core collection failure, use <run-directory>/pr/pr-error.txt, <run-directory>/pr/worktree-preflight.json, and <run-directory>/pr/command-failure.json when present to distinguish classified process failure from source-review findings; for dirty-worktree overlap, name exact overlapping_paths first; do not treat it as merge recommendation.

When gh pr view metadata fails, public unauthenticated HTTPS fallback is eligible only when all of these hold:

• The failure is github-network, github-auth, github-rate-limit, or command-timeout.
• The checkout target is trusted: canonical PR URL must match configured GitHub remote; numeric target requires exactly one distinct configured GitHub repository identity.

Ambiguous or unsafe targets, permission failures, not-found failures, and unclassified failures remain fail-closed.

Fallback behavior:

• Public metadata fallback alone never satisfies remediation's attached-branch checkout contract or authorizes edits. It may supply limited metadata for the same-repository original-branch route only when every identity, checkout, destination, and degraded-evidence gate passes. After gh pr checkout fails, remediation has no exact-commit, detached, unverified cached-ref, generated-branch, or manual set-upstream fallback; only the verified same-repository original-branch route or the fork recovery loop is permitted.
• online-review-summary.json must list unavailable fallback evidence as sorted IDs.
• Raw GitHub CLI stderr is never persisted; terminal diagnostics may include safe failure_reason enum alongside non-secret classification metadata.

Findings intake:

• For mode=report, normalize only the review report after confirming it is assessed. Reject review_status=unavailable and review_status=closed; the latter is a close disposition without source findings. Do not read, collect, or infer any <run-directory>/pr/ evidence.
• For mode=pr, always normalize <run-directory>/pr/comments.json, <run-directory>/pr/reviews.json, <run-directory>/pr/review-threads.json, and <run-directory>/pr/unresolved-review-threads.json.
  • When REQUESTED_REPORT=false, those current online records are complete findings source. Do not read or infer review report, and do not require prior assessed artifact. If no online item is actionable after triage, continue through documented none-selectable path instead of requesting code-review.
  • When REQUESTED_REPORT=true, additionally normalize <run-directory>/findings-input.txt. Treat review report as closure contract, not only code findings: before editing normalize report findings, failed checks_failed, follow_up, review_decision.required_next_work, confidence gaps, confidence-recovery remaining limits, and no-finding residual risks into report-origin action items.
  • Use local checkout in <run-directory>/pr/local-checkout.json as the authoritative collected PR source and require its verified-local-checkout diff provenance. After authorized target integration, apply the recorded merge result as described below; do not switch back to the unmerged PR head for finding edits.
  • Refresh both target and PR head yourself before conflict/review-item resolution; <run-directory>/pr/target-branch.json and <run-directory>/pr/pr-head-fetch.json must record fetched tips, including fork PRs. Normal fetches use no persistent ref destinations and avoid forced cache updates; the verified same-repository original-branch fallback may instead perform a guarded local update of an explicitly selected remote-tracking ref from the already fetched, verified PR head, using the observed prior value and preserving divergent or concurrently changed refs, for native tracking creation. Do not perform a second network fetch for that update. Capture verified IDs before another fetch changes FETCH_HEAD. Routine freshness is agent-owned work, not request for user to pull branches. Use the immutable fetched target ID in target-branch.json.remote_ref; separate local target checkout is unnecessary.
  • Remediation checkout artifacts must prove checkout_mode=remediate, the initial gh pr checkout <canonical PR URL> command and result, attached branch, and exact PR head. If that command fails, retain its safe classified cause and fresh local identity/state. A same-repository fallback must prove head_repository == base_repository, local branch name equals headRefName, exact head SHA, branch.<name>.merge=refs/heads/<headRefName>, and effective push destination identity; native tracking setup performed by the authorized direct checkout is allowed, but manual tracking repair is not. A fork fallback must complete the bounded recovery loop and then rerun gh to obtain an attached branch. Any detached, wrong-branch, wrong-head, unverified destination, or incomplete loop stops before prepare, edits, merges, or commits. Never replace it with exact-SHA detach, an unverified cached-ref checkout, a generated branch, or a generic "repair checkout" instruction. If fresh fetched evidence proves the PR moved, a new authorized collection must still use this remediation checkout route.
  • If core metadata, target refresh, checkout, or local diff fails, record failure; continue with supplied report only when user accepts stale online-review coverage and no code edits are required, else fail.
  • If only supplemental review-thread resolution status is unavailable, continue with explicit partial-coverage evidence and do not infer that any thread is resolved.
  • Never inspect/edit PR code from curl, raw.githubusercontent.com, or copied head-files/ snapshots; raw-file snapshot rejection: snapshots are rejected.

Collection failure recovery

Explain a failed pr-head-fetch as "The PR refresh failed before checkout verification, so I have not yet established which code is safe to fix." The commit may already exist locally; a failed cache/ref update is not proof that it could not be downloaded. When evidence proves the PR advanced, explain that the previous review covers an older version and include the actual old/current identifiers after that explanation. A failed fetch does not prove an authentication problem, unavailable contributor fork, or local merge failure; when the safe diagnostic lacks a cause, state that the reason is unknown.