codecartographer-pi 0.12.10 → 0.13.0

package/.codecarto/CONTRIBUTING.md

@@ -25,7 +25,7 @@ Key things to verify:
 - Pipeline YAML files parse correctly and phase dependencies resolve.
 - SKILL.md instructions produce output that matches the corresponding template.
 - Validation protocol (VALIDATE.md) catches missing or incomplete sections.
-- `status.yaml` updates correctly after each phase, with the schema-split `open_questions` / `carry_forward` lists used for what each is for (see GUIDE.md "Open Questions vs Carry-Forward").
+- `status.yaml` updates correctly after each phase from the session's phase handoff, with the schema-split `open_questions` / `carry_forward` lists used for what each is for (see GUIDE.md "Open Questions vs Carry-Forward").
 - All file paths referenced in pipeline YAML, GUIDE.md, and SKILL.md files exist.
 
 #### THREAD_LOG.md de-dup check

package/.codecarto/GUIDE.md

@@ -39,8 +39,8 @@ If this is the first LLM to touch this project — no closeouts in `closeouts/`,
 If the user accepts the orchestrator role:
 
 1. Initialize `CONVENTIONS.md` from `templates/conventions-template.md` and `DECISIONS.md` from `templates/decisions-template.md` (skeletons only — populate as patterns and decisions accumulate).
-2. Set `project_name` in `workflow/status.yaml`.
-3. **Do not run the architecture phase yourself.** The orchestrator never executes pipeline phases — that is the implementing-session role (see §Roles). Instead, **draft an implementing-session prompt for the architecture phase** that a fresh thread will execute. Hand the prompt to the user; they spin up a new thread with it; the implementing thread runs the phase, validates, writes a closeout, and reports back; you (the orchestrator) read the returned closeout, update `CONVENTIONS.md` / `DECISIONS.md` / `workflow/status.yaml` per the closeout ritual, and draft the next phase's prompt. **Phase work always happens in fresh implementing-session threads, never in the orchestration thread.** A useful self-check: if you find yourself reading a `findings/<phase>/SKILL.md` or writing a `findings/<phase>/<primary-output>.md`, you have slipped into the implementing-session role — stop, draft the prompt, hand off.
+2. Confirm the project name. `project_name` defaults to the repository directory name and is persisted by the framework on the first completion; it only needs attention if the project should be called something else.
+3. **Do not run the architecture phase yourself.** The orchestrator never executes pipeline phases — that is the implementing-session role (see §Roles). Instead, **draft an implementing-session prompt for the architecture phase** that a fresh thread will execute. Hand the prompt to the user; they spin up a new thread with it; the implementing thread runs the phase, validates, writes a closeout, and reports back; you (the orchestrator) read the returned closeout and update `CONVENTIONS.md` / `DECISIONS.md` from it, then draft the next phase's prompt. The implementing session's own completion already applied its handoff to `workflow/status.yaml` — the orchestrator never edits that file. **Phase work always happens in fresh implementing-session threads, never in the orchestration thread.** A useful self-check: if you find yourself reading a `findings/<phase>/SKILL.md` or writing a `findings/<phase>/<primary-output>.md`, you have slipped into the implementing-session role — stop, draft the prompt, hand off.
 
 If the user declines:
 
@@ -63,7 +63,7 @@ Read these files in order before doing any analysis:
 
 All paths in this guide are relative to `.codecarto/` unless stated otherwise.
 
-If `project_name` in `workflow/status.yaml` is blank, set it to the name of this repository before starting analysis.
+A blank `project_name` in `workflow/status.yaml` needs no action: the framework resolves it to this repository's directory name and persists it on the first completion.
 
 Treat this workspace as durable memory across sessions. Do not invent a new structure. Use the one that exists.
 
@@ -80,6 +80,7 @@ Some files in this workspace are **read-only instructions** and must not be modi
 | Source code (read-only) | `../` (everything outside `.codecarto/`) | Read only. Analyze but never modify. |
 | Synthesis input (user-maintained) | `inputs/vision.md` | The user fills this before the synthesis pipeline starts. Implementing phases read it but do not rewrite the raw brief. |
 | Workflow state (framework-owned) | `workflow/status.yaml` | Read to understand progress. Implementing sessions never edit it directly; completion applies a validated phase handoff under a lock. |
+| Scaffold version stamp (framework-owned) | `workflow/scaffold-version.yaml` | Written at release, copied by init. The framework compares it to its own version to warn about stale scaffolds. Never edit. |
 | Findings (read-write) | `findings/<phase>/<primary-output>.md`, secondary output files | Create and update during phases. |
 | Phase handoff (read-write) | `scratch/handoffs/<phase>.yaml` | Implementing sessions propose state changes and closeout content here. The framework validates and applies them. |
 | Closeouts (framework-owned) | `closeouts/<date>-<phase-or-module>.md`, `THREAD_LOG.md` | Completion writes or updates one canonical closeout and one idempotent index entry. |

package/.codecarto/NEW_THREAD_BLURB.md

@@ -9,7 +9,7 @@ All CodeCartographer files are inside `.codecarto/`. Paths below are relative to
 Read these in order before doing work:
 
 1. `GUIDE.md` - the LLM entry point and session guide
-2. `workflow/status.yaml` - the single source of truth for project progress
+2. `workflow/status.yaml` - current progress and routed items (framework-owned: read it, never edit it)
 3. `CONVENTIONS.md` if present - cross-cutting patterns this project follows
 4. The current phase's existing output file, if present
 5. The current phase's `SKILL.md`
@@ -20,18 +20,17 @@ Where to store results:
 
 - Durable findings: `findings/<phase>/`
 - Rough notes: `scratch/`
-- Workflow status: `workflow/status.yaml` (only status file to update)
-- Per-session closeouts: `closeouts/<YYYY-MM-DD>-<phase-or-module>.md` (use `templates/closeout-template.md`)
-- Cross-session log: append a one-line index entry to `THREAD_LOG.md` pointing at your closeout file
+- State changes (owner notes, open questions, carry-forward routings): `scratch/handoffs/<phase>.yaml` — completion applies it to `workflow/status.yaml`; never edit `status.yaml` directly
+- Closeouts and `THREAD_LOG.md`: framework-owned; supply `closeout_summary` and optional `closeout_content` in the handoff
 
 After completing work:
 
 1. Run validation per `workflow/VALIDATE.md`. Append the validation block to the output.
-2. Update `workflow/status.yaml`: mark the phase `complete`, advance `current_phase` to the next pending phase (or `complete` if all phases are done), and update both `open_questions` (genuinely unknown) and `carry_forward` (deferred to a specific later phase) for the phase. See GUIDE.md "Open Questions vs Carry-Forward" for the entry shape.
-3. Record 2-3 key observations in `owner_notes` for the completed phase.
-4. Write a per-session closeout file at `closeouts/<YYYY-MM-DD>-<phase-or-module>.md`. Append a one-line entry to `THREAD_LOG.md` pointing at it (de-dup discipline: scan the bottom 5 entries first to avoid double-appending).
-5. Store the durable output in the declared `findings/` path.
-6. If the session made cross-cutting decisions or proposed conventions, fill in the closeout's "Decisions Beyond Prompt" and "Proposed Conventions" sections. The orchestrator promotes them to `DECISIONS.md` and `CONVENTIONS.md` respectively.
+2. Write `scratch/handoffs/<phase>.yaml` (see `templates/phase-handoff.yaml`): `schema_version: 1`, the exact `phase_id`, arrays for `owner_notes`, `open_questions`, `carry_forward`, `carry_forward_closures`, `open_question_closures`, `post_pipeline`, and `decisions`, plus `closeout_summary` and optional multiline `closeout_content`. See GUIDE.md "Open Questions vs Carry-Forward" for the entry shape.
+3. Record 2-3 key observations in the handoff's `owner_notes`.
+4. Store the durable output in the declared `findings/` path.
+5. Run completion. The framework verifies the primary output and validation, applies the handoff to `workflow/status.yaml`, and writes the closeout and `THREAD_LOG.md` entry.
+6. If the session made cross-cutting decisions or proposed conventions, record them in the handoff's `decisions` array and the closeout content's "Decisions Beyond Prompt" and "Proposed Conventions" sections. The orchestrator promotes them to `DECISIONS.md` and `CONVENTIONS.md` respectively.
 
 ## File-System Sync Warning
 
@@ -44,4 +43,4 @@ To stay safe:
 - **Never chain Edit and bash heredocs against the same file in a single session** — pick one writer and stick with it.
 - Keep test code in a separate file from production code so a sync gap on one doesn't poison the other.
 
-This is not a CodeCartographer issue per se, but the framework's reliance on append-to-narrative-files (`THREAD_LOG.md`, `status.yaml`, large primary outputs) magnifies the cost — every truncated write is a potential silent data loss in a load-bearing place.
+This is not a CodeCartographer issue per se, but the framework's reliance on large narrative files (findings reports, primary outputs) magnifies the cost — every truncated write is a potential silent data loss in a load-bearing place.

package/.codecarto/findings/defect-scan-mechanical/SKILL.md

@@ -57,4 +57,4 @@ If the semantic phase later finds related defects, those go in its own report
 - Auth, input validation, secrets, and trust boundary defects → pass 4 in `defect-scan-semantic`.
 - API/spec/state-machine drift → pass 5 in `defect-scan-semantic`.
 
-If you spot something semantic during this phase, record it as a `carry_forward` entry in `workflow/status.yaml` with `target_phase: defect-scan-semantic` so the later phase picks it up.
+If you spot something semantic during this phase, record it as a `carry_forward` entry in your phase handoff at `scratch/handoffs/defect-scan-mechanical.yaml` with `target_phase: defect-scan-semantic`. Completion applies it to `workflow/status.yaml`, and the semantic phase receives it as a routed item in its prompt. Listing it only in your report's routing table does not route it.

package/.codecarto/skills/spec-delta-application/SKILL.md

@@ -86,7 +86,7 @@ Per the standard closeout ritual:
 
 - Append a one-line entry to `THREAD_LOG.md` pointing at the closeout file.
 - Write `closeouts/<YYYY-MM-DD>-spec-deltas.md` using `templates/closeout-template.md`.
-- Update `status.yaml` only if a delta closed an `open_questions` or `carry_forward` entry — do NOT change `current_phase` (stays `complete`).
+- If a delta closed an `open_questions` or `carry_forward` entry, record that in the closeout. Do not edit `status.yaml` — phase state is framework-owned, and post-pipeline work has no completion step that applies handoffs, so a hand-edit here is unreviewed and can be overwritten by a later phase completion.
 - Append numbered entries to `DECISIONS.md` for any decisions made during triage that weren't already in the deltas (e.g., "rejected Δ7 because the spec already covered the case at §X").
 
 ## What to avoid

package/.codecarto/templates/architecture-map.md

@@ -126,7 +126,8 @@
 
 <!-- Items deferred to a specific later phase whose rubric is the right place to close them.
      Each entry: { id, kind: defer-to-phase, target_phase, description, deferred_reason }.
-     Mirror these into workflow/status.yaml under this phase's carry_forward list. -->
+     Mirror these into your phase handoff at scratch/handoffs/<phase>.yaml under carry_forward;
+     completion applies them to workflow/status.yaml. Never write that file yourself. -->
 
 | ID | Target Phase | Description | Deferred Reason |
 |---|---|---|---|

package/.codecarto/templates/behavioral-contracts.md

@@ -114,7 +114,8 @@
 <!-- Items deferred to a specific later phase whose rubric is the right place to close them.
      Common targets from contracts: protocols (wire-format details), porting (synthesis-level resolution).
      Each entry: { id, kind: defer-to-phase, target_phase, description, deferred_reason }.
-     Mirror these into workflow/status.yaml under this phase's carry_forward list. -->
+     Mirror these into your phase handoff at scratch/handoffs/<phase>.yaml under carry_forward;
+     completion applies them to workflow/status.yaml. Never write that file yourself. -->
 
 | ID | Target Phase | Description | Deferred Reason |
 |---|---|---|---|

package/.codecarto/templates/closeout-template.md

@@ -58,7 +58,8 @@
 ## Open Questions Left Behind
 
 <!-- Items that are still genuinely unknown after this session.
-     Mirror these into workflow/status.yaml under the relevant phase's open_questions. -->
+     Mirror these into your phase handoff under open_questions; completion applies them
+     to workflow/status.yaml. This table documents them — it does not record them. -->
 
 | ID | Kind | Description | Deferred Reason |
 |---|---|---|---|
@@ -67,7 +68,9 @@
 ## Carry-Forward Routed
 
 <!-- Items deferred to a specific later phase.
-     Mirror these into workflow/status.yaml under the relevant phase's carry_forward. -->
+     Mirror these into your phase handoff under carry_forward, each with a target_phase;
+     completion applies them to workflow/status.yaml. This table documents them — it does
+     not route them. -->
 
 | ID | Target Phase | Description | Deferred Reason |
 |---|---|---|---|

package/.codecarto/templates/mechanical-defects.md

@@ -79,8 +79,10 @@
 ### Routed To Semantic Phase
 
 <!-- Items spotted during this phase that are actually semantic in nature
-     (concurrency, security, contract drift). Mirror these into status.yaml as
-     carry_forward entries with target_phase: defect-scan-semantic. -->
+     (concurrency, security, contract drift). Mirror these into your phase handoff at
+     scratch/handoffs/defect-scan-mechanical.yaml as carry_forward entries with
+     target_phase: defect-scan-semantic; completion applies them to workflow/status.yaml.
+     The table below documents the routing — it does not perform it. -->
 
 | ID | Description | Why Routed |
 |----|-------------|-----------|

package/.codecarto/templates/protocols-and-state.md

@@ -109,7 +109,8 @@
 <!-- Items deferred to a specific later phase whose rubric is the right place to close them.
      Common target from protocols: porting (synthesis-level resolution).
      Each entry: { id, kind: defer-to-phase, target_phase, description, deferred_reason }.
-     Mirror these into workflow/status.yaml under this phase's carry_forward list. -->
+     Mirror these into your phase handoff at scratch/handoffs/<phase>.yaml under carry_forward;
+     completion applies them to workflow/status.yaml. Never write that file yourself. -->
 
 | ID | Target Phase | Description | Deferred Reason |
 |---|---|---|---|

package/.codecarto/templates/reverse-engineering-bundle.md

@@ -140,7 +140,8 @@
 <!-- Items deferred to a specific later phase whose rubric is the right place to close them.
      Common target from porting: reimplementation-spec (rule-pinning, opinionated decisions).
      Each entry: { id, kind: defer-to-phase, target_phase, description, deferred_reason }.
-     Mirror these into workflow/status.yaml under this phase's carry_forward list. -->
+     Mirror these into your phase handoff at scratch/handoffs/<phase>.yaml under carry_forward;
+     completion applies them to workflow/status.yaml. Never write that file yourself. -->
 
 | ID | Target Phase | Description | Deferred Reason |
 |---|---|---|---|

package/.codecarto/templates/semantic-defects.md

@@ -85,7 +85,9 @@
 
 ### Carry-Forward Closure
 
-<!-- carry_forward entries in status.yaml that targeted defect-scan-semantic and were closed here. -->
+<!-- carry_forward entries routed to defect-scan-semantic (delivered in this phase's prompt)
+     that were closed here. Address each in the findings above, then list its id under
+     carry_forward_closures in your phase handoff so completion removes the entry. -->
 
 | ID | Source Phase | Closed Because |
 |----|--------------|---------------|

package/.codecarto/templates/thread-log-entry-template.md

@@ -1,14 +1,13 @@
-# THREAD_LOG.md Entry Template (legacy / one-line index form)
+# THREAD_LOG.md Entry Format (framework-owned)
 
-This template is the **one-line index entry** appended to `THREAD_LOG.md` per session.
-The full body of each session lives in a separate closeout file under `closeouts/`.
+`THREAD_LOG.md` is written by completion, not by sessions. Completion appends one index entry per completed phase, built from the `closeout_summary` in your phase handoff and the canonical closeout filename, and skips the append when an entry already links that closeout — so retries never duplicate.
 
-For the closeout file itself, use `templates/closeout-template.md`.
+Your input to this file is the handoff's `closeout_summary`. The full body of each session lives in a separate closeout file under `closeouts/`; for that file, use `templates/closeout-template.md`.
 
-## Entry format
+## Entry format produced
 
 ```
-- YYYY-MM-DD — <phase-or-module> — <one-line-summary> — [closeout](closeouts/YYYY-MM-DD-phase-or-module.md)
+- YYYY-MM-DD — <phase-or-module> — <closeout_summary> — [closeout](closeouts/YYYY-MM-DD-phase-or-module.md)
 ```
 
 ## Example
@@ -17,11 +16,10 @@ For the closeout file itself, use `templates/closeout-template.md`.
 - 2026-05-02 — architecture — mapped 14 packages across 3 layers; 2 carry-forward items routed to defect-scan — [closeout](closeouts/2026-05-02-architecture.md)
 ```
 
-## Rules
+## Writing a good closeout_summary
 
-- One line per session, no exceptions.
-- Date in ISO format (YYYY-MM-DD).
-- `<phase-or-module>` matches the closeout filename's slug.
-- Summary is one clause, no more than ~20 words.
-- Always link to the closeout file. If there is no closeout file, the entry doesn't belong here.
-- Before appending, scan the bottom 5 entries to avoid duplicating a prior session's entry.
+- One clause, no more than ~20 words — it has to read well inside the one-line entry above.
+- Name what the phase established and what it routed onward, as in the example.
+- Omitting it is allowed; completion falls back to `Validation: <overall>`, which carries no information about the work.
+
+Everything else in the entry — the date, the phase slug, the closeout link, and de-duplication across retries — is supplied by the framework. Do not append to `THREAD_LOG.md` yourself; a hand-written entry will sit alongside the canonical one rather than replacing it.

package/.codecarto/workflow/VALIDATE.md

@@ -13,8 +13,8 @@ Run this check after completing a phase's primary output, before marking the pha
 4. Append a validation block to the end of the primary output file (see format below).
 5. If any criterion is FAIL, do not mark the phase as complete. Fix the output first.
 6. If any criterion is PARTIAL, route the gap appropriately:
-   - If the gap is **still genuinely unknown** (needs a runtime test, maintainer decision, or spec ruling that no later phase will close), record it under `open_questions` for the phase in `workflow/status.yaml`.
-   - If the gap is **deferred to a specific later phase** in this pipeline (the next phase's rubric is the right place to close it), record it under `carry_forward` with an explicit `target_phase` field. See GUIDE.md "Open Questions vs Carry-Forward" for the entry shape.
+   - If the gap is **still genuinely unknown** (needs a runtime test, maintainer decision, or spec ruling that no later phase will close), record it under `open_questions` in your phase handoff at `scratch/handoffs/<phase>.yaml`.
+   - If the gap is **deferred to a specific later phase** in this pipeline (the next phase's rubric is the right place to close it), record it under `carry_forward` in the same handoff with an explicit `target_phase` field. See GUIDE.md "Open Questions vs Carry-Forward" for the entry shape.
    - You may still mark the phase complete if the gaps are documented under one of the two lists and are non-blocking for downstream phases.
 
 ## Validation Block Format
@@ -56,20 +56,23 @@ Below is what a real PASS WITH GAPS block looks like — useful when a phase fin
 **Overall:** PASS WITH GAPS
 ```
 
-The `arch-CF2` entry then appears in `workflow/status.yaml` under the architecture phase's `carry_forward`:
+You record the `arch-CF2` entry in your phase handoff at `scratch/handoffs/architecture.yaml`:
 
 ```yaml
-phases:
-  architecture:
-    carry_forward:
-      - id: arch-CF2
-        kind: defer-to-phase
-        target_phase: protocols
-        description: MCP server endpoints and websocket subscription channel listed by name only; schemas not extracted.
-        deferred_reason: Wire-format extraction is the protocols phase's rubric; deferring avoids guessing at shapes here.
+schema_version: 1
+phase_id: architecture
+carry_forward:
+  - id: arch-CF2
+    kind: defer-to-phase
+    target_phase: protocols
+    description: MCP server endpoints and websocket subscription channel listed by name only; schemas not extracted.
+    deferred_reason: Wire-format extraction is the protocols phase's rubric; deferring avoids guessing at shapes here.
+closeout_summary: Architecture mapped; wire formats deferred to protocols.
 ```
 
-The protocols phase, on session start, scans `carry_forward` entries with `target_phase: protocols`, picks `arch-CF2` up, and either resolves it (deletes the entry once the schemas are pinned) or re-defers to a later phase.
+Completion validates the handoff and applies the entry to `workflow/status.yaml` under the architecture phase's `carry_forward`. Never write that file yourself — see GUIDE.md "Trust Boundaries."
+
+The protocols phase then receives `arch-CF2` in its phase prompt as a routed item. It either resolves it (addressing it in the phase output and listing the id under `carry_forward_closures` in its own handoff, so completion removes the entry atomically) or re-defers it by writing a fresh `carry_forward` entry naming a later `target_phase`.
 
 ## Rules
 
@@ -77,5 +80,5 @@ The protocols phase, on session start, scans `carry_forward` entries with `targe
 - Do not inflate results. A criterion you are uncertain about is PARTIAL, not PASS.
 - If the output file already has a validation block from a prior session, replace it with a fresh one.
 - Validation checks the output against the pipeline's criteria only. It does not re-evaluate the source code.
-- For automated agents: a phase with any FAIL result must not have its status set to `complete` in status.yaml.
-- A PARTIAL row's `Evidence` cell must name what is missing and (if applicable) which `open_questions` or `carry_forward` entry tracks the gap. "Incomplete" alone is not honest enough.
+- For automated agents: a phase with any FAIL result must not be completed. Completion refuses FAIL and MISSING validations outright.
+- A PARTIAL row's `Evidence` cell must name what is missing and (if applicable) which `open_questions` or `carry_forward` entry tracks the gap. "Incomplete" alone is not honest enough. Record that entry in the phase handoff — an evidence cell that only *describes* the routing does not perform it.

package/.codecarto/workflow/pipeline-architecture-only.yaml

@@ -35,5 +35,5 @@ phases:
       - Coverage and limits name inspected scope, skipped scope, evidence basis, and blind spots.
     handoff_requirements:
       - Run validation per workflow/VALIDATE.md. Append validation block to primary output.
-      - Update workflow/status.yaml.
-      - Append a summary entry to THREAD_LOG.md.
+      - Write the phase handoff to scratch/handoffs/<phase>.yaml with owner notes, open questions, and carry-forward routings; completion applies it to workflow/status.yaml.
+      - Provide closeout_summary and optional closeout_content in the handoff; completion writes the closeout and THREAD_LOG.md entry.

package/.codecarto/workflow/pipeline-defect-scan.yaml

@@ -36,8 +36,8 @@ phases:
       - Coverage and limits name inspected scope, skipped scope, evidence basis, and blind spots.
     handoff_requirements:
       - Run validation per workflow/VALIDATE.md. Append validation block to primary output.
-      - Update workflow/status.yaml.
-      - Append a summary entry to THREAD_LOG.md.
+      - Write the phase handoff to scratch/handoffs/<phase>.yaml with owner notes, open questions, and carry-forward routings; completion applies it to workflow/status.yaml.
+      - Provide closeout_summary and optional closeout_content in the handoff; completion writes the closeout and THREAD_LOG.md entry.
   - id: defect-scan
     purpose: Run a multi-pass defect scan to identify bugs, security issues, and code quality problems for maintenance prioritization.
     skill_path: findings/defect-scan/SKILL.md
@@ -59,5 +59,5 @@ phases:
       - Coverage and limits name inspected scope, skipped scope, evidence basis, and blind spots.
     handoff_requirements:
       - Run validation per workflow/VALIDATE.md. Append validation block to primary output.
-      - Update workflow/status.yaml.
-      - Append a summary entry to THREAD_LOG.md.
+      - Write the phase handoff to scratch/handoffs/<phase>.yaml with owner notes, open questions, and carry-forward routings; completion applies it to workflow/status.yaml.
+      - Provide closeout_summary and optional closeout_content in the handoff; completion writes the closeout and THREAD_LOG.md entry.

package/.codecarto/workflow/pipeline-full-with-audit.yaml

@@ -40,8 +40,8 @@ phases:
       - Coverage and limits name inspected scope, skipped scope, evidence basis, and blind spots.
     handoff_requirements:
       - Run validation per workflow/VALIDATE.md. Append validation block to primary output.
-      - Update workflow/status.yaml.
-      - Append a summary entry to THREAD_LOG.md.
+      - Write the phase handoff to scratch/handoffs/<phase>.yaml with owner notes, open questions, and carry-forward routings; completion applies it to workflow/status.yaml.
+      - Provide closeout_summary and optional closeout_content in the handoff; completion writes the closeout and THREAD_LOG.md entry.
   - id: defect-scan
     purpose: Run a multi-pass defect scan to identify legacy bugs, security issues, and code quality problems before porting.
     skill_path: findings/defect-scan/SKILL.md
@@ -63,8 +63,8 @@ phases:
       - Coverage and limits name inspected scope, skipped scope, evidence basis, and blind spots.
     handoff_requirements:
       - Run validation per workflow/VALIDATE.md. Append validation block to primary output.
-      - Update workflow/status.yaml.
-      - Append a summary entry to THREAD_LOG.md.
+      - Write the phase handoff to scratch/handoffs/<phase>.yaml with owner notes, open questions, and carry-forward routings; completion applies it to workflow/status.yaml.
+      - Provide closeout_summary and optional closeout_content in the handoff; completion writes the closeout and THREAD_LOG.md entry.
   - id: contracts
     purpose: Recover user-visible behavior, defaults, side effects, error behavior, and black-box acceptance checks.
     skill_path: findings/contracts/SKILL.md
@@ -95,8 +95,8 @@ phases:
       - Coverage and limits name inspected scope, skipped scope, evidence basis, and blind spots.
     handoff_requirements:
       - Run validation per workflow/VALIDATE.md. Append validation block to primary output.
-      - Update workflow/status.yaml.
-      - Append a summary entry to THREAD_LOG.md.
+      - Write the phase handoff to scratch/handoffs/<phase>.yaml with owner notes, open questions, and carry-forward routings; completion applies it to workflow/status.yaml.
+      - Provide closeout_summary and optional closeout_content in the handoff; completion writes the closeout and THREAD_LOG.md entry.
   - id: protocols
     purpose: Capture event catalogs, state machines, persistence formats, and compatibility hazards.
     skill_path: findings/protocols/SKILL.md
@@ -126,8 +126,8 @@ phases:
       - Coverage and limits name inspected scope, skipped scope, evidence basis, and blind spots.
     handoff_requirements:
       - Run validation per workflow/VALIDATE.md. Append validation block to primary output.
-      - Update workflow/status.yaml.
-      - Append a summary entry to THREAD_LOG.md.
+      - Write the phase handoff to scratch/handoffs/<phase>.yaml with owner notes, open questions, and carry-forward routings; completion applies it to workflow/status.yaml.
+      - Provide closeout_summary and optional closeout_content in the handoff; completion writes the closeout and THREAD_LOG.md entry.
   - id: porting
     purpose: Synthesize architecture, contracts, protocols, and defect findings into a reverse-engineering bundle oriented toward porting.
     skill_path: findings/porting/SKILL.md
@@ -165,8 +165,8 @@ phases:
       - The Source Index makes the bundle a self-contained compression boundary and identifies targeted deep-read triggers.
     handoff_requirements:
       - Run validation per workflow/VALIDATE.md. Append validation block to primary output.
-      - Update workflow/status.yaml.
-      - Append a summary entry to THREAD_LOG.md.
+      - Write the phase handoff to scratch/handoffs/<phase>.yaml with owner notes, open questions, and carry-forward routings; completion applies it to workflow/status.yaml.
+      - Provide closeout_summary and optional closeout_content in the handoff; completion writes the closeout and THREAD_LOG.md entry.
   - id: reimplementation-spec
     purpose: Produce the final language-agnostic reimplementation plan and acceptance spec.
     skill_path: findings/reimplementation-spec/SKILL.md
@@ -189,5 +189,5 @@ phases:
       - Lower-level findings are deep-read only when the porting bundle identifies a gap, conflict, missing acceptance detail, or defect rationale.
     handoff_requirements:
       - Run validation per workflow/VALIDATE.md. Append validation block to primary output.
-      - Update workflow/status.yaml.
-      - Append a summary entry to THREAD_LOG.md.
+      - Write the phase handoff to scratch/handoffs/<phase>.yaml with owner notes, open questions, and carry-forward routings; completion applies it to workflow/status.yaml.
+      - Provide closeout_summary and optional closeout_content in the handoff; completion writes the closeout and THREAD_LOG.md entry.

package/.codecarto/workflow/pipeline-full-with-deep-audit.yaml

@@ -41,8 +41,8 @@ phases:
       - Coverage and limits name inspected scope, skipped scope, evidence basis, and blind spots.
     handoff_requirements:
       - Run validation per workflow/VALIDATE.md. Append validation block to primary output.
-      - Update workflow/status.yaml.
-      - Append a summary entry to THREAD_LOG.md.
+      - Write the phase handoff to scratch/handoffs/<phase>.yaml with owner notes, open questions, and carry-forward routings; completion applies it to workflow/status.yaml.
+      - Provide closeout_summary and optional closeout_content in the handoff; completion writes the closeout and THREAD_LOG.md entry.
   - id: defect-scan-mechanical
     purpose: Early, context-light defect pass covering logic, error handling, and configuration hazards. Runs before contracts so mechanical bugs are surfaced for the contracts and porting phases to reference.
     skill_path: findings/defect-scan-mechanical/SKILL.md
@@ -60,13 +60,13 @@ phases:
       - Each finding has location, severity, evidence level, and recommended action.
       - Findings are organized by pass and sorted by severity.
       - Summary tables are complete and counts match the detailed findings.
-      - Items spotted that are actually semantic in nature are routed to defect-scan-semantic via carry_forward in workflow/status.yaml.
+      - Items spotted that are actually semantic in nature are routed onward via a carry_forward entry in the phase handoff targeting defect-scan-semantic.
       - Findings are marked with evidence levels.
       - Coverage and limits name inspected scope, skipped scope, evidence basis, and blind spots.
     handoff_requirements:
       - Run validation per workflow/VALIDATE.md. Append validation block to primary output.
-      - Update workflow/status.yaml.
-      - Append a summary entry to THREAD_LOG.md.
+      - Write the phase handoff to scratch/handoffs/<phase>.yaml with owner notes, open questions, and carry-forward routings; completion applies it to workflow/status.yaml.
+      - Provide closeout_summary and optional closeout_content in the handoff; completion writes the closeout and THREAD_LOG.md entry.
   - id: contracts
     purpose: Recover user-visible behavior, defaults, side effects, error behavior, and black-box acceptance checks.
     skill_path: findings/contracts/SKILL.md
@@ -98,8 +98,8 @@ phases:
       - Coverage and limits name inspected scope, skipped scope, evidence basis, and blind spots.
     handoff_requirements:
       - Run validation per workflow/VALIDATE.md. Append validation block to primary output.
-      - Update workflow/status.yaml.
-      - Append a summary entry to THREAD_LOG.md.
+      - Write the phase handoff to scratch/handoffs/<phase>.yaml with owner notes, open questions, and carry-forward routings; completion applies it to workflow/status.yaml.
+      - Provide closeout_summary and optional closeout_content in the handoff; completion writes the closeout and THREAD_LOG.md entry.
   - id: protocols
     purpose: Capture event catalogs, state machines, persistence formats, and compatibility hazards.
     skill_path: findings/protocols/SKILL.md
@@ -130,8 +130,8 @@ phases:
       - Coverage and limits name inspected scope, skipped scope, evidence basis, and blind spots.
     handoff_requirements:
       - Run validation per workflow/VALIDATE.md. Append validation block to primary output.
-      - Update workflow/status.yaml.
-      - Append a summary entry to THREAD_LOG.md.
+      - Write the phase handoff to scratch/handoffs/<phase>.yaml with owner notes, open questions, and carry-forward routings; completion applies it to workflow/status.yaml.
+      - Provide closeout_summary and optional closeout_content in the handoff; completion writes the closeout and THREAD_LOG.md entry.
   - id: defect-scan-semantic
     purpose: Deep, context-rich defect pass covering concurrency, security, and API contract violations. Runs after protocols so contracts/protocols context is available, and before porting so the porting phase can synthesize all defects with full understanding of the system.
     skill_path: findings/defect-scan-semantic/SKILL.md
@@ -160,8 +160,8 @@ phases:
       - Coverage and limits name inspected scope, skipped scope, evidence basis, and blind spots.
     handoff_requirements:
       - Run validation per workflow/VALIDATE.md. Append validation block to primary output.
-      - Update workflow/status.yaml.
-      - Append a summary entry to THREAD_LOG.md.
+      - Write the phase handoff to scratch/handoffs/<phase>.yaml with owner notes, open questions, and carry-forward routings; completion applies it to workflow/status.yaml.
+      - Provide closeout_summary and optional closeout_content in the handoff; completion writes the closeout and THREAD_LOG.md entry.
   - id: porting
     purpose: Synthesize architecture, contracts, protocols, and both defect passes into a reverse-engineering bundle oriented toward porting. Fill the Defect Synthesis section by consolidating mechanical-defects.md and semantic-defects.md into a single porting-oriented view.
     skill_path: findings/porting/SKILL.md
@@ -202,8 +202,8 @@ phases:
       - The Source Index makes the bundle a self-contained compression boundary and identifies targeted deep-read triggers.
     handoff_requirements:
       - Run validation per workflow/VALIDATE.md. Append validation block to primary output.
-      - Update workflow/status.yaml.
-      - Append a summary entry to THREAD_LOG.md.
+      - Write the phase handoff to scratch/handoffs/<phase>.yaml with owner notes, open questions, and carry-forward routings; completion applies it to workflow/status.yaml.
+      - Provide closeout_summary and optional closeout_content in the handoff; completion writes the closeout and THREAD_LOG.md entry.
   - id: reimplementation-spec
     purpose: Produce the final language-agnostic reimplementation plan and acceptance spec. The Strategic Alignment Hook in GUIDE.md decides between the default and opinionated template variants.
     skill_path: findings/reimplementation-spec/SKILL.md
@@ -227,5 +227,5 @@ phases:
       - Lower-level findings are deep-read only when the porting bundle identifies a gap, conflict, missing acceptance detail, or defect rationale.
     handoff_requirements:
       - Run validation per workflow/VALIDATE.md. Append validation block to primary output.
-      - Update workflow/status.yaml.
-      - Append a summary entry to THREAD_LOG.md.
+      - Write the phase handoff to scratch/handoffs/<phase>.yaml with owner notes, open questions, and carry-forward routings; completion applies it to workflow/status.yaml.
+      - Provide closeout_summary and optional closeout_content in the handoff; completion writes the closeout and THREAD_LOG.md entry.

package/.codecarto/workflow/pipeline-lite.yaml

@@ -37,8 +37,8 @@ phases:
       - Coverage and limits name inspected scope, skipped scope, evidence basis, and blind spots.
     handoff_requirements:
       - Run validation per workflow/VALIDATE.md. Append validation block to primary output.
-      - Update workflow/status.yaml.
-      - Append a summary entry to THREAD_LOG.md.
+      - Write the phase handoff to scratch/handoffs/<phase>.yaml with owner notes, open questions, and carry-forward routings; completion applies it to workflow/status.yaml.
+      - Provide closeout_summary and optional closeout_content in the handoff; completion writes the closeout and THREAD_LOG.md entry.
   - id: contracts
     purpose: Recover user-visible behavior, defaults, side effects, error behavior, and black-box acceptance checks.
     skill_path: findings/contracts/SKILL.md
@@ -68,8 +68,8 @@ phases:
       - Coverage and limits name inspected scope, skipped scope, evidence basis, and blind spots.
     handoff_requirements:
       - Run validation per workflow/VALIDATE.md. Append validation block to primary output.
-      - Update workflow/status.yaml.
-      - Append a summary entry to THREAD_LOG.md.
+      - Write the phase handoff to scratch/handoffs/<phase>.yaml with owner notes, open questions, and carry-forward routings; completion applies it to workflow/status.yaml.
+      - Provide closeout_summary and optional closeout_content in the handoff; completion writes the closeout and THREAD_LOG.md entry.
   - id: protocols
     purpose: Capture event catalogs, state machines, persistence formats, and compatibility hazards.
     skill_path: findings/protocols/SKILL.md
@@ -99,5 +99,5 @@ phases:
       - Coverage and limits name inspected scope, skipped scope, evidence basis, and blind spots.
     handoff_requirements:
       - Run validation per workflow/VALIDATE.md. Append validation block to primary output.
-      - Update workflow/status.yaml.
-      - Append a summary entry to THREAD_LOG.md.
+      - Write the phase handoff to scratch/handoffs/<phase>.yaml with owner notes, open questions, and carry-forward routings; completion applies it to workflow/status.yaml.
+      - Provide closeout_summary and optional closeout_content in the handoff; completion writes the closeout and THREAD_LOG.md entry.

package/.codecarto/workflow/pipeline.yaml

@@ -39,8 +39,8 @@ phases:
       - Coverage and limits name inspected scope, skipped scope, evidence basis, and blind spots.
     handoff_requirements:
       - Run validation per workflow/VALIDATE.md. Append validation block to primary output.
-      - Update workflow/status.yaml.
-      - Append a summary entry to THREAD_LOG.md.
+      - Write the phase handoff to scratch/handoffs/<phase>.yaml with owner notes, open questions, and carry-forward routings; completion applies it to workflow/status.yaml.
+      - Provide closeout_summary and optional closeout_content in the handoff; completion writes the closeout and THREAD_LOG.md entry.
   - id: contracts
     purpose: Recover user-visible behavior, defaults, side effects, error behavior, and black-box acceptance checks.
     skill_path: findings/contracts/SKILL.md
@@ -71,8 +71,8 @@ phases:
       - Coverage and limits name inspected scope, skipped scope, evidence basis, and blind spots.
     handoff_requirements:
       - Run validation per workflow/VALIDATE.md. Append validation block to primary output.
-      - Update workflow/status.yaml.
-      - Append a summary entry to THREAD_LOG.md.
+      - Write the phase handoff to scratch/handoffs/<phase>.yaml with owner notes, open questions, and carry-forward routings; completion applies it to workflow/status.yaml.
+      - Provide closeout_summary and optional closeout_content in the handoff; completion writes the closeout and THREAD_LOG.md entry.
   - id: protocols
     purpose: Capture event catalogs, state machines, persistence formats, and compatibility hazards.
     skill_path: findings/protocols/SKILL.md
@@ -102,8 +102,8 @@ phases:
       - Coverage and limits name inspected scope, skipped scope, evidence basis, and blind spots.
     handoff_requirements:
       - Run validation per workflow/VALIDATE.md. Append validation block to primary output.
-      - Update workflow/status.yaml.
-      - Append a summary entry to THREAD_LOG.md.
+      - Write the phase handoff to scratch/handoffs/<phase>.yaml with owner notes, open questions, and carry-forward routings; completion applies it to workflow/status.yaml.
+      - Provide closeout_summary and optional closeout_content in the handoff; completion writes the closeout and THREAD_LOG.md entry.
   - id: porting
     purpose: Synthesize architecture, contracts, and protocols into a reverse-engineering bundle oriented toward porting.
     skill_path: findings/porting/SKILL.md
@@ -139,8 +139,8 @@ phases:
       - The Source Index makes the bundle a self-contained compression boundary and identifies targeted deep-read triggers.
     handoff_requirements:
       - Run validation per workflow/VALIDATE.md. Append validation block to primary output.
-      - Update workflow/status.yaml.
-      - Append a summary entry to THREAD_LOG.md.
+      - Write the phase handoff to scratch/handoffs/<phase>.yaml with owner notes, open questions, and carry-forward routings; completion applies it to workflow/status.yaml.
+      - Provide closeout_summary and optional closeout_content in the handoff; completion writes the closeout and THREAD_LOG.md entry.
   - id: reimplementation-spec
     purpose: Produce the final language-agnostic reimplementation plan and acceptance spec.
     skill_path: findings/reimplementation-spec/SKILL.md
@@ -163,5 +163,5 @@ phases:
       - Lower-level findings are deep-read only when the porting bundle identifies a gap, conflict, missing acceptance detail, or defect rationale.
     handoff_requirements:
       - Run validation per workflow/VALIDATE.md. Append validation block to primary output.
-      - Update workflow/status.yaml.
-      - Append a summary entry to THREAD_LOG.md.
+      - Write the phase handoff to scratch/handoffs/<phase>.yaml with owner notes, open questions, and carry-forward routings; completion applies it to workflow/status.yaml.
+      - Provide closeout_summary and optional closeout_content in the handoff; completion writes the closeout and THREAD_LOG.md entry.

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

@@ -0,0 +1,6 @@
+# Version of the CodeCartographer release that shipped this .codecarto/
+# scaffold. The framework compares it against its own version to warn when a
+# 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

package/README.md

@@ -9,7 +9,7 @@
 [![npm version](https://img.shields.io/npm/v/codecartographer-pi.svg)](https://www.npmjs.com/package/codecartographer-pi)
 [![Node](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](package.json)
 
-> **Evidence-backed software cartography for coding agents.** Turn an unfamiliar repository into validated architecture, contracts, defects, and a reimplementation specification—then combine explicitly confirmed specifications with a product vision to produce a provenance-backed implementation plan.
+> **Understand an unfamiliar codebase with an AI agent — and get a validated spec you can rebuild from.** CodeCartographer turns a repository into layered architecture, behavioral contracts, defect findings, and a language-agnostic reimplementation spec, with each phase validated before the next one runs. Works with Pi, Claude Code, Cursor, Codex, or any MCP-capable agent.
 
 ```text
 ●  CodeCartographer
@@ -19,6 +19,24 @@
        ⎿ extracting behavioral contracts from server/index.ts…
 ```
 
+<p align="center">
+  <img src="docs/demo-dashboard-hero.png" alt="CodeCartographer dashboard — a mid-run pipeline with architecture and defect-scan phases complete, contracts in progress, per-phase token and tool-use telemetry.">
+</p>
+
+---
+
+## Why CodeCartographer
+
+Asking an LLM to "analyze this repo" loses context halfway through, hallucinates findings, and leaves no artifact the next session can pick up. CodeCartographer fixes three things:
+
+1. **The filesystem is the memory, not the conversation.** Each phase writes a smaller, templated, evidence-tagged artifact to `.codecarto/findings/`. Later phases re-read the specific upstream files they need. A new session — or a context compaction — picks up from `status.yaml` without losing progress.
+
+2. **Every phase is validated before the pipeline advances.** Completion criteria are real: a `FAIL` output stops the run. You can't accidentally build a reimplementation spec on top of hallucinated architecture.
+
+3. **The output is a spec, not a chat log.** The final `reimplementation-spec.md` is language-agnostic, module-inventoried, and carries acceptance scenarios plus known unknowns. Hand it to another agent to rebuild from.
+
+Every finding is tagged with an evidence level: `observed fact`, `strong inference`, `portability hazard`, or `open question`.
+
 ---
 
 ## At a glance
@@ -36,6 +54,8 @@
 
 Publish completed reimplementation specs from Pi or MCP, then run the `synthesis` pipeline to turn a product vision and explicitly confirmed library entries into a conflict-aware `project-plan.md` with a decision-level provenance ledger.
 
+> **If CodeCartographer saves you a day of codebase archaeology, star the repo** — it helps the next person find it.
+
 OpenAI Build Week reviewers: see the [new-vs-existing scope and one-command demo](docs/build-week-2026.md).
 
 ---
@@ -70,6 +90,8 @@ pi -e /absolute/path/to/CodeCartographer/extensions/codecarto/index.ts
 
 Use this when your coding agent isn't Pi — Claude Code, Codex, opencode, Cursor, Claude Desktop, or anything else that speaks MCP. The host drives the conversation and runs the LLM; CodeCartographer provides phase prompts, validation, and experimental library publish/list/reindex operations.
 
+> **30-second setup for Claude Code, Cursor, Codex, and Claude Desktop: see the [MCP quickstart](docs/mcp-quickstart.md).**
+
 ```bash
 npm install --global codecartographer-pi
 ```

package/dist/core/completion.js

@@ -54,6 +54,19 @@ export async function completeValidatedPhase(cwd, validation, sourceLabel) {
     if (handoff && handoff.phase_id !== validation.phaseId) {
         throw new Error(`Invalid handoff: phase_id ${handoff.phase_id} does not match ${validation.phaseId}`);
     }
+    // A phase that declares handoff_requirements must not complete without its
+    // handoff: silently proceeding writes empty carry_forward/open_questions and
+    // severs the cross-phase routing channel (issue #84). Phases without the
+    // declaration keep the lenient path for custom pipelines.
+    if (!handoff) {
+        const declaringPhase = resolvePhase(initialState, validation.phaseId);
+        if (declaringPhase?.handoff_requirements?.length) {
+            throw new Error(`Phase ${validation.phaseId} declares handoff_requirements, but no phase handoff exists at .codecarto/scratch/handoffs/${validation.phaseId}.yaml. `
+                + `Write the handoff first (see GUIDE.md and templates/phase-handoff.yaml): schema_version: 1, the exact phase_id, `
+                + `arrays for owner_notes, open_questions, carry_forward, carry_forward_closures, open_question_closures, post_pipeline, and decisions (omitted arrays default to empty), `
+                + `plus closeout_summary and optional closeout_content. Then re-run completion.`);
+        }
+    }
     if (handoff) {
         const activePhases = new Set(initialState.pipeline.phase_order);
         const sourceIndex = initialState.pipeline.phase_order.indexOf(validation.phaseId);

package/dist/core/prompts.js

@@ -4,6 +4,7 @@
 import { readdir } from "node:fs/promises";
 import { join } from "node:path";
 import { pathExists } from "./utils.js";
+import { describeScaffoldStaleness } from "./workspace.js";
 import { runPhasePreflight } from "./synthesis.js";
 export function describeEntry(entry) {
     const parts = [];
@@ -30,6 +31,7 @@ export function collectRoutedCarryForward(state, targetPhaseId) {
 export async function buildPhasePrompt(state, phase, forced, options = {}) {
     const preflight = options.preflight ?? await runPhasePreflight(state, phase);
     const synthesisWorkflow = state.pipeline.workflow_name === "evidence-backed-project-synthesis";
+    const handoffTemplateExists = await pathExists(join(state.workspaceDir, "templates", "phase-handoff.yaml"));
     const lines = [
         `Read .codecarto/GUIDE.md and continue the CodeCartographer workflow for the phase \`${phase.id}\`.`,
         synthesisWorkflow
@@ -39,8 +41,10 @@ export async function buildPhasePrompt(state, phase, forced, options = {}) {
         "Required reads before analysis:",
         "- .codecarto/GUIDE.md",
         "- .codecarto/workflow/status.yaml",
-        "- .codecarto/templates/phase-handoff.yaml",
     ];
+    if (handoffTemplateExists) {
+        lines.push("- .codecarto/templates/phase-handoff.yaml");
+    }
     const primaryOutput = phase.primary_output ? `.codecarto/${phase.primary_output}` : undefined;
     if (primaryOutput) {
         lines.push(`- ${primaryOutput} if it already exists (continue instead of duplicating work)`);
@@ -69,6 +73,21 @@ export async function buildPhasePrompt(state, phase, forced, options = {}) {
     if (await pathExists(decisionsPath)) {
         lines.push("- .codecarto/DECISIONS.md (numbered project decisions; new entries are appended in your closeout)");
     }
+    // Stale-scaffold warnings (issue #85): a workspace copied from an old
+    // template can contradict the runtime contract. Both surfaces render this
+    // prompt, so warn here rather than per-host.
+    const scaffoldWarnings = [];
+    if (!handoffTemplateExists) {
+        scaffoldWarnings.push(`.codecarto/templates/phase-handoff.yaml is missing — this scaffold predates the v0.12.0 handoff contract. Completion still requires a phase handoff at .codecarto/scratch/handoffs/${phase.id}.yaml; refresh the framework-owned files (GUIDE.md, templates/, workflow/VALIDATE.md, workflow/pipeline*.yaml) from the current CodeCartographer template, and trust this prompt over the workspace GUIDE.md where they disagree.`);
+    }
+    const staleness = describeScaffoldStaleness(state);
+    if (staleness)
+        scaffoldWarnings.push(staleness);
+    if (scaffoldWarnings.length > 0) {
+        lines.push("");
+        for (const warning of scaffoldWarnings)
+            lines.push(`WARNING: ${warning}`);
+    }
     const routed = collectRoutedCarryForward(state, phase.id);
     if (routed.length > 0) {
         lines.push("", `Items routed to \`${phase.id}\` for closure (carry_forward from earlier phases):`);

package/dist/core/types.d.ts

@@ -67,6 +67,8 @@ export type WorkspaceState = {
     pipelinePath: string;
     status: NormalizedStatus;
     pipeline: PipelineFile;
+    /** From workflow/scaffold-version.yaml; undefined for scaffolds that predate the marker. */
+    scaffoldVersion?: string;
 };
 export type ValidationOverall = "PASS" | "PASS WITH GAPS" | "FAIL" | "MISSING";
 export type ValidationResult = {

package/dist/core/workspace.d.ts

@@ -2,6 +2,15 @@ import type { PhaseHandoff, WorkspaceState } from "./types.ts";
 export declare const packagedWorkspaceDir: string;
 export declare const PACKAGE_VERSION: string;
 export declare function getWorkspaceState(cwd: string): Promise<WorkspaceState | null>;
+/**
+ * Human-readable staleness notice for the workspace's .codecarto/ scaffold,
+ * or null when the scaffold matches the running framework. A missing marker
+ * means the scaffold was copied from a release that predates it — those
+ * scaffolds may also predate the v0.12.0 handoff contract, whose GUIDE and
+ * pipelines instruct the exact opposite completion protocol. Warn, never
+ * fail: unversioned workspaces must keep working.
+ */
+export declare function describeScaffoldStaleness(state: WorkspaceState): string | null;
 export declare function updateStatusAtomically(cwd: string, updater: (state: WorkspaceState) => Promise<{
     state: WorkspaceState;
     handoff?: PhaseHandoff;

package/dist/core/workspace.js

@@ -76,6 +76,17 @@ export async function getWorkspaceState(cwd) {
     }
     const pipeline = await loadYamlFile(pipelinePath);
     const status = normalizeStatus(rawStatus, pipeline, pipelineRelativePath, cwd);
+    const scaffoldVersionPath = join(workspaceDir, "workflow", "scaffold-version.yaml");
+    let scaffoldVersion;
+    if (await pathExists(scaffoldVersionPath)) {
+        const marker = await loadYamlFile(scaffoldVersionPath);
+        if (typeof marker.scaffold_version === "string" && marker.scaffold_version.trim()) {
+            scaffoldVersion = marker.scaffold_version.trim();
+        }
+        else if (typeof marker.scaffold_version === "number") {
+            scaffoldVersion = String(marker.scaffold_version);
+        }
+    }
     return {
         cwd,
         workspaceDir,
@@ -83,8 +94,51 @@ export async function getWorkspaceState(cwd) {
         pipelinePath,
         pipeline,
         status,
+        ...(scaffoldVersion !== undefined && { scaffoldVersion }),
     };
 }
+// Numeric x.y.z comparison; null when either side is not a plain dotted triple.
+function compareDottedVersions(a, b) {
+    const parse = (version) => {
+        const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(version.trim());
+        return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : null;
+    };
+    const left = parse(a);
+    const right = parse(b);
+    if (!left || !right)
+        return null;
+    for (let i = 0; i < 3; i++) {
+        if (left[i] !== right[i])
+            return left[i] < right[i] ? -1 : 1;
+    }
+    return 0;
+}
+/**
+ * Human-readable staleness notice for the workspace's .codecarto/ scaffold,
+ * or null when the scaffold matches the running framework. A missing marker
+ * means the scaffold was copied from a release that predates it — those
+ * scaffolds may also predate the v0.12.0 handoff contract, whose GUIDE and
+ * pipelines instruct the exact opposite completion protocol. Warn, never
+ * fail: unversioned workspaces must keep working.
+ */
+export function describeScaffoldStaleness(state) {
+    const scaffold = state.scaffoldVersion;
+    if (!scaffold) {
+        return "This workspace's .codecarto/ scaffold has no workflow/scaffold-version.yaml marker (introduced after v0.12.11), so its framework-owned files (GUIDE.md, templates/, workflow/ pipelines and VALIDATE.md) may predate the v0.12.0 handoff contract. Refresh them from the packaged CodeCartographer template.";
+    }
+    const comparison = compareDottedVersions(scaffold, PACKAGE_VERSION);
+    if (comparison === 0)
+        return null;
+    if (comparison === null) {
+        return scaffold === PACKAGE_VERSION
+            ? null
+            : `This workspace's scaffold version (${scaffold}) does not match the running framework (${PACKAGE_VERSION}). Refresh the framework-owned files (GUIDE.md, templates/, workflow/) from the packaged template.`;
+    }
+    if (comparison < 0) {
+        return `This workspace's scaffold (v${scaffold}) is older than the running framework (v${PACKAGE_VERSION}). Refresh the framework-owned files (GUIDE.md, templates/, workflow/) from the packaged template to pick up pipeline and template fixes.`;
+    }
+    return `This workspace's scaffold (v${scaffold}) is newer than the running framework (v${PACKAGE_VERSION}). Upgrade CodeCartographer to at least v${scaffold}.`;
+}
 export async function updateStatusAtomically(cwd, updater) {
     const workspaceDir = join(cwd, ".codecarto");
     const statusPath = join(workspaceDir, "workflow", "status.yaml");

package/dist/extensions/codecarto/index.js

@@ -8,7 +8,7 @@ import { narrateDashboard } from "./dashboard-narrator.js";
 import { writeDashboard } from "./dashboard-writer.js";
 import { parseNextFlags } from "./next-flags.js";
 import { phaseCompactionExtension } from "./phase-compaction.js";
-import { buildPhasePrompt, buildSkillPrompt, buildValidationSummary, canonicalPath, computePerPhaseTotals, computeTotals, createEmptyStatus, DEFAULT_PIPELINE_PATH, deriveSlug, discoverLibrary, getNextEligiblePhase, getPipelineLabel, getWorkspaceState, isWithinPathResolved, listSkillNames, loadCodecartoConfig, loadUsage, loadYamlFile, normalizeForComparison, packagedWorkspaceDir, pathExists, PACKAGE_VERSION, PhasePreflightError, PIPELINE_ALIASES, publishEntry, resolvePhase, resolvePipelineChoice, runPhasePreflight, stringifySimpleYaml, switchPipeline, validatePhaseOutput, writeLibraryConfig, } from "../../core/index.js";
+import { buildPhasePrompt, buildSkillPrompt, buildValidationSummary, canonicalPath, computePerPhaseTotals, computeTotals, createEmptyStatus, DEFAULT_PIPELINE_PATH, describeScaffoldStaleness, deriveSlug, discoverLibrary, getNextEligiblePhase, getPipelineLabel, getWorkspaceState, isWithinPathResolved, listSkillNames, loadCodecartoConfig, loadUsage, loadYamlFile, normalizeForComparison, packagedWorkspaceDir, pathExists, PACKAGE_VERSION, PhasePreflightError, PIPELINE_ALIASES, publishEntry, resolvePhase, resolvePipelineChoice, runPhasePreflight, stringifySimpleYaml, switchPipeline, validatePhaseOutput, writeLibraryConfig, } from "../../core/index.js";
 import { initLibrary } from "../../core/library.js";
 import { resolveUserConfigPath } from "../../core/orchestrator-config.js";
 const STATUS_WIDGET_ID = "codecarto-widget";
@@ -71,6 +71,9 @@ function buildStatusLines(state, extraLines = []) {
         `Post-pipeline work: ${postPipelinePending} pending`,
         `Next: ${nextAction}`,
     ];
+    const scaffoldNotice = describeScaffoldStaleness(state);
+    if (scaffoldNotice)
+        lines.push(`Scaffold: ${scaffoldNotice}`);
     if (extraLines.length > 0) {
         lines.push("", ...extraLines);
     }

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

@@ -78,6 +78,11 @@ export declare function handleSkill(args: {
     }>;
     structuredContent?: Record<string, unknown>;
 }>;
+export declare function readSpecArg(args: {
+    spec?: unknown;
+    spec_path?: unknown;
+    cwd?: unknown;
+}, allowedRoots: string[]): Promise<string>;
 export declare function handlePublish(args: Record<string, unknown>): Promise<{
     content: Array<{
         type: "text";

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, getNextEligiblePhase, getPipelineLabel, getWorkspaceState, isValidSlug, 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, 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";
@@ -118,7 +118,8 @@ export async function handleStatus(args) {
     const currentOpenQuestions = currentPhase === "complete" ? 0 : state.status.phases[currentPhase]?.open_questions.length ?? 0;
     const terminalOpenQuestions = Object.values(state.status.phases).reduce((sum, phase) => sum + (phase.open_questions?.length ?? 0), 0);
     const postPipelinePending = state.status.post_pipeline.filter((entry) => entry.status !== "resolved").length;
-    const summary = [
+    const scaffoldNotice = describeScaffoldStaleness(state);
+    const summaryLines = [
         `Phase: ${currentPhase}`,
         `Pipeline state: ${currentPhase === "complete" ? "complete" : "in progress"}`,
         `Pipeline: ${getPipelineLabel(state.status.pipeline)} (${state.status.pipeline})`,
@@ -127,8 +128,12 @@ export async function handleStatus(args) {
         `Carry-forward (pipeline phases): ${totalCarryForward}`,
         `Post-pipeline work: ${postPipelinePending} pending`,
         `Next: ${state.status.next_actions[0] ?? (nextPhase ? `Begin ${nextPhase.id}` : "All phases complete.")}`,
-    ].join("\n");
+    ];
+    if (scaffoldNotice)
+        summaryLines.push(`Scaffold: ${scaffoldNotice}`);
+    const summary = summaryLines.join("\n");
     return textResult(summary, {
+        ...(scaffoldNotice ? { scaffoldNotice } : {}),
         currentPhase,
         pipeline: state.status.pipeline,
         pipelineLabel: getPipelineLabel(state.status.pipeline),
@@ -325,16 +330,33 @@ function buildGenerationFromArg(model_metadata) {
         out.notes = m.notes;
     return out;
 }
-async function readSpecArg(args) {
+// `allowedRoots` is deliberately required and must be non-empty whenever
+// spec_path is used. It previously defaulted to `[]`, which made containment
+// opt-in: a caller that omitted it would read any absolute path the client
+// asked for, silently reopening the arbitrary-file-read class of bug fixed in
+// v0.12.11. Containment is now the default posture and an empty root set is a
+// programming error rather than a bypass.
+export async function readSpecArg(args, allowedRoots) {
     if (typeof args.spec === "string" && args.spec.length > 0)
         return args.spec;
     if (typeof args.spec_path === "string" && args.spec_path.length > 0) {
         if (!isAbsolute(args.spec_path)) {
             throw new McpError(ErrorCode.InvalidParams, `spec_path must be absolute, got: ${args.spec_path}`);
         }
+        if (!Array.isArray(allowedRoots) || allowedRoots.length === 0) {
+            throw new McpError(ErrorCode.InternalError, "refusing to read spec_path without a containment root — this is a caller bug, not a client error");
+        }
         if (!(await pathExists(args.spec_path))) {
             throw new McpError(ErrorCode.InvalidParams, `spec_path does not exist: ${args.spec_path}`);
         }
+        // Enforce path containment: spec_path must be within an allowed root
+        // (cwd's .codecarto/ or the configured library path) to prevent
+        // arbitrary file reads.
+        const resolvedSpecPath = await canonicalPath(args.spec_path);
+        const withinAllowed = await Promise.all(allowedRoots.map((root) => isWithinPathResolved(resolvedSpecPath, root)));
+        if (!withinAllowed.some((result) => result)) {
+            throw new McpError(ErrorCode.InvalidParams, `spec_path must be within the workspace (.codecarto/) or the configured library path. Got: ${args.spec_path}`);
+        }
         return readFile(args.spec_path, "utf8");
     }
     throw new McpError(ErrorCode.InvalidParams, "Either spec (inline content) or spec_path (absolute file path) is required");
@@ -375,7 +397,12 @@ export async function handlePublish(args) {
     if (!marker) {
         throw new McpError(ErrorCode.InvalidParams, `No CodeCartographer library at ${libraryPath} (missing .codecarto-library marker). Create one before publishing.`);
     }
-    const spec = await readSpecArg(args);
+    // Build allowed roots for spec_path containment: workspace .codecarto/ and library path
+    const allowedRoots = [libraryPath];
+    if (typeof args.cwd === "string" && args.cwd.trim() !== "") {
+        allowedRoots.push(join(args.cwd.trim(), ".codecarto"));
+    }
+    const spec = await readSpecArg(args, allowedRoots);
     if (typeof args.source_repo !== "string" || args.source_repo.trim() === "") {
         throw new McpError(ErrorCode.InvalidParams, "source_repo is required");
     }

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "codecartographer-pi",
-  "version": "0.12.10",
+  "version": "0.13.0",
   "mcpName": "io.github.HuginnIndustries/codecartographer",
-  "description": "Evidence-backed reverse engineering and human-gated software planning for Pi and MCP coding agents.",
+  "description": "Turn an unfamiliar codebase into a validated reimplementation spec, then synthesize confirmed specs and a product vision into a traceable plan.",
   "type": "module",
   "keywords": [
     "pi-package",
@@ -13,7 +13,12 @@
     "mcp",
     "software-planning",
     "code-analysis",
-    "synthesis"
+    "synthesis",
+    "codebase",
+    "ai-agent",
+    "context-engineering",
+    "code-understanding",
+    "spec-driven"
   ],
   "license": "MIT",
   "author": "James Sesler",
@@ -59,5 +64,8 @@
   },
   "devDependencies": {
     "typescript": "^5.9.3"
+  },
+  "overrides": {
+    "undici": "^8.10.0"
   }
 }