codecartographer-pi 0.17.1 → 0.19.0

package/dist/core/status.js

@@ -36,8 +36,42 @@ function coerceEntry(value, allowTargetPhase) {
         entry.deferred_reason = raw.deferred_reason.trim();
     if (allowTargetPhase && typeof raw.target_phase === "string" && raw.target_phase.trim())
         entry.target_phase = raw.target_phase.trim();
+    // derives_from rides the same flag as target_phase: it is a carry-forward
+    // concept only — the id of the open question this routed item answers one
+    // candidate of (#122, #186). An open_questions entry has nothing to derive
+    // from, so the field is dropped there rather than silently carried.
+    if (allowTargetPhase && typeof raw.derives_from === "string" && raw.derives_from.trim())
+        entry.derives_from = raw.derives_from.trim();
     return Object.keys(entry).length > 0 ? entry : null;
 }
+/**
+ * Normalize a handoff's `open_question_closures` (#122, #186). Accepts both
+ * the original bare-string shape and `{ id, evidence }`; a string becomes
+ * `{ id }`, and an entry with no usable id is dropped rather than resolving
+ * nothing under the lock. Values are trimmed.
+ */
+export function ensureClosureArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    const result = [];
+    for (const item of value) {
+        if (typeof item === "string") {
+            const id = item.trim();
+            if (id)
+                result.push({ id });
+            continue;
+        }
+        if (!item || typeof item !== "object" || Array.isArray(item))
+            continue;
+        const raw = item;
+        const id = typeof raw.id === "string" ? raw.id.trim() : "";
+        if (!id)
+            continue;
+        const evidence = typeof raw.evidence === "string" && raw.evidence.trim() ? raw.evidence.trim() : undefined;
+        result.push({ id, ...(evidence !== undefined && { evidence }) });
+    }
+    return result;
+}
 export function ensureEntryArray(value, allowTargetPhase = false) {
     if (!Array.isArray(value))
         return [];
@@ -126,26 +160,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) {
@@ -204,7 +252,7 @@ export function parseHandoff(value) {
         open_questions: openQuestions,
         carry_forward: carryForward,
         carry_forward_closures: ensureArray(raw.carry_forward_closures),
-        open_question_closures: ensureArray(raw.open_question_closures),
+        open_question_closures: ensureClosureArray(raw.open_question_closures),
         post_pipeline: ensurePostPipelineArray(raw.post_pipeline),
         decisions: ensureArray(raw.decisions),
         proposed_conventions: ensureProposedConventionArray(raw.proposed_conventions),
@@ -321,7 +369,8 @@ export function applyHandoff(status, handoff) {
         }
     }
     // Apply open_question_closures: remove resolved questions from ALL phases by id
-    for (const closureId of handoff.open_question_closures) {
+    for (const closure of handoff.open_question_closures) {
+        const closureId = closure?.id;
         if (!closureId)
             continue;
         for (const ph of Object.values(status.phases)) {

package/dist/core/types.d.ts

@@ -9,6 +9,16 @@ export type OpenQuestionEntry = {
 };
 export type CarryForwardEntry = OpenQuestionEntry & {
     target_phase?: string;
+    /**
+     * Optional id of the `open_questions` entry this routed item is one
+     * candidate answer to (#122, #186). The upstream phase usually registers
+     * the question and routes the candidate onward in the same handoff, which
+     * is the cheapest moment to record the link. Completion refuses a closure
+     * of this entry while that question is still open and is not closed by the
+     * same handoff: closing a routed item does not settle the question it came
+     * from. Omitted on every entry that predates the field.
+     */
+    derives_from?: string;
 };
 export type PostPipelineEntry = OpenQuestionEntry & {
     source_phase?: string;
@@ -114,6 +124,18 @@ export type ProposedConventionEntry = {
     /** Optional: where the pattern showed up (file, phase, incident). */
     evidence?: string;
 };
+/**
+ * One claimed closure in a handoff's `open_question_closures` (#122, #186).
+ * A bare string — the only shape before this field grew — normalizes to
+ * `{ id }`; the object form adds the evidence that settles the question.
+ * Completion requires non-empty `evidence` when the closed question's `kind`
+ * is `needs-runtime-test`, because such a question closes on runtime evidence
+ * rather than on another source read.
+ */
+export type ClosureEntry = {
+    id: string;
+    evidence?: string;
+};
 export type PhaseHandoff = {
     phase_id: string;
     /**
@@ -126,7 +148,8 @@ export type PhaseHandoff = {
     open_questions: OpenQuestionEntry[];
     carry_forward: CarryForwardEntry[];
     carry_forward_closures: string[];
-    open_question_closures: string[];
+    /** ids to resolve and remove from all phases; a bare string parses to `{ id }`. */
+    open_question_closures: ClosureEntry[];
     post_pipeline: PostPipelineEntry[];
     decisions: string[];
     /** Conventions proposed for promotion; completion stages them in CONVENTIONS.md. Omitted defaults to empty. */

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}.`;
 }