codecartographer-pi 0.19.3 → 0.19.4

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

package/dist/core/yaml.js

@@ -167,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)
@@ -221,23 +246,7 @@ export function parseSimpleYaml(raw) {
             seen.add(key);
             const blockHeader = parseBlockScalarHeader(rawValue);
             if (blockHeader) {
-                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++;
-                }
-                assign(key, applyBlockScalar(blockLines, blockHeader));
+                assign(key, applyBlockScalar(collectBlockScalarLines(indent), blockHeader));
                 continue;
             }
             if (rawValue !== "") {
@@ -285,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.js

@@ -40,6 +40,27 @@ export const PI_SURFACE_ADDENDUM = [
     `- **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

package/dist/extensions/codecarto/index.js

@@ -499,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);
@@ -573,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) => {

package/package.json

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