codecartographer-pi 0.14.1 → 0.16.0

package/dist/core/types.d.ts

@@ -85,6 +85,28 @@ export type ValidationResult = {
     }>;
     gaps: string[];
     errors: string[];
+    /**
+     * The phase's declared secondary outputs with existence at validation time.
+     * Non-gating visibility: secondary outputs are created only when needed,
+     * but one that ends the phase absent and unaccounted-for is a silent drop.
+     */
+    secondaryOutputs?: Array<{
+        path: string;
+        exists: boolean;
+    }>;
+};
+/**
+ * One convention a phase proposes for promotion. Completion stages these in
+ * CONVENTIONS.md under "## Pending proposals"; promoting a proposal into the
+ * canonical sections stays an orchestrator judgment at the phase boundary.
+ */
+export type ProposedConventionEntry = {
+    /** Short name for the pattern (becomes the staged bullet's label). */
+    name: string;
+    /** The rule itself, one or two sentences. */
+    rule: string;
+    /** Optional: where the pattern showed up (file, phase, incident). */
+    evidence?: string;
 };
 export type PhaseHandoff = {
     phase_id: string;
@@ -101,6 +123,8 @@ export type PhaseHandoff = {
     open_question_closures: string[];
     post_pipeline: PostPipelineEntry[];
     decisions: string[];
+    /** Conventions proposed for promotion; completion stages them in CONVENTIONS.md. Omitted defaults to empty. */
+    proposed_conventions: ProposedConventionEntry[];
     closeout_content: string;
     closeout_summary: string;
     schema_version?: number;

package/dist/core/usage.d.ts

@@ -23,6 +23,13 @@ export interface UsageRun {
     tokens: UsageTokens;
     session_file?: string;
     compactions?: CompactionTelemetry;
+    /**
+     * Which surface recorded the run. `pi-runner` entries carry real token and
+     * activity telemetry; `mcp-complete` entries are completion receipts with
+     * zeroed counters, because MCP hosts execute phases in their own context
+     * and report no usage (issue #100). Absent on entries from older versions.
+     */
+    recorded_by?: "pi-runner" | "mcp-complete";
 }
 export interface UsageFile {
     version: number;

package/dist/core/usage.js

@@ -105,7 +105,8 @@ function isUsageRun(x) {
         isFiniteNumber(run.duration_ms) &&
         isUsageTokens(run.tokens) &&
         (run.session_file === undefined || typeof run.session_file === "string") &&
-        (run.compactions === undefined || isCompactionTelemetry(run.compactions)));
+        (run.compactions === undefined || isCompactionTelemetry(run.compactions)) &&
+        (run.recorded_by === undefined || run.recorded_by === "pi-runner" || run.recorded_by === "mcp-complete"));
 }
 function isUsageTokens(x) {
     if (!x || typeof x !== "object")

package/dist/core/workspace.d.ts

@@ -4,6 +4,45 @@ export declare const packageRoot: string;
 export declare const packagedWorkspaceDir: string;
 export declare const PACKAGE_VERSION: string;
 export declare function getWorkspaceState(cwd: string): Promise<WorkspaceState | null>;
+/** The orchestrator-maintained files init seeds and completion appends to. */
+export declare const ORCHESTRATOR_FILES: readonly [{
+    readonly file: "CONVENTIONS.md";
+    readonly template: "conventions-template.md";
+}, {
+    readonly file: "DECISIONS.md";
+    readonly template: "decisions-template.md";
+}];
+/**
+ * Seed the orchestrator-maintained files from the workspace's templates
+ * (issue #98): orchestration is on by default, so a fresh workspace starts
+ * with both skeletons instead of gating them behind a role ritual. Idempotent
+ * — existing files are never touched, and a scaffold without the templates
+ * (pre-template era) is left for completion's minimal-header fallback.
+ * @returns the file names created, for the caller's report.
+ */
+export declare function seedOrchestratorFiles(workspaceDir: string): Promise<string[]>;
+/** One scaffold refresh's outcome. */
+export type RefreshScaffoldResult = {
+    /** Workspace-relative paths written, sorted. */
+    written: string[];
+    /** The workspace's scaffold version before the refresh, if any. */
+    scaffoldVersionBefore?: string;
+    /** The running framework version the scaffold now matches. */
+    scaffoldVersionAfter: string;
+};
+/**
+ * Refresh a workspace's framework-owned files from the packaged template
+ * (issue #102): both staleness notices instruct exactly this, and the only
+ * tool that previously touched scaffold files was init's force mode, which
+ * backs up the entire workspace. Copies every file the packaged template
+ * ships except project state (`workflow/status.yaml`), user configuration
+ * (`workflow/config.yaml`, usage log), user-owned top-level files
+ * (BACKLOG, THREAD_LOG, CONVENTIONS, DECISIONS), and session-written
+ * directories (`scratch/`, `inputs/`, `closeouts/`). Files the template no
+ * longer ships are left in place. Appends one THREAD_LOG entry naming the
+ * version transition.
+ */
+export declare function refreshScaffold(cwd: string): Promise<RefreshScaffoldResult>;
 /**
  * Human-readable staleness notice for the workspace's .codecarto/ scaffold,
  * or null when the scaffold matches the running framework. A missing marker

package/dist/core/workspace.js

@@ -3,7 +3,7 @@
 // + normalizes the per-project workspace state from disk, and provides the
 // atomic status-update primitive used by /codecarto-complete.
 import { existsSync, readFileSync } from "node:fs";
-import { appendFile, readFile, rename, writeFile } from "node:fs/promises";
+import { appendFile, copyFile, mkdir, readFile, readdir, rename, writeFile } from "node:fs/promises";
 import { basename, dirname, join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
 import { acquireLock, applyHandoff, createEmptyStatus, normalizeStatus, parseHandoff } from "./status.js";
@@ -98,6 +98,94 @@ export async function getWorkspaceState(cwd) {
         ...(scaffoldVersion !== undefined && { scaffoldVersion }),
     };
 }
+/** The orchestrator-maintained files init seeds and completion appends to. */
+export const ORCHESTRATOR_FILES = [
+    { file: "CONVENTIONS.md", template: "conventions-template.md" },
+    { file: "DECISIONS.md", template: "decisions-template.md" },
+];
+/**
+ * Seed the orchestrator-maintained files from the workspace's templates
+ * (issue #98): orchestration is on by default, so a fresh workspace starts
+ * with both skeletons instead of gating them behind a role ritual. Idempotent
+ * — existing files are never touched, and a scaffold without the templates
+ * (pre-template era) is left for completion's minimal-header fallback.
+ * @returns the file names created, for the caller's report.
+ */
+export async function seedOrchestratorFiles(workspaceDir) {
+    const created = [];
+    for (const { file, template } of ORCHESTRATOR_FILES) {
+        const target = join(workspaceDir, file);
+        if (await pathExists(target))
+            continue;
+        const templatePath = join(workspaceDir, "templates", template);
+        if (!(await pathExists(templatePath)))
+            continue;
+        await copyFile(templatePath, target);
+        created.push(file);
+    }
+    return created;
+}
+/**
+ * Workspace paths refresh never touches: project state, user configuration,
+ * user-owned top-level files, and the directories sessions write into.
+ * Everything else present in the packaged template is framework-owned.
+ */
+const REFRESH_EXCLUDED_TOP_LEVEL = new Set(["BACKLOG.md", "THREAD_LOG.md", "CONVENTIONS.md", "DECISIONS.md"]);
+const REFRESH_EXCLUDED_DIRS = new Set(["scratch", "inputs", "closeouts"]);
+const REFRESH_EXCLUDED_WORKFLOW_FILES = new Set(["status.yaml", "config.yaml", ".usage.local.yaml"]);
+async function listTemplateFiles(dir, relativeDir = "") {
+    const entries = await readdir(dir, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        const relativePath = relativeDir ? `${relativeDir}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) {
+            if (!relativeDir && REFRESH_EXCLUDED_DIRS.has(entry.name))
+                continue;
+            files.push(...await listTemplateFiles(join(dir, entry.name), relativePath));
+            continue;
+        }
+        if (!relativeDir && REFRESH_EXCLUDED_TOP_LEVEL.has(entry.name))
+            continue;
+        if (relativeDir === "workflow" && REFRESH_EXCLUDED_WORKFLOW_FILES.has(entry.name))
+            continue;
+        files.push(relativePath);
+    }
+    return files;
+}
+/**
+ * Refresh a workspace's framework-owned files from the packaged template
+ * (issue #102): both staleness notices instruct exactly this, and the only
+ * tool that previously touched scaffold files was init's force mode, which
+ * backs up the entire workspace. Copies every file the packaged template
+ * ships except project state (`workflow/status.yaml`), user configuration
+ * (`workflow/config.yaml`, usage log), user-owned top-level files
+ * (BACKLOG, THREAD_LOG, CONVENTIONS, DECISIONS), and session-written
+ * directories (`scratch/`, `inputs/`, `closeouts/`). Files the template no
+ * longer ships are left in place. Appends one THREAD_LOG entry naming the
+ * version transition.
+ */
+export async function refreshScaffold(cwd) {
+    const state = await getWorkspaceState(cwd);
+    if (!state)
+        throw new Error("CodeCartographer workspace not found. Run /codecarto-init first.");
+    if (!existsSync(packagedWorkspaceDir)) {
+        throw new Error("Packaged .codecarto template is missing. Reinstall codecartographer-pi.");
+    }
+    const scaffoldVersionBefore = state.scaffoldVersion;
+    const files = (await listTemplateFiles(packagedWorkspaceDir)).sort();
+    for (const relativePath of files) {
+        const target = join(state.workspaceDir, relativePath);
+        await mkdir(dirname(target), { recursive: true });
+        await copyFile(join(packagedWorkspaceDir, relativePath), target);
+    }
+    const entry = `- ${new Date().toISOString().slice(0, 10)} — scaffold-refresh — Refreshed ${files.length} framework-owned file(s) from the packaged template (${scaffoldVersionBefore ?? "unversioned"} → ${PACKAGE_VERSION}); project state, user config, and session outputs untouched.`;
+    await appendFile(join(state.workspaceDir, "THREAD_LOG.md"), `${entry}\n`, "utf8");
+    return {
+        written: files,
+        ...(scaffoldVersionBefore !== undefined && { scaffoldVersionBefore }),
+        scaffoldVersionAfter: PACKAGE_VERSION,
+    };
+}
 // Numeric x.y.z comparison; null when either side is not a plain dotted triple.
 function compareDottedVersions(a, b) {
     const parse = (version) => {
@@ -125,7 +213,7 @@ function compareDottedVersions(a, b) {
 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.";
+        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).";
     }
     const comparison = compareDottedVersions(scaffold, PACKAGE_VERSION);
     if (comparison === 0)
@@ -133,10 +221,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.`;
+            : `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.`;
     }
     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.`;
+        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 newer than the running framework (v${PACKAGE_VERSION}). Upgrade CodeCartographer to at least v${scaffold}.`;
 }

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

@@ -357,6 +357,7 @@ async function recordUsage(workspaceDir, phaseId, status, activity, sessionFile)
                 output: activity.lifetimeUsage.output,
                 cache_write: activity.lifetimeUsage.cacheWrite,
             },
+            recorded_by: "pi-runner",
             compactions: activity.compactions,
             ...(sessionFile ? { session_file: sessionFile } : {}),
         });

package/dist/extensions/codecarto/dashboard-writer.d.ts

@@ -1 +1,8 @@
-export declare function writeDashboard(cwd: string, packageVersion: string): Promise<void>;
+/**
+ * Render and atomically replace `.codecarto/dashboard.html`.
+ * @returns true when a fresh dashboard landed on disk; false when the
+ * workspace is missing or any gather/render/write step failed (swallowed —
+ * lifecycle callers must never fail on a dashboard problem, but they may
+ * report truthfully whether a refresh happened).
+ */
+export declare function writeDashboard(cwd: string, packageVersion: string): Promise<boolean>;

package/dist/extensions/codecarto/dashboard-writer.js

@@ -6,11 +6,18 @@ import { readdir, readFile, rename, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { DASHBOARD_RELATIVE_PATH, getWorkspaceState, loadUsage, NARRATION_CACHE_RELATIVE_PATH, parseSimpleYaml, pathExists, renderDashboard, } from "../../core/index.js";
 const CLOSEOUT_FILENAME_RE = /^(\d{4}-\d{2}-\d{2})-(.+)\.md$/;
+/**
+ * Render and atomically replace `.codecarto/dashboard.html`.
+ * @returns true when a fresh dashboard landed on disk; false when the
+ * workspace is missing or any gather/render/write step failed (swallowed —
+ * lifecycle callers must never fail on a dashboard problem, but they may
+ * report truthfully whether a refresh happened).
+ */
 export async function writeDashboard(cwd, packageVersion) {
     try {
         const state = await getWorkspaceState(cwd);
         if (!state)
-            return;
+            return false;
         const workspaceDir = state.workspaceDir;
         const [usage, closeouts, outputsPresent, narration] = await Promise.all([
             loadUsage(workspaceDir),
@@ -33,11 +40,13 @@ export async function writeDashboard(cwd, packageVersion) {
         const tempPath = `${path}.${process.pid}.${Date.now()}.tmp`;
         await writeFile(tempPath, html, "utf8");
         await rename(tempPath, path);
+        return true;
     }
     catch {
         // Best-effort: a failed dashboard write must not surface as a phase
         // error. The user's pipeline state is unaffected; the next state
         // change will trigger another render attempt.
+        return false;
     }
 }
 async function listCloseouts(workspaceDir) {

package/dist/extensions/codecarto/index.js

@@ -8,7 +8,7 @@ import { narrateDashboard } from "./dashboard-narrator.js";
 import { writeDashboard } from "./dashboard-writer.js";
 import { parseNextFlags } from "./next-flags.js";
 import { phaseCompactionExtension } from "./phase-compaction.js";
-import { buildPhasePrompt, buildSkillPrompt, buildValidationSummary, canonicalPath, computePerPhaseTotals, computeTotals, createEmptyStatus, DEFAULT_PIPELINE_PATH, describeScaffoldStaleness, deriveSlug, discoverLibrary, getNextEligiblePhase, getPipelineLabel, getWorkspaceState, isWithinPathResolved, listSkillNames, loadCodecartoConfig, loadUsage, loadYamlFile, normalizeForComparison, packagedWorkspaceDir, pathExists, PACKAGE_VERSION, PhasePreflightError, PIPELINE_ALIASES, publishEntry, resolvePhase, resolvePipelineChoice, runPhasePreflight, stringifySimpleYaml, switchPipeline, validatePhaseOutput, writeLibraryConfig, } from "../../core/index.js";
+import { buildPhasePrompt, buildSkillPrompt, buildValidationSummary, canonicalPath, computePerPhaseTotals, computeTotals, createEmptyStatus, DEFAULT_PIPELINE_PATH, describeScaffoldStaleness, deriveSlug, discoverLibrary, getNextEligiblePhase, getPipelineLabel, getWorkspaceState, isWithinPathResolved, listSkillNames, loadCodecartoConfig, loadUsage, loadYamlFile, normalizeForComparison, packagedWorkspaceDir, pathExists, PACKAGE_VERSION, PhasePreflightError, PIPELINE_ALIASES, publishEntry, resolvePhase, resolvePipelineChoice, runPhasePreflight, 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";
@@ -282,6 +282,9 @@ export default function codeCartographerExtension(pi) {
             const normalizedStatus = createEmptyStatus(basename(ctx.cwd), selectedPipelinePath, pipeline);
             normalizedStatus.last_updated = new Date().toISOString();
             await writeFile(rawStatusPath, `${stringifySimpleYaml(normalizedStatus)}\n`, "utf8");
+            // Orchestration is on by default (issue #97/#98): seed the files its
+            // duties maintain so they exist from the first phase.
+            await seedOrchestratorFiles(targetWorkspaceDir);
             codecartoModeActive = true;
             lastFeedbackLines = [`Initialized workspace with pipeline: ${getPipelineLabel(selectedPipelinePath)}`];
             ctx.ui.notify(`Initialized CodeCartographer (${getPipelineLabel(selectedPipelinePath)})`, "info");

package/dist/mcp-server/server.d.ts

@@ -207,6 +207,29 @@ export declare function handleListSkills(args: {
         text: string;
     };
 }>;
+export declare function handleRefreshScaffold(args: {
+    cwd: string;
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent: {
+        text: string;
+    };
+}>;
+export declare function handleAmend(args: {
+    cwd: string;
+    name: string;
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent: {
+        text: string;
+    };
+}>;
 export declare function handleGuide(args: {
     topic?: string;
 }): Promise<{

package/dist/mcp-server/server.js

@@ -15,7 +15,9 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError, } from "@modelcontextprotocol/sdk/types.js";
 import { cp, mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { basename, isAbsolute, join } from "node:path";
-import { buildPhasePrompt, buildSkillPrompt, buildValidationSummary, canonicalPath, completeValidatedPhase, computePerPhaseTotals, computeTotals, createEmptyStatus, DEFAULT_PIPELINE_PATH, deriveSlug, discoverLibrary, describeScaffoldStaleness, getNextEligiblePhase, getPipelineLabel, getWorkspaceState, isValidSlug, isWithinPathResolved, listEntries, listGuideTopics, readGuide, listSkillNames, loadCodecartoConfig, loadUsage, loadYamlFile, normalizeForComparison, PACKAGE_VERSION, packagedWorkspaceDir, pathExists, PhasePreflightError, publishEntry, reindex as libraryReindex, resolvePhase, resolvePipelineChoice, stringifySimpleYaml, switchPipeline, validatePhaseOutput, writeLibraryConfig, } from "../core/index.js";
+import { buildPhasePrompt, buildSkillPrompt, buildValidationSummary, canonicalPath, completeValidatedPhase, computePerPhaseTotals, computeTotals, createEmptyStatus, DEFAULT_PIPELINE_PATH, deriveSlug, discoverLibrary, describeScaffoldStaleness, getNextEligiblePhase, getPipelineLabel, getWorkspaceState, isValidSlug, isWithinPathResolved, listEntries, listGuideTopics, readGuide, listSkillNames, loadCodecartoConfig, loadUsage, loadYamlFile, normalizeForComparison, PACKAGE_VERSION, packagedWorkspaceDir, pathExists, PhasePreflightError, publishEntry, reindex as libraryReindex, refreshScaffold, resolvePhase, resolvePipelineChoice, seedOrchestratorFiles, 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";
 import { loadUserConfig, resolveUserConfigPath } from "../core/orchestrator-config.js";
 import { writeDashboard } from "../extensions/codecarto/dashboard-writer.js";
@@ -104,12 +106,23 @@ export async function handleInit(args) {
     const normalizedStatus = createEmptyStatus(basename(cwd), selectedPipelinePath, pipeline);
     normalizedStatus.last_updated = new Date().toISOString();
     await writeFile(statusPath, `${stringifySimpleYaml(normalizedStatus)}\n`, "utf8");
+    // Orchestration is on by default (issue #97/#98): the driving chat holds the
+    // duties, so the files those duties maintain exist from the first phase.
+    const seeded = await seedOrchestratorFiles(targetWorkspaceDir);
     const label = getPipelineLabel(selectedPipelinePath);
-    return textResult(`Initialized CodeCartographer workspace at ${targetWorkspaceDir}.\nPipeline: ${label} (${selectedPipelinePath})\nFirst phase: ${normalizedStatus.current_phase}`, {
+    const initLines = [
+        `Initialized CodeCartographer workspace at ${targetWorkspaceDir}.`,
+        `Pipeline: ${label} (${selectedPipelinePath})`,
+        `First phase: ${normalizedStatus.current_phase}`,
+    ];
+    if (seeded.length > 0)
+        initLines.push(`Seeded orchestrator files: ${seeded.join(", ")} (the driving chat holds the orchestrator duties — see GUIDE.md §Roles).`);
+    return textResult(initLines.join("\n"), {
         workspaceDir: targetWorkspaceDir,
         pipeline: selectedPipelinePath,
         pipelineLabel: label,
         firstPhase: normalizedStatus.current_phase,
+        seededOrchestratorFiles: seeded,
     });
 }
 export async function handleStatus(args) {
@@ -131,7 +144,12 @@ export async function handleStatus(args) {
         `Open questions (terminal unresolved): ${terminalOpenQuestions}`,
         `Carry-forward (pipeline phases): ${totalCarryForward}`,
         `Post-pipeline work: ${postPipelinePending} pending`,
-        `Next: ${state.status.next_actions[0] ?? (nextPhase ? `Begin ${nextPhase.id}` : "All phases complete.")}`,
+        // Render every stored action: the terminal list routes to several
+        // post-pipeline surfaces (issue #114), and a text-reading client that
+        // only ever sees actions[0] loses exactly the routing it exists for.
+        ...(state.status.next_actions.length > 0
+            ? state.status.next_actions.map((action, index) => `${index === 0 ? "Next: " : "      "}${action}`)
+            : [`Next: ${nextPhase ? `Begin ${nextPhase.id}` : "All phases complete."}`]),
     ];
     if (scaffoldNotice)
         summaryLines.push(`Scaffold: ${scaffoldNotice}`);
@@ -216,6 +234,7 @@ export async function handleValidate(args) {
         rows: validation.rows,
         gaps: validation.gaps,
         errors: validation.errors,
+        secondaryOutputs: validation.secondaryOutputs ?? [],
     });
 }
 export async function handleComplete(args) {
@@ -227,20 +246,54 @@ export async function handleComplete(args) {
     if (validation.overall === "FAIL" || validation.overall === "MISSING") {
         throw new McpError(ErrorCode.InvalidRequest, `Cannot complete ${validation.phaseId}: validation is ${validation.overall}.\n${buildValidationSummary(validation).join("\n")}`);
     }
-    const { updatedState, closeoutNotice } = await completeValidatedPhase(cwd, validation, "codecarto_complete").catch((error) => {
+    const { updatedState, closeoutNotice, orchestratorCheckpoint } = await completeValidatedPhase(cwd, validation, "codecarto_complete").catch((error) => {
         throw new McpError(ErrorCode.InvalidParams, error instanceof Error ? error.message : String(error));
     });
+    // Record the run in the usage log (issue #100). MCP hosts execute phases in
+    // their own context, so tokens and activity are unknowable here — this is a
+    // completion receipt, marked recorded_by so totals can tell it apart from
+    // the Pi runner's token-bearing entries. Recording lives in this handler,
+    // not core completion, because Pi-driven runs already record with real
+    // telemetry and must not double-count.
+    try {
+        await appendUsageRun(updatedState.workspaceDir, {
+            timestamp: new Date().toISOString(),
+            phase: validation.phaseId,
+            status: "completed",
+            turn_count: 0,
+            tool_uses: 0,
+            duration_ms: 0,
+            tokens: { input: 0, output: 0, cache_write: 0 },
+            recorded_by: "mcp-complete",
+        });
+    }
+    catch {
+        // Usage is best-effort telemetry: the phase completed and canonical
+        // state is already written, so a usage-log write failure must not fail
+        // the completion result. Nothing else can act on the error here.
+    }
+    // Dashboard freshness is a completion side effect (issue #112): the counts
+    // it renders change exactly here, and a stale dashboard misreports them
+    // confidently. writeDashboard never throws; its boolean says whether a
+    // fresh render actually landed, so the result only claims what happened.
+    const dashboardPath = (await writeDashboard(cwd, PACKAGE_VERSION)) ? ".codecarto/dashboard.html" : undefined;
     const lines = [
         `Marked ${validation.phaseId} complete (validation: ${validation.overall}).`,
         `Next phase: ${updatedState.status.current_phase}`,
     ];
     if (closeoutNotice)
         lines.push(closeoutNotice);
+    if (orchestratorCheckpoint)
+        lines.push(orchestratorCheckpoint);
+    if (dashboardPath)
+        lines.push(`Dashboard refreshed: ${dashboardPath}`);
     return textResult(lines.join("\n"), {
         completedPhase: validation.phaseId,
         validation: validation.overall,
         nextPhase: updatedState.status.current_phase,
         closeoutNotice,
+        orchestratorCheckpoint,
+        dashboardPath,
     });
 }
 export async function handleSkill(args) {
@@ -619,18 +672,22 @@ export async function handleUsage(args) {
     }
     const totals = computeTotals(usage);
     const perPhase = computePerPhaseTotals(usage);
+    const receiptRuns = usage.runs.filter((run) => run.recorded_by === "mcp-complete").length;
     const lines = [
         `Total runs: ${totals.runs}`,
         `Total tokens: ${totals.tokens.input} in / ${totals.tokens.output} out / ${totals.tokens.cache_write} cache-write`,
         `Total duration: ${totals.duration_ms}ms / ${totals.tool_uses} tool uses`,
-        "",
-        "Per-phase totals:",
     ];
+    if (receiptRuns > 0) {
+        lines.push(`Note: ${receiptRuns} run(s) recorded via codecarto_complete carry no token or activity data (MCP hosts execute phases in their own context) — zeros above are unknowns, not free runs.`);
+    }
+    lines.push("", "Per-phase totals:");
     for (const [phaseId, t] of perPhase) {
         lines.push(`  ${phaseId}: ${t.runs} run(s), ${t.tokens.input + t.tokens.output} tokens, ${t.tool_uses} tool uses, ${t.duration_ms}ms`);
     }
     return textResult(lines.join("\n"), {
         runs: totals.runs,
+        receiptRuns,
         tokens: totals.tokens,
         toolUses: totals.tool_uses,
         durationMs: totals.duration_ms,
@@ -640,7 +697,9 @@ export async function handleUsage(args) {
 export async function handleDashboard(args) {
     const cwd = await validateCwd(args.cwd);
     await requireWorkspace(cwd);
-    await writeDashboard(cwd, PACKAGE_VERSION);
+    if (!(await writeDashboard(cwd, PACKAGE_VERSION))) {
+        throw new McpError(ErrorCode.InvalidRequest, "Dashboard render failed: the workspace state could not be gathered or .codecarto/dashboard.html is not writable.");
+    }
     return textResult("Dashboard regenerated: .codecarto/dashboard.html", { path: ".codecarto/dashboard.html" });
 }
 export async function handleListSkills(args) {
@@ -652,6 +711,56 @@ export async function handleListSkills(args) {
         : ["No skills installed."];
     return textResult(lines.join("\n"), { skills });
 }
+export async function handleRefreshScaffold(args) {
+    const cwd = await validateCwd(args.cwd);
+    await requireWorkspace(cwd);
+    const result = await refreshScaffold(cwd).catch((error) => {
+        throw new McpError(ErrorCode.InvalidRequest, error instanceof Error ? error.message : String(error));
+    });
+    const shown = result.written.slice(0, 20);
+    const lines = [
+        `Refreshed ${result.written.length} framework-owned file(s) from the packaged template (${result.scaffoldVersionBefore ?? "unversioned"} → ${result.scaffoldVersionAfter}).`,
+        "Project state, user config, findings outputs, scratch, closeouts, and orchestrator files were not touched.",
+        ...shown.map((path) => `  - .codecarto/${path}`),
+    ];
+    if (result.written.length > shown.length)
+        lines.push(`  … +${result.written.length - shown.length} more`);
+    return textResult(lines.join("\n"), {
+        written: result.written,
+        scaffoldVersionBefore: result.scaffoldVersionBefore,
+        scaffoldVersionAfter: result.scaffoldVersionAfter,
+    });
+}
+export async function handleAmend(args) {
+    if (typeof args.name !== "string" || !args.name.trim()) {
+        throw new McpError(ErrorCode.InvalidParams, "name is required (the amendment file's slug under .codecarto/scratch/amendments/)");
+    }
+    const cwd = await validateCwd(args.cwd);
+    await requireWorkspace(cwd);
+    const { applied, closeoutNotice } = await applyAmendment(cwd, args.name).catch((error) => {
+        throw new McpError(ErrorCode.InvalidRequest, error instanceof Error ? error.message : String(error));
+    });
+    // An amendment exists precisely to change the numbers the dashboard shows
+    // (issue #112); refresh it, reporting only a render that actually landed.
+    const dashboardPath = (await writeDashboard(cwd, PACKAGE_VERSION)) ? ".codecarto/dashboard.html" : undefined;
+    const lines = [
+        `Amendment applied.`,
+        `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 (dashboardPath)
+        lines.push(`Dashboard refreshed: ${dashboardPath}`);
+    return textResult(lines.join("\n"), {
+        openQuestionsClosed: applied.openQuestionsClosed,
+        postPipelineClosed: applied.postPipelineClosed,
+        unknownIds: applied.unknownIds,
+        closeoutNotice,
+        dashboardPath,
+    });
+}
 // ---------- tool registry ----------
 const TOOLS = [
     {
@@ -902,9 +1011,32 @@ const TOOLS = [
             required: ["cwd"],
         },
     },
+    {
+        name: "codecarto_amend",
+        description: "Apply a post-pipeline amendment from .codecarto/scratch/amendments/<name>.yaml to workflow/status.yaml: close open questions resolved on evidence after the pipeline completed and retire finished post-pipeline backlog items, under the same lock completion uses. Writes an amendment closeout and THREAD_LOG entry. Refused while the pipeline is incomplete — mid-pipeline resolutions belong in the phase handoff. Idempotent: ids that no longer match are reported, not fatal.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                cwd: { type: "string", description: "Absolute path to the target repository." },
+                name: { type: "string", description: "Amendment file slug under .codecarto/scratch/amendments/ (with or without .yaml)." },
+            },
+            required: ["cwd", "name"],
+        },
+    },
+    {
+        name: "codecarto_refresh_scaffold",
+        description: "Refresh a workspace's framework-owned files (GUIDE.md, templates/, workflow pipelines and VALIDATE.md, skills/, findings SKILL and README stubs) from the packaged template — the action every scaffold-staleness warning instructs. Never touches project state (status.yaml), user config (workflow/config.yaml, usage log), findings outputs, scratch/, closeouts/, or the orchestrator files (CONVENTIONS.md, DECISIONS.md, BACKLOG.md, THREAD_LOG.md). Appends one THREAD_LOG entry naming the version transition. Unlike codecarto_init force:true, nothing is backed up or lost.",
+        inputSchema: {
+            type: "object",
+            properties: { cwd: { type: "string", description: "Absolute path to the target repository." } },
+            required: ["cwd"],
+        },
+    },
 ];
 const HANDLERS = {
+    codecarto_amend: handleAmend,
     codecarto_init: handleInit,
+    codecarto_refresh_scaffold: handleRefreshScaffold,
     codecarto_status: handleStatus,
     codecarto_switch_pipeline: handleSwitchPipeline,
     codecarto_next: handleNext,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codecartographer-pi",
-  "version": "0.14.1",
+  "version": "0.16.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",