codecartographer-pi 0.10.0 → 0.12.0

package/.codecarto/workflow/status.yaml

@@ -1,4 +1,5 @@
 project_name: ""
+schema_version: 1
 # source_location is defined in the active pipeline YAML. Do not duplicate it here.
 pipeline: workflow/pipeline-full-with-deep-audit.yaml
 # ^^^ To switch pipelines, change the line above AND adjust the phases below to match:
@@ -62,3 +63,4 @@ phases:
     carry_forward: []
 next_actions:
   - Begin architecture phase by reading the repository and producing findings/architecture/architecture-map.md
+post_pipeline: []

package/README.md

@@ -32,8 +32,11 @@
 | **HTML dashboard** — single-file aggregate of progress, links, usage, narrative | `.codecarto/dashboard.html` |
 | **Per-phase token tracking** | `/codecarto-usage` |
 | **Opt-in LLM steering** of the next phase's seed prompt | `/codecarto-next --llm-steer` |
+| **Forward synthesis** — vision + confirmed library specs → provenance-backed project plan | `pipeline-synthesis.yaml` |
 
-> **Forward-flow synthesis is underway.** v0.9.0 adds the experimental library foundation and MCP publish/list/reindex tools for accumulating `reimplementation-spec.md` artifacts in a git-trackable library. The Pi publish UX and synthesis pipeline that turns selected library entries plus a vision into `project-plan.md` are still in progress. See [`docs/synthesis-roadmap.md`](docs/synthesis-roadmap.md) for the implementation tracker.
+> **Forward-flow synthesis is available on the development branch.** Publish completed reimplementation specs from Pi or MCP, then run the `synthesis` pipeline to turn a product vision and explicitly confirmed library entries into a conflict-aware `project-plan.md` with a decision-level provenance ledger.
+
+OpenAI Build Week reviewers: see the [new-vs-existing scope and one-command demo](docs/build-week-2026.md).
 
 ---
 
@@ -93,7 +96,47 @@ cp -r /path/to/CodeCartographer/.codecarto /path/to/your-repo/
 
 Then in the LLM session: `Read .codecarto/GUIDE.md and begin the analysis.`
 
-> **Limitation.** Drop-in mode runs the analysis pipeline fully, but library + synthesis workflows require executable code. Publishing and reading library entries are currently available through the MCP server; Pi publish UX and project-plan synthesis are still in progress. See [`docs/synthesis-roadmap.md`](docs/synthesis-roadmap.md) for the planned scope.
+> **Limitation.** Drop-in mode runs the analysis pipeline fully, but library + synthesis workflows require executable code through Pi or MCP.
+
+---
+
+## Forward synthesis quickstart
+
+Analysis turns repositories into reusable specifications. Synthesis runs the other direction: it combines a raw product vision with human-confirmed specifications and produces an implementation-ready plan without losing provenance.
+
+1. Configure the library that contains specs published with `/codecarto-publish` or the MCP `codecarto_publish` tool:
+
+   ```yaml
+   # ~/.codecarto/config.yaml or .codecarto/workflow/config.yaml
+   library:
+     path: /absolute/path/to/codecarto-library
+     namespace: your-namespace # omit for a single-tenant library
+     publish_confirm: true
+   ```
+
+2. Initialize a clean planning workspace and fill in its brief:
+
+   ```text
+   /codecarto-init synthesis
+   ```
+
+   Edit `.codecarto/inputs/vision.md` with the audience, problem, desired outcome, constraints, and non-goals.
+
+3. Run until CodeCartographer creates the candidate proposal:
+
+   ```text
+   /codecarto-next --auto
+   ```
+
+   The run intentionally stops before merging. Review `.codecarto/findings/goal-synthesis/proposal.md` and change one or more candidate boxes from `[ ]` to `[x]`.
+
+4. Resume:
+
+   ```text
+   /codecarto-next --auto
+   ```
+
+The final `.codecarto/findings/goal-synthesis/project-plan.md` contains product scope, architecture, work packages, acceptance gates, an unresolved-conflict register, and a provenance ledger mapping every load-bearing decision back to the vision or a confirmed specification. Runtime preflight checks prevent merging or finalization before explicit human confirmation.
 
 ---
 
@@ -114,6 +157,39 @@ For multi-session work, every new session reads `.codecarto/GUIDE.md` (or the li
 
 ---
 
+## Progressive distillation and context resilience
+
+CodeCartographer is a progressive, evidence-tagged distillation of a codebase. It does not ask one context window to retain the entire investigation. Instead, each phase turns a large body of source evidence into a smaller, more task-specific artifact that the next phase can read:
+
+```text
+source code
+  → architecture map
+  → behavioral contracts + protocols + defect findings
+  → porting bundle
+  → reimplementation spec
+```
+
+This is deliberate distillation, not incidental chat summarization. Each artifact follows a template, preserves evidence levels and known unknowns, and must pass validation before it becomes an input to downstream phases.
+
+### What happens when conversation context is compacted?
+
+The filesystem, not the conversation, is the durable memory of a run:
+
+- Each phase gets a fresh context window. In the Pi extension it runs as an isolated phase sub-agent; MCP and drop-in hosts should use the same one-session-per-phase pattern.
+- Completed findings live under `.codecarto/findings/`. Later phases re-read the specific upstream artifacts declared by the active pipeline instead of relying on conversational recall.
+- `workflow/status.yaml` records progress, terminal `open_questions`, in-pipeline `carry_forward`, and a separate `post_pipeline` backlog for optional spikes, amendments, deltas, decisions, and reruns after completion. Phase agents propose changes in `.codecarto/scratch/handoffs/<phase>.yaml`; completion validates and applies them under a lock with host timestamps, one canonical closeout, and an idempotent `THREAD_LOG.md` entry.
+- Pi phase transcripts are file-backed and remain available through `/resume`, `/tree`, and `/export`, even when the active model context has been compacted.
+- For isolated Pi phase sessions, compaction uses a phase-aware continuation summary that explicitly preserves evidence, files inspected, output progress, open questions, and validation gaps. The resulting summary is also checkpointed atomically at `.codecarto/scratch/checkpoints/<phase>.md`.
+- Pi records successful, failed, and aborted compactions plus their trigger (`threshold`, `overflow`, or `manual`) in local usage data and exposes the totals in the widget, `/codecarto-usage`, completion summaries, and dashboard.
+
+As a result, compaction—or even replacement—of the orchestrator session does not erase pipeline progress. A new session can reconstruct the relevant state from disk and continue.
+
+The remaining limit is **within a single oversized phase**. Even Pi's phase-aware summary is still a lossy distillation, and MCP/drop-in compaction remains entirely host-controlled. Phase instructions therefore prioritize targeted reads, durable checkpoints, and explicit coverage accounting; if full coverage will not fit, the phase records `PARTIAL` validation and places unresolved work in `open_questions` or `carry_forward`. Cross-phase context loss is largely designed out; intra-phase context pressure is observed and bounded rather than hidden.
+
+The porting bundle is the final intentional compression boundary. It carries a source index, load-bearing invariants, defect dispositions, and deep-read triggers. `reimplementation-spec` reads that bundle by default and opens lower-level reports only for a named gap, conflict, missing acceptance detail, or defect rationale.
+
+---
+
 ## Phases produce these artifacts
 
 | Artifact | Description |
@@ -142,6 +218,7 @@ The default is a 7-phase run that splits the defect scan into a mechanical early
 | **Defect scan** | 2 | Maintenance audit to surface latent problems |
 | **Lite** | 3 | You need to understand behavior without porting plans |
 | **Architecture only** | 1 | Quick structural overview |
+| **Synthesis** | 4 | Turn a product vision and confirmed library specifications into a provenance-backed implementation plan |
 
 Set the active pipeline by editing `workflow/status.yaml`'s `pipeline:` field, or pass it as the argument to `/codecarto-init`.
 
@@ -155,6 +232,7 @@ Set the active pipeline by editing `workflow/status.yaml`'s `pipeline:` field, o
 | Defect scan | `workflow/pipeline-defect-scan.yaml` |
 | Lite | `workflow/pipeline-lite.yaml` |
 | Architecture only | `workflow/pipeline-architecture-only.yaml` |
+| Synthesis | `workflow/pipeline-synthesis.yaml` |
 
 ---
 
@@ -164,7 +242,7 @@ Every state change re-renders `.codecarto/dashboard.html` — a self-contained s
 
 - Pipeline progress strip with per-phase status badges
 - Per-phase cards with output links, open questions, carry-forward routing, owner notes, last-run usage
-- Aggregate token usage panel + per-phase breakdown
+- Aggregate token and compaction telemetry + per-phase breakdown
 - Activity timeline with session-file links
 - Open questions roll-up grouped by source phase
 - Closeouts list (reverse-chronological) with relative-path links
@@ -191,25 +269,29 @@ Beyond the slash commands, the Pi extension layers on:
 
 **File-backed phase sessions.** Phase transcripts persist to the same Pi session directory the orchestrator uses, so `/resume`, `/tree`, and `/export` browse them as first-class sessions. Each appears as `CodeCartographer phase: <id>` with lineage back to the orchestrator's session.
 
+**Phase-aware compaction and checkpoints.** Only isolated sessions named `CodeCartographer phase: <id>` receive the specialized compaction prompt. It preserves the phase goal, evidence, inspected files, output progress, open questions, and validation gaps, then writes the resulting summary to `.codecarto/scratch/checkpoints/<phase>.md`. Orchestrator and unrelated Pi sessions retain normal host compaction.
+
 **Phase-completion summary in the orchestrator transcript.** When a phase finishes, a Markdown closeout block is appended to the orchestrator's session via `pi.sendMessage(...)`. Visible in the TUI scrollback; available to the orchestrator's LLM as context on your next message. No auto-trigger — you stay in control.
 
 **Opt-in LLM-steered seed prompts.** Set `orchestrator.llm_steer_next_phase: true` in `.codecarto/workflow/config.yaml` (or pass `--llm-steer` per invocation), and the orchestrator's LLM rewrites the next phase's seed prompt to highlight relevant prior findings. Off by default — extra orchestrator-side tokens, opt-in. The rewritten prompt is injected into the orchestrator transcript so you can audit what the rewriter chose to emphasize.
 
-**Per-phase usage tracking.** Each phase run is appended to `.codecarto/workflow/.usage.local.yaml`. `/codecarto-usage` reports cumulative + per-phase totals.
+**Per-phase usage tracking.** Each phase run is appended to `.codecarto/workflow/.usage.local.yaml`. `/codecarto-usage` reports cumulative + per-phase token, runtime, tool-use, and compaction totals, including threshold/overflow/manual triggers and successful/failed/aborted outcomes.
 
-**Tool interception.** `bash` is blocked outright; `edit` and `write` are confined to `.codecarto/`. Same rules apply to phase sub-agents.
+**Tool interception.** `bash` is blocked outright; `edit` and `write` are confined to `.codecarto/`, plus the configured, marker-validated CodeCartographer library when one is configured. Same rules apply to phase sub-agents.
 
 ### Slash commands
 
 | Command | Purpose |
 |---|---|
 | `/codecarto-init [variant]` | Copy `.codecarto/` into the current repository, select pipeline variant |
+| `/codecarto-open` | Activate an existing `.codecarto/` workspace in a new Pi session without resetting durable state |
 | `/codecarto-status` | Current phase, progress, open questions |
 | `/codecarto-next [--auto [--strict]] [--llm-steer \| --no-llm-steer]` | Spawn the next eligible phase as a sub-agent. `--auto` walks the full pipeline end-to-end (auto-validate + auto-complete + advance); `--strict` flips the `PASS WITH GAPS` rule from "advance" to "pause". |
 | `/codecarto-phase <id>` | Force a specific phase, even out of pipeline order |
 | `/codecarto-validate [phase]` | Validate a phase output against completion criteria |
-| `/codecarto-complete [phase]` | Atomically mark a phase complete (validation must pass) |
+| `/codecarto-complete [phase]` | Validate and atomically apply the phase handoff, canonical status, closeout, and log entry |
 | `/codecarto-skill <name>` | Run a post-pipeline skill once all phases are complete |
+| `/codecarto-publish` | Publish the reimplementation spec to the configured library after reviewing an explicit confirmation preview |
 | `/codecarto-usage` | Cumulative + per-phase token usage |
 | `/codecarto-dashboard [--narrate]` | Regenerate `.codecarto/dashboard.html`; `--narrate` for the LLM executive summary |
 
@@ -391,7 +473,7 @@ If you're testing a new model, start with `pipeline-architecture-only.yaml` on a
     protocols/               # Event streams, state machines, persistence formats.
     porting/                 # Reverse-engineering synthesis bundle.
     reimplementation-spec/   # Language-agnostic build spec.
-  scratch/                   # Disposable analysis notes.
+  scratch/                   # Disposable notes plus checkpoints and structured phase handoffs.
   templates/                 # Output structure templates.
   workflow/                  # Pipeline definitions, status, validation, config.
   closeouts/                 # Per-session closeout files.

package/dist/core/completion.d.ts

@@ -0,0 +1,6 @@
+import type { ValidationResult, WorkspaceState } from "./types.ts";
+export type CompletionResult = {
+    updatedState: WorkspaceState;
+    closeoutNotice?: string;
+};
+export declare function completeValidatedPhase(cwd: string, validation: ValidationResult, sourceLabel: string): Promise<CompletionResult>;

package/dist/core/completion.js

@@ -0,0 +1,127 @@
+import { appendFile, copyFile, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { getNextEligiblePhase, resolvePhase } from "./pipeline.js";
+import { applyHandoff, autoAssignIds, loadHandoffFile, normalizeStatus } from "./status.js";
+import { dateOnly, pathExists, uniqueStrings } from "./utils.js";
+import { getWorkspaceState, updateStatusAtomically } from "./workspace.js";
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+async function canonicalCloseoutFile(workspaceDir, phaseId, timestamp) {
+    const closeoutsDir = join(workspaceDir, "closeouts");
+    await mkdir(closeoutsDir, { recursive: true });
+    const pattern = new RegExp(`^\\d{4}-\\d{2}-\\d{2}-${escapeRegExp(phaseId)}\\.md$`);
+    const existing = (await readdir(closeoutsDir)).filter((name) => pattern.test(name)).sort();
+    return existing.at(-1) ?? `${dateOnly(timestamp)}-${phaseId}.md`;
+}
+async function writeCompletionArtifacts(workspaceDir, phaseId, validation, timestamp, handoff) {
+    const closeoutFile = await canonicalCloseoutFile(workspaceDir, phaseId, timestamp);
+    const closeoutPath = join(workspaceDir, "closeouts", closeoutFile);
+    const suppliedContent = handoff?.closeout_content?.trim();
+    if (suppliedContent) {
+        const decisions = handoff?.decisions ?? [];
+        const decisionsSection = decisions.length > 0
+            ? `\n\n## Decisions Beyond Prompt\n\n${decisions.map((decision) => `- ${decision}`).join("\n")}`
+            : "";
+        await writeFile(closeoutPath, `${suppliedContent}${decisionsSection}\n`, "utf8");
+    }
+    else if (!(await pathExists(closeoutPath))) {
+        const templatePath = join(workspaceDir, "templates", "closeout-template.md");
+        if (await pathExists(templatePath))
+            await copyFile(templatePath, closeoutPath);
+    }
+    const summary = handoff?.closeout_summary?.trim() || `Validation: ${validation.overall}`;
+    const entry = `- ${dateOnly(timestamp)} — ${phaseId} — ${summary} — [closeout](closeouts/${closeoutFile})`;
+    const threadLogPath = join(workspaceDir, "THREAD_LOG.md");
+    let current = "";
+    try {
+        current = await readFile(threadLogPath, "utf8");
+    }
+    catch {
+        // Created below when absent.
+    }
+    const link = `[closeout](closeouts/${closeoutFile})`;
+    if (!current.split(/\r?\n/).some((line) => line.includes(link))) {
+        await appendFile(threadLogPath, `${entry}\n`, "utf8");
+    }
+    return `.codecarto/closeouts/${closeoutFile}`;
+}
+export async function completeValidatedPhase(cwd, validation, sourceLabel) {
+    const initialState = await getWorkspaceState(cwd);
+    if (!initialState)
+        throw new Error("CodeCartographer workspace not found. Run /codecarto-init first.");
+    const handoff = await loadHandoffFile(validation.phaseId, initialState.workspaceDir);
+    if (handoff && handoff.phase_id !== validation.phaseId) {
+        throw new Error(`Invalid handoff: phase_id ${handoff.phase_id} does not match ${validation.phaseId}`);
+    }
+    if (handoff) {
+        const activePhases = new Set(initialState.pipeline.phase_order);
+        const sourceIndex = initialState.pipeline.phase_order.indexOf(validation.phaseId);
+        for (const entry of handoff.carry_forward) {
+            const targetIndex = entry.target_phase ? initialState.pipeline.phase_order.indexOf(entry.target_phase) : -1;
+            if (!entry.target_phase || !activePhases.has(entry.target_phase) || targetIndex <= sourceIndex) {
+                throw new Error(`Invalid handoff: carry_forward target_phase ${entry.target_phase ?? "(missing)"} is not a downstream active pipeline phase; use post_pipeline for work after the pipeline`);
+            }
+        }
+        for (const entry of handoff.post_pipeline) {
+            if (!entry.id?.trim())
+                throw new Error("Invalid handoff: post_pipeline entries require a canonical id");
+        }
+    }
+    const completionTimestamp = new Date().toISOString();
+    let closeoutPath;
+    const updatedState = await updateStatusAtomically(cwd, async (lockedState) => {
+        const phase = resolvePhase(lockedState, validation.phaseId);
+        if (!phase?.primary_output)
+            throw new Error(`Phase ${validation.phaseId} is missing primary_output.`);
+        const nextStatus = normalizeStatus(lockedState.status, lockedState.pipeline, lockedState.status.pipeline, lockedState.cwd);
+        const existingPhase = nextStatus.phases[validation.phaseId] ?? {
+            status: "pending",
+            owner_notes: [],
+            outputs_present: [],
+            open_questions: [],
+            carry_forward: [],
+        };
+        const gapEntries = validation.rows
+            .filter((row) => row.result.toUpperCase().includes("PARTIAL"))
+            .map((row) => ({
+            kind: "needs-maintainer-decision",
+            description: row.criterion || "Partial validation gap",
+            deferred_reason: row.evidence || "Marked PARTIAL by validation",
+        }));
+        autoAssignIds(gapEntries, "oq", validation.phaseId);
+        const mergedOpenQuestions = [...existingPhase.open_questions];
+        for (const candidate of gapEntries) {
+            if (!mergedOpenQuestions.some((entry) => entry.description === candidate.description && entry.deferred_reason === candidate.deferred_reason)) {
+                mergedOpenQuestions.push(candidate);
+            }
+        }
+        nextStatus.phases[validation.phaseId] = {
+            status: "complete",
+            owner_notes: uniqueStrings([
+                ...existingPhase.owner_notes,
+                `Completed via ${sourceLabel}.`,
+                `Primary output: .codecarto/${validation.primaryOutput}`,
+                `Validation: ${validation.overall}`,
+            ]),
+            outputs_present: uniqueStrings([...existingPhase.outputs_present, validation.primaryOutput]),
+            open_questions: mergedOpenQuestions,
+            carry_forward: existingPhase.carry_forward ?? [],
+        };
+        if (handoff)
+            applyHandoff(nextStatus, handoff);
+        nextStatus.last_updated = completionTimestamp;
+        const nextWorkspace = { ...lockedState, status: nextStatus };
+        const nextEligible = getNextEligiblePhase(nextWorkspace);
+        nextStatus.current_phase = nextEligible?.id ?? "complete";
+        nextStatus.next_actions = nextEligible
+            ? [`Begin ${nextEligible.id} phase by producing ${nextEligible.primary_output ?? `findings/${nextEligible.id}/`}`]
+            : ["All phases complete. Review findings, open questions, and downstream implementation notes."];
+        closeoutPath = await writeCompletionArtifacts(lockedState.workspaceDir, validation.phaseId, validation, completionTimestamp, handoff);
+        return { state: { ...nextWorkspace, status: nextStatus } };
+    });
+    return {
+        updatedState,
+        closeoutNotice: closeoutPath ? `Closeout: ${closeoutPath}` : undefined,
+    };
+}

package/dist/core/dashboard.js

@@ -22,6 +22,7 @@ export function renderDashboard(inputs) {
         renderUsagePanel(inputs),
         renderActivityTimeline(inputs.usage.runs),
         renderOpenQuestionsRollup(inputs.status),
+        renderPostPipelineWork(inputs.status),
         renderCloseoutsList(inputs),
         renderFooter(inputs),
         `</div>`,
@@ -74,6 +75,7 @@ function renderSidebar(inputs) {
         `<a class="cc-nav-section" href="#phases">Phases</a>`,
         phaseLinks,
         `<a class="cc-nav-section" href="#usage">Usage</a>`,
+        (inputs.status.post_pipeline?.length ?? 0) > 0 ? `<a class="cc-nav-section" href="#post-pipeline">Post-pipeline</a>` : "",
         `<a class="cc-nav-section" href="#closeouts">Closeouts</a>`,
         `</nav>`,
         `<button type="button" class="cc-export" data-export>Export dashboard JSON</button>`,
@@ -134,6 +136,7 @@ function renderHealthPanel(inputs) {
     const issues = collectDashboardIssues(inputs);
     const openQuestionCount = countOpenQuestions(status);
     const carryForwardCount = countCarryForward(status);
+    const postPipelineCount = (status.post_pipeline ?? []).filter((entry) => entry.status !== "resolved").length;
     const health = issues.some((i) => i.severity === "blocker") ? "attention required" : issues.length ? "review recommended" : completed === total ? "complete" : "on track";
     const healthClass = issues.some((i) => i.severity === "blocker") ? "bad" : issues.length ? "warn" : "ok";
     const tokenText = usageHasTokenAccounting(usage) ? formatTokenCount(totals.tokens.input + totals.tokens.output) : usage.runs.length ? "unavailable" : "0";
@@ -150,6 +153,7 @@ function renderHealthPanel(inputs) {
         renderHealthMetric("Artifacts needing attention", String(issues.length), issues.length ? "bad" : "ok"),
         renderHealthMetric("Open questions", String(openQuestionCount), openQuestionCount ? "warn" : "ok"),
         renderHealthMetric("Carry-forward items", String(carryForwardCount), carryForwardCount ? "warn" : "ok"),
+        renderHealthMetric("Post-pipeline work", String(postPipelineCount), postPipelineCount ? "neutral" : "ok"),
         renderHealthMetric("Tool uses", String(totals.tool_uses), "neutral"),
         renderHealthMetric("Runtime", formatMillis(totals.duration_ms), "neutral"),
         renderHealthMetric("Tokens", tokenText, tokenText === "unavailable" ? "warn" : "neutral"),
@@ -369,7 +373,8 @@ function renderPhaseLastRun(run) {
     const tokensTotal = formatRunTokens(run);
     const sessionLink = run.session_file ? renderSafeLink(run.session_file, "transcript") : undefined;
     const session = sessionLink ? `<dt>Session</dt><dd>${sessionLink}</dd>` : "";
-    return [`<div class="cc-phase-section">`, `<h3>Last run</h3>`, `<dl class="cc-run-meta">`, `<dt>Timestamp</dt><dd>${escapeHtml(run.timestamp)}</dd>`, `<dt>Status</dt><dd>${escapeHtml(run.status)}</dd>`, `<dt>Turns</dt><dd>${run.turn_count}</dd>`, `<dt>Tool uses</dt><dd>${run.tool_uses}</dd>`, `<dt>Tokens</dt><dd>${escapeHtml(tokensTotal)}</dd>`, `<dt>Duration</dt><dd>${escapeHtml(formatMillis(run.duration_ms))}</dd>`, session, `</dl>`, `</div>`].join("");
+    const compactions = run.compactions ? `<dt>Compactions</dt><dd>${formatCompactionCounts(run.compactions)}</dd>` : "";
+    return [`<div class="cc-phase-section">`, `<h3>Last run</h3>`, `<dl class="cc-run-meta">`, `<dt>Timestamp</dt><dd>${escapeHtml(run.timestamp)}</dd>`, `<dt>Status</dt><dd>${escapeHtml(run.status)}</dd>`, `<dt>Turns</dt><dd>${run.turn_count}</dd>`, `<dt>Tool uses</dt><dd>${run.tool_uses}</dd>`, `<dt>Tokens</dt><dd>${escapeHtml(tokensTotal)}</dd>`, `<dt>Duration</dt><dd>${escapeHtml(formatMillis(run.duration_ms))}</dd>`, compactions, session, `</dl>`, `</div>`].join("");
 }
 function renderUsagePanel(inputs) {
     const { usage, pipeline, status } = inputs;
@@ -382,10 +387,11 @@ function renderUsagePanel(inputs) {
         const t = perPhase.get(phaseId);
         if (!t) {
             const complete = status.phases[phaseId]?.status === "complete";
-            return `<tr class="${complete ? "cc-usage-missing" : ""}"><td><a href="#${phaseAnchor(phaseId)}">${escapeHtml(phaseId)}</a></td><td>0</td><td>—</td><td>—</td><td>—</td><td>${complete ? "usage not recorded" : "not run"}</td></tr>`;
+            return `<tr class="${complete ? "cc-usage-missing" : ""}"><td><a href="#${phaseAnchor(phaseId)}">${escapeHtml(phaseId)}</a></td><td>0</td><td>—</td><td>—</td><td>—</td><td>—</td><td>${complete ? "usage not recorded" : "not run"}</td></tr>`;
         }
         const tokensTotal = t.tokens.input + t.tokens.output;
-        return `<tr><td><a href="#${phaseAnchor(phaseId)}">${escapeHtml(phaseId)}</a></td><td>${t.runs}</td><td>${escapeHtml(tokenAccounting ? formatTokenCount(tokensTotal) : "unavailable")}</td><td>${renderUsageBar(t.tool_uses, maxTools, String(t.tool_uses))}</td><td>${renderUsageBar(t.duration_ms, maxDuration, formatMillis(t.duration_ms))}</td><td>${usagePhaseNote(phaseId, status)}</td></tr>`;
+        const compactions = t.compaction_runs > 0 ? formatCompactionTriplet(t.compactions) : "unavailable";
+        return `<tr><td><a href="#${phaseAnchor(phaseId)}">${escapeHtml(phaseId)}</a></td><td>${t.runs}</td><td>${escapeHtml(tokenAccounting ? formatTokenCount(tokensTotal) : "unavailable")}</td><td>${renderUsageBar(t.tool_uses, maxTools, String(t.tool_uses))}</td><td>${renderUsageBar(t.duration_ms, maxDuration, formatMillis(t.duration_ms))}</td><td>${compactions}</td><td>${usagePhaseNote(phaseId, status)}</td></tr>`;
     }).join("");
     return [
         `<section class="cc-card cc-usage" id="usage" aria-label="Token usage" data-section data-search-text="usage tokens tool duration">`,
@@ -393,7 +399,7 @@ function renderUsagePanel(inputs) {
         usage.runs.length === 0 ? `<p class="cc-empty">No phase runs recorded yet.</p>` : `<dl class="cc-usage-totals">${renderUsageTotalsList(totals, tokenAccounting)}</dl>`,
         renderUsageInsights(perPhase, status),
         `<table class="cc-usage-table">`,
-        `<thead><tr><th>Phase</th><th>Runs</th><th>Tokens</th><th>Tools</th><th>Duration</th><th>State</th></tr></thead>`,
+        `<thead><tr><th>Phase</th><th>Runs</th><th>Tokens</th><th>Tools</th><th>Duration</th><th>Compactions</th><th>State</th></tr></thead>`,
         `<tbody>${rows}</tbody>`,
         `</table>`,
         `</section>`,
@@ -405,7 +411,18 @@ function renderUsageTotalsList(totals, tokenAccounting) {
         ? `${escapeHtml(formatTokenCount(totals.tokens.input))} / ${escapeHtml(formatTokenCount(totals.tokens.output))} / ${escapeHtml(formatTokenCount(totals.tokens.cache_write))}`
         : `<span class="cc-muted">unavailable — host did not report token counts</span>`;
     const tokenTotal = tokenAccounting ? escapeHtml(formatTokenCount(tokensTotal)) : `<span class="cc-muted">unavailable</span>`;
-    return [`<dt>Total runs</dt><dd>${totals.runs}</dd>`, `<dt>Tokens (in / out / cache)</dt><dd>${tokenDetail}</dd>`, `<dt>Total tokens</dt><dd>${tokenTotal}</dd>`, `<dt>Tool uses</dt><dd>${totals.tool_uses}</dd>`, `<dt>Total duration</dt><dd>${escapeHtml(formatMillis(totals.duration_ms))}</dd>`].join("");
+    const compactionCounts = totals.compaction_runs > 0 ? formatCompactionCounts(totals.compactions) : `<span class="cc-muted">unavailable — host did not report compaction events</span>`;
+    const compactionReasons = totals.compaction_runs > 0 ? `<dt>Reasons</dt><dd>${formatCompactionReasons(totals.compactions)}</dd>` : "";
+    return [`<dt>Total runs</dt><dd>${totals.runs}</dd>`, `<dt>Tokens (in / out / cache)</dt><dd>${tokenDetail}</dd>`, `<dt>Total tokens</dt><dd>${tokenTotal}</dd>`, `<dt>Tool uses</dt><dd>${totals.tool_uses}</dd>`, `<dt>Total duration</dt><dd>${escapeHtml(formatMillis(totals.duration_ms))}</dd>`, `<dt>Compactions</dt><dd>${compactionCounts}</dd>`, compactionReasons].join("");
+}
+function formatCompactionCounts(value) {
+    return `${value.successful} successful · ${value.failed} failed · ${value.aborted} aborted`;
+}
+function formatCompactionReasons(value) {
+    return `threshold ${value.reasons.threshold} · overflow ${value.reasons.overflow} · manual ${value.reasons.manual}`;
+}
+function formatCompactionTriplet(value) {
+    return `${value.successful} / ${value.failed} / ${value.aborted}`;
 }
 function renderUsageInsights(perPhase, status) {
     if (perPhase.size === 0)
@@ -455,7 +472,7 @@ function renderOpenQuestionsRollup(status) {
     for (const [phaseId, phaseState] of Object.entries(status.phases)) {
         const questions = [];
         for (const q of phaseState.open_questions ?? []) {
-            const key = `${q.kind ?? ""}|${q.description ?? ""}|${q.deferred_reason ?? ""}`;
+            const key = q.id ?? `${q.kind ?? ""}|${q.description ?? ""}|${q.deferred_reason ?? ""}`;
             if (seen.has(key))
                 continue;
             seen.add(key);
@@ -473,6 +490,19 @@ function renderOpenQuestionsRollup(status) {
     const kindSummary = [...byKind.entries()].sort((a, b) => b[1] - a[1]).map(([kind, count]) => `<span class="cc-kind-chip"><strong>${count}</strong>${escapeHtml(kind)}</span>`).join("");
     return [`<section class="cc-card cc-rollup" aria-label="Open questions roll-up" data-section data-search-text="open questions">`, `<div class="cc-section-head"><h2>Open questions</h2><span>${total} unique</span></div>`, `<div class="cc-kind-summary">${kindSummary}</div>`, buckets.join("\n"), `</section>`].join("\n");
 }
+function renderPostPipelineWork(status) {
+    const items = status.post_pipeline ?? [];
+    if (items.length === 0)
+        return "";
+    const pending = items.filter((entry) => entry.status !== "resolved").length;
+    const rows = items.map((entry) => {
+        const state = entry.status ?? "pending";
+        const source = entry.source_phase ? `<span class="cc-pill cc-pill-target">from ${escapeHtml(entry.source_phase)}</span>` : "";
+        const kind = entry.kind ? `<span class="cc-kind">${escapeHtml(String(entry.kind))}</span>` : "";
+        return `<li>${kind}<strong>${escapeHtml(entry.id ?? "unidentified")}</strong> ${escapeHtml(entry.description ?? "")}${source}<span class="cc-pill">${escapeHtml(state)}</span></li>`;
+    }).join("");
+    return [`<section class="cc-card cc-rollup" id="post-pipeline" aria-label="Post-pipeline work" data-section data-search-text="post pipeline spikes amendments deltas decisions reruns">`, `<div class="cc-section-head"><h2>Post-pipeline work</h2><span>${pending} pending · ${items.length} total</span></div>`, `<p class="cc-muted">Optional work after the active pipeline; these items do not make pipeline completion partial.</p>`, `<ul class="cc-question-list">${rows}</ul>`, `</section>`].join("\n");
+}
 function renderCloseoutsList(inputs) {
     const closeouts = inputs.closeouts;
     if (closeouts.length === 0)
@@ -522,7 +552,7 @@ function renderExportData(inputs) {
             secondary_outputs: outputs?.secondary ?? [],
         };
     });
-    const data = { project: inputs.status.project_name, generatedAt: inputs.generatedAt, packageVersion: inputs.packageVersion, phases, usage: inputs.usage, closeouts: inputs.closeouts };
+    const data = { project: inputs.status.project_name, generatedAt: inputs.generatedAt, packageVersion: inputs.packageVersion, phases, post_pipeline: inputs.status.post_pipeline, usage: inputs.usage, closeouts: inputs.closeouts };
     return `<script id="cc-dashboard-data" type="application/json">${escapeJsonForScript(data)}</script>`;
 }
 function renderScripts() {

package/dist/core/index.d.ts

@@ -5,7 +5,9 @@ export * from "./status.ts";
 export * from "./pipeline.ts";
 export * from "./prompts.ts";
 export * from "./workspace.ts";
+export * from "./completion.ts";
 export * from "./orchestrator-config.ts";
 export * from "./usage.ts";
 export * from "./dashboard.ts";
 export * from "./library.ts";
+export * from "./synthesis.ts";

package/dist/core/index.js

@@ -8,7 +8,9 @@ export * from "./status.js";
 export * from "./pipeline.js";
 export * from "./prompts.js";
 export * from "./workspace.js";
+export * from "./completion.js";
 export * from "./orchestrator-config.js";
 export * from "./usage.js";
 export * from "./dashboard.js";
 export * from "./library.js";
+export * from "./synthesis.js";

package/dist/core/pipeline.js

@@ -9,6 +9,7 @@ export const PIPELINE_ALIASES = {
     "defect-scan": "workflow/pipeline-defect-scan.yaml",
     lite: "workflow/pipeline-lite.yaml",
     "architecture-only": "workflow/pipeline-architecture-only.yaml",
+    synthesis: "workflow/pipeline-synthesis.yaml",
 };
 export const DEFAULT_PIPELINE_PATH = "workflow/pipeline-full-with-deep-audit.yaml";
 export function getPhaseMap(pipeline) {

package/dist/core/prompts.d.ts

@@ -1,7 +1,15 @@
-import type { CarryForwardEntry, OpenQuestionEntry, PipelinePhase, ValidationResult, WorkspaceState } from "./types.ts";
+import type { CarryForwardEntry, OpenQuestionEntry, PipelinePhase, WorkspaceState } from "./types.ts";
+import { type PhasePreflightResult } from "./synthesis.ts";
 export declare function describeEntry(entry: OpenQuestionEntry | CarryForwardEntry): string;
 export declare function collectRoutedCarryForward(state: WorkspaceState, targetPhaseId: string): CarryForwardEntry[];
 export interface BuildPhasePromptOptions {
+    /**
+     * A result the caller already validated immediately before prompt building.
+     * Pi uses this to preserve its caller-specific preflight error handling
+     * without repeating the same filesystem reads. Callers that omit it (MCP
+     * and direct/forced prompting) remain self-contained and run preflight here.
+     */
+    preflight?: PhasePreflightResult;
     /**
      * Set when the phase is being run inside `/codecarto-next --auto` (or any
      * other non-interactive driver). Suppresses interactive hooks that would
@@ -14,7 +22,5 @@ export interface BuildPhasePromptOptions {
 }
 export declare function buildPhasePrompt(state: WorkspaceState, phase: PipelinePhase, forced: boolean, options?: BuildPhasePromptOptions): Promise<string>;
 export declare function closeoutFileName(date: string, phaseOrModule: string): string;
-export declare function buildThreadLogEntry(phaseOrModule: string, validation: ValidationResult, timestamp: string): string;
-export declare function ensureCloseoutStub(workspaceDir: string, phaseOrModule: string, timestamp: string): Promise<string | null>;
 export declare function listSkillNames(workspaceDir: string): Promise<string[]>;
 export declare function buildSkillPrompt(state: WorkspaceState, skillName: string): Promise<string>;