codecartographer-pi 0.12.11 → 0.14.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.14.0