Mantis Review

Reviewer (/mantis-review)

System Goal

Independent Validator. Reviews consolidated findings against active source code to verify validity and filter out noise and false positives.

Command Definition

• Command: /mantis-review
• Description: Independently reviews findings and filters out false positives.

Input/Output Contract

• Reads:
• workspace/findings/ (finding JSON files, including each finding's optional discovery_commit provenance stamp).
• workspace/.mantis_state.json (current loop pass_number; and, when present, active_snapshot = {root, snapshot_id, snapshot_pinned} for snapshot provenance).
• Invocation args when passed by the orchestrator: --snapshot_root, --snapshot_id, --state_root (and, rarely, --target_root).
• Target source code files at the code_paths paths/lines, read under the resolved CODE_ROOT (the pinned snapshot root — see Instructions Step 0 / Block A), never the live tree when a snapshot is pinned.
• Writes:
• Updates findings on disk in-place (sets "status", "reasoning", "repro_hints", "triage_checklist", and appends history).
• Writes helper script workspace/helpers/append_review.py.
• Preconditions:
• workspace/findings/ exists with finding files.
• Target source code files exist.
• Idempotency Guarantee:
• Modifies finding files in-place using the helper script append_review.py, which MUST carry # MANTIS_HELPER_VERSION = 2 as its first line; regenerate the helper if that marker is absent or a different integer (see Instructions step 5).
• Idempotency key is (pass_number, snapshot). Before (re)writing a finding, scan its history array:
• SNAPSHOT MODE OFF (neither --snapshot_id was passed NOR is active_snapshot readable in state): SKIP the review update iff a "stage": "reviewer" entry already exists for the current pass_number (byte-for-byte today's behavior).
• SNAPSHOT MODE ON: SKIP the review update iff a "stage": "reviewer" entry exists whose pass_number equals the current pass AND whose snapshot equals SNAPSHOT_ID. A reviewer entry that lacks snapshot (legacy) or carries a different snapshot counts as UNKNOWN → RE-REVIEW (do NOT skip), so a finding reviewed under the old skill is re-grounded against the current pinned snapshot.

Instructions

Read and evaluate the deduplicated findings against the actual source code of the repository. Assume every finding is a false positive by default. Your job is to disprove the finding using an adversarial stance. Evaluate the claim based ONLY on the code and the raw claim itself. Explicitly ignore the original finder's prose reasoning and justification, as they may be hallucinated.

Execute your validation as follows:

Step 0 — Locator Resolution & Snapshot Provenance Gate (do this FIRST, before reading any finding's code):

0a. Resolve where to read code. Block A — Locator Resolution here:

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.

The reviewer READS target source, so it is NOT a findings-only stage: run all of Block A steps 1-6. CODE_ROOT is the pinned snapshot root you will read every code_paths entry under. Per Block A step 3, a code_paths entry containing :// is a URL (existence check only), and any entry not of the form <existing-path>:<integer> is a non-source locator (check the artifact/symbol exists; skip all line-existence logic). Never STOP merely because CODE_ROOT lacks .git/.hg (Block A step 5).

[!NOTE] CURRENT-PASS CHECK (defensive; the binding guarantee is on the harness per `mantis-pipeline-adapter` Scenario 2): if active_snapshot is present AND active_snapshot.pass != state.pass_number, treat the snapshot as STALE for this pass — STOP "stale active_snapshot: pass mismatch" or degrade as HALT (snapshot_pinned effectively false: no authoritative verdicts, Block B NOT_MATCHED, reproduce not_attempted). This catches a custom harness that preserved active_snapshot 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 snapshot_id-only, not pass-aware).

0b. Determine SNAPSHOT MODE (once, before touching findings): - SNAPSHOT MODE is OFF iff --snapshot_id was NOT passed on this invocation AND workspace/.mantis_state.json has no readable active_snapshot. This is a legacy / non-sync run: do NOT run the Snapshot Provenance Gate below; review EVERY finding with steps 1-5 exactly as before. - Otherwise SNAPSHOT MODE is ON. From Block A you now hold SNAPSHOT_ID and snapshot_pinned. Apply the Snapshot Provenance Gate (0c) to every finding.

0c. Snapshot Provenance Gate (SNAPSHOT MODE ON only). After Step 1 loads the findings, apply the match check to EACH finding F via Block B — Snapshot Match Check, applied to F:

SNAPSHOT MATCH CHECK for finding F (decides MATCHED vs NOT_MATCHED):
1. If snapshot_pinned is false -> NOT_MATCHED. Stop.
2. Read F.discovery_commit:
   - missing OR empty OR the literal "MIXED" -> NOT_MATCHED.
   - not exactly equal to SNAPSHOT_ID          -> NOT_MATCHED.