codecartographer-pi 0.11.0 → 0.12.0

package/dist/extensions/codecarto/auto-runner.js

@@ -17,7 +17,7 @@ import { buildSteeringMessage, rewritePhasePrompt } from "./agent-rewriter.js";
 import { buildPhaseSummary } from "./agent-summary.js";
 import { getAgentsWidget } from "./agent-widget.js";
 import { writeDashboard } from "./dashboard-writer.js";
-import { appendUsageRun, buildPhasePrompt, buildThreadLogEntry, buildValidationSummary, closeoutFileName, dateOnly, ensureCloseoutStub, formatMillis, formatTokenCount, getNextEligiblePhase, getWorkspaceState, loadCodecartoConfig, normalizeStatus, PACKAGE_VERSION, resolvePhase, uniqueStrings, updateStatusAtomically, validatePhaseOutput, } from "../../core/index.js";
+import { appendUsageRun, buildPhasePrompt, buildValidationSummary, completeValidatedPhase, formatMillis, formatTokenCount, getNextEligiblePhase, getWorkspaceState, loadCodecartoConfig, PACKAGE_VERSION, PhasePreflightError, runPhasePreflight, validatePhaseOutput, } from "../../core/index.js";
 /**
  * Run one phase end to end: optional LLM-steered rewrite, spawn the sub-agent,
  * wait for it, then emit the side effects the historical /codecarto-next chain
@@ -29,7 +29,10 @@ import { appendUsageRun, buildPhasePrompt, buildThreadLogEntry, buildValidationS
  * getPhaseActivity) and attached the agents widget if it wanted live progress.
  */
 export async function runSinglePhase(ctx, pi, state, phase, options) {
-    let prompt = await buildPhasePrompt(state, phase, false, { auto: options.auto === true });
+    let prompt = await buildPhasePrompt(state, phase, false, {
+        auto: options.auto === true,
+        preflight: options.preflight,
+    });
     if (options.llmSteerEnabled) {
         if (ctx.hasUI)
             ctx.ui.notify(`Customizing ${phase.id} prompt via LLM rewriter…`, "info");
@@ -149,73 +152,9 @@ export function isPhaseRunning(phaseId) {
     return existing?.status === "running";
 }
 export async function autoCompletePhase(ctx, validation) {
-    const completionTimestamp = new Date().toISOString();
-    const updatedState = await updateStatusAtomically(ctx.cwd, (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",
-        }));
-        const mergedOpenQuestions = [...existingPhase.open_questions];
-        for (const candidate of gapEntries) {
-            const dupe = mergedOpenQuestions.some((entry) => entry.description === candidate.description && entry.deferred_reason === candidate.deferred_reason);
-            if (!dupe)
-                mergedOpenQuestions.push(candidate);
-        }
-        nextStatus.phases[validation.phaseId] = {
-            status: "complete",
-            owner_notes: uniqueStrings([
-                ...existingPhase.owner_notes,
-                `Completed via /codecarto-complete on ${completionTimestamp}.`,
-                `Primary output: .codecarto/${validation.primaryOutput}`,
-                `Validation: ${validation.overall}`,
-            ]).slice(-3),
-            outputs_present: uniqueStrings([...existingPhase.outputs_present, validation.primaryOutput]),
-            open_questions: mergedOpenQuestions,
-            carry_forward: existingPhase.carry_forward ?? [],
-        };
-        nextStatus.last_updated = completionTimestamp;
-        const updatedWorkspaceState = {
-            ...lockedState,
-            status: nextStatus,
-        };
-        const nextEligible = getNextEligiblePhase(updatedWorkspaceState);
-        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."];
-        return {
-            state: { ...updatedWorkspaceState, status: nextStatus },
-            threadLogEntry: buildThreadLogEntry(validation.phaseId, validation, completionTimestamp),
-        };
-    });
-    let closeoutNotice;
-    try {
-        const created = await ensureCloseoutStub(updatedState.workspaceDir, validation.phaseId, completionTimestamp);
-        if (created) {
-            closeoutNotice = `Closeout stub: .codecarto/closeouts/${closeoutFileName(dateOnly(completionTimestamp), validation.phaseId)} (fill it in)`;
-        }
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        closeoutNotice = `Closeout stub not created: ${message}`;
-    }
+    const result = await completeValidatedPhase(ctx.cwd, validation, "/codecarto-complete");
     void writeDashboard(ctx.cwd, PACKAGE_VERSION);
-    return { updatedState, closeoutNotice };
+    return result;
 }
 export function decideAfterPhase(phaseStatus, phaseError, validation, strict) {
     if (phaseStatus === "aborted")
@@ -266,6 +205,18 @@ export async function runAuto(ctx, pi, initialState, options) {
                 reason: "Pipeline complete.",
             });
         }
+        let preflight;
+        try {
+            preflight = await runPhasePreflight(state, phase);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return finish({
+                outcome: "stopped",
+                reason: message,
+                stoppedAt: { phaseId: phase.id, error: err instanceof PhasePreflightError ? undefined : message },
+            });
+        }
         if (isPhaseRunning(phase.id)) {
             return finish({
                 outcome: "stopped",
@@ -277,6 +228,7 @@ export async function runAuto(ctx, pi, initialState, options) {
             llmSteerEnabled,
             signal: options.signal,
             auto: true,
+            preflight,
         });
         // Accumulate tokens whether the phase succeeded, was aborted, or errored.
         totalTokens.input += phaseResult.activity.lifetimeUsage.input;

package/dist/extensions/codecarto/index.js

@@ -1,4 +1,4 @@
-import { cp, mkdir, rm, writeFile } from "node:fs/promises";
+import { cp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { basename, join, resolve } from "node:path";
 import { autoCompletePhase, buildAutoSummary, isPhaseRunning, runAuto, runSinglePhase } from "./auto-runner.js";
 import { disposeAgentsWidget } from "./agent-widget.js";
@@ -7,10 +7,31 @@ import { narrateDashboard } from "./dashboard-narrator.js";
 import { writeDashboard } from "./dashboard-writer.js";
 import { parseNextFlags } from "./next-flags.js";
 import { phaseCompactionExtension } from "./phase-compaction.js";
-import { buildPhasePrompt, buildSkillPrompt, buildValidationSummary, canonicalPath, computePerPhaseTotals, computeTotals, createEmptyStatus, DEFAULT_PIPELINE_PATH, getNextEligiblePhase, getPipelineLabel, getWorkspaceState, isWithinPath, listSkillNames, loadCodecartoConfig, loadUsage, loadYamlFile, normalizeForComparison, packagedWorkspaceDir, pathExists, PACKAGE_VERSION, PIPELINE_ALIASES, resolvePhase, resolvePipelineChoice, stringifySimpleYaml, validatePhaseOutput, } from "../../core/index.js";
+import { buildPhasePrompt, buildSkillPrompt, buildValidationSummary, canonicalPath, computePerPhaseTotals, computeTotals, createEmptyStatus, DEFAULT_PIPELINE_PATH, deriveSlug, discoverLibrary, getNextEligiblePhase, getPipelineLabel, getWorkspaceState, isWithinPath, listSkillNames, loadCodecartoConfig, loadUsage, loadYamlFile, normalizeForComparison, packagedWorkspaceDir, pathExists, PACKAGE_VERSION, PhasePreflightError, PIPELINE_ALIASES, publishEntry, resolvePhase, resolvePipelineChoice, runPhasePreflight, stringifySimpleYaml, validatePhaseOutput, } from "../../core/index.js";
 const STATUS_WIDGET_ID = "codecarto-widget";
 const STATUS_LINE_ID = "codecarto-status";
 const SAFE_TOOL_NAMES = ["read", "grep", "find", "ls", "edit", "write"];
+function derivePublishHeadline(spec, cwd) {
+    const summary = spec.split(/^##\s+System Summary\s*$/mi)[1]?.split(/^##\s+/m)[0] ?? "";
+    const candidate = summary
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .find((line) => line && !line.startsWith("<!--") && !line.startsWith("-->") && !line.startsWith("#"));
+    return candidate?.replace(/\s+/g, " ").slice(0, 280) || `Reimplementation specification for ${basename(cwd)}.`;
+}
+function piGeneration(ctx) {
+    return {
+        surface: "pi-extension",
+        agent: "pi",
+        agent_version: "unknown",
+        model: ctx.model?.id ?? "unknown",
+        model_vendor: ctx.model?.provider ?? "unknown",
+        // Pi's extension context exposes the selected model but not the active
+        // thinking level. Preserve that uncertainty instead of inferring it.
+        reasoning: "unknown",
+        notes: "",
+    };
+}
 function formatUsageTokens(count) {
     if (count >= 1_000_000)
         return `${(count / 1_000_000).toFixed(2)}M`;
@@ -32,16 +53,19 @@ function buildStatusLines(state, extraLines = []) {
     const currentPhase = nextPhase?.id ?? state.status.current_phase ?? "complete";
     const pipelineLabel = getPipelineLabel(state.status.pipeline);
     const completedCount = state.pipeline.phase_order.filter((phaseId) => state.status.phases[phaseId]?.status === "complete").length;
-    const currentOpenQuestions = currentPhase === "complete" ? 0 : state.status.phases[currentPhase]?.open_questions.length ?? 0;
+    const terminalOpenQuestions = Object.values(state.status.phases).reduce((sum, phase) => sum + (phase.open_questions?.length ?? 0), 0);
     const totalCarryForward = Object.values(state.status.phases).reduce((sum, phase) => sum + (phase.carry_forward?.length ?? 0), 0);
+    const postPipelinePending = state.status.post_pipeline.filter((entry) => entry.status !== "resolved").length;
     const nextAction = state.status.next_actions[0] ?? (nextPhase ? `Next: ${nextPhase.id}` : "All phases complete.");
     const lines = [
         "CodeCartographer",
         `Phase: ${currentPhase}`,
+        `Pipeline state: ${currentPhase === "complete" ? "complete" : "in progress"}`,
         `Pipeline: ${pipelineLabel}`,
         `Progress: ${completedCount}/${state.pipeline.phase_order.length} complete`,
-        `Open questions: ${currentOpenQuestions}`,
-        `Carry-forward: ${totalCarryForward}`,
+        `Open questions (terminal unresolved): ${terminalOpenQuestions}`,
+        `Carry-forward (pipeline phases): ${totalCarryForward}`,
+        `Post-pipeline work: ${postPipelinePending} pending`,
         `Next: ${nextAction}`,
     ];
     if (extraLines.length > 0) {
@@ -135,12 +159,16 @@ export default function codeCartographerExtension(pi) {
             const inputPath = typeof event.input.path === "string" ? event.input.path : "";
             const strippedPath = inputPath.startsWith("@") ? inputPath.slice(1) : inputPath;
             const targetPath = await canonicalPath(resolve(ctx.cwd, strippedPath));
-            const allowedRoot = await canonicalPath(workspaceDir);
-            if (!isWithinPath(targetPath, allowedRoot)) {
+            const allowedRoots = [await canonicalPath(workspaceDir)];
+            const config = await loadCodecartoConfig(workspaceDir);
+            if (config.library.path && await discoverLibrary(config.library.path)) {
+                allowedRoots.push(await canonicalPath(config.library.path));
+            }
+            if (!allowedRoots.some((allowedRoot) => isWithinPath(targetPath, allowedRoot))) {
                 if (ctx.hasUI) {
-                    ctx.ui.notify(`Blocked ${event.toolName} outside .codecarto/: ${inputPath}`, "warning");
+                    ctx.ui.notify(`Blocked ${event.toolName} outside .codecarto/ or configured library: ${inputPath}`, "warning");
                 }
-                return { block: true, reason: `CodeCartographer mode only allows ${event.toolName} within .codecarto/` };
+                return { block: true, reason: `CodeCartographer mode only allows ${event.toolName} within .codecarto/ or the configured CodeCartographer library.` };
             }
         }
         return undefined;
@@ -292,6 +320,17 @@ export default function codeCartographerExtension(pi) {
                 ctx.ui.notify("All CodeCartographer phases are complete.", "info");
                 return;
             }
+            let preflight;
+            try {
+                preflight = await runPhasePreflight(state, phase);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                lastFeedbackLines = [message];
+                setUiState(ctx, state, lastFeedbackLines);
+                ctx.ui.notify(message, error instanceof PhasePreflightError ? "warning" : "error");
+                return;
+            }
             // Reject re-entry: don't spawn a duplicate runner for a phase that's
             // already in flight from a previous /codecarto-next invocation.
             if (isPhaseRunning(phase.id)) {
@@ -305,7 +344,7 @@ export default function codeCartographerExtension(pi) {
             // Fire-and-forget: keep the TUI responsive while the sub-agent works.
             // runSinglePhase handles all side effects (steering message, notify,
             // phase summary, recordUsage, dashboard regen, clearPhase linger).
-            void runSinglePhase(ctx, pi, state, phase, { llmSteerEnabled, signal: ctx.signal })
+            void runSinglePhase(ctx, pi, state, phase, { llmSteerEnabled, signal: ctx.signal, preflight })
                 .finally(() => {
                 // Refresh the status widget after the phase resolves so the
                 // "Open questions / Carry-forward / Next" lines reflect any
@@ -330,7 +369,15 @@ export default function codeCartographerExtension(pi) {
                 ctx.ui.notify(`Unknown phase: ${phaseId}`, "error");
                 return;
             }
-            const prompt = await buildPhasePrompt(state, phase, true);
+            let prompt;
+            try {
+                prompt = await buildPhasePrompt(state, phase, true);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                ctx.ui.notify(message, error instanceof PhasePreflightError ? "warning" : "error");
+                return;
+            }
             if (ctx.isIdle()) {
                 pi.sendUserMessage(prompt);
             }
@@ -431,6 +478,73 @@ export default function codeCartographerExtension(pi) {
             ctx.ui.notify(`Queued CodeCartographer skill: ${skillName}`, "info");
         },
     });
+    pi.registerCommand("codecarto-publish", {
+        description: "Publish the completed reimplementation spec to the configured CodeCartographer library",
+        handler: async (_args, ctx) => {
+            const state = await ensureWorkspaceState(ctx);
+            if (!state)
+                return;
+            const config = await loadCodecartoConfig(state.workspaceDir);
+            if (!config.library.path) {
+                ctx.ui.notify("No library.path is configured. Set it in ~/.codecarto/config.yaml or .codecarto/workflow/config.yaml.", "error");
+                return;
+            }
+            const marker = await discoverLibrary(config.library.path);
+            if (!marker) {
+                ctx.ui.notify(`No CodeCartographer library at ${config.library.path} (missing .codecarto-library).`, "error");
+                return;
+            }
+            const phase = resolvePhase(state, "reimplementation-spec");
+            if (!phase?.primary_output) {
+                ctx.ui.notify("The active pipeline does not produce a reimplementation spec to publish.", "error");
+                return;
+            }
+            const specPath = join(state.workspaceDir, phase.primary_output);
+            if (!(await pathExists(specPath))) {
+                ctx.ui.notify(`Reimplementation spec is missing: .codecarto/${phase.primary_output}`, "error");
+                return;
+            }
+            const spec = await readFile(specPath, "utf8");
+            const slug = deriveSlug(ctx.cwd);
+            const headline = derivePublishHeadline(spec, ctx.cwd);
+            const namespace = marker.namespaced ? config.library.namespace ?? undefined : undefined;
+            if (marker.namespaced && !namespace) {
+                ctx.ui.notify("The configured library is namespaced; set library.namespace before publishing.", "error");
+                return;
+            }
+            const preview = [
+                `Publish ${namespace ? `${namespace}/` : ""}${slug} to ${config.library.path}`,
+                `Source: ${ctx.cwd}`,
+                `Spec: .codecarto/${phase.primary_output}`,
+                `Headline: ${headline}`,
+                `Provenance: Pi / ${ctx.model?.provider ?? "unknown"} / ${ctx.model?.id ?? "unknown"}`,
+            ].join("\n");
+            if (config.library.publish_confirm && !(await ctx.ui.confirm("Publish reimplementation spec", preview)))
+                return;
+            try {
+                const result = await publishEntry(config.library.path, spec, {
+                    slug,
+                    namespace,
+                    source_repo: ctx.cwd,
+                    analyzed_at: new Date().toISOString(),
+                    pipeline: state.status.pipeline,
+                    codecarto_version: PACKAGE_VERSION,
+                    headline,
+                    tags: [],
+                    capabilities: [],
+                    generation: piGeneration(ctx),
+                });
+                lastFeedbackLines = [`Published ${result.namespace ? `${result.namespace}/` : ""}${result.slug} v${result.version}`, result.isNewVersion ? "New content version." : "Metadata-only update (content unchanged)."];
+                await writeDashboard(ctx.cwd, PACKAGE_VERSION);
+                await refreshWorkspaceUi(ctx, lastFeedbackLines);
+                ctx.ui.notify(`Published ${result.namespace ? `${result.namespace}/` : ""}${result.slug} v${result.version}.`, "info");
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                ctx.ui.notify(`Unable to publish: ${message}`, "error");
+            }
+        },
+    });
     pi.registerCommand("codecarto-usage", {
         description: "Show cumulative + per-phase token usage from local phase runs",
         handler: async (_args, ctx) => {

package/dist/mcp-server/server.js

@@ -15,7 +15,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError, } from "@modelcontextprotocol/sdk/types.js";
 import { cp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { basename, isAbsolute, join } from "node:path";
-import { buildPhasePrompt, buildSkillPrompt, buildThreadLogEntry, buildValidationSummary, canonicalPath, closeoutFileName, createEmptyStatus, dateOnly, DEFAULT_PIPELINE_PATH, deriveSlug, discoverLibrary, ensureCloseoutStub, getNextEligiblePhase, getPipelineLabel, getWorkspaceState, isValidSlug, listEntries, listSkillNames, loadCodecartoConfig, loadYamlFile, normalizeForComparison, normalizeStatus, PACKAGE_VERSION, packagedWorkspaceDir, pathExists, publishEntry, reindex as libraryReindex, resolvePhase, resolvePipelineChoice, stringifySimpleYaml, uniqueStrings, updateStatusAtomically, validatePhaseOutput, } from "../core/index.js";
+import { buildPhasePrompt, buildSkillPrompt, buildValidationSummary, canonicalPath, completeValidatedPhase, createEmptyStatus, DEFAULT_PIPELINE_PATH, deriveSlug, discoverLibrary, getNextEligiblePhase, getPipelineLabel, getWorkspaceState, isValidSlug, listEntries, listSkillNames, loadCodecartoConfig, loadYamlFile, normalizeForComparison, PACKAGE_VERSION, packagedWorkspaceDir, pathExists, PhasePreflightError, publishEntry, reindex as libraryReindex, resolvePhase, resolvePipelineChoice, stringifySimpleYaml, validatePhaseOutput, } from "../core/index.js";
 // ---------- input helpers ----------
 async function validateCwd(cwd) {
     if (typeof cwd !== "string" || !cwd.trim()) {
@@ -46,6 +46,17 @@ function textResult(text, structured) {
         result.structuredContent = structured;
     return result;
 }
+async function buildMcpPhasePrompt(state, phase, forced) {
+    try {
+        return await buildPhasePrompt(state, phase, forced);
+    }
+    catch (error) {
+        if (error instanceof PhasePreflightError) {
+            throw new McpError(ErrorCode.InvalidRequest, error.message);
+        }
+        throw error;
+    }
+}
 // ---------- handlers ----------
 export async function handleInit(args) {
     const cwd = await validateCwd(args.cwd);
@@ -101,12 +112,16 @@ export async function handleStatus(args) {
     const completed = state.pipeline.phase_order.filter((id) => state.status.phases[id]?.status === "complete").length;
     const totalCarryForward = Object.values(state.status.phases).reduce((sum, phase) => sum + (phase.carry_forward?.length ?? 0), 0);
     const currentOpenQuestions = currentPhase === "complete" ? 0 : state.status.phases[currentPhase]?.open_questions.length ?? 0;
+    const terminalOpenQuestions = Object.values(state.status.phases).reduce((sum, phase) => sum + (phase.open_questions?.length ?? 0), 0);
+    const postPipelinePending = state.status.post_pipeline.filter((entry) => entry.status !== "resolved").length;
     const summary = [
         `Phase: ${currentPhase}`,
+        `Pipeline state: ${currentPhase === "complete" ? "complete" : "in progress"}`,
         `Pipeline: ${getPipelineLabel(state.status.pipeline)} (${state.status.pipeline})`,
         `Progress: ${completed}/${state.pipeline.phase_order.length} complete`,
-        `Open questions (current phase): ${currentOpenQuestions}`,
-        `Carry-forward (all phases): ${totalCarryForward}`,
+        `Open questions (terminal unresolved): ${terminalOpenQuestions}`,
+        `Carry-forward (pipeline phases): ${totalCarryForward}`,
+        `Post-pipeline work: ${postPipelinePending} pending`,
         `Next: ${state.status.next_actions[0] ?? (nextPhase ? `Begin ${nextPhase.id}` : "All phases complete.")}`,
     ].join("\n");
     return textResult(summary, {
@@ -116,7 +131,9 @@ export async function handleStatus(args) {
         completed,
         total: state.pipeline.phase_order.length,
         openQuestionsCurrentPhase: currentOpenQuestions,
+        openQuestionsTerminal: terminalOpenQuestions,
         carryForwardTotal: totalCarryForward,
+        postPipelinePending,
         nextActions: state.status.next_actions,
     });
 }
@@ -129,7 +146,7 @@ export async function handleNext(args) {
             complete: true,
         });
     }
-    const prompt = await buildPhasePrompt(state, phase, false);
+    const prompt = await buildMcpPhasePrompt(state, phase, false);
     return textResult(prompt, { phase: phase.id, forced: false });
 }
 export async function handlePhase(args) {
@@ -142,7 +159,7 @@ export async function handlePhase(args) {
     if (!phase) {
         throw new McpError(ErrorCode.InvalidParams, `Unknown phase: ${args.phase}`);
     }
-    const prompt = await buildPhasePrompt(state, phase, true);
+    const prompt = await buildMcpPhasePrompt(state, phase, true);
     return textResult(prompt, { phase: phase.id, forced: true });
 }
 export async function handleValidate(args) {
@@ -172,70 +189,9 @@ export async function handleComplete(args) {
     if (validation.overall === "FAIL" || validation.overall === "MISSING") {
         throw new McpError(ErrorCode.InvalidRequest, `Cannot complete ${validation.phaseId}: validation is ${validation.overall}.\n${buildValidationSummary(validation).join("\n")}`);
     }
-    const completionTimestamp = new Date().toISOString();
-    const updatedState = await updateStatusAtomically(cwd, (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",
-        }));
-        const mergedOpenQuestions = [...existingPhase.open_questions];
-        for (const candidate of gapEntries) {
-            const dupe = mergedOpenQuestions.some((entry) => entry.description === candidate.description && entry.deferred_reason === candidate.deferred_reason);
-            if (!dupe)
-                mergedOpenQuestions.push(candidate);
-        }
-        nextStatus.phases[validation.phaseId] = {
-            status: "complete",
-            owner_notes: uniqueStrings([
-                ...existingPhase.owner_notes,
-                `Completed via codecarto_complete on ${completionTimestamp}.`,
-                `Primary output: .codecarto/${validation.primaryOutput}`,
-                `Validation: ${validation.overall}`,
-            ]).slice(-3),
-            outputs_present: uniqueStrings([...existingPhase.outputs_present, validation.primaryOutput]),
-            open_questions: mergedOpenQuestions,
-            carry_forward: existingPhase.carry_forward ?? [],
-        };
-        nextStatus.last_updated = completionTimestamp;
-        const updatedWorkspaceState = {
-            ...lockedState,
-            status: nextStatus,
-        };
-        const nextEligible = getNextEligiblePhase(updatedWorkspaceState);
-        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."];
-        return {
-            state: { ...updatedWorkspaceState, status: nextStatus },
-            threadLogEntry: buildThreadLogEntry(validation.phaseId, validation, completionTimestamp),
-        };
+    const { updatedState, closeoutNotice } = await completeValidatedPhase(cwd, validation, "codecarto_complete").catch((error) => {
+        throw new McpError(ErrorCode.InvalidParams, error instanceof Error ? error.message : String(error));
     });
-    let closeoutNotice;
-    try {
-        const created = await ensureCloseoutStub(updatedState.workspaceDir, validation.phaseId, completionTimestamp);
-        if (created) {
-            closeoutNotice = `Closeout stub created: .codecarto/closeouts/${closeoutFileName(dateOnly(completionTimestamp), validation.phaseId)} (fill it in)`;
-        }
-    }
-    catch (error) {
-        closeoutNotice = `Closeout stub not created: ${error instanceof Error ? error.message : String(error)}`;
-    }
     const lines = [
         `Marked ${validation.phaseId} complete (validation: ${validation.overall}).`,
         `Next phase: ${updatedState.status.current_phase}`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codecartographer-pi",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "CodeCartographer packaged for Pi as an extension-driven workflow wrapper.",
   "type": "module",
   "keywords": [
@@ -37,7 +37,8 @@
     "build": "tsc",
     "prepublishOnly": "npm run build",
     "test": "node --experimental-strip-types --disable-warning=ExperimentalWarning --test tests/*.test.mjs",
-    "smoke": "node scripts/smoke-mcp.mjs"
+    "smoke": "node scripts/smoke-mcp.mjs",
+    "demo:synthesis": "npm run build && node scripts/create-synthesis-demo.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0"