mantis-patch

name	mantis-patch
description	Generates minimal security fixes using transactional isolation (shadow directories or file backups), applies patches, and verifies them. Use when security findings are successfully reproduced and need patches applied and verified. Don't use for initial vulnerability research or reproduction payload generation.

Patcher (/mantis-patch)

System Goal

Security Patching Expert. Generates minimal, correct code fixes, applies them to source code files, and verifies them inside isolated sandboxes before appending logs to long-term memory.

Command Definition

• Command: /mantis-patch [--target_root=<path>] [--state_root=<path>] [--snapshot_root=<path>] [--snapshot_id=<id>] [--snapshot_pinned=<true|false>]
• Description: Generates minimal security fixes using transactional isolation (shadow directories or file backups), applies patches, and verifies them.
• Parameters (all optional; absent ⇒ today's behavior):
  • --target_root: Root of the code snapshot to read (CODE_ROOT). When the orchestrator pins a snapshot it passes --snapshot_root; --target_root is reserved for a caller that hands you an already-prepared tree.
  • --snapshot_root: Root of the pinned immutable snapshot for this pass.
  • --snapshot_id: The SNAPSHOT_ID string of the pinned snapshot (used by the Snapshot Match Check).
  • --snapshot_pinned: true when a pinned immutable snapshot exists this pass; false/absent ⇒ degraded/legacy (see Backward-compat).
  • --state_root: Root of the Mantis state directory that contains workspace/ (defaults to the current directory). ALL workspace/... paths in this file are STATE-RELATIVE and resolve under <state_root>/workspace/....

Input/Output Contract

• Reads:
  • workspace/findings/ (reproduced finding JSON files where patch_status is not "VERIFIED_SECURE" or "MITIGATION_PROPOSED").
  • workspace/.mantis_state.json (to track current loop pass).
  • workspace/.mantis_state.json active_snapshot (root, snapshot_id, snapshot_pinned) — resolved via Block A; supplies CODE_ROOT and the SNAPSHOT_ID used by the Snapshot Match Check when no --snapshot_* flag is passed.
  • Target source code files.
  • Reproducer script path (repro_file_path) and command (run_command) from findings.
  • Pre-existing backup files matching finding ID (if Option B is used).
• Writes:
  • Source code modifications (applied transactionally and rolled back).
  • Updates finding JSON files in-place (sets "patch_status", "patch_diff", re-attack details including "reattack_status" and "reattack_variants", and history).
  • Appends to workspace/learnings.jsonl.
  • Reusable helper script workspace/helpers/append_patch.py.
• Preconditions:
  • Findings must exist in workspace/findings/.
• Idempotency Guarantee:
  • Snapshot-aware skip: Skips a finding whose patch_status is already "VERIFIED_SECURE" or "MITIGATION_PROPOSED" ONLY when its recorded patch_base_snapshot equals the current SNAPSHOT_ID (i.e. it was verified against THIS snapshot). If patch_base_snapshot is absent, empty, or different from the current SNAPSHOT_ID, the terminal status is stale — do NOT skip; re-open and re-verify the finding against the current snapshot. In legacy mode (no active_snapshot and no --snapshot_* flags) skip exactly as today (by patch_status alone).
  • Transactional isolation: modifies code inside uniquely generated temporary directories or creates temporary file backups (target.c.bak-[id]), restoring baseline state upon completion (using rollback mechanisms).

Instructions

Fix successfully reproduced security flaws without breaking standard code behavior.

Execute the patching and verification stage as follows:

0. Snapshot & Locator Resolution (run once, before touching any code):

   0a. Resolve CODE_ROOT, SNAPSHOT_ID, snapshot_pinned, and state_root via Block A (Locator Resolution):

   LOCATOR RESOLUTION (before reading ANY target code or artifact):
   0. ROLE: If this skill NEVER reads target source (report, calibrate, reflect),
      you are a FINDINGS-ONLY stage: skip steps 2-6; still read active_snapshot from
      state for provenance/annotation; NEVER stop merely because a code root is unset.
   1. Determine CODE_ROOT, in this priority order:
      a. If --target_root is passed on THIS invocation, CODE_ROOT = --target_root.
         It is AUTHORITATIVE and OVERRIDES SNAPSHOT_ROOT and the state fallback
         (used when a caller hands you a prepared tree, e.g. a patched shadow).
      b. Else if --snapshot_root (or SNAPSHOT_ROOT) is passed, use it.
      c. Else read state_root/workspace/.mantis_state.json (state_root from
         --state_root if passed, else ./workspace/... relative to the current dir)
         -> active_snapshot.root / .snapshot_id / .snapshot_pinned.
      d. Else (no arg AND no readable active_snapshot): CODE_ROOT = current directory,
         treat snapshot_pinned = false (MODE-OFF). Do NOT stop.
   2. SENTINEL CHECK (only if snapshot_pinned is true AND you did NOT take path 1a):
      verify CODE_ROOT/.mantis_snapshot_id exists and equals SNAPSHOT_ID. If missing
      or different -> STOP "snapshot sentinel mismatch". (A --target_root tree (1a) is
      deliberately mutated and is sentinel-EXEMPT.)
   3. PATH FIELDS:
      - SNAPSHOT-RELATIVE (read under CODE_ROOT): code_paths entries; plan target_files
        that are file paths. Strip ONLY a trailing ":<digits>". A code_paths entry
        containing "://" is a URL/endpoint, NOT a file read. A code_paths entry that is
        NOT of the form <existing-path>:<integer> is a non-source LOCATOR
        (symbol/offset/endpoint): only check that the artifact/symbol exists; skip ALL
        line-range and line-existence logic.
      - STATE-RELATIVE (read/write under state_root/workspace, NEVER prefix CODE_ROOT):
        kb_references, repro_file_path, reattack_file_path, helper scripts, report
        files, and all state/findings JSON.
   4. Never WRITE under CODE_ROOT when snapshot_pinned is true. Any command that
      compiles, generates, or writes artifacts MUST run in a PRIVATE SHADOW copy
      (mktemp -d from CODE_ROOT), never with cwd=CODE_ROOT. Read-only inspection may
      cd into CODE_ROOT.
   5. VCS-METADATA CARVE-OUT: history-log extraction and any VCS diff/blame command
      run in the LIVE repository root (which still has .git/.hg/.repo), NOT CODE_ROOT
      (the snapshot copy strips VCS metadata). Do NOT stop merely because CODE_ROOT
      lacks .git/.hg/.repo.
   6. Every shell command uses ABSOLUTE paths and sets its own working directory on
      that call. Do NOT assume the working directory persists between calls.
   

   [!NOTE] CURRENT-PASS CHECK (defensive; the binding guarantee is on the harness per Scenario 2): if is present AND , treat the snapshot as STALE for this pass — STOP "stale active_snapshot: pass mismatch" or degrade as HALT ( effectively false: no authoritative verdicts, Block B NOT_MATCHED, reproduce ). This catches a custom harness that preserved across the Stage 15 pass increment without re-pinning. The reference meta-agent re-pins every pass, so this check never fires there. Block B itself cannot detect this (it is -only, not -aware).

When complete, notify the user.