codecartographer-pi 0.17.0 → 0.18.0

package/dist/extensions/codecarto/index.js

@@ -1,6 +1,6 @@
 import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
-import { basename, join, resolve } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
 import { autoCompletePhase, buildAutoSummary, isPhaseRunning, runAuto, runSinglePhase } from "./auto-runner.js";
 import { disposeAgentsWidget } from "./agent-widget.js";
 import { parseDashboardFlags } from "./dashboard-flags.js";
@@ -9,7 +9,7 @@ import { writeDashboard } from "./dashboard-writer.js";
 import { parseBroadsideFlags, KNOWN_BROADSIDE_TOKENS } from "./broadside-flags.js";
 import { parseNextFlags } from "./next-flags.js";
 import { phaseCompactionExtension } from "./phase-compaction.js";
-import { buildPhasePrompt, buildSkillPrompt, buildValidationSummary, canonicalPath, copyPackagedWorkspace, computePerPhaseTotals, computeTotals, createEmptyStatus, DEFAULT_PIPELINE_PATH, describeScaffoldStaleness, deriveSlug, discoverLibrary, getNextEligiblePhase, getPipelineLabel, getWorkspaceState, isWithinPathResolved, BROADSIDE_LENS_IDS, BROADSIDE_SKILL_NAME, BroadsideCancelledError, broadsideDirFor, collectResultText, estimateSubmitText, getLens, listBatchModels, listSkillNames, loadBroadsideConfig, modelsText, runBroadsideCollect, runBroadsideStatus, runBroadsideSubmit, statusText, loadCodecartoConfig, loadUsage, loadYamlFile, normalizeForComparison, packagedWorkspaceDir, pathExists, PACKAGE_VERSION, readBroadsideSkill, PhasePreflightError, PIPELINE_ALIASES, publishEntry, resolvePhase, resolvePipelineChoice, runPhasePreflight, seedOrchestratorFiles, stringifySimpleYaml, switchPipeline, validatePhaseOutput, writeLibraryConfig, } from "../../core/index.js";
+import { applyAmendment, buildPhasePrompt, buildSkillPrompt, buildValidationSummary, canonicalPath, copyPackagedWorkspace, computePerPhaseTotals, computeTotals, ConfidentialityMismatchError, createEmptyStatus, DEFAULT_PIPELINE_PATH, describeScaffoldStaleness, deriveSlug, discoverLibrary, getNextEligiblePhase, getPipelineLabel, getWorkspaceState, isWithinPathResolved, BROADSIDE_LENS_IDS, BROADSIDE_SKILL_NAME, BroadsideCancelledError, broadsideDirFor, collectResultText, estimateSubmitText, getLens, listAmendmentNames, listBatchModels, listGuideTopics, listScaffoldRefreshFiles, listSkillNames, loadAmendmentFile, loadBroadsideConfig, modelsText, runBroadsideCollect, runBroadsideStatus, runBroadsideSubmit, statusText, loadCodecartoConfig, loadUsage, loadYamlFile, normalizeForComparison, packagedWorkspaceDir, pathExists, PACKAGE_VERSION, readBroadsideSkill, readGuide, refreshScaffold, PhasePreflightError, PIPELINE_ALIASES, publishEntry, resolvePhase, resolvePipelineChoice, resolvePublishSourceRepo, SourceRepoMismatchError, runPhasePreflight, SCAFFOLD_REFRESH_PROTECTED, seedOrchestratorFiles, stringifySimpleYaml, switchPipeline, validatePhaseOutput, writeLibraryConfig, } from "../../core/index.js";
 import { initLibrary } from "../../core/library.js";
 import { resolveUserConfigPath } from "../../core/orchestrator-config.js";
 const STATUS_WIDGET_ID = "codecarto-widget";
@@ -137,11 +137,130 @@ function describeBroadsideEstimate(estimate) {
     lines.push("", "The estimate is a pre-flight prediction from file sizes; OpenRouter bills actual usage.");
     return lines.join("\n");
 }
+/**
+ * Resolve the argument of /codecarto-amend to the slug applyAmendment takes.
+ * Accepts the slug, `slug.yaml`, or a path to the file — but a path only when
+ * it lands inside .codecarto/scratch/amendments/, the one place an amendment
+ * is read from. The path names the file; the read always goes through the slug.
+ */
+function resolveAmendmentName(rawArg, cwd) {
+    const trimmed = rawArg.trim().replace(/^@/, "");
+    if (!trimmed)
+        return null;
+    if (!/[\\/]/.test(trimmed))
+        return trimmed;
+    const amendmentsDir = resolve(cwd, ".codecarto", "scratch", "amendments");
+    for (const candidate of [resolve(cwd, trimmed), resolve(cwd, ".codecarto", trimmed)]) {
+        if (dirname(candidate) === amendmentsDir)
+            return basename(candidate);
+    }
+    return null;
+}
+function clipDescription(text, max = 140) {
+    if (!text)
+        return "";
+    const oneLine = text.replace(/\s+/g, " ").trim();
+    return `: ${oneLine.length > max ? `${oneLine.slice(0, max - 1)}…` : oneLine}`;
+}
+/**
+ * What an amendment will do to canonical state, rendered for a human about to
+ * approve it: each closure resolved against status.yaml so an id that matches
+ * nothing is visible before the write, not only in the result.
+ */
+function describeAmendmentPreview(amendment, state) {
+    const openQuestions = new Map();
+    for (const [phaseId, phase] of Object.entries(state.status.phases)) {
+        for (const entry of phase.open_questions ?? []) {
+            if (!entry.id)
+                continue;
+            openQuestions.set(entry.id, [...(openQuestions.get(entry.id) ?? []), { phaseId, entry }]);
+        }
+    }
+    const unmatched = " — matches nothing (already closed or unknown; reported, not fatal)";
+    const lines = [`Amendment file: .codecarto/scratch/amendments/${amendment.slug}.yaml`];
+    if (amendment.open_question_closures.length > 0) {
+        lines.push("", `Closes ${amendment.open_question_closures.length} open question(s):`);
+        for (const id of amendment.open_question_closures) {
+            const matches = openQuestions.get(id);
+            if (!matches) {
+                lines.push(`  - ${id}${unmatched}`);
+                continue;
+            }
+            const { entry } = matches[0];
+            const where = [matches.map((match) => match.phaseId).join(", "), entry.kind].filter(Boolean).join(", ");
+            lines.push(`  - ${id} (${where})${clipDescription(entry.description)}`);
+        }
+    }
+    if (amendment.post_pipeline_closures.length > 0) {
+        lines.push("", `Retires ${amendment.post_pipeline_closures.length} post-pipeline item(s):`);
+        for (const id of amendment.post_pipeline_closures) {
+            const entry = state.status.post_pipeline.find((item) => item.id === id);
+            if (!entry) {
+                lines.push(`  - ${id}${unmatched}`);
+                continue;
+            }
+            const where = [entry.kind, entry.source_phase ? `from ${entry.source_phase}` : ""].filter(Boolean).join(", ");
+            lines.push(`  - ${id}${where ? ` (${where})` : ""}${clipDescription(entry.description)}`);
+        }
+    }
+    if (amendment.notes.length > 0) {
+        lines.push("", `Records ${amendment.notes.length} note(s) in the closeout:`, ...amendment.notes.map((note) => `  - ${note}`));
+    }
+    const summary = amendment.closeout_summary.trim();
+    lines.push("", `Writes .codecarto/closeouts/<date>-amendment-${amendment.slug}.md, appends one THREAD_LOG entry${summary ? ` ("${summary}")` : ""}, updates workflow/status.yaml under the completion lock, and refreshes the dashboard.`);
+    return lines.join("\n");
+}
+/**
+ * What a scaffold refresh will overwrite, rendered for a human about to approve
+ * it. The file set is the one refreshScaffold writes; the protected set is the
+ * one it skips — both come from core, so the preview cannot drift from the write.
+ */
+function describeScaffoldRefreshPreview(files, scaffoldVersionBefore) {
+    const topLevel = [];
+    const byDir = new Map();
+    for (const file of files) {
+        const slash = file.indexOf("/");
+        if (slash === -1) {
+            topLevel.push(file);
+            continue;
+        }
+        const dir = file.slice(0, slash);
+        byDir.set(dir, [...(byDir.get(dir) ?? []), file.slice(slash + 1)]);
+    }
+    const from = scaffoldVersionBefore ?? "unversioned";
+    const lines = [
+        from === PACKAGE_VERSION
+            ? `Scaffold version: ${from} (already current — the files are re-copied from the packaged template byte-for-byte).`
+            : `Scaffold version: ${from} → ${PACKAGE_VERSION}.`,
+        "",
+        `Overwrites ${files.length} framework-owned file(s) in .codecarto/ with the packaged template:`,
+    ];
+    if (topLevel.length > 0)
+        lines.push(`  ${topLevel.join(", ")}`);
+    for (const [dir, entries] of [...byDir.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+        // workflow/ is where the pipelines live, and the version marker: name them.
+        lines.push(dir === "workflow" ? `  workflow/: ${entries.join(", ")}` : `  ${dir}/: ${entries.length} file(s)`);
+    }
+    if (byDir.has("findings")) {
+        lines.push("  (findings/ refreshes only the packaged SKILL.md, README.md, and pass files — the findings outputs beside them stay.)");
+    }
+    const protectedPaths = [
+        ...SCAFFOLD_REFRESH_PROTECTED.workflowFiles.map((file) => `workflow/${file}`),
+        ...SCAFFOLD_REFRESH_PROTECTED.topLevel,
+        ...SCAFFOLD_REFRESH_PROTECTED.dirs.map((dir) => `${dir}/`),
+    ];
+    lines.push("", `Never touched: ${protectedPaths.join(", ")}.`, "One THREAD_LOG entry records the refresh. Continue?");
+    return lines.join("\n");
+}
 export default function codeCartographerExtension(pi) {
     phaseCompactionExtension(pi);
     let lastFeedbackLines = [];
     let codecartoModeActive = false;
+    // Argument completers receive only the prefix, so the session's cwd is
+    // remembered here for the completers that list files under .codecarto/.
+    let sessionCwd;
     const readWorkspaceState = async (ctx, notifyOnError = true) => {
+        sessionCwd = ctx.cwd;
         try {
             return await getWorkspaceState(ctx.cwd);
         }
@@ -185,6 +304,7 @@ export default function codeCartographerExtension(pi) {
     pi.on("session_start", async (_event, ctx) => {
         codecartoModeActive = false;
         lastFeedbackLines = [];
+        sessionCwd = ctx.cwd;
         setUiState(ctx, null);
     });
     pi.on("session_shutdown", async () => {
@@ -618,7 +738,7 @@ export default function codeCartographerExtension(pi) {
                 ctx.ui.notify(`Cannot complete ${validation.phaseId}: ${validation.overall}`, "error");
                 return;
             }
-            const { updatedState, closeoutNotice } = await autoCompletePhase(ctx, validation);
+            const { updatedState, closeoutNotice, warnings } = await autoCompletePhase(ctx, validation);
             lastFeedbackLines = [
                 `Completed phase: ${validation.phaseId}`,
                 `Validation: ${validation.overall}`,
@@ -626,10 +746,15 @@ export default function codeCartographerExtension(pi) {
             ];
             if (closeoutNotice)
                 lastFeedbackLines.push(closeoutNotice);
+            const notes = [...(validation.warnings ?? []), ...warnings];
+            for (const note of notes)
+                lastFeedbackLines.push(`NOTE: ${note} Non-gating.`);
             setUiState(ctx, updatedState, lastFeedbackLines);
-            ctx.ui.notify(`Marked ${validation.phaseId} complete`, validation.overall === "PASS WITH GAPS" ? "warning" : "info");
+            ctx.ui.notify(`Marked ${validation.phaseId} complete`, validation.overall === "PASS WITH GAPS" || notes.length > 0 ? "warning" : "info");
             if (closeoutNotice)
                 ctx.ui.notify(closeoutNotice, "info");
+            for (const note of notes)
+                ctx.ui.notify(note, "warning");
         },
     });
     pi.registerCommand("codecarto-skill", {
@@ -693,6 +818,76 @@ export default function codeCartographerExtension(pi) {
             ctx.ui.notify(`Queued CodeCartographer skill: ${skillName}`, "info");
         },
     });
+    pi.registerCommand("codecarto-list-skills", {
+        description: "List the post-pipeline skills installed in .codecarto/skills/ (and the ungated Broad-Side reading guide)",
+        handler: async (_args, ctx) => {
+            // Same gate as /codecarto-skill: the listing reads the workspace's
+            // skills directory, so it needs a workspace — mirrors handleListSkills.
+            const state = await ensureWorkspaceState(ctx);
+            if (!state)
+                return;
+            const skills = await listSkillNames(state.workspaceDir);
+            const lines = skills.length > 0
+                ? [`Available skills (${skills.length}):`, ...skills.map((name) => `  - ${name}`)]
+                : ["No skills installed."];
+            const nextPhase = getNextEligiblePhase(state);
+            if (skills.length > 0) {
+                lines.push(nextPhase
+                    ? `Post-pipeline skills unlock when the pipeline completes (next phase: ${nextPhase.id}).`
+                    : "Run one with /codecarto-skill <name>.");
+            }
+            // Broad-Side is listed apart from the post-pipeline set because it
+            // answers to /codecarto-skill without the completion gate.
+            const broadsideAvailable = await readBroadsideSkill(ctx.cwd).then(() => true, () => false);
+            if (broadsideAvailable) {
+                lines.push("", `Also served by /codecarto-skill (not pipeline-gated): ${BROADSIDE_SKILL_NAME} — how to read a Broad-Side batch reconnaissance run.`);
+            }
+            lastFeedbackLines = lines;
+            setUiState(ctx, state, lastFeedbackLines);
+            ctx.ui.notify(skills.length > 0
+                ? `${skills.length} post-pipeline skill${skills.length === 1 ? "" : "s"}: ${skills.join(", ")}`
+                : "No post-pipeline skills installed.", "info");
+        },
+    });
+    pi.registerCommand("codecarto-guide", {
+        description: "Read the packaged CodeCartographer agent guide into the session: /codecarto-guide [topic]",
+        getArgumentCompletions: async (prefix) => {
+            const topics = await listGuideTopics().catch(() => ["overview"]);
+            const items = topics
+                .filter((value) => value.startsWith(prefix))
+                .map((value) => ({ value, label: value }));
+            return items.length > 0 ? items : null;
+        },
+        handler: async (args, ctx) => {
+            // The guide is packaged with the extension, not copied into a
+            // workspace, so — like codecarto_guide — this needs no workspace.
+            let document;
+            let topics;
+            try {
+                topics = await listGuideTopics();
+                document = await readGuide(args.trim() || undefined);
+            }
+            catch (error) {
+                ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+                return;
+            }
+            const other = topics.filter((name) => name !== document.topic);
+            const footer = other.length > 0
+                ? `\n\n---\nOther guide topics: ${other.join(", ")} (run /codecarto-guide <topic>).`
+                : "";
+            const message = `${document.content}${footer}`;
+            if (ctx.isIdle()) {
+                pi.sendUserMessage(message);
+            }
+            else {
+                pi.sendUserMessage(message, { deliverAs: "followUp" });
+            }
+            lastFeedbackLines = [`Queued the CodeCartographer guide: ${document.topic}`];
+            if (codecartoModeActive)
+                void refreshWorkspaceUi(ctx, lastFeedbackLines);
+            ctx.ui.notify(`Queued the CodeCartographer guide (${document.topic})`, "info");
+        },
+    });
     pi.registerCommand("codecarto-broadside", {
         description: "Batch reconnaissance (Broad-Side): /codecarto-broadside [submit|collect|status|models] [lenses…] [flags]",
         getArgumentCompletions: (prefix) => {
@@ -786,7 +981,9 @@ export default function codeCartographerExtension(pi) {
                         lenses,
                         model: config.model,
                         maxCost: flags.maxCost ?? config.maxCost,
-                        incremental: flags.incremental || config.incremental,
+                        // `??`, not `||`: --no-incremental parses to false and must beat a
+                        // config-set true, exactly as MCP's `incremental: false` does (#163).
+                        incremental: flags.incremental ?? config.incremental,
                         // Pi can ask, so it asks instead of refusing over max_cost the
                         // way MCP has to. An approval here IS the force flag.
                         confirm: (estimate) => ctx.ui.confirm(`Broad-Side will spend about $${estimate.totalCost.toFixed(4)}`, describeBroadsideEstimate(estimate)),
@@ -879,35 +1076,78 @@ export default function codeCartographerExtension(pi) {
                 return;
             }
             const spec = await readFile(specPath, "utf8");
-            const slug = deriveSlug(ctx.cwd);
+            // The git remote when there is one, the directory otherwise (#147).
+            // Slug and source_repo derive from the same value so they agree.
+            const source = await resolvePublishSourceRepo(ctx.cwd);
+            const slug = deriveSlug(source.source_repo);
             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 label = `${namespace ? `${namespace}/` : ""}${slug}`;
             const preview = [
-                `Publish ${namespace ? `${namespace}/` : ""}${slug} to ${config.library.path}`,
-                `Source: ${ctx.cwd}`,
+                `Publish ${label} to ${config.library.path}`,
+                `Source: ${source.source_repo}${source.remote ? ` (git remote ${source.remote})` : ""}`,
                 `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;
+            const input = {
+                slug,
+                namespace,
+                source_repo: source.source_repo,
+                analyzed_at: new Date().toISOString(),
+                pipeline: state.status.pipeline,
+                codecarto_version: PACKAGE_VERSION,
+                headline,
+                tags: [],
+                capabilities: [],
+                generation: piGeneration(ctx),
+            };
             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),
-                });
+                // Both guards in publishEntry raise before anything is written, and
+                // each asks a question only the user can answer, so the command has
+                // no flags for them: a yes is the override. The options accumulate,
+                // so a publish that trips both guards asks both questions in turn.
+                const options = {};
+                let result;
+                while (!result) {
+                    try {
+                        result = await publishEntry(config.library.path, spec, input, options);
+                    }
+                    catch (error) {
+                        if (error instanceof SourceRepoMismatchError && !options.allowSourceRepoChange) {
+                            // The entry's history belongs to whatever the newest version
+                            // records. Appending is right only if that repository and this
+                            // one are the same project under a new address (#146) — which
+                            // includes the first publish after upgrading from a Pi that
+                            // recorded the directory to one that records the git remote.
+                            const moved = await ctx.ui.confirm("Source repository changed — did it move?", `Library entry ${label} records source_repo "${error.recorded}", but this publish carries "${error.incoming}". If the repository genuinely moved (rename, org transfer, host change — or this is the first publish since CodeCartographer began recording the git remote instead of the local directory), answer yes and this spec is appended as the entry's next version. If these are two different projects that share a directory name, answer no: nothing is written, and the second project needs a distinct slug (codecarto_publish on MCP accepts one). Did the repository move?`);
+                            if (!moved) {
+                                ctx.ui.notify("Publish cancelled. Nothing was written.", "info");
+                                return;
+                            }
+                            options.allowSourceRepoChange = true;
+                        }
+                        else if (error instanceof ConfidentialityMismatchError && !options.allowConfidentialityMismatch) {
+                            // Pi declares no confidentiality, so the entry sits at the internal
+                            // default; whether it may go into a wider library is the user's call.
+                            const publishAnyway = await ctx.ui.confirm("Confidentiality mismatch — publish anyway?", `This spec's confidentiality is "${error.entryConfidentiality}" (CodeCartographer's default; /codecarto-publish declares none), but the library "${marker.name}" has visibility "${error.libraryVisibility}". Publishing would expose it to everyone that library reaches. Publish anyway?`);
+                            if (!publishAnyway) {
+                                ctx.ui.notify("Publish cancelled. Nothing was written.", "info");
+                                return;
+                            }
+                            options.allowConfidentialityMismatch = true;
+                        }
+                        else {
+                            throw error;
+                        }
+                    }
+                }
                 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);
@@ -1045,4 +1285,123 @@ export default function codeCartographerExtension(pi) {
             ctx.ui.notify("Dashboard regenerated: .codecarto/dashboard.html", "info");
         },
     });
+    pi.registerCommand("codecarto-refresh-scaffold", {
+        description: "Refresh the framework-owned .codecarto/ files (GUIDE.md, templates/, workflow/ pipelines and VALIDATE.md) from the packaged template, after confirming; project state is untouched",
+        handler: async (_args, ctx) => {
+            const state = await ensureWorkspaceState(ctx);
+            if (!state)
+                return;
+            // Pi can ask, so it shows the exact file set before overwriting
+            // anything — MCP's codecarto_refresh_scaffold writes on call.
+            let files;
+            try {
+                files = await listScaffoldRefreshFiles();
+            }
+            catch (error) {
+                ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+                return;
+            }
+            const approved = await ctx.ui.confirm("Refresh the .codecarto/ scaffold from the packaged template?", describeScaffoldRefreshPreview(files, state.scaffoldVersion));
+            if (!approved) {
+                ctx.ui.notify("Scaffold refresh cancelled. Nothing was written.", "info");
+                return;
+            }
+            try {
+                const result = await refreshScaffold(ctx.cwd);
+                const transition = `${result.scaffoldVersionBefore ?? "unversioned"} → ${result.scaffoldVersionAfter}`;
+                lastFeedbackLines = [
+                    `Refreshed ${result.written.length} framework-owned file(s) from the packaged template (${transition}).`,
+                    "Project state, user config, findings outputs, scratch, closeouts, and orchestrator files were not touched.",
+                    "THREAD_LOG.md: one scaffold-refresh entry appended.",
+                ];
+                // Re-read state so the widget's staleness line clears with the marker.
+                await refreshWorkspaceUi(ctx, lastFeedbackLines);
+                ctx.ui.notify(`Refreshed ${result.written.length} framework-owned file(s) (${transition}).`, "info");
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                lastFeedbackLines = [message];
+                setUiState(ctx, state, lastFeedbackLines);
+                ctx.ui.notify(`Scaffold refresh failed: ${message}`, "error");
+            }
+        },
+    });
+    pi.registerCommand("codecarto-amend", {
+        description: "Apply a post-pipeline amendment from .codecarto/scratch/amendments/, after a preview: /codecarto-amend <name | scratch/amendments/name.yaml>",
+        getArgumentCompletions: async (prefix) => {
+            const names = await listAmendmentNames(join(sessionCwd ?? process.cwd(), ".codecarto"));
+            const items = names
+                .filter((value) => value.startsWith(prefix))
+                .map((value) => ({ value, label: value }));
+            return items.length > 0 ? items : null;
+        },
+        handler: async (args, ctx) => {
+            const state = await ensureWorkspaceState(ctx);
+            if (!state)
+                return;
+            if (!args.trim()) {
+                const staged = await listAmendmentNames(state.workspaceDir);
+                const hint = staged.length > 0
+                    ? ` (staged: ${staged.join(", ")})`
+                    : " — write .codecarto/scratch/amendments/<name>.yaml first (see templates/amendment.yaml)";
+                ctx.ui.notify(`Usage: /codecarto-amend <name>${hint}`, "warning");
+                return;
+            }
+            const name = resolveAmendmentName(args, ctx.cwd);
+            if (!name) {
+                ctx.ui.notify(`Amendments are read from .codecarto/scratch/amendments/ only; pass the amendment name or a path inside that directory, not ${args.trim()}.`, "error");
+                return;
+            }
+            // The same refusals codecarto_amend surfaces, raised before the
+            // confirmation so nobody approves an amendment that cannot apply.
+            let amendment;
+            try {
+                amendment = await loadAmendmentFile(name, state.workspaceDir);
+            }
+            catch (error) {
+                ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+                return;
+            }
+            const nextPhase = getNextEligiblePhase(state);
+            if (nextPhase) {
+                ctx.ui.notify(`Cannot amend: the pipeline is not complete (next phase: ${nextPhase.id}). `
+                    + "Resolve open questions and routed items through that phase's handoff (open_question_closures / carry_forward_closures) instead.", "error");
+                return;
+            }
+            // Pi can ask, so the amendment is previewed against status.yaml
+            // before anything is written — MCP's codecarto_amend applies on call.
+            const approved = await ctx.ui.confirm(`Apply amendment "${amendment.slug}"?`, describeAmendmentPreview(amendment, state));
+            if (!approved) {
+                ctx.ui.notify(`Amendment ${amendment.slug} cancelled. Nothing was written.`, "info");
+                return;
+            }
+            try {
+                const { applied, closeoutNotice } = await applyAmendment(ctx.cwd, name);
+                // An amendment exists precisely to change the numbers the dashboard
+                // shows; refresh it, reporting only a render that actually landed.
+                const dashboardWritten = await writeDashboard(ctx.cwd, PACKAGE_VERSION);
+                const lines = [
+                    `Amendment applied: ${amendment.slug}`,
+                    `Open questions closed: ${applied.openQuestionsClosed.length > 0 ? applied.openQuestionsClosed.join(", ") : "none"}`,
+                    `Post-pipeline items closed: ${applied.postPipelineClosed.length > 0 ? applied.postPipelineClosed.join(", ") : "none"}`,
+                ];
+                if (applied.unknownIds.length > 0)
+                    lines.push(`Ids that matched nothing (already closed or unknown): ${applied.unknownIds.join(", ")}`);
+                lines.push(closeoutNotice);
+                if (dashboardWritten)
+                    lines.push("Dashboard refreshed: .codecarto/dashboard.html");
+                lastFeedbackLines = lines;
+                await refreshWorkspaceUi(ctx, lastFeedbackLines);
+                const closed = applied.openQuestionsClosed.length + applied.postPipelineClosed.length;
+                ctx.ui.notify(`Amendment ${amendment.slug} applied: ${applied.openQuestionsClosed.length} open question(s) and ${applied.postPipelineClosed.length} post-pipeline item(s) closed`
+                    + `${applied.unknownIds.length > 0 ? `; ${applied.unknownIds.length} id(s) matched nothing` : ""}.`, closed === 0 || applied.unknownIds.length > 0 ? "warning" : "info");
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                lastFeedbackLines = [message];
+                setUiState(ctx, state, lastFeedbackLines);
+                ctx.ui.notify(`Amendment failed: ${message}`, "error");
+            }
+        },
+    });
 }

package/dist/extensions/codecarto/phase-compaction.js

@@ -81,6 +81,10 @@ export function phaseCompactionExtension(pi) {
             return undefined;
         try {
             const state = await getWorkspaceState(ctx.cwd);
+            // No workspace under this cwd: nothing phase-aware to add, so the host
+            // default applies — not a failure worth a warning (#134).
+            if (!state)
+                return undefined;
             const phase = state.pipeline.phases.find((candidate) => candidate.id === phaseId);
             const auth = await ctx.modelRegistry.getApiKeyAndHeaders(ctx.model);
             if (!auth.ok || !auth.apiKey)