codecartographer-pi 0.14.1 → 0.16.0

package/.codecarto/BACKLOG.md

@@ -9,23 +9,15 @@ of the change would look like.
 
 ---
 
-## B1. Spike template + first-class spike concept
+## B1. Spike template + first-class spike concept — SHIPPED in smallest viable form (v0.15.0, issue #101)
 
-**Raised by:** `Run three Thaumaturge implementation spikes.txt`, `Apply 20 spec deltas to Thaumaturge.txt`, `Agent on protocols phase - protocols.txt` (3 agents)
-
-**Why deferred:** A spike template would land cleanly, but "first-class spike concept" implies workflow machinery (a `spikes/` directory convention, a validation rule for spike outputs, status.yaml fields for spike tracking). The 2026-05-02 pass is already changing the closeouts pattern, the open_questions schema, and the orchestrator-maintained artifacts list. Adding spike machinery on top risks too much surface change in one revision.
-
-**Smallest viable form:** `templates/spike-report.md` skeleton with sections for Goal, Method, Measurements, Findings, Recommended Deltas. No workflow machinery; spikes stay a per-project convention initially. Status.yaml integration deferred until a project demonstrates the need.
+Landed exactly as scoped: `templates/spike-report.md` (Goal / Method / Measurements / Findings / Recommended Deltas) with the `scratch/spikes/<spike-id>/<scenario>.md` convention documented in GUIDE.md and the spec-delta-application skill. No workflow machinery; spikes stay registered as `post_pipeline` entries (`kind: spike`), their findings flow to the spec through spec-delta-application and to `status.yaml` through `codecarto_amend`. Status.yaml spike tracking remains deferred until a project demonstrates the need.
 
 ---
 
-## B2. Amendments mechanic (`findings/amendments/` directory)
-
-**Raised by:** `Run three Thaumaturge implementation spikes.txt`, `Agent on protocols phase - protocols.txt` (2 agents — under threshold but persistent)
-
-**Why deferred:** "Phase outputs can't correct prior phases" is a real gap, but `carry_forward` (introduced in this pass) already covers the most common case (forward-routing a deferred item). True back-amendment (a later phase says "the architecture map is wrong about X") needs more design — should it edit the prior output? Append a "superseded by" marker? Live in a parallel directory? The shape isn't obvious enough to land safely.
+## B2. Amendments mechanic — SHIPPED (v0.15.0, issue #99)
 
-**Smallest viable form:** A pre-reimpl-spec "reconciliation" pass that surfaces contradictions across primary outputs. Less ambitious than a full amendments directory; uses existing artifacts.
+Landed as `codecarto_amend` over `scratch/amendments/<slug>.yaml` (see `templates/amendment.yaml`): post-pipeline open-question closures and post_pipeline backlog retirement, applied to `workflow/status.yaml` under the completion lock with an amendment closeout and THREAD_LOG entry. The narrower back-amendment question ("a later phase says a prior output is wrong") remains open — a real run handled it with a correction section in the later report plus a delta-application pass, which worked; promote that pattern only if it recurs.
 
 ---
 

package/.codecarto/GUIDE.md

@@ -12,43 +12,40 @@ Work in explicit phases. Do not try to do everything at once.
 
 ## Roles
 
-CodeCartographer distinguishes two roles. They are different jobs, often held by different threads, and the framework's discipline depends on both existing.
+CodeCartographer distinguishes two roles. They are different jobs — but they are not different threads by default, and the framework's discipline depends on the first one existing.
 
-**Implementing session.** One phase or one module of work, fresh thread, follows a SKILL.md and a template, validates, writes a closeout, ends. The bulk of the framework — phases, skills, templates, validation gates — is written for this role. The "You are an LLM assistant" framing in "What This Is" addresses this role.
+**Orchestrator.** The persistent chat driving the run — normally the very session reading this guide. The role is defined by its **duties**, not by who executes phases:
 
-**Orchestrator.** One persistent thread (typically the first LLM the user points at the project) paired with the human user. The orchestrator holds cross-session context, drafts implementing-session prompts from prior closeouts, curates `CONVENTIONS.md` and `DECISIONS.md` (promoting patterns when they recur), and gates strategic forks the user makes. **The orchestrator does not execute pipeline phases itself** — that is the implementing-session role. The orchestrator's deliverables are *prompts and curated artifacts*, not phase outputs. When the orchestrator finds itself reading a SKILL.md or producing a `findings/<phase>/<primary-output>.md`, it has slipped into the implementing-session role and should stop, draft a prompt, and hand off instead. Without an orchestrator, the framework still works phase-by-phase but cross-cutting conventions and decisions don't accumulate, and each implementing session re-discovers what prior sessions established.
+- **Curate `CONVENTIONS.md` and `DECISIONS.md`**: promote patterns when they recur; append cross-cutting decisions as they land.
+- **Re-triage open questions at every phase boundary.** A question's `kind` label is itself a claim that needs evidence: before accepting `needs-maintainer-decision` or `needs-runtime-test`, re-test whether the question has become answerable by reading. A mislabeled question suppresses verification for every later phase (the `orchestration` guide topic records a real four-phase failure).
+- **Sweep for contradictions** between the incoming phase's required reads and earlier phases' `owner_notes`. A measured fact that contradicts a summarized claim is a gap to route, not a nuance to smooth over.
+- **Route gaps**: confirm each completed phase's declared secondary outputs were written or explicitly routed, and that handoff `decisions` deferring work landed somewhere a later phase will actually see.
+- **Gate strategic forks** with the user: pipeline switches, opinionated-vs-agnostic specs, scope changes.
 
-If you are an LLM reading this guide for the first time on a project where `CONVENTIONS.md` and `DECISIONS.md` are unwritten (still showing template content) and `closeouts/` is empty, **see "First-Time Project Setup" below before starting any phase.**
+**Phase executor.** Whoever performs one phase against its SKILL.md and template: reads the sources, writes the primary output, validates, writes the handoff. The bulk of the framework — phases, skills, templates, validation gates — is written for this role; the "You are an LLM assistant" framing in "What This Is" addresses it.
 
-## First-Time Project Setup
+How the roles map onto threads is an **execution strategy**, chosen per run:
+
+- **Inline** — the orchestrator executes phases itself, wearing both hats. This is the normal mode for a single chat driving the MCP tools. The duties above happen at each phase boundary: after completion, before the next phase begins.
+- **Delegated** — the orchestrator dispatches each phase to a separate execution context (the Pi extension's phase sub-agents, or fresh threads the user spins up from drafted prompts) and reviews each closeout. Same duties, same boundary; only the executor differs, keeping phase context out of the orchestrator's window.
 
-If this is the first LLM to touch this project — no closeouts in `closeouts/`, `CONVENTIONS.md` and `DECISIONS.md` still showing template skeletons, `workflow/status.yaml` at defaults — stop before starting any pipeline phase and have a one-time role conversation with the user. Combine the explanation and the ask in one structured prompt:
+Either strategy is full orchestration. The **session-by-session fallback** — each phase in an isolated session, nobody holding the cross-phase duties — is not: `CONVENTIONS.md` stays empty, proposals die in closeout prose, and mislabeled questions go unchallenged. Use it only when the user explicitly declines orchestration or the driving model cannot sustain cross-phase context, and record the reason in the first handoff's `owner_notes`.
 
-> "I see this is a fresh CodeCartographer-equipped project. Before I start the analysis, one one-time decision: would you like me to take on the **orchestrator role** for this project, or work session-by-session?
->
-> The orchestrator role means I'd hold cross-session context across the entire project — drafting prompts for implementation threads you'll spin up, curating two project-wide files (`CONVENTIONS.md` for patterns and `DECISIONS.md` for cross-cutting calls), and gating the strategic forks where you'd want to make a call.
->
-> How it works in practice: this thread becomes the orchestrator; you spin up fresh threads for each implementation session using the prompts I draft, run them, and paste the closeout report back here. I update `CONVENTIONS.md`/`DECISIONS.md` and prepare the next prompt. The framework's discipline compounds across sessions instead of being reinvented each time.
->
-> One operational tip: if your coding agent supports renaming and pinning threads, rename this thread to "Orchestrator" and pin it. Keeps it organized and quick to find when you switch back from implementation threads.
->
-> The alternative is session-by-session work with no cross-session context — the framework still works phase-by-phase, but `CONVENTIONS.md` stays empty and each session has to re-derive patterns from prior closeouts. Better for one-off audits; worse for long-running multi-module projects.
->
-> Which would you like?"
+If you are an LLM reading this guide for the first time on a project where `CONVENTIONS.md` and `DECISIONS.md` are missing or unwritten (still showing template content) and `closeouts/` is empty, **see "First-Time Project Setup" below before starting any phase.**
 
-If the user accepts the orchestrator role:
+## First-Time Project Setup
 
-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. 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 this is the first LLM to touch this project — no closeouts in `closeouts/`, `CONVENTIONS.md` and `DECISIONS.md` missing or still template skeletons, `workflow/status.yaml` at defaults — **adopt the orchestrator role by default.** Do not interview the user about whether orchestration should happen. Concretely:
 
-If the user declines:
+1. `codecarto_init` (and Pi's `/codecarto-init`) seeds `CONVENTIONS.md` and `DECISIONS.md` from their templates. On an older workspace where they are missing, initialize them from `templates/conventions-template.md` and `templates/decisions-template.md` yourself (skeletons only — they fill as patterns and decisions accumulate).
+2. Confirm the project name only if the repository directory name is wrong for the project; `project_name` otherwise resolves and persists automatically on the first completion.
+3. Note the run's execution strategy (inline or delegated) in the first phase handoff's `owner_notes`.
 
-1. Note in `THREAD_LOG.md` that the project runs in degraded no-orchestrator mode.
-2. Proceed phase-by-phase as a standalone implementing session.
-3. `CONVENTIONS.md` and `DECISIONS.md` stay as templates; closeouts accumulate but cross-cutting promotion doesn't happen.
+Choose the execution strategy from the situation rather than asking: a single chat driving the MCP tools runs **inline**; a host with phase sub-agent dispatch (the Pi extension) runs **delegated**. Ask the user only when their instructions genuinely conflict with both defaults — and never under `/codecarto-next --auto`, which must not block on questions.
 
-If the user is ambivalent, default to recommending the orchestrator path for any project expected to span more than one phase or module — the framework's compounding-discipline benefits are real and the cost is just paste-and-react work for the user.
+Fall back to session-by-session mode only if the user explicitly declines orchestration or the driving model cannot hold cross-phase context. Record the reason in the first handoff's `owner_notes`, and expect the costs named under §Roles.
+
+One operational tip for delegated runs: if your coding agent supports renaming and pinning threads, rename the orchestrator thread to "Orchestrator" and pin it — quick to find when you switch back from phase threads.
 
 ## First Read For New Sessions
 
@@ -82,12 +79,12 @@ Some files in this workspace are **read-only instructions** and must not be modi
 | 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. |
+| Phase handoff (read-write) | `scratch/handoffs/<phase>.yaml` | Phase executors 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. |
-| Conventions (orchestrator-maintained) | `CONVENTIONS.md` | Cross-cutting patterns promoted to project-wide invariants. Implementing sessions propose; the orchestrator writes. |
-| Decisions (orchestrator-maintained, append-only) | `DECISIONS.md` | Numbered log of decisions that diverge from spec, prompt, or obvious-default. Appended at session close. |
+| Conventions (orchestrator-maintained) | `CONVENTIONS.md` | Cross-cutting patterns promoted to project-wide invariants. Phase executors propose; the orchestrator promotes at the phase boundary — in inline runs, the same chat changing hats. |
+| Decisions (orchestrator-maintained, append-only) | `DECISIONS.md` | Numbered log of decisions that diverge from spec, prompt, or obvious-default. Completion appends each handoff's `decisions` under `## Completion log`; the orchestrator may re-file entries into categories. |
 | Backlog (read-write) | `BACKLOG.md` | Deferred items with rationale. |
-| Scratch (read-write) | `scratch/*` | Working notes; `scratch/checkpoints/<phase>.md` is the durable in-phase continuation checkpoint until the phase validates. |
+| Scratch (read-write) | `scratch/*` | Working notes; `scratch/checkpoints/<phase>.md` is the durable in-phase continuation checkpoint until the phase validates; `scratch/spikes/<spike-id>/<scenario>.md` holds spike reports (`templates/spike-report.md`); `scratch/amendments/<slug>.yaml` holds post-pipeline amendments (`templates/amendment.yaml`). |
 
 If you are uncertain whether a file should be modified, treat it as read-only.
 
@@ -156,10 +153,10 @@ If a primary and a secondary output describe the same topic (e.g., the architect
 
 Two cross-cutting files compound across sessions and live at the `.codecarto/` top level:
 
-- **`CONVENTIONS.md`** — cross-cutting patterns that have been promoted to project-wide invariants (e.g., a shared discriminated-union return shape, a tripwire-naming vocabulary, a verbatim-spec-quote discipline). Implementing sessions propose additions in their closeout; the orchestrator promotes them. New conventions land when a third independent session reaches for the same pattern, or when a spec/feedback corpus identifies a project-wide invariant.
-- **`DECISIONS.md`** — append-only numbered log of cross-cutting decisions that diverge from spec, prompt, or obvious-default. Each entry: `D<NNN> | <one-liner> | <source-session> | <rationale-pointer>`. Categories partition the namespace (type system, toolchain, module-internal patterns, lifted primitives, etc.).
+- **`CONVENTIONS.md`** — cross-cutting patterns that have been promoted to project-wide invariants (e.g., a shared discriminated-union return shape, a tripwire-naming vocabulary, a verbatim-spec-quote discipline). Completion **stages** each handoff's `proposed_conventions` under `## Pending proposals`; the orchestrator promotes a staged entry into a numbered convention (or removes it with a note) at the phase boundary. New conventions land when a third independent phase reaches for the same pattern, or when a spec/feedback corpus identifies a project-wide invariant.
+- **`DECISIONS.md`** — append-only numbered log of cross-cutting decisions that diverge from spec, prompt, or obvious-default. Each entry: `D<NNN> | <one-liner> | <source-closeout> | <rationale-pointer>`. Completion **appends** each handoff's `decisions` as rows under `## Completion log`, numbering shared with the orchestrator-curated category sections; the orchestrator may re-file entries into categories later.
 
-Both files are skeletons in the framework templates (`templates/conventions-template.md`, `templates/decisions-template.md`) and become project-specific artifacts when a session writes to them. They are *orchestrator-maintained*, not implementer-edited — implementing sessions propose, the orchestrator promotes.
+Both files are seeded from the framework templates (`templates/conventions-template.md`, `templates/decisions-template.md`) at init and become project-specific artifacts as entries accumulate. The bookkeeping half is mechanized — completion collects, so proposals can never be stranded in closeout prose — while promotion stays judged: phase executors propose, the orchestrator promotes, and in an inline run the same chat does both at the phase boundary.
 
 ## Context Budget
 
@@ -210,6 +207,8 @@ post_pipeline:
 
 `kind` is one of: `needs-runtime-test`, `needs-maintainer-decision`, `needs-spec-ruling`, `defer-to-phase`, `needs-fixture-capture`, or a post-pipeline work kind such as `spike` or `amendment`. Every new `carry_forward.target_phase` must be an ID in the active pipeline. Every `post_pipeline` entry requires a stable ID. Open questions should carry a stable `id` (e.g. `q-loadconfig-ambiguity`); if omitted, the framework auto-assigns one. When a later phase resolves an open question, list its id in `open_question_closures` to remove it from all phases. The downstream phase records resolved carry-forward IDs in `carry_forward_closures`; completion removes those entries atomically.
 
+After the pipeline completes, the handoff channel closes with it. Post-pipeline resolutions — an open question answered on evidence, a finished `post_pipeline` backlog item — are applied with an **amendment**: write `scratch/amendments/<slug>.yaml` (see `templates/amendment.yaml`) and run `codecarto_amend`. It updates `workflow/status.yaml` under the same lock completion uses and writes an amendment closeout plus THREAD_LOG entry. Never hand-edit `status.yaml` for this; amendments are refused while the pipeline is still running, so the two channels cannot race.
+
 ## Phase Selection Logic
 
 1. Load the active pipeline YAML (see `pipeline` field in `workflow/status.yaml`).
@@ -238,11 +237,11 @@ When a session starts:
 When a session finishes durable work:
 
 1. Run the validation step described in `workflow/VALIDATE.md`. Append a validation block to the output.
-2. Write `scratch/handoffs/<phase>.yaml` with `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`. Omitted arrays default to empty; malformed collection shapes fail completion.
+2. Write `scratch/handoffs/<phase>.yaml` with `schema_version: 1`, the exact `phase_id`, arrays for `owner_notes`, `open_questions`, `carry_forward`, `carry_forward_closures`, `open_question_closures`, `post_pipeline`, `decisions`, and `proposed_conventions`, plus `closeout_summary` and optional multiline `closeout_content`. Omitted arrays default to empty; malformed collection shapes fail completion.
 3. Record 2-3 key observations in the handoff's `owner_notes` (e.g., row counts, notable decisions, scope of analysis). Do not provide a canonical timestamp; the host clock owns timestamps.
 4. Run `/codecarto-complete` (or `codecarto_complete`). The framework atomically updates `workflow/status.yaml`, writes or updates one canonical closeout, and appends one idempotent `THREAD_LOG.md` entry. Do not edit those files directly.
 5. Store the durable output in the declared `findings/` path.
-6. If the session made cross-cutting decisions or discovered project-wide invariants, propose additions to `CONVENTIONS.md` (in the closeout's "Proposed Conventions" section) and `DECISIONS.md` (numbered entries in the closeout's "Decisions Beyond Prompt" section). The orchestrator promotes these to the canonical files.
+6. If the session made cross-cutting decisions or discovered project-wide invariants, record them in the handoff: `decisions` entries are appended to `DECISIONS.md` by completion (numbered `D<NNN>` rows under `## Completion log`), and `proposed_conventions` entries are staged in `CONVENTIONS.md` under `## Pending proposals`. Promoting a staged proposal into a numbered convention — or removing it with a note — is the orchestrator duty at the next phase boundary; in an inline run, do it yourself before starting the next phase.
 
 ### Strategic Alignment Hook (before synthesis)
 
@@ -270,7 +269,7 @@ These rules combine framework enforcement with explicit agent discipline:
 - The primary outputs are listed in the deliverables table above.
 - Secondary outputs are created only when needed, using `mode: append`.
 - Completion owns `closeouts/<YYYY-MM-DD>-<phase-or-module>.md` and `THREAD_LOG.md`; implementing sessions supply closeout content through their phase handoff.
-- Cross-cutting patterns go in `CONVENTIONS.md`; numbered cross-cutting decisions go in `DECISIONS.md`. Both are orchestrator-maintained — implementing sessions propose in their closeout, the orchestrator promotes.
+- Cross-cutting patterns go in `CONVENTIONS.md`; numbered cross-cutting decisions go in `DECISIONS.md`. Both are orchestrator-maintained — phase executors propose in their closeout, the orchestrator promotes at the phase boundary.
 - Do not store durable findings only in `THREAD_LOG.md`. The log is an index, not the primary artifact store.
 
 ## Folder Layout

package/.codecarto/NEW_THREAD_BLURB.md

@@ -4,7 +4,7 @@ Source code under evaluation: `../` (this repository — everything outside `.co
 
 All CodeCartographer files are inside `.codecarto/`. Paths below are relative to `.codecarto/`.
 
-**First-time project?** If `CONVENTIONS.md` and `DECISIONS.md` are still template skeletons and `closeouts/` is empty, see GUIDE.md §Roles and §First-Time Project Setup before reading the rest. The first LLM on a project takes a one-time role decision with the user (orchestrator vs session-by-session).
+**First-time project?** If `CONVENTIONS.md` and `DECISIONS.md` are missing or still template skeletons and `closeouts/` is empty, see GUIDE.md §Roles and §First-Time Project Setup before reading the rest. The chat driving the run **is the orchestrator by default** — seed `CONVENTIONS.md`/`DECISIONS.md` and pick an execution strategy (inline or delegated) from the situation; do not interview the user about whether orchestration should happen.
 
 Read these in order before doing work:
 
@@ -26,11 +26,11 @@ Where to store results:
 After completing work:
 
 1. Run validation per `workflow/VALIDATE.md`. Append the validation block to the output.
-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.
+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`, `decisions`, and `proposed_conventions`, 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.
+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. Promoting them to `DECISIONS.md` and `CONVENTIONS.md` is the orchestrator duty at the phase boundary — in an inline run, do it yourself before the next phase.
 
 ## File-System Sync Warning
 

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

@@ -9,7 +9,7 @@ Use this skill when:
 
 - The pipeline has produced a complete `findings/reimplementation-spec/reimplementation-spec.md` (the spec is `complete` in status.yaml).
 - A separate source has surfaced changes the spec should absorb. Common sources:
-  - **Spike reports** (`spikes/<spike-id>/<scenario>.md` plus a `CONSOLIDATED-DELTA.md`).
+  - **Spike reports** (`scratch/spikes/<spike-id>/<scenario>.md`, written from `templates/spike-report.md`, plus an optional `CONSOLIDATED-DELTA.md` when several scenarios merge).
   - **Defect-scan re-runs** that find corrections to spec text.
   - **Implementation discoveries** that contradict spec assumptions (e.g., a wire format the spec misread).
   - **Maintainer rulings** that close prior open questions.
@@ -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`.
-- 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.
+- If a delta resolved an `open_questions` entry (or finished a `post_pipeline` backlog item), apply it: write `scratch/amendments/<slug>.yaml` (see `templates/amendment.yaml`) listing the closures, then run `codecarto_amend`. It updates `status.yaml` under the completion lock and writes the amendment closeout — never hand-edit `status.yaml`, which is framework-owned. Without the MCP server, record the intended amendment file in the closeout for the next MCP-capable session to apply.
 - 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/amendment.yaml

@@ -0,0 +1,17 @@
+# Post-pipeline amendment schema v1. Copy to scratch/amendments/<slug>.yaml,
+# then run codecarto_amend (MCP) with the slug. Refused while the pipeline is
+# incomplete — mid-pipeline resolutions belong in the phase handoff
+# (open_question_closures / carry_forward_closures).
+schema_version: 1
+# Open-question ids resolved on evidence after the pipeline completed;
+# removed from every phase in workflow/status.yaml.
+open_question_closures: []
+# Finished post-pipeline backlog item ids; removed from status.yaml's
+# post_pipeline list (the amendment closeout records the closure).
+post_pipeline_closures: []
+# Durable observations worth keeping with the amendment record.
+notes: []
+closeout_summary: ""
+# Optional full closeout Markdown; generated from the applied closures when omitted.
+closeout_content: |-
+  # Amendment — <slug>

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

@@ -8,16 +8,17 @@
   Every new session reads this file and either honors these conventions or documents why it
   diverges.
 
-  This file is **orchestrator-maintained**. Implementing sessions should not edit it without
-  explicit invitation; they propose additions in their session closeout and the orchestrator
-  promotes them.
+  This file is **orchestrator-maintained**. Phase executors propose additions in their session
+  closeout; the orchestrator promotes them at the phase boundary. In an inline run the same chat
+  does both — the rule is about *when* (between phases, deliberately), not about which thread.
 -->
 
 Cross-cutting patterns promoted to project-wide invariants. Every session reads this file at start
 and either honors these conventions or documents why it diverges.
 
-This file is **orchestrator-maintained**. Implementing sessions propose additions in their
-closeout's "Proposed Conventions" section; the orchestrator promotes them here.
+This file is **orchestrator-maintained**. Phase executors propose additions in their closeout's
+"Proposed Conventions" section; the orchestrator promotes them here at the phase boundary — in an
+inline run, the same chat changing hats between phases.
 
 ## How conventions get added
 

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

@@ -1,25 +1,27 @@
 # Decisions
 
 <!--
-  Project-level skeleton. Copy this to `.codecarto/DECISIONS.md` (one level up from templates/)
-  the first time the orchestrator promotes a decision. Then add entries as they accumulate.
+  Project-level skeleton. codecarto_init seeds this to `.codecarto/DECISIONS.md` (one level up
+  from templates/); entries accumulate as phases complete.
 
   This file is an append-only numbered log of cross-cutting decisions made during the project
   that diverge from spec text, prompt direction, or the obvious-default. Each entry is a
   one-liner with a back-reference to the closeout where the decision was made and the rationale
   lives.
 
-  This file is **append-only and orchestrator-maintained**. Every implementing session's
-  "Decisions Beyond Prompt" section in the closeout becomes one or more entries here.
+  This file is **append-only and orchestrator-maintained**. Completion appends each phase
+  handoff's `decisions` array as rows under `## Completion log` (added at first use); the
+  orchestrator may re-file entries into the category sections below. Numbering is shared across
+  the whole file.
 -->
 
 Append-only log of cross-cutting decisions that diverge from spec text, prompt direction, or
 obvious-default. Each entry is a one-liner with a back-reference to the closeout where the
 decision was made and the rationale lives.
 
-This file is **append-only and orchestrator-maintained**. Every implementing session's
-"Decisions Beyond Prompt" section in the closeout becomes one or more entries here. The
-orchestrator updates this file at session close as part of the closeout ritual.
+This file is **append-only and orchestrator-maintained**. Completion appends each phase handoff's
+`decisions` array as numbered rows under `## Completion log`; the orchestrator may re-file entries
+into the category sections at the phase boundary.
 
 ## Format
 
@@ -73,9 +75,10 @@ D001 | Outcome<T,E> is a brand newtype keyed by a unique Symbol, NOT a value-uni
 
 ## How decisions get added
 
-Every implementing session's "Decisions Beyond Prompt" section in the closeout becomes one or
-more `D<NNN>` entries here. The orchestrator promotes them at session close as part of the
-closeout ritual. Implementing sessions never edit this file directly.
+Completion appends every phase handoff's `decisions` array as `D<NNN>` rows under
+`## Completion log` — nothing gets stranded in closeout prose. The orchestrator may re-file an
+entry into the category sections above at the phase boundary. Phase executors never edit this
+file directly; they record decisions in the handoff.
 
 If a decision is later overturned, do **not** delete the entry. Append a new `D<NNN>` superseding
 it (with `Supersedes D<old-NNN>` in the one-liner) and update the old entry's one-liner to begin

package/.codecarto/templates/phase-handoff.yaml

@@ -12,6 +12,13 @@ open_question_closures: []
 # or opinionated reruns. Every entry requires a stable id.
 post_pipeline: []
 decisions: []
+# Conventions proposed for promotion. Completion stages each entry in
+# CONVENTIONS.md under "## Pending proposals"; the orchestrator promotes or
+# removes it at the phase boundary. Entries require non-empty name and rule.
+#   - name: <short pattern name>
+#     rule: <the rule, one or two sentences>
+#     evidence: <optional: where the pattern showed up>
+proposed_conventions: []
 closeout_summary: ""
 # Optional full closeout Markdown. YAML literal blocks are supported.
 closeout_content: |-

package/.codecarto/templates/spike-report.md

@@ -0,0 +1,51 @@
+# Spike — <spike-id>: <one-line question>
+
+<!--
+  Output template for one spike: a bounded investigation that answers a question
+  the pipeline could not settle from source reading alone (a runtime probe, a
+  measurement, a reproduction attempt).
+
+  Place the report at: scratch/spikes/<spike-id>/<scenario>.md
+  (one file per scenario; several scenarios may serve one spike-id).
+
+  Spikes are usually registered first as post_pipeline entries (kind: spike) in a
+  phase handoff. When a spike's findings change the reimplementation spec, write
+  the deltas as Recommended Deltas below and apply them with the
+  spec-delta-application skill; when a spike resolves an open question after the
+  pipeline completed, close it with an amendment (templates/amendment.yaml +
+  codecarto_amend), citing this report.
+
+  Keep it honest: a spike that failed to answer its question is a valid result —
+  record what was tried and what blocked it.
+-->
+
+## Goal
+
+<!-- The exact question this spike answers, and which open_questions / post_pipeline
+     id(s) it serves. One paragraph. -->
+
+## Method
+
+<!-- What was run, built, probed, or measured — precisely enough to re-run it.
+     Include commands, fixtures, and environment facts that affect the result. -->
+
+## Measurements
+
+<!-- Raw observations before interpretation: outputs, timings, counts, captured
+     frames, exit codes. Paste the actual returns — a summary is not evidence. -->
+
+## Findings
+
+<!-- What the measurements mean for the question in Goal. Mark each finding:
+     confirmed / refuted / inconclusive. An inconclusive spike states what would
+     settle it. -->
+
+## Recommended Deltas
+
+<!-- Changes the findings imply, one per bullet, each addressed to a specific
+     artifact section (usually the reimplementation spec). These feed the
+     spec-delta-application skill's triage — APPLY / CLARIFY / DEFER / REJECT is
+     that session's call, not this report's. If a finding closes an open
+     question, name the amendment slug that will apply it. -->
+
+- Δ1 —

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

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

package/agent-skill/codecartographer/SKILL.md

@@ -14,9 +14,11 @@ Three roles, and you hold two of them:
 | Role | Who | Does |
 |---|---|---|
 | State machine | the MCP server | phase order, prompts, validation parsing, completion gate, canonical state |
-| Orchestrator | you | pick the pipeline, drive the loop, choose an executor, verify |
+| Orchestrator | you | pick the pipeline, drive the loop, choose an executor, verify, and hold the cross-phase duties (`references/orchestration.md`) |
 | Executor | you, or a model you delegate to | read the repo, write the phase artifact |
 
+Being the orchestrator does not preclude executing phases yourself — a single chat driving these tools inline is the normal case, and it holds both the Orchestrator and Executor rows. What makes a run orchestrated is performing the phase-boundary duties (convention promotion, open-question re-triage, contradiction sweeps, gap routing), not delegating the work. If the workspace `GUIDE.md` predates this contract and says the orchestrator must not execute phases, trust this guide.
+
 ## The drive loop
 
 ```
@@ -120,6 +122,8 @@ A PARTIAL row's evidence must name what is missing and which `open_questions` or
 
 ## When the run drives a rewrite
 
+When the pipeline completes, the finished spec has a designed destination: publish it to a **library** (`codecarto_publish`; create one with `codecarto_library_init`) so synthesis runs and other projects can consume it — `references/library.md`. A spec that only ever lives in its workspace helps exactly one repository.
+
 If the goal is to rebuild or refactor rather than to understand, two phases carry that weight and both have their own reference:
 
 - the defect scans feed `porting` and `reimplementation-spec` as inputs, not as an appendix — `references/deep-audit-synthesis.md`;
@@ -129,6 +133,7 @@ If the goal is to rebuild or refactor rather than to understand, two phases carr
 
 Running the pipeline:
 
+- `references/orchestration.md` — the orchestrator's duties, inline vs delegated execution, and the session-by-session fallback's real costs
 - `references/pipeline-selection.md` — choosing a variant, and switching without losing work
 - `references/executors.md` — the executor contract, adapters, and model selection
 - `references/handoff-contract.md` — full handoff schema, routing, and closure semantics
@@ -139,5 +144,6 @@ Using what it produces:
 - `references/deep-audit-synthesis.md` — defect dispositions, hazards as normative rules, reporting
 - `references/kernel-first-rewrite.md` — rings, build order, acceptance harness, strategic assumptions
 - `references/carrying-results-forward.md` — starting implementation, autonomy boundaries, publishing findings
+- `references/library.md` — publishing finished specs to a library and consuming them from synthesis runs
 
 This guide is also served by the `codecarto_guide` MCP tool, so an agent with the server configured can read it without installing anything.

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

@@ -19,7 +19,8 @@ carry_forward: []               # deferred to a specific later phase in this pip
 carry_forward_closures: []      # ids of carry_forward entries this phase resolved
 open_question_closures: []      # ids of open questions this phase resolved, removed everywhere
 post_pipeline: []               # work after the pipeline; every entry needs a stable id
-decisions: []                   # choices made beyond what the prompt specified
+decisions: []                   # choices made beyond what the prompt specified; completion appends them to DECISIONS.md
+proposed_conventions: []        # patterns proposed for promotion; completion stages them in CONVENTIONS.md
 closeout_summary: ""            # one clause, ~20 words; becomes the THREAD_LOG entry
 closeout_content: |-            # optional full closeout markdown
   # Closeout — architecture
@@ -52,6 +53,16 @@ Omitted arrays default to empty. A malformed collection fails completion without
 
 Allowed `kind` values: `needs-runtime-test`, `needs-maintainer-decision`, `needs-spec-ruling`, `defer-to-phase`, `needs-fixture-capture`.
 
+`proposed_conventions` entries (optional; omitted defaults to empty):
+
+```yaml
+- name: evidence-marker-citations
+  rule: Cite every load-bearing claim with an evidence marker naming its source file.
+  evidence: Third phase in a row independently adopted the [fact/inference] vocabulary.
+```
+
+`name` and `rule` are required and non-empty — a malformed entry fails completion. Completion stages each entry in `CONVENTIONS.md` under `## Pending proposals` (mechanical, deduplicated on re-run); promoting a staged proposal into a numbered convention stays an orchestrator judgment at the phase boundary. `decisions` are simpler: plain strings that completion both renders into the closeout's "Decisions Beyond Prompt" section and appends to `DECISIONS.md` as numbered `D<NNN>` rows under `## Completion log`.
+
 ## Open question or carry-forward?
 
 - **`open_questions`** — nobody in this pipeline will resolve it. It needs a runtime test, a maintainer decision, or a spec ruling. It survives to the end as a known unknown.

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

@@ -0,0 +1,32 @@
+# The library: where finished specs go
+
+A CodeCartographer **library** is a directory of published reimplementation-specs with provenance — the bridge between analysis runs and everything downstream. An analysis pipeline ends with a spec in one workspace; publishing it makes it addressable from any other project, and the **synthesis pipeline** consumes exactly these entries ("convert a user vision and explicitly confirmed library specs into a provenance-backed project plan" — see `codecarto_guide` topic `pipeline-selection`). Without a publish step, every analysis is an island.
+
+## Anatomy
+
+- A directory holding a `.codecarto-library` marker, `entries/` (optionally namespaced), and a generated `index.yaml` + `INDEX.md`.
+- Discovery: tools take `library_path` (absolute) directly, or resolve the library from a workspace `cwd`'s `config.yaml`; `codecarto_library_init` also writes `library.path` into the user-global config so later calls need no path at all.
+- `codecarto_config` shows the effective merge (`library.path`, `library.namespace`, `publish_confirm`) and whether the marker was found.
+
+## The four tools
+
+| Tool | Does | Notes |
+|---|---|---|
+| `codecarto_library_init` | Create the directory, write the marker, record `library.path` in user-global config | Idempotent; pass `namespace` to create a namespaced library |
+| `codecarto_publish` | Publish a spec as a library entry | Required: `source_repo`, `headline`, and `spec` (inline) or `spec_path` (absolute). Content-hash idempotent: identical bytes update metadata in place, no version bump. `slug` derives from `source_repo` if omitted; namespaced libraries require `namespace` (or inherit via `cwd`). Provenance (`source_commit`, `source_branch`, `source_dirty`, `analyzed_at`, `pipeline`, `model_metadata`) is recorded; omitted generation fields default to `unknown` |
+| `codecarto_library_list` | List entries | Filter by `namespace`, `tag`, `slug`, or `source_repo` |
+| `codecarto_library_reindex` | Regenerate `index.yaml` + `INDEX.md` from filesystem state | For manual edits and index merge conflicts |
+
+## When to publish
+
+The moment `reimplementation-spec` completes and validates is the publish moment — the spec is finished, the workspace still knows its provenance (`cwd` inherits `pipeline` from `status.yaml`), and the terminal `next_actions` point here. Publish with `cwd` set so provenance rides along:
+
+```
+codecarto_publish cwd:<workspace repo> source_repo:<repo URL or path> headline:"<one line>" spec_path:<abs path to reimplementation-spec.md>
+```
+
+Set `publish_confirm` in config if you want an explicit confirmation gate before writes.
+
+## What this is not
+
+Publishing a spec into a library is different from copying findings into a product repository you are about to build — that curated-snapshot flow is `references/carrying-results-forward.md`. The library holds *specs as reusable inputs*; a product repo holds *your implementation of one*.

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

@@ -0,0 +1,45 @@
+# Orchestration
+
+The orchestrator is the persistent chat driving the run — normally the session reading this guide. The role is defined by **duties**, not by who executes phases. A single chat that runs every phase itself and performs the duties below is fully orchestrated; a fleet of delegated sub-agents whose driver skips them is not.
+
+## The duties
+
+All of them happen at the **phase boundary**: after one phase completes, before the next begins. None of them happen mid-phase — a phase executor follows its SKILL.md; the orchestrator judges between phases.
+
+1. **Promote conventions and append decisions.** Phase closeouts carry "Proposed Conventions" and "Decisions Beyond Prompt" sections; handoffs carry a `decisions` array. Promotion into `CONVENTIONS.md` (when a pattern recurs or clearly generalizes) and `DECISIONS.md` (every cross-cutting decision, numbered, append-only) is your call to make at the boundary. Proposals left in closeout prose are proposals lost — a real seven-phase run stranded ~12 proposed conventions and 23 decisions this way, because nobody held the duty.
+
+2. **Re-triage open-question labels.** An `open_questions` entry's `kind` is itself a claim that needs evidence. Before accepting `needs-maintainer-decision` or `needs-runtime-test` into the next phase, re-test: *has this become answerable by reading?* Labels are sticky — the routing machinery faithfully carries a question forward, but nothing re-examines whether the label was right, so a mislabel suppresses verification for the rest of the pipeline.
+
+3. **Sweep for contradictions.** Compare the incoming phase's required reads against earlier phases' `owner_notes`. A measured fact that contradicts a summarized claim (a line count that belies "this layer is pure configuration", a schema that admits a value a doc says is impossible) is a gap to route — into the next phase's work, an `open_questions` entry, or a correction — not a nuance to smooth over.
+
+4. **Route gaps.** Confirm the completed phase's declared secondary outputs were written or explicitly routed to a later phase. Confirm any handoff decision that *defers* work names a place a later phase will actually look. A deferral recorded only as prose in a decision entry goes nowhere: the same seven-phase run deferred a declared secondary output via a handoff decision, and it was silently dropped.
+
+5. **Gate strategic forks with the user.** Pipeline switches, the opinionated-vs-language-agnostic spec choice, scope changes, force-reinit. These are the user's calls; your job is to surface them at the right moment with a recommendation.
+
+## The failure this section exists to prevent
+
+In a real `full-with-deep-audit` run, the architecture phase recorded an open question — "is the absence of authentication on the web surface intended?" — labeled `needs-maintainer-decision`, on the stated ground that a threat model is not derivable from code. The label was wrong: the shipped launcher *refuses* non-loopback binds in code, with the reason in the error string, and five minutes of reading would have answered the question. But the label was never re-examined. The question rode the carry-forward machinery through four phases (`arch-OQ2` → `dss-OQ3` → `port-OQ1` → `spec-OQ1`), and its unverified premise hardened into a wrong high-severity security finding that survived into the final reimplementation spec — corrected only because the user happened to ask about it directly afterward.
+
+Two duties would each have caught it: re-triage (duty 2) would have re-tested the label at any of four boundaries; the contradiction sweep (duty 3) had the evidence in hand, since the run's own notes contained both "the launcher owns only composition selection" and "no enforcement exists anywhere."
+
+## Execution strategies
+
+How the orchestrator and executor roles map onto threads is a per-run choice, orthogonal to the duties:
+
+- **Inline** — you execute phases yourself. The normal mode for a single chat driving the MCP tools; also the right mode when the user asks one thread to do everything. Perform the duties between `codecarto_complete` and the next `codecarto_next`.
+- **Delegated** — you dispatch each phase to a separate execution context (the Pi extension's phase sub-agents do this automatically; on other hosts, fresh threads run prompts you draft) and review each closeout. Keeps phase context out of your window, which matters on long pipelines and small context budgets. Same duties, same boundary.
+
+Mixing is normal: delegate the wide-read phases, run the synthesis phases inline where your judgment is the value. See `references/executors.md` for choosing per phase.
+
+## The session-by-session fallback
+
+Running each phase in an isolated session with nobody holding the duties is a **fallback, not a peer mode**. Its costs are the failures above: empty `CONVENTIONS.md`, stranded proposals, unchallenged labels, dropped deferrals. It is legitimate in exactly two cases:
+
+- the user explicitly declines orchestration, or
+- the driving model cannot sustain cross-phase context.
+
+Record the reason in the first handoff's `owner_notes` so a later session knows the mode was chosen, not defaulted into.
+
+## First run on a fresh workspace
+
+Adopt the orchestrator role by default — do not interview the user about whether orchestration should happen. Seed `CONVENTIONS.md` and `DECISIONS.md` from their templates if missing, pick the execution strategy from the situation (single MCP chat → inline; sub-agent host → delegated), and note the strategy in the first handoff's `owner_notes`. Ask the user only when their instructions genuinely conflict with both defaults, and never under an `--auto` run, which must not block on questions.

package/dist/core/amendment.d.ts

@@ -0,0 +1,41 @@
+import type { WorkspaceState } from "./types.ts";
+/** One parsed amendment file from scratch/amendments/<slug>.yaml. */
+export type Amendment = {
+    /** The file's basename without extension; names the closeout. */
+    slug: string;
+    /** Open-question ids to remove from every phase. */
+    open_question_closures: string[];
+    /** post_pipeline item ids to remove from the backlog (the closeout records the closure). */
+    post_pipeline_closures: string[];
+    /** Durable observations recorded in the amendment closeout. */
+    notes: string[];
+    closeout_summary: string;
+    closeout_content: string;
+    schema_version?: number;
+};
+/** What one amendment application changed, id by id. */
+export type AmendmentApplication = {
+    openQuestionsClosed: string[];
+    postPipelineClosed: string[];
+    /** Requested ids that matched nothing — already closed or never existed. Re-running an amendment is safe. */
+    unknownIds: string[];
+};
+export type AmendmentResult = {
+    updatedState: WorkspaceState;
+    closeoutNotice: string;
+    applied: AmendmentApplication;
+};
+/** Same charset rule as phase ids: the slug becomes file names, so path shapes are refused. */
+export declare function assertSafeAmendmentSlug(slug: string): void;
+/**
+ * Load and validate one amendment file.
+ * @param name - the amendment slug, with or without a `.yaml` suffix.
+ */
+export declare function loadAmendmentFile(name: string, workspaceDir: string): Promise<Amendment>;
+/**
+ * Apply one amendment to canonical state under the completion lock. Refuses
+ * while the pipeline is incomplete — mid-pipeline resolutions belong in the
+ * phase handoff, and allowing both channels at once would race them.
+ * Idempotent: ids that no longer match anything are reported, not fatal.
+ */
+export declare function applyAmendment(cwd: string, name: string): Promise<AmendmentResult>;