codecartographer-pi 0.12.2 → 0.12.4

package/README.md

@@ -86,7 +86,7 @@ Add to your host config (`~/.config/claude-code/config.json`, `claude_desktop_co
 }
 ```
 
-Official MCP Registry server name: `io.github.HuginnIndustries/codecartographer`.
+[Official MCP Registry listing](https://registry.modelcontextprotocol.io/?search=CodeCartographer): `io.github.HuginnIndustries/codecartographer`.
 
 ### Drop-in template (one-off / evaluation)
 
@@ -288,7 +288,7 @@ Beyond the slash commands, the Pi extension layers on:
 | `/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-next [--auto [--strict]] [--llm-steer \| --no-llm-steer]` | Spawn the next eligible phase as a sub-agent. After the sub-agent finishes, auto-validates and auto-completes the phase so `status.yaml` advances without manual steps. `--auto` walks the full pipeline end-to-end (same validate + complete + advance loop, repeated); `--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]` | Validate and atomically apply the phase handoff, canonical status, closeout, and log entry |

package/dist/core/synthesis.js

@@ -78,25 +78,25 @@ export async function runPhasePreflight(state, phase) {
     if (checks.has("requires-vision-input")) {
         const visionPath = join(state.workspaceDir, SYNTHESIS_VISION_INPUT_PATH);
         if (!(await pathExists(visionPath))) {
-            throw new PhasePreflightError(phase.id, `the vision brief is missing at .codecarto/${SYNTHESIS_VISION_INPUT_PATH}. Create it before starting synthesis.`);
+            throw new PhasePreflightError(phase.id, `the vision brief is missing at .codecarto/${SYNTHESIS_VISION_INPUT_PATH}. Create that file and describe your product intent (audience, problem, desired outcome, constraints, non-goals). See .codecarto/templates/vision.md for the expected structure.`);
         }
         const rawVision = await readFile(visionPath, "utf8");
         if (!hasMeaningfulVisionContent(rawVision)) {
-            throw new PhasePreflightError(phase.id, `the vision brief at .codecarto/${SYNTHESIS_VISION_INPUT_PATH} is still empty. Describe the audience, problem, and desired outcome, then retry.`);
+            throw new PhasePreflightError(phase.id, `the vision brief at .codecarto/${SYNTHESIS_VISION_INPUT_PATH} appears to be empty or only contains comments. Write your product intent into that file — at minimum: who the product is for, what problem it solves, and what outcome you want. See .codecarto/templates/vision.md for the full structure.`);
         }
     }
     if (checks.has("requires-library")) {
         const config = await loadCodecartoConfig(state.workspaceDir);
         if (!config.library.path) {
-            throw new PhasePreflightError(phase.id, "no library.path is configured. Set it in ~/.codecarto/config.yaml or .codecarto/workflow/config.yaml.");
+            throw new PhasePreflightError(phase.id, "no library.path is configured. Create a library directory with a .codecarto-library marker file, then set library.path in ~/.codecarto/config.yaml or .codecarto/workflow/config.yaml. Example config:\n  library:\n    path: ~/codecarto-library\n    publish_confirm: true");
         }
         const marker = await discoverLibrary(config.library.path);
         if (!marker) {
-            throw new PhasePreflightError(phase.id, `no CodeCartographer library was found at ${config.library.path} (missing .codecarto-library).`);
+            throw new PhasePreflightError(phase.id, `no CodeCartographer library was found at ${config.library.path} (missing .codecarto-library). Create a .codecarto-library marker file in that directory with: {"schema_version": 1, "name": "personal-library", "visibility": "internal", "namespaced": false}`);
         }
         const entries = await listEntries(config.library.path);
         if (entries.length === 0) {
-            throw new PhasePreflightError(phase.id, `the configured library at ${config.library.path} has no entries. Publish at least one reimplementation spec first.`);
+            throw new PhasePreflightError(phase.id, `the configured library at ${config.library.path} has no entries. Run a reverse-engineering pipeline (e.g. /codecarto-init full-with-deep-audit) on a source repository, then use /codecarto-publish to publish at least one reimplementation spec into the library before starting synthesis.`);
         }
         result.libraryPath = config.library.path;
         result.libraryName = marker.name;
@@ -110,13 +110,13 @@ export async function runPhasePreflight(state, phase) {
         result.confirmedSelections = parseConfirmedProposalSelections(await readFile(proposalPath, "utf8"));
         result.confirmedEntries = result.confirmedSelections.map((selection) => selection.ref);
         if (result.confirmedSelections.length === 0) {
-            throw new PhasePreflightError(phase.id, `no library entries are confirmed in .codecarto/${SYNTHESIS_PROPOSAL_PATH}. Change at least one [ ] checkbox to [x], then retry.`);
+            throw new PhasePreflightError(phase.id, `no library entries are confirmed in .codecarto/${SYNTHESIS_PROPOSAL_PATH}. Open that file and change at least one [ ] checkbox to [x] for the entry you want to include, then retry.`);
         }
         const available = new Map(result.libraryEntries.map((entry) => [entry.ref, entry]));
         for (const selection of result.confirmedSelections) {
             const entry = available.get(selection.ref);
             if (!entry || !entry.versions.includes(selection.version)) {
-                throw new PhasePreflightError(phase.id, `confirmed selection ${selection.ref}@v${selection.version} is not present in the configured library. Re-run the proposal phase or correct the checked row.`);
+                throw new PhasePreflightError(phase.id, `confirmed selection ${selection.ref}@v${selection.version} is not present in the configured library. Edit .codecarto/${SYNTHESIS_PROPOSAL_PATH} to correct the checked row (change [x] back to [ ] or update the version), or re-run the goal-synthesis-propose phase to regenerate the proposal.`);
             }
             selection.specPath = specPathForVersion(result.libraryPath, selection.ref, selection.version);
         }

package/dist/extensions/codecarto/agent-summary.js

@@ -66,7 +66,7 @@ function formatTrailer(input) {
         lines.push(`Phase transcript: \`${input.sessionFile}\` (open via \`/resume\`).`);
     }
     if (input.status === "completed") {
-        lines.push("Run `/codecarto-validate` to check the output, then `/codecarto-complete` to advance.");
+        lines.push("Auto-validating and completing the phase — check the status widget for the result.");
     }
     return lines.join("\n");
 }

package/dist/extensions/codecarto/index.js

@@ -1,4 +1,4 @@
-import { cp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { cp, mkdir, readFile, rename, 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";
@@ -220,10 +220,13 @@ export default function codeCartographerExtension(pi) {
             if (targetExists) {
                 const sameWorkspace = normalizeForComparison(await canonicalPath(targetWorkspaceDir)) === normalizeForComparison(await canonicalPath(sourceWorkspaceDir));
                 if (!sameWorkspace) {
-                    const overwrite = await ctx.ui.confirm("CodeCartographer already exists", "A .codecarto/ directory already exists in this repository. Overwrite it?");
+                    const overwrite = await ctx.ui.confirm("CodeCartographer already exists — data will be lost", "A .codecarto/ directory already exists in this repository. Re-initializing will back up the existing workspace to .codecarto-backup-TIMESTAMP/ and create a fresh one. All phase findings, handoffs, usage data, closeouts, and progress will be moved to the backup. Consider /codecarto-open to reattach without resetting. Continue?");
                     if (!overwrite)
                         return;
-                    await rm(targetWorkspaceDir, { recursive: true, force: true });
+                    const backupDir = join(ctx.cwd, `.codecarto-backup-${new Date().toISOString().replace(/[:.]/g, "-")}`);
+                    await rename(targetWorkspaceDir, backupDir);
+                    if (ctx.hasUI)
+                        ctx.ui.notify(`Backed up existing workspace to ${basename(backupDir)}/`, "info");
                 }
             }
             if (!(await pathExists(targetWorkspaceDir))) {
@@ -344,7 +347,59 @@ 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).
+            // After the sub-agent finishes, auto-validate and auto-complete the
+            // phase so status.yaml advances without requiring the user to manually
+            // run /codecarto-validate then /codecarto-complete. This mirrors what
+            // the auto loop (runAuto) does after each phase.
             void runSinglePhase(ctx, pi, state, phase, { llmSteerEnabled, signal: ctx.signal, preflight })
+                .then(async (result) => {
+                if (result.status !== "completed")
+                    return;
+                // Refresh state from disk — the sub-agent may have written
+                // findings that the validator needs to read.
+                const stateForValidation = (await getWorkspaceState(ctx.cwd)) ?? state;
+                const validation = await validatePhaseOutput(stateForValidation, phase.id).catch((error) => (error instanceof Error ? error : new Error(String(error))));
+                if (validation instanceof Error) {
+                    if (ctx.hasUI)
+                        ctx.ui.notify(`Auto-validation error for ${phase.id}: ${validation.message}`, "warning");
+                    lastFeedbackLines = [`Validation error: ${validation.message}`, "Run `/codecarto-validate` then `/codecarto-complete` manually."];
+                    return;
+                }
+                if (validation.overall === "FAIL" || validation.overall === "MISSING") {
+                    if (ctx.hasUI)
+                        ctx.ui.notify(`Phase ${phase.id} validation: ${validation.overall}. Fix the output, then re-run /codecarto-next.`, "warning");
+                    lastFeedbackLines = buildValidationSummary(validation);
+                    return;
+                }
+                // PASS or PASS WITH GAPS — auto-complete the phase.
+                try {
+                    const { updatedState, closeoutNotice } = await autoCompletePhase(ctx, validation);
+                    if (ctx.hasUI) {
+                        ctx.ui.notify(`Phase ${phase.id} auto-completed (validation: ${validation.overall}).`, validation.overall === "PASS WITH GAPS" ? "warning" : "info");
+                        if (closeoutNotice)
+                            ctx.ui.notify(closeoutNotice, "info");
+                    }
+                    lastFeedbackLines = [
+                        `Completed phase: ${validation.phaseId}`,
+                        `Validation: ${validation.overall}`,
+                        `Next phase: ${updatedState.status.current_phase}`,
+                    ];
+                    if (closeoutNotice)
+                        lastFeedbackLines.push(closeoutNotice);
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    if (ctx.hasUI)
+                        ctx.ui.notify(`Auto-completion failed for ${phase.id}: ${message}. Run /codecarto-complete manually.`, "warning");
+                    lastFeedbackLines = [`Auto-completion failed: ${message}`, "Run `/codecarto-complete` manually."];
+                }
+            })
+                .catch((error) => {
+                const message = error instanceof Error ? error.message : String(error);
+                if (ctx.hasUI)
+                    ctx.ui.notify(`Post-phase processing error for ${phase.id}: ${message}`, "warning");
+                lastFeedbackLines = [`Post-phase error: ${message}`];
+            })
                 .finally(() => {
                 // Refresh the status widget after the phase resolves so the
                 // "Open questions / Carry-forward / Next" lines reflect any
@@ -486,12 +541,12 @@ export default function codeCartographerExtension(pi) {
                 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");
+                ctx.ui.notify("No library.path is configured. Create a library directory with a .codecarto-library marker, then set library.path 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");
+                ctx.ui.notify(`No CodeCartographer library at ${config.library.path} (missing .codecarto-library). Create a .codecarto-library marker file in that directory.`, "error");
                 return;
             }
             const phase = resolvePhase(state, "reimplementation-spec");

package/dist/mcp-server/server.js

@@ -13,7 +13,7 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 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 { cp, mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { basename, isAbsolute, join } from "node:path";
 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 ----------
@@ -77,9 +77,10 @@ export async function handleInit(args) {
     }
     if (targetExists && !sameWorkspace) {
         if (!args.force) {
-            throw new McpError(ErrorCode.InvalidRequest, `A .codecarto/ directory already exists at ${targetWorkspaceDir}. Pass force: true to overwrite it.`);
+            throw new McpError(ErrorCode.InvalidRequest, `A .codecarto/ directory already exists at ${targetWorkspaceDir}. Pass force: true to back it up and reinitialize. Warning: this moves all existing findings, handoffs, usage data, closeouts, and phase progress to a .codecarto-backup-TIMESTAMP/ directory.`);
         }
-        await rm(targetWorkspaceDir, { recursive: true, force: true });
+        const backupDir = join(cwd, `.codecarto-backup-${new Date().toISOString().replace(/[:.]/g, "-")}`);
+        await rename(targetWorkspaceDir, backupDir);
     }
     if (!(await pathExists(targetWorkspaceDir))) {
         await mkdir(cwd, { recursive: true });
@@ -463,7 +464,7 @@ export async function handleLibraryReindex(args) {
 const TOOLS = [
     {
         name: "codecarto_init",
-        description: "Initialize a CodeCartographer workspace (.codecarto/) in a target repository. Copies the packaged framework template and writes a fresh status.yaml for the chosen pipeline. Errors if .codecarto/ already exists unless force is true.",
+        description: "Initialize a CodeCartographer workspace (.codecarto/) in a target repository. Copies the packaged framework template and writes a fresh status.yaml for the chosen pipeline. If .codecarto/ already exists, pass force: true to back up the existing workspace to .codecarto-backup-TIMESTAMP/ and create a fresh one. Warning: backing up moves all existing findings, handoffs, usage data, closeouts, and phase progress to the backup directory.",
         inputSchema: {
             type: "object",
             properties: {
@@ -474,7 +475,7 @@ const TOOLS = [
                 },
                 force: {
                     type: "boolean",
-                    description: "Overwrite an existing .codecarto/ directory if present (default false).",
+                    description: "Back up and overwrite an existing .codecarto/ directory if present (default false).",
                 },
             },
             required: ["cwd"],
@@ -625,7 +626,7 @@ const HANDLERS = {
 };
 // ---------- server bootstrap ----------
 export function buildServer() {
-    const server = new Server({ name: "codecartographer", version: "0.2.0" }, { capabilities: { tools: {} } });
+    const server = new Server({ name: "codecartographer", version: PACKAGE_VERSION }, { capabilities: { tools: {} } });
     server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const handler = HANDLERS[request.params.name];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codecartographer-pi",
-  "version": "0.12.2",
+  "version": "0.12.4",
   "mcpName": "io.github.HuginnIndustries/codecartographer",
   "description": "Evidence-backed reverse engineering and human-gated software planning for Pi and MCP coding agents.",
   "type": "module",