codecartographer-pi 0.1.0

package/core/yaml.ts

@@ -0,0 +1,256 @@
+// Hand-rolled YAML parser/serializer good enough for the .codecarto workflow
+// files (mappings, sequences, scalars, nested maps, strings/numbers/booleans).
+// Round-trips structured carry_forward/open_questions entries.
+
+import { readFile } from "node:fs/promises";
+import { isPlainObject } from "./utils.ts";
+
+export function stripYamlComment(value: string): string {
+	let inSingle = false;
+	let inDouble = false;
+
+	for (let i = 0; i < value.length; i++) {
+		const char = value[i];
+		if (char === "'" && !inDouble) {
+			inSingle = !inSingle;
+			continue;
+		}
+		if (char === '"' && !inSingle && value[i - 1] !== "\\") {
+			inDouble = !inDouble;
+			continue;
+		}
+		if (char === "#" && !inSingle && !inDouble) {
+			if (i === 0 || /\s/.test(value[i - 1] ?? "")) {
+				return value.slice(0, i).trimEnd();
+			}
+		}
+	}
+
+	return value.trimEnd();
+}
+
+function countIndent(line: string): number {
+	let count = 0;
+	for (const char of line) {
+		if (char === " ") count++;
+		else if (char === "\t") count += 2;
+		else break;
+	}
+	return count;
+}
+
+function isBlankOrComment(line: string): boolean {
+	const trimmed = line.trim();
+	return trimmed === "" || trimmed.startsWith("#");
+}
+
+function findKeySeparator(text: string): number {
+	let inSingle = false;
+	let inDouble = false;
+
+	for (let i = 0; i < text.length; i++) {
+		const char = text[i];
+		if (char === "'" && !inDouble) {
+			inSingle = !inSingle;
+			continue;
+		}
+		if (char === '"' && !inSingle && text[i - 1] !== "\\") {
+			inDouble = !inDouble;
+			continue;
+		}
+		if (char === ":" && !inSingle && !inDouble) {
+			return i;
+		}
+	}
+
+	return -1;
+}
+
+export function parseYamlScalar(rawValue: string): unknown {
+	const trimmed = stripYamlComment(rawValue).trim();
+	if (trimmed === "") return "";
+	if (trimmed === "[]") return [];
+	if (trimmed === "{}") return {};
+	if (trimmed === "null") return null;
+	if (trimmed === "true") return true;
+	if (trimmed === "false") return false;
+	if (/^-?\d+$/.test(trimmed)) return Number.parseInt(trimmed, 10);
+	if (/^-?\d+\.\d+$/.test(trimmed)) return Number.parseFloat(trimmed);
+	if (trimmed.startsWith('"') && trimmed.endsWith('"')) {
+		try {
+			return JSON.parse(trimmed);
+		} catch {
+			return trimmed.slice(1, -1);
+		}
+	}
+	if (trimmed.startsWith("'") && trimmed.endsWith("'")) {
+		return trimmed.slice(1, -1).replace(/''/g, "'");
+	}
+	return trimmed;
+}
+
+export function parseSimpleYaml(raw: string): unknown {
+	const lines = raw.split(/\r?\n/);
+	let index = 0;
+
+	const skipBlank = (): void => {
+		while (index < lines.length && isBlankOrComment(lines[index] ?? "")) index++;
+	};
+
+	const parseBlock = (indent: number): unknown => {
+		skipBlank();
+		if (index >= lines.length) return {};
+		const line = lines[index] ?? "";
+		const lineIndent = countIndent(line);
+		const trimmed = line.slice(lineIndent);
+		if (trimmed.startsWith("- ") || trimmed === "-") {
+			return parseSequence(indent);
+		}
+		return parseMapping(indent);
+	};
+
+	const parseMapping = (indent: number): Record<string, unknown> => {
+		const result: Record<string, unknown> = {};
+
+		while (index < lines.length) {
+			skipBlank();
+			if (index >= lines.length) break;
+			const line = lines[index] ?? "";
+			const lineIndent = countIndent(line);
+			if (lineIndent < indent) break;
+			if (lineIndent > indent) {
+				throw new Error(`Invalid YAML indentation near: ${line.trim()}`);
+			}
+
+			const trimmed = line.slice(indent);
+			if (trimmed.startsWith("- ") || trimmed === "-") break;
+
+			const separator = findKeySeparator(trimmed);
+			if (separator === -1) {
+				throw new Error(`Invalid YAML mapping entry: ${trimmed}`);
+			}
+
+			const key = trimmed.slice(0, separator).trim();
+			const rawValue = trimmed.slice(separator + 1).trim();
+			index++;
+
+			if (rawValue !== "") {
+				result[key] = parseYamlScalar(rawValue);
+				continue;
+			}
+
+			skipBlank();
+			if (index < lines.length && countIndent(lines[index] ?? "") > indent) {
+				result[key] = parseBlock(countIndent(lines[index] ?? ""));
+			} else {
+				result[key] = null;
+			}
+		}
+
+		return result;
+	};
+
+	const parseSequence = (indent: number): unknown[] => {
+		const result: unknown[] = [];
+
+		while (index < lines.length) {
+			skipBlank();
+			if (index >= lines.length) break;
+			const line = lines[index] ?? "";
+			const lineIndent = countIndent(line);
+			if (lineIndent < indent) break;
+			const trimmed = line.slice(lineIndent);
+			if (lineIndent !== indent || (!trimmed.startsWith("- ") && trimmed !== "-")) break;
+
+			const rawItem = trimmed === "-" ? "" : trimmed.slice(2).trim();
+			index++;
+
+			if (rawItem === "") {
+				skipBlank();
+				if (index < lines.length && countIndent(lines[index] ?? "") > indent) {
+					result.push(parseBlock(countIndent(lines[index] ?? "")));
+				} else {
+					result.push(null);
+				}
+				continue;
+			}
+
+			const separator = findKeySeparator(rawItem);
+			if (separator !== -1) {
+				const key = rawItem.slice(0, separator).trim();
+				const rawValue = rawItem.slice(separator + 1).trim();
+				const item: Record<string, unknown> = {};
+				item[key] = rawValue === "" ? null : parseYamlScalar(rawValue);
+
+				skipBlank();
+				if (rawValue === "" && index < lines.length && countIndent(lines[index] ?? "") > indent + 1) {
+					item[key] = parseBlock(countIndent(lines[index] ?? ""));
+				}
+				if (index < lines.length && countIndent(lines[index] ?? "") > indent) {
+					const nested = parseMapping(indent + 2);
+					for (const [nestedKey, nestedValue] of Object.entries(nested)) item[nestedKey] = nestedValue;
+				}
+				result.push(item);
+				continue;
+			}
+
+			result.push(parseYamlScalar(rawItem));
+		}
+
+		return result;
+	};
+
+	skipBlank();
+	if (index >= lines.length) return {};
+	return parseBlock(countIndent(lines[index] ?? ""));
+}
+
+export function formatYamlScalar(value: unknown): string {
+	if (value === null) return "null";
+	if (typeof value === "number" || typeof value === "boolean") return String(value);
+	if (Array.isArray(value)) return value.length === 0 ? "[]" : JSON.stringify(value);
+	if (isPlainObject(value)) return Object.keys(value).length === 0 ? "{}" : JSON.stringify(value);
+	const stringValue = String(value);
+	if (stringValue === "") return '""';
+	if (/^[A-Za-z0-9_./-]+$/.test(stringValue)) return stringValue;
+	return JSON.stringify(stringValue);
+}
+
+export function stringifySimpleYaml(value: unknown, indent: number = 0): string {
+	const prefix = " ".repeat(indent);
+	if (Array.isArray(value)) {
+		if (value.length === 0) return `${prefix}[]`;
+		return value
+			.map((item) => {
+				if (Array.isArray(item) || isPlainObject(item)) {
+					const isEmptyObject = isPlainObject(item) && Object.keys(item).length === 0;
+					if (Array.isArray(item) && item.length === 0) return `${prefix}- []`;
+					if (isEmptyObject) return `${prefix}- {}`;
+					return `${prefix}-\n${stringifySimpleYaml(item, indent + 2)}`;
+				}
+				return `${prefix}- ${formatYamlScalar(item)}`;
+			})
+			.join("\n");
+	}
+	if (isPlainObject(value)) {
+		const entries = Object.entries(value);
+		if (entries.length === 0) return `${prefix}{}`;
+		return entries
+			.map(([key, entryValue]) => {
+				if (Array.isArray(entryValue) || isPlainObject(entryValue)) {
+					const isEmptyObject = isPlainObject(entryValue) && Object.keys(entryValue).length === 0;
+					if (Array.isArray(entryValue) && entryValue.length === 0) return `${prefix}${key}: []`;
+					if (isEmptyObject) return `${prefix}${key}: {}`;
+					return `${prefix}${key}:\n${stringifySimpleYaml(entryValue, indent + 2)}`;
+				}
+				return `${prefix}${key}: ${formatYamlScalar(entryValue)}`;
+			})
+			.join("\n");
+	}
+	return `${prefix}${formatYamlScalar(value)}`;
+}
+
+export async function loadYamlFile<T>(path: string): Promise<T> {
+	const raw = await readFile(path, "utf8");
+	return (parseSimpleYaml(raw) ?? {}) as T;
+}

package/extensions/codecarto/index.ts

@@ -0,0 +1,446 @@
+import { cp, mkdir, rm, writeFile } from "node:fs/promises";
+import { basename, join, resolve } from "node:path";
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@mariozechner/pi-coding-agent";
+
+import {
+	buildPhasePrompt,
+	buildSkillPrompt,
+	buildThreadLogEntry,
+	buildValidationSummary,
+	canonicalPath,
+	closeoutFileName,
+	createEmptyStatus,
+	dateOnly,
+	DEFAULT_PIPELINE_PATH,
+	ensureCloseoutStub,
+	getNextEligiblePhase,
+	getPipelineLabel,
+	getWorkspaceState,
+	isWithinPath,
+	listSkillNames,
+	loadYamlFile,
+	normalizeForComparison,
+	normalizeStatus,
+	type OpenQuestionEntry,
+	packagedWorkspaceDir,
+	pathExists,
+	PIPELINE_ALIASES,
+	type PipelineFile,
+	resolvePhase,
+	resolvePipelineChoice,
+	type StatusFile,
+	stringifySimpleYaml,
+	uniqueStrings,
+	updateStatusAtomically,
+	validatePhaseOutput,
+	type WorkspaceState,
+} from "../../core/index.ts";
+
+const STATUS_WIDGET_ID = "codecarto-widget";
+const STATUS_LINE_ID = "codecarto-status";
+const SAFE_TOOL_NAMES = ["read", "grep", "find", "ls", "edit", "write"];
+
+function buildStatusLines(state: WorkspaceState, extraLines: string[] = []): string[] {
+	const nextPhase = getNextEligiblePhase(state);
+	const currentPhase = nextPhase?.id ?? state.status.current_phase ?? "complete";
+	const pipelineLabel = getPipelineLabel(state.status.pipeline);
+	const completedCount = state.pipeline.phase_order.filter((phaseId) => state.status.phases[phaseId]?.status === "complete").length;
+	const currentOpenQuestions = currentPhase === "complete" ? 0 : state.status.phases[currentPhase]?.open_questions.length ?? 0;
+	const totalCarryForward = Object.values(state.status.phases).reduce((sum, phase) => sum + (phase.carry_forward?.length ?? 0), 0);
+	const nextAction = state.status.next_actions[0] ?? (nextPhase ? `Next: ${nextPhase.id}` : "All phases complete.");
+
+	const lines = [
+		"CodeCartographer",
+		`Phase: ${currentPhase}`,
+		`Pipeline: ${pipelineLabel}`,
+		`Progress: ${completedCount}/${state.pipeline.phase_order.length} complete`,
+		`Open questions: ${currentOpenQuestions}`,
+		`Carry-forward: ${totalCarryForward}`,
+		`Next: ${nextAction}`,
+	];
+
+	if (extraLines.length > 0) {
+		lines.push("", ...extraLines);
+	}
+
+	return lines;
+}
+
+function setUiState(ctx: ExtensionContext | ExtensionCommandContext, state: WorkspaceState | null, extraLines: string[] = []): void {
+	if (!ctx.hasUI) return;
+	if (!state) {
+		ctx.ui.setStatus(STATUS_LINE_ID, undefined);
+		ctx.ui.setWidget(STATUS_WIDGET_ID, undefined);
+		return;
+	}
+
+	const theme = ctx.ui.theme;
+	const currentPhase = getNextEligiblePhase(state)?.id ?? state.status.current_phase ?? "complete";
+	ctx.ui.setStatus(STATUS_LINE_ID, `${theme.fg("accent", "CC")} ${theme.fg("dim", currentPhase)}`);
+	ctx.ui.setWidget(STATUS_WIDGET_ID, buildStatusLines(state, extraLines));
+}
+
+export default function codeCartographerExtension(pi: ExtensionAPI) {
+	let lastFeedbackLines: string[] = [];
+
+	const readWorkspaceState = async (ctx: ExtensionContext | ExtensionCommandContext, notifyOnError: boolean = true): Promise<WorkspaceState | null> => {
+		try {
+			return await getWorkspaceState(ctx.cwd);
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			lastFeedbackLines = [message];
+			setUiState(ctx, null);
+			if (notifyOnError && ctx.hasUI) ctx.ui.notify(message, "error");
+			return null;
+		}
+	};
+
+	const refreshWorkspaceUi = async (ctx: ExtensionContext | ExtensionCommandContext, extraLines?: string[]): Promise<WorkspaceState | null> => {
+		const state = await readWorkspaceState(ctx, false);
+		setUiState(ctx, state, extraLines ?? lastFeedbackLines);
+		if (state) {
+			const phaseId = getNextEligiblePhase(state)?.id ?? state.status.current_phase;
+			if (phaseId) pi.setSessionName(`CodeCartographer: ${phaseId}`);
+		}
+		return state;
+	};
+
+	const ensureWorkspaceState = async (ctx: ExtensionCommandContext): Promise<WorkspaceState | null> => {
+		const state = await readWorkspaceState(ctx);
+		if (state) return state;
+		const hasWorkspace = await pathExists(join(ctx.cwd, ".codecarto", "workflow", "status.yaml"));
+		if (!hasWorkspace) ctx.ui.notify("No .codecarto/ workspace found. Run /codecarto-init first.", "warning");
+		return null;
+	};
+
+	pi.on("session_start", async (_event, ctx) => {
+		const state = await refreshWorkspaceUi(ctx);
+		if (!state) return;
+		pi.setActiveTools(SAFE_TOOL_NAMES);
+	});
+
+	pi.on("agent_end", async (_event, ctx) => {
+		await refreshWorkspaceUi(ctx);
+	});
+
+	pi.on("tool_call", async (event, ctx) => {
+		const workspaceDir = join(ctx.cwd, ".codecarto");
+		if (!(await pathExists(workspaceDir))) return undefined;
+
+		if (event.toolName === "bash") {
+			if (ctx.hasUI) ctx.ui.notify("Blocked bash in CodeCartographer mode", "warning");
+			return { block: true, reason: "CodeCartographer mode disables bash to keep source analysis read-only." };
+		}
+
+		if (event.toolName === "edit" || event.toolName === "write") {
+			const inputPath = typeof event.input.path === "string" ? event.input.path : "";
+			const strippedPath = inputPath.startsWith("@") ? inputPath.slice(1) : inputPath;
+			const targetPath = await canonicalPath(resolve(ctx.cwd, strippedPath));
+			const allowedRoot = await canonicalPath(workspaceDir);
+			if (!isWithinPath(targetPath, allowedRoot)) {
+				if (ctx.hasUI) {
+					ctx.ui.notify(`Blocked ${event.toolName} outside .codecarto/: ${inputPath}`, "warning");
+				}
+				return { block: true, reason: `CodeCartographer mode only allows ${event.toolName} within .codecarto/` };
+			}
+		}
+
+		return undefined;
+	});
+
+	pi.registerCommand("codecarto-init", {
+		description: "Initialize .codecarto/ in the current repository",
+		getArgumentCompletions: (prefix) => {
+			const items = Object.keys(PIPELINE_ALIASES)
+				.filter((value) => value.startsWith(prefix))
+				.map((value) => ({ value, label: value }));
+			return items.length > 0 ? items : null;
+		},
+		handler: async (args, ctx) => {
+			const trimmedArgs = args.trim();
+			const pipelineChoice = resolvePipelineChoice(trimmedArgs);
+			if (trimmedArgs && !pipelineChoice) {
+				ctx.ui.notify(`Unknown pipeline: ${trimmedArgs}`, "error");
+				return;
+			}
+			const targetWorkspaceDir = join(ctx.cwd, ".codecarto");
+			const sourceWorkspaceDir = packagedWorkspaceDir;
+
+			if (!(await pathExists(sourceWorkspaceDir))) {
+				ctx.ui.notify("Packaged .codecarto assets are missing.", "error");
+				return;
+			}
+
+			const targetExists = await pathExists(targetWorkspaceDir);
+			if (targetExists) {
+				const sameWorkspace = normalizeForComparison(await canonicalPath(targetWorkspaceDir)) === normalizeForComparison(await canonicalPath(sourceWorkspaceDir));
+				if (!sameWorkspace) {
+					const overwrite = await ctx.ui.confirm(
+						"CodeCartographer already exists",
+						"A .codecarto/ directory already exists in this repository. Overwrite it?",
+					);
+					if (!overwrite) return;
+					await rm(targetWorkspaceDir, { recursive: true, force: true });
+				}
+			}
+
+			if (!(await pathExists(targetWorkspaceDir))) {
+				await mkdir(ctx.cwd, { recursive: true });
+				await cp(sourceWorkspaceDir, targetWorkspaceDir, { recursive: true });
+			}
+
+			const rawStatusPath = join(targetWorkspaceDir, "workflow", "status.yaml");
+			const rawStatus = (await loadYamlFile<StatusFile>(rawStatusPath)) ?? {};
+			const selectedPipelinePath = pipelineChoice ?? rawStatus.pipeline?.trim() ?? DEFAULT_PIPELINE_PATH;
+			const resolvedPipelinePath = join(targetWorkspaceDir, selectedPipelinePath);
+
+			if (!(await pathExists(resolvedPipelinePath))) {
+				ctx.ui.notify(`Pipeline not found: ${selectedPipelinePath}`, "error");
+				return;
+			}
+
+			const pipeline = await loadYamlFile<PipelineFile>(resolvedPipelinePath);
+			const normalizedStatus = createEmptyStatus(basename(ctx.cwd), selectedPipelinePath, pipeline);
+			normalizedStatus.last_updated = new Date().toISOString();
+			await writeFile(rawStatusPath, `${stringifySimpleYaml(normalizedStatus)}\n`, "utf8");
+
+			lastFeedbackLines = [`Initialized workspace with pipeline: ${getPipelineLabel(selectedPipelinePath)}`];
+			ctx.ui.notify(`Initialized CodeCartographer (${getPipelineLabel(selectedPipelinePath)})`, "info");
+			await ctx.reload();
+			return;
+		},
+	});
+
+	pi.registerCommand("codecarto-status", {
+		description: "Show the current CodeCartographer phase and progress",
+		handler: async (_args, ctx) => {
+			const state = await ensureWorkspaceState(ctx);
+			if (!state) return;
+
+			const nextPhase = getNextEligiblePhase(state)?.id ?? "complete";
+			lastFeedbackLines = [`Current phase: ${nextPhase}`, `Pipeline: ${getPipelineLabel(state.status.pipeline)}`];
+			setUiState(ctx, state, lastFeedbackLines);
+			ctx.ui.notify(`CodeCartographer phase: ${nextPhase}`, "info");
+		},
+	});
+
+	pi.registerCommand("codecarto-next", {
+		description: "Queue the next eligible CodeCartographer phase prompt",
+		handler: async (_args, ctx) => {
+			const state = await ensureWorkspaceState(ctx);
+			if (!state) return;
+
+			const phase = getNextEligiblePhase(state);
+			if (!phase) {
+				lastFeedbackLines = ["All phases complete."];
+				setUiState(ctx, state, lastFeedbackLines);
+				ctx.ui.notify("All CodeCartographer phases are complete.", "info");
+				return;
+			}
+
+			const prompt = await buildPhasePrompt(state, phase, false);
+			if (ctx.isIdle()) {
+				pi.sendUserMessage(prompt);
+			} else {
+				pi.sendUserMessage(prompt, { deliverAs: "followUp" });
+			}
+
+			lastFeedbackLines = [`Queued phase prompt for ${phase.id}`];
+			setUiState(ctx, state, lastFeedbackLines);
+			ctx.ui.notify(`Queued CodeCartographer phase: ${phase.id}`, "info");
+		},
+	});
+
+	pi.registerCommand("codecarto-phase", {
+		description: "Queue a specific CodeCartographer phase prompt: /codecarto-phase <phase>",
+		handler: async (args, ctx) => {
+			const phaseId = args.trim();
+			if (!phaseId) {
+				ctx.ui.notify("Usage: /codecarto-phase <phase>", "warning");
+				return;
+			}
+
+			const state = await ensureWorkspaceState(ctx);
+			if (!state) return;
+
+			const phase = resolvePhase(state, phaseId);
+			if (!phase) {
+				ctx.ui.notify(`Unknown phase: ${phaseId}`, "error");
+				return;
+			}
+
+			const prompt = await buildPhasePrompt(state, phase, true);
+			if (ctx.isIdle()) {
+				pi.sendUserMessage(prompt);
+			} else {
+				pi.sendUserMessage(prompt, { deliverAs: "followUp" });
+			}
+
+			lastFeedbackLines = [`Queued explicit phase prompt for ${phase.id}`];
+			setUiState(ctx, state, lastFeedbackLines);
+			ctx.ui.notify(`Queued CodeCartographer phase: ${phase.id}`, "info");
+		},
+	});
+
+	pi.registerCommand("codecarto-validate", {
+		description: "Validate a phase output: /codecarto-validate [phase]",
+		handler: async (args, ctx) => {
+			const state = await ensureWorkspaceState(ctx);
+			if (!state) return;
+
+			const validation = await validatePhaseOutput(state, args.trim() || undefined);
+			lastFeedbackLines = buildValidationSummary(validation);
+			setUiState(ctx, state, lastFeedbackLines);
+
+			const level = validation.overall === "FAIL" || validation.overall === "MISSING" ? "error" : validation.overall === "PASS WITH GAPS" ? "warning" : "info";
+			ctx.ui.notify(`Validation ${validation.phaseId}: ${validation.overall}`, level);
+		},
+	});
+
+	pi.registerCommand("codecarto-complete", {
+		description: "Mark a phase complete after validation passes: /codecarto-complete [phase]",
+		handler: async (args, ctx) => {
+			const currentState = await ensureWorkspaceState(ctx);
+			if (!currentState) return;
+
+			const validation = await validatePhaseOutput(currentState, args.trim() || undefined);
+			if (validation.overall === "FAIL" || validation.overall === "MISSING") {
+				lastFeedbackLines = buildValidationSummary(validation);
+				setUiState(ctx, currentState, lastFeedbackLines);
+				ctx.ui.notify(`Cannot complete ${validation.phaseId}: ${validation.overall}`, "error");
+				return;
+			}
+
+			const completionTimestamp = new Date().toISOString();
+			const updatedState = await updateStatusAtomically(ctx.cwd, (lockedState) => {
+				const phase = resolvePhase(lockedState, validation.phaseId);
+				if (!phase?.primary_output) {
+					throw new Error(`Phase ${validation.phaseId} is missing primary_output.`);
+				}
+
+				const nextStatus = normalizeStatus(lockedState.status, lockedState.pipeline, lockedState.status.pipeline, lockedState.cwd);
+				const existingPhase = nextStatus.phases[validation.phaseId] ?? {
+					status: "pending",
+					owner_notes: [],
+					outputs_present: [],
+					open_questions: [],
+					carry_forward: [],
+				};
+
+				const gapEntries: OpenQuestionEntry[] = validation.rows
+					.filter((row) => row.result.toUpperCase().includes("PARTIAL"))
+					.map((row) => ({
+						kind: "needs-maintainer-decision",
+						description: row.criterion || "Partial validation gap",
+						deferred_reason: row.evidence || "Marked PARTIAL by validation",
+					}));
+
+				const mergedOpenQuestions: OpenQuestionEntry[] = [...existingPhase.open_questions];
+				for (const candidate of gapEntries) {
+					const dupe = mergedOpenQuestions.some((entry) => entry.description === candidate.description && entry.deferred_reason === candidate.deferred_reason);
+					if (!dupe) mergedOpenQuestions.push(candidate);
+				}
+
+				nextStatus.phases[validation.phaseId] = {
+					status: "complete",
+					owner_notes: uniqueStrings([
+						...existingPhase.owner_notes,
+						`Completed via /codecarto-complete on ${completionTimestamp}.`,
+						`Primary output: .codecarto/${validation.primaryOutput}`,
+						`Validation: ${validation.overall}`,
+					]).slice(-3),
+					outputs_present: uniqueStrings([...existingPhase.outputs_present, validation.primaryOutput]),
+					open_questions: mergedOpenQuestions,
+					carry_forward: existingPhase.carry_forward ?? [],
+				};
+
+				nextStatus.last_updated = completionTimestamp;
+				const updatedWorkspaceState: WorkspaceState = {
+					...lockedState,
+					status: nextStatus,
+				};
+
+				const nextEligible = getNextEligiblePhase(updatedWorkspaceState);
+				nextStatus.current_phase = nextEligible?.id ?? "complete";
+				nextStatus.next_actions = nextEligible
+					? [
+						`Begin ${nextEligible.id} phase by producing ${nextEligible.primary_output ?? `findings/${nextEligible.id}/`}`,
+					]
+					: ["All phases complete. Review findings, open questions, and downstream implementation notes."];
+
+				return {
+					state: {
+						...updatedWorkspaceState,
+						status: nextStatus,
+					},
+					threadLogEntry: buildThreadLogEntry(validation.phaseId, validation, completionTimestamp),
+				};
+			});
+
+			let closeoutNotice: string | undefined;
+			try {
+				const created = await ensureCloseoutStub(updatedState.workspaceDir, validation.phaseId, completionTimestamp);
+				if (created) {
+					closeoutNotice = `Closeout stub: .codecarto/closeouts/${closeoutFileName(dateOnly(completionTimestamp), validation.phaseId)} (fill it in)`;
+				}
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				closeoutNotice = `Closeout stub not created: ${message}`;
+			}
+
+			lastFeedbackLines = [
+				`Completed phase: ${validation.phaseId}`,
+				`Validation: ${validation.overall}`,
+				`Next phase: ${updatedState.status.current_phase}`,
+			];
+			if (closeoutNotice) lastFeedbackLines.push(closeoutNotice);
+			setUiState(ctx, updatedState, lastFeedbackLines);
+			ctx.ui.notify(`Marked ${validation.phaseId} complete`, validation.overall === "PASS WITH GAPS" ? "warning" : "info");
+			if (closeoutNotice) ctx.ui.notify(closeoutNotice, "info");
+		},
+	});
+
+	pi.registerCommand("codecarto-skill", {
+		description: "Run a post-pipeline skill (after all phases are complete): /codecarto-skill <name>",
+		handler: async (args, ctx) => {
+			const skillName = args.trim();
+			if (!skillName) {
+				const available = await listSkillNames(join(ctx.cwd, ".codecarto"));
+				const hint = available.length > 0 ? ` (available: ${available.join(", ")})` : "";
+				ctx.ui.notify(`Usage: /codecarto-skill <name>${hint}`, "warning");
+				return;
+			}
+
+			const state = await ensureWorkspaceState(ctx);
+			if (!state) return;
+
+			const nextPhase = getNextEligiblePhase(state);
+			if (nextPhase) {
+				ctx.ui.notify(
+					`Cannot run skill: pipeline is not complete (next phase: ${nextPhase.id}). Finish the pipeline before running post-pipeline skills.`,
+					"error",
+				);
+				return;
+			}
+
+			const skillFile = join(state.workspaceDir, "skills", skillName, "SKILL.md");
+			if (!(await pathExists(skillFile))) {
+				const available = await listSkillNames(state.workspaceDir);
+				const hint = available.length > 0 ? ` (available: ${available.join(", ")})` : " (no skills installed)";
+				ctx.ui.notify(`Unknown skill: ${skillName}${hint}`, "error");
+				return;
+			}
+
+			const prompt = await buildSkillPrompt(state, skillName);
+			if (ctx.isIdle()) {
+				pi.sendUserMessage(prompt);
+			} else {
+				pi.sendUserMessage(prompt, { deliverAs: "followUp" });
+			}
+
+			lastFeedbackLines = [`Queued post-pipeline skill: ${skillName}`];
+			setUiState(ctx, state, lastFeedbackLines);
+			ctx.ui.notify(`Queued CodeCartographer skill: ${skillName}`, "info");
+		},
+	});
+}