codecartographer-pi 0.17.1 → 0.19.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, ConfidentialityMismatchError, 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 () => {
@@ -698,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) => {
@@ -886,16 +1076,20 @@ 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"}`,
@@ -905,7 +1099,7 @@ export default function codeCartographerExtension(pi) {
             const input = {
                 slug,
                 namespace,
-                source_repo: ctx.cwd,
+                source_repo: source.source_repo,
                 analyzed_at: new Date().toISOString(),
                 pipeline: state.status.pipeline,
                 codecarto_version: PACKAGE_VERSION,
@@ -915,22 +1109,44 @@ export default function codeCartographerExtension(pi) {
                 generation: piGeneration(ctx),
             };
             try {
+                // 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;
-                try {
-                    result = await publishEntry(config.library.path, spec, input);
-                }
-                catch (error) {
-                    if (!(error instanceof ConfidentialityMismatchError))
-                        throw error;
-                    // Nothing was written. 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, and a yes is the override.
-                    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;
+                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;
+                        }
                     }
-                    result = await publishEntry(config.library.path, spec, input, { allowConfidentialityMismatch: true });
                 }
                 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);
@@ -1069,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/mcp-server/server.js

@@ -17,7 +17,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError, } from "@modelcontextprotocol/sdk/types.js";
 import { mkdir, readFile, readdir, rename, writeFile } from "node:fs/promises";
 import { basename, isAbsolute, join } from "node:path";
-import { buildPhasePrompt, buildSkillPrompt, buildValidationSummary, BROADSIDE_DIR, broadsideDirFor, BROADSIDE_LENS_IDS, BROADSIDE_SKILL_NAME, canonicalPath, copyPackagedWorkspace, collectResultText, completeValidatedPhase, computePerPhaseTotals, computeTotals, createEmptyStatus, DEFAULT_PIPELINE_PATH, deriveSlug, discoverLibrary, describeScaffoldStaleness, detectProvenanceConflicts, estimateSubmitText, getLens, getNextEligiblePhase, getPipelineLabel, getWorkspaceState, isValidSlug, isWithinPathResolved, listBatchModels, listEntries, listGuideTopics, loadBroadsideConfig, modelsText, readGuide, listSkillNames, loadCodecartoConfig, loadUsage, loadYamlFile, normalizeForComparison, PACKAGE_VERSION, packagedWorkspaceDir, pathExists, PhasePreflightError, publishEntry, reindex as libraryReindex, refreshScaffold, resolvePhase, resolvePipelineChoice, readBroadsideSkill, runBroadsideCollect, runBroadsideStatus, runBroadsideSubmit, seedOrchestratorFiles, statusText, stringifySimpleYaml, switchPipeline, validatePhaseOutput, writeLibraryConfig, } from "../core/index.js";
+import { buildPhasePrompt, buildSkillPrompt, buildValidationSummary, BROADSIDE_DIR, broadsideDirFor, BROADSIDE_LENS_IDS, BROADSIDE_SKILL_NAME, canonicalPath, copyPackagedWorkspace, collectResultText, completeValidatedPhase, computePerPhaseTotals, computeTotals, createEmptyStatus, DEFAULT_PIPELINE_PATH, deriveSlug, discoverLibrary, describeScaffoldStaleness, detectProvenanceConflicts, estimateSubmitText, getLens, getNextEligiblePhase, getPipelineLabel, getWorkspaceState, isValidSlug, isWithinPathResolved, listBatchModels, listEntries, listGuideTopics, loadBroadsideConfig, modelsText, readGuide, listSkillNames, loadCodecartoConfig, loadUsage, loadYamlFile, normalizeForComparison, PACKAGE_VERSION, packagedWorkspaceDir, pathExists, PhasePreflightError, previewPublishVersion, publishEntry, reindex as libraryReindex, refreshScaffold, resolvePhase, resolvePipelineChoice, readBroadsideSkill, runBroadsideCollect, runBroadsideStatus, runBroadsideSubmit, seedOrchestratorFiles, statusText, stringifySimpleYaml, switchPipeline, validatePhaseOutput, writeLibraryConfig, } from "../core/index.js";
 import { applyAmendment } from "../core/amendment.js";
 import { appendUsageRun } from "../core/usage.js";
 import { initLibrary } from "../core/library.js";
@@ -370,6 +370,17 @@ async function resolveLibraryPath(args) {
     }
     throw new McpError(ErrorCode.InvalidParams, "library_path is required (pass it explicitly, or pass cwd and configure library.path in ~/.codecarto/config.yaml or .codecarto/workflow/config.yaml).");
 }
+/**
+ * The configuration `codecarto_config` reports for the same `cwd`: workspace
+ * over user-global when a cwd is given, user-global alone otherwise. Publish
+ * reads its gate from here so the value the config tool displays is the value
+ * the publish tool enforces.
+ */
+async function loadEffectiveConfig(cwd) {
+    return typeof cwd === "string" && cwd.trim() !== ""
+        ? loadCodecartoConfig(join(cwd.trim(), ".codecarto"))
+        : loadUserConfig();
+}
 function asStringArray(value, fieldName) {
     if (!Array.isArray(value)) {
         throw new McpError(ErrorCode.InvalidParams, `${fieldName} must be an array of strings`);
@@ -550,6 +561,50 @@ export async function handlePublish(args) {
     const analyzedAt = typeof args.analyzed_at === "string" && args.analyzed_at !== ""
         ? args.analyzed_at
         : new Date().toISOString();
+    const headline = args.headline.trim();
+    const forceNewVersion = args.force_new_version === true;
+    // publish_confirm gate (#162). Pi shows a preview and asks before writing.
+    // An MCP server has no one to ask, so — as codecarto_broadside does for its
+    // spend limit — it refuses with the preview and lets the caller re-invoke
+    // with confirm: true. The gate applies only when a config layer actually
+    // set the key: the loader's default (true) exists to make Pi's dialog
+    // opt-out, and a host that never configured the key keeps the behavior it
+    // had. Runs after every argument check so the preview names the resolved
+    // slug and namespace, and before publishEntry so nothing is written.
+    const config = await loadEffectiveConfig(args.cwd);
+    if (config.library.publish_confirm && config.library.publish_confirm_configured && args.confirm !== true) {
+        const preview = await previewPublishVersion(libraryPath, spec, { slug, namespace }, { forceNewVersion });
+        const label = `${namespace ? `${namespace}/` : ""}${slug}`;
+        const versionLine = preview.latestVersion === 0
+            ? "v1 (first version of a new entry)"
+            : preview.isNewVersion
+                ? `v${preview.version} (new content version; the newest is v${preview.latestVersion})`
+                : `v${preview.version} (metadata-only update; the content hash matches the newest version)`;
+        const specSource = typeof args.spec_path === "string" && args.spec_path.trim() !== ""
+            ? args.spec_path.trim()
+            : `inline (${spec.length} characters)`;
+        throw new McpError(ErrorCode.InvalidRequest, [
+            "Publish not performed: library.publish_confirm is set and this call did not carry confirm: true. Nothing was written.",
+            `Would publish ${label} to ${libraryPath}`,
+            `  Version: ${versionLine}`,
+            `  Source repo: ${sourceRepo}`,
+            `  Headline: ${headline}`,
+            `  Confidentiality: ${confidentiality ?? "internal (the default; none declared)"}`,
+            `  Spec: ${specSource}`,
+            "Re-invoke codecarto_publish with the same arguments plus confirm: true to publish, or set library.publish_confirm: false in config to drop this gate.",
+        ].join("\n"), {
+            refused: "publish_confirm",
+            libraryPath,
+            namespace: namespace ?? null,
+            slug,
+            version: preview.version,
+            isNewVersion: preview.isNewVersion,
+            latestVersion: preview.latestVersion,
+            source_repo: sourceRepo,
+            headline,
+            confidentiality: confidentiality ?? null,
+        });
+    }
     const result = await publishEntry(libraryPath, spec, {
         slug,
         namespace: namespace ?? undefined,
@@ -560,13 +615,13 @@ export async function handlePublish(args) {
         analyzed_at: analyzedAt,
         pipeline: defaults.pipeline,
         codecarto_version: PACKAGE_VERSION,
-        headline: args.headline.trim(),
+        headline,
         tags,
         capabilities,
         confidentiality,
         generation,
     }, {
-        forceNewVersion: args.force_new_version === true,
+        forceNewVersion,
         allowSourceRepoChange: args.allow_source_repo_change === true,
         allowConfidentialityMismatch: args.allow_confidentiality_mismatch === true,
     });
@@ -1060,7 +1115,7 @@ const TOOLS = [
     },
     {
         name: "codecarto_publish",
-        description: "Publish a reimplementation-spec to a CodeCartographer library. Identified by library_path (absolute) or cwd's config.yaml. Content-hash idempotent — re-publishing identical spec bytes updates metadata in place rather than bumping the version. Required: source_repo, headline, and either spec (inline) or spec_path (absolute file). Slug derives from source_repo if not provided. If the library is namespaced, namespace is required (or pass cwd to inherit from config). Generation context (agent, model, vendor, reasoning) is passed via model_metadata so the host can record provenance; omitted fields default to 'unknown'.",
+        description: "Publish a reimplementation-spec to a CodeCartographer library. Identified by library_path (absolute) or cwd's config.yaml. Content-hash idempotent — re-publishing identical spec bytes updates metadata in place rather than bumping the version. Required: source_repo, headline, and either spec (inline) or spec_path (absolute file). Slug derives from source_repo if not provided. If the library is namespaced, namespace is required (or pass cwd to inherit from config). Generation context (agent, model, vendor, reasoning) is passed via model_metadata so the host can record provenance; omitted fields default to 'unknown'. When library.publish_confirm is set in config, a call without confirm: true is refused with a preview of what would be published (nothing is written); re-invoke with confirm: true to publish.",
         inputSchema: {
             type: "object",
             properties: {
@@ -1104,6 +1159,10 @@ const TOOLS = [
                     type: "boolean",
                     description: "Permit publishing when the entry's confidentiality is more restricted than the library's visibility (internal < shared < public: an internal entry into a shared or public library, a shared entry into a public one). Off by default, because that direction exposes the spec to everyone the library reaches. An omitted confidentiality counts as internal. Set only when the exposure is intended; the recorded confidentiality is not changed.",
                 },
+                confirm: {
+                    type: "boolean",
+                    description: "Acknowledge the publish_confirm gate. When library.publish_confirm is set in config (user-global ~/.codecarto/config.yaml, or the workspace's .codecarto/workflow/config.yaml when cwd is passed), a call without confirm: true is refused and the refusal previews what would be published — library, entry, whether a new version or a metadata-only update, source_repo, headline, confidentiality — so the caller can show it before committing to the write. Pass true to publish. No effect when publish_confirm is unset or false.",
+                },
             },
             required: ["source_repo", "headline"],
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codecartographer-pi",
-  "version": "0.17.1",
+  "version": "0.19.0",
   "mcpName": "io.github.HuginnIndustries/codecartographer",
   "description": "Turn an unfamiliar codebase into a validated reimplementation spec, then synthesize confirmed specs and a product vision into a traceable plan.",
   "type": "module",