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:

0. 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.
  ```

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.

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

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

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

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