codecartographer-pi 0.11.0 → 0.12.0

package/dist/core/status.js

@@ -1,11 +1,17 @@
 // Status normalization, atomic writes, and file-lock primitives. Pure
 // framework logic shared by every wrapper.
 import { open, rm, stat } from "node:fs/promises";
-import { basename } from "node:path";
-import { sleep } from "./utils.js";
+import { basename, join } from "node:path";
+import { pathExists, sleep } from "./utils.js";
+import { loadYamlFile } from "./yaml.js";
 export const LOCK_RETRY_MS = 125;
 export const LOCK_TIMEOUT_MS = 5000;
 export const STALE_LOCK_MS = 60_000;
+export function assertSafePhaseId(phaseId) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(phaseId)) {
+        throw new Error(`Invalid phase id: ${phaseId}`);
+    }
+}
 export function ensureArray(value) {
     return Array.isArray(value) ? value.filter((entry) => typeof entry === "string") : [];
 }
@@ -43,6 +49,39 @@ export function ensureEntryArray(value, allowTargetPhase = false) {
     }
     return result;
 }
+export function autoAssignIds(entries, prefix, phaseId) {
+    const existingIds = new Set(entries.map((e) => e.id).filter(Boolean));
+    let counter = 0;
+    for (const entry of entries) {
+        if (!entry.id || !entry.id.trim()) {
+            counter++;
+            let candidate = `${prefix}-${phaseId}-${counter}`;
+            while (existingIds.has(candidate)) {
+                counter++;
+                candidate = `${prefix}-${phaseId}-${counter}`;
+            }
+            existingIds.add(candidate);
+            entry.id = candidate;
+        }
+    }
+}
+export function ensurePostPipelineArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    const result = [];
+    for (const item of value) {
+        const base = coerceEntry(item, false);
+        if (!base)
+            continue;
+        const raw = typeof item === "object" && item && !Array.isArray(item) ? item : {};
+        result.push({
+            ...base,
+            source_phase: typeof raw.source_phase === "string" && raw.source_phase.trim() ? raw.source_phase.trim() : undefined,
+            status: raw.status === "resolved" ? "resolved" : "pending",
+        });
+    }
+    return result;
+}
 export function ensurePhaseRecord(value) {
     if (!value || typeof value !== "object")
         return {};
@@ -79,13 +118,18 @@ export function createEmptyStatus(projectName, pipelinePath, pipeline) {
         pipeline: pipelinePath,
         current_phase: firstPhase,
         last_updated: "",
+        schema_version: 1,
         phases,
         next_actions: firstPhaseConfig?.primary_output
             ? [`Begin ${firstPhase} phase by producing ${firstPhaseConfig.primary_output}`]
             : ["Begin the first pending phase."],
+        post_pipeline: [],
     };
 }
 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.`);
+    }
     const phases = ensurePhaseRecord(status.phases);
     for (const phaseId of pipeline.phase_order) {
         if (!phases[phaseId]) {
@@ -103,10 +147,151 @@ export function normalizeStatus(status, pipeline, pipelinePath, cwd) {
         pipeline: status.pipeline?.trim() || pipelinePath,
         current_phase: status.current_phase?.trim() || pipeline.phase_order[0] || "complete",
         last_updated: status.last_updated?.trim() || "",
+        schema_version: typeof status.schema_version === "number" ? status.schema_version : 1,
         phases,
         next_actions: ensureArray(status.next_actions),
+        post_pipeline: ensurePostPipelineArray(status.post_pipeline),
+    };
+}
+export function parseHandoff(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("Invalid handoff: expected object");
+    }
+    const raw = value;
+    if (typeof raw.phase_id !== "string" || !raw.phase_id.trim()) {
+        throw new Error("Invalid handoff: phase_id is required");
+    }
+    const schemaVersion = typeof raw.schema_version === "number" ? raw.schema_version : 1;
+    // Reject unsupported future versions (anything > current version 1)
+    if (schemaVersion > 1) {
+        throw new Error(`Invalid handoff: unsupported schema_version ${schemaVersion}. Supported: 1.`);
+    }
+    for (const field of ["owner_notes", "open_questions", "carry_forward", "carry_forward_closures", "open_question_closures", "post_pipeline", "decisions"]) {
+        if (raw[field] !== undefined && !Array.isArray(raw[field])) {
+            throw new Error(`Invalid handoff: ${field} must be an array`);
+        }
+    }
+    const openQuestions = ensureEntryArray(raw.open_questions, false);
+    const carryForward = ensureEntryArray(raw.carry_forward, true);
+    autoAssignIds(openQuestions, "oq", raw.phase_id.trim());
+    autoAssignIds(carryForward, "cf", raw.phase_id.trim());
+    return {
+        phase_id: raw.phase_id.trim(),
+        timestamp: typeof raw.timestamp === "string" ? raw.timestamp.trim() : undefined,
+        owner_notes: ensureArray(raw.owner_notes),
+        open_questions: openQuestions,
+        carry_forward: carryForward,
+        carry_forward_closures: ensureArray(raw.carry_forward_closures),
+        open_question_closures: ensureArray(raw.open_question_closures),
+        post_pipeline: ensurePostPipelineArray(raw.post_pipeline),
+        decisions: ensureArray(raw.decisions),
+        closeout_content: typeof raw.closeout_content === "string" ? raw.closeout_content : "",
+        closeout_summary: typeof raw.closeout_summary === "string" ? raw.closeout_summary : "",
+        schema_version: schemaVersion,
     };
 }
+export async function loadHandoffFile(phaseId, workspaceDir) {
+    assertSafePhaseId(phaseId);
+    const handoffPath = join(workspaceDir, "scratch", "handoffs", `${phaseId}.yaml`);
+    if (!(await pathExists(handoffPath)))
+        return null;
+    const raw = await loadYamlFile(handoffPath);
+    return parseHandoff(raw);
+}
+export function applyHandoff(status, handoff) {
+    const phase = status.phases[handoff.phase_id];
+    if (!phase)
+        return status;
+    phase.owner_notes = ensureArray([
+        ...phase.owner_notes,
+        ...handoff.owner_notes,
+    ]);
+    // Merge open_questions: deduplicate by id across ALL phases, not just this one
+    // First, collect existing questions with the same id from other phases
+    const oqMap = new Map();
+    for (const [pid, ph] of Object.entries(status.phases)) {
+        for (const entry of ph.open_questions ?? []) {
+            const key = entry.id || entry.description || "";
+            if (key)
+                oqMap.set(key, { entry, phase: pid });
+        }
+    }
+    // Remove existing entries with matching ids from their original phases
+    for (const entry of handoff.open_questions) {
+        const key = entry.id || entry.description || "";
+        if (key && oqMap.has(key)) {
+            const existing = oqMap.get(key);
+            if (existing.phase !== handoff.phase_id) {
+                status.phases[existing.phase].open_questions = status.phases[existing.phase].open_questions.filter((e) => (e.id || e.description || "") !== key);
+            }
+        }
+    }
+    // Now merge into the current phase: overwrite by id or append new
+    const localOqMap = new Map();
+    for (const entry of phase.open_questions) {
+        const key = entry.id || entry.description || "";
+        if (key)
+            localOqMap.set(key, entry);
+    }
+    for (const entry of handoff.open_questions) {
+        const key = entry.id || entry.description || "";
+        if (key)
+            localOqMap.set(key, entry);
+        else
+            phase.open_questions.push(entry);
+    }
+    phase.open_questions = [...localOqMap.values()];
+    // Merge carry_forward: overwrite by id or append new
+    const cfMap = new Map();
+    for (const entry of phase.carry_forward) {
+        const key = entry.id || entry.description || "";
+        if (key)
+            cfMap.set(key, entry);
+    }
+    for (const entry of handoff.carry_forward) {
+        const key = entry.id || entry.description || "";
+        if (key)
+            cfMap.set(key, entry);
+        else
+            phase.carry_forward.push(entry);
+    }
+    phase.carry_forward = [...cfMap.values()];
+    // Apply closures: remove carry_forward entries from ALL phases by id
+    for (const closureId of handoff.carry_forward_closures) {
+        if (!closureId)
+            continue;
+        for (const ph of Object.values(status.phases)) {
+            ph.carry_forward = ph.carry_forward.filter((entry) => entry.id !== closureId);
+        }
+    }
+    // Apply open_question_closures: remove resolved questions from ALL phases by id
+    for (const closureId of handoff.open_question_closures) {
+        if (!closureId)
+            continue;
+        for (const ph of Object.values(status.phases)) {
+            ph.open_questions = ph.open_questions.filter((entry) => entry.id !== closureId);
+        }
+    }
+    const postPipeline = new Map();
+    const legacyPostPipeline = [];
+    for (const entry of status.post_pipeline) {
+        if (entry.id)
+            postPipeline.set(entry.id, entry);
+        else
+            legacyPostPipeline.push(entry);
+    }
+    for (const entry of handoff.post_pipeline) {
+        const normalized = {
+            ...entry,
+            source_phase: entry.source_phase ?? handoff.phase_id,
+            status: entry.status ?? "pending",
+        };
+        if (normalized.id)
+            postPipeline.set(normalized.id, normalized);
+    }
+    status.post_pipeline = [...legacyPostPipeline, ...postPipeline.values()];
+    return status;
+}
 export async function acquireLock(lockPath) {
     const startedAt = Date.now();
     while (true) {

package/dist/core/synthesis.d.ts

@@ -0,0 +1,31 @@
+import type { PipelinePhase, WorkspaceState } from "./types.ts";
+export declare const SYNTHESIS_PROPOSAL_PATH = "findings/goal-synthesis/proposal.md";
+export declare const SYNTHESIS_VISION_INPUT_PATH = "inputs/vision.md";
+export type SynthesisLibraryEntry = {
+    ref: string;
+    version: number;
+    versions: number[];
+    headline: string;
+    tags: string[];
+    specPath: string;
+};
+export type ConfirmedProposalSelection = {
+    ref: string;
+    version: number;
+    specPath?: string;
+};
+export type PhasePreflightResult = {
+    libraryPath?: string;
+    libraryName?: string;
+    libraryEntries: SynthesisLibraryEntry[];
+    confirmedEntries: string[];
+    confirmedSelections: ConfirmedProposalSelection[];
+};
+export declare class PhasePreflightError extends Error {
+    readonly phaseId: string;
+    constructor(phaseId: string, message: string);
+}
+export declare function parseConfirmedProposalEntries(markdown: string): string[];
+export declare function hasMeaningfulVisionContent(markdown: string): boolean;
+export declare function parseConfirmedProposalSelections(markdown: string): ConfirmedProposalSelection[];
+export declare function runPhasePreflight(state: WorkspaceState, phase: PipelinePhase): Promise<PhasePreflightResult>;

package/dist/core/synthesis.js

@@ -0,0 +1,140 @@
+// Runtime guards and library context for the forward synthesis pipeline.
+// These checks live in core so Pi and MCP refuse the same invalid transition
+// before an LLM receives a phase prompt.
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { discoverLibrary, listEntries } from "./library.js";
+import { loadCodecartoConfig } from "./orchestrator-config.js";
+import { pathExists } from "./utils.js";
+export const SYNTHESIS_PROPOSAL_PATH = "findings/goal-synthesis/proposal.md";
+export const SYNTHESIS_VISION_INPUT_PATH = "inputs/vision.md";
+export class PhasePreflightError extends Error {
+    phaseId;
+    constructor(phaseId, message) {
+        super(`Cannot start ${phaseId}: ${message}`);
+        this.phaseId = phaseId;
+        this.name = "PhasePreflightError";
+    }
+}
+export function parseConfirmedProposalEntries(markdown) {
+    return parseConfirmedProposalSelections(markdown).map((selection) => selection.ref);
+}
+export function hasMeaningfulVisionContent(markdown) {
+    let inHtmlComment = false;
+    for (const line of markdown.split(/\r?\n/)) {
+        const visibleSegments = [];
+        let cursor = 0;
+        while (cursor < line.length) {
+            if (inHtmlComment) {
+                const commentEnd = line.indexOf("-->", cursor);
+                if (commentEnd === -1) {
+                    cursor = line.length;
+                    continue;
+                }
+                inHtmlComment = false;
+                cursor = commentEnd + 3;
+                continue;
+            }
+            const commentStart = line.indexOf("<!--", cursor);
+            if (commentStart === -1) {
+                visibleSegments.push(line.slice(cursor));
+                break;
+            }
+            visibleSegments.push(line.slice(cursor, commentStart));
+            inHtmlComment = true;
+            cursor = commentStart + 4;
+        }
+        // Keep source segments separated so removing a comment cannot manufacture
+        // a new multi-character token from the characters on either side.
+        const visible = visibleSegments.join(" ").trim();
+        if (!visible || /^#+(?:\s|$)/.test(visible))
+            continue;
+        if (/[\p{L}\p{N}]/u.test(visible))
+            return true;
+    }
+    return false;
+}
+export function parseConfirmedProposalSelections(markdown) {
+    const confirmed = [];
+    for (const rawLine of markdown.split(/\r?\n/)) {
+        const match = rawLine.match(/^\|\s*\[[xX]\]\s*\|\s*`?([^|`]+)`?\s*\|\s*`?v?(\d+)`?\s*\|/i);
+        const ref = match?.[1]?.trim();
+        const version = match?.[2] ? Number.parseInt(match[2], 10) : Number.NaN;
+        if (ref && Number.isInteger(version) && !confirmed.some((selection) => selection.ref === ref)) {
+            confirmed.push({ ref, version });
+        }
+    }
+    return confirmed;
+}
+export async function runPhasePreflight(state, phase) {
+    const checks = new Set(phase.preflight ?? []);
+    // Confirmed proposal rows are meaningful only when they can be resolved
+    // against the configured versioned library. Keep the stronger check
+    // self-contained instead of relying on every pipeline to co-declare its
+    // implementation dependency.
+    if (checks.has("requires-confirmed-proposal"))
+        checks.add("requires-library");
+    const result = { libraryEntries: [], confirmedEntries: [], confirmedSelections: [] };
+    if (checks.has("requires-vision-input")) {
+        const visionPath = join(state.workspaceDir, SYNTHESIS_VISION_INPUT_PATH);
+        if (!(await pathExists(visionPath))) {
+            throw new PhasePreflightError(phase.id, `the vision brief is missing at .codecarto/${SYNTHESIS_VISION_INPUT_PATH}. Create it before starting synthesis.`);
+        }
+        const rawVision = await readFile(visionPath, "utf8");
+        if (!hasMeaningfulVisionContent(rawVision)) {
+            throw new PhasePreflightError(phase.id, `the vision brief at .codecarto/${SYNTHESIS_VISION_INPUT_PATH} is still empty. Describe the audience, problem, and desired outcome, then retry.`);
+        }
+    }
+    if (checks.has("requires-library")) {
+        const config = await loadCodecartoConfig(state.workspaceDir);
+        if (!config.library.path) {
+            throw new PhasePreflightError(phase.id, "no library.path is configured. Set it in ~/.codecarto/config.yaml or .codecarto/workflow/config.yaml.");
+        }
+        const marker = await discoverLibrary(config.library.path);
+        if (!marker) {
+            throw new PhasePreflightError(phase.id, `no CodeCartographer library was found at ${config.library.path} (missing .codecarto-library).`);
+        }
+        const entries = await listEntries(config.library.path);
+        if (entries.length === 0) {
+            throw new PhasePreflightError(phase.id, `the configured library at ${config.library.path} has no entries. Publish at least one reimplementation spec first.`);
+        }
+        result.libraryPath = config.library.path;
+        result.libraryName = marker.name;
+        result.libraryEntries = entries.map((entry) => describeLibraryEntry(config.library.path, entry));
+    }
+    if (checks.has("requires-confirmed-proposal")) {
+        const proposalPath = join(state.workspaceDir, SYNTHESIS_PROPOSAL_PATH);
+        if (!(await pathExists(proposalPath))) {
+            throw new PhasePreflightError(phase.id, `the proposal is missing at .codecarto/${SYNTHESIS_PROPOSAL_PATH}. Run goal-synthesis-propose first.`);
+        }
+        result.confirmedSelections = parseConfirmedProposalSelections(await readFile(proposalPath, "utf8"));
+        result.confirmedEntries = result.confirmedSelections.map((selection) => selection.ref);
+        if (result.confirmedSelections.length === 0) {
+            throw new PhasePreflightError(phase.id, `no library entries are confirmed in .codecarto/${SYNTHESIS_PROPOSAL_PATH}. Change at least one [ ] checkbox to [x], then retry.`);
+        }
+        const available = new Map(result.libraryEntries.map((entry) => [entry.ref, entry]));
+        for (const selection of result.confirmedSelections) {
+            const entry = available.get(selection.ref);
+            if (!entry || !entry.versions.includes(selection.version)) {
+                throw new PhasePreflightError(phase.id, `confirmed selection ${selection.ref}@v${selection.version} is not present in the configured library. Re-run the proposal phase or correct the checked row.`);
+            }
+            selection.specPath = specPathForVersion(result.libraryPath, selection.ref, selection.version);
+        }
+    }
+    return result;
+}
+function describeLibraryEntry(libraryPath, entry) {
+    const ref = entry.namespace ? `${entry.namespace}/${entry.slug}` : entry.slug;
+    const version = entry.latest_version;
+    return {
+        ref,
+        version,
+        versions: [...entry.versions],
+        headline: entry.headline,
+        tags: [...entry.tags],
+        specPath: join(libraryPath, "entries", ...(entry.namespace ? [entry.namespace] : []), entry.slug, `v${version}`, "reimplementation-spec.md"),
+    };
+}
+function specPathForVersion(libraryPath, ref, version) {
+    return join(libraryPath, "entries", ...ref.split("/"), `v${version}`, "reimplementation-spec.md");
+}

package/dist/core/types.d.ts

@@ -10,6 +10,10 @@ export type OpenQuestionEntry = {
 export type CarryForwardEntry = OpenQuestionEntry & {
     target_phase?: string;
 };
+export type PostPipelineEntry = OpenQuestionEntry & {
+    source_phase?: string;
+    status?: "pending" | "resolved";
+};
 export type StatusPhase = {
     status: PhaseStatusValue | string;
     owner_notes: string[];
@@ -22,8 +26,10 @@ export type StatusFile = {
     pipeline?: string;
     current_phase?: string;
     last_updated?: string;
+    schema_version?: number;
     phases?: Record<string, StatusPhase>;
     next_actions?: string[];
+    post_pipeline?: PostPipelineEntry[];
 };
 export type SecondaryOutput = {
     path: string;
@@ -40,6 +46,7 @@ export type PipelinePhase = {
     required_reads?: string[];
     completion_criteria?: string[];
     handoff_requirements?: string[];
+    preflight?: Array<"requires-vision-input" | "requires-library" | "requires-confirmed-proposal">;
 };
 export type PipelineFile = {
     workflow_name?: string;
@@ -50,7 +57,9 @@ export type PipelineFile = {
     phase_order: string[];
     phases: PipelinePhase[];
 };
-export type NormalizedStatus = Required<Pick<StatusFile, "project_name" | "pipeline" | "current_phase" | "last_updated" | "phases" | "next_actions">>;
+export type NormalizedStatus = Required<Pick<StatusFile, "project_name" | "pipeline" | "current_phase" | "last_updated" | "phases" | "next_actions" | "post_pipeline">> & {
+    schema_version: number;
+};
 export type WorkspaceState = {
     cwd: string;
     workspaceDir: string;
@@ -75,3 +84,22 @@ export type ValidationResult = {
     gaps: string[];
     errors: string[];
 };
+export type PhaseHandoff = {
+    phase_id: string;
+    /**
+     * Deprecated: model-provided timestamps are ignored. The framework uses
+     * the host clock for all canonical writes (status.yaml, THREAD_LOG,
+     * closeout). Kept in the type for backward-compatible parse only.
+     */
+    timestamp?: string;
+    owner_notes: string[];
+    open_questions: OpenQuestionEntry[];
+    carry_forward: CarryForwardEntry[];
+    carry_forward_closures: string[];
+    open_question_closures: string[];
+    post_pipeline: PostPipelineEntry[];
+    decisions: string[];
+    closeout_content: string;
+    closeout_summary: string;
+    schema_version?: number;
+};

package/dist/core/workspace.d.ts

@@ -1,11 +1,13 @@
-import type { WorkspaceState } from "./types.ts";
+import type { PhaseHandoff, WorkspaceState } from "./types.ts";
 export declare const packagedWorkspaceDir: string;
 export declare const PACKAGE_VERSION: string;
 export declare function getWorkspaceState(cwd: string): Promise<WorkspaceState | null>;
 export declare function updateStatusAtomically(cwd: string, updater: (state: WorkspaceState) => Promise<{
     state: WorkspaceState;
+    handoff?: PhaseHandoff;
     threadLogEntry?: string;
 }> | {
     state: WorkspaceState;
+    handoff?: PhaseHandoff;
     threadLogEntry?: string;
 }): Promise<WorkspaceState>;

package/dist/core/workspace.js

@@ -3,10 +3,10 @@
 // + normalizes the per-project workspace state from disk, and provides the
 // atomic status-update primitive used by /codecarto-complete.
 import { existsSync, readFileSync } from "node:fs";
-import { appendFile, rename, writeFile } from "node:fs/promises";
+import { appendFile, readFile, rename, writeFile } from "node:fs/promises";
 import { dirname, join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
-import { acquireLock, normalizeStatus } from "./status.js";
+import { acquireLock, applyHandoff, normalizeStatus, parseHandoff } from "./status.js";
 import { pathExists } from "./utils.js";
 import { loadYamlFile, stringifySimpleYaml } from "./yaml.js";
 // Walk up from the current file to find the package root. Needed because the
@@ -42,6 +42,24 @@ export const PACKAGE_VERSION = (() => {
         return "0.0.0";
     }
 })();
+function assertCanonicalStatus(status) {
+    if (status.schema_version !== 1) {
+        throw new Error(`Cannot write unsupported status schema_version ${String(status.schema_version)}.`);
+    }
+    if (!Array.isArray(status.post_pipeline)) {
+        throw new Error("Cannot write status: post_pipeline must be an array.");
+    }
+    if (!status.phases || typeof status.phases !== "object" || Array.isArray(status.phases)) {
+        throw new Error("Cannot write status: phases must be a mapping.");
+    }
+    for (const [phaseId, phase] of Object.entries(status.phases)) {
+        for (const field of ["owner_notes", "outputs_present", "open_questions", "carry_forward"]) {
+            if (!Array.isArray(phase?.[field])) {
+                throw new Error(`Cannot write status: phases.${phaseId}.${field} must be an array.`);
+            }
+        }
+    }
+}
 export async function getWorkspaceState(cwd) {
     const workspaceDir = join(cwd, ".codecarto");
     const statusPath = join(workspaceDir, "workflow", "status.yaml");
@@ -79,13 +97,31 @@ export async function updateStatusAtomically(cwd, updater) {
         }
         const result = await updater(currentState);
         const nextState = result.state;
+        // Apply handoff if provided
+        if (result.handoff) {
+            const handoff = parseHandoff(result.handoff);
+            applyHandoff(nextState.status, handoff);
+        }
+        assertCanonicalStatus(nextState.status);
         const serialized = `${stringifySimpleYaml(nextState.status)}\n`;
         const tempPath = `${statusPath}.${process.pid}.${Date.now()}.tmp`;
         await writeFile(tempPath, serialized, "utf8");
         await rename(tempPath, statusPath);
         if (result.threadLogEntry) {
             const threadLogPath = join(workspaceDir, "THREAD_LOG.md");
-            await appendFile(threadLogPath, result.threadLogEntry, "utf8");
+            let currentLog = "";
+            try {
+                currentLog = await readFile(threadLogPath, "utf8");
+            }
+            catch {
+                // File may not exist yet
+            }
+            const logEntries = currentLog.split(/\r?\n/).filter((line) => line.trim().startsWith("- "));
+            const normalizedEntry = result.threadLogEntry.trim();
+            const isDuplicate = logEntries.some((line) => line.trim() === normalizedEntry);
+            if (!isDuplicate) {
+                await appendFile(threadLogPath, result.threadLogEntry, "utf8");
+            }
         }
         return nextState;
     }

package/dist/core/yaml.js

@@ -132,6 +132,30 @@ export function parseSimpleYaml(raw) {
             const key = trimmed.slice(0, separator).trim();
             const rawValue = trimmed.slice(separator + 1).trim();
             index++;
+            if (key in result) {
+                throw new Error(`Duplicate YAML key: ${key} near line: ${line.trim()}`);
+            }
+            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+$/, "");
+                result[key] = rawValue === "|" ? `${content}\n` : content;
+                continue;
+            }
             if (rawValue !== "") {
                 result[key] = parseYamlScalar(rawValue);
                 continue;

package/dist/extensions/codecarto/auto-runner.d.ts

@@ -1,9 +1,11 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { type PhaseActivity } from "./agent-state.ts";
-import { type PipelinePhase, type ValidationOverall, type ValidationResult, type WorkspaceState } from "../../core/index.ts";
+import { type PhasePreflightResult, type PipelinePhase, type ValidationOverall, type ValidationResult, type WorkspaceState } from "../../core/index.ts";
 export interface RunSinglePhaseOptions {
     llmSteerEnabled: boolean;
     signal?: AbortSignal;
+    /** Preflight validated by the caller so prompt construction does not repeat it. */
+    preflight?: PhasePreflightResult;
     /**
      * True when this phase is being driven by `/codecarto-next --auto`. The flag
      * propagates into `buildPhasePrompt` so interactive hooks (notably the