A tour of every piece: pipeline variants, evidence classification, phase-gating, cross-session continuity, and the output artifacts you end up with.
Six analysis variants scale from quick orientation to a deep audit. The forward synthesis pipeline combines a vision with confirmed reusable specs to create a traceable project plan.
7 phases
Complete analysis with a two-pass defect scan. An early mechanical sweep catches surface-level issues; a later semantic pass re-examines defects with full contracts and protocols context before reimplementation planning.
The default pipeline. Best when you need the deepest defect analysis grounded in full behavioral understanding.
Two directions: analysis distills source code into reusable specifications; synthesis combines human-confirmed specifications with a product vision and preserves decision-level provenance in the resulting plan.
An LLM can sound certain about things it inferred. CodeCartographer requires every finding to carry an evidence tag so you know what was observed, what was deduced, and what remains an open question.
Directly visible in source code or documentation. Not inferred.
Deduced from patterns and structure. High confidence but not directly stated.
Behavior or assumption that may not survive a rewrite or language change.
Could not determine from available sources. Needs human input or deeper analysis.
If an LLM cannot classify a finding with one of these four tags, the finding is not specific enough to be useful. Vague assertions get rejected by the validation protocol.
Each phase produces a structured output against a template. The validation protocol checks
completion criteria: are all required sections present, are findings tagged with evidence
levels, are open questions logged in status.yaml.
templates/
Structured Markdown templates enforce consistent sections across projects and sessions. Every artifact has the same shape regardless of which LLM produced it.
VALIDATE.md
Run after every phase. Checks that outputs match templates, evidence tags are applied, and partial results are logged properly before allowing the status to advance.
CodeCartographer does not ask one context window to remember the entire investigation. Each phase turns a large body of source evidence into a smaller, more task-specific artifact that downstream phases can read and validate.
Evidence-tagged distillation
This is deliberate distillation, not incidental chat summarization. Templates, evidence labels, open questions, and validation gates reduce the risk of an unsupported claim becoming “fact” as information moves downstream.
Each phase gets a fresh context window and re-reads the upstream findings declared by the pipeline. Progress, open questions, carry-forward items, decisions, and closeouts live under .codecarto/ rather than only in the conversation.
Compaction inside one oversized phase can still be lossy. When full coverage will not fit, the phase records PARTIAL validation and routes unresolved work through open_questions or carry_forward instead of hiding the gap.
Practical result: compacting or replacing the orchestrator session does not erase pipeline progress. The next host session can reopen the durable state and continue; Pi users run /codecarto-open to attach without resetting it.
Large codebases need multiple sessions. status.yaml is the single source of
truth. After the host opens the workspace, the new session reads the guide, checks the status
file, sees what is complete, and starts the next eligible phase. No explaining what happened before.
status.yamlMutable per-project state. Tracks phase completion, current phase, open questions, carry-forward work, and the active pipeline.
THREAD_LOG.mdAppend-only index pointing to per-session closeout files. Durable findings stay in phase outputs and closeouts; the log gives new sessions a compact route into that evidence without becoming a second summary store.
In the Pi extension, /codecarto-open safely activates existing state in a fresh
orchestrator session. Phase sub-agents persist transcripts alongside that session.
/resume, /tree, and /export browse them as
first-class sessions with lineage back to the orchestrator.
It is better described as progressive, evidence-tagged distillation. Each phase produces a purpose-built artifact with templates, evidence levels, known unknowns, and a validation gate before downstream phases use it.
Cross-phase state is reconstructed from files under .codecarto/, so compacting or replacing the orchestrator does not erase progress. Pi phase compaction now uses a phase-aware continuation summary, writes scratch/checkpoints/<phase>.md, and records compaction outcomes in local usage telemetry. The summary is still lossy, so material gaps remain explicit as PARTIAL, open_questions, or carry_forward.
The Pi extension automatically runs phases in isolated, file-backed sessions and applies phase-aware compaction only to sessions named CodeCartographer phase: <id>. An MCP host controls its own LLM sessions and compaction, so it should dispatch one fresh session per phase. The MCP server itself does not run an agent.
Drop-in mode uses the same durable files and phase protocol, but isolation is procedural rather than enforced. Start each phase in a fresh session, read the declared upstream artifacts, and preserve unresolved work on disk.
No. The porting bundle is the final intentional compression boundary. Its source index carries load-bearing claims, defect dispositions, coverage gaps, and deep-read triggers. Final synthesis opens lower-level findings only for a named gap, conflict, missing acceptance detail, or defect rationale.
Every phase has a Coverage and limits section naming inspected scope, skipped scope, evidence basis, and blind spots. Material gaps produce PARTIAL validation and remain visible in open_questions or carry_forward.
Each artifact targets a different audience: engineers, reviewers, maintainers, and the next LLM session.
Layers, public surfaces, runtime lifecycle, dependency direction, porting priorities.
Multi-pass scan: logic, error handling, concurrency, security, API drift, config risks.
User-visible behavior, defaults, side effects, error modes, black-box acceptance checks.
Events, state machines, persistence notes, compatibility hazards, internal message flow.
Synthesis layer ranking what matters, what is risky, what needs special treatment in a rewrite.
Language-agnostic build plan with modules, acceptance scenarios, and known unknowns.
Read the installation docs for drop-in setup, Pi extension commands, or MCP server configuration.