Mantis Researcher

Mantis Researcher (/mantis-researcher)

System Goal

Resilience Code Auditor. Performs rapid triage and deep-dive reviews of source files to identify boundary checks, preconditions, missing sanitization, and interface violations.

Command Definition

• Command: /mantis-researcher
• Description: Audits production source code files based on the strategy in workspace/plan.json.
• Arguments (optional; supplied by the orchestrator, consumed by Block A):
• --snapshot_root / SNAPSHOT_ROOT: absolute path to the pinned, read-only code snapshot for this pass. This is the CODE_ROOT that all snapshot-relative path fields resolve against (Block A step 1b).
• --snapshot_id / SNAPSHOT_ID: the pass snapshot identifier. Used for the sentinel check (Block A step 2) and stamped verbatim into every finding's discovery_commit.
• --state_root: absolute path to the workspace/ state directory (plan.json, .mantis_state.json, findings/, kb/). State paths are STATE-RELATIVE and are NEVER prefixed with CODE_ROOT (Block A step 3).
• --target_root (authoritative override, Block A step 1a) is also honored if supplied.
• All flags absent -> DEGRADED/legacy mode: CODE_ROOT falls back to the current directory, snapshot_pinned is treated as false, and behavior matches today's exactly (no discovery_commit is written).

Input/Output Contract

• Reads:
• workspace/plan.json (falls back to codebase sweep if missing/empty).
• workspace/.mantis_state.json (to track current loop pass).
• referenced Markdown files in "kb_references" (e.g. workspace/kb/entities/*.md).
• Target source code files.
• workspace/kb/structural_index/manifest.json (to check structural index availability/status).
• workspace/helpers/query_structural_index.py (to invoke bounded structural-index queries).
• Writes:
• Raw finding files to workspace/findings/<uuid>.json (creates workspace/findings/ if missing).
• Preconditions:
• Target files must be accessible.
• Idempotency Guarantee:
• Writes new findings as separate files with unique UUIDs. Rely on mantis-dedupe to cluster and merge duplicate findings on subsequent steps.

Instructions

Step 0: Locator Resolution (Snapshot-Aware Path Handling)

Run this BEFORE the numbered research steps below. It fixes the single CODE_ROOT that every target_files / code_paths reference in this stage resolves against, so all sub-agents audit the same pinned snapshot.

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.

Skill-specific notes for the researcher:

• The researcher is a CODE-READING stage, so Block A step 0's findings-only skip does NOT apply here — you MUST resolve CODE_ROOT and honor the sentinel.
• workspace/plan.json target_files and finding code_paths are SNAPSHOT-RELATIVE: resolve them under CODE_ROOT (Block A step 3).
• kb_references, workspace/plan.json, workspace/.mantis_state.json, and everything under workspace/findings/ are STATE-RELATIVE: read/write them under --state_root, NEVER under CODE_ROOT.
• Never write, compile, or generate anything under CODE_ROOT when pinned (Block A step 4).

Perform a thorough memory-safety, logical-correctness, and robustness review of the targeted codebase.

Execute the research stage as follows:

1. Load Reviewing Plan & Context: Read the active pass number from workspace/.mantis_state.json and resolve the current ISO 8601 timestamp. Read the workspace/plan.json file to retrieve the target investigations. If workspace/plan.json is missing or empty, perform a general list of the directories and review any primary source files. If the investigation contains a "kb_references" array, explicitly read those Markdown files (e.g., workspace/kb/entities/auth.md) to gain compounded historical context before you begin auditing the "target_files". Also read active_snapshot from workspace/.mantis_state.json (root, snapshot_id, snapshot_pinned). Hold active_snapshot.snapshot_id in memory: it is the value you will stamp into every finding's discovery_commit (see Findings Schema Format). If active_snapshot is absent or snapshot_pinned is false, you are in DEGRADED/legacy mode — do NOT stop (Block A step 1d); you will simply omit discovery_commit.

1. Sub-Agent Delegation (Wave-Based Swarm Parallelization): If the CLI or agent platform supports spawning sub-agents (e.g., using specialized sub-agent tools or multi-agent orchestrator directives):

• Do not execute investigations sequentially if sub-agents are supported. Split the investigations in workspace/plan.json into parallel waves to maximize throughput and context efficiency.

• Wave 1: Lightweight Rapid Triage (Concurrency Peak): Spawn concurrent, lightweight sub-agents (e.g. up to 10-20 in parallel) to sweep all files listed in workspace/plan.json. Each sub-agent should only output a fast classification: {"potentially_flawed": true/false, "reason": "..."}.

• Wave 2: Deep Security Flaw Hotspot Audits & Parallel Trajectory Search: Collect all files flagged in Wave 1. Spawn a wave of concurrent deep