patch skill

patch

Last leg of the defending-code loop (/threat-model → /vuln-scan → /triage → /patch). Turns a ranked list of verified findings into candidate diffs. Nothing consumes this skill's output automatically — a human reviews and applies the 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 § "Reviewing generated patches" at the end of this file. 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, Agent. Some sessions do not provision Glob or Grep. allowed-tools only pre-approves the listed tools for the invoking turn; it neither loads nor blocks any tool, so the Bash limits below are this skill's rules to follow, not limits the runtime enforces. When Glob/Grep are unavailable, fall back to the read-only Bash commands pre-approved 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/patch/scripts/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/patch/scripts/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/patch/scripts/checkpoint.py load ./.patch-state

• status == "absent" OR "complete", OR --fresh in $ARGUMENTS → fresh start. Bash: python3 .claude/skills/patch/scripts/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/patch/scripts/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/patch/scripts/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). The findings have PoC bytes + ASAN traces + reproduction commands; the pipeline's verification ladder applies.
• Stop when that directory also holds an INCIDENTS.json anywhere under it: it is a detection & response run, which writes run_*/result.json too. vuln-pipeline patch cannot patch it and this skill does not ingest incidents — say so; never delegate it.
• static mode otherwise: TRIAGE.json, VULN-FINDINGS.json, 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/patch/scripts/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. 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.
4. 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
source_ref	source, taint_source (as file:line)
sink_ref	sink, taint_sink (as file:line)

Attach id (f001, f002, ... in ingest order; preserve existing ids from TRIAGE.json) and source (relative path of the file it came from).

source_ref / sink_ref decide where the fix lands: a validation fix belongs at the source, a bounds/escaping fix at the sink, and when several findings share one sink the fix belongs there once rather than at each source. Carry them verbatim; never infer a ref the input did not carry.

From TRIAGE.json, also carry asset, impact, deployment_condition, and verify_verdict verbatim when present — they tell the human reviewer why the fix matters and under what deployment its severity moves, not just a severity label. Null when the input lacks them.

1c. Filter and order

• Compute fix_priority per finding — decoupled from severity: high when the category is a dangerous primitive (arbitrary file read/write, SSRF, command/code execution, unsafe deserialization) AND its severity is gated only by the current deployment (deployment_condition set, or verify_verdict == "reachable_no_impact"). Such a primitive is worth fixing first even at MEDIUM/LOW severity: it becomes exploitable the moment the deployment changes. Everything else: normal.
• If --id fNNN: keep only that finding.
• If --top N (static mode): sort by fix_priority (high first), then severity HIGH > MEDIUM > LOW, then confidence desc, keep the first N — so a deployment-conditional dangerous primitive is not buried under higher-severity but lower-value fixes.
• 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/patch/scripts/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/patch/scripts/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/patch/scripts/checkpoint.py save ./.patch-state 2 generate --from ./.patch-state/_chunk.tmp

2B. Static mode — one patch subagent per finding

One Agent per finding, all in a SINGLE assistant message for parallel execution. subagent_type: "patch-author" (plugin installs: defending-code:patch-author). Never set run_in_background: true — this needs the diff text. Interactive sessions background subagents by default anyway (fork mode on): expect async_launched there and use the recovery below.

Each subagent is restricted to read-only tools and 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-author instructions and tail

The full patch-author instructions are the system prompt of the patch-author agent definition (../../agents/patch-author.md relative to this skill directory — same layout in the repo and in a plugin install), shared and prompt-cached across every author in the batch. Each spawn's prompt is only the tail in references/prompts.md § Patch-author tail (Phase 2B). Fallback: if neither agent name resolves, Read the agent definition file and spawn general-purpose with its body pasted above the tail.

Spawn

For each finding in findings[], build a Agent call with the tail above (substituting {REPO_PATH}, {id}, {file}, {line}, {category}, {severity}, {title}, {description}, {recommendation}, and a fresh {nonce} per spawn — see the references/prompts.md preamble; it isolates the attacker-influenced finding text). description: "patch {id}".

If len(findings) > ~40, shard into sequential batches of ~40 (each batch one message). Per-finding shard checkpoint after each result is parsed.

If any Agent call returns status: "async_launched" instead of the subagent's text, the runtime backgrounded it. Pick one recovery and use it for the whole batch:

• If completion notifications arrive in the conversation: parse each subagent's tagged blocks from its notification result as it lands. Notifications arrive in later turns, so ending a turn to wait is fine; do not save the phase checkpoint or start the next phase until every finding is accounted for.
• If notifications do not arrive: do NOT poll transcript files. Re-spawn the missing patch subagents in a fresh Agent batch (smaller shard, e.g. 10) and use the synchronous results. The same recovery applies to reviewer subagents in Phase 3.

Parse

From each Agent result, extract the five tagged blocks. Tolerate leading/ trailing whitespace, stray ``` fences, and HTML-escaped entities (< > & — some runtimes escape angle brackets in notification payloads; unescape before writing the diff). If <patch_diff> is NONE or empty, mark status: "no_patch". Otherwise write the diff text to ./PATCHES/bug_NN/patch.diff (NN = zero-padded index in sorted order) and record rationale, variants_checked, bypass_considered, test_note.

Checkpoint per finding: Write tool → ./.patch-state/_chunk.tmp = {"id": ..., "bug_nn": "NN", "status": ..., "rationale": ..., ...}, then Bash: python3 .claude/skills/patch/scripts/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/patch/scripts/checkpoint.py save ./.patch-state 2 generate --from ./.patch-state/_chunk.tmp

---

Phase 3: Independent review (static mode only)

One reviewer subagent per generated diff, all in ONE message, subagent_type: "patch-reviewer" (plugin installs: defending-code:patch-reviewer; fallback as in Phase 2B, with ../../agents/patch-reviewer.md).

The reviewer never sees the finding's description, recommendation, or the patch author's rationale. It gets only {file, line, category} plus the raw diff bytes, and re-derives whether the diff is a minimal, in-scope fix by reading the source itself. This keeps any instructions embedded in finding prose from reaching both the author and the gate.

Reviewer instructions and tail

The full reviewer instructions are the patch-reviewer agent definition's cached system prompt. Each spawn's prompt is only the tail in references/prompts.md § Reviewer tail (Phase 3) — {REPO_PATH}, {file}, {line}, {category}, the diff, and a fresh {nonce} per spawn (it wraps the diff as untrusted data). Pass it ONLY those fields — never the finding prose or author rationale.

Spawn and parse

One Agent per finding with status != "no_patch". Parse the trailing block. Attach review, gates ({root_cause, instance_coverage, no_new_vulns, best_practices}, each pass|partial|fail, instance_coverage also skip), style_score, out_of_scope_hunks, review_reason to the finding. An ACCEPT with any gate at partial (or instance_coverage skip) is a qualified accept — count it in summary.qualified and keep the gate values visible downstream; never collapse it to a plain accept. Set verified: "static_review_only" for every static-mode result regardless of ACCEPT/REJECT — the label describes the verification class, not the outcome.

Checkpoint: Write tool → ./.patch-state/_chunk.tmp: {"phase": 3, "findings": [...]} Then Bash: python3 .claude/skills/patch/scripts/checkpoint.py save ./.patch-state 3 review --from ./.patch-state/_chunk.tmp

---

Phase 4: Output

4a. Per-finding patch_result.json

For each finding (both modes), Write ./PATCHES/bug_NN/patch_result.json:

{
  "id": "f003",
  "source": "TRIAGE.json#2",
  "title": "...",
  "file": "...",
  "source_ref": "...|null",
  "sink_ref": "...|null",
  "line": 0,
  "category": "...",
  "severity": "HIGH",
  "fix_priority": "high" | "normal",
  "asset": "...|null",
  "deployment_condition": "...|null",
  "owner_hint": "...",
  "mode": "exec" | "static",
  "verified": "ladder_passed" | "ladder_failed" | "static_review_only",
  "review": "ACCEPT" | "REJECT" | null,
  "gates": {
    "root_cause": "pass|partial|fail",
    "instance_coverage": "pass|partial|fail|skip",
    "no_new_vulns": "pass|partial|fail",
    "best_practices": "pass|partial|fail"
  },
  "style_score": 0,
  "out_of_scope_hunks": [],
  "rationale": "...",
  "variants_checked": "...",
  "bypass_considered": "...",
  "test_note": "...",
  "review_reason": "...",
  "verdict": { "t0_builds": true, "...": "(exec mode only, from pipeline)" }
}

In exec mode, also Read the pipeline's <findings_path>/reports/bug_NN/patch.diff and Write its bytes to ./PATCHES/bug_NN/patch.diff so both modes land in the same place.

4b. ./PATCHES.json

{
  "patch_completed": true,
  "mode": "exec" | "static",
  "repo": "...",
  "summary": {
    "input_count": 0,
    "patched": 0,
    "no_patch": 0,
    "accepted": 0,
    "qualified": 0,
    "rejected": 0,
    "ladder_passed": 0
  },
  "findings": [ { ...patch_result.json shape... } ]
}

4c. ./PATCHES.md (incremental)

Step 1 — header. Write tool → ./PATCHES.md (clobbers prior):

# Candidate Patches

{if mode == "static":}
> **Static review only.** These diffs were authored and reviewed by
> independent agents reading source. They were NOT compiled, run, or
> re-attacked. Read each diff yourself before applying — see § "Reviewing
> generated patches" in the skill for what to look for.

{if mode == "exec":}
> **Execution-verified.** Each diff passed (or failed) the external harness's
> verification ladder: build → reproduce → regress → re-attack. The ladder
> proves the crash is gone, not that the diff introduces no new problems.

**Input:** {findings_path} · **Repo:** {repo} · {N} findings → {M} diffs

---

Step 2 — per finding (sorted: ACCEPT/ladder_passed first, then fix_priority high first, then by severity). Write ./.patch-state/_chunk.tmp:

## bug_{NN}: [{severity}{if fix_priority == "high"}, FIX-FIRST{/if}] {title}  ({id})

`{file}:{line}` · {category} · owner: {owner_hint or "?"}
{if source_ref or sink_ref}**Flow:** {source_ref or "?"} -> {sink_ref or "?"}{/if}
**Asset:** {asset or "?"} · **severity moves if:** {deployment_condition or "n/a"}
**Status:** {verified} · review {review or "n/a"} · style {style_score or "n/a"}/10
{if gates:}**Gates:** root-cause {gates.root_cause} · coverage {gates.instance_coverage} · no-new-vulns {gates.no_new_vulns} · best-practices {gates.best_practices}
**Diff:** `PATCHES/bug_{NN}/patch.diff` ({hunk count} hunks, {line count} lines)

**Rationale:** {rationale}
**Variants checked:** {variants_checked}
**Bypass considered:** {bypass_considered}
{if review == "REJECT":}
> **Rejected by reviewer:** {review_reason}
{if out_of_scope_hunks:}
> **Out-of-scope hunks:** {out_of_scope_hunks}

---

Then checkpoint.py append ./PATCHES.md --from ./.patch-state/_chunk.tmp.

Step 3 — footer. Append a ## Skipped table for findings with no file or status == "no_patch", one line each with the reason.

Checkpoint (final): Bash: python3 .claude/skills/patch/scripts/checkpoint.py done ./.patch-state 4

4d. Terminal summary

Under ~10 lines:

Patches generated ({mode} mode): {N} findings → {M} diffs.

  Accepted:  {n}   {title of top accepted}
  {if any:} Qualified accepts (a gate at partial/skip): {n} — read their Gates lines
  Rejected:  {n}
  No patch:  {n}
  {if exec:} Ladder passed: {n}/{M}

Wrote ./PATCHES/bug_NN/, ./PATCHES.md, ./PATCHES.json
{if static:} These are drafts. Review before applying — see § "Reviewing generated patches".

End of the defending-code loop. No skill applies these; a human does.

---

Guard rails

• The skill never applies diffs. No git apply, no patch, no Edit against --repo. Needing to means the design is wrong.
• Write only under ./PATCHES/ and ./.patch-state/.
• Reviewer isolation. The reviewer prompt receives {file, line, category, diff} and nothing else from the finding. Do not pass it description, recommendation, exploit_scenario, or the patch author's rationale.
• Always set subagent_type; never fork. An omitted type falls back to general-purpose, losing the read-only agent definition; a fork inherits the whole conversation, leaking every finding's prose into every subagent.
• All Agent calls for a phase in ONE message. Serial spawning is correct but N× slower.
• Checkpoint before starting the next phase, every time.
• Exec mode delegates, never reimplements. The execution-verified ladder belongs to an external harness (the defending-code reference pipeline; see ../vuln-scan/HARNESS.md). If its vuln-pipeline patch binary isn't on PATH, stop and tell the user the harness isn't installed; don't fall back to static mode silently.

---

Testing this skill

Static mode against any repo with known findings — run the loop end to end:

/vuln-scan <target-dir>
/triage <target-dir>/VULN-FINDINGS.json --repo <target-dir> --auto
/patch TRIAGE.json --repo <target-dir> --top 3

Expected: one diff per top finding under PATCHES/bug_NN/, each verified: "static_review_only" with a review ACCEPT/REJECT verdict and a style score. Spot-check that ACCEPTed diffs are minimal, root-cause fixes that match surrounding style.

Execution-verified mode requires an external harness (see ../vuln-scan/HARNESS.md). Point /patch at a harness results/<target>/<ts>/ directory; it delegates to vuln-pipeline patch, surfaces verified: "ladder_passed" per bug, and copies diffs into ./PATCHES/.

---

Reviewing generated patches

These diffs are candidates, never auto-applied. Before applying one:

1. Read the diff against the source. Confirm it changes only code on the path between the finding's file:line and its callers — no drive-by edits.
2. Root cause, not symptom. Reject patches that swallow the error (try/except: pass, early-return on a magic value, deleting the check that fired, lowering a log level) instead of fixing the underlying bug.
3. No new attack surface. Confirm the diff doesn't add parsing, trust a new input field, or weaken validation elsewhere.
4. Run the regression test. Static-mode diffs embed a test that should fail before the change and pass after. Run it yourself; the skill could not.
5. Minimal. Prefer the smallest change that fixes the root cause. An over-broad patch is harder to review and more likely to break a dependency.

A human owns the final patch. The skill's job is to make that review cheap, not to replace it.

---