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

--snapshotroot=<dir> (or the SNAPSHOTROOT env var) — the pinned code snapshot to read target source from; --snapshotid=<id> — the SNAPSHOTID of that snapshot; --stateroot=<dir> — the parent of workspace/ for all state and KB paths; --targetroot=<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/historicallearnings.jsonl (optional, past vulnerability metadata). - Codebase directory structure and key source files. - Existing Markdown files in workspace/kb/ (to validate/decay check). - workspace/.mantisstate.json (to retrieve pass count). - workspace/.mantisstate.json → activesnapshot (root, snapshotid, snapshotpinned) and snapshothistory — 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/.mantisstate.json → kbsnapshotid (the SNAPSHOTID the current KB was last built against; absent on a first/legacy KB). - workspace/.mantisstate.json → changedfiles and changedfilesstatus (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 changedfilespass against state.passnumber and falls back to full rebuild if they differ.)

• Writes:

- Markdown files under workspace/kb/ (architecture.md, entities/[componentname].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 CODEROOT; 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/learningspass${N}${X}.jsonl. - A <!-- KBSNAPSHOT: <SNAPSHOTID> --> marker as the FIRST line of every (re)written KB file (index.md, each entities/.md, each vulnerabilities/.md), plus kbsnapshotid = SNAPSHOTID in workspace/.mantisstate.json. - An immutable per-pass copy of the whole KB tree to workspace/archive/kb/kbpass${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 KBSNAPSHOT markers, the per-pass workspace/archive/kb/kbpass${N}${Xkb}/ copy, and the kbsnapshot_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:

1. 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 CODEROOT, SNAPSHOTID, and snapshotpinned from state BEFORE doing anything below. Per Block A step 3, all workspace/kb/... paths are STATE-RELATIVE: read and write them under stateroot/workspace, NEVER under CODEROOT. Read all target source under CODEROOT. 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

activesnapshot was absent). PINNED = snapshotpinned (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 CODEROOT, do NOT prepend any STALE banner, and do NOT stamp kbsnapshot_id. This is byte-for-byte today's behavior. (Only HALT and PINNED run the gate below.)

• KBID = the kbsnapshotid value in .mantisstate.json (primary); else the

text after KBSNAPSHOT: on the FIRST line of stateroot/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 — activesnapshot present but unpinned) -> STALE / HALT. Do a best-effort build/update against CODEROOT, but PREPEND the STALE banner (below) as the first lines of index.md. Do NOT claim currency: leave the banner in place. Set kbsnapshotid = CUR (a live: id). 2. Else KBID == CUR (both non-empty) -> CURRENT. Do the incremental update + decay-check (step 4) as today. Re-stamp KBSNAPSHOT: CUR on every (re)written file. REMOVE any STALE banner previously prepended to index.md. 3. Else (PINNED true AND (KBID is empty OR KBID != 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 changedfilesstatus is known (not UNKNOWN) AND the KB already has a KBSNAPSHOT stamp (KBID was non-empty, just different) AND changedfilespass equals the current state.passnumber (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 changedfiles, plus their parent-rollup dependents (KB entities that import/reference the changed files). Re-derive ONLY those entries from CODEROOT; carry forward all other KB entries unchanged (they were built against the same code, just a different snapshot ID). Re-stamp KBSNAPSHOT: 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 kbreference 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 changedfiles is empty but KBID != CUR), fall back to full rebuild below. Never carry forward a stale entry for a changed file. - Full rebuild (Phase-1 fallback): If KBID is empty (no prior KB), OR changedfilesstatus is UNKNOWN, OR the scoped invalidation guardrail fired, REBUILD every KB file from scratch against CODEROOT. Do NOT carry forward any prior assertion you have not re-derived from CODEROOT 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. > snapshotpinned=false, or the KB was built against a different snapshot. > KBSNAPSHOT=<KBID> does not match activesnapshot.snapshotid=<CUR>. > Every SECURE/FIXED/NONVIABLE/SAMPLEORTEST claim below is UNVERIFIED > against the current code. Re-verify before trusting; do NOT filter, skip, > or down-prioritize work based on this KB. ` ```

1. **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.

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

1. 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/[componentname].md: Specific definitions for components (e.g., authmodule.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 LOWCRITICALITY if applicable). Incorporate trajectory insights here. - workspace/kb/vulnerabilities/[CWE-IDor_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 <!-- KBSNAPSHOT: <SNAPSHOTID> --> (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 activesnapshot is ABSENT (MODE-OFF — no --sync was requested), do NOT stamp the per-file KBSNAPSHOT marker: CUR is the empty string (arch:145: "the empty string if activesnapshot was absent"), so the mandated marker would be <!-- KBSNAPSHOT: --> (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 KBSNAPSHOT stamping is the sole provenance mechanism for KB assertions. Do NOT write per-assertion (ASOF:<snapshot>) tags — the ASOF re-verification reader was never built, and staleness protection is already provided by the freshness gate (step 0b) comparing kbsnapshotid to SNAPSHOTID, 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.

1. 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 CODEROOT (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 CODEROOT 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.

1. 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 <!-- KBSNAPSHOT: <SNAPSHOTID> --> marker and that every finding-derived verdict is grounded in the current SNAPSHOTID. - 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 "passnumber" from workspace/.mantisstate.json. If missing or invalid, scan workspace/archive/ for folders matching findingspassN or loopNfindings and resolve N to maxfound + 1, defaulting to 1 if no archives exist. - Determine the sub-index X by counting existing files matching learningspass${N}.jsonl in workspace/archive/learnings/ and adding 1. - Move the file: mv workspace/learnings.jsonl workspace/archive/learnings/learningspass${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 Xkb = (count of existing kbpass${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/kbpass${N}${Xkb}/. - Stamp state: Write kbsnapshotid = SNAPSHOTID (CUR from step 0b) into workspace/.mantisstate.json. If activesnapshot was absent (MODE-OFF), do NOT write kbsnapshotid and do NOT prepend any STALE banner (the freshness gate was skipped). In HALT mode, write kbsnapshotid = 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 KBSNAPSHOT markers, write kbsnapshot_id, and copy the per-pass KB archive. KB provenance must be recorded on every invocation.

When complete, notify the user.