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.