codecartographer-pi 0.14.0 → 0.15.0

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/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

@@ -4,79 +4,95 @@ export declare function handleInit(args: {
     pipeline?: string;
     force?: boolean;
 }): Promise<{
-    content: Array<{
+    content: {
         type: "text";
         text: string;
-    }>;
-    structuredContent?: Record<string, unknown>;
+    }[];
+    structuredContent: {
+        text: string;
+    };
 }>;
 export declare function handleStatus(args: {
     cwd: string;
 }): Promise<{
-    content: Array<{
+    content: {
         type: "text";
         text: string;
-    }>;
-    structuredContent?: Record<string, unknown>;
+    }[];
+    structuredContent: {
+        text: string;
+    };
 }>;
 export declare function handleSwitchPipeline(args: {
     cwd: string;
     pipeline: string;
 }): Promise<{
-    content: Array<{
+    content: {
         type: "text";
         text: string;
-    }>;
-    structuredContent?: Record<string, unknown>;
+    }[];
+    structuredContent: {
+        text: string;
+    };
 }>;
 export declare function handleNext(args: {
     cwd: string;
 }): Promise<{
-    content: Array<{
+    content: {
         type: "text";
         text: string;
-    }>;
-    structuredContent?: Record<string, unknown>;
+    }[];
+    structuredContent: {
+        text: string;
+    };
 }>;
 export declare function handlePhase(args: {
     cwd: string;
     phase: string;
 }): Promise<{
-    content: Array<{
+    content: {
         type: "text";
         text: string;
-    }>;
-    structuredContent?: Record<string, unknown>;
+    }[];
+    structuredContent: {
+        text: string;
+    };
 }>;
 export declare function handleValidate(args: {
     cwd: string;
     phase?: string;
 }): Promise<{
-    content: Array<{
+    content: {
         type: "text";
         text: string;
-    }>;
-    structuredContent?: Record<string, unknown>;
+    }[];
+    structuredContent: {
+        text: string;
+    };
 }>;
 export declare function handleComplete(args: {
     cwd: string;
     phase?: string;
 }): Promise<{
-    content: Array<{
+    content: {
         type: "text";
         text: string;
-    }>;
-    structuredContent?: Record<string, unknown>;
+    }[];
+    structuredContent: {
+        text: string;
+    };
 }>;
 export declare function handleSkill(args: {
     cwd: string;
     name: string;
 }): Promise<{
-    content: Array<{
+    content: {
         type: "text";
         text: string;
-    }>;
-    structuredContent?: Record<string, unknown>;
+    }[];
+    structuredContent: {
+        text: string;
+    };
 }>;
 export declare function readSpecArg(args: {
     spec?: unknown;
@@ -84,25 +100,31 @@ export declare function readSpecArg(args: {
     cwd?: unknown;
 }, allowedRoots: string[]): Promise<string>;
 export declare function handlePublish(args: Record<string, unknown>): Promise<{
-    content: Array<{
+    content: {
         type: "text";
         text: string;
-    }>;
-    structuredContent?: Record<string, unknown>;
+    }[];
+    structuredContent: {
+        text: string;
+    };
 }>;
 export declare function handleLibraryList(args: Record<string, unknown>): Promise<{
-    content: Array<{
+    content: {
         type: "text";
         text: string;
-    }>;
-    structuredContent?: Record<string, unknown>;
+    }[];
+    structuredContent: {
+        text: string;
+    };
 }>;
 export declare function handleLibraryReindex(args: Record<string, unknown>): Promise<{
-    content: Array<{
+    content: {
         type: "text";
         text: string;
-    }>;
-    structuredContent?: Record<string, unknown>;
+    }[];
+    structuredContent: {
+        text: string;
+    };
 }>;
 export declare function handleLibraryInit(args: {
     library_path: string;
@@ -110,75 +132,114 @@ export declare function handleLibraryInit(args: {
     namespace?: string;
     cwd?: string;
 }): Promise<{
-    content: Array<{
+    content: {
         type: "text";
         text: string;
-    }>;
-    structuredContent?: Record<string, unknown>;
+    }[];
+    structuredContent: {
+        text: string;
+    };
 }>;
 export declare function handleVision(args: {
     cwd: string;
     raw_text: string;
 }): Promise<{
-    content: Array<{
+    content: {
         type: "text";
         text: string;
-    }>;
-    structuredContent?: Record<string, unknown>;
+    }[];
+    structuredContent: {
+        text: string;
+    };
 }>;
 export declare function handleConfig(args: {
     cwd?: string;
 }): Promise<{
-    content: Array<{
+    content: {
         type: "text";
         text: string;
-    }>;
-    structuredContent?: Record<string, unknown>;
+    }[];
+    structuredContent: {
+        text: string;
+    };
 }>;
 export declare function handleOpen(args: {
     cwd: string;
 }): Promise<{
-    content: Array<{
+    content: {
         type: "text";
         text: string;
-    }>;
-    structuredContent?: Record<string, unknown>;
+    }[];
+    structuredContent: {
+        text: string;
+    };
 }>;
 export declare function handleUsage(args: {
     cwd: string;
 }): Promise<{
-    content: Array<{
+    content: {
         type: "text";
         text: string;
-    }>;
-    structuredContent?: Record<string, unknown>;
+    }[];
+    structuredContent: {
+        text: string;
+    };
 }>;
 export declare function handleDashboard(args: {
     cwd: string;
 }): Promise<{
-    content: Array<{
+    content: {
         type: "text";
         text: string;
-    }>;
-    structuredContent?: Record<string, unknown>;
+    }[];
+    structuredContent: {
+        text: string;
+    };
 }>;
 export declare function handleListSkills(args: {
     cwd: string;
 }): Promise<{
-    content: Array<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent: {
+        text: string;
+    };
+}>;
+export declare function handleRefreshScaffold(args: {
+    cwd: string;
+}): Promise<{
+    content: {
         type: "text";
         text: string;
-    }>;
-    structuredContent?: Record<string, unknown>;
+    }[];
+    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<{
-    content: Array<{
+    content: {
         type: "text";
         text: string;
-    }>;
-    structuredContent?: Record<string, unknown>;
+    }[];
+    structuredContent: {
+        text: string;
+    };
 }>;
 export declare function buildServer(): Server<{
     method: string;