codecartographer-pi 0.15.0 → 0.17.0

package/dist/mcp-server/server.js

@@ -1,5 +1,7 @@
-// CodeCartographer MCP server. Exposes the framework as seven JSON-RPC tools
-// equivalent to the seven /codecarto-* commands the Pi extension registers.
+// CodeCartographer MCP server. Exposes the framework's workflow, library, and
+// Broad-Side operations as JSON-RPC tools (the TOOLS array below is the
+// authoritative list; the README's tool table maps each tool to its Pi
+// equivalent or marks it MCP-only).
 // Both wrappers import their primitives from ../core/index.ts so phase prompts,
 // status normalization, validation, and atomic completion are byte-identical
 // across surfaces.
@@ -13,9 +15,9 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 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 { mkdir, readFile, readdir, 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, refreshScaffold, resolvePhase, resolvePipelineChoice, seedOrchestratorFiles, stringifySimpleYaml, switchPipeline, validatePhaseOutput, writeLibraryConfig, } from "../core/index.js";
+import { buildPhasePrompt, buildSkillPrompt, buildValidationSummary, BROADSIDE_DIR, broadsideDirFor, BROADSIDE_LENS_IDS, BROADSIDE_SKILL_NAME, canonicalPath, copyPackagedWorkspace, collectResultText, completeValidatedPhase, computePerPhaseTotals, computeTotals, createEmptyStatus, DEFAULT_PIPELINE_PATH, deriveSlug, discoverLibrary, describeScaffoldStaleness, estimateSubmitText, getLens, getNextEligiblePhase, getPipelineLabel, getWorkspaceState, isValidSlug, isWithinPathResolved, listBatchModels, listEntries, listGuideTopics, loadBroadsideConfig, modelsText, readGuide, listSkillNames, loadCodecartoConfig, loadUsage, loadYamlFile, normalizeForComparison, PACKAGE_VERSION, packagedWorkspaceDir, pathExists, PhasePreflightError, publishEntry, reindex as libraryReindex, refreshScaffold, resolvePhase, resolvePipelineChoice, readBroadsideSkill, runBroadsideCollect, runBroadsideStatus, runBroadsideSubmit, seedOrchestratorFiles, statusText, 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";
@@ -84,7 +86,16 @@ export async function handleInit(args) {
             normalizeForComparison(await canonicalPath(targetWorkspaceDir)) ===
                 normalizeForComparison(await canonicalPath(packagedWorkspaceDir));
     }
+    // Broad-Side (batch reconnaissance) creates .codecarto/broadside/ on any
+    // repo, workspace or not. A .codecarto/ holding only that directory is not
+    // an existing workspace — init must proceed and merge the template into it
+    // rather than demanding force and a backup of pure scout state.
+    let broadsideOnly = false;
     if (targetExists && !sameWorkspace) {
+        const entries = (await readdir(targetWorkspaceDir)).filter((entry) => entry !== BROADSIDE_DIR);
+        broadsideOnly = entries.length === 0 && (await pathExists(join(targetWorkspaceDir, BROADSIDE_DIR)));
+    }
+    if (targetExists && !sameWorkspace && !broadsideOnly) {
         if (!args.force) {
             throw new McpError(ErrorCode.InvalidRequest, `A .codecarto/ directory already exists at ${targetWorkspaceDir}. Pass force: true to back it up and reinitialize. Warning: this moves all existing findings, handoffs, usage data, closeouts, and phase progress to a .codecarto-backup-TIMESTAMP/ directory.`);
         }
@@ -93,7 +104,12 @@ export async function handleInit(args) {
     }
     if (!(await pathExists(targetWorkspaceDir))) {
         await mkdir(cwd, { recursive: true });
-        await cp(packagedWorkspaceDir, targetWorkspaceDir, { recursive: true });
+        await copyPackagedWorkspace(targetWorkspaceDir);
+    }
+    else if (broadsideOnly) {
+        // Merge the template into the scout-only .codecarto/, preserving the
+        // broadside state and results already on disk.
+        await copyPackagedWorkspace(targetWorkspaceDir);
     }
     const statusPath = join(targetWorkspaceDir, "workflow", "status.yaml");
     const rawStatus = (await loadYamlFile(statusPath)) ?? {};
@@ -144,7 +160,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 +288,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 +301,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) {
@@ -288,6 +317,15 @@ export async function handleSkill(args) {
         throw new McpError(ErrorCode.InvalidParams, "name is required");
     }
     const cwd = await validateCwd(args.cwd);
+    // Broad-Side is a reading guide for batch reconnaissance output, not a
+    // post-pipeline skill: it is useful before the pipeline starts and on a
+    // repository with no workspace at all, so it is served ahead of both gates.
+    if (args.name.trim() === BROADSIDE_SKILL_NAME) {
+        const skill = await readBroadsideSkill(cwd).catch((error) => {
+            throw new McpError(ErrorCode.InvalidRequest, error instanceof Error ? error.message : String(error));
+        });
+        return textResult(skill.content, { skill: BROADSIDE_SKILL_NAME, path: skill.path, postPipeline: false });
+    }
     const state = await requireWorkspace(cwd);
     const nextPhase = getNextEligiblePhase(state);
     if (nextPhase) {
@@ -297,7 +335,7 @@ export async function handleSkill(args) {
     if (!(await pathExists(skillFile))) {
         const available = await listSkillNames(state.workspaceDir);
         const hint = available.length > 0 ? ` Available: ${available.join(", ")}.` : " No skills installed.";
-        throw new McpError(ErrorCode.InvalidParams, `Unknown skill: ${args.name}.${hint}`);
+        throw new McpError(ErrorCode.InvalidParams, `Unknown skill: ${args.name}.${hint} The Broad-Side reading guide is served as \`${BROADSIDE_SKILL_NAME}\` and is not pipeline-gated.`);
     }
     const prompt = await buildSkillPrompt(state, args.name);
     return textResult(prompt, { skill: args.name });
@@ -495,7 +533,10 @@ export async function handlePublish(args) {
         capabilities,
         confidentiality,
         generation,
-    }, { forceNewVersion: args.force_new_version === true });
+    }, {
+        forceNewVersion: args.force_new_version === true,
+        allowSourceRepoChange: args.allow_source_repo_change === true,
+    });
     const lines = [
         `Published ${result.namespace ? `${result.namespace}/` : ""}${result.slug} v${result.version} to ${libraryPath}`,
         result.isNewVersion ? `New version: v${result.version}` : `Metadata-only update (content hash matched v${result.version}).`,
@@ -684,7 +725,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) {
@@ -694,7 +737,13 @@ export async function handleListSkills(args) {
     const lines = skills.length > 0
         ? [`Available skills (${skills.length}):`, ...skills.map((s) => `  - ${s}`)]
         : ["No skills installed."];
-    return textResult(lines.join("\n"), { skills });
+    // Broad-Side is listed apart from the post-pipeline set because it answers
+    // to codecarto_skill without the completion gate.
+    const broadsideAvailable = await readBroadsideSkill(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.`);
+    }
+    return textResult(lines.join("\n"), { skills, broadside: broadsideAvailable });
 }
 export async function handleRefreshScaffold(args) {
     const cwd = await validateCwd(args.cwd);
@@ -725,6 +774,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 +785,125 @@ 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,
+    });
+}
+// ---------- broadside (batch reconnaissance) ----------
+function resolveBroadsideApiKey(explicit, config) {
+    if (explicit && explicit.trim())
+        return explicit.trim();
+    const fromEnv = process.env.OPENROUTER_API_KEY?.trim();
+    if (fromEnv)
+        return fromEnv;
+    if (config.apiKey)
+        return config.apiKey;
+    throw new McpError(ErrorCode.InvalidParams, "No OpenRouter API key found. Pass api_key, set the OPENROUTER_API_KEY environment variable, or add api_key to .codecarto/broadside/config.yaml.");
+}
+export async function handleBroadside(args) {
+    const cwd = await validateCwd(args.cwd);
+    const action = args.action ?? "submit";
+    if (!["submit", "collect", "status", "models"].includes(action)) {
+        throw new McpError(ErrorCode.InvalidParams, `Unknown action: ${action}. Valid actions: submit, collect, status, models.`);
+    }
+    const config = await loadBroadsideConfig(broadsideDirFor(cwd));
+    if (action === "status") {
+        const { state } = await runBroadsideStatus(cwd);
+        return textResult(statusText(state), { state });
+    }
+    const apiKey = resolveBroadsideApiKey(args.api_key, config);
+    // Every run knob resolves the same way: explicit parameter, else the repo's
+    // config.yaml default, else the shipped default baked into loadBroadsideConfig.
+    const waitSeconds = typeof args.wait_seconds === "number" && args.wait_seconds > 0
+        ? args.wait_seconds
+        : config.waitSeconds;
+    const waitMs = waitSeconds > 0 ? waitSeconds * 1000 : undefined;
+    const includeSynthesis = args.include_synthesis ?? config.includeSynthesis;
+    const includeTriage = args.include_triage ?? config.includeTriage;
+    const retryTruncated = args.retry_truncated ?? config.retryTruncated;
+    const incremental = args.incremental ?? config.incremental;
+    if (action === "models") {
+        const { entries, benchmarks } = await listBatchModels(broadsideDirFor(cwd), config, apiKey, {
+            includeBenchmarks: args.include_benchmarks === true,
+        }).catch((error) => {
+            throw new McpError(ErrorCode.InvalidRequest, error instanceof Error ? error.message : String(error));
+        });
+        return textResult(modelsText(entries, { benchmarks, defaultModel: config.model }), {
+            models: entries,
+            defaultModel: config.model,
+            benchmarkMeta: benchmarks?.meta ?? null,
+        });
+    }
+    if (action === "submit") {
+        let lenses;
+        if (args.lenses && args.lenses.length > 0) {
+            const unknown = args.lenses.filter((l) => !BROADSIDE_LENS_IDS.includes(l));
+            if (unknown.length > 0) {
+                throw new McpError(ErrorCode.InvalidParams, `Unknown lens(es): ${unknown.join(", ")}. Valid: ${BROADSIDE_LENS_IDS.join(", ")}`);
+            }
+            lenses = args.lenses;
+        }
+        else {
+            lenses = config.defaultLenses;
+        }
+        const maxCost = typeof args.max_cost === "number" && args.max_cost > 0 ? args.max_cost : config.maxCost;
+        const result = await runBroadsideSubmit(cwd, apiKey, {
+            lenses,
+            model: config.model,
+            maxCost,
+            force: args.force === true,
+            incremental,
+        }).catch((error) => {
+            throw new McpError(ErrorCode.InvalidRequest, error instanceof Error ? error.message : String(error));
+        });
+        const lines = [estimateSubmitText(result, lenses.map(getLens))];
+        if (waitMs) {
+            lines.push("", "Waiting for batches to complete...");
+            const collect = await runBroadsideCollect(cwd, apiKey, {
+                waitMs,
+                includeSynthesis,
+                includeTriage,
+                retryTruncated,
+                onStatus: (lensId, status, counts) => lines.push(`  ${lensId}: ${status} (${counts.completed ?? 0}/${counts.total ?? "?"})`),
+            });
+            lines.push("", collectResultText(collect));
+        }
+        return textResult(lines.join("\n"), {
+            runId: result.runId,
+            outputDir: result.outputDir,
+            batches: result.batches,
+            estimatedTotalCost: result.estimatedTotalCost,
+            pricing: result.pricing,
+            maxCost: result.maxCost,
+        });
+    }
+    // action === "collect"
+    const collect = await runBroadsideCollect(cwd, apiKey, {
+        waitMs,
+        includeSynthesis,
+        includeTriage,
+        retryTruncated,
+    }).catch((error) => {
+        throw new McpError(ErrorCode.InvalidRequest, error instanceof Error ? error.message : String(error));
+    });
+    return textResult(collectResultText(collect), {
+        runId: collect.runId,
+        status: collect.status,
+        totalCost: collect.totalCost,
+        resultCount: collect.resultCount,
+        truncatedCount: collect.truncatedCount,
+        retriedCount: collect.retriedCount,
+        lensOutcomes: collect.lensOutcomes,
+        synthesis: collect.synthesis,
+        triage: collect.triage,
+        topFindings: collect.topFindings,
+        topTriageItems: collect.topTriageItems,
     });
 }
 // ---------- tool registry ----------
@@ -832,12 +998,12 @@ const TOOLS = [
     },
     {
         name: "codecarto_skill",
-        description: "Return the prompt text for a post-pipeline skill (only callable after all phases are complete). Use codecarto_status to confirm completion first.",
+        description: "Return the prompt text for a post-pipeline skill (only callable after all phases are complete). Use codecarto_status to confirm completion first. One name is exempt from the completion gate: \"broadside\" returns the reading guide for a Broad-Side batch reconnaissance run, which is meant to be read before or during the pipeline and works without a workspace.",
         inputSchema: {
             type: "object",
             properties: {
                 cwd: { type: "string", description: "Absolute path to the target repository." },
-                name: { type: "string", description: "Skill name (a directory under .codecarto/skills/)." },
+                name: { type: "string", description: "Skill name (a directory under .codecarto/skills/), or \"broadside\" for the Broad-Side reading guide." },
             },
             required: ["cwd", "name"],
         },
@@ -876,6 +1042,10 @@ const TOOLS = [
                     },
                 },
                 force_new_version: { type: "boolean" },
+                allow_source_repo_change: {
+                    type: "boolean",
+                    description: "Permit publishing when the target entry already records a different source_repo. Off by default, because a mismatch usually means two projects derived the same slug and the spec would land in the wrong version history. Set only when the repository itself moved.",
+                },
             },
             required: ["source_repo", "headline"],
         },
@@ -983,7 +1153,7 @@ const TOOLS = [
     },
     {
         name: "codecarto_list_skills",
-        description: "List available post-pipeline skills installed in the workspace.",
+        description: "List available post-pipeline skills installed in the workspace, plus the Broad-Side reading guide when it is present (that one is not pipeline-gated).",
         inputSchema: {
             type: "object",
             properties: { cwd: { type: "string", description: "Absolute path to the target repository." } },
@@ -1011,6 +1181,63 @@ const TOOLS = [
             required: ["cwd"],
         },
     },
+    {
+        name: "codecarto_broadside",
+        description: "Broad-Side: fire a cheap batch reconnaissance scan at a repository via the OpenRouter Batch API. Six lenses (architecture, api, security, defect, conventions, porting) run as asynchronous single-turn prompts with structured JSON schemas; results land in .codecarto/broadside/<run>/ as JSON plus markdown, with an optional cross-lens synthesis report. Works on any git repository — no CodeCartographer workspace required. Requires an OpenRouter API key (api_key param, OPENROUTER_API_KEY env var, or .codecarto/broadside/config.yaml). Findings are unverified scouting signals from a batch model, not validated claims — they tell the interactive pipeline where to look. Actions: submit (fire batches, returns batch ids and cost estimate), collect (poll to completion, save results, optionally synthesize), status (show recorded runs), models (list batch-capable models with pricing, context, output caps, structured-output support, and optional coding benchmarks).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                cwd: { type: "string", description: "Absolute path to the target repository." },
+                action: {
+                    type: "string",
+                    enum: ["submit", "collect", "status", "models"],
+                    description: "submit fires all lens batches and returns batch ids; collect polls submitted batches, saves results, and optionally runs the synthesis pass; status shows recorded runs; models lists batch-capable models with pricing and capabilities.",
+                },
+                lenses: {
+                    type: "array",
+                    items: { type: "string", enum: [...BROADSIDE_LENS_IDS] },
+                    description: "Lenses to run (submit only). Defaults to all six.",
+                },
+                api_key: {
+                    type: "string",
+                    description: "OpenRouter API key. Prefer the OPENROUTER_API_KEY environment variable or .codecarto/broadside/config.yaml.",
+                },
+                wait_seconds: {
+                    type: "number",
+                    description: "For submit: after submitting, poll up to this many seconds before returning. For collect: poll up to this many seconds before returning with partial state. Falls back to wait_seconds in .codecarto/broadside/config.yaml.",
+                },
+                include_synthesis: {
+                    type: "boolean",
+                    description: "Run the cross-lens synthesis pass once all lens batches complete. Falls back to include_synthesis in .codecarto/broadside/config.yaml (default true).",
+                },
+                include_triage: {
+                    type: "boolean",
+                    description: "Run the triage pass once all lens batches complete: turns the findings into a prioritized work order (impact × difficulty, P0-P3, effort estimates). Falls back to include_triage in .codecarto/broadside/config.yaml (default true).",
+                },
+                retry_truncated: {
+                    type: "boolean",
+                    description: "Re-submit lens results that came back truncated at the output token limit, once, with a doubled output cap. Falls back to retry_truncated in .codecarto/broadside/config.yaml (default true).",
+                },
+                max_cost: {
+                    type: "number",
+                    description: "Approximate run expense limit in USD. The submit action estimates the run cost from slice sizes and the configured model's per-token pricing (live OpenRouter lookup, cached 24h) and refuses to submit when the estimate exceeds the limit unless force is true. Falls back to max_cost in .codecarto/broadside/config.yaml.",
+                },
+                force: {
+                    type: "boolean",
+                    description: "Submit even when the cost estimate exceeds max_cost (default false).",
+                },
+                incremental: {
+                    type: "boolean",
+                    description: "Diff against the previous run's git HEAD and scan only the modules whose files changed (falls back to a full scan on a dirty tree or when no prior run exists). Falls back to incremental in .codecarto/broadside/config.yaml (default false).",
+                },
+                include_benchmarks: {
+                    type: "boolean",
+                    description: "For action 'models': annotate each model with its Artificial Analysis coding index (extra API call; default false).",
+                },
+            },
+            required: ["cwd", "action"],
+        },
+    },
 ];
 const HANDLERS = {
     codecarto_amend: handleAmend,
@@ -1034,6 +1261,7 @@ const HANDLERS = {
     codecarto_dashboard: handleDashboard,
     codecarto_list_skills: handleListSkills,
     codecarto_guide: handleGuide,
+    codecarto_broadside: handleBroadside,
 };
 export async function handleGuide(args) {
     const topics = await listGuideTopics();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codecartographer-pi",
-  "version": "0.15.0",
+  "version": "0.17.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",
@@ -35,6 +35,14 @@
   },
   "files": [
     ".codecarto/**/*",
+    "!.codecarto/BACKLOG.md",
+    "!.codecarto/THREAD_LOG.md",
+    "!.codecarto/CONVENTIONS.md",
+    "!.codecarto/DECISIONS.md",
+    "!.codecarto/closeouts/**",
+    "!.codecarto/broadside/**",
+    ".codecarto/broadside/SKILL.md",
+    ".codecarto/broadside/config.yaml",
     "agent-skill/**/*",
     "dist/**/*",
     "assets/logo.svg",
@@ -49,6 +57,7 @@
     "prepublishOnly": "npm run build",
     "test": "node --experimental-strip-types --disable-warning=ExperimentalWarning --test tests/*.test.mjs",
     "smoke": "node scripts/smoke-mcp.mjs",
+    "smoke:broadside": "node scripts/smoke-broadside.mjs",
     "demo:synthesis": "npm run build && node scripts/create-synthesis-demo.mjs"
   },
   "dependencies": {

package/.codecarto/BACKLOG.md

@@ -1,184 +0,0 @@
-# Backlog
-
-Deferred framework improvements with rationale and source feedback files. Items here were
-proposed by one or more agents in the feedback corpus but were not load-bearing enough to land
-in the 2026-05-02 framework feedback pass. Each item is a candidate for a future pass.
-
-Format per entry: rationale + which feedback file(s) raised it + what the smallest viable form
-of the change would look like.
-
----
-
-## B1. Spike template + first-class spike concept — SHIPPED in smallest viable form (v0.15.0, issue #101)
-
-Landed exactly as scoped: `templates/spike-report.md` (Goal / Method / Measurements / Findings / Recommended Deltas) with the `scratch/spikes/<spike-id>/<scenario>.md` convention documented in GUIDE.md and the spec-delta-application skill. No workflow machinery; spikes stay registered as `post_pipeline` entries (`kind: spike`), their findings flow to the spec through spec-delta-application and to `status.yaml` through `codecarto_amend`. Status.yaml spike tracking remains deferred until a project demonstrates the need.
-
----
-
-## B2. Amendments mechanic — SHIPPED (v0.15.0, issue #99)
-
-Landed as `codecarto_amend` over `scratch/amendments/<slug>.yaml` (see `templates/amendment.yaml`): post-pipeline open-question closures and post_pipeline backlog retirement, applied to `workflow/status.yaml` under the completion lock with an amendment closeout and THREAD_LOG entry. The narrower back-amendment question ("a later phase says a prior output is wrong") remains open — a real run handled it with a correction section in the later report plus a delta-application pass, which worked; promote that pattern only if it recurs.
-
----
-
-## B3. Cross-CodeCartographer-workspace references in status.yaml
-
-**Raised by:** `Agent on reimplementation spec - reimplementation spec.txt` (1 agent)
-
-**Why deferred:** Single-agent ask. The use case (one CodeCarto workspace cites another) is real but rare. Most projects have one CodeCarto workspace. Designing a citation format that works across workspaces (relative paths? URLs? content-addressed IDs?) is non-trivial.
-
-**Smallest viable form:** A documented convention for citing across workspaces using `<other-workspace-path>/<phase>/<output>.md#<anchor>` paths, without machinery. If a project demonstrates the need, formalize.
-
----
-
-## B4. 1–5 coverage-depth score (alternative to PASS WITH GAPS)
-
-**Raised by:** `Agent on reimplementation spec - reimplementation spec.txt` (1 agent)
-
-**Why deferred:** Validation is currently structural (PASS / PARTIAL / FAIL with criterion-by-criterion check). A semantic depth score is a real ask but conflicts with the framework's posture that "honest output is the default" — a 1–5 score invites grade inflation in a way the binary criteria do not. Worth more thought before landing.
-
-**Smallest viable form:** Optional second column in the validation block: "Depth: 1–5" with a rubric (1 = section header only; 5 = exhaustive). Use only when the team agrees on the rubric.
-
----
-
-## B5. Programmatic markdown-regex validator
-
-**Raised by:** `Agent on Deep Defect Scan - defect-scan-deep.txt`, `Agent on broad Defect Scan - defect-scan-broad.txt` (2 agents)
-
-**Why deferred:** A real validator (parses status.yaml, checks output paths, verifies validation blocks exist with correct criterion counts, etc.) is a separate tooling project — more than a SKILL/template change. It deserves its own scoping.
-
-**Smallest viable form:** A `scripts/validate.sh` that runs `yq` + `grep` checks for the most common gates (every primary_output exists; every validation block has at least N rows; every status.yaml phase has a status field). Document, don't ship without consensus on scope.
-
----
-
-## B6. CI grep gate for tripwire-named functions
-
-**Raised by:** `Agent on fifth module work - thaum-state.txt` (1 agent — project-level concern)
-
-**Why deferred:** This is a *project*-level CI concern (Thaumaturge), not a framework concern. The framework's job is to surface the convention (which the orchestrator does in CONVENTIONS.md); the project's job is to gate it. Documented for the orchestrator to pick up at the project level.
-
-**Smallest viable form:** Document in CONVENTIONS.md template's example entry that "production code path importing any tripwire-named function should fail the build" is a known follow-up. No framework artifact.
-
----
-
-## B7. Append-mode supersession rule (consolidate vs append)
-
-**Raised by:** `Agent on porting phase - porting.txt`, `Agent on protocols phase - protocols.txt`, `Agent on contracts phase - contracts.txt` (3 agents — at threshold but defers per scope)
-
-**Why deferred:** Real friction: secondary outputs accumulate overlapping descriptions and recency wins by unwritten convention. A "supersedes" marker would land cleanly, but it also implies a reconciliation pass before reimplementation-spec, which is a phase-shape change. Worth landing in a follow-up pass that focuses on append-mode discipline holistically.
-
-**Smallest viable form:** A `> SUPERSEDES <date>:<reason>` block convention at the top of each new dated section in append-mode files, plus a paragraph in GUIDE.md describing it. No machinery; just convention.
-
----
-
-## B8. Validation as semantic check (not just structural / completeness)
-
-**Raised by:** `Agent on broad Defect Scan - defect-scan-broad.txt`, `Agent on Deep Defect Scan - defect-scan-deep.txt`, `Agent on porting phase - porting.txt`, `Agent on protocols phase - protocols.txt` (4 agents — at-threshold)
-
-**Why deferred:** "LLM grades its own homework" is a real gap. The fix is either a quality-subagent (a separate LLM pass that grades against the criteria) or a coverage-depth score (B4). Both are larger changes than this pass should land. The structural check at minimum prevents the worst failure mode (skipping the criterion entirely).
-
-**Smallest viable form:** A `quality-review` skill that delegates to a subagent for criterion-by-criterion semantic check. Optional; not in the default closeout ritual.
-
----
-
-## B9. Spec file split (single 1000+ line file → spec/ directory)
-
-**Raised by:** `Agent on fourth module work - thaum-engine.txt`, `Agent on second module work - thaum-providers-ollama.txt`, `Run three Thaumaturge implementation spikes.txt` (3 agents — at-threshold)
-
-**Why deferred:** This is a *project*-level concern (Thaumaturge's reimplementation-spec.md is 1300+ lines). The framework's template doesn't enforce a single file; a project can split. Documented for the orchestrator to pick up at the project level.
-
-**Smallest viable form:** A documented convention in the opinionated reimpl-spec template that says "if the spec exceeds N lines, split into spec/ with INDEX.md anchored to original section IDs." No framework machinery.
-
----
-
-## B10. SKILL.md and template files redundancy / consolidation
-
-**Raised by:** `Agent on porting phase - porting.txt`, `Agent on protocols phase - protocols.txt`, `Agent on contracts phase - contracts.txt` (3 agents — at-threshold)
-
-**Why deferred:** "SKILL says X, template says X — agent reads both and reconciles" is a real cost. But the framework's posture is that SKILL.md is the *how* (analysis instructions) and template is the *shape* (output skeleton). Collapsing them risks losing the separation. A surgical edit (de-duplicate the obvious overlaps without merging) is hard to do without per-file judgment.
-
-**Smallest viable form:** A pass that inspects each SKILL/template pair and removes section headers from the SKILL that exactly match the template (the template alone is canonical for shape). Per-file work; not a single sweep.
-
----
-
-## B11. Defect-pass-N append discipline (multi-pass defect-scan)
-
-**Raised by:** `Agent on Deep Defect Scan - defect-scan-deep.txt`, `Agent on broad Defect Scan - defect-scan-broad.txt` (2 agents)
-
-**Why deferred:** Defect-scan today expects "one pass = one phase output." Multi-pass (broad → deep) is a real pattern that emerged in Thaumaturge. Partially blessed in 2026-05-04 by `pipeline-full-with-deep-audit.yaml`, which splits the scan into mechanical (passes 1, 2, 6 — after architecture, before contracts) and semantic (passes 3, 4, 5 — after protocols, before porting) phases. Different mechanism than the originally-proposed within-phase pass-N append, but it covers the broad→deep use case. Open question: do projects still need the within-phase append pattern?
-
-**Smallest viable form:** A `templates/defect-report-pass-N.md` template with a `findings/defect-scan/passes/<pass-id>.md` directory convention. Documented; not pre-applied.
-
----
-
-## B12. Resolutions footer / phase resolution mechanic
-
-**Raised by:** `Agent coordinating results - coordinating.txt`, `Agent on contracts phase - contracts.txt` (2 agents)
-
-**Why deferred:** Partially resolved by `carry_forward` in this pass — the routing-and-resolution loop now exists. The remaining ask (a "previously resolved" footer in each output, or a resolutions/ directory) may be obviated by `carry_forward` in practice. Wait for next-pass feedback before adding more machinery.
-
----
-
-## B13. Engine→leaf seam contracts table
-
-**Raised by:** `Agent on fifth module work - thaum-state.txt` (1 agent — project-level)
-
-**Why deferred:** Project-level (Thaumaturge-specific). The framework's job is to surface the convention; CONVENTIONS.md template now has the shape for it. The actual SEAMS.md would live at the project level.
-
----
-
-## B14. Cross-phase consistency check
-
-**Raised by:** `Agent on protocols phase - protocols.txt` (1 agent)
-
-**Why deferred:** "Contracts and protocols both touch dispatcher / redaction / SSE and must stay aligned" — the proposed consistency check is a pre-reimpl-spec reconciliation pass. Related to B7 (append-mode supersession). Bundle into the same future pass.
-
----
-
-## B15. spec-delta-application SKILL canonical refinements (first-run friction)
-
-**Raised by:** `Spec-delta-3 application - 2026-05-03.txt` (1 agent — first real run of the SKILL post-2026-05-02 framework pass; high-signal because the SKILL had no field exposure before this)
-
-**Why deferred:** Six small refinements to the same SKILL.md / templates pair, all visible only after a non-spike-sourced run. Bundling makes the next pass cheap; piecemeal would churn the SKILL repeatedly.
-
-**Smallest viable form:** A surgical pass over `skills/spec-delta-application/SKILL.md` and `templates/deltas-applied.md` covering:
-- **Citation forms** — canonicalize a small family beyond the spike-sourced `[revised per <file> §<delta-id>]`. Round-3 introduced `[revised per DECISIONS.md D5XX (Δ-N), round-N]` for D-entry-sourced deltas and `[revised per closeouts/<file> §<id>, round-N]` for closeout-sourced deltas. Document both as canonical, alongside the spike form.
-- **Audit file path** — explicitly cover the non-spike case. Round-3 used `findings/deltas-applied/round-N.md` (directory convention) when the deltas weren't spike-driven; the existing "sibling-of-spec DELTAS-APPLIED.md" remains a special case for spike rounds.
-- **Closeout filename** — round-numbered (`closeouts/<YYYY-MM-DD>-spec-delta-N.md`) avoids the collision risk of the current `closeouts/<YYYY-MM-DD>-spec-deltas.md` when two passes happen on the same day.
-- **§header naming** — the spec's `## Post-Spike Revisions` header doesn't generalize for non-spike rounds. Rename to `## Post-Pipeline Revisions` (or similar) so post-pipeline non-spike rounds don't have to add explanatory paragraphs about why "Post-Spike" still applies.
-- **Step 6 prominence** — add a sentence to Step 6 ("Update the spec's front-matter citation conventions list") emphasizing this is required when the application introduces new citation forms; otherwise the audit-table marker list is unanchored.
-- **APPLY may refine the proposal** — Δ-36's literal D501 text was "map to 'error'" but the application refined to "emit error event + done(error)" mirroring the existing in-stream-error pattern. The four-bucket matrix's APPLY bucket implicitly permits refinement, but the SKILL should make it explicit: APPLY may include refinements beyond the literal proposal text, with the refinement captured as a Decision-Beyond-Triage in the closeout.
-
----
-
-## B16. Project-level BACKLOG.md template + GUIDE.md project-vs-framework-level clarification
-
-**Raised by:** `Spec-delta-3 application - 2026-05-03.txt` (1 agent — first-run-of-SKILL friction)
-
-**Why deferred:** The SKILL says "DEFER → Add to BACKLOG.md with rationale and a back-reference," but the codex workspace had no project-level BACKLOG.md and the upstream `.codecarto/BACKLOG.md` is for framework-feedback deferrals (correctly excluded from project sync). Round-3 created `.codecarto/BACKLOG.md` from scratch with a project-scoped shape. Future projects will hit the same bootstrap gap.
-
-**Smallest viable form:**
-- Ship `templates/backlog-project.md` skeleton with header + format-per-entry note + an example entry. Format-per-entry should include: rationale, raised-by (closeout file or D-entry), preconditions (which modules / artifacts need to land before the deferral can be revisited — Δ-38 demonstrated this field's value), and "smallest viable form."
-- Add one paragraph to `GUIDE.md` clarifying the project-level vs framework-level distinction: framework `.codecarto/BACKLOG.md` is for framework-feedback deferrals (raised by agents about CodeCartographer itself); project `.codecarto/BACKLOG.md` is for project-decision deferrals (raised during the project's own work).
-- SKILL Step 7 (DEFER bucket) explicitly references the project template.
-
----
-
-## B17. SKILL clarification — DECISIONS.md vs BACKLOG.md semantics for DEFER
-
-**Raised by:** `Spec-delta-3 application - 2026-05-03.txt` (1 agent — first-run-of-SKILL semantic ambiguity)
-
-**Why deferred:** The SKILL's DEFER guidance and its "append numbered entries to DECISIONS.md for any decisions made during triage that weren't already in the deltas" instruction left ambiguous whether DEFER-with-rationale belongs in DECISIONS.md or BACKLOG.md. Round-3 chose: DECISIONS.md is for things the project decided to **DO** (including refinements made during application — e.g., D501's refinement); BACKLOG.md is for things the project decided to **DEFER**. DEFERs do not get a D5xx number, and DECISIONS.md's "pending spec deltas" subsection only tracks proposed → applied lifecycle.
-
-**Smallest viable form:** A two-sentence clarification in SKILL Step 7's DEFER bucket: DEFER → BACKLOG.md (no D-number); refinements made during APPLY → DECISIONS.md "Decisions Beyond Triage" section in the audit file, lifted to DECISIONS.md only if cross-cutting. Existing D-entries for proposed deltas get their disposition updated in place (e.g., "APPLIED 2026-05-03 round-3"); they do not get superseded by new D-entries when applied.
-
----
-
-## How to use this backlog
-
-A future framework-feedback pass picks items up from here. Each item has a "Smallest viable
-form" line so the pass doesn't have to re-design from scratch — the design work was done in this
-pass; the next pass executes.
-
-Add new entries below as agents raise items in future feedback files. When promoting an item to
-"applied," remove the entry from this file and document in the relevant CHANGELOG.