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:
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.
Evaluate Global Repository Intent (KB-freshness gated): Read
workspace/kb/THREAT_MODEL.md (if it exists). Check the Deployment
Intent section.
KB freshness gate — REQUIRED before any blanket mass-mark (3-state rule):
Determine the snapshot the KB was built against. Read it from ONE of these
sources (try in order, first match wins):
- The literal
KB_SNAPSHOT: token on the FIRST line of
workspace/kb/THREAT_MODEL.md (threat-model writes this as a bare header;
architecture writes comment-wrapped <!-- KB_SNAPSHOT: ... --> on each KB
file). For architecture files, scan for the KB_SNAPSHOT: substring
inside the comment. Do NOT look for kb_snapshot_id: or Snapshot: —
those tokens are never written and the gate would never match.
- Else the
kb_snapshot_id value in workspace/.mantis_state.json (which
architecture writes in its state-stamp step).
- Else
"" (no prior KB provenance). The blanket mass-mark below is gated
as follows:
- MODE-OFF (no
active_snapshot in state — no --sync): SKIP the
freshness gate entirely. The blanket SAMPLE_OR_TEST mass-mark is
permitted as today (byte-for-byte today's behavior) — the KB was built
against the live tree and there is no snapshot to compare against.
- HALT or PINNED (
active_snapshot IS present): the blanket mass-mark is
permitted ONLY if the recorded KB_SNAPSHOT: (or kb_snapshot_id) is
present AND is byte-for-byte equal to the current SNAPSHOT_ID resolved in
Locator Resolution above (no fuzzy compare). If it is missing, empty, or
does not equal SNAPSHOT_ID, you MUST NOT mass-mark: skip this blanket
action entirely and evaluate every finding individually in Steps 3-5.
Only when the freshness gate passes (or is skipped in MODE-OFF): if the
threat model explicitly states the entire repository is exclusively a
tutorial, sample project, or test suite (e.g.,
Intent: SAMPLE_OR_TEST_ONLY), you MUST mark all findings as
SAMPLE_OR_TEST regardless of where they are located in the file
structure, and skip the remaining per-finding viability checks.
Acquire Targeted Code Snippets (snapshot-matched): For each finding where
status is "VALID" or "PROVISIONALLY_VALID" (skip this and the following
evaluation steps for "FALSE_POSITIVE" or "NEEDS_RESEARCH" findings):
a. Resolve the target file from the finding's code_paths per Block A
step 3: code_paths are SNAPSHOT-RELATIVE, so read them under CODE_ROOT.
Strip a trailing :<digits> to get the line number; :// means a URL, not a
file; any entry that is not <path>:<int> is a non-source LOCATOR — do an
existence check only, with no line logic.
b. Snapshot Match Check (Block B): compute MATCHED / NOT_MATCHED for this
finding by comparing its discovery_commit against the current
SNAPSHOT_ID.
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.)
c. Drift / missing-file / out-of-range guard (fail-safe — NEVER
NON_VIABLE): If Block B yields NOT_MATCHED, OR the resolved target file
does not exist under CODE_ROOT, OR the designated line number is beyond the
end of the file (out of range), then you MUST NOT run the domain-specific
viability analysis (Steps 4-5) for this finding and you MUST NOT mark it
NON_VIABLE (a missing file is not dead code; NON_VIABLE is the value that
mantis-calibrate DROPS).
Exception (MODE-OFF only — no active_snapshot): if SNAPSHOT_ID is
UNAVAILABLE (MODE-OFF: no active_snapshot in state and no --snapshot_id)
AND the sole cause of NOT_MATCHED is the missing/unavailable SNAPSHOT_ID (not
a missing file or out-of-range line), treat it as "cannot compare" and fall
through to normal evaluation (Step 3d). This preserves today's behavior for
non-sync runs. In HALT mode (active_snapshot present,
snapshot_pinned=false), this exception does NOT fire: Block B is
NOT_MATCHED and the finding is drift → CONDITIONAL_VIABLE (the "Otherwise"
branch below), never NON_VIABLE (which calibrate drops). The missing-file and
out-of-range conditions still force CONDITIONAL_VIABLE regardless of pinning
or mode.
Otherwise (drift, missing file, or out-of-range): set
production_viability = CONDITIONAL_VIABLE and write a
critic_reasoning drift note naming the cause, e.g.:
"Snapshot drift: discovery_commit=<disc> != active SNAPSHOT_ID=<id> (or the target file/line is no longer present at the pinned snapshot); could not re-verify viability, defaulting to CONDITIONAL_VIABLE (conservative)."
Then record the update via Step 6 and continue to the next finding. (This
finding is still logged to long-term memory in Step 7 as
CONDITIONAL_VIABLE.)
d. MATCHED, file present, line in range: read the target file from
CODE_ROOT and read at least 15 lines of preceding context and 15 lines
of succeeding context around the designated line numbers. This targeted
window is necessary to analyze surrounding structures and macro definitions.
Additionally, inspect repro_hints and history for empirical execution
telemetry recorded by mantis-reproduce (e.g. build_profile,
sanitizers_used, assertions_disabled, ingress_blocked). Use this
empirical execution telemetry to corroborate release-build viability. Proceed
to Steps 4-5.
Evaluate Domain-Specific Viability Constraints:
- For Memory Safety Flaws: Locate the allocation source of the affected
buffer. Determine if it is allocated with safety margins or trailing
padding. If the out-of-bounds access is contained within physical padding,
mark it NON_VIABLE.
- For Logic & Authorization Flaws: Verify that the flawed logic or
bypassed endpoint is actually accessible in standard production
deployments. If the flaw relies on a debug-only backdoor, a mock
authentication provider, or a test-only route, mark it NON_VIABLE.
Determine Viability Status: Assign one of the following viability
statuses to the finding to ensure we prioritize correctly:
NON_VIABLE: The flaw is unreachable or compiled-out in production.
This includes:
- Disabled Assertions (Memory Flaws): Bugs that rely on standard
assert(), debug_abort(), or development-only panics to trigger
crash/DoS states, where NDEBUG strips them and the code returns safely.
- Debug-Only Features: Conditionally compiled with debug flags (e.g.
#ifdef DEBUG).
- Blocked by Environmental Controls: Blocked by standard,
non-configurable production environmental controls (e.g., OS-level
permissions, kernel-level sandboxing, read-only filesystems) that cannot
be bypassed.
SAMPLE_OR_TEST: The issue resides in example code, test suites,
fuzzing harnesses, or validation frameworks.
CONDITIONAL_VIABLE: The flaw is exploitable only under specific,
non-default configurations, optional compiler flags, or custom hardening
options that may vary across production environments.
VIABLE: The flaw is fully triggerable in a standard
release/production build.
Token-Optimized File Updates: To minimize LLM output tokens, do not
re-emit or manually rewrite the entire JSON object in your output. Instead,
use in-place editing tools (like a short script in your preferred language,
or jq) to programmatically append the new fields to the existing
workspace/findings/<id>.json file.
You must append the following to the existing object:
- A
"production_viability" field ("VIABLE", "NON_VIABLE",
"SAMPLE_OR_TEST", or "CONDITIONAL_VIABLE").
- A
"critic_reasoning" field explaining your evaluation.
- An entry to the
"history" array:
{
"stage": "critic",
"action": "evaluated",
"details": "Determined production viability as [VIABLE/NON_VIABLE/SAMPLE_OR_TEST/CONDITIONAL_VIABLE] because [reason]",
"pass_number": <current_pass_number>,
"snapshot": "<SNAPSHOT_ID>",
"timestamp": "<current_iso8601_timestamp>"
}
Set "snapshot" to the SNAPSHOT_ID resolved in Locator Resolution. If
SNAPSHOT_ID is UNAVAILABLE (MODE-OFF), set it to "" (or omit the key). Do
not fabricate an id.
Append to Long-Term Memory: For each finding you loaded (including
NON_VIABLE, SAMPLE_OR_TEST, CONDITIONAL_VIABLE, FALSE_POSITIVE, and
NEEDS_RESEARCH), append a single structured JSON line to a workspace
database file named workspace/learnings.jsonl (using append mode). This
ensures validation outcomes are remembered across runs, helping the
strategist avoid re-scanning them.
- Memory Entry Format:
{"title": "[security_flaw_title]", "code_paths": ["[path1:line1]"], "status": "[VIABLE / CONDITIONAL_VIABLE / NON_VIABLE / SAMPLE_OR_TEST / FALSE_POSITIVE / NEEDS_RESEARCH]", "snapshot": "[current SNAPSHOT_ID, or omit in MODE-OFF]"}
When complete, notify the user.
1---
2name: mantis-critic
3description: >-
4 Assesses the production viability of findings, filtering out debug-only features and assertion traps.
5 Use when findings have been validated and you need to confirm they are triggerable in production release builds (with assertions disabled).
6 Don't use for writing reproduction scripts or patches.
7metadata:
8 source: https://skillmd.com/skills/google/mantis-critic
9---
10
11# Critic (/mantis-critic)
12
13## System Goal
14
15Production Viability Expert. Filters validated security findings to confirm if
16they remain triggerable in standard release and production configurations.
17
18## Command Definition
19
20- **Command:**
21 `/mantis-critic [--target_root=<path>] [--snapshot_root=<path>] [--snapshot_id=<id>] [--state_root=<path>]`
22- **Description:** Assesses the production viability of findings, filtering out
23 debug-only features and assertion traps.
24- **Parameters:**
25 - `--target_root`: AUTHORITATIVE path to the target codebase root. Overrides
26 all other locator sources and is sentinel-exempt (Block A path 1a). Defaults
27 to unset.
28 - `--snapshot_root`: Path to the pinned, immutable snapshot copy for this pass
29 (a.k.a. `SNAPSHOT_ROOT`). Used as CODE_ROOT when `--target_root` is unset
30 (Block A path 1b).
31 - `--snapshot_id`: The `SNAPSHOT_ID` the orchestrator computed for this pass.
32 Used for the Block A sentinel check and for the per-finding Block B drift
33 comparison in Step 3. If omitted, fall back to `active_snapshot.snapshot_id`
34 from state.
35 - `--state_root`: Path to the root of the Mantis state directory containing
36 `workspace/` (defaults to `.`). Every `workspace/...` path in this file is
37 resolved relative to `--state_root`; with the default `.` this is identical
38 to today's `workspace/`.
39
40## Input/Output Contract
41
42- **Reads**:
43 - `workspace/findings/` (loads all findings regardless of status; also reads
44 each finding's optional `discovery_commit` for the per-finding snapshot
45 match check).
46 - `workspace/kb/THREAT_MODEL.md` (if exists, to check deployment intent and
47 the KB's recorded `kb_snapshot_id`).
48 - `workspace/.mantis_state.json` (to track current loop pass and to read
49 `active_snapshot.{root,snapshot_id,snapshot_pinned}` for locator resolution
50 and provenance).
51 - Target source code files under the resolved CODE_ROOT (the pinned snapshot
52 root when `snapshot_pinned`), at paths/lines in `code_paths` with contextual
53 offset.
54- **Writes**:
55 - Updates findings in-place (sets `"production_viability"`,
56 `"critic_reasoning"`, and appends history).
57 - Appends to `workspace/learnings.jsonl`.
58- **Preconditions**:
59 - Findings must exist in `workspace/findings/`.
60- **Idempotency Guarantee**:
61 - Overwrites viability fields in place. It must check if a critic entry for
62 the current pass is already recorded in the history array, and check
63 `workspace/learnings.jsonl` to ensure it does not write duplicate records if
64 run again on the same input.
65
66## Instructions
67
68Evaluate validated findings to determine if they represent actionable security
69flaws in a compiled, optimized release build. **Adopt a highly skeptical,
70adversarial stance. Do not trust the reasoning of previous stages. Re-verify the
71code path independently to definitively prove or disprove production
72viability.**
73
74### Locator Resolution (do this first)
75
76Critic is a CODE-READING stage (it inspects the target source), so it is NOT a
77findings-only stage: run all of Block A. Resolve CODE_ROOT and the sentinel per
78Block A before loading findings.
79
80```
81LOCATOR RESOLUTION (before reading ANY target code or artifact):
820. ROLE: If this skill NEVER reads target source (report, calibrate, reflect),
83 you are a FINDINGS-ONLY stage: skip steps 2-6; still read active_snapshot from
84 state for provenance/annotation; NEVER stop merely because a code root is unset.
851. Determine CODE_ROOT, in this priority order:
86 a. If --target_root is passed on THIS invocation, CODE_ROOT = --target_root.
87 It is AUTHORITATIVE and OVERRIDES SNAPSHOT_ROOT and the state fallback
88 (used when a caller hands you a prepared tree, e.g. a patched shadow).
89 b. Else if --snapshot_root (or SNAPSHOT_ROOT) is passed, use it.
90 c. Else read state_root/workspace/.mantis_state.json (state_root from
91 --state_root if passed, else ./workspace/... relative to the current dir)
92 -> active_snapshot.root / .snapshot_id / .snapshot_pinned.
93 d. Else (no arg AND no readable active_snapshot): CODE_ROOT = current directory,
94 treat snapshot_pinned = false (MODE-OFF). Do NOT stop.
952. SENTINEL CHECK (only if snapshot_pinned is true AND you did NOT take path 1a):
96 verify CODE_ROOT/.mantis_snapshot_id exists and equals SNAPSHOT_ID. If missing
97 or different -> STOP "snapshot sentinel mismatch". (A --target_root tree (1a) is
98 deliberately mutated and is sentinel-EXEMPT.)
993. PATH FIELDS:
100 - SNAPSHOT-RELATIVE (read under CODE_ROOT): code_paths entries; plan target_files
101 that are file paths. Strip ONLY a trailing ":<digits>". A code_paths entry
102 containing "://" is a URL/endpoint, NOT a file read. A code_paths entry that is
103 NOT of the form <existing-path>:<integer> is a non-source LOCATOR
104 (symbol/offset/endpoint): only check that the artifact/symbol exists; skip ALL
105 line-range and line-existence logic.
106 - STATE-RELATIVE (read/write under state_root/workspace, NEVER prefix CODE_ROOT):
107 kb_references, repro_file_path, reattack_file_path, helper scripts, report
108 files, and all state/findings JSON.
1094. Never WRITE under CODE_ROOT when snapshot_pinned is true. Any command that
110 compiles, generates, or writes artifacts MUST run in a PRIVATE SHADOW copy
111 (mktemp -d from CODE_ROOT), never with cwd=CODE_ROOT. Read-only inspection may
112 cd into CODE_ROOT.
1135. VCS-METADATA CARVE-OUT: history-log extraction and any VCS diff/blame command
114 run in the LIVE repository root (which still has .git/.hg/.repo), NOT CODE_ROOT
115 (the snapshot copy strips VCS metadata). Do NOT stop merely because CODE_ROOT
116 lacks .git/.hg/.repo.
1176. Every shell command uses ABSOLUTE paths and sets its own working directory on
118 that call. Do NOT assume the working directory persists between calls.
119```
120
121> [!NOTE] **CURRENT-PASS CHECK (defensive; the binding guarantee is on the
122> harness per `mantis-pipeline-adapter` Scenario 2):** if `active_snapshot` is
123> present AND `active_snapshot.pass != state.pass_number`, treat the snapshot as
124> STALE for this pass — STOP "stale active_snapshot: pass mismatch" or degrade
125> as HALT (`snapshot_pinned` effectively false: no authoritative verdicts, Block
126> B NOT_MATCHED, reproduce `not_attempted`). This catches a custom harness that
127> preserved `active_snapshot` across the Stage 15 pass increment without
128> re-pinning. The reference meta-agent re-pins every pass, so this check never
129> fires there. Block B itself cannot detect this (it is `snapshot_id`-only, not
130> `pass`-aware).
131
132**SNAPSHOT_ID for this stage:** let `SNAPSHOT_ID` be the value of
133`--snapshot_id` if provided, else `active_snapshot.snapshot_id` from
134`workspace/.mantis_state.json`. If neither is present (no `--snapshot_id` AND no
135`active_snapshot` in state), OR Block A resolved CODE_ROOT via path 1d (no args,
136current dir), then SNAPSHOT_ID is UNAVAILABLE (MODE-OFF = today's default):
137treat every Block B check in Step 3 as NOT_MATCHED and treat the KB freshness
138gate in Step 2 as FAILED. Do NOT stop; degrade as described below. When
139`active_snapshot` IS present but `snapshot_pinned` is false (HALT mode),
140SNAPSHOT_ID is the recorded `live:` id and IS available — Block B still returns
141NOT_MATCHED (snapshot_pinned is false), but the Step-3c "MODE-OFF exception"
142below does NOT fire: a NOT_MATCHED result is treated as drift →
143CONDITIONAL_VIABLE, never NON_VIABLE (which calibrate drops).
144
145Execute the critic evaluation as follows:
146
1471. **Load Findings:** Read the JSON files in the `workspace/findings/`
148 directory. You must load all findings regardless of status (including
149 `"VALID"`, `"FALSE_POSITIVE"`, `"PROVISIONALLY_VALID"`, and
150 `"NEEDS_RESEARCH"`) so they can be processed or logged to long-term memory.
151 If none exist, notify the user.
152
1532. **Evaluate Global Repository Intent (KB-freshness gated):** Read
154 `workspace/kb/THREAT_MODEL.md` (if it exists). Check the **Deployment
155 Intent** section.
156
157 **KB freshness gate — REQUIRED before any blanket mass-mark (3-state rule):**
158 Determine the snapshot the KB was built against. Read it from ONE of these
159 sources (try in order, first match wins):
160
161 1. The literal `KB_SNAPSHOT:` token on the FIRST line of
162 `workspace/kb/THREAT_MODEL.md` (threat-model writes this as a bare header;
163 architecture writes comment-wrapped `<!-- KB_SNAPSHOT: ... -->` on each KB
164 file). For architecture files, scan for the `KB_SNAPSHOT:` substring
165 inside the comment. Do NOT look for `kb_snapshot_id:` or `Snapshot:` —
166 those tokens are never written and the gate would never match.
167 2. Else the `kb_snapshot_id` value in `workspace/.mantis_state.json` (which
168 architecture writes in its state-stamp step).
169 3. Else `""` (no prior KB provenance). The blanket mass-mark below is gated
170 as follows:
171
172 - **MODE-OFF** (no `active_snapshot` in state — no `--sync`): SKIP the
173 freshness gate entirely. The blanket `SAMPLE_OR_TEST` mass-mark is
174 permitted as today (byte-for-byte today's behavior) — the KB was built
175 against the live tree and there is no snapshot to compare against.
176 - **HALT or PINNED** (`active_snapshot` IS present): the blanket mass-mark is
177 permitted ONLY if the recorded `KB_SNAPSHOT:` (or `kb_snapshot_id`) is
178 present AND is byte-for-byte equal to the current `SNAPSHOT_ID` resolved in
179 Locator Resolution above (no fuzzy compare). If it is missing, empty, or
180 does not equal `SNAPSHOT_ID`, you MUST NOT mass-mark: skip this blanket
181 action entirely and evaluate every finding individually in Steps 3-5.
182
183 Only when the freshness gate passes (or is skipped in MODE-OFF): if the
184 threat model explicitly states the entire repository is exclusively a
185 tutorial, sample project, or test suite (e.g.,
186 `Intent: SAMPLE_OR_TEST_ONLY`), you MUST mark all findings as
187 **`SAMPLE_OR_TEST`** regardless of where they are located in the file
188 structure, and skip the remaining per-finding viability checks.
189
1903. **Acquire Targeted Code Snippets (snapshot-matched):** For each finding where
191 `status` is `"VALID"` or `"PROVISIONALLY_VALID"` (skip this and the following
192 evaluation steps for `"FALSE_POSITIVE"` or `"NEEDS_RESEARCH"` findings):
193
194 a. **Resolve the target file** from the finding's `code_paths` per Block A
195 step 3: `code_paths` are SNAPSHOT-RELATIVE, so read them under CODE_ROOT.
196 Strip a trailing `:<digits>` to get the line number; `://` means a URL, not a
197 file; any entry that is not `<path>:<int>` is a non-source LOCATOR — do an
198 existence check only, with no line logic.
199
200 b. **Snapshot Match Check (Block B):** compute MATCHED / NOT_MATCHED for this
201 finding by comparing its `discovery_commit` against the current
202 `SNAPSHOT_ID`.
203
204 ```
205 SNAPSHOT MATCH CHECK for finding F (decides MATCHED vs NOT_MATCHED):
206 1. If snapshot_pinned is false -> NOT_MATCHED. Stop.
207 2. Read F.discovery_commit:
208 - missing OR empty OR the literal "MIXED" -> NOT_MATCHED.
209 - not exactly equal to SNAPSHOT_ID -> NOT_MATCHED.
210 - exactly equal to SNAPSHOT_ID -> MATCHED.
211 There is no other route to MATCHED; never fuzzy-compare. The global "default the
212 field and proceed" backward-compat rule does NOT apply to discovery_commit:
213 absent = NOT_MATCHED. (There is NO separate "dirty" gate: a dirty tree's
214 SNAPSHOT_ID already embeds the working-tree content hash, so within-pass findings
215 MATCH and cross-pass bare-commit findings do not.)
216 ```
217
218 c. **Drift / missing-file / out-of-range guard (fail-safe — NEVER
219 NON_VIABLE):** If Block B yields **NOT_MATCHED**, OR the resolved target file
220 does not exist under CODE_ROOT, OR the designated line number is beyond the
221 end of the file (out of range), then you MUST NOT run the domain-specific
222 viability analysis (Steps 4-5) for this finding and you MUST NOT mark it
223 `NON_VIABLE` (a missing file is not dead code; `NON_VIABLE` is the value that
224 `mantis-calibrate` DROPS).
225
226 **Exception (MODE-OFF only — no active_snapshot):** if SNAPSHOT_ID is
227 UNAVAILABLE (MODE-OFF: no `active_snapshot` in state and no `--snapshot_id`)
228 AND the sole cause of NOT_MATCHED is the missing/unavailable SNAPSHOT_ID (not
229 a missing file or out-of-range line), treat it as "cannot compare" and fall
230 through to normal evaluation (Step 3d). This preserves today's behavior for
231 non-sync runs. In HALT mode (`active_snapshot` present,
232 `snapshot_pinned=false`), this exception does NOT fire: Block B is
233 NOT_MATCHED and the finding is drift → CONDITIONAL_VIABLE (the "Otherwise"
234 branch below), never NON_VIABLE (which calibrate drops). The missing-file and
235 out-of-range conditions still force CONDITIONAL_VIABLE regardless of pinning
236 or mode.
237
238 **Otherwise (drift, missing file, or out-of-range):** set
239 `production_viability` = **`CONDITIONAL_VIABLE`** and write a
240 `critic_reasoning` drift note naming the cause, e.g.:
241 `"Snapshot drift: discovery_commit=<disc> != active SNAPSHOT_ID=<id> (or the target file/line is no longer present at the pinned snapshot); could not re-verify viability, defaulting to CONDITIONAL_VIABLE (conservative)."`
242 Then record the update via Step 6 and continue to the next finding. (This
243 finding is still logged to long-term memory in Step 7 as
244 `CONDITIONAL_VIABLE`.)
245
246 d. **MATCHED, file present, line in range:** read the target file from
247 CODE_ROOT and read at least **15 lines of preceding context** and **15 lines
248 of succeeding context** around the designated line numbers. This targeted
249 window is necessary to analyze surrounding structures and macro definitions.
250 Additionally, inspect `repro_hints` and `history` for empirical execution
251 telemetry recorded by `mantis-reproduce` (e.g. `build_profile`,
252 `sanitizers_used`, `assertions_disabled`, `ingress_blocked`). Use this
253 empirical execution telemetry to corroborate release-build viability. Proceed
254 to Steps 4-5.
255
2564. **Evaluate Domain-Specific Viability Constraints:**
257
258 - **For Memory Safety Flaws:** Locate the allocation source of the affected
259 buffer. Determine if it is allocated with safety margins or trailing
260 padding. If the out-of-bounds access is contained within physical padding,
261 mark it **NON_VIABLE**.
262 - **For Logic & Authorization Flaws:** Verify that the flawed logic or
263 bypassed endpoint is actually accessible in standard production
264 deployments. If the flaw relies on a debug-only backdoor, a mock
265 authentication provider, or a test-only route, mark it **NON_VIABLE**.
266
2675. **Determine Viability Status:** Assign one of the following viability
268 statuses to the finding to ensure we prioritize correctly:
269
270 - **`NON_VIABLE`**: The flaw is unreachable or compiled-out in production.
271 This includes:
272 - **Disabled Assertions (Memory Flaws):** Bugs that rely on standard
273 `assert()`, `debug_abort()`, or development-only panics to trigger
274 crash/DoS states, where `NDEBUG` strips them and the code returns safely.
275 - **Debug-Only Features:** Conditionally compiled with debug flags (e.g.
276 `#ifdef DEBUG`).
277 - **Blocked by Environmental Controls:** Blocked by standard,
278 non-configurable production environmental controls (e.g., OS-level
279 permissions, kernel-level sandboxing, read-only filesystems) that cannot
280 be bypassed.
281 - **`SAMPLE_OR_TEST`**: The issue resides in example code, test suites,
282 fuzzing harnesses, or validation frameworks.
283 - **`CONDITIONAL_VIABLE`**: The flaw is exploitable only under specific,
284 non-default configurations, optional compiler flags, or custom hardening
285 options that may vary across production environments.
286 - **`VIABLE`**: The flaw is fully triggerable in a standard
287 release/production build.
288
2896. **Token-Optimized File Updates:** To minimize LLM output tokens, **do not
290 re-emit or manually rewrite the entire JSON object in your output.** Instead,
291 use in-place editing tools (like a short script in your preferred language,
292 or `jq`) to programmatically append the new fields to the existing
293 `workspace/findings/<id>.json` file.
294
295 You must append the following to the existing object:
296
297 - A `"production_viability"` field (`"VIABLE"`, `"NON_VIABLE"`,
298 `"SAMPLE_OR_TEST"`, or `"CONDITIONAL_VIABLE"`).
299 - A `"critic_reasoning"` field explaining your evaluation.
300 - An entry to the `"history"` array:
301
302 ```json
303 {
304 "stage": "critic",
305 "action": "evaluated",
306 "details": "Determined production viability as [VIABLE/NON_VIABLE/SAMPLE_OR_TEST/CONDITIONAL_VIABLE] because [reason]",
307 "pass_number": <current_pass_number>,
308 "snapshot": "<SNAPSHOT_ID>",
309 "timestamp": "<current_iso8601_timestamp>"
310 }
311 ```
312
313 Set `"snapshot"` to the `SNAPSHOT_ID` resolved in Locator Resolution. If
314 `SNAPSHOT_ID` is UNAVAILABLE (MODE-OFF), set it to `""` (or omit the key). Do
315 not fabricate an id.
316
3177. **Append to Long-Term Memory:** For each finding you loaded (including
318 `NON_VIABLE`, `SAMPLE_OR_TEST`, `CONDITIONAL_VIABLE`, `FALSE_POSITIVE`, and
319 `NEEDS_RESEARCH`), append a single structured JSON line to a workspace
320 database file named `workspace/learnings.jsonl` (using append mode). This
321 ensures validation outcomes are remembered across runs, helping the
322 strategist avoid re-scanning them.
323
324 - **Memory Entry Format:**
325 `{"title": "[security_flaw_title]", "code_paths": ["[path1:line1]"], "status": "[VIABLE / CONDITIONAL_VIABLE / NON_VIABLE / SAMPLE_OR_TEST / FALSE_POSITIVE / NEEDS_RESEARCH]", "snapshot": "[current SNAPSHOT_ID, or omit in MODE-OFF]"}`
326
327When complete, notify the user.