Mantis Critic

Critic (/mantis-critic)

System Goal

Production Viability Expert. Filters validated security findings to confirm if they remain triggerable in standard release and production configurations.

Command Definition

• Command: /mantis-critic [--target_root=<path>] [--snapshot_root=<path>] [--snapshot_id=<id>] [--state_root=<path>]
• Description: Assesses the production viability of findings, filtering out debug-only features and assertion traps.
• Parameters:
• --target_root: AUTHORITATIVE path to the target codebase root. Overrides all other locator sources and is sentinel-exempt (Block A path 1a). Defaults to unset.
• --snapshot_root: Path to the pinned, immutable snapshot copy for this pass (a.k.a. SNAPSHOT_ROOT). Used as CODE_ROOT when --target_root is unset (Block A path 1b).
• --snapshot_id: The SNAPSHOT_ID the orchestrator computed for this pass. Used for the Block A sentinel check and for the per-finding Block B drift comparison in Step 3. If omitted, fall back to active_snapshot.snapshot_id from state.
• --state_root: Path to the root of the Mantis state directory containing workspace/ (defaults to .). Every workspace/... path in this file is resolved relative to --state_root; with the default . this is identical to today's workspace/.

Input/Output Contract

• Reads:
• workspace/findings/ (loads all findings regardless of status; also reads each finding's optional discovery_commit for the per-finding snapshot match check).
• workspace/kb/THREAT_MODEL.md (if exists, to check deployment intent and the KB's recorded kb_snapshot_id).
• workspace/.mantis_state.json (to track current loop pass and to read active_snapshot.{root,snapshot_id,snapshot_pinned} for locator resolution and provenance).
• Target source code files under the resolved CODE_ROOT (the pinned snapshot root when snapshot_pinned), at paths/lines in code_paths with contextual offset.
• Writes:
• Updates findings in-place (sets "production_viability", "critic_reasoning", and appends history).
• Appends to workspace/learnings.jsonl.
• Preconditions:
• Findings must exist in workspace/findings/.
• Idempotency Guarantee:
• Overwrites viability fields in place. It must check if a critic entry for the current pass is already recorded in the history array, and check workspace/learnings.jsonl to ensure it does not write duplicate records if run again on the same input.

Instructions

Evaluate validated findings to determine if they represent actionable security flaws in a compiled, optimized release build. Adopt a highly skeptical, adversarial stance. Do not trust the reasoning of previous stages. Re-verify the code path independently to definitively prove or disprove production viability.

Locator Resolution (do this first)

Critic is a CODE-READING stage (it inspects the target source), so it is NOT a findings-only stage: run all of Block A. Resolve CODE_ROOT and the sentinel per Block A before loading findings.

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

SNAPSHOT_ID for this stage: let SNAPSHOT_ID be the value of --snapshot_id if provided, else active_snapshot.snapshot_id from workspace/.mantis_state.json. If neither is present (no --snapshot_id AND no active_snapshot in state), OR Block A resolved CODE_ROOT via path 1d (no args, current dir), then SNAPSHOT_ID is UNAVAILABLE (MODE-OFF = today's default): treat every Block B check in Step 3 as NOT_MATCHED and treat the KB freshness gate in Step 2 as FAILED. Do NOT stop; degrade as described below. When active_snapshot IS present but snapshot_pinned is false (HALT mode), SNAPSHOT_ID is the recorded live: id and IS available — Block B still returns NOT_MATCHED (snapshot_pinned is false), but the Step-3c "MODE-OFF exception" below does NOT fire: a NOT_MATCHED result is treated as drift → CONDITIONAL_VIABLE, never NON_VIABLE (which calibrate drops).

Execute the critic evaluation as follows:

1. Load Findings: Read the JSON files in the workspace/findings/ directory. You must load all findings regardless of status (including "VALID", "FALSE_POSITIVE", "PROVISIONALLY_VALID", and "NEEDS_RESEARCH") so they can be processed or logged to long-term memory. If none exist, notify the user.

1. Evaluate Global Repository Intent (KB-freshness gated): Read workspace/kb/THREAT_MODEL.md (if it exists). Check the Deployment Intent section.