codecartographer-pi 0.13.0 → 0.14.0

package/.codecarto/workflow/scaffold-version.yaml

@@ -3,4 +3,4 @@
 # workspace's framework-owned files (GUIDE.md, templates/, workflow/ pipelines
 # and VALIDATE.md) predate the running release. Written at release time and
 # copied verbatim by init — never edit by hand.
-scaffold_version: 0.13.0
+scaffold_version: 0.14.0

package/README.md

@@ -92,6 +92,8 @@ Use this when your coding agent isn't Pi — Claude Code, Codex, opencode, Curso
 
 > **30-second setup for Claude Code, Cursor, Codex, and Claude Desktop: see the [MCP quickstart](docs/mcp-quickstart.md).**
 
+> **Teaching an agent to drive it:** call the `codecarto_guide` tool — the server returns the full drive loop, the phase-handoff contract, executor selection, and recovery patterns, with nothing to install. The same content ships as an installable skill at `agent-skill/codecartographer/` for agents that load skills from disk.
+
 ```bash
 npm install --global codecartographer-pi
 ```

package/agent-skill/codecartographer/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: codecartographer
+description: Drive the CodeCartographer MCP server to reverse-engineer a repository or synthesize a new project through validated analysis phases. Use when asked to run CodeCartographer, analyze or reverse-engineer a codebase, produce architecture/contracts/protocols/defect/porting/reimplementation artifacts, or operate a .codecarto/ workspace.
+version: 1.0.0
+license: MIT
+---
+
+# Driving CodeCartographer
+
+CodeCartographer is a pipeline state machine, not an agent. It hands you a phase prompt, checks the artifact you produce against that phase's criteria, and gates completion. **It never reads your repository and never writes your findings** — you do that.
+
+Three roles, and you hold two of them:
+
+| Role | Who | Does |
+|---|---|---|
+| State machine | the MCP server | phase order, prompts, validation parsing, completion gate, canonical state |
+| Orchestrator | you | pick the pipeline, drive the loop, choose an executor, verify |
+| Executor | you, or a model you delegate to | read the repo, write the phase artifact |
+
+## The drive loop
+
+```
+codecarto_status  →  codecarto_init (first time only)
+                          ↓
+        ┌──────── codecarto_next ────────┐
+        │              ↓                  │
+        │         execute the phase       │
+        │       (write primary output)    │
+        │              ↓                  │
+        │      write the phase handoff    │
+        │              ↓                  │
+        │       codecarto_validate        │
+        │              ↓                  │
+        │       codecarto_complete        │
+        └───────── repeat until ──────────┘
+             status reports "complete"
+```
+
+1. **`codecarto_status`** — always start here. It reports the active pipeline, progress, next action, and any scaffold-staleness warning. Every tool takes an absolute `cwd` pointing at the target repository.
+2. **`codecarto_init`** — only when no `.codecarto/` exists. Choose the pipeline deliberately (see `references/pipeline-selection.md`). Never pass `force: true` without the user's explicit approval; it moves an existing workspace, findings and all, to a backup directory.
+3. **`codecarto_next`** — returns the prompt for the next eligible phase. It returns *text*; it does not execute anything. Use `codecarto_phase` only to force a specific phase out of order, and only when the user asked for that.
+4. **Execute** — see "Executing a phase" below.
+5. **Write the handoff** — see "The handoff contract" below. This is the step integrations most often miss, and completion now refuses without it.
+6. **`codecarto_validate`** — parses the validation block you appended to the primary output. Returns `PASS`, `PASS WITH GAPS`, `FAIL`, or `MISSING`.
+7. **`codecarto_complete`** — marks the phase done, applies your handoff to canonical state, and writes the closeout and `THREAD_LOG.md` entry. It refuses anything worse than `PASS WITH GAPS`.
+
+When `codecarto_status` reports all phases complete, post-pipeline skills become available via `codecarto_list_skills` and `codecarto_skill`.
+
+## The handoff contract
+
+Since v0.12.0 the framework owns `workflow/status.yaml`, `closeouts/`, and `THREAD_LOG.md`. **Never write those files.** A session proposes state changes in one file:
+
+```
+.codecarto/scratch/handoffs/<phase-id>.yaml
+```
+
+```yaml
+schema_version: 1
+phase_id: architecture
+owner_notes:
+  - Mapped 14 packages across 3 layers.
+open_questions: []
+carry_forward:
+  - id: arch-CF2
+    kind: defer-to-phase
+    target_phase: protocols
+    description: MCP endpoints listed by name only; schemas not extracted.
+    deferred_reason: Wire-format extraction is the protocols phase's rubric.
+closeout_summary: Architecture mapped; wire formats deferred to protocols.
+```
+
+Omitted arrays default to empty. `phase_id` must match the phase exactly. `carry_forward` targets must be a *later* phase in the active pipeline — anything else belongs in `post_pipeline`. Full schema and closure semantics: `references/handoff-contract.md`.
+
+Two failure modes worth naming, because both have happened in the field:
+
+- **No handoff written.** Completion fails with an error naming the expected path. Earlier versions completed silently with empty state, which severed cross-phase routing for an entire run without a trace.
+- **Routing described but not performed.** Writing "routed to the semantic phase" in your report's prose table does *not* route anything. The handoff entry is the routing; the table documents it.
+
+## Executing a phase
+
+A phase executor takes the prompt from `codecarto_next` plus the repository path, and must:
+
+1. read the repository (or, for late synthesis phases, the prior `findings/` artifacts);
+2. write the exact primary output path the prompt names;
+3. append a validation block whose last line is `**Overall:** PASS` or `**Overall:** PASS WITH GAPS`;
+4. write the phase handoff;
+5. touch nothing outside `.codecarto/`.
+
+Anything satisfying that contract works. Choose per phase, by weight and context budget rather than by brand — see `references/executors.md` for adapters (running it in your own context, delegating to a CLI agent, using local models for scoped pre-passes) and for the concrete selection rules.
+
+The short version: use the strongest model available for synthesis phases (`porting`, `reimplementation-spec`) where reasoning quality drives the artifact's value, delegate the wide repository reads to whatever has the largest usable context, and reserve small local models for narrow, verifiable pre-passes whose output you treat as evidence rather than as findings.
+
+## Validation gates
+
+| Result | Meaning | Do |
+|---|---|---|
+| `PASS` | every criterion satisfied | complete |
+| `PASS WITH GAPS` | some criterion PARTIAL, gaps documented | complete only if the gaps are acceptable for the user's goal; the gaps must be tracked in the handoff |
+| `FAIL` | a criterion is unmet | fix the artifact, re-validate; completion will refuse |
+| `MISSING` | primary output or validation block absent | the executor did not finish; see `references/phase-recovery.md` |
+
+A PARTIAL row's evidence must name what is missing and which `open_questions` or `carry_forward` entry tracks it — and that entry must exist in the handoff, not only in the prose.
+
+## Verify before reporting success
+
+- `codecarto_validate` returned `PASS` or an accepted `PASS WITH GAPS`
+- `codecarto_complete` succeeded
+- the primary output file exists and is non-trivial
+- `codecarto_status` shows the expected progress and next action
+- if you delegated, the executor's own result reports success — do not infer it from exit code alone
+
+## Pitfalls
+
+- `codecarto_next` returns a prompt. Something still has to *do* the phase.
+- Never hand-edit `workflow/status.yaml`, append `THREAD_LOG.md`, or write a second closeout. Propose through the handoff.
+- Do not force phases out of DAG order unless the user asked.
+- If `codecarto_status` reports a scaffold-staleness warning, refresh the workspace's framework-owned files before trusting anything written inside `.codecarto/`; a stale scaffold's `GUIDE.md` can contradict this contract.
+- A delegated run that times out may still have written its artifact. Check for the file and validate before retrying.
+- The drop-in `.codecarto/` template works without MCP, but the server is preferred: it owns atomic state updates, validation parsing, and the completion gate.
+
+## When the run drives a rewrite
+
+If the goal is to rebuild or refactor rather than to understand, two phases carry that weight and both have their own reference:
+
+- the defect scans feed `porting` and `reimplementation-spec` as inputs, not as an appendix — `references/deep-audit-synthesis.md`;
+- the spec should describe the least error-prone build order, not a clone — `references/kernel-first-rewrite.md`.
+
+## References
+
+Running the pipeline:
+
+- `references/pipeline-selection.md` — choosing a variant, and switching without losing work
+- `references/executors.md` — the executor contract, adapters, and model selection
+- `references/handoff-contract.md` — full handoff schema, routing, and closure semantics
+- `references/phase-recovery.md` — stalled, interrupted, and failed phase runs
+
+Using what it produces:
+
+- `references/deep-audit-synthesis.md` — defect dispositions, hazards as normative rules, reporting
+- `references/kernel-first-rewrite.md` — rings, build order, acceptance harness, strategic assumptions
+- `references/carrying-results-forward.md` — starting implementation, autonomy boundaries, publishing findings
+
+This guide is also served by the `codecarto_guide` MCP tool, so an agent with the server configured can read it without installing anything.

package/agent-skill/codecartographer/references/carrying-results-forward.md

@@ -0,0 +1,53 @@
+# After the pipeline completes
+
+Two things usually follow a finished run: someone starts implementing, and the findings need a home outside the analysed repository.
+
+## Starting implementation
+
+When a completed `reimplementation-spec` is the input to real work rather than more analysis:
+
+1. **Read the spec first and treat it as the contract.** Not the source repository, and not the architecture map — the spec is what later disagreements resolve against.
+2. **Inspect the target repository's actual stack before choosing a layout.** Its project and build files, whether the existing test suite currently compiles, and its root build configuration. A layout chosen before this is a layout that gets redone.
+3. **Prefer a non-destructive adjacent module** when the existing product is large or defect-prone: leave the legacy code untouched, add a small kernel module beside it with its own focused test project, and wire it into the workspace only once the layout is settled.
+4. **Write acceptance tests against fakes before touching real providers, UI, or adapters** — see `kernel-first-rewrite.md`.
+5. **Isolate new tests when the legacy suite is unrelatedly broken.** A filtered run often still compiles the whole legacy assembly and surfaces failures that have nothing to do with the new work. Do not expand into repairing the legacy suite unless the user asked for that scope.
+6. **Carry the "do not clone" hazards through as test names**, so the reason a rule exists survives into the code.
+
+## Autonomy boundaries
+
+If implementation will proceed while the user is away, settle the boundary before they go: whether work may edit code, run tests, commit, and push. Prefer scoping permission to the specific worker over disabling approvals globally, and exclude force-pushes, history rewrites, unrelated destructive changes, and anything touching secrets.
+
+Verify independently after any autonomous run reports success — check the repository state yourself, run the tests yourself, confirm generated and workflow-state files are untracked, and inspect the commit scope. Report exact commit hashes and test counts rather than a claim of success.
+
+## Publishing findings into a product repository
+
+When the results should inform a *new* repository, publish a curated snapshot rather than the raw workspace, which is noisy and carries executable workflow state:
+
+```text
+docs/codecarto/
+  README.md
+  architecture-map.md
+  behavioral-contracts.md
+  protocols-and-state.md
+  mechanical-defects.md
+  semantic-defects.md
+  reverse-engineering-bundle.md
+  reimplementation-spec.md
+```
+
+The README should say that these are curated audit outputs from the source repository, that `reimplementation-spec.md` is the canonical implementation contract, and — when true — that the new product is a ground-up rework rather than a source-level port.
+
+Keep the workspace itself untracked in the new repository:
+
+```gitignore
+.codecarto/
+.codecarto-backup-*/
+```
+
+Before publishing, confirm the tests pass and that neither the workspace nor build output is tracked:
+
+```bash
+git ls-files | grep -E '^\.codecarto' || echo "clean"
+```
+
+Default to this curated shape. Copy the raw `.codecarto/` workspace across only when the user explicitly wants executable workflow state in the new repository — for example, to continue the pipeline there.

package/agent-skill/codecartographer/references/deep-audit-synthesis.md

@@ -0,0 +1,54 @@
+# Turning a deep audit into rewrite guidance
+
+Use this when the run exists to decide *how to rebuild or refactor* something, not merely to describe it. It assumes a pipeline with defect scans — `full-with-audit` or `full-with-deep-audit`.
+
+If the user expected defect findings and none appeared, check the active variant first: `full` has no defect phases at all.
+
+## Defect scans are contract inputs, not an appendix
+
+The common failure is treating defect reports as a separate document that the porting and spec phases summarize politely and move past. They are inputs to those phases' actual decisions. Every defect should reach the porting bundle carrying an explicit disposition:
+
+| Disposition | Means | Consequence for the port |
+|---|---|---|
+| `fix before porting` | the defect would be reproduced by a faithful port | design it out; the spec states the correct behavior |
+| `port differently` | the behavior is needed but the mechanism is wrong | spec the intent, not the implementation |
+| `leave behind` | dead, vestigial, or actively harmful | name it explicitly so a later reader doesn't "restore" it |
+
+Add the acceptance-test implication alongside each row. A hazard with no test in the spec will be reintroduced by whoever implements it.
+
+Close a carry-forward item only once its guidance is represented in an artifact a later phase actually consumes — not merely mentioned in the phase that raised it.
+
+## Convert hazards into normative rules
+
+In the final spec, a defect becomes a rule plus a black-box scenario. "The old code had a race in session writes" is an observation; "session writes MUST be atomic: temp file, fsync, same-filesystem rename, sidecars after the primary file — verified by a crash-injection test" is a contract.
+
+Hazards worth checking for in agent-like or CLI tools, drawn from real deep-audit runs. Treat as prompts, not a checklist to assert blindly:
+
+- non-atomic session, checkpoint, or index writes
+- record parsing that keys on substring detection rather than a schema discriminator
+- JSON-RPC responses not correlated by `id`, so an out-of-order reply satisfies the wrong request
+- subprocess `stdout`/`stderr` piped but not drained concurrently, deadlocking on a full pipe
+- timeouts that log but never kill the process tree
+- shell interpolation of externally supplied variables in hook or plugin execution
+- background process features with no ownership, cleanup, readiness, or recovery semantics
+- config validation that cannot distinguish an absent value from an explicit zero, or that skips range checks
+- config fields parsed and then never read — each needs an implement / remove / deprecate decision
+- permission checks bypassed by a second read path that loses provenance
+- stream reducers that early-`continue` after one field kind and silently drop others in the same event
+
+## Preserve behavior, not bugs
+
+Preserve observable behavior as tests and contracts. Do not clone an accidental bug unless something external depends on it — and when it does, say so explicitly and mark it as compatibility-significant rather than letting it look like good design.
+
+## Reporting
+
+Separate these when reporting, and lead with the recommendation rather than the narrative:
+
+- what the pipeline completed and validated
+- the high-signal defects that actually shape the rewrite
+- the recommended build sequence
+- what must be preserved exactly
+- what to fix rather than copy
+- what remains open
+
+See `kernel-first-rewrite.md` for the build sequence this feeds.

package/agent-skill/codecartographer/references/executors.md

@@ -0,0 +1,75 @@
+# Phase executors
+
+CodeCartographer does not run models. Any executor that satisfies the contract below can run a phase, so pick per phase rather than committing to one tool for a whole pipeline.
+
+## The executor contract
+
+Given the prompt text from `codecarto_next` and the absolute repository path, an executor must:
+
+1. read the repository — or, for late synthesis phases, the prior `.codecarto/findings/` artifacts rather than the source tree;
+2. write the exact primary output path the prompt names;
+3. append a validation block whose final line is `**Overall:** PASS` or `**Overall:** PASS WITH GAPS`;
+4. write `.codecarto/scratch/handoffs/<phase-id>.yaml`;
+5. modify nothing outside `.codecarto/`.
+
+Anything meeting all five works. Nothing else about the executor matters to the framework.
+
+## Choosing one
+
+Two properties decide it: how much repository the phase must read, and how much reasoning quality changes the artifact's worth.
+
+| Phase | Reads | Reasoning weight | Typical choice |
+|---|---|---|---|
+| `architecture` | wide — whole tree | moderate | largest usable context |
+| `contracts`, `protocols` | wide, but guided by architecture | high | strong model, large context |
+| `defect-scan-*` | wide, pattern-driven | high for semantic, moderate for mechanical | strong model; mechanical tolerates a cheaper one |
+| `porting`, `reimplementation-spec` | narrow — prior findings only | highest | the strongest model available, always |
+| `vision-capture`, `goal-synthesis-*` | narrow — vision brief and library | high | strong model |
+
+Two rules that matter more than any specific product:
+
+- **Synthesis phases deserve your best model.** `porting` and `reimplementation-spec` read almost nothing new; their entire value is the quality of the reasoning over prior findings. Saving tokens there is a false economy — that artifact is what someone builds from.
+- **Wide-read phases deserve your largest usable context**, because the binding constraint is how much of the tree fits before the executor starts guessing.
+
+Prefer whatever is strongest and largest among what the user actually has configured. Ask if it is unclear which models are available rather than assuming a particular vendor.
+
+## Adapter: run it in your own context
+
+Simplest and usually correct for small and mid-size repositories. Take the prompt from `codecarto_next` and follow it with your own file, search, and edit tools.
+
+Choose this when the repository fits comfortably in your context, when the phase is a synthesis phase reading only prior findings, or when you want to interleave judgment with the user.
+
+## Adapter: delegate to a CLI coding agent
+
+Right when the phase would consume more context than you want to spend, or when you want the phase isolated from the orchestration conversation.
+
+Pass the prompt through a file rather than inline — phase prompts contain backticks, quotes, and newlines that mangle badly in shell quoting:
+
+```bash
+# Write the prompt from codecarto_next to a file first, then:
+<agent-cli> --prompt-file /tmp/codecarto-phase.md --workdir /abs/path/to/repo
+```
+
+Whatever CLI you use:
+
+- set the working directory to the target repository;
+- grant read, write, edit, and search tools; grant shell access only if the phase needs it;
+- request structured output if available, so success is machine-checkable rather than inferred;
+- for long phases, run in the background with a completion signal instead of blocking indefinitely;
+- afterwards, confirm the primary output exists and inspect the executor's own success report — a zero exit code is not evidence the artifact was written.
+
+## Adapter: local or small models for scoped pre-passes
+
+Useful for saving context, but only in a specific shape: narrow, verifiable summaries of one subsystem at a time.
+
+- Generate per-subsystem notes, never whole-repository analysis.
+- Write them under `.codecarto/scratch/` as supporting evidence. Primary outputs still live in `findings/` and still have to pass validation.
+- Feed the notes to the phase executor as *auxiliary evidence*, and tell it explicitly not to re-run the pre-pass.
+- Treat the output as hints to verify, never as findings. A local model's claim about the code is a lead; the phase artifact needs the evidence level to match what was actually confirmed.
+- If a large local model fails on memory, drop to a smaller one and narrow the scope. The lesson is "scope the notes smaller," not "local models don't work."
+
+## Mixing executors across one pipeline
+
+Normal and often optimal: a cheap wide pass for `architecture`, a strong model for `contracts` and the semantic defect scan, your best for `reimplementation-spec`. The framework neither knows nor cares — each phase is validated on its artifact alone.
+
+Keep one thing consistent regardless of executor: every phase writes its handoff. A mixed pipeline where one executor forgets is exactly how cross-phase routing goes missing.

package/agent-skill/codecartographer/references/handoff-contract.md

@@ -0,0 +1,80 @@
+# The phase handoff
+
+Every phase proposes its state changes in one file, which completion validates and applies atomically:
+
+```
+.codecarto/scratch/handoffs/<phase-id>.yaml
+```
+
+The framework owns `workflow/status.yaml`, `closeouts/`, and `THREAD_LOG.md`, and owns all canonical timestamps. A session never writes them.
+
+## Schema (version 1)
+
+```yaml
+schema_version: 1
+phase_id: architecture          # must match the phase exactly
+owner_notes: []                 # 2-3 durable observations; appended to the phase's notes
+open_questions: []              # genuinely unknown, no later phase will close them
+carry_forward: []               # deferred to a specific later phase in this pipeline
+carry_forward_closures: []      # ids of carry_forward entries this phase resolved
+open_question_closures: []      # ids of open questions this phase resolved, removed everywhere
+post_pipeline: []               # work after the pipeline; every entry needs a stable id
+decisions: []                   # choices made beyond what the prompt specified
+closeout_summary: ""            # one clause, ~20 words; becomes the THREAD_LOG entry
+closeout_content: |-            # optional full closeout markdown
+  # Closeout — architecture
+```
+
+Omitted arrays default to empty. A malformed collection fails completion without mutating anything.
+
+`.codecarto/templates/phase-handoff.yaml` in the workspace is a copyable skeleton.
+
+## Entry shapes
+
+`open_questions` entries:
+
+```yaml
+- id: q-loadconfig-ambiguity      # stable; auto-assigned if omitted
+  kind: needs-runtime-test
+  description: loadConfig returns {} on both ENOENT and parse error.
+  deferred_reason: Distinguishing them needs a runtime probe this phase cannot run.
+```
+
+`carry_forward` entries add `target_phase`:
+
+```yaml
+- id: arch-CF2
+  kind: defer-to-phase
+  target_phase: protocols
+  description: MCP endpoints listed by name only; schemas not extracted.
+  deferred_reason: Wire-format extraction is the protocols phase's rubric.
+```
+
+Allowed `kind` values: `needs-runtime-test`, `needs-maintainer-decision`, `needs-spec-ruling`, `defer-to-phase`, `needs-fixture-capture`.
+
+## Open question or carry-forward?
+
+- **`open_questions`** — nobody in this pipeline will resolve it. It needs a runtime test, a maintainer decision, or a spec ruling. It survives to the end as a known unknown.
+- **`carry_forward`** — a specific later phase's rubric is the right place to close it. It is a routing, and it must name a real downstream phase.
+
+`carry_forward` targets are validated: the target must exist in the active pipeline and come *after* the current phase. A target that is earlier, equal, or absent fails completion. Work that belongs after the pipeline goes in `post_pipeline` instead.
+
+## Closing routed items
+
+A later phase receives routed items in its phase prompt. To close one:
+
+1. address it in that phase's output;
+2. list its id under `carry_forward_closures` in that phase's handoff.
+
+Completion then removes the entry atomically. Resolving an open question works the same way through `open_question_closures`, which removes the id from every phase that raised it.
+
+Re-deferring instead of closing means writing a fresh `carry_forward` entry naming a later `target_phase`.
+
+## The failure this prevents
+
+Before completion required a handoff, a phase could finish with empty state and no signal. A real seven-phase run documented five cross-phase routings in its report prose, wrote no handoffs, and completed all seven phases with `carry_forward: []` throughout. Every downstream phase's routed-item intake was empty. The findings survived only because each phase happened to re-read the previous phase's full markdown.
+
+Two habits follow from that:
+
+- Writing the routing in a report table documents it. The handoff entry *is* it.
+- A validation Evidence cell that says "routed to the semantic phase" is a claim about state. If the handoff entry does not exist, the claim is false and nothing will contradict it.

package/agent-skill/codecartographer/references/kernel-first-rewrite.md

@@ -0,0 +1,56 @@
+# Kernel-first rewrite shape
+
+A pattern for the `reimplementation-spec` phase when the goal is the least error-prone path to a replacement rather than a clone. It has held up on agent-like CLI tools; the reasoning generalizes to any system with a small semantic core and a wide adapter surface.
+
+## Classify the strategic assumptions first
+
+Before writing the spec, state which of these the user has actually committed to. Guessing produces a spec that is wrong in a way nobody notices until implementation.
+
+- **Platform** — is a specific OS or runtime assumed? If so, record which primitives the MVP may rely on (atomic rename, fsync, process groups, a POSIX shell).
+- **Architecture inspiration** — if the user pointed at another project, is it shape-only inspiration or a behavior contract? Default to shape-only unless they said otherwise.
+- **Stack lock** — if the language and runtime are not chosen, keep the spec language-agnostic *even when the platform is fixed*. Use the opinionated template only when stack, project identity, module names, and toolchain are all committed.
+- **Build order** — kernel-first with fake-driven acceptance tests, or something the user prefers instead.
+
+Record the chosen variant in the spec front matter and the validation block, so a later opinionated re-run is traceable.
+
+## Rings
+
+Frame the replacement as rings, innermost first. This keeps high-risk surface out of the MVP while preserving the seams it will later attach to.
+
+1. **Kernel** — the semantic core. For an agent tool: the loop, stream reduction, loop-detection, tool planning and execution, the permission decision, context-pressure policy.
+2. **Ports** — the interfaces the kernel talks through: provider stream, tool registry, persistence, permission prompt, event sink, clock and randomness, process execution.
+3. **Adapters** — concrete implementations of those ports: a specific provider API, filesystem persistence, a terminal renderer, a subprocess runner.
+4. **Extensions** — everything optional: MCP, LSP, hooks, background execution, subagents, memory, plan modes.
+5. **Delivery modes** — interactive, one-shot print, RPC, embedded SDK.
+
+The kernel must be buildable and testable without any ring above it. If it isn't, the boundary is in the wrong place.
+
+## Acceptance harness before adapters
+
+The first implementation artifact is a deterministic harness, not a working product:
+
+- a fake provider yielding scripted stream events, including malformed and mixed-field ones;
+- fake tools with deterministic success, error, crash, and cancel outcomes;
+- a fake permission prompt;
+- temp-directory persistence fixtures;
+- black-box tests for turn lifecycle, tool pipeline ordering, loop-break semantics, atomic persistence, config validation, cancellation, and stream reduction.
+
+Real providers, UI, and extensions come only after that harness is green. Every "do not clone" hazard from `deep-audit-synthesis.md` should appear here as a named test.
+
+## Milestone ordering
+
+Small, independently reviewable slices, each one commit with its tests. An order that has worked:
+
+1. tool pipeline result contract and failure semantics
+2. crash-safe durable persistence
+3. capability-based permission kernel
+4. minimal deterministic input-schema validation
+5. provider abstraction, proven against the fake streaming provider
+6. loop orchestration over fake provider and fake tools
+7. real adapters, only once the seams above are proven
+
+Stop after a coherent slice rather than stacking changes past the point of reviewability. For schema validation specifically, start with a deliberately small subset — root object, properties, required, primitive types, `additionalProperties: false`, and failing cleanly on a malformed schema — and extend only when a contract demands it.
+
+## What kernel-first is not
+
+It is not a reduced scope or a prototype. It is the safest route to a *full* replacement: the parts most likely to be subtly wrong get built first, in isolation, under deterministic tests, before anything depends on them.

package/agent-skill/codecartographer/references/phase-recovery.md

@@ -0,0 +1,48 @@
+# Recovering a stalled or failed phase
+
+Treat the workspace as the source of truth. Before assuming anything failed, run `codecarto_status` and `codecarto_validate`.
+
+## First: check whether it actually failed
+
+A delegated run that times out, is interrupted, or returns empty output **may still have written its artifact**. Executors commonly write the file and then die during cleanup or summary.
+
+1. Does the primary output file exist?
+2. If yes, run `codecarto_validate`. A `PASS` means the phase succeeded regardless of how the executor exited.
+3. Only retry when the artifact is absent or validation is `MISSING`/`FAIL`.
+
+Retrying a phase that already succeeded wastes the run and can overwrite a good artifact with a worse one.
+
+## Diagnosing by validation result
+
+**`MISSING`** — no primary output, or no validation block. The executor did not finish. Retry with reduced scope.
+
+**`FAIL`** — a criterion is unmet. The validation output names which. Repair the artifact against that criterion specifically; do not regenerate the whole thing.
+
+**`PASS WITH GAPS` you did not intend** — the executor marked criteria PARTIAL. Read the evidence cells: either the gaps are real and belong in the handoff as `open_questions`/`carry_forward`, or the executor under-read and should retry.
+
+**Completion refuses despite `PASS`** — almost always a missing handoff. The error names the expected path. Write `.codecarto/scratch/handoffs/<phase-id>.yaml` and complete again.
+
+## Writing a recovery prompt
+
+Narrower than the original, not a repeat of it:
+
+- name the exact primary output path;
+- require the validation block, with the literal `**Overall:** PASS` or `**Overall:** PASS WITH GAPS` final line;
+- require the handoff file, naming its path;
+- constrain traversal explicitly — skip vendored code, build output, generated files, and lockfiles unless the phase needs them;
+- for late phases, direct it to read prior `.codecarto/findings/` artifacts *instead of* the source tree, which is usually why the first attempt exhausted its budget;
+- narrow the tool grant. For an analysis-writing retry, read/write/edit/search is typically enough; shell access is often what let the first run wander.
+
+## Repeated failure on the same phase
+
+If two reduced-scope attempts fail, the problem is usually scope, not the executor:
+
+- Split the reading. Use scoped pre-passes over individual subsystems, save the notes under `.codecarto/scratch/`, and give the retry those notes as evidence.
+- Consider whether the pipeline variant is right. A repository too large for one `architecture` pass may want `architecture-only` first, reviewed, then a switch.
+- Check for a scaffold-staleness warning in `codecarto_status`. A workspace whose framework-owned files predate the running version can carry instructions that contradict the current contract, which produces artifacts that fail validation for reasons the executor cannot see.
+
+## What not to do
+
+- Do not hand-edit `workflow/status.yaml` to move past a failure. Completion is the only writer, and a manual edit is unreviewed state that the next completion may overwrite.
+- Do not mark a phase complete to unblock the pipeline. Downstream phases read upstream findings; a hollow artifact propagates.
+- Do not delete and re-init to escape a bad phase. `codecarto_init --force` moves the whole workspace, including phases that succeeded.

package/agent-skill/codecartographer/references/pipeline-selection.md

@@ -0,0 +1,38 @@
+# Choosing a pipeline
+
+Pass an alias to `codecarto_init` as `pipeline`. The default is `full-with-deep-audit`.
+
+| Alias | Phases | Use when |
+|---|---|---|
+| `architecture-only` | architecture | quick structural read; "what is this repo" |
+| `lite` | architecture → contracts → protocols | understanding a system you will keep, not rewrite |
+| `defect-scan` | architecture → defect-scan | maintenance audit of a system you already understand |
+| `full` | architecture → contracts → protocols → porting → reimplementation-spec | porting or rewriting, no defect audit |
+| `full-with-audit` | adds a single defect-scan after architecture | porting, with defects surfaced once |
+| `full-with-deep-audit` *(default)* | splits the scan: mechanical after architecture, semantic after protocols | porting or rewriting where correctness matters |
+| `synthesis` | vision-capture → goal-synthesis-propose → spec-merge → goal-synthesis-finalize | forward synthesis of a *new* product, not reverse-engineering |
+
+## Deep audit versus plain audit
+
+`full-with-deep-audit` runs the defect scan in two passes for a reason worth understanding before choosing:
+
+- **mechanical** (logic, error handling, configuration) runs early, right after architecture, so contracts and porting can cite its findings;
+- **semantic** (concurrency, security, API contract violations) runs after protocols, because judging those needs the state machines and wire formats in hand.
+
+The mechanical pass routes anything it cannot settle locally to the semantic pass. If the user expects "seven phases," they mean this variant.
+
+Choose `full-with-audit` when one combined pass is enough and you want fewer phases. Choose `full-with-deep-audit` when the output will drive a rewrite, since a semantic pass without protocols context will miss the findings that most change a port.
+
+## Synthesis is a different workspace
+
+The `synthesis` pipeline plans a new product from a vision brief and a library of reusable specs. It does **not** treat the surrounding repository as source evidence. It has preflight gates: a completed `inputs/vision.md`, a valid non-empty library, and — for merge and finalization — at least one human-confirmed selection. `codecarto_vision` runs the guided interview that produces the brief.
+
+Do not reach for it when the user wants a repository analyzed.
+
+## Switching later
+
+Use `codecarto_switch_pipeline`, never a hand-edit. It preserves findings, handoffs, usage data, closeouts, and per-phase progress; phases present in both variants keep their completion status, phases unique to the new variant start pending, and phases only in the old one are dropped from state while their findings stay on disk.
+
+Switching from `full` to `full-with-deep-audit` mid-run is the common case — the user wanted the defect scans and started without them. That works and keeps the completed architecture, contracts, and protocols phases.
+
+Re-initializing with `force: true` is the destructive alternative: it moves the entire existing workspace to a backup directory. Only do that when the user explicitly asks, and say what will move.

package/dist/core/guide.d.ts

@@ -0,0 +1,18 @@
+/** Packaged agent-skill directory. Wrappers serve its contents through codecarto_guide. */
+export declare const packagedAgentSkillDir: string;
+/** A guide document: the main skill or one of its topic references. */
+export type GuideDocument = {
+    /** `overview` for SKILL.md, otherwise the reference's basename without `.md`. */
+    topic: string;
+    /** Markdown body, with SKILL.md's installer frontmatter stripped. */
+    content: string;
+};
+/** Topic names available to {@link readGuide}, `overview` first. */
+export declare function listGuideTopics(): Promise<string[]>;
+/**
+ * Read one guide document.
+ * @param topic - `overview` (default) for the main skill, or a reference name from {@link listGuideTopics}.
+ * @returns the requested document.
+ * @throws when the packaged skill is missing, or the topic is not one of {@link listGuideTopics}.
+ */
+export declare function readGuide(topic?: string): Promise<GuideDocument>;

package/dist/core/guide.js

@@ -0,0 +1,50 @@
+// Serves the packaged agent skill — the instructions for driving this server —
+// so an MCP client can read them without installing the skill files. The shipped
+// markdown under agent-skill/ is the single source: nothing here duplicates its
+// prose, and a drift test would have nothing to compare.
+import { readdir, readFile } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { pathExists } from "./utils.js";
+import { packageRoot } from "./workspace.js";
+/** Packaged agent-skill directory. Wrappers serve its contents through codecarto_guide. */
+export const packagedAgentSkillDir = join(packageRoot, "agent-skill", "codecartographer");
+/**
+ * Strip a leading YAML frontmatter block. The frontmatter is skill-installer
+ * metadata (name, version, license) that carries no instruction value for an
+ * agent reading the guide through the tool.
+ */
+function stripFrontmatter(markdown) {
+    const match = /^---\r?\n[\s\S]*?\r?\n---\r?\n/.exec(markdown);
+    return match ? markdown.slice(match[0].length).trimStart() : markdown;
+}
+/** Topic names available to {@link readGuide}, `overview` first. */
+export async function listGuideTopics() {
+    const referencesDir = join(packagedAgentSkillDir, "references");
+    if (!(await pathExists(referencesDir)))
+        return ["overview"];
+    const names = (await readdir(referencesDir))
+        .filter((name) => name.endsWith(".md"))
+        .map((name) => basename(name, ".md"))
+        .sort();
+    return ["overview", ...names];
+}
+/**
+ * Read one guide document.
+ * @param topic - `overview` (default) for the main skill, or a reference name from {@link listGuideTopics}.
+ * @returns the requested document.
+ * @throws when the packaged skill is missing, or the topic is not one of {@link listGuideTopics}.
+ */
+export async function readGuide(topic = "overview") {
+    const requested = topic.trim() || "overview";
+    const available = await listGuideTopics();
+    if (!available.includes(requested)) {
+        throw new Error(`Unknown guide topic ${requested}. Available: ${available.join(", ")}.`);
+    }
+    const path = requested === "overview"
+        ? join(packagedAgentSkillDir, "SKILL.md")
+        : join(packagedAgentSkillDir, "references", `${requested}.md`);
+    if (!(await pathExists(path))) {
+        throw new Error(`Packaged agent skill is missing at ${path}. Reinstall codecartographer-pi.`);
+    }
+    return { topic: requested, content: stripFrontmatter(await readFile(path, "utf8")) };
+}

package/dist/core/index.d.ts

@@ -8,6 +8,7 @@ export * from "./workspace.ts";
 export * from "./completion.ts";
 export * from "./orchestrator-config.ts";
 export * from "./usage.ts";
+export * from "./guide.ts";
 export * from "./dashboard.ts";
 export * from "./library.ts";
 export * from "./synthesis.ts";

package/dist/core/index.js

@@ -11,6 +11,7 @@ export * from "./workspace.js";
 export * from "./completion.js";
 export * from "./orchestrator-config.js";
 export * from "./usage.js";
+export * from "./guide.js";
 export * from "./dashboard.js";
 export * from "./library.js";
 export * from "./synthesis.js";

package/dist/core/workspace.d.ts

@@ -1,4 +1,6 @@
 import type { PhaseHandoff, WorkspaceState } from "./types.ts";
+/** Installed package root. Anchors packaged assets served to clients (template, agent skill). */
+export declare const packageRoot: string;
 export declare const packagedWorkspaceDir: string;
 export declare const PACKAGE_VERSION: string;
 export declare function getWorkspaceState(cwd: string): Promise<WorkspaceState | null>;

package/dist/core/workspace.js

@@ -26,7 +26,8 @@ function findPackageRoot(start) {
     }
 }
 const coreDir = dirname(fileURLToPath(import.meta.url));
-const packageRoot = findPackageRoot(coreDir);
+/** Installed package root. Anchors packaged assets served to clients (template, agent skill). */
+export const packageRoot = findPackageRoot(coreDir);
 // Path to the packaged framework template directory. Wrappers copy this on
 // /codecarto-init.
 export const packagedWorkspaceDir = join(packageRoot, ".codecarto");

package/dist/mcp-server/server.d.ts

@@ -171,6 +171,15 @@ export declare function handleListSkills(args: {
     }>;
     structuredContent?: Record<string, unknown>;
 }>;
+export declare function handleGuide(args: {
+    topic?: string;
+}): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    structuredContent?: Record<string, unknown>;
+}>;
 export declare function buildServer(): Server<{
     method: string;
     params?: {

package/dist/mcp-server/server.js

@@ -15,7 +15,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError, } from "@modelcontextprotocol/sdk/types.js";
 import { cp, mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { basename, isAbsolute, join } from "node:path";
-import { buildPhasePrompt, buildSkillPrompt, buildValidationSummary, canonicalPath, completeValidatedPhase, computePerPhaseTotals, computeTotals, createEmptyStatus, DEFAULT_PIPELINE_PATH, deriveSlug, discoverLibrary, describeScaffoldStaleness, getNextEligiblePhase, getPipelineLabel, getWorkspaceState, isValidSlug, isWithinPathResolved, listEntries, listSkillNames, loadCodecartoConfig, loadUsage, loadYamlFile, normalizeForComparison, PACKAGE_VERSION, packagedWorkspaceDir, pathExists, PhasePreflightError, publishEntry, reindex as libraryReindex, resolvePhase, resolvePipelineChoice, stringifySimpleYaml, switchPipeline, validatePhaseOutput, writeLibraryConfig, } from "../core/index.js";
+import { buildPhasePrompt, buildSkillPrompt, buildValidationSummary, canonicalPath, completeValidatedPhase, computePerPhaseTotals, computeTotals, createEmptyStatus, DEFAULT_PIPELINE_PATH, deriveSlug, discoverLibrary, describeScaffoldStaleness, getNextEligiblePhase, getPipelineLabel, getWorkspaceState, isValidSlug, isWithinPathResolved, listEntries, listGuideTopics, readGuide, listSkillNames, loadCodecartoConfig, loadUsage, loadYamlFile, normalizeForComparison, PACKAGE_VERSION, packagedWorkspaceDir, pathExists, PhasePreflightError, publishEntry, reindex as libraryReindex, resolvePhase, resolvePipelineChoice, stringifySimpleYaml, switchPipeline, validatePhaseOutput, writeLibraryConfig, } from "../core/index.js";
 import { initLibrary } from "../core/library.js";
 import { loadUserConfig, resolveUserConfigPath } from "../core/orchestrator-config.js";
 import { writeDashboard } from "../extensions/codecarto/dashboard-writer.js";
@@ -876,6 +876,19 @@ const TOOLS = [
             required: ["cwd"],
         },
     },
+    {
+        name: "codecarto_guide",
+        description: "Return the instructions for driving this server: the status/next/execute/validate/complete loop, the phase-handoff contract, pipeline selection, executor choice, and recovery. Call this first when you have not run a CodeCartographer pipeline before. Takes no workspace.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                topic: {
+                    type: "string",
+                    description: "Guide topic. Omit for the overview; other topics are listed in every response.",
+                },
+            },
+        },
+    },
     {
         name: "codecarto_list_skills",
         description: "List available post-pipeline skills installed in the workspace.",
@@ -905,7 +918,19 @@ const HANDLERS = {
     codecarto_usage: handleUsage,
     codecarto_dashboard: handleDashboard,
     codecarto_list_skills: handleListSkills,
+    codecarto_guide: handleGuide,
 };
+export async function handleGuide(args) {
+    const topics = await listGuideTopics();
+    const document = await readGuide(args.topic).catch((error) => {
+        throw new McpError(ErrorCode.InvalidParams, error instanceof Error ? error.message : String(error));
+    });
+    const other = topics.filter((name) => name !== document.topic);
+    const footer = other.length > 0
+        ? `\n\n---\nOther guide topics: ${other.join(", ")} (call codecarto_guide with topic).`
+        : "";
+    return textResult(`${document.content}${footer}`, { topic: document.topic, topics });
+}
 // ---------- server bootstrap ----------
 export function buildServer() {
     const server = new Server({ name: "codecartographer", version: PACKAGE_VERSION }, { capabilities: { tools: {} } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codecartographer-pi",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "mcpName": "io.github.HuginnIndustries/codecartographer",
   "description": "Turn an unfamiliar codebase into a validated reimplementation spec, then synthesize confirmed specs and a product vision into a traceable plan.",
   "type": "module",
@@ -35,6 +35,7 @@
   },
   "files": [
     ".codecarto/**/*",
+    "agent-skill/**/*",
     "dist/**/*",
     "assets/logo.svg",
     "README.md",