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)

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": ...}