gentle-pi 0.4.3 → 0.4.4

package/assets/orchestrator.md

@@ -181,6 +181,24 @@ proposal → design ┘
 
 `/sdd-status [change]` is the read-only status action for resolving the active change, artifact paths, task progress, dependency readiness, and action context before apply/verify/sync/archive.
 
+## Native SDD Dispatcher
+
+The user expresses intent; they should not have to administer phases manually. For natural-language SDD requests and `/sdd-continue`, the parent/orchestrator must use the native status engine as the state authority, decide the next phase, and delegate only the phase that status marks ready.
+
+Flow:
+
+```text
+user intent → preflight/init guard → native status engine → phase decision → subagent gets status JSON + generated instructions → artifact/progress write → status recalculation → continue or stop
+```
+
+Rules:
+
+- `/sdd-status` is a debug/status command, not the main UX.
+- `/sdd-continue` is the native dispatcher command: resolve status, choose the next ready phase, and carry status/instructions into the subagent prompt.
+- `sdd-apply`, `sdd-verify`, `sdd-sync`, and `sdd-archive` must obey parent-provided native status; they must not reconstruct readiness from prompt inference when status JSON is present.
+- Do not launch a phase when native status marks that dependency `blocked`.
+- `sdd-archive` cannot proceed unless native status says archive is ready.
+
 ## SDD Status Contract
 
 Before `/sdd-continue`, `sdd-apply`, `sdd-verify`, `sdd-sync`, or `sdd-archive`, resolve and carry structured status. Lookup order: parent-provided status, then project override `.pi/gentle-ai/support/sdd-status-contract.md`, then globally installed `~/.pi/agent/gentle-ai/support/sdd-status-contract.md`, then the embedded `sdd-status` prompt contract. Do not use `assets/support/...` as a runtime path; that is only the package source path before installation.

package/extensions/gentle-ai.ts

@@ -29,6 +29,15 @@ import {
 	renderSddPreflightPrompt,
 	type SddPreflightPreferences,
 } from "../lib/sdd-preflight.ts";
+import {
+	parseSddStatusCommandArgs,
+	renderNativeSddPhasePrompt,
+	renderSddDispatcherMarkdown,
+	renderSddStatusMarkdown,
+	resolveSddStatus,
+	sddStatusSeverity,
+	type SddPhase,
+} from "../lib/sdd-status.ts";
 
 const PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
 const ASSETS_DIR = join(PACKAGE_ROOT, "assets");
@@ -305,6 +314,21 @@ function isNamedAgentStartEvent(event: unknown): boolean {
 	return readAgentStartNames(event).length > 0;
 }
 
+function sddPhaseFromAgentStartEvent(event: unknown): SddPhase | undefined {
+	for (const name of readAgentStartNames(event)) {
+		if (name === "sdd-apply") return "apply";
+		if (name === "sdd-verify") return "verify";
+		if (name === "sdd-sync") return "sync";
+		if (name === "sdd-archive") return "archive";
+	}
+	const systemPrompt = readStringPath(event, ["systemPrompt"]) ?? "";
+	if (/\bSDD apply executor\b/i.test(systemPrompt)) return "apply";
+	if (/\bSDD verify executor\b/i.test(systemPrompt)) return "verify";
+	if (/\bSDD sync executor\b/i.test(systemPrompt)) return "sync";
+	if (/\bSDD archive executor\b/i.test(systemPrompt)) return "archive";
+	return undefined;
+}
+
 function evaluateDeniedCommand(
 	command: string,
 ): ToolCallEventResult | undefined {
@@ -1608,11 +1632,18 @@ export default function gentleAi(pi: ExtensionAPI): void {
 			prefs && (!isNamedAgent || isSddAgent)
 				? `\n\n${renderSddPreflightPrompt(prefs)}`
 				: "";
+		const phase = isSddAgent ? sddPhaseFromAgentStartEvent(event) : undefined;
+		const nativeStatusPrompt = phase
+			? `\n\n${renderNativeSddPhasePrompt(resolveSddStatus({
+				cwd: ctx.cwd,
+				includeInstructions: true,
+			}), phase)}`
+			: "";
 		const gentlePrompt = isNamedAgent || isSddAgent
 			? ""
 			: `\n\n${buildGentlePrompt(readPersonaMode(ctx.cwd))}`;
 		return {
-			systemPrompt: `${event.systemPrompt}${gentlePrompt}${sddPrompt}`,
+			systemPrompt: `${event.systemPrompt}${gentlePrompt}${sddPrompt}${nativeStatusPrompt}`,
 		};
 	});
 
@@ -1656,6 +1687,60 @@ export default function gentleAi(pi: ExtensionAPI): void {
 		},
 	});
 
+	const handleSddStatusCommand = (args: string, ctx: ExtensionContext) => {
+		const parsed = parseSddStatusCommandArgs(args);
+		const status = resolveSddStatus({
+			cwd: ctx.cwd,
+			changeName: parsed.changeName,
+			includeInstructions: true,
+		});
+		ctx.ui.notify(
+			parsed.json ? JSON.stringify(status, null, 2) : renderSddStatusMarkdown(status),
+			sddStatusSeverity(status),
+		);
+	};
+
+	pi.registerCommand("sdd-status", {
+		description: "Show deterministic SDD change status and instructions.",
+		handler: async (args, ctx) => {
+			handleSddStatusCommand(args, ctx);
+		},
+	});
+
+	pi.registerCommand("gentle-ai:sdd-status", {
+		description: "Compatibility alias for /sdd-status.",
+		handler: async (args, ctx) => {
+			handleSddStatusCommand(args, ctx);
+		},
+	});
+
+	const handleSddContinueCommand = (args: string, ctx: ExtensionContext) => {
+		const parsed = parseSddStatusCommandArgs(args);
+		const status = resolveSddStatus({
+			cwd: ctx.cwd,
+			changeName: parsed.changeName,
+			includeInstructions: true,
+		});
+		ctx.ui.notify(
+			parsed.json ? JSON.stringify(status, null, 2) : renderSddDispatcherMarkdown(status),
+			sddStatusSeverity(status),
+		);
+	};
+
+	pi.registerCommand("sdd-continue", {
+		description: "Resolve SDD status and route the next phase deterministically.",
+		handler: async (args, ctx) => {
+			handleSddContinueCommand(args, ctx);
+		},
+	});
+
+	pi.registerCommand("gentle-ai:sdd-continue", {
+		description: "Compatibility alias for /sdd-continue.",
+		handler: async (args, ctx) => {
+			handleSddContinueCommand(args, ctx);
+		},
+	});
+
 	pi.registerCommand("gentle:models", {
 		description: "Configure global per-agent models for el Gentleman.",
 		handler: async (_args, ctx) => {

package/lib/sdd-status.ts

@@ -0,0 +1,529 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, join, relative, resolve } from "node:path";
+import {
+	detectActiveDomainCollisions,
+	detectLegacyFlatSpec,
+	type DomainCollision,
+} from "./openspec-guardrails.ts";
+
+export type SddArtifactStore = "openspec";
+export type ArtifactState = "missing" | "done" | "partial";
+export type DependencyState = "blocked" | "ready" | "all_done" | "not_applicable";
+export type ApplyState = "blocked" | "ready" | "all_done";
+export type SddPhase = "apply" | "verify" | "sync" | "archive";
+
+export interface SddArtifactPaths {
+	proposal: string[];
+	specs: string[];
+	design: string[];
+	tasks: string[];
+	applyProgress: string[];
+	verifyReport: string[];
+	syncReport: string[];
+}
+
+export interface SddTaskProgress {
+	total: number;
+	complete: number;
+	remaining: number;
+	unchecked: string[];
+}
+
+export interface SddActionContext {
+	mode: "repo-local";
+	workspaceRoot: string;
+	allowedEditRoots: string[];
+	warnings: string[];
+}
+
+export interface SddDomainCollisionReport {
+	domain: string;
+	changes: DomainCollision[];
+}
+
+export interface SddPhaseInstructions {
+	apply: string[];
+	verify: string[];
+	sync: string[];
+	archive: string[];
+}
+
+export interface SddRelationships {
+	dependsOn: string[];
+	supersedes: string[];
+	amends: string[];
+	conflictsWith: string[];
+	sameDomainActiveChanges: SddDomainCollisionReport[];
+}
+
+export interface SddStatus {
+	schemaName: "gentle-pi.sdd-status";
+	schemaVersion: 1;
+	changeName: string | null;
+	artifactStore: SddArtifactStore;
+	planningHome: { root: string; changesDir: string };
+	changeRoot: string | null;
+	artifactPaths: SddArtifactPaths;
+	contextFiles: SddArtifactPaths;
+	artifacts: Record<keyof SddArtifactPaths, ArtifactState>;
+	taskProgress: SddTaskProgress;
+	applyState: ApplyState;
+	dependencies: Record<SddPhase, DependencyState>;
+	actionContext: SddActionContext;
+	relationships: SddRelationships;
+	collisions: SddDomainCollisionReport[];
+	legacyFlatSpec?: { path: string; hasDomainSpecs: boolean };
+	nextRecommended: string;
+	instructions?: SddPhaseInstructions;
+	blockedReasons: string[];
+}
+
+export interface ResolveSddStatusOptions {
+	cwd: string;
+	changeName?: string;
+	includeInstructions?: boolean;
+	workspaceRoot?: string;
+}
+
+const EMPTY_PATHS: SddArtifactPaths = {
+	proposal: [],
+	specs: [],
+	design: [],
+	tasks: [],
+	applyProgress: [],
+	verifyReport: [],
+	syncReport: [],
+};
+
+function safeDirectories(path: string): string[] {
+	try {
+		return readdirSync(path)
+			.filter((entry) => {
+				try {
+					return statSync(join(path, entry)).isDirectory();
+				} catch {
+					return false;
+				}
+			})
+			.sort();
+	} catch {
+		return [];
+	}
+}
+
+function safeRead(path: string): string {
+	try {
+		return readFileSync(path, "utf8");
+	} catch {
+		return "";
+	}
+}
+
+function hasContent(path: string): boolean {
+	return existsSync(path) && safeRead(path).trim().length > 0;
+}
+
+function singleFileState(paths: string[]): ArtifactState {
+	if (paths.length === 0) return "missing";
+	return paths.some((path) => !hasContent(path)) ? "partial" : "done";
+}
+
+function multiFileState(paths: string[], partial = false): ArtifactState {
+	if (paths.length === 0) return partial ? "partial" : "missing";
+	return paths.some((path) => !hasContent(path)) || partial ? "partial" : "done";
+}
+
+function findSpecFiles(specsDir: string): string[] {
+	const files: string[] = [];
+	function walk(dir: string): void {
+		for (const entry of safeDirectories(dir)) {
+			const path = join(dir, entry);
+			const specPath = join(path, "spec.md");
+			if (existsSync(specPath)) files.push(specPath);
+			walk(path);
+		}
+	}
+	walk(specsDir);
+	return files.sort();
+}
+
+function domainFromSpecPath(changeRoot: string, specPath: string): string | undefined {
+	const rel = relative(join(changeRoot, "specs"), specPath).split(/[\\/]/);
+	return rel.length >= 2 && rel.at(-1) === "spec.md" ? rel.slice(0, -1).join("/") : undefined;
+}
+
+function countTasks(tasksPath: string | undefined): SddTaskProgress {
+	if (!tasksPath || !existsSync(tasksPath)) {
+		return { total: 0, complete: 0, remaining: 0, unchecked: [] };
+	}
+	const unchecked: string[] = [];
+	let complete = 0;
+	for (const rawLine of safeRead(tasksPath).split(/\r?\n/)) {
+		const line = rawLine.trimEnd();
+		if (/^\s*- \[[xX]\]/.test(line)) complete += 1;
+		if (/^\s*- \[ \]/.test(line)) unchecked.push(line.trim());
+	}
+	return {
+		total: complete + unchecked.length,
+		complete,
+		remaining: unchecked.length,
+		unchecked,
+	};
+}
+
+function reportIsClearlyPassing(path: string | undefined): boolean {
+	if (!path || !hasContent(path)) return false;
+	const text = safeRead(path);
+	const hasBlocker = /(^|\b)(FAIL|FAILED|BLOCKED|CRITICAL|PENDING|TODO)(\b|:)|verification blockers?|not\s+(?:pass|passed|passing|successful|complete|completed)|(?:pass|passed|success|successful|complete|completed)\s*:\s*no\b/i.test(text);
+	const hasPassSignal = text
+		.split(/\r?\n/)
+		.map((line) => line.trim())
+		.some((line) =>
+			/^(?:(?:status|verdict|result|verification|sync|final(?:\s+verdict)?)\s*:\s*)?(?:PASS|PASSED|SUCCESS|SUCCESSFUL)$/i.test(line) ||
+			/^all checks passed\.?$/i.test(line) ||
+			/^ready for archive\.?$/i.test(line) ||
+			/^sync completed?\.?$/i.test(line),
+		);
+	return hasPassSignal && !hasBlocker;
+}
+
+function emptyStatus(cwd: string, changeName: string | null, blockedReasons: string[]): SddStatus {
+	const root = resolve(cwd);
+	const changesDir = join(root, "openspec", "changes");
+	const actionContext: SddActionContext = {
+		mode: "repo-local",
+		workspaceRoot: root,
+		allowedEditRoots: [root],
+		warnings: [],
+	};
+	return {
+		schemaName: "gentle-pi.sdd-status",
+		schemaVersion: 1,
+		changeName,
+		artifactStore: "openspec",
+		planningHome: { root, changesDir },
+		changeRoot: null,
+		artifactPaths: { ...EMPTY_PATHS },
+		contextFiles: { ...EMPTY_PATHS },
+		artifacts: {
+			proposal: "missing",
+			specs: "missing",
+			design: "missing",
+			tasks: "missing",
+			applyProgress: "missing",
+			verifyReport: "missing",
+			syncReport: "missing",
+		},
+		taskProgress: { total: 0, complete: 0, remaining: 0, unchecked: [] },
+		applyState: "blocked",
+		dependencies: { apply: "blocked", verify: "blocked", sync: "blocked", archive: "blocked" },
+		actionContext,
+		relationships: {
+			dependsOn: [],
+			supersedes: [],
+			amends: [],
+			conflictsWith: [],
+			sameDomainActiveChanges: [],
+		},
+		collisions: [],
+		nextRecommended: blockedReasons[0] ?? "Start an SDD change.",
+		blockedReasons,
+	};
+}
+
+export function listActiveOpenSpecChanges(cwd: string): string[] {
+	return safeDirectories(join(cwd, "openspec", "changes")).filter(
+		(change) => change !== "archive",
+	);
+}
+
+export function renderPhaseInstructions(status: SddStatus): SddPhaseInstructions {
+	const change = status.changeName ?? "<unresolved>";
+	return {
+		apply: [
+			`Change: ${change}`,
+			`State: ${status.dependencies.apply}`,
+			status.applyState === "all_done"
+				? "All tasks are already checked complete; do not edit."
+				: "Implement only unchecked tasks from the tasks artifact.",
+			`Tasks: ${status.taskProgress.complete}/${status.taskProgress.total} complete`,
+			"Update persisted task checkboxes immediately after completing each task.",
+			...status.taskProgress.unchecked.map((line) => `Remaining: ${line}`),
+		],
+		verify: [
+			`Change: ${change}`,
+			`State: ${status.dependencies.verify}`,
+			"Verify task completion, spec coverage, implementation correctness, design coherence, and tests when available.",
+			"Unchecked implementation tasks are CRITICAL archive blockers.",
+			...status.taskProgress.unchecked.map((line) => `Unchecked blocker: ${line}`),
+		],
+		sync: [
+			`Change: ${change}`,
+			`State: ${status.dependencies.sync}`,
+			"Sync delta specs into openspec/specs only after verification is clean.",
+			...status.artifactPaths.specs.map((path) => `Delta spec: ${path}`),
+			...status.collisions.flatMap((collision) =>
+				collision.changes.map((item) =>
+					`Same-domain collision: ${collision.domain} also touched by ${item.change} (${item.path})`,
+				),
+			),
+		],
+		archive: [
+			`Change: ${change}`,
+			`State: ${status.dependencies.archive}`,
+			"Archive only after clean verify, completed sync, and zero unchecked implementation tasks.",
+			"CRITICAL verification issues have no override.",
+			status.changeRoot
+				? `Archive target: ${join(status.planningHome.changesDir, "archive", `YYYY-MM-DD-${change}`)}`
+				: "Archive target unavailable until change is resolved.",
+		],
+	};
+}
+
+export function resolveSddStatus(options: ResolveSddStatusOptions): SddStatus {
+	const root = resolve(options.cwd);
+	const changesDir = join(root, "openspec", "changes");
+	const activeChanges = listActiveOpenSpecChanges(root);
+	let changeName = options.changeName?.trim() || "";
+	const blockedReasons: string[] = [];
+
+	if (!changeName) {
+		if (activeChanges.length === 1) {
+			changeName = activeChanges[0];
+		} else if (activeChanges.length === 0) {
+			return emptyStatus(root, null, ["No active SDD changes found."]);
+		} else {
+			return emptyStatus(root, null, [
+				`Change selection is ambiguous: ${activeChanges.join(", ")}.`,
+			]);
+		}
+	}
+
+	if (!activeChanges.includes(changeName)) {
+		return emptyStatus(root, changeName, [`Active change not found: ${changeName}.`]);
+	}
+
+	const changeRoot = join(changesDir, changeName);
+	const proposal = join(changeRoot, "proposal.md");
+	const design = join(changeRoot, "design.md");
+	const tasks = join(changeRoot, "tasks.md");
+	const applyProgress = join(changeRoot, "apply-progress.md");
+	const verifyReport = join(changeRoot, "verify-report.md");
+	const syncReport = join(changeRoot, "sync-report.md");
+	const specFiles = findSpecFiles(join(changeRoot, "specs"));
+	const legacyFlatSpec = detectLegacyFlatSpec(root, changeName);
+	const flatOnly = Boolean(legacyFlatSpec && specFiles.length === 0);
+
+	const artifactPaths: SddArtifactPaths = {
+		proposal: existsSync(proposal) ? [proposal] : [],
+		specs: specFiles,
+		design: existsSync(design) ? [design] : [],
+		tasks: existsSync(tasks) ? [tasks] : [],
+		applyProgress: existsSync(applyProgress) ? [applyProgress] : [],
+		verifyReport: existsSync(verifyReport) ? [verifyReport] : [],
+		syncReport: existsSync(syncReport) ? [syncReport] : [],
+	};
+	const artifacts = {
+		proposal: singleFileState(artifactPaths.proposal),
+		specs: multiFileState(artifactPaths.specs, flatOnly),
+		design: singleFileState(artifactPaths.design),
+		tasks: singleFileState(artifactPaths.tasks),
+		applyProgress: singleFileState(artifactPaths.applyProgress),
+		verifyReport: singleFileState(artifactPaths.verifyReport),
+		syncReport: singleFileState(artifactPaths.syncReport),
+	} satisfies SddStatus["artifacts"];
+	const taskProgress = countTasks(artifactPaths.tasks[0]);
+	const actionContext: SddActionContext = {
+		mode: "repo-local",
+		workspaceRoot: options.workspaceRoot ? resolve(options.workspaceRoot) : root,
+		allowedEditRoots: [options.workspaceRoot ? resolve(options.workspaceRoot) : root],
+		warnings: [],
+	};
+
+	const collisions = specFiles
+		.map((path) => domainFromSpecPath(changeRoot, path))
+		.filter((domain): domain is string => Boolean(domain))
+		.map((domain) => ({
+			domain,
+			changes: detectActiveDomainCollisions(root, changeName, domain).sort((a, b) =>
+				a.change.localeCompare(b.change),
+			),
+		}))
+		.filter((collision) => collision.changes.length > 0);
+
+	if (artifacts.proposal === "missing") blockedReasons.push("proposal.md is missing.");
+	if (artifacts.proposal === "partial") blockedReasons.push("proposal.md is empty or partial.");
+	if (artifacts.specs !== "done") blockedReasons.push("domain specs are missing or partial.");
+	if (artifacts.design === "missing") blockedReasons.push("design.md is missing.");
+	if (artifacts.design === "partial") blockedReasons.push("design.md is empty or partial.");
+	if (artifacts.tasks === "missing") blockedReasons.push("tasks.md is missing.");
+	if (artifacts.tasks === "partial") blockedReasons.push("tasks.md is empty or partial.");
+	if (artifacts.tasks === "done" && taskProgress.total === 0) {
+		blockedReasons.push("tasks.md has no implementation task checkboxes.");
+	}
+	if (flatOnly && legacyFlatSpec) {
+		blockedReasons.push(`Legacy flat spec is present without domain specs: ${legacyFlatSpec.path}.`);
+	}
+
+	const coreArtifactsReady = artifacts.proposal === "done" && artifacts.specs === "done" && artifacts.design === "done" && artifacts.tasks === "done" && taskProgress.total > 0 && !flatOnly;
+	const applyState: ApplyState = !coreArtifactsReady
+		? "blocked"
+		: taskProgress.remaining === 0
+			? "all_done"
+			: "ready";
+	const verifyClean = reportIsClearlyPassing(artifactPaths.verifyReport[0]);
+	const syncClean = reportIsClearlyPassing(artifactPaths.syncReport[0]);
+	const syncPrerequisitesReady = coreArtifactsReady && verifyClean && collisions.length === 0 && !flatOnly;
+	const syncState: DependencyState = syncPrerequisitesReady
+		? syncClean
+			? "all_done"
+			: "ready"
+		: "blocked";
+	const verifyState: DependencyState = verifyClean
+		? "all_done"
+		: artifacts.tasks === "done" && taskProgress.total > 0 && (artifacts.applyProgress === "done" || applyState === "all_done")
+			? "ready"
+			: "blocked";
+	const dependencies: SddStatus["dependencies"] = {
+		apply: applyState === "blocked" ? "blocked" : applyState,
+		verify: verifyState,
+		sync: syncState,
+		archive: coreArtifactsReady && verifyClean && syncClean && taskProgress.remaining === 0 ? "ready" : "blocked",
+	};
+	const archiveReady = dependencies.archive === "ready";
+	const nextRecommended = dependencies.apply === "ready"
+		? "sdd-apply"
+		: dependencies.verify === "ready"
+			? "sdd-verify"
+			: dependencies.sync === "ready"
+				? "sdd-sync"
+				: archiveReady
+					? "sdd-archive"
+					: blockedReasons[0] ?? "Resolve blockers.";
+
+	const status: SddStatus = {
+		schemaName: "gentle-pi.sdd-status",
+		schemaVersion: 1,
+		changeName,
+		artifactStore: "openspec",
+		planningHome: { root, changesDir },
+		changeRoot,
+		artifactPaths,
+		contextFiles: artifactPaths,
+		artifacts,
+		taskProgress,
+		applyState,
+		dependencies,
+		actionContext,
+		relationships: {
+			dependsOn: [],
+			supersedes: [],
+			amends: [],
+			conflictsWith: [],
+			sameDomainActiveChanges: collisions,
+		},
+		collisions,
+		legacyFlatSpec: legacyFlatSpec
+			? { path: legacyFlatSpec.path, hasDomainSpecs: specFiles.length > 0 }
+			: undefined,
+		nextRecommended,
+		blockedReasons,
+	};
+	if (options.includeInstructions) status.instructions = renderPhaseInstructions(status);
+	return status;
+}
+
+export function renderNativeSddPhasePrompt(status: SddStatus, phase?: SddPhase): string {
+	const selectedInstructions = phase ? status.instructions?.[phase] : undefined;
+	return [
+		"## Native SDD Status Engine",
+		"The parent/orchestrator resolved this status deterministically. Treat it as authoritative over prompt inference.",
+		"Do not run phase work when this status marks the phase blocked; return the blockers instead.",
+		...(phase && selectedInstructions
+			? ["", `### ${phase} instructions`, ...selectedInstructions.map((line) => `- ${line}`)]
+			: []),
+		"",
+		"```json",
+		JSON.stringify(status, null, 2),
+		"```",
+	].join("\n");
+}
+
+export function renderSddDispatcherMarkdown(status: SddStatus): string {
+	return [
+		`## Native SDD Dispatcher: ${status.changeName ?? "unresolved"}`,
+		"",
+		`nextPhase: ${status.nextRecommended}`,
+		`apply: ${status.dependencies.apply}`,
+		`verify: ${status.dependencies.verify}`,
+		`sync: ${status.dependencies.sync}`,
+		`archive: ${status.dependencies.archive}`,
+		"",
+		status.blockedReasons.length > 0
+			? ["### Blocked", ...status.blockedReasons.map((reason) => `- ${reason}`)].join("\n")
+			: "### Ready\nThe next phase may be delegated with the attached status JSON and phase instructions.",
+		"",
+		"### Instructions for next phase",
+		...((status.instructions?.[status.nextRecommended.replace(/^sdd-/, "") as SddPhase] ?? [])
+			.map((line) => `- ${line}`)),
+		"",
+		"### Status JSON",
+		"```json",
+		JSON.stringify(status, null, 2),
+		"```",
+	].join("\n");
+}
+
+export function renderSddStatusMarkdown(status: SddStatus): string {
+	const title = status.changeName ?? "unresolved";
+	const lines = [
+		`## SDD Status: ${title}`,
+		"",
+		`schema: ${status.schemaName}@${status.schemaVersion}`,
+		`store: ${status.artifactStore}`,
+		`root: ${status.planningHome.root}`,
+		`next: ${status.nextRecommended}`,
+		"",
+		"### Tasks",
+		`- complete: ${status.taskProgress.complete}/${status.taskProgress.total}`,
+		`- remaining: ${status.taskProgress.remaining}`,
+		...status.taskProgress.unchecked.map((line) => `- unchecked: ${line}`),
+		"",
+		"### Dependencies",
+		...Object.entries(status.dependencies).map(([phase, state]) => `- ${phase}: ${state}`),
+	];
+	if (status.collisions.length > 0) {
+		lines.push("", "### Same-domain active changes");
+		for (const collision of status.collisions) {
+			lines.push(
+				`- ${collision.domain}: ${collision.changes.map((item) => item.change).join(", ")}`,
+			);
+		}
+	}
+	if (status.blockedReasons.length > 0) {
+		lines.push("", "### Blockers", ...status.blockedReasons.map((reason) => `- ${reason}`));
+	}
+	lines.push("", "### JSON", "```json", JSON.stringify(status, null, 2), "```");
+	return lines.join("\n");
+}
+
+export function parseSddStatusCommandArgs(args: string): { changeName?: string; json: boolean } {
+	const parts = args.trim().split(/\s+/).filter(Boolean);
+	const json = parts.includes("--json");
+	const changeName = parts.find((part) => part !== "--json");
+	return { changeName, json };
+}
+
+export function sddStatusSeverity(status: SddStatus): "info" | "warning" {
+	return status.blockedReasons.length > 0 || Object.values(status.dependencies).includes("blocked")
+		? "warning"
+		: "info";
+}
+
+export function summarizeSddStatusForTitle(status: SddStatus): string {
+	return `${status.changeName ?? "unresolved"}: ${status.nextRecommended} (${status.taskProgress.complete}/${status.taskProgress.total} tasks)`;
+}
+
+export function activeChangeLabel(cwd: string): string {
+	return basename(resolve(cwd));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gentle-pi",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "description": "Turn Pi into el Gentleman: a senior-architect development harness with SDD/OpenSpec, subagents, strict TDD evidence, review guardrails, and skill discovery.",
   "license": "MIT",
   "type": "module",

package/tests/runtime-harness.mjs

@@ -31,6 +31,10 @@ const EXPECTED_COMMANDS = [
 	"gentle-ai:install-sdd",
 	"gentle-ai:sdd-preflight",
 	"gentle:sdd-preflight",
+	"sdd-status",
+	"gentle-ai:sdd-status",
+	"sdd-continue",
+	"gentle-ai:sdd-continue",
 	"gentle:models",
 	"gentle-ai:models",
 	"gentleman:models",
@@ -246,6 +250,25 @@ async function run() {
 		assert.match(onboardPromptResult.systemPrompt, /onboard base/);
 		assert.match(onboardPromptResult.systemPrompt, /## SDD Session Preflight/);
 		assert.equal(existsSync(join(globalAgentHome, "agents", "sdd-onboard.md")), true);
+		await mkdir(join(promptCwd, "openspec", "changes", "status-demo", "specs", "demo"), { recursive: true });
+		await writeFile(join(promptCwd, "openspec", "changes", "status-demo", "proposal.md"), "# Proposal\n");
+		await writeFile(join(promptCwd, "openspec", "changes", "status-demo", "specs", "demo", "spec.md"), "# Spec\n");
+		await writeFile(join(promptCwd, "openspec", "changes", "status-demo", "design.md"), "# Design\n");
+		await writeFile(join(promptCwd, "openspec", "changes", "status-demo", "tasks.md"), "# Tasks\n\n- [ ] 1.1 Implement demo\n");
+		const applyPromptResult = await promptHook(
+			{ agentName: "sdd-apply", systemPrompt: "apply base" },
+			createCtx(promptCwd, true, "sdd-apply-session"),
+		);
+		assert.match(applyPromptResult.systemPrompt, /## Native SDD Status Engine/);
+		assert.match(applyPromptResult.systemPrompt, /"changeName": "status-demo"/);
+		assert.match(applyPromptResult.systemPrompt, /### apply instructions/);
+		const statusCtx = createCtx(promptCwd, true);
+		await commands.get("sdd-status").handler("status-demo --json", statusCtx);
+		assert.match(statusCtx.ui.notifications.at(-1).message, /"schemaName": "gentle-pi\.sdd-status"/);
+		const continueCtx = createCtx(promptCwd, true);
+		await commands.get("sdd-continue").handler("status-demo", continueCtx);
+		assert.match(continueCtx.ui.notifications.at(-1).message, /Native SDD Dispatcher/);
+		assert.match(continueCtx.ui.notifications.at(-1).message, /nextPhase: sdd-apply/);
 	} finally {
 		await rm(promptCwd, { recursive: true, force: true });
 	}

package/tests/sdd-status.test.ts

@@ -0,0 +1,291 @@
+import assert from "node:assert/strict";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import test from "node:test";
+import {
+	listActiveOpenSpecChanges,
+	parseSddStatusCommandArgs,
+	renderPhaseInstructions,
+	renderSddStatusMarkdown,
+	resolveSddStatus,
+} from "../lib/sdd-status.ts";
+
+async function workspace(): Promise<string> {
+	return mkdtemp(join(tmpdir(), "gentle-pi-sdd-status-"));
+}
+
+function write(path: string, content: string): void {
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, content);
+}
+
+function seedChange(cwd: string, change = "add-auth"): string {
+	const root = join(cwd, "openspec", "changes", change);
+	write(join(root, "proposal.md"), "# Proposal\n");
+	write(join(root, "specs", "auth", "spec.md"), "# Auth Spec\n");
+	write(join(root, "design.md"), "# Design\n");
+	write(
+		join(root, "tasks.md"),
+		`# Tasks
+
+- [x] 1.1 Build foundation
+- [ ] 1.2 Wire routes
+`,
+	);
+	return root;
+}
+
+test("listActiveOpenSpecChanges excludes archive and sorts active changes", async () => {
+	const cwd = await workspace();
+	mkdirSync(join(cwd, "openspec", "changes", "b-change"), { recursive: true });
+	mkdirSync(join(cwd, "openspec", "changes", "a-change"), { recursive: true });
+	mkdirSync(join(cwd, "openspec", "changes", "archive", "2026-01-01-old"), { recursive: true });
+
+	assert.deepEqual(listActiveOpenSpecChanges(cwd), ["a-change", "b-change"]);
+});
+
+test("resolveSddStatus blocks when there are no active changes", async () => {
+	const cwd = await workspace();
+	mkdirSync(join(cwd, "openspec", "changes"), { recursive: true });
+
+	const status = resolveSddStatus({ cwd });
+
+	assert.equal(status.changeName, null);
+	assert.match(status.blockedReasons[0], /No active SDD changes/);
+	assert.equal(status.dependencies.apply, "blocked");
+});
+
+test("resolveSddStatus blocks when change selection is ambiguous", async () => {
+	const cwd = await workspace();
+	mkdirSync(join(cwd, "openspec", "changes", "first"), { recursive: true });
+	mkdirSync(join(cwd, "openspec", "changes", "second"), { recursive: true });
+
+	const status = resolveSddStatus({ cwd });
+
+	assert.equal(status.changeName, null);
+	assert.match(status.blockedReasons[0], /ambiguous/);
+});
+
+test("resolveSddStatus selects the only active change and counts task progress", async () => {
+	const cwd = await workspace();
+	const root = seedChange(cwd);
+
+	const status = resolveSddStatus({ cwd, includeInstructions: true });
+
+	assert.equal(status.changeName, "add-auth");
+	assert.equal(status.changeRoot, root);
+	assert.equal(status.artifacts.proposal, "done");
+	assert.equal(status.artifacts.specs, "done");
+	assert.deepEqual(status.taskProgress, {
+		total: 2,
+		complete: 1,
+		remaining: 1,
+		unchecked: ["- [ ] 1.2 Wire routes"],
+	});
+	assert.equal(status.applyState, "ready");
+	assert.equal(status.dependencies.apply, "ready");
+	assert.match(status.instructions?.apply.join("\n") ?? "", /persisted task checkboxes/);
+});
+
+test("resolveSddStatus marks apply all_done and verify ready when tasks are checked", async () => {
+	const cwd = await workspace();
+	const root = seedChange(cwd);
+	write(join(root, "tasks.md"), "# Tasks\n\n- [x] 1.1 Build foundation\n");
+
+	const status = resolveSddStatus({ cwd, changeName: "add-auth" });
+
+	assert.equal(status.applyState, "all_done");
+	assert.equal(status.dependencies.apply, "all_done");
+	assert.equal(status.dependencies.verify, "ready");
+});
+
+test("resolveSddStatus blocks sync when verify report is not clearly passing", async () => {
+	const cwd = await workspace();
+	const root = seedChange(cwd);
+	write(join(root, "apply-progress.md"), "# Apply\n\nSome work completed.\n");
+	write(join(root, "verify-report.md"), "# Verify\n\nTODO: tests not run yet\n");
+
+	const status = resolveSddStatus({ cwd, changeName: "add-auth" });
+
+	assert.equal(status.dependencies.verify, "ready");
+	assert.equal(status.dependencies.sync, "blocked");
+	assert.equal(status.dependencies.archive, "blocked");
+});
+
+test("resolveSddStatus rejects negated pass and sync-complete phrases", async () => {
+	const cwd = await workspace();
+	const root = seedChange(cwd);
+	write(join(root, "tasks.md"), "# Tasks\n\n- [x] 1.1 Done\n");
+	write(join(root, "verify-report.md"), "# Verify\n\nStatus: not passed\n");
+	write(join(root, "sync-report.md"), "# Sync\n\nSync complete: no\n");
+
+	const status = resolveSddStatus({ cwd, changeName: "add-auth" });
+
+	assert.equal(status.dependencies.verify, "ready");
+	assert.equal(status.dependencies.sync, "blocked");
+	assert.equal(status.dependencies.archive, "blocked");
+	assert.notEqual(status.nextRecommended, "sdd-archive");
+});
+
+test("resolveSddStatus blocks sync when verify report contains critical text", async () => {
+	const cwd = await workspace();
+	const root = seedChange(cwd);
+	write(join(root, "verify-report.md"), "# Verify\n\nCRITICAL: missing tests\n");
+
+	const status = resolveSddStatus({ cwd, changeName: "add-auth" });
+
+	assert.equal(status.dependencies.sync, "blocked");
+	assert.equal(status.dependencies.archive, "blocked");
+});
+
+test("resolveSddStatus reports same-domain collisions", async () => {
+	const cwd = await workspace();
+	const root = seedChange(cwd, "current");
+	write(join(root, "tasks.md"), "# Tasks\n\n- [x] 1.1 Done\n");
+	write(join(root, "verify-report.md"), "# Verify\n\nPASS\n");
+	write(join(cwd, "openspec", "changes", "other", "specs", "auth", "spec.md"), "# Other\n");
+
+	const status = resolveSddStatus({ cwd, changeName: "current" });
+
+	assert.deepEqual(status.collisions.map((collision) => collision.domain), ["auth"]);
+	assert.equal(status.collisions[0].changes[0].change, "other");
+	assert.equal(status.dependencies.sync, "blocked");
+});
+
+test("resolveSddStatus blocks apply when tasks has no checkboxes", async () => {
+	const cwd = await workspace();
+	const root = seedChange(cwd);
+	write(join(root, "tasks.md"), "# Tasks\n\nImplementation notes only.\n");
+
+	const status = resolveSddStatus({ cwd, changeName: "add-auth" });
+
+	assert.equal(status.taskProgress.total, 0);
+	assert.equal(status.applyState, "blocked");
+	assert.equal(status.dependencies.apply, "blocked");
+	assert.match(status.blockedReasons.join("\n"), /no implementation task checkboxes/);
+});
+
+test("resolveSddStatus marks legacy flat specs partial and blocks sync", async () => {
+	const cwd = await workspace();
+	write(join(cwd, "openspec", "changes", "legacy", "proposal.md"), "# Proposal\n");
+	write(join(cwd, "openspec", "changes", "legacy", "spec.md"), "# Flat\n");
+	write(join(cwd, "openspec", "changes", "legacy", "design.md"), "# Design\n");
+	write(join(cwd, "openspec", "changes", "legacy", "tasks.md"), "# Tasks\n\n- [x] 1.1 Done\n");
+	write(join(cwd, "openspec", "changes", "legacy", "verify-report.md"), "# Verify\n\nPASS\n");
+
+	const status = resolveSddStatus({ cwd, changeName: "legacy" });
+
+	assert.equal(status.artifacts.specs, "partial");
+	assert.match(status.blockedReasons.join("\n"), /Legacy flat spec/);
+	assert.equal(status.dependencies.sync, "blocked");
+});
+
+test("resolveSddStatus accepts nested domain specs even when a legacy flat spec also exists", async () => {
+	const cwd = await workspace();
+	write(join(cwd, "openspec", "changes", "mixed", "proposal.md"), "# Proposal\n");
+	write(join(cwd, "openspec", "changes", "mixed", "spec.md"), "# Flat\n");
+	write(join(cwd, "openspec", "changes", "mixed", "specs", "parent", "child", "spec.md"), "# Nested\n");
+	write(join(cwd, "openspec", "changes", "mixed", "design.md"), "# Design\n");
+	write(join(cwd, "openspec", "changes", "mixed", "tasks.md"), "# Tasks\n\n- [x] 1.1 Done\n");
+
+	const status = resolveSddStatus({ cwd, changeName: "mixed" });
+
+	assert.equal(status.artifacts.specs, "done");
+	assert.equal(status.legacyFlatSpec?.hasDomainSpecs, true);
+	assert.doesNotMatch(status.blockedReasons.join("\n"), /Legacy flat spec/);
+});
+
+test("resolveSddStatus blocks sync when core artifacts are missing even with clean verify", async () => {
+	const cwd = await workspace();
+	write(join(cwd, "openspec", "changes", "thin", "proposal.md"), "# Proposal\n");
+	write(join(cwd, "openspec", "changes", "thin", "design.md"), "# Design\n");
+	write(join(cwd, "openspec", "changes", "thin", "tasks.md"), "# Tasks\n\n- [x] 1.1 Done\n");
+	write(join(cwd, "openspec", "changes", "thin", "verify-report.md"), "# Verify\n\nPASS\n");
+
+	const status = resolveSddStatus({ cwd, changeName: "thin" });
+
+	assert.match(status.blockedReasons.join("\n"), /domain specs are missing or partial/);
+	assert.equal(status.dependencies.sync, "blocked");
+	assert.notEqual(status.nextRecommended, "sdd-sync");
+});
+
+test("resolveSddStatus blocks stale sync report when current verify is not passing", async () => {
+	const cwd = await workspace();
+	const root = seedChange(cwd);
+	write(join(root, "tasks.md"), "# Tasks\n\n- [x] 1.1 Done\n");
+	write(join(root, "verify-report.md"), "# Verify\n\nStatus: not passed\n");
+	write(join(root, "sync-report.md"), "# Sync\n\nPASS\n");
+
+	const status = resolveSddStatus({ cwd, changeName: "add-auth" });
+
+	assert.equal(status.dependencies.verify, "ready");
+	assert.equal(status.dependencies.sync, "blocked");
+	assert.equal(status.dependencies.archive, "blocked");
+	assert.notEqual(status.nextRecommended, "sdd-archive");
+});
+
+test("resolveSddStatus blocks archive when required artifacts are missing", async () => {
+	const cwd = await workspace();
+	write(join(cwd, "openspec", "changes", "thin", "tasks.md"), "# Tasks\n\n- [x] 1.1 Done\n");
+	write(join(cwd, "openspec", "changes", "thin", "verify-report.md"), "# Verify\n\nPASS\n");
+	write(join(cwd, "openspec", "changes", "thin", "sync-report.md"), "# Sync\n\nPASS\n");
+
+	const status = resolveSddStatus({ cwd, changeName: "thin" });
+
+	assert.match(status.blockedReasons.join("\n"), /proposal\.md is missing/);
+	assert.equal(status.dependencies.archive, "blocked");
+	assert.notEqual(status.nextRecommended, "sdd-archive");
+});
+
+test("resolveSddStatus reports partial core artifacts as blockers", async () => {
+	const cwd = await workspace();
+	const root = seedChange(cwd);
+	write(join(root, "proposal.md"), "");
+	write(join(root, "tasks.md"), "# Tasks\n\n- [x] 1.1 Done\n");
+	write(join(root, "verify-report.md"), "# Verify\n\nPASS\n");
+	write(join(root, "sync-report.md"), "# Sync\n\nPASS\n");
+
+	const status = resolveSddStatus({ cwd, changeName: "add-auth" });
+
+	assert.equal(status.artifacts.proposal, "partial");
+	assert.match(status.blockedReasons.join("\n"), /proposal\.md is empty or partial/);
+	assert.equal(status.dependencies.archive, "blocked");
+});
+
+test("resolveSddStatus marks archive ready only after clean verify, sync, and complete tasks", async () => {
+	const cwd = await workspace();
+	const root = seedChange(cwd);
+	write(join(root, "tasks.md"), "# Tasks\n\n- [x] 1.1 Done\n");
+	write(join(root, "verify-report.md"), "# Verify\n\nPASS\n");
+	write(join(root, "sync-report.md"), "# Sync\n\nPASS\n");
+
+	const status = resolveSddStatus({ cwd, changeName: "add-auth" });
+
+	assert.equal(status.dependencies.archive, "ready");
+	assert.equal(status.nextRecommended, "sdd-archive");
+	assert.match(renderPhaseInstructions(status).archive.join("\n"), /CRITICAL verification issues have no override/);
+});
+
+test("renderSddStatusMarkdown includes structured JSON", async () => {
+	const cwd = await workspace();
+	seedChange(cwd);
+
+	const markdown = renderSddStatusMarkdown(resolveSddStatus({ cwd }));
+
+	assert.match(markdown, /## SDD Status: add-auth/);
+	assert.match(markdown, /```json/);
+	assert.match(markdown, /"schemaName": "gentle-pi.sdd-status"/);
+});
+
+test("parseSddStatusCommandArgs extracts change and json flag", () => {
+	assert.deepEqual(parseSddStatusCommandArgs("add-auth --json"), {
+		changeName: "add-auth",
+		json: true,
+	});
+	assert.deepEqual(parseSddStatusCommandArgs("--json"), {
+		changeName: undefined,
+		json: true,
+	});
+});