codecartographer-pi 0.19.2 → 0.19.3

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.3

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;
@@ -164,7 +219,8 @@ export function parseSimpleYaml(raw) {
                 throw new Error(`Duplicate YAML key: ${key} near line: ${line.trim()}`);
             }
             seen.add(key);
-            if (rawValue === "|" || rawValue === "|-") {
+            const blockHeader = parseBlockScalarHeader(rawValue);
+            if (blockHeader) {
                 const blockLines = [];
                 let contentIndent = null;
                 while (index < lines.length) {
@@ -181,8 +237,7 @@ export function parseSimpleYaml(raw) {
                     blockLines.push(blockLine.slice(Math.min(contentIndent, blockIndent)));
                     index++;
                 }
-                const content = blockLines.join("\n").replace(/\n+$/, "");
-                assign(key, rawValue === "|" ? `${content}\n` : content);
+                assign(key, applyBlockScalar(blockLines, blockHeader));
                 continue;
             }
             if (rawValue !== "") {

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,55 @@
+// 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.",
+].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";
@@ -937,10 +938,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.3",
   "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",