patch

# patch Third leg of the static pipeline (`/vuln-scan` → `/triage` → `/patch`). Turns a ranked list of verified findings into candidate diffs. The skill **never applies a diff** to the target repo. Output is inert text in `./PATCHES/` for a human to review and apply out-of-band — see `docs/patching.md#reviewing-generated-patches`. There is no `--apply` or `--approve` flag by design: the capability isn't present, so it can't be prompt-injected into use. Invoke with `/patch <findings-path> [--repo PATH] [--top N] [--id fNNN] [--model M] [--fresh]`. **Arguments** (parse from `$ARGUMENTS`): - findings path (first positional, required): `TRIAGE.json`, `VULN-FINDINGS.json`, a pipeline `results/<target>/<ts>/` directory, or any JSON the `/triage` ingest table recognizes. - `--repo PATH`: target codebase, read-only (default cwd). Required for static mode; the skill stops if cited files don't resolve under it. - `--top N`: patch only the N highest-severity true positives (static mode). - `--id fNNN`: patch only the finding with this id. - `--model M`: passed through to `vuln-pipeline patch` in execution-verified mode. Ignored in static mode (subagents inherit the orchestrator's model). - `--fresh`: ignore `./.patch-state/` checkpoint and start over. **Tools.** Prefer Read, Glob, Grep, Write, Task. Some sessions do not provision Glob or Grep; `allowed-tools` is a permission filter, not a loader. When they are unavailable, fall back to the read-only Bash commands whitelisted above: `rg`/`grep` for search, `ls` for enumeration, `head`/`file`/`wc` for sniffing, `jq` for JSON ingest. Bash is otherwise permitted only for `python3 .claude/skills/_lib/checkpoint.py` (state I/O) and `vuln-pipeline patch` (execution-verified delegate). `find` is NOT permitted. **Write scope.** The Write tool may target ONLY paths under `./PATCHES/` and `./.patch-state/`. Never write into `--repo`, never `git apply`, never `patch`, never edit target source. If a step seems to require it, the step is wrong. --- ## Checkpointing (runs before Phase 0 and after every phase) State persists to `./.patch-state/` so a fresh `/patch` session resumes without re-spawning patch or reviewer subagents. All checkpoint I/O goes through `python3 .claude/skills/_lib/checkpoint.py` (atomic, JSON-validated). The Write→`--from` pattern keeps repo-derived bytes out of Bash argv; never pass payload via heredoc or stdin. State files: `progress.json` (single source of truth: `{"status": "running"|"complete", "phase_done": N, "shards_done": [...]}`), `phaseN.json`, `_chunk.tmp`. **Start of run.** Bash: `python3 .claude/skills/_lib/checkpoint.py load ./.patch-state` - `status == "absent"` OR `"complete"`, OR `--fresh` in `$ARGUMENTS` → fresh start. Bash: `python3 .claude/skills/_lib/checkpoint.py reset ./.patch-state`, proceed to Phase 0. - `status == "running"` with `phase_done == N` → resume. Read `phase0.json`..`phaseN.json` in order (and any `shard_*.json` listed in `shards_done`), merge into working state, print `Resuming from checkpoint: Phase N complete`, skip to Phase N+1. Do not re-spawn any subagent whose output is already checkpointed. **End of every phase N.** Write tool → `./.patch-state/_chunk.tmp` with the phase's JSON, then Bash: `python3 .claude/skills/_lib/checkpoint.py save ./.patch-state <N> <name> --from ./.patch-state/_chunk.tmp` **End of run.** After writing `PATCHES.md` and `PATCHES.json`, Bash: `python3 .claude/skills/_lib/checkpoint.py done ./.patch-state 4` --- ## Phase 0: Parse arguments and detect mode ### 0a. Parse `$ARGUMENTS` Extract findings path (first positional), `--repo` (default `.`), `--top`, `--id`, `--model`, `--fresh`. If no findings path, stop and ask. ### 0b. Detect mode Inspect the findings path: - **execution-verified mode** when the path is a directory containing `reports/manifest.jsonl` OR `found_bugs.jsonl` OR `run_*/result.json` (pipeline output) — unless an `INCIDENTS.json` is present anywhere in it: D&R run dirs also contain `run_*/result.json`, and their incidents route static. The findings have PoC bytes + ASAN traces + reproduction commands; the pipeline's verification ladder applies. - **static mode** otherwise: `TRIAGE.json`, `VULN-FINDINGS.json`, `INCIDENTS.json` (the `/dnr-*` output), generic finding JSON, or markdown. No PoC; the oracle is a fresh-context reviewer. Record `mode` in working state. The two modes share Phase 1 ingest then fork at Phase 2. **Checkpoint:** Write tool → `./.patch-state/_chunk.tmp`: `{"phase": 0, "mode": "exec"|"static", "args": {repo, top, id, model, findings_path}}` Then Bash: `python3 .claude/skills/_lib/checkpoint.py save ./.patch-state 0 mode --from ./.patch-state/_chunk.tmp` --- ## Phase 1: Ingest and normalize Same input contract as `/triage` Phase 1. Normalize every input format to a flat `findings[]` of dicts. Pull what's present; never guess what's absent. ### 1a. Recognized containers (priority order) 1. **`TRIAGE.json`** — read `.findings[]`. **Filter to `verdict == "true_positive"`.** This is the canonical input: already verified, deduped, ranked, owner-tagged. 2. **`VULN-FINDINGS.json`** — read `.findings[]`. Unverified; print `Warning: VULN-FINDINGS.json is unverified scanner output. Consider /triage first.` and continue. 3. **`INCIDENTS.json`** (the `/dnr-hunt` / `/dnr-respond` output) — same mapping as `/triage` 1a: one finding per `.incidents[]` entry, nested `vuln.file`/`vuln.line`/`vuln.type` → `file`/`line`/`category`, `description` ← `vuln.mechanism` plus `impact`, and keep `poc` — a `confirmed_exploited` incident's `poc.command` is the regression check for its fix. The top-level `ruled_out` array is not findings. Print `Warning: INCIDENTS.json has not been triaged. Consider /triage first.` and continue. No-`file` incidents follow 1c like any other finding. 4. **Pipeline results directory** — one finding per `reports/bug_NN/`. Map `report.json` → `description`, `crash.crash_type` → `category`, ASAN top-frame → `file`/`line`. Record `bug_id = NN` for the `--bug N` delegate flag. 5. Generic `*.json` with a top-level list or a `findings`/`results`/ `issues`/`vulnerabilities` array. ### 1b. Field aliases (canonical ← also-accept) | Canonical | Also accept | |------------------|----------------------------------------------------------| | `file` | `path`, `location.file`, `filename` | | `line` | `line_number`, `location.line`, `lineno` | | `category` | `type`, `cwe`, `rule_id`, `crash_type` | | `severity` | `severity_rating`, `level`, `priority` | | `title` | `name`, `summary`, `message` | | `description` | `details`, `report`, `body`, `evidence`, `rationale` | | `recommendation` | `fix`, `remediation`, `mitigation` | | `owner_hint` | `owner`, `component` | Attach `id` (`f001`, `f002`, ... in ingest order; preserve existing ids from TRIAGE.json) and `source` (relative path of the file it came from). ### 1c. Filter and order - If `--id fNNN`: keep only that finding. - If `--top N` (static mode): sort by `severity` HIGH > MEDIUM > LOW then `confidence` desc, keep the first N. - Drop findings with no `file` (cannot patch what cannot be located). Record them as `skipped` with reason `"no source location"`. ### 1d. Locate the target codebase (static mode) Resolve `--repo`. For the first 5 findings with a `file`, check the path resolves under repo (try as-given, then with common prefixes stripped). If none resolve, **stop**: tell the user the cited files aren't reachable and suggest a `--repo` value. **Checkpoint:** Write tool → `./.patch-state/_chunk.tmp`: `{"phase": 1, "mode": ..., "findings": [...], "skipped": [...], "repo": ...}` Then Bash: `python3 .claude/skills/_lib/checkpoint.py save ./.patch-state 1 ingest --from ./.patch-state/_chunk.tmp` --- ## Phase 2: Generate patches Forks on `mode`. ### 2A. Execution-verified mode — delegate to the pipeline The pipeline already implements the build → reproduce → regress → re-attack ladder with executable oracles. Do not reimplement it. For each finding (or once for the whole directory if no `--id`/`--top` filter), Bash: ``` vuln-pipeline patch <findings_path> --model <--model arg> [--bug <bug_id>] ``` The pipeline writes `<findings_path>/reports/bug_NN/{patch.diff, patch_result.json}` itself. After it returns, Read each `patch_result.json` and copy `verdict` + `rationale` into working state. Set `verified: "ladder_passed"` when `verdict.passed == true`, else `verified: "ladder_failed"`. If the CLI exits non-zero (no `build_command`, missing target config), record the stderr as the finding's `error` and continue with remaining findings. Skip Phase 3 (the ladder is the verifier). Proceed to Phase 4. **Checkpoint per finding:** Write tool → `./.patch-state/_chunk.tmp` = `{"id": ..., "verified": ..., "verdict": ..., "diff_path": ...}`, then Bash: `python3 .claude/skills/_lib/checkpoint.py shard ./.patch-state <id> --from ./.patch-state/_chunk.tmp`. After all findings, write the consolidated phase payload to `_chunk.tmp` then: `python3 .claude/skills/_lib/checkpoint.py save ./.patch-state 2 generate --from ./.patch-state/_chunk.tmp` ### 2B. Static mode — one patch subagent per finding One Task per finding, all in a SINGLE assistant message for parallel execution. `subagent_type: "general-purpose"`. Never set `run_in_background` — you need the diff text, not an async handle. Each subagent has read-only access to `--repo`. It cannot modify the target; it emits the diff as text in its response. The orchestrator writes that text to `PATCHES/bug_NN/patch.diff`. #### Patch subagent prompt (assemble once, reuse per finding) ``` You are conducting authorized security research as part of a defensive assessment. Your task: write a candidate fix for ONE verified vulnerability finding in a codebase you have read-only access to. You may use Read, Glob, and Grep ONLY on paths inside {REPO_PATH}. You may NOT build, run, install, edit files on disk, or reach the network. You will emit the fix as a unified diff in your final response; you will NOT apply it. ──────────────────────────────────────────────────────────────────────── FINDING: id: {id} file: {file} line: {line} category: {category} severity: {severity} title: {title} description: {description} recommendation: {recommendation or "(none provided)"} ──────────────────────────────────────────────────────────────────────── PROCEDURE: 1. READ THE CODE. Open {file} at line {line} and the surrounding function. Understand what the code does — do not trust the finding's description as the only source. 2. ROOT CAUSE FIRST. Trace backward from the cited sink to where the bad value or missing check originates. The fix usually belongs there, not at the line the scanner flagged. Name the root-cause location (file:line). 3. VARIANT HUNT. Grep for sibling call sites with the same pattern. Your fix should cover all of them, or your rationale should say why not. 4. MINIMAL DIFF. Smallest change that fixes the root cause. No refactoring, no drive-by cleanup, no reformatting, no comment-only changes. Match the surrounding code's style (brace placement, naming, error handling). 5. ADVERSARIAL SELF-CHECK. Re-read your diff as an attacker. Name one input variation that would reach the same bad state without tripping your change. If you can name one, your fix is at the wrong layer — go back to step 2. 6. REGRESSION TEST. As part of the diff, add ONE test case that fails before your change and passes after — placed wherever the project keeps its tests (look for test_*/, *_test.*, tests/, spec/). If no test directory exists, omit the test and say so in <test_note>. ──────────────────────────────────────────────────────────────────────── OUTPUT — your final response MUST contain exactly these tags. Emit the diff verbatim between the markers; do NOT wrap it in ``` fences. <patch_diff> --- a/path/to/file +++ b/path/to/file @@ ... @@ context line -removed line +added line </patch_diff>