codecartographer-pi 0.15.0 → 0.16.0

package/.codecarto/workflow/scaffold-version.yaml

@@ -3,4 +3,4 @@
 # workspace's framework-owned files (GUIDE.md, templates/, workflow/ pipelines
 # and VALIDATE.md) predate the running release. Written at release time and
 # copied verbatim by init — never edit by hand.
-scaffold_version: 0.15.0
+scaffold_version: 0.16.0

package/agent-skill/codecartographer/SKILL.md

@@ -122,6 +122,8 @@ A PARTIAL row's evidence must name what is missing and which `open_questions` or
 
 ## When the run drives a rewrite
 
+When the pipeline completes, the finished spec has a designed destination: publish it to a **library** (`codecarto_publish`; create one with `codecarto_library_init`) so synthesis runs and other projects can consume it — `references/library.md`. A spec that only ever lives in its workspace helps exactly one repository.
+
 If the goal is to rebuild or refactor rather than to understand, two phases carry that weight and both have their own reference:
 
 - the defect scans feed `porting` and `reimplementation-spec` as inputs, not as an appendix — `references/deep-audit-synthesis.md`;
@@ -142,5 +144,6 @@ Using what it produces:
 - `references/deep-audit-synthesis.md` — defect dispositions, hazards as normative rules, reporting
 - `references/kernel-first-rewrite.md` — rings, build order, acceptance harness, strategic assumptions
 - `references/carrying-results-forward.md` — starting implementation, autonomy boundaries, publishing findings
+- `references/library.md` — publishing finished specs to a library and consuming them from synthesis runs
 
 This guide is also served by the `codecarto_guide` MCP tool, so an agent with the server configured can read it without installing anything.

package/agent-skill/codecartographer/references/library.md

@@ -0,0 +1,32 @@
+# The library: where finished specs go
+
+A CodeCartographer **library** is a directory of published reimplementation-specs with provenance — the bridge between analysis runs and everything downstream. An analysis pipeline ends with a spec in one workspace; publishing it makes it addressable from any other project, and the **synthesis pipeline** consumes exactly these entries ("convert a user vision and explicitly confirmed library specs into a provenance-backed project plan" — see `codecarto_guide` topic `pipeline-selection`). Without a publish step, every analysis is an island.
+
+## Anatomy
+
+- A directory holding a `.codecarto-library` marker, `entries/` (optionally namespaced), and a generated `index.yaml` + `INDEX.md`.
+- Discovery: tools take `library_path` (absolute) directly, or resolve the library from a workspace `cwd`'s `config.yaml`; `codecarto_library_init` also writes `library.path` into the user-global config so later calls need no path at all.
+- `codecarto_config` shows the effective merge (`library.path`, `library.namespace`, `publish_confirm`) and whether the marker was found.
+
+## The four tools
+
+| Tool | Does | Notes |
+|---|---|---|
+| `codecarto_library_init` | Create the directory, write the marker, record `library.path` in user-global config | Idempotent; pass `namespace` to create a namespaced library |
+| `codecarto_publish` | Publish a spec as a library entry | Required: `source_repo`, `headline`, and `spec` (inline) or `spec_path` (absolute). Content-hash idempotent: identical bytes update metadata in place, no version bump. `slug` derives from `source_repo` if omitted; namespaced libraries require `namespace` (or inherit via `cwd`). Provenance (`source_commit`, `source_branch`, `source_dirty`, `analyzed_at`, `pipeline`, `model_metadata`) is recorded; omitted generation fields default to `unknown` |
+| `codecarto_library_list` | List entries | Filter by `namespace`, `tag`, `slug`, or `source_repo` |
+| `codecarto_library_reindex` | Regenerate `index.yaml` + `INDEX.md` from filesystem state | For manual edits and index merge conflicts |
+
+## When to publish
+
+The moment `reimplementation-spec` completes and validates is the publish moment — the spec is finished, the workspace still knows its provenance (`cwd` inherits `pipeline` from `status.yaml`), and the terminal `next_actions` point here. Publish with `cwd` set so provenance rides along:
+
+```
+codecarto_publish cwd:<workspace repo> source_repo:<repo URL or path> headline:"<one line>" spec_path:<abs path to reimplementation-spec.md>
+```
+
+Set `publish_confirm` in config if you want an explicit confirmation gate before writes.
+
+## What this is not
+
+Publishing a spec into a library is different from copying findings into a product repository you are about to build — that curated-snapshot flow is `references/carrying-results-forward.md`. The library holds *specs as reusable inputs*; a product repo holds *your implementation of one*.

package/dist/core/amendment.js

@@ -8,7 +8,7 @@
 import { appendFile, mkdir, readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { getNextEligiblePhase } from "./pipeline.js";
-import { ensureArray, normalizeStatus } from "./status.js";
+import { buildTerminalNextActions, ensureArray, normalizeStatus } from "./status.js";
 import { dateOnly, pathExists } from "./utils.js";
 import { getWorkspaceState, updateStatusAtomically } from "./workspace.js";
 import { loadYamlFile } from "./yaml.js";
@@ -111,6 +111,9 @@ export async function applyAmendment(cwd, name) {
             nextStatus.post_pipeline = nextStatus.post_pipeline.filter((entry) => entry.id !== closureId);
             (nextStatus.post_pipeline.length !== before ? applied.postPipelineClosed : applied.unknownIds).push(closureId);
         }
+        // The amendment changed exactly the counts the terminal routing lines
+        // carry (issue #114); rebuild them so status never shows stale numbers.
+        nextStatus.next_actions = buildTerminalNextActions(nextStatus);
         nextStatus.last_updated = timestamp;
         // Amendment closeout + THREAD_LOG entry, same idempotence rule as
         // completion: the closeout link appears in THREAD_LOG at most once.

package/dist/core/completion.js

@@ -1,7 +1,7 @@
 import { appendFile, copyFile, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { getNextEligiblePhase, resolvePhase } from "./pipeline.js";
-import { applyHandoff, autoAssignIds, loadHandoffFile, normalizeStatus } from "./status.js";
+import { applyHandoff, autoAssignIds, buildTerminalNextActions, loadHandoffFile, normalizeStatus } from "./status.js";
 import { dateOnly, pathExists, uniqueStrings } from "./utils.js";
 import { getWorkspaceState, updateStatusAtomically } from "./workspace.js";
 /**
@@ -46,6 +46,18 @@ function visibleMarkdown(content) {
 export const DECISIONS_COMPLETION_LOG_HEADING = "## Completion log";
 /** Section heading completion stages proposed conventions under. */
 export const CONVENTIONS_PENDING_HEADING = "## Pending proposals";
+/**
+ * True when `heading` exists as its own visible line. Both orchestrator-file
+ * templates mention their headings in running prose (issue #111: a raw
+ * substring check saw the decisions-template's "…rows under `## Completion
+ * log`…" sentence and never inserted the real heading), so presence checks
+ * must match a whole trimmed line of comment-stripped content.
+ */
+function hasVisibleHeadingLine(content, heading) {
+    return visibleMarkdown(content)
+        .split(/\r?\n/)
+        .some((line) => line.trim() === heading);
+}
 /**
  * Ensure an orchestrator file exists: prefer the workspace's template, fall
  * back to a minimal header for scaffolds that predate the template.
@@ -90,7 +102,7 @@ async function appendDecisionLog(workspaceDir, phaseId, closeoutFile, decisions)
         if (Number.isFinite(parsed) && parsed >= nextNumber)
             nextNumber = parsed + 1;
     }
-    if (!content.includes(DECISIONS_COMPLETION_LOG_HEADING)) {
+    if (!hasVisibleHeadingLine(content, DECISIONS_COMPLETION_LOG_HEADING)) {
         content += `${content.endsWith("\n") ? "" : "\n"}\n${DECISIONS_COMPLETION_LOG_HEADING}\n\nAppended by completion from each phase handoff's \`decisions\` array. The orchestrator may re-file entries into the category sections above; numbering is shared with them.\n`;
     }
     const source = closeoutFile.replace(/\.md$/, "");
@@ -114,13 +126,20 @@ export async function countPendingProposals(workspaceDir, content) {
             return 0;
         text = await readFile(filePath, "utf8");
     }
-    const start = text.indexOf(CONVENTIONS_PENDING_HEADING);
-    if (start === -1)
+    // Same line-anchored rule as the heading-insertion checks: a prose mention
+    // of the heading must not open the section early and miscount.
+    const lines = visibleMarkdown(text).split(/\r?\n/);
+    const headingIndex = lines.findIndex((line) => line.trim() === CONVENTIONS_PENDING_HEADING);
+    if (headingIndex === -1)
         return 0;
-    const rest = text.slice(start + CONVENTIONS_PENDING_HEADING.length);
-    const end = rest.indexOf("\n## ");
-    const section = end === -1 ? rest : rest.slice(0, end);
-    return section.split(/\r?\n/).filter((line) => line.startsWith("- **")).length;
+    let count = 0;
+    for (const line of lines.slice(headingIndex + 1)) {
+        if (line.startsWith("## "))
+            break;
+        if (line.startsWith("- **"))
+            count += 1;
+    }
+    return count;
 }
 /**
  * Stage handoff `proposed_conventions` in CONVENTIONS.md under
@@ -135,7 +154,7 @@ async function stageProposedConventions(workspaceDir, phaseId, timestamp, propos
         return { staged: 0, totalPending: await countPendingProposals(workspaceDir) };
     }
     let content = await ensureOrchestratorFile(workspaceDir, "CONVENTIONS.md", "conventions-template.md", "# Conventions\n\nCross-cutting patterns promoted to project-wide invariants. This scaffold predates templates/conventions-template.md; refresh the framework-owned files for the full format.\n");
-    if (!content.includes(CONVENTIONS_PENDING_HEADING)) {
+    if (!hasVisibleHeadingLine(content, CONVENTIONS_PENDING_HEADING)) {
         content += `${content.endsWith("\n") ? "" : "\n"}\n${CONVENTIONS_PENDING_HEADING}\n\nStaged by completion from each phase handoff's \`proposed_conventions\`. The orchestrator promotes an entry into a numbered convention above (or removes it with a note) at the phase boundary — see GUIDE.md §Roles.\n`;
     }
     // Same visible-content rule as the decision log: template comments must not
@@ -298,7 +317,7 @@ export async function completeValidatedPhase(cwd, validation, sourceLabel) {
         nextStatus.current_phase = nextEligible?.id ?? "complete";
         nextStatus.next_actions = nextEligible
             ? [`Begin ${nextEligible.id} phase by producing ${nextEligible.primary_output ?? `findings/${nextEligible.id}/`}`]
-            : ["All phases complete. Review findings, open questions, and downstream implementation notes."];
+            : buildTerminalNextActions(nextStatus);
         const artifacts = await writeCompletionArtifacts(lockedState.workspaceDir, validation.phaseId, validation, completionTimestamp, handoff);
         closeoutPath = artifacts.closeoutPath;
         orchestratorCheckpoint = buildOrchestratorCheckpoint(artifacts.decisionsAppended, artifacts.totalPendingProposals, nextStatus);

package/dist/core/status.d.ts

@@ -9,6 +9,14 @@ export declare function autoAssignIds(entries: OpenQuestionEntry[], prefix: stri
 export declare function ensurePostPipelineArray(value: unknown): PostPipelineEntry[];
 export declare function ensurePhaseRecord(value: unknown): Record<string, StatusPhase>;
 export declare function createEmptyStatus(projectName: string, pipelinePath: string, pipeline: PipelineFile): NormalizedStatus;
+/**
+ * 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.
+ */
+export declare function buildTerminalNextActions(status: NormalizedStatus): string[];
 export declare function normalizeStatus(status: StatusFile, pipeline: PipelineFile, pipelinePath: string, cwd: string): NormalizedStatus;
 export declare function parseHandoff(value: unknown): PhaseHandoff;
 /**

package/dist/core/status.js

@@ -126,6 +126,28 @@ export function createEmptyStatus(projectName, pipelinePath, pipeline) {
         post_pipeline: [],
     };
 }
+/**
+ * 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.
+ */
+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.",
+    ];
+    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).`);
+    }
+    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("Dashboard: .codecarto/dashboard.html (refreshed on completion and amendment; codecarto_dashboard re-renders on demand). Usage totals: codecarto_usage.");
+    return actions;
+}
 export function normalizeStatus(status, pipeline, pipelinePath, cwd) {
     if (typeof status.schema_version === "number" && status.schema_version > 1) {
         throw new Error(`Unsupported status schema_version ${status.schema_version}. Supported: 1.`);

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/mcp-server/server.js

@@ -144,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}`);
@@ -267,6 +272,11 @@ export async function handleComplete(args) {
         // 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}`,
@@ -275,12 +285,15 @@ export async function handleComplete(args) {
         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) {
@@ -684,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) {
@@ -725,6 +740,9 @@ export async function handleAmend(args) {
     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"}`,
@@ -733,11 +751,14 @@ export async function handleAmend(args) {
     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 ----------

package/package.json

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