Architect (/mantis-architecture)
System Goal
Knowledge Base Synthesizer. Translates ephemeral insights from the learnings
queue (workspace/learnings.jsonl) and structural analysis of the codebase into
a canonical, interlinked Markdown Knowledge Base (workspace/kb/).
Command Definition
- Command:
/mantis-architecture
- Description: Builds the foundation of the KB by defining system
architecture, mapping specific entities (components), and categorizing
historical vulnerability patterns.
- Arguments (all optional; resolved by LOCATOR RESOLUTION / Block A):
--snapshot_root=<dir> (or the SNAPSHOT_ROOT env var) — the pinned code
snapshot to read target source from; --snapshot_id=<id> — the SNAPSHOT_ID
of that snapshot; --state_root=<dir> — the parent of workspace/ for all
state and KB paths; --target_root=<dir> — an already-prepared tree that
OVERRIDES the snapshot (rarely passed to this stage). When none are passed,
behavior is byte-for-byte today's (degraded/unpinned): read source from the
current directory and treat snapshot_pinned as false.
Input/Output Contract
- Reads:
workspace/learnings.jsonl (raw insights from the current round).
workspace/historical_learnings.jsonl (optional, past vulnerability
metadata).
- Codebase directory structure and key source files.
- Existing Markdown files in
workspace/kb/ (to validate/decay check).
workspace/.mantis_state.json (to retrieve pass count).
workspace/.mantis_state.json → active_snapshot (root, snapshot_id,
snapshot_pinned) and snapshot_history — provenance for the KB freshness
gate (step 0b). Read the snapshot from STATE ONLY; NEVER run a live VCS
command (git/hg/repo) to decide KB currency.
workspace/.mantis_state.json → kb_snapshot_id (the SNAPSHOT_ID the
current KB was last built against; absent on a first/legacy KB).
workspace/.mantis_state.json → changed_files and changed_files_status
(written by mantis-plan's Block E; consumed by the scoped KB invalidation in
step 0b outcome 3. Present from pass 2 on, but may be stale (written in a
prior pass) — the scoped path checks changed_files_pass against
state.pass_number and falls back to full rebuild if they differ.)
- Writes:
- Markdown files under
workspace/kb/ (architecture.md,
entities/[component_name].md, vulnerabilities/[CWE-ID].md, index.md).
workspace/kb/dependencies.json — a JSON map of import/dependency edges
extracted during architectural analysis (keys = source file paths relative
to CODE_ROOT; values = arrays of files that import/depend on the key file).
This is consumed by mantis-plan's dependency-aware fan-out (Phase 2). If
the codebase has no parseable import structure, write {}. Re-derive only
changed entries during scoped invalidation (see outcome 3 below).
- Archives
workspace/learnings.jsonl to
workspace/archive/learnings/learnings_pass_${N}_${X}.jsonl.
- A
<!-- KB_SNAPSHOT: <SNAPSHOT_ID> --> marker as the FIRST line of every
(re)written KB file (index.md, each entities/*.md, each
vulnerabilities/*.md), plus kb_snapshot_id = SNAPSHOT_ID in
workspace/.mantis_state.json.
- An immutable per-pass copy of the whole KB tree to
workspace/archive/kb/kb_pass_${N}_${X}/ (so a later reverted fix cannot
silently erase the record of what the KB claimed at pass N).
- Preconditions:
workspace/learnings.jsonl must exist.
- Idempotency Guarantee:
- Transactional: moves
workspace/learnings.jsonl to archive only after
programmatically verifying all KB Markdown updates were written
successfully. KB files are overwritten in-place.
- Snapshot stamping is part of the same transaction: the
KB_SNAPSHOT
markers, the per-pass workspace/archive/kb/kb_pass_${N}_${X_kb}/ copy, and
the kb_snapshot_id state write complete before (or together with) the
learnings move. On any failure, leave workspace/learnings.jsonl intact.
Instructions
Analyze the codebase and pending learnings to construct a permanent,
Markdown-based memory for future agents.
Execute the architecture stage as follows:
- LOCATOR RESOLUTION (Block A, inlined below):
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.
This is a CODE-READING stage (steps 2 and 4 read target source), so Block A
steps 1-6 all apply; it is NOT findings-only. Resolve CODE_ROOT,
SNAPSHOT_ID, and snapshot_pinned from state BEFORE doing anything below. Per
Block A step 3, all workspace/kb/... paths are STATE-RELATIVE: read and write
them under state_root/workspace, NEVER under CODE_ROOT. Read all target
source under CODE_ROOT. Do NOT run any VCS command to decide KB freshness
(Block A step 5's carve-out is only for history/diff/blame, which this stage
does not use).
0b. KB SNAPSHOT FRESHNESS GATE (mechanical; STATE + KB marker only, NO live
VCS):
- `CUR` = `SNAPSHOT_ID` (resolved by Block A; the empty string if
`active_snapshot` was absent). `PINNED` = `snapshot_pinned` (false if absent).
- **MODE-OFF short-circuit (3-state rule):** if `active_snapshot` is ABSENT
in state (no `--sync` was requested — MODE-OFF = today's default), SKIP the
freshness gate entirely: do a best-effort build/update against `CODE_ROOT`,
do NOT prepend any STALE banner, and do
NOT stamp `kb_snapshot_id`. This is byte-for-byte today's behavior. (Only
HALT and PINNED run the gate below.)
- `KB_ID` = the `kb_snapshot_id` value in `.mantis_state.json` (primary); else the
text after `KB_SNAPSHOT:` on the FIRST line of
`state_root/workspace/kb/index.md` if that file exists (secondary fallback,
for legacy runs without state); else `""` (no prior KB). State is primary so
the file-marker parsing pitfall (comment-wrapped first line, no `-->`
stripping) can never strand `KB_ID` with the comment closer and force BUILD
FRESH every pass.
- Choose EXACTLY ONE outcome by string checks, top to bottom, first match wins:
1. `PINNED` is false (HALT mode — `active_snapshot` present but unpinned)
-> **STALE / HALT.** Do a best-effort build/update against `CODE_ROOT`,
but PREPEND the STALE banner (below) as the first lines of `index.md`.
Do NOT claim currency: leave the
banner in place. Set `kb_snapshot_id` = `CUR` (a `live:` id).
2. Else `KB_ID` == `CUR` (both non-empty) -> **CURRENT.** Do the incremental
update + decay-check (step 4) as today. Re-stamp `KB_SNAPSHOT: CUR` on
every (re)written file. REMOVE any STALE banner previously prepended to
`index.md`.
3. Else (`PINNED` true AND (`KB_ID` is empty OR `KB_ID` != `CUR`)) ->
**BUILD FRESH (full or scoped re-architecture).** The pinned code advanced
since the KB was built (a sync / pass-boundary change), OR the KB is
unstamped / legacy. Choose full or scoped:
- **Scoped invalidation (Phase 2 incremental efficiency):** If
`changed_files_status` is known (not UNKNOWN) AND the KB already has a
`KB_SNAPSHOT` stamp (KB_ID was non-empty, just different) AND
`changed_files_pass` equals the current `state.pass_number` (the diff
is from THIS pass, not a stale prior pass — absent or different →
treat as UNKNOWN → full rebuild below), attempt a SCOPED rebuild: only
invalidate KB entries whose source files are in `changed_files`, plus
their parent-rollup dependents (KB entities that import/reference the
changed files). Re-derive ONLY those entries from `CODE_ROOT`; carry
forward all other KB entries unchanged (they were built against the
same code, just a different snapshot ID). Re-stamp `KB_SNAPSHOT: CUR`
on every (re)written file.
- **Parent-rollup (2-hop, matching plan's fan-out):** When
invalidating a KB entry for changed file F, also invalidate any KB
entry that REFERENCES F directly (1-hop) AND any entry that
references a 1-hop dependent of F (2-hop). This matches
`mantis-plan`'s dependency-aware fan-out (which expands up to 2
hops), ensuring that a grandchild entity (H imports G, G imports
changed F) is not carried forward stale and later fed as a
`kb_reference` while its dependency has changed.
- **Guardrail:** If ANY uncertainty arises (can't determine which KB
entries map to which source files, the KB structure is ambiguous, or
changed_files is empty but KB_ID != CUR), fall back to full rebuild
below. Never carry forward a stale entry for a changed file.
- **Full rebuild (Phase-1 fallback):** If KB_ID is empty (no prior KB),
OR `changed_files_status` is UNKNOWN, OR the scoped invalidation guardrail
fired, REBUILD every KB file from scratch against `CODE_ROOT`. Do NOT
carry forward any prior assertion you have not re-derived from
`CODE_ROOT` this pass. Stamp `KB_SNAPSHOT: CUR`. REMOVE any STALE banner.
- STALE banner (paste verbatim, substituting `<KB_ID>` and `<CUR>`; keep the
leading `>` on every line so it renders as a visible blockquote):
```
> **STALE KB WARNING — do not trust without re-verifying.**
> snapshot_pinned=false, or the KB was built against a different snapshot.
> KB_SNAPSHOT=<KB_ID> does not match active_snapshot.snapshot_id=<CUR>.
> Every SECURE/FIXED/NON_VIABLE/SAMPLE_OR_TEST claim below is UNVERIFIED
> against the current code. Re-verify before trusting; do NOT filter, skip,
> or down-prioritize work based on this KB.
```
Read the Inbox (workspace/learnings.jsonl and
workspace/historical_learnings.jsonl):
- Parse the contents of
workspace/learnings.jsonl (and
workspace/historical_learnings.jsonl if it exists). Extract all
trajectory insights, discovered vulnerabilities, viable crash paths, and
verified patches.
Analyze Source Code Boundaries:
- Examine the directory structure and key source files under
CODE_ROOT
(the pinned snapshot resolved by Block A; use absolute paths per Block A
step 6, and do NOT run a VCS command). Dynamically identify the core
components, interfaces, and trust boundaries of the system based on the
repository's contents. This applies broadly across domains: whether it is a
software system (e.g., identifying parsers, controllers, or network
daemons), a hardware/RTL design (e.g., identifying IP blocks, JTAG
interfaces, or memory controllers), Infrastructure-as-Code (e.g.,
identifying cloud permissions, VPC perimeters, or deployment descriptors),
or data/ML pipelines (e.g., identifying data ingress points, model
serialization mechanisms, or training boundaries).
Build or Update the Knowledge Base (KB):
Create or update files in the workspace/kb/ directory using standard
Markdown. Follow these strict paths:
workspace/kb/architecture.md: High-level data flows, zone definitions,
system design, and overall availability/uptime requirements (if
documented or inferable from configuration like systemd, kubernetes, or
load balancers).
workspace/kb/entities/[component_name].md: Specific definitions for
components (e.g., auth_module.md). Must include links to associated
vulnerability classes and document known constraints (e.g., "This module
sanitizes input X"). Document the component's criticality and
availability requirements (classify as CRITICAL, STANDARD, or
LOW_CRITICALITY if applicable). Incorporate trajectory insights here.
workspace/kb/vulnerabilities/[CWE-ID_or_BugClass].md: Descriptions of
bug classes (e.g., CWE-79.md or Memory-Corruption.md) that have been
historically relevant to this codebase, including examples of what not
to do.
workspace/kb/index.md: A root catalog containing links and 1-line
summaries to every file created above. This is the map the Planner will
read.
Important Formatting Rules: Use relative links to cross-reference
entities and vulnerabilities (e.g.,
[Auth Module](entities/auth_module.md)). Ensure all markdown files are
concise and focused on actionable security context.
Snapshot stamping (REQUIRED on every (re)written KB file when running the
freshness gate, i.e. HALT or PINNED; never in MODE-OFF): Make the FIRST
line of index.md, each entities/*.md, and each vulnerabilities/*.md
exactly <!-- KB_SNAPSHOT: <SNAPSHOT_ID> --> (substitute CUR from step
0b; it is an HTML comment so it does not render). This is how the next
pass's freshness gate (step 0b) detects drift. MODE-OFF gate (3-state
rule): if active_snapshot is ABSENT (MODE-OFF — no --sync was
requested), do NOT stamp the per-file KB_SNAPSHOT marker: CUR is the
empty string (arch:145: "the empty string if active_snapshot was
absent"), so the mandated marker would be <!-- KB_SNAPSHOT: --> (empty
value) — a snapshot-era artifact that did not exist in Phase 1. The
per-file marker is ONLY consumed by step 0b's freshness gate, which
MODE-OFF skips entirely (arch:147-152: "SKIP the freshness gate
entirely... This is byte-for-byte today's behavior. Only HALT and PINNED
run the gate below."). This MODE-OFF gate mirrors the freshness gate logic
below and step 0b's outcome clauses, which mention per-file
KB_SNAPSHOT: CUR stamping only in HALT/PINNED outcomes (CURRENT :164,
scoped BUILD FRESH :178, full BUILD FRESH :195).
Per-file KB_SNAPSHOT stamping is the sole provenance mechanism for KB
assertions. Do NOT write per-assertion (AS_OF:<snapshot>) tags — the
AS_OF re-verification reader was never built, and staleness protection is
already provided by the freshness gate (step 0b) comparing kb_snapshot_id
to SNAPSHOT_ID, plus per-finding discovery_commit (enforced by
mantis-critic Block B). A later-reverted fix is caught by these
mechanisms, not by per-assertion tags.
Validate and Decay Knowledge (Drift Prevention):
- Knowledge becomes stale when code is patched or refactored. Before
finalizing the KB updates, spot-check the assertions in the existing
workspace/kb/entities/ against the source under CODE_ROOT (the
pinned snapshot — NOT a live VCS query, and NOT the live working tree). In
the BUILD FRESH outcome (step 0b) do NOT spot-check at all: discard the
prior assertions and re-derive every entity from CODE_ROOT this pass. In
the STALE / HALT outcome, spot-check only best-effort and keep the
STALE banner regardless of the result.
- If an entity file claims a variable is un-sanitized (based on an old
learning) but the live code now contains a sanitization function (because a
patch landed), delete or correct that outdated learning in the KB.
- If a learning is repeatedly proven wrong by the current trajectory
insights, actively correct it to prevent the "wrong learning" from
persisting and blinding future agents.
- When you correct or re-confirm a finding-derived assertion, re-stamp the
KB_SNAPSHOT marker on that KB file.
Transactional Inbox Clearing & Archiving:
- To prevent infinite loops and token bloat, you must clear the queue and
archive the learnings.
- Verify and Finalize: Programmatically verify that all Markdown KB
updates were successfully written to disk and that cross-references are
valid. Also verify, before committing, that every (re)written KB file
BEGINS with its
<!-- KB_SNAPSHOT: <SNAPSHOT_ID> --> marker and that every
finding-derived verdict is grounded in the current SNAPSHOT_ID.
- Commit by Moving: Only after verifying synthesis success, move
workspace/learnings.jsonl to the archive directory:
- Ensure the target directory exists (e.g.,
mkdir -p workspace/archive/learnings/).
- Determine the loop pass number
N by reading "pass_number" from
workspace/.mantis_state.json. If missing or invalid, scan
workspace/archive/ for folders matching findings_pass_N or
loopN_findings and resolve N to max_found + 1, defaulting to 1 if
no archives exist.
- Determine the sub-index
X by counting existing files matching
learnings_pass_${N}_*.jsonl in workspace/archive/learnings/ and
adding 1.
- Move the file:
mv workspace/learnings.jsonl workspace/archive/learnings/learnings_pass_${N}_${X}.jsonl.
- Snapshot the KB (per-pass archive): After a successful synthesis, copy
the whole KB tree to a per-pass archive:
- Ensure the directory exists (
mkdir -p workspace/archive/kb/).
- Compute sub-index
X_kb = (count of existing kb_pass_${N}_*
directories in workspace/archive/kb/) + 1.
- Copy (do NOT move — the live
workspace/kb/ must persist for the next
pass): cp -a workspace/kb/. workspace/archive/kb/kb_pass_${N}_${X_kb}/.
- Stamp state: Write
kb_snapshot_id = SNAPSHOT_ID (CUR from step
0b) into workspace/.mantis_state.json. If active_snapshot was absent
(MODE-OFF), do NOT write kb_snapshot_id and do NOT prepend any STALE
banner (the freshness gate was skipped). In HALT mode, write
kb_snapshot_id = CUR and leave the STALE banner in index.md.
- If synthesis fails or is interrupted, leave
workspace/learnings.jsonl
intact in its original location to ensure no data is lost.
- If
workspace/learnings.jsonl is ABSENT on entry (e.g. the Stage-15
invocation, because the Stage-2 invocation already archived it this pass),
skip ONLY the learnings move; STILL run the freshness gate (step 0b), stamp
the KB_SNAPSHOT markers, write kb_snapshot_id, and copy the per-pass KB
archive. KB provenance must be recorded on every invocation.
When complete, notify the user.
1---
2name: mantis-architecture
3description: >-
4 Synthesizes raw learnings and codebase analysis into an interlinked Markdown Knowledge Base (KB).
5 Use at the beginning of a loop to build or update architecture.md, entities, and vulnerabilities.
6 Don't use for generating threat models or formulating execution plans.
7metadata:
8 source: https://skillmd.com/skills/google/mantis-architecture
9---
10
11# Architect (/mantis-architecture)
12
13## System Goal
14
15Knowledge Base Synthesizer. Translates ephemeral insights from the learnings
16queue (`workspace/learnings.jsonl`) and structural analysis of the codebase into
17a canonical, interlinked Markdown Knowledge Base (`workspace/kb/`).
18
19## Command Definition
20
21- **Command:** `/mantis-architecture`
22- **Description:** Builds the foundation of the KB by defining system
23 architecture, mapping specific entities (components), and categorizing
24 historical vulnerability patterns.
25- **Arguments (all optional; resolved by LOCATOR RESOLUTION / Block A):**
26 `--snapshot_root=<dir>` (or the `SNAPSHOT_ROOT` env var) — the pinned code
27 snapshot to read target source from; `--snapshot_id=<id>` — the `SNAPSHOT_ID`
28 of that snapshot; `--state_root=<dir>` — the parent of `workspace/` for all
29 state and KB paths; `--target_root=<dir>` — an already-prepared tree that
30 OVERRIDES the snapshot (rarely passed to this stage). When none are passed,
31 behavior is byte-for-byte today's (degraded/unpinned): read source from the
32 current directory and treat `snapshot_pinned` as false.
33
34## Input/Output Contract
35
36- **Reads**:
37 - `workspace/learnings.jsonl` (raw insights from the current round).
38 - `workspace/historical_learnings.jsonl` (optional, past vulnerability
39 metadata).
40 - Codebase directory structure and key source files.
41 - Existing Markdown files in `workspace/kb/` (to validate/decay check).
42 - `workspace/.mantis_state.json` (to retrieve pass count).
43 - `workspace/.mantis_state.json` → `active_snapshot` (`root`, `snapshot_id`,
44 `snapshot_pinned`) and `snapshot_history` — provenance for the KB freshness
45 gate (step 0b). Read the snapshot from STATE ONLY; NEVER run a live VCS
46 command (`git`/`hg`/`repo`) to decide KB currency.
47 - `workspace/.mantis_state.json` → `kb_snapshot_id` (the `SNAPSHOT_ID` the
48 current KB was last built against; absent on a first/legacy KB).
49 - `workspace/.mantis_state.json` → `changed_files` and `changed_files_status`
50 (written by mantis-plan's Block E; consumed by the scoped KB invalidation in
51 step 0b outcome 3. Present from pass 2 on, but may be stale (written in a
52 prior pass) — the scoped path checks `changed_files_pass` against
53 `state.pass_number` and falls back to full rebuild if they differ.)
54- **Writes**:
55 - Markdown files under `workspace/kb/` (`architecture.md`,
56 `entities/[component_name].md`, `vulnerabilities/[CWE-ID].md`, `index.md`).
57 - `workspace/kb/dependencies.json` — a JSON map of import/dependency edges
58 extracted during architectural analysis (keys = source file paths relative
59 to CODE_ROOT; values = arrays of files that import/depend on the key file).
60 This is consumed by `mantis-plan`'s dependency-aware fan-out (Phase 2). If
61 the codebase has no parseable import structure, write `{}`. Re-derive only
62 changed entries during scoped invalidation (see outcome 3 below).
63 - Archives `workspace/learnings.jsonl` to
64 `workspace/archive/learnings/learnings_pass_${N}_${X}.jsonl`.
65 - A `<!-- KB_SNAPSHOT: <SNAPSHOT_ID> -->` marker as the FIRST line of every
66 (re)written KB file (`index.md`, each `entities/*.md`, each
67 `vulnerabilities/*.md`), plus `kb_snapshot_id` = `SNAPSHOT_ID` in
68 `workspace/.mantis_state.json`.
69 - An immutable per-pass copy of the whole KB tree to
70 `workspace/archive/kb/kb_pass_${N}_${X}/` (so a later reverted fix cannot
71 silently erase the record of what the KB claimed at pass N).
72- **Preconditions**:
73 - `workspace/learnings.jsonl` must exist.
74- **Idempotency Guarantee**:
75 - Transactional: moves `workspace/learnings.jsonl` to archive only after
76 programmatically verifying all KB Markdown updates were written
77 successfully. KB files are overwritten in-place.
78 - Snapshot stamping is part of the same transaction: the `KB_SNAPSHOT`
79 markers, the per-pass `workspace/archive/kb/kb_pass_${N}_${X_kb}/` copy, and
80 the `kb_snapshot_id` state write complete before (or together with) the
81 learnings move. On any failure, leave `workspace/learnings.jsonl` intact.
82
83## Instructions
84
85Analyze the codebase and pending learnings to construct a permanent,
86Markdown-based memory for future agents.
87
88Execute the architecture stage as follows:
89
900. **LOCATOR RESOLUTION (Block A, inlined below):**
91
92```
93LOCATOR RESOLUTION (before reading ANY target code or artifact):
940. ROLE: If this skill NEVER reads target source (report, calibrate, reflect),
95 you are a FINDINGS-ONLY stage: skip steps 2-6; still read active_snapshot from
96 state for provenance/annotation; NEVER stop merely because a code root is unset.
971. Determine CODE_ROOT, in this priority order:
98 a. If --target_root is passed on THIS invocation, CODE_ROOT = --target_root.
99 It is AUTHORITATIVE and OVERRIDES SNAPSHOT_ROOT and the state fallback
100 (used when a caller hands you a prepared tree, e.g. a patched shadow).
101 b. Else if --snapshot_root (or SNAPSHOT_ROOT) is passed, use it.
102 c. Else read state_root/workspace/.mantis_state.json (state_root from
103 --state_root if passed, else ./workspace/... relative to the current dir)
104 -> active_snapshot.root / .snapshot_id / .snapshot_pinned.
105 d. Else (no arg AND no readable active_snapshot): CODE_ROOT = current directory,
106 treat snapshot_pinned = false (MODE-OFF). Do NOT stop.
1072. SENTINEL CHECK (only if snapshot_pinned is true AND you did NOT take path 1a):
108 verify CODE_ROOT/.mantis_snapshot_id exists and equals SNAPSHOT_ID. If missing
109 or different -> STOP "snapshot sentinel mismatch". (A --target_root tree (1a) is
110 deliberately mutated and is sentinel-EXEMPT.)
1113. PATH FIELDS:
112 - SNAPSHOT-RELATIVE (read under CODE_ROOT): code_paths entries; plan target_files
113 that are file paths. Strip ONLY a trailing ":<digits>". A code_paths entry
114 containing "://" is a URL/endpoint, NOT a file read. A code_paths entry that is
115 NOT of the form <existing-path>:<integer> is a non-source LOCATOR
116 (symbol/offset/endpoint): only check that the artifact/symbol exists; skip ALL
117 line-range and line-existence logic.
118 - STATE-RELATIVE (read/write under state_root/workspace, NEVER prefix CODE_ROOT):
119 kb_references, repro_file_path, reattack_file_path, helper scripts, report
120 files, and all state/findings JSON.
1214. Never WRITE under CODE_ROOT when snapshot_pinned is true. Any command that
122 compiles, generates, or writes artifacts MUST run in a PRIVATE SHADOW copy
123 (mktemp -d from CODE_ROOT), never with cwd=CODE_ROOT. Read-only inspection may
124 cd into CODE_ROOT.
1255. VCS-METADATA CARVE-OUT: history-log extraction and any VCS diff/blame command
126 run in the LIVE repository root (which still has .git/.hg/.repo), NOT CODE_ROOT
127 (the snapshot copy strips VCS metadata). Do NOT stop merely because CODE_ROOT
128 lacks .git/.hg/.repo.
1296. Every shell command uses ABSOLUTE paths and sets its own working directory on
130 that call. Do NOT assume the working directory persists between calls.
131```
132
133This is a CODE-READING stage (steps 2 and 4 read target source), so Block A
134steps 1-6 all apply; it is NOT findings-only. Resolve `CODE_ROOT`,
135`SNAPSHOT_ID`, and `snapshot_pinned` from state BEFORE doing anything below. Per
136Block A step 3, all `workspace/kb/...` paths are STATE-RELATIVE: read and write
137them under `state_root/workspace`, NEVER under `CODE_ROOT`. Read all target
138source under `CODE_ROOT`. Do NOT run any VCS command to decide KB freshness
139(Block A step 5's carve-out is only for history/diff/blame, which this stage
140does not use).
141
1420b. **KB SNAPSHOT FRESHNESS GATE (mechanical; STATE + KB marker only, NO live
143VCS):**
144
145````
146- `CUR` = `SNAPSHOT_ID` (resolved by Block A; the empty string if
147 `active_snapshot` was absent). `PINNED` = `snapshot_pinned` (false if absent).
148- **MODE-OFF short-circuit (3-state rule):** if `active_snapshot` is ABSENT
149 in state (no `--sync` was requested — MODE-OFF = today's default), SKIP the
150 freshness gate entirely: do a best-effort build/update against `CODE_ROOT`,
151 do NOT prepend any STALE banner, and do
152 NOT stamp `kb_snapshot_id`. This is byte-for-byte today's behavior. (Only
153 HALT and PINNED run the gate below.)
154- `KB_ID` = the `kb_snapshot_id` value in `.mantis_state.json` (primary); else the
155 text after `KB_SNAPSHOT:` on the FIRST line of
156 `state_root/workspace/kb/index.md` if that file exists (secondary fallback,
157 for legacy runs without state); else `""` (no prior KB). State is primary so
158 the file-marker parsing pitfall (comment-wrapped first line, no `-->`
159 stripping) can never strand `KB_ID` with the comment closer and force BUILD
160 FRESH every pass.
161- Choose EXACTLY ONE outcome by string checks, top to bottom, first match wins:
162 1. `PINNED` is false (HALT mode — `active_snapshot` present but unpinned)
163 -> **STALE / HALT.** Do a best-effort build/update against `CODE_ROOT`,
164 but PREPEND the STALE banner (below) as the first lines of `index.md`.
165 Do NOT claim currency: leave the
166 banner in place. Set `kb_snapshot_id` = `CUR` (a `live:` id).
167 2. Else `KB_ID` == `CUR` (both non-empty) -> **CURRENT.** Do the incremental
168 update + decay-check (step 4) as today. Re-stamp `KB_SNAPSHOT: CUR` on
169 every (re)written file. REMOVE any STALE banner previously prepended to
170 `index.md`.
171 3. Else (`PINNED` true AND (`KB_ID` is empty OR `KB_ID` != `CUR`)) ->
172 **BUILD FRESH (full or scoped re-architecture).** The pinned code advanced
173 since the KB was built (a sync / pass-boundary change), OR the KB is
174 unstamped / legacy. Choose full or scoped:
175 - **Scoped invalidation (Phase 2 incremental efficiency):** If
176 `changed_files_status` is known (not UNKNOWN) AND the KB already has a
177 `KB_SNAPSHOT` stamp (KB_ID was non-empty, just different) AND
178 `changed_files_pass` equals the current `state.pass_number` (the diff
179 is from THIS pass, not a stale prior pass — absent or different →
180 treat as UNKNOWN → full rebuild below), attempt a SCOPED rebuild: only
181 invalidate KB entries whose source files are in `changed_files`, plus
182 their parent-rollup dependents (KB entities that import/reference the
183 changed files). Re-derive ONLY those entries from `CODE_ROOT`; carry
184 forward all other KB entries unchanged (they were built against the
185 same code, just a different snapshot ID). Re-stamp `KB_SNAPSHOT: CUR`
186 on every (re)written file.
187 - **Parent-rollup (2-hop, matching plan's fan-out):** When
188 invalidating a KB entry for changed file F, also invalidate any KB
189 entry that REFERENCES F directly (1-hop) AND any entry that
190 references a 1-hop dependent of F (2-hop). This matches
191 `mantis-plan`'s dependency-aware fan-out (which expands up to 2
192 hops), ensuring that a grandchild entity (H imports G, G imports
193 changed F) is not carried forward stale and later fed as a
194 `kb_reference` while its dependency has changed.
195 - **Guardrail:** If ANY uncertainty arises (can't determine which KB
196 entries map to which source files, the KB structure is ambiguous, or
197 changed_files is empty but KB_ID != CUR), fall back to full rebuild
198 below. Never carry forward a stale entry for a changed file.
199 - **Full rebuild (Phase-1 fallback):** If KB_ID is empty (no prior KB),
200 OR `changed_files_status` is UNKNOWN, OR the scoped invalidation guardrail
201 fired, REBUILD every KB file from scratch against `CODE_ROOT`. Do NOT
202 carry forward any prior assertion you have not re-derived from
203 `CODE_ROOT` this pass. Stamp `KB_SNAPSHOT: CUR`. REMOVE any STALE banner.
204- STALE banner (paste verbatim, substituting `<KB_ID>` and `<CUR>`; keep the
205 leading `>` on every line so it renders as a visible blockquote):
206
207 ```
208 > **STALE KB WARNING — do not trust without re-verifying.**
209 > snapshot_pinned=false, or the KB was built against a different snapshot.
210 > KB_SNAPSHOT=<KB_ID> does not match active_snapshot.snapshot_id=<CUR>.
211 > Every SECURE/FIXED/NON_VIABLE/SAMPLE_OR_TEST claim below is UNVERIFIED
212 > against the current code. Re-verify before trusting; do NOT filter, skip,
213 > or down-prioritize work based on this KB.
214 ```
215````
216
2171. **Read the Inbox (`workspace/learnings.jsonl` and
218 `workspace/historical_learnings.jsonl`):**
219
220 - Parse the contents of `workspace/learnings.jsonl` (and
221 `workspace/historical_learnings.jsonl` if it exists). Extract all
222 trajectory insights, discovered vulnerabilities, viable crash paths, and
223 verified patches.
224
2252. **Analyze Source Code Boundaries:**
226
227 - Examine the directory structure and key source files **under `CODE_ROOT`**
228 (the pinned snapshot resolved by Block A; use absolute paths per Block A
229 step 6, and do NOT run a VCS command). Dynamically identify the core
230 components, interfaces, and trust boundaries of the system based on the
231 repository's contents. This applies broadly across domains: whether it is a
232 software system (e.g., identifying parsers, controllers, or network
233 daemons), a hardware/RTL design (e.g., identifying IP blocks, JTAG
234 interfaces, or memory controllers), Infrastructure-as-Code (e.g.,
235 identifying cloud permissions, VPC perimeters, or deployment descriptors),
236 or data/ML pipelines (e.g., identifying data ingress points, model
237 serialization mechanisms, or training boundaries).
238
2393. **Build or Update the Knowledge Base (KB):**
240
241 - Create or update files in the `workspace/kb/` directory using standard
242 Markdown. Follow these strict paths:
243
244 - `workspace/kb/architecture.md`: High-level data flows, zone definitions,
245 system design, and overall availability/uptime requirements (if
246 documented or inferable from configuration like systemd, kubernetes, or
247 load balancers).
248 - `workspace/kb/entities/[component_name].md`: Specific definitions for
249 components (e.g., `auth_module.md`). Must include links to associated
250 vulnerability classes and document known constraints (e.g., "This module
251 sanitizes input X"). Document the component's criticality and
252 availability requirements (classify as CRITICAL, STANDARD, or
253 LOW_CRITICALITY if applicable). Incorporate trajectory insights here.
254 - `workspace/kb/vulnerabilities/[CWE-ID_or_BugClass].md`: Descriptions of
255 bug classes (e.g., `CWE-79.md` or `Memory-Corruption.md`) that have been
256 historically relevant to this codebase, including examples of what *not*
257 to do.
258 - `workspace/kb/index.md`: A root catalog containing links and 1-line
259 summaries to every file created above. This is the map the Planner will
260 read.
261
262 - **Important Formatting Rules:** Use relative links to cross-reference
263 entities and vulnerabilities (e.g.,
264 `[Auth Module](entities/auth_module.md)`). Ensure all markdown files are
265 concise and focused on actionable security context.
266
267 - **Snapshot stamping (REQUIRED on every (re)written KB file when running the
268 freshness gate, i.e. HALT or PINNED; never in MODE-OFF):** Make the FIRST
269 line of `index.md`, each `entities/*.md`, and each `vulnerabilities/*.md`
270 exactly `<!-- KB_SNAPSHOT: <SNAPSHOT_ID> -->` (substitute `CUR` from step
271 0b; it is an HTML comment so it does not render). This is how the next
272 pass's freshness gate (step 0b) detects drift. **MODE-OFF gate (3-state
273 rule):** if `active_snapshot` is ABSENT (MODE-OFF — no `--sync` was
274 requested), do NOT stamp the per-file `KB_SNAPSHOT` marker: `CUR` is the
275 empty string (`arch:145`: "the empty string if `active_snapshot` was
276 absent"), so the mandated marker would be `<!-- KB_SNAPSHOT: -->` (empty
277 value) — a snapshot-era artifact that did not exist in Phase 1. The
278 per-file marker is ONLY consumed by step 0b's freshness gate, which
279 MODE-OFF skips entirely (`arch:147-152`: "SKIP the freshness gate
280 entirely... This is byte-for-byte today's behavior. Only HALT and PINNED
281 run the gate below."). This MODE-OFF gate mirrors the freshness gate logic
282 below and step 0b's outcome clauses, which mention per-file
283 `KB_SNAPSHOT: CUR` stamping only in HALT/PINNED outcomes (CURRENT `:164`,
284 scoped BUILD FRESH `:178`, full BUILD FRESH `:195`).
285
286 - **Per-file `KB_SNAPSHOT` stamping is the sole provenance mechanism for KB
287 assertions.** Do NOT write per-assertion `(AS_OF:<snapshot>)` tags — the
288 `AS_OF` re-verification reader was never built, and staleness protection is
289 already provided by the freshness gate (step 0b) comparing `kb_snapshot_id`
290 to `SNAPSHOT_ID`, plus per-finding `discovery_commit` (enforced by
291 `mantis-critic` Block B). A later-reverted fix is caught by these
292 mechanisms, not by per-assertion tags.
293
2944. **Validate and Decay Knowledge (Drift Prevention):**
295
296 - Knowledge becomes stale when code is patched or refactored. Before
297 finalizing the KB updates, spot-check the assertions in the existing
298 `workspace/kb/entities/` against the source **under `CODE_ROOT`** (the
299 pinned snapshot — NOT a live VCS query, and NOT the live working tree). In
300 the **BUILD FRESH** outcome (step 0b) do NOT spot-check at all: discard the
301 prior assertions and re-derive every entity from `CODE_ROOT` this pass. In
302 the **STALE / HALT** outcome, spot-check only best-effort and keep the
303 STALE banner regardless of the result.
304 - If an entity file claims a variable is un-sanitized (based on an old
305 learning) but the live code now contains a sanitization function (because a
306 patch landed), **delete or correct that outdated learning** in the KB.
307 - If a learning is repeatedly proven wrong by the current trajectory
308 insights, actively correct it to prevent the "wrong learning" from
309 persisting and blinding future agents.
310 - When you correct or re-confirm a finding-derived assertion, re-stamp the
311 `KB_SNAPSHOT` marker on that KB file.
312
3135. **Transactional Inbox Clearing & Archiving:**
314
315 - To prevent infinite loops and token bloat, you must clear the queue and
316 archive the learnings.
317 - **Verify and Finalize:** Programmatically verify that all Markdown KB
318 updates were successfully written to disk and that cross-references are
319 valid. Also verify, before committing, that every (re)written KB file
320 BEGINS with its `<!-- KB_SNAPSHOT: <SNAPSHOT_ID> -->` marker and that every
321 finding-derived verdict is grounded in the current `SNAPSHOT_ID`.
322 - **Commit by Moving:** Only after verifying synthesis success, move
323 `workspace/learnings.jsonl` to the archive directory:
324 - Ensure the target directory exists (e.g.,
325 `mkdir -p workspace/archive/learnings/`).
326 - Determine the loop pass number `N` by reading `"pass_number"` from
327 `workspace/.mantis_state.json`. If missing or invalid, scan
328 `workspace/archive/` for folders matching `findings_pass_N` or
329 `loopN_findings` and resolve `N` to `max_found + 1`, defaulting to 1 if
330 no archives exist.
331 - Determine the sub-index `X` by counting existing files matching
332 `learnings_pass_${N}_*.jsonl` in `workspace/archive/learnings/` and
333 adding 1.
334 - Move the file:
335 `mv workspace/learnings.jsonl workspace/archive/learnings/learnings_pass_${N}_${X}.jsonl`.
336 - **Snapshot the KB (per-pass archive):** After a successful synthesis, copy
337 the whole KB tree to a per-pass archive:
338 - Ensure the directory exists (`mkdir -p workspace/archive/kb/`).
339 - Compute sub-index `X_kb` = (count of existing `kb_pass_${N}_*`
340 directories in `workspace/archive/kb/`) + 1.
341 - Copy (do NOT move — the live `workspace/kb/` must persist for the next
342 pass): `cp -a workspace/kb/. workspace/archive/kb/kb_pass_${N}_${X_kb}/`.
343 - **Stamp state:** Write `kb_snapshot_id` = `SNAPSHOT_ID` (`CUR` from step
344 0b) into `workspace/.mantis_state.json`. If `active_snapshot` was absent
345 (MODE-OFF), do NOT write `kb_snapshot_id` and do NOT prepend any STALE
346 banner (the freshness gate was skipped). In HALT mode, write
347 `kb_snapshot_id` = `CUR` and leave the STALE banner in `index.md`.
348 - If synthesis fails or is interrupted, leave `workspace/learnings.jsonl`
349 intact in its original location to ensure no data is lost.
350 - If `workspace/learnings.jsonl` is ABSENT on entry (e.g. the Stage-15
351 invocation, because the Stage-2 invocation already archived it this pass),
352 skip ONLY the learnings move; STILL run the freshness gate (step 0b), stamp
353 the `KB_SNAPSHOT` markers, write `kb_snapshot_id`, and copy the per-pass KB
354 archive. KB provenance must be recorded on every invocation.
355
356When complete, notify the user.