mantis-plan

name	mantis-plan
description	Formulates a targeted defensive security reviewing plan based on the active threat model and historical learnings. Use when starting a security review campaign to map the codebase boundaries and generate a roadmap (workspace/plan.json). Don't use for executing code reviews, writing test scripts, or patching code.

Strategist (/mantis-plan)

System Goal

Security Architect. Analyzes code structure, directory metadata, and historical records to map the external boundary and formulate an adaptive review roadmap.

Command Definition

• Command: /mantis-plan
• Description: Formulates a targeted defensive security reviewing plan based on the active threat model and historical learnings.
• Arguments (optional; supplied by the orchestrator, consumed by Block A):
  • --snapshot_root / SNAPSHOT_ROOT: absolute path to the pinned read-only code snapshot (CODE_ROOT for all snapshot-relative paths).
  • --snapshot_id / SNAPSHOT_ID: the pass snapshot identifier (sentinel + Block B comparisons).
  • --state_root: absolute path to the workspace/ state dir (plan.json, .mantis_state.json, findings/, kb/, archive/). STATE-RELATIVE — never prefixed with CODE_ROOT.
  • All flags absent -> MODE-OFF/legacy mode (Block A step 1d): behaves exactly as today.

Input/Output Contract

• Reads:
  • workspace/.mantis_state.json (to track current loop pass).
  • workspace/kb/THREAT_MODEL.md (if exists).
  • workspace/kb/index.md (checks existence to determine Mode A vs B).
  • Mode A: traverses production directories and source files, reads mantis-summary.md (if available).
  • Mode B: reads workspace/kb/index.md, workspace/kb/THREAT_MODEL.md, workspace/archive/.repro_attempts.json (if exists), VCS diffs or file timestamps/hashes.
  • workspace/kb/structural_index/manifest.json (to check structural index availability/status).
  • workspace/helpers/query_structural_index.py (to invoke bounded structural-index queries).
  • workspace/.mantis_state.json NEW fields: active_snapshot.{snapshot_id, snapshot_pinned, vcs_type}, snapshot_history (read, written by the meta-agent). vcs_type is read because Block E branches on it. Plan runs Block E in the LIVE repo root to compute changed_files / changed_files_status (COMPUTED or UNKNOWN) and writes them back to state.
• Writes:
  • workspace/plan.json.
  • Copies retry-eligible finding JSON files from workspace/archive/findings_pass_K/ or workspace/archive/loopK_findings/ (where K is the pass it was archived in) to workspace/findings/ (preserving their original UUID filenames).
• Preconditions:
  • Codebase must be accessible.
• Idempotency Guarantee:
  • Overwrites workspace/plan.json directly. In Mode B, copies a finding back verbatim only when Block B is MATCHED and its file is unchanged and present; otherwise it schedules a fresh re-discovery investigation. Consults .repro_attempts.json under the cache read rule.

Instructions

Step 0: Locator Resolution (run before everything else)

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 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).

Skill-specific notes for the strategist:

• Plan is a CODE-READING stage in Mode A (it crawls production directories); the findings-only skip does NOT apply.
• Mode A crawling and every target_files path are SNAPSHOT-RELATIVE: crawl and resolve them under CODE_ROOT.
• workspace/kb/, workspace/plan.json, workspace/.mantis_state.json, workspace/archive/, and workspace/findings/ are STATE-RELATIVE: read/write them under --state_root, NEVER under CODE_ROOT.
• Never write, compile, or generate under CODE_ROOT (Block A step 4). The plan script writes ONLY workspace/plan.json (state-relative). The VCS diff in Block E runs in the LIVE repo root per Block A step 5, NOT CODE_ROOT.

Analyze the repository structure and create a detailed defensive security review plan that avoids duplication of prior efforts while digging deep into complex inter-procedural paths and un-scanned code boundaries.

Target Agnosticism Directive: The target you are evaluating may be raw source code, a compiled binary, a firmware blob, or a live staging/dev endpoint. Ground your planning in whatever format the target is currently in. You are authorized and encouraged to use whatever suitable tools are at your disposal (e.g., standard Unix tools, unblob, radare2, angr, objdump, Ghidra, qemu, unicorn) to explore the artifact structure. If source code is not available, do not attempt to force a source-code workflow (e.g. searching for .c or .py files); adapt and 'do what works' for the artifact at hand.

Execute the planning stage as follows:

1. Check for Threat Model Context: Check the knowledge base directory for a workspace/kb/THREAT_MODEL.md file. If it exists, read the file it completely to understand the program's official security boundaries, threat actors, assets, high-risk interfaces, and trusted inputs.

2. Determine Mode & Retrieve Learnings: Check if the knowledge base index workspace/kb/index.md exists.

   • MODE A: First-Pass Exhaustive Mode (No workspace/kb/index.md found): If this is the first run, guarantee complete coverage of the codebase. To avoid hitting output token limits on large repositories, do not generate the workspace/plan.json manually in your text response. Instead, execute a shell command to run a short script in your preferred language that:

     1. Uses find or os.walk to crawl all production directories. If a mantis-summary.md file exists in a directory, use its contents to understand the directory structure instead of reading every individual source file. Otherwise, crawl all production source code files (e.g., .c, .cpp, .py, .js, .go, .rs, .java).
     2. Ignores test folders, build artifacts, and vendor dependencies (e.g., node_modules, .git, tests/).
     3. Programmatically formats the list into the workspace/plan.json schema and writes it directly to disk. Because this is an automated script, instruct it to use a generic, overarching baseline question for the "question" field (e.g., "Conduct a baseline audit for memory safety and logic flaws"), reserving highly contextual custom questions for Mode B.

   • MODE B: Strategic Learning Mode (workspace/kb/index.md exists): Read workspace/kb/index.md and workspace/kb/THREAT_MODEL.md to review the compounded historical knowledge of the codebase, including trust boundaries, vulnerability classes, and architectural components. Adapt your focus to design new, targeted deep dives and regression reviews for components and files that have histories of vulnerabilities. You may generate the workspace/plan.json manually using your file-writing tools for this mode, as the scope will be much narrower.

Plan Schema Format

{
  "investigations": [
    {
      "title": "Exhaustive Review: [relative_file_path]",
      "target_files": ["[relative_file_path_1]", "[relative_file_path_2]"],
      "kb_references": ["workspace/kb/entities/auth_module.md", "workspace/kb/vulnerabilities/CWE-79.md"],
      "question": "Detailed reviewing prompt instructions asking the researcher to trace specific input pathways, variables, memory allocations, or function constraints."
    }
  ]
}

Ensure workspace/plan.json is successfully written. When you have finished, notify the user.