codecartographer

CodeCartographer is a framework for understanding an unfamiliar codebase with an AI coding agent and producing a validated, language-agnostic reimplementation spec. It is distributed as a Pi extension, an MCP server, or a drop-in `.codecarto/` template of Markdown and YAML files. How it works: the "code" is structured Markdown plus YAML inside `.codecarto/`. `GUIDE.md` is the LLM entry point, `workflow/pipeline.yaml` defines phases and dependencies, `workflow/status.yaml` holds mutable per-project state, and `workflow/VALIDATE.md` describes the validation protocol. Phases form a DAG — contracts and protocols can run in parallel after architecture, porting waits for both, and the reimplementation spec is last. The host reads the active pipeline, finds the next phase whose dependencies are complete, hands the LLM that phase's instructions, validates the output, and advances status. Evidence and validation: each phase writes a smaller, templated, evidence-tagged artifact under `.codecarto/findings/`, and later phases re-read the specific upstream files they need. Findings are tagged as observed fact, strong inference, portability hazard, external-behavior claim, or open question. Every phase output ends with a `## Validation` table marking each completion criterion PASS, PARTIAL, or FAIL with evidence; validation parses that table and cross-checks evidence/action pairing and declared secondary outputs, refusing to advance on a FAIL, a missing output, or an unreadable verdict. Artifacts produced include an architecture map, defect report, defect fix tracker, behavioral contracts, protocols and state, a porting bundle, and the final reimplementation spec with modules, acceptance scenarios, and known unknowns. Pipeline variants: the default is a 7-phase deep-audit run that splits the defect scan into mechanical and semantic passes. Other variants include scout-first (8 phases), full-with-audit (6), full (5), defect scan (2), lite (3), architecture-only (1), and synthesis (4). Variants can be switched in place without deleting findings or progress. Context resilience: the filesystem, not the conversation, is the durable memory. Each phase gets a fresh context window; completed findings live on disk; `status.yaml` records progress, open questions, carry-forward items, and a post-pipeline backlog. Pi phase transcripts are file-backed and remain available through `/resume`, `/tree`, and `/export`. Phase-aware compaction summaries are checkpointed under `.codecarto/scratch/checkpoints/`. The README notes that intra-phase context pressure is bounded rather than eliminated. Surfaces and features: the Pi extension adds slash commands, a live agents widget, file-backed phase sessions, phase-completion summaries, opt-in LLM-steered seed prompts, per-phase usage tracking, and tool interception (bash blocked; edit/write confined to `.codecarto/`). The MCP server exposes phase prompts, validation, and experimental library publish/list/reindex operations for other MCP-capable agents. A single-file HTML dashboard aggregates progress, links, usage, and an optional narrative summary. Forward synthesis combines a product vision with human-confirmed library specs into a provenance-backed project plan, with runtime preflight checks requiring explicit human confirmation before merging or finalization.