mantis-plan

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)

[!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.

     • Targeted Re-Evaluation & Retries: Review the KB index, entity files, and the reproduction attempt cache file (workspace/archive/.repro_attempts.json if it exists). You must identify findings that need re-evaluation or retries:

       Also read the snapshot context from workspace/.mantis_state.json: active_snapshot.{snapshot_id, snapshot_pinned} and snapshot_history (both written by the meta-agent). Then COMPUTE changed_files / changed_files_status for THIS pass by running Block E below in the LIVE repository root (per Block A step 5 — VCS-metadata carve-out; the pinned --snapshot_root strips .git/.hg/.repo, so the diff MUST run against the live tree). Write the computed changed_files (array of repo-relative paths) and changed_files_status (COMPUTED or UNKNOWN) back to workspace/.mantis_state.json, then use them for the rest of the stage. Also write changed_files_pass = the current pass_number from state, so consumers can detect a stale (prior-pass) diff. Use the following to know which files changed since the previous pass:

       CHANGED-SINCE-PREVIOUS: run in the LIVE repository root (NOT SNAPSHOT_ROOT). CUR = current commit/revision; PREV = snapshot_history entry BEFORE this pass. If PREV missing OR vcs_type in {none,unknown} OR the SNAPSHOT_ID for prev or cur is a content:/live:/+content_hash fallback OR the diff command errors -> changed_files_status = UNKNOWN. Treat EVERY file as CHANGED. NEVER treat as unchanged. NEVER drop. (Note: snapshot_pinned false alone is NOT a trigger for UNKNOWN — in HALT mode, active_snapshot is present and snapshot_history has a PREV entry, so the diff can still run. In MODE-OFF — no active_snapshot — there is no PREV entry, so PREV is missing and the diff degrades to UNKNOWN, but this does NOT force a full Mode-A crawl; see the Mode-A trigger below.) Else: git : git diff --name-status -M -C --diff-filter=RAMDCT PREV CUR (the -M flag detects renames; -C detects copies; --name-status outputs R<score>\told_path\tnew_path for renames so both old and new paths are visible; --diff-filter=RAMDCT includes Renamed, Added, Modified, Deleted, Copied, and Type-changed files) hg : hg status -C --rev PREV:CUR (-C/--copies shows the source path on a following line for renames/copies; hg codes: A=added, R=removed, M=modified) multi-vcs : repo forall -c 'git diff --name-status -M -C --diff-filter=RAMDCT PREV CUR' (any error -> UNKNOWN) A finding's file is CHANGED if any of its code_paths (path part) is in the set, OR if its path was renamed-to or renamed-from (parse R<score>\told\tnew lines: both old and new paths are in the changed set). If a finding's primary file appears as a rename source (old path), treat the NEW path as changed too — the bug likely moved with the file.

       Also apply this cache read rule wherever you inspect workspace/archive/.repro_attempts.json. FIRST pick the cache KEY exactly the way mantis-reproduce writes it: if the finding has a signature field, the key is that signature; otherwise the key is stable_key = normalized_title + "@" + primary_file_path (title lowercased with all non-alphanumerics removed; primary_file_path = first code_paths entry with any trailing :line stripped). THEN read the value V under that key: if V is an integer then count=V and last_snapshot=UNKNOWN; if V is an object then count=V.count and last_snapshot=V.last_snapshot (default UNKNOWN). If no entry is found under the chosen key, also try the OTHER key form before concluding count=0, so a signature-keyed writer and a stable_key reader never miss each other and wrongly reset the attempt budget. (The cache mixes both value forms AND both key styles during migration.)

       1. Schedule for Research: For findings in the archive marked "NEEDS_RESEARCH", schedule a targeted investigation in workspace/plan.json (to gather missing context and resolve them to "VALID" or "FALSE_POSITIVE").

       2. Copy for Retry (snapshot-gated) or Re-discover: For each archived finding that would otherwise be retry-eligible (repro not attempted, or failed_to_reproduce with fewer than 2 attempts per the cache read rule above, or patch_status in {VERIFICATION_FAILED,ERROR,VERIFICATION_INCOMPLETE}), run:

          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.
             - exactly equal to SNAPSHOT_ID              -> MATCHED.
          There is no other route to MATCHED; never fuzzy-compare. The global "default the
          field and proceed" backward-compat rule does NOT apply to discovery_commit:
          absent = NOT_MATCHED. (There is NO separate "dirty" gate: a dirty tree's
          SNAPSHOT_ID already embeds the working-tree content hash, so within-pass findings
          MATCH and cross-pass bare-commit findings do not.)

          Then decide mechanically:

          • COPY VERBATIM (fast retry) ONLY if ALL hold: Block B is MATCHED for the finding, AND its primary file (first code_paths, line stripped) is NOT in changed_files, AND that file EXISTS under CODE_ROOT. Copy the archived <uuid>.json back to workspace/findings/<uuid>.json preserving the UUID and its ORIGINAL discovery_commit (do not re-stamp it — drift must stay detectable).

          • MODE-OFF bypass (3-state rule): if active_snapshot is ABSENT in state (MODE-OFF — no --sync was requested), Block B always returns NOT_MATCHED (snapshot_pinned is false -> NOT_MATCHED), so the COPY-VERBATIM gate above never fires and every retry- eligible finding is RE-DISCOVERed — a regression from today's behavior (today, pass ≥2 carries forward unchanged findings when the file still exists). In MODE-OFF, COPY-VERBATIM when the finding's primary file (first code_paths, line stripped) EXISTS under CODE_ROOT (drop the Block B MATCHED and file NOT in changed_files conjuncts — there is no changed_files diff in MODE-OFF anyway). This mirrors mantis-patch's LEGACY-mode carve- out (patch:133-138, patch:172-174). Do NOT gate the bypass on snapshot_pinned==false — that would also catch HALT mode, where the STALE banner legitimately marks the finding as needing re-verification. Gate ONLY on active_snapshot absent. (Do NOT change Block B itself — it is character-identical across skills per README_AGENTS.md:711-718 block-fidelity warning; the fix goes in plan's CONSUMERS of Block B, not Block B.)

          • RE-DISCOVER in every other case (Block B NOT_MATCHED, or file in changed_files, or file missing, or changed_files_status==UNKNOWN): do NOT copy back. Instead append a fresh investigation to workspace/plan.json that embeds the finding's title, description, and repro_hints, sets target_files to the old code_paths' directory subtree(s) PLUS a repository-wide symbol/keyword search for the finding's function/struct/title terms (so a moved/renamed bug is re-found), and asks the researcher to re-derive the exact lines on the CURRENT snapshot. Additionally, record a history note unconfirmed-regression-pending on the archived finding so it is never silently dropped until a pass re-discovers it or a human dismisses it.

          • Line/AST Re-anchoring (Phase 2 incremental efficiency): Before falling back to full RE-DISCOVER, attempt to re-anchor the finding's line numbers to the CURRENT snapshot using forward line-tracking (reverse blame or diff-hunk offset). This is an optimization: if the finding's primary function/symbol still exists nearby, re-anchoring produces a line-number HINT that focuses the RE-DISCOVER investigation — it does NOT replace re-verification (the snapshot changed, so the finding is still re-researched downstream).

            • How: Translate the finding's old line FORWARD from PREV to CUR (do NOT blame PREV in isolation — that returns the line as of PREV and does not map it forward). Run in the LIVE repo root (Block A step 5 carve-out): git : git blame --reverse <PREV>..<CUR> -L <old_line>,<old_line> -- <file> (reverse blame follows the line forward to CUR), or add the hunk offset from git diff <PREV> <CUR> -- <file> to <old_line>. Then read the mapped line in CODE_ROOT (the current pinned snapshot) and confirm the finding's primary function/symbol is present within ±50 lines. This yields a CANDIDATE new line number only — a search hint for RE-DISCOVER, never a trusted re-validation.
            • When re-anchoring SUCCEEDS (symbol found at the mapped line): use the new line number to FOCUS this finding's RE-DISCOVER investigation (point the researcher at the mapped code_paths location first). Do NOT convert the finding to COPY-VERBATIM and do NOT skip re-verification: Block B is NOT_MATCHED, so the finding is still re-researched/re-reproduced downstream (a symbol can exist at the mapped line yet already be FIXED). Keep discovery_commit, signature, and lineage_id unchanged; add a history note re-anchored: <old_line> -> <new_line> (search hint).
            • When re-anchoring FAILS (function deleted, symbol not found, diff too large, blame errors, or the code at the old line is completely different): fall back to full RE-DISCOVER as above. This is the conservative guardrail: on ANY uncertainty, re-discover.
            • Never use re-anchoring to suppress or drop a finding. It is purely a fast-path for line-number updates; if it fails, the finding is still re-discovered via the normal path.
            • VCS-agnostic: For hg, diff PREV:CUR (hg diff --rev PREV:CUR -- <file>) and apply the hunk offset to <old_line> to get the forward-mapped line. For no-VCS/binary targets, re-anchoring is not applicable; always fall back to RE-DISCOVER.

          • NEVER copy back a finding whose "status" is "FALSE_POSITIVE", or "patch_status" is "VERIFIED_SECURE", or "repro_status" is "reproduced" (unless patch failed as above), or that has reached the 2-attempt cap for the CURRENT snapshot. But if such a finding's file IS in changed_files or Block B is NOT_MATCHED, treat it as a possible regression: RE-DISCOVER it (do not trust the old terminal verdict against changed code). MODE-OFF carve-out: if active_snapshot is ABSENT (MODE-OFF), drop the or Block B is NOT_MATCHED disjunct above — in MODE-OFF, Block B is NOT_MATCHED for every finding (artifact of no snapshot, not a signal of drift), so leaving the disjunct in would re-open every terminal verdict (FALSE_POSITIVE/VERIFIED_SECURE/reproduced) every pass. In MODE-OFF, rely ONLY on file IS in changed_files (which is vacuously false in MODE-OFF — there is no changed_files diff), so terminal findings are carried forward unchanged. This is today's behavior.

     • Changed / new attack-surface coverage (MANDATORY): Add an investigation titled Exhaustive Review: <path> for EVERY path in changed_files (whether or not it maps to an archived finding). If changed_files_status==UNKNOWN AND active_snapshot is present (HALT or PINNED mode — a sync was requested this pass), OR a sync occurred this pass (snapshot_id != the previous snapshot_history entry's id), you CANNOT trust a narrow set: fall back to a full Mode A exhaustive crawl for this pass EVEN IF kb/index.md exists (this is the only way to catch newly added files). However, in MODE-OFF (no active_snapshot — no --sync), do NOT force a full Mode-A crawl in pass ≥2 even if changed_files_status==UNKNOWN: this is today's default behavior, and forcing Mode-A on every MODE-OFF pass ≥2 would be a regression. In MODE-OFF, rely on the existing kb/index.md (Mode B) for narrowing, as today.

     • Dependency-aware fan-out (Phase 2 incremental efficiency): When changed_files_status is known (not UNKNOWN) and a dependency graph is available, EXPAND the investigation scope beyond just the changed files themselves. The goal: identify files that IMPORT or DEPEND ON the changed files, so the planner can schedule targeted investigations for consumers of the changed code (not just the changed code itself).

       • How: Start with the file-level dependency graph (workspace/kb/dependencies.json or entity-relationship markdown) as the mandatory floor: for each changed file F, find all files that import F (directly or transitively up to 2 hops). Add these dependent files to the investigation scope as Exhaustive Review: <dependent_file> entries. Then ADD structural index callers on top: use the query helper (workspace/helpers/query_structural_index.py) for function-level precision when available — call resolve_symbol() for a changed file's exported functions, then find_callers() to enumerate dependents at the symbol level. Schedule investigations for the UNION of dependency-graph-found dependents and structural-index-found callers — they are complementary, not alternatives. If the structural index is absent (no manifest.json), empty, or the query helper is missing, the dependency graph alone remains the floor.
       • When to use: ONLY when changed_files_status is known AND the KB contains dependency information. If the KB lacks an import/build graph, or the KB is stale (check kb_snapshot_id in workspace/.mantis_state.json against SNAPSHOT_ID — if they differ, the KB was built against a different snapshot and may be stale), fall back to the Phase-1 behavior (full Mode-A crawl or Mode-B narrowing).
       • Guardrail: If the dependency graph is incomplete, stale, or any uncertainty arises, fall back to Phase-1 re-discovery (treat ALL files as potentially affected). Never use dependency narrowing to DROP an investigation — it can only ADD targeted investigations for dependent files. The changed files themselves are ALWAYS investigated regardless.
       • VCS-agnostic: The dependency graph is derived from the KB's architecture analysis, not from VCS metadata. It works for any language with import/include/use statements that the KB has indexed.

     • Structural Index Queries (HINT-only enhancement): When a structural index is available (workspace/kb/structural_index/manifest.json exists), use it to SUPPLEMENT the dependency-aware fan-out above with precise, symbol-level caller discovery. The structural index decides ORDER of investigation priority, NEVER MEMBERSHIP of the audit set.

       • Resolution-first protocol (MANDATORY): Before querying callers, resolve the symbol:

         python3 workspace/helpers/query_structural_index.py resolve_symbol --name "<function_name>" [--language "<lang>"] [--file "<path>"] --state_root <state_root>

         If the response has ambiguous: true, do NOT silently pick one match. Narrow with --file/--language, or schedule investigations for ALL matched symbols.

       • Bounded caller queries: Once resolved, query callers with explicit bounds:

         python3 workspace/helpers/query_structural_index.py find_callers --symbol_id "<resolved_id>" --limit 100 --offset 0 --state_root <state_root>

         Paginate with --offset if has_more is true.

       • Coverage-aware interpretation: Check coverage.partition_status in every structural index response:

         • complete + precision == semantic + no callers = "no indexed callers" — the partition is fully indexed with a semantic backend, so the empty result is authoritative for indexed code. Still run grep per the HINT-only rule (grep catches macro-based calls, function pointers, and dynamic dispatch).
         • complete + precision != semantic + no callers = "no indexed callers" — the partition is complete but precision is below semantic, so the empty result is NOT authoritative. MUST run exhaustive grep fallback.
         • partial / empty / failed + no callers = "not fully indexed" — the partition is not complete, so expand the investigation scope and MUST run exhaustive grep fallback.

       • Guardrails:

         • HINT-only: structural index results decide ORDER, never MEMBERSHIP. They prioritize which dependent files to investigate first; they MUST NEVER cause a file to be dropped from the audit scope.
         • Every result carries precision and backend fields — use precision (semantic > typecheck > ast > symbol-only > heuristic > deferred > coverage-only) to weight trust in the result.
         • If the structural index is absent (no manifest.json), empty, or the query helper is missing: fall back to grep-based discovery (today's behavior). The structural index is a coverage HINT only.

     • Context Injection (kb_references): For each investigation you plan, you must determine which files in the workspace/kb/ directory (e.g., workspace/kb/entities/auth_module.md or workspace/kb/vulnerabilities/CWE-79.md) provide necessary context for the researcher. Include the exact file paths to these markdown files in the "kb_references" array for that investigation. This shifts the burden of context-gathering off the researcher.

     • Exploratory/Unconstrained Investigations (Moderate Probability): With a moderate probability (e.g., a 25-50% chance per planning pass), include either an unconstrained adversarial sweep or a random exploration in the plan:

       1. Adversarial Sweep: Select a component or directory that the threat model currently marks as safe, low-risk, or out of scope. Instruct the researcher to perform an unconstrained sweep, ignoring safety assumptions in workspace/kb/THREAT_MODEL.md.

       2. Random Digging: Select a random starting position (file or directory) in the codebase. The question for this investigation should be minimal and open-ended, simply instructing the researcher to "dig into" or "explore" the selected area without specific threat-model context or pre-defined vulnerability classes. Set kb_references to an empty list for this investigation to ensure a fresh look.

       Token Optimization: Whether using a script (Mode A) or your file-writing tools (Mode B), write the plan directly to disk and do not print the JSON contents in your chat response.

3. Schema Enforcement: Regardless of the mode, the final workspace/plan.json file written to disk should match the following schema to ensure downstream auditing agents can parse it correctly:

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.