codecartographer-pi 0.19.2 → 0.19.4

package/.codecarto/templates/phase-handoff.yaml

@@ -39,7 +39,8 @@ decisions: []
 #     evidence: <optional: where the pattern showed up>
 proposed_conventions: []
 closeout_summary: ""
-# Optional full closeout Markdown. YAML literal blocks are supported.
+# Optional full closeout Markdown. Block scalars are supported — literal (|, |-,
+# |+) to keep line breaks, folded (>, >-, >+) to join wrapped prose into one line.
 closeout_content: |-
   # Closeout — <phase-id>
 

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.19.2
+scaffold_version: 0.19.4

package/dist/core/yaml.js

@@ -105,6 +105,61 @@ export function parseYamlScalar(rawValue) {
     }
     return trimmed;
 }
+function parseBlockScalarHeader(rawValue) {
+    const match = /^([|>])([-+]?)$/.exec(rawValue);
+    if (!match)
+        return null;
+    return {
+        literal: match[1] === "|",
+        chomp: match[2] === "-" ? "strip" : match[2] === "+" ? "keep" : "clip",
+    };
+}
+/**
+ * Fold a block scalar's lines per YAML's folding rules: a single line break
+ * between two content lines becomes a space, and a run of k blank lines becomes
+ * k newlines. Lines indented deeper than the block's own content indent are
+ * "more indented" and keep their breaks literally, which is what lets a folded
+ * block hold an indented snippet without it being flattened onto one line.
+ */
+function foldBlockLines(blockLines) {
+    let result = "";
+    let pendingBreaks = 0;
+    let started = false;
+    let previousMoreIndented = false;
+    for (const line of blockLines) {
+        if (line.trim() === "") {
+            pendingBreaks++;
+            continue;
+        }
+        const moreIndented = /^[ \t]/.test(line);
+        if (!started) {
+            result = line;
+            started = true;
+            previousMoreIndented = moreIndented;
+            continue;
+        }
+        if (pendingBreaks > 0) {
+            result += "\n".repeat(pendingBreaks);
+            pendingBreaks = 0;
+        }
+        else if (moreIndented || previousMoreIndented) {
+            result += "\n";
+        }
+        else {
+            result += " ";
+        }
+        result += line;
+        previousMoreIndented = moreIndented;
+    }
+    return started ? result + "\n".repeat(pendingBreaks) : "";
+}
+function applyBlockScalar(blockLines, header) {
+    const content = header.literal ? blockLines.join("\n") : foldBlockLines(blockLines);
+    if (header.chomp === "keep")
+        return content;
+    const stripped = content.replace(/\n+$/, "");
+    return header.chomp === "strip" ? stripped : `${stripped}\n`;
+}
 export function parseSimpleYaml(raw) {
     const lines = raw.split(/\r?\n/);
     let index = 0;
@@ -112,6 +167,31 @@ export function parseSimpleYaml(raw) {
         while (index < lines.length && isBlankOrComment(lines[index] ?? ""))
             index++;
     };
+    /**
+     * Read the body of a block scalar that opened on the line just consumed.
+     * Shared by mapping values (`key: >-`) and sequence items (`- >-`): when only
+     * the mapping path had it, a handoff whose `decisions:` list used `- >-`
+     * still failed with the indentation error that #211 was supposed to end.
+     */
+    const collectBlockScalarLines = (baseIndent) => {
+        const blockLines = [];
+        let contentIndent = null;
+        while (index < lines.length) {
+            const blockLine = lines[index] ?? "";
+            if (blockLine.trim() === "") {
+                blockLines.push("");
+                index++;
+                continue;
+            }
+            const blockIndent = countIndent(blockLine);
+            if (blockIndent <= baseIndent)
+                break;
+            contentIndent ??= blockIndent;
+            blockLines.push(blockLine.slice(Math.min(contentIndent, blockIndent)));
+            index++;
+        }
+        return blockLines;
+    };
     const parseBlock = (indent) => {
         skipBlank();
         if (index >= lines.length)
@@ -164,25 +244,9 @@ export function parseSimpleYaml(raw) {
                 throw new Error(`Duplicate YAML key: ${key} near line: ${line.trim()}`);
             }
             seen.add(key);
-            if (rawValue === "|" || rawValue === "|-") {
-                const blockLines = [];
-                let contentIndent = null;
-                while (index < lines.length) {
-                    const blockLine = lines[index] ?? "";
-                    if (blockLine.trim() === "") {
-                        blockLines.push("");
-                        index++;
-                        continue;
-                    }
-                    const blockIndent = countIndent(blockLine);
-                    if (blockIndent <= indent)
-                        break;
-                    contentIndent ??= blockIndent;
-                    blockLines.push(blockLine.slice(Math.min(contentIndent, blockIndent)));
-                    index++;
-                }
-                const content = blockLines.join("\n").replace(/\n+$/, "");
-                assign(key, rawValue === "|" ? `${content}\n` : content);
+            const blockHeader = parseBlockScalarHeader(rawValue);
+            if (blockHeader) {
+                assign(key, applyBlockScalar(collectBlockScalarLines(indent), blockHeader));
                 continue;
             }
             if (rawValue !== "") {
@@ -230,6 +294,11 @@ export function parseSimpleYaml(raw) {
                 }
                 continue;
             }
+            const itemBlockHeader = parseBlockScalarHeader(rawItem);
+            if (itemBlockHeader) {
+                result.push(applyBlockScalar(collectBlockScalarLines(indent), itemBlockHeader));
+                continue;
+            }
             const separator = findKeySeparator(rawItem);
             if (separator !== -1) {
                 const key = rawItem.slice(0, separator).trim();

package/dist/extensions/codecarto/guide-framing.d.ts

@@ -0,0 +1,11 @@
+/** Tool names in the guide that have no Pi slash command. */
+export declare const MCP_ONLY_TOOLS: readonly ["codecarto_library_list", "codecarto_library_reindex"];
+export declare const GUIDE_PREAMBLE: string;
+export declare const PI_SURFACE_ADDENDUM: string;
+/**
+ * Assemble the message /codecarto-guide queues. The guide document is embedded
+ * whole and unmodified between the framing and the addendum — `guide.test.mjs`
+ * pins that documents are served entire rather than summarized, and that holds
+ * on this surface too.
+ */
+export declare function buildPiGuideMessage(documentContent: string, otherTopics: readonly string[]): string;

package/dist/extensions/codecarto/guide-framing.js

@@ -0,0 +1,76 @@
+// Surface framing for the packaged agent guide when it is read into a Pi
+// session.
+//
+// Two problems this solves, both invisible on the MCP surface:
+//
+// 1. The guide arrives as a user message. /codecarto-guide queues the document
+//    through pi.sendUserMessage, so ~200 lines of imperative instructions land
+//    as if the user had typed them, with no task attached. A model handed
+//    instructions and no task either starts driving immediately or stalls
+//    asking what to do; both are wrong for what is a reference lookup.
+//
+// 2. The guide is written for the MCP surface. It tells the agent to call
+//    codecarto_* tools — but the Pi extension registers no tools at all, only
+//    slash commands the *user* invokes. A model that tries to follow it finds
+//    nothing to call and reasonably concludes the server is missing. The drive
+//    loop differs too: on Pi, /codecarto-next runs the phase as an isolated
+//    sub-agent and then auto-validates and auto-completes it, so the guide's
+//    hand-written execute → handoff → validate → complete loop does not
+//    describe a Pi session.
+//
+// The guide text itself stays untouched — agent-skill/ is the single source and
+// core/guide.ts serves it verbatim to every surface. Per-surface adaptation
+// belongs in the wrapper, which is here.
+/** Tool names in the guide that have no Pi slash command. */
+export const MCP_ONLY_TOOLS = ["codecarto_library_list", "codecarto_library_reindex"];
+export const GUIDE_PREAMBLE = [
+    "**CodeCartographer guide — reference material, not a task.**",
+    "",
+    "The user ran `/codecarto-guide`, which queues the guide below into this session so it is available when needed. Nothing is being asked of you yet.",
+    "",
+    "Do not start a workflow, do not begin a phase, and do not ask which repository or pipeline to use. Acknowledge in a sentence that you have read it, then wait. Answer from it when the user asks.",
+].join("\n");
+export const PI_SURFACE_ADDENDUM = [
+    "---",
+    "",
+    "## Reading this guide in a Pi session",
+    "",
+    "The guide above is written for the MCP surface, where an agent drives the workflow by calling `codecarto_*` tools. **This session is the Pi extension, which registers no tools.** There is nothing named `codecarto_*` for you to call, and their absence does not mean a server is missing or misconfigured.",
+    "",
+    `- **Every tool name maps to a slash command the user runs**, mechanically: \`codecarto_status\` → \`/codecarto-status\`, \`codecarto_next\` → \`/codecarto-next\`, and so on. Two have no Pi equivalent: ${MCP_ONLY_TOOLS.map((name) => `\`${name}\``).join(" and ")}.`,
+    "- **Ignore \"every tool takes an absolute `cwd`\".** Slash commands act on the session's own directory; there is no `cwd` argument to pass.",
+    "- **The drive loop is different.** `/codecarto-next` executes the phase itself, as an isolated sub-agent, and then auto-validates and auto-completes it. The guide's hand-written loop — take the prompt, execute it, write the handoff, then validate and complete yourself — describes the MCP surface. On Pi the user drives and the extension executes; your job is to explain what the framework is doing and answer questions about it, not to reproduce that loop by hand.",
+    "",
+    "### How to drive a run",
+    "",
+    "`/codecarto-next` takes flags that change how much runs and how each phase is seeded. They are independent: `--auto` decides *how many phases run*, `--llm-steer` decides *what prompt each one gets*.",
+    "",
+    "| Invocation | What it does |",
+    "| --- | --- |",
+    "| `/codecarto-next` | Runs the next eligible phase, once. Good for watching a single phase or retrying one that stopped. |",
+    "| `/codecarto-next --auto` | Runs every remaining phase back to back, validating and completing each before starting the next. Stops on a validation failure or a sub-agent error. |",
+    "| `/codecarto-next --auto --llm-steer` | The same, with each phase's prompt rewritten from the previous phase's closeout. **This is the usual choice for a full run** — it is what makes phase N+1 aware of what phase N found. |",
+    "| `/codecarto-next --auto --strict --llm-steer` | The same, but also stops on `PASS WITH GAPS` instead of advancing through it. Use when gaps should be reviewed rather than carried forward. |",
+    "",
+    "Notes worth passing on when the user asks:",
+    "",
+    "- **The first phase is never steered** — there is no previous closeout to steer from, so it reports `LLM rewriter skipped (no previous phase to steer from)` and uses the stock prompt. That message is normal, not a failure.",
+    "- **Steering costs an extra model call per phase**, on top of the phase sub-agent itself.",
+    "- `--strict` is only valid with `--auto`; on its own it is an error.",
+    "- `--no-llm-steer` forces steering off for one invocation when the workspace config has it on (`orchestrator.llm_steer_next_phase`, default off).",
+    "- **An auto run that stops says why in its summary block.** If a phase produced its artifact but the pipeline still shows it incomplete, read the `Auto pipeline stopped at …` message rather than assuming the phase failed — the phase usually succeeded and something after it did not.",
+    "",
+    "If the user has just initialized a workspace and has not said what they want, tell them the run command rather than waiting to be asked: `/codecarto-next --auto --llm-steer` for a full pass, or plain `/codecarto-next` to watch one phase first.",
+].join("\n");
+/**
+ * Assemble the message /codecarto-guide queues. The guide document is embedded
+ * whole and unmodified between the framing and the addendum — `guide.test.mjs`
+ * pins that documents are served entire rather than summarized, and that holds
+ * on this surface too.
+ */
+export function buildPiGuideMessage(documentContent, otherTopics) {
+    const footer = otherTopics.length > 0
+        ? `\n\n---\nOther guide topics: ${otherTopics.join(", ")} (run /codecarto-guide <topic>).`
+        : "";
+    return `${GUIDE_PREAMBLE}\n\n---\n\n${documentContent}\n\n${PI_SURFACE_ADDENDUM}${footer}`;
+}

package/dist/extensions/codecarto/index.js

@@ -8,6 +8,7 @@ import { narrateDashboard } from "./dashboard-narrator.js";
 import { writeDashboard } from "./dashboard-writer.js";
 import { parseBroadsideFlags, KNOWN_BROADSIDE_TOKENS } from "./broadside-flags.js";
 import { parseNextFlags } from "./next-flags.js";
+import { buildPiGuideMessage } from "./guide-framing.js";
 import { phaseCompactionExtension } from "./phase-compaction.js";
 import { applyAmendment, buildPhasePrompt, buildSkillPrompt, buildValidationSummary, canonicalPath, copyPackagedWorkspace, computePerPhaseTotals, computeTotals, ConfidentialityMismatchError, createEmptyStatus, DEFAULT_PIPELINE_PATH, describeScaffoldStaleness, deriveSlug, discoverLibrary, getNextEligiblePhase, getPipelineLabel, getWorkspaceState, isWithinPathResolved, BROADSIDE_LENS_IDS, BROADSIDE_SKILL_NAME, BroadsideCancelledError, broadsideDirFor, collectResultText, estimateSubmitText, getLens, listAmendmentNames, listBatchModels, listGuideTopics, listScaffoldRefreshFiles, listSkillNames, loadAmendmentFile, loadBroadsideConfig, modelsText, runBroadsideCollect, runBroadsideStatus, runBroadsideSubmit, statusText, loadCodecartoConfig, loadUsage, loadYamlFile, normalizeForComparison, packagedWorkspaceDir, pathExists, PACKAGE_VERSION, readBroadsideSkill, readGuide, refreshScaffold, PhasePreflightError, PIPELINE_ALIASES, publishEntry, resolvePhase, resolvePipelineChoice, resolvePublishSourceRepo, SourceRepoMismatchError, runPhasePreflight, SCAFFOLD_REFRESH_PROTECTED, seedOrchestratorFiles, stringifySimpleYaml, switchPipeline, validatePhaseOutput, writeLibraryConfig, } from "../../core/index.js";
 import { initLibrary } from "../../core/library.js";
@@ -498,8 +499,14 @@ export default function codeCartographerExtension(pi) {
             // 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");
+            // Name the run command here: init is the moment someone needs it, and
+            // the flags that make a full run useful are not guessable from the
+            // command name alone.
+            lastFeedbackLines = [
+                `Initialized workspace with pipeline: ${getPipelineLabel(selectedPipelinePath)}`,
+                "Full run: `/codecarto-next --auto --llm-steer` — or `/codecarto-next` to watch one phase first.",
+            ];
+            ctx.ui.notify(`Initialized CodeCartographer (${getPipelineLabel(selectedPipelinePath)}). Full run: /codecarto-next --auto --llm-steer`, "info");
             // Render the initial dashboard (empty usage, all phases pending) so
             // the user sees the file exist immediately after /codecarto-init.
             void writeDashboard(ctx.cwd, PACKAGE_VERSION);
@@ -572,11 +579,23 @@ export default function codeCartographerExtension(pi) {
         },
     });
     pi.registerCommand("codecarto-next", {
-        description: "Run the next eligible CodeCartographer phase as a sub-agent. Flags: --llm-steer / --no-llm-steer / --auto [--strict]",
+        description: "Run the next phase as a sub-agent. Full run: --auto --llm-steer. Add --strict to stop on PASS WITH GAPS.",
         getArgumentCompletions: (prefix) => {
-            const items = ["--llm-steer", "--no-llm-steer", "--auto", "--strict"]
-                .filter((value) => value.startsWith(prefix))
-                .map((value) => ({ value, label: value }));
+            // Descriptions, not bare flag names: the completion list is the only
+            // place most users will ever see what these do, and the useful
+            // combination (--auto --llm-steer) is not guessable from the names.
+            // --strict is offered only once --auto is present, because on its own
+            // it is rejected — suggesting it standalone invites the one error the
+            // parser has.
+            const autoAlreadyTyped = prefix.includes("--auto");
+            const items = [
+                { value: "--auto", label: "--auto", description: "run every remaining phase back to back (recommended with --llm-steer)" },
+                { value: "--llm-steer", label: "--llm-steer", description: "seed each phase from the previous phase's closeout; no effect on the first phase" },
+                { value: "--no-llm-steer", label: "--no-llm-steer", description: "force steering off when the workspace config turns it on" },
+                ...(autoAlreadyTyped
+                    ? [{ value: "--strict", label: "--strict", description: "with --auto: stop on PASS WITH GAPS instead of advancing" }]
+                    : []),
+            ].filter((item) => item.value.startsWith(prefix.split(/\s+/).pop() ?? prefix));
             return items.length > 0 ? items : null;
         },
         handler: async (args, ctx) => {
@@ -937,10 +956,10 @@ export default function codeCartographerExtension(pi) {
                 return;
             }
             const other = topics.filter((name) => name !== document.topic);
-            const footer = other.length > 0
-                ? `\n\n---\nOther guide topics: ${other.join(", ")} (run /codecarto-guide <topic>).`
-                : "";
-            const message = `${document.content}${footer}`;
+            // Framed, not bare: the guide is MCP-centric text arriving as a user
+            // message, so it needs both a "this is reference, not a task" header
+            // and a Pi-surface addendum. See guide-framing.ts.
+            const message = buildPiGuideMessage(document.content, other);
             if (ctx.isIdle()) {
                 pi.sendUserMessage(message);
             }

package/package.json

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