Mantis Architecture

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:

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