codecartographer-pi 0.17.1 → 0.18.0

package/dist/core/status.js

@@ -126,26 +126,40 @@ export function createEmptyStatus(projectName, pipelinePath, pipeline) {
         post_pipeline: [],
     };
 }
+/**
+ * Spell a tool for both executable surfaces — the shape the scaffold
+ * staleness notice adopted (#177). next_actions is canonical state rendered
+ * by codecarto_status on MCP and as the Pi widget's "Next:" line alike, and a
+ * Pi user handed only the MCP tool name has nothing to run. Several tools
+ * join with "then" so a sequence reads as one per surface. No backticks:
+ * these lines render in a plain TUI line and in the HTML dashboard.
+ */
+function onBothSurfaces(...tools) {
+    const mcp = tools.map((tool) => `codecarto_${tool}`).join(" then ");
+    const pi = tools.map((tool) => `/codecarto-${tool.replace(/_/g, "-")}`).join(" then ");
+    return `${mcp} on MCP, ${pi} on Pi`;
+}
 /**
  * Route the terminal boundary to the post-pipeline surfaces (issue #114). The
  * moment every phase completes is exactly when skills, amendments, publishing,
  * and the dashboard apply; the prior static sentence left them undiscovered —
  * the 0.15.0 field test finished two full runs with every one of them unused.
- * Amendment recomputes this list so closure counts never go stale.
+ * Amendment recomputes this list so closure counts never go stale. Every tool
+ * named here is spelled for both surfaces (see onBothSurfaces).
  */
 export function buildTerminalNextActions(status) {
     const openQuestions = Object.values(status.phases).reduce((sum, phase) => sum + (phase.open_questions?.length ?? 0), 0);
     const postPipeline = status.post_pipeline.length;
     const actions = [
-        "All phases complete. Review findings; post-pipeline skills: codecarto_list_skills / codecarto_skill.",
+        `All phases complete. Review findings; post-pipeline skills: ${onBothSurfaces("list_skills", "skill")}.`,
     ];
     if (openQuestions > 0 || postPipeline > 0) {
-        actions.push(`${openQuestions} open question(s) and ${postPipeline} post-pipeline item(s) remain — apply resolutions with codecarto_amend (write scratch/amendments/<slug>.yaml from templates/amendment.yaml).`);
+        actions.push(`${openQuestions} open question(s) and ${postPipeline} post-pipeline item(s) remain — apply resolutions with ${onBothSurfaces("amend")} (write scratch/amendments/<slug>.yaml from templates/amendment.yaml).`);
     }
     if ("reimplementation-spec" in status.phases) {
-        actions.push("Publish the finished spec to a library: codecarto_publish (create one with codecarto_library_init; see the library guide topic).");
+        actions.push(`Publish the finished spec to a library: ${onBothSurfaces("publish")} (create one with ${onBothSurfaces("library_init")}; see the library guide topic).`);
     }
-    actions.push("Dashboard: .codecarto/dashboard.html (refreshed on completion and amendment; codecarto_dashboard re-renders on demand). Usage totals: codecarto_usage.");
+    actions.push(`Dashboard: .codecarto/dashboard.html (refreshed on completion and amendment; re-render on demand with ${onBothSurfaces("dashboard")}). Usage totals: ${onBothSurfaces("usage")}.`);
     return actions;
 }
 export function normalizeStatus(status, pipeline, pipelinePath, cwd) {

package/dist/core/workspace.d.ts

@@ -38,6 +38,16 @@ export declare function copyPackagedWorkspace(targetWorkspaceDir: string, source
  * @returns the file names created, for the caller's report.
  */
 export declare function seedOrchestratorFiles(workspaceDir: string): Promise<string[]>;
+/**
+ * What a scaffold refresh never touches, for a wrapper that asks before
+ * refreshing to show. The same sets drive {@link refreshScaffold}, so the
+ * preview and the write cannot disagree.
+ */
+export declare const SCAFFOLD_REFRESH_PROTECTED: Readonly<{
+    topLevel: readonly string[];
+    dirs: readonly string[];
+    workflowFiles: readonly string[];
+}>;
 /** One scaffold refresh's outcome. */
 export type RefreshScaffoldResult = {
     /** Workspace-relative paths written, sorted. */
@@ -47,6 +57,12 @@ export type RefreshScaffoldResult = {
     /** The running framework version the scaffold now matches. */
     scaffoldVersionAfter: string;
 };
+/**
+ * The workspace-relative paths a scaffold refresh would write, sorted — the
+ * exact set {@link refreshScaffold} copies, computed without writing anything.
+ * A wrapper that asks before refreshing shows this.
+ */
+export declare function listScaffoldRefreshFiles(): Promise<string[]>;
 /**
  * Refresh a workspace's framework-owned files from the packaged template
  * (issue #102): both staleness notices instruct exactly this, and the only

package/dist/core/workspace.js

@@ -199,6 +199,16 @@ const REFRESH_EXCLUDED_TOP_LEVEL = new Set(["BACKLOG.md", "THREAD_LOG.md", "CONV
 // generated results) — refresh must never overwrite it.
 const REFRESH_EXCLUDED_DIRS = new Set(["scratch", "inputs", "closeouts", "broadside"]);
 const REFRESH_EXCLUDED_WORKFLOW_FILES = new Set(["status.yaml", "config.yaml", ".usage.local.yaml"]);
+/**
+ * What a scaffold refresh never touches, for a wrapper that asks before
+ * refreshing to show. The same sets drive {@link refreshScaffold}, so the
+ * preview and the write cannot disagree.
+ */
+export const SCAFFOLD_REFRESH_PROTECTED = Object.freeze({
+    topLevel: Object.freeze([...REFRESH_EXCLUDED_TOP_LEVEL]),
+    dirs: Object.freeze([...REFRESH_EXCLUDED_DIRS]),
+    workflowFiles: Object.freeze([...REFRESH_EXCLUDED_WORKFLOW_FILES]),
+});
 async function listTemplateFiles(dir, relativeDir = "") {
     const entries = await readdir(dir, { withFileTypes: true });
     const files = [];
@@ -218,6 +228,17 @@ async function listTemplateFiles(dir, relativeDir = "") {
     }
     return files;
 }
+/**
+ * The workspace-relative paths a scaffold refresh would write, sorted — the
+ * exact set {@link refreshScaffold} copies, computed without writing anything.
+ * A wrapper that asks before refreshing shows this.
+ */
+export async function listScaffoldRefreshFiles() {
+    if (!existsSync(packagedWorkspaceDir)) {
+        throw new Error("Packaged .codecarto template is missing. Reinstall codecartographer-pi.");
+    }
+    return (await listTemplateFiles(packagedWorkspaceDir)).sort();
+}
 /**
  * Refresh a workspace's framework-owned files from the packaged template
  * (issue #102): both staleness notices instruct exactly this, and the only
@@ -238,7 +259,7 @@ export async function refreshScaffold(cwd) {
         throw new Error("Packaged .codecarto template is missing. Reinstall codecartographer-pi.");
     }
     const scaffoldVersionBefore = state.scaffoldVersion;
-    const files = (await listTemplateFiles(packagedWorkspaceDir)).sort();
+    const files = await listScaffoldRefreshFiles();
     for (const relativePath of files) {
         const target = join(state.workspaceDir, relativePath);
         await mkdir(dirname(target), { recursive: true });
@@ -261,6 +282,12 @@ export async function refreshScaffold(cwd) {
     };
 }
 // Numeric x.y.z comparison; null when either side is not a plain dotted triple.
+/**
+ * The remedy every staleness notice points at, spelled for both executable
+ * surfaces: this text renders inside Pi's widget and inside MCP's status
+ * result alike, and a Pi user handed only the MCP tool name has nothing to run.
+ */
+const SCAFFOLD_REFRESH_REMEDY = "`codecarto_refresh_scaffold` on MCP, `/codecarto-refresh-scaffold` on Pi";
 /**
  * Human-readable staleness notice for the workspace's .codecarto/ scaffold,
  * or null when the scaffold matches the running framework. A missing marker
@@ -272,7 +299,7 @@ export async function refreshScaffold(cwd) {
 export function describeScaffoldStaleness(state) {
     const scaffold = state.scaffoldVersion;
     if (!scaffold) {
-        return "This workspace's .codecarto/ scaffold has no workflow/scaffold-version.yaml marker (introduced after v0.12.11), so its framework-owned files (GUIDE.md, templates/, workflow/ pipelines and VALIDATE.md) may predate the v0.12.0 handoff contract. Refresh them from the packaged CodeCartographer template (codecarto_refresh_scaffold does exactly this without touching project state).";
+        return `This workspace's .codecarto/ scaffold has no workflow/scaffold-version.yaml marker (introduced after v0.12.11), so its framework-owned files (GUIDE.md, templates/, workflow/ pipelines and VALIDATE.md) may predate the v0.12.0 handoff contract. Refresh them from the packaged CodeCartographer template (${SCAFFOLD_REFRESH_REMEDY}) — that refresh does not touch project state.`;
     }
     const comparison = compareDottedVersions(scaffold, PACKAGE_VERSION);
     if (comparison === 0)
@@ -280,10 +307,10 @@ export function describeScaffoldStaleness(state) {
     if (comparison === null) {
         return scaffold === PACKAGE_VERSION
             ? null
-            : `This workspace's scaffold version (${scaffold}) does not match the running framework (${PACKAGE_VERSION}). Refresh the framework-owned files (GUIDE.md, templates/, workflow/) from the packaged template — codecarto_refresh_scaffold does exactly this without touching project state.`;
+            : `This workspace's scaffold version (${scaffold}) does not match the running framework (${PACKAGE_VERSION}). Refresh the framework-owned files (GUIDE.md, templates/, workflow/) from the packaged template (${SCAFFOLD_REFRESH_REMEDY}) — that refresh does not touch project state.`;
     }
     if (comparison < 0) {
-        return `This workspace's scaffold (v${scaffold}) is older than the running framework (v${PACKAGE_VERSION}). Refresh the framework-owned files (GUIDE.md, templates/, workflow/) from the packaged template to pick up pipeline and template fixes — codecarto_refresh_scaffold does exactly this without touching project state.`;
+        return `This workspace's scaffold (v${scaffold}) is older than the running framework (v${PACKAGE_VERSION}). Refresh the framework-owned files (GUIDE.md, templates/, workflow/) from the packaged template to pick up pipeline and template fixes (${SCAFFOLD_REFRESH_REMEDY}) — that refresh does not touch project state.`;
     }
     return `This workspace's scaffold (v${scaffold}) is newer than the running framework (v${PACKAGE_VERSION}). Upgrade CodeCartographer to at least v${scaffold}.`;
 }

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");
+            }
+        },
+    });
 }