mantis-researcher

name	mantis-researcher
description	Audits production source code files based on the strategy in workspace/plan.json. Use when a review plan exists and you need to perform static analysis and deep-dive reviews of targeted files. Don't use for planning, deduplicating, or writing patches.

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.

2. 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 auditor sub-agents (e.g. up to 4-8 in parallel) to focus exclusively on those identified hotspots. For particularly complex files, spawn multiple subagents targeting the same file using either different prompt constraints or a diverse set of less expensive LLMs to explore parallel attack vectors. Rely on the subsequent deduplication stage to merge any overlapping findings.

   • Instruct the Wave 2 sub-agents to generate unique UUIDs and write their findings directly to individual files on disk. Do not ask them to return the full JSON payload in their messages back to you, as aggregating them will blow out your context window. Ask them to only return the list of UUIDs they created.

Findings Schema Format (Per File)

{
  "id": "A unique identifier generated for this finding (e.g., a UUID or random hash). This must be included and match the filename.",
  "title": "Authorization bypass or Memory bounds violation in [function_name]",
  "description": "Thorough root cause analysis detailing why the function is flawed under untrusted input.",
  "impact": "Exploit outcome (e.g., Privilege escalation, Memory corruption, Data exfiltration).",
  "severity": "CRITICAL / HIGH / MEDIUM / LOW",
  "privileges_required": "NONE / LOW / HIGH",
  "attacker_position": "EXTERNAL / INTERNAL_NETWORK / IN_CLUSTER / LOCAL / HOST_SYSTEM / SUPPLY_CHAIN / PHYSICAL_TEMPORARY / PHYSICAL_LONG_TERM",
  "user_interaction": "NONE / REQUIRED",
  "status": "PROVISIONALLY_VALID",
  "code_paths": ["SNAPSHOT-RELATIVE path under CODE_ROOT, e.g. 'relative/file/path.c:145'. For a NON-SOURCE target (binary/firmware/URL, per Block A step 3) use a STABLE LOCATOR (symbol name, offset, or bare path) WITHOUT a fabricated ':line'. Never invent a line number."],
  "discovery_commit" 
   
   
   
   
   
    
       
       
       
       <current_pass_number>
       
    
  

discovery_commit rule (set once, at creation): This stage is the creation site for discovery_commit. When the snapshot is pinned, every finding you (or your Wave-2 sub-agents) write MUST carry a non-empty discovery_commit equal to active_snapshot.snapshot_id. Downstream stages treat an absent discovery_commit as NOT_MATCHED (the conservative branch), so writing an empty string or a wrong value would silently corrupt matching — never do it. In DEGRADED/legacy mode (no active_snapshot, or snapshot_pinned false) omit the key so behavior matches today's pipeline.

signature/lineage_id rule (set once, at creation): These fields are ALWAYS computed (unlike discovery_commit, which is omitted in degraded mode). The signature is a deterministic hash of the finding's content identity; the lineage_id chains the finding to its archived ancestors. Downstream consumers (dedupe, chain, report, reproduce) key on signature/lineage with UUID fallback: absent signature → today's UUID behavior exactly (no silent wrong result).

Ensure all individual finding files are written to the workspace/findings/ directory. When complete, notify the user.