gentle-pi 0.2.8 → 0.3.0

package/README.md

@@ -81,7 +81,7 @@ Then start Pi in a project:
 pi
 ```
 
-On session start, `gentle-pi` installs local SDD assets without overwriting your edits.
+`gentle-pi` waits until the first SDD request in a session, then runs a one-time SDD preflight and installs local SDD assets without overwriting your edits.
 
 ## Quick start
 
@@ -147,9 +147,9 @@ For substantial work, the parent session coordinates the flow and each phase wri
 - verification reports;
 - archive notes for future agents.
 
-## Project files installed
+## SDD preflight and project files
 
-On Pi `session_start`, `gentle-pi` copies these assets if they are missing:
+`gentle-pi` does not interrupt every new session. Slash SDD flows such as `/sdd-*`, `/sdd-init`, and the explicit `/gentle-ai:sdd-preflight` command run a lazy preflight, ask for session-scoped SDD preferences, and then copy these assets if they are missing. For natural-language requests, the parent agent decides whether the work should use SDD and must run/reuse `/gentle-ai:sdd-preflight` before continuing.
 
 ```text
 .pi/agents/sdd-*.md
@@ -158,12 +158,26 @@ On Pi `session_start`, `gentle-pi` copies these assets if they are missing:
 .pi/gentle-ai/support/strict-tdd-verify.md
 ```
 
+The preflight choices are reused for later SDD flows in the same session:
+
+- execution mode: `interactive` or `auto`;
+- artifact store: `openspec`, or `engram`/`both` when callable memory tools are available;
+- PR chaining strategy: `auto-forecast`, `ask-always`, `single-pr-default`, or `force-chained`;
+- review budget line threshold.
+
 It does **not** overwrite existing files unless you explicitly run:
 
 ```text
 /gentle-ai:install-sdd --force
 ```
 
+Manual preflight commands:
+
+```text
+/gentle-ai:sdd-preflight
+/gentle:sdd-preflight
+```
+
 ## Skill registry
 
 `gentle-pi` keeps a local registry at:

package/assets/orchestrator.md

@@ -177,16 +177,25 @@ proposal → spec ─┬→ tasks → apply → verify → archive
 proposal → design ┘
 ```
 
-## Automatic Setup Expectations
+## Lazy SDD Preflight
 
-On startup, the package should ensure SDD assets are present for `pi-subagents` without the user needing to remember setup commands. If assets are missing, install them non-destructively into:
+Do not ask SDD setup questions on session start. The first time the user initiates an SDD process in a Pi session, run the SDD preflight once and keep those choices for the rest of that session. Runtime trigger detection is intentionally deterministic: slash SDD flows and `/sdd-init` run preflight automatically; for natural-language requests, the parent/orchestrator decides semantically whether SDD is needed and must run/reuse `/gentle-ai:sdd-preflight` before continuing.
+
+The preflight captures:
+
+- execution mode: `interactive` or `auto`;
+- artifact store: `openspec`, `engram`, or `both` when callable memory tools are available;
+- chained PR strategy: `auto-forecast`, `ask-always`, `single-pr-default`, or `force-chained`;
+- review budget in changed lines.
+
+During that lazy preflight, the package should ensure SDD assets are present for `pi-subagents` without the user needing to remember setup commands. If assets are missing, install them non-destructively into:
 
 ```text
 .pi/agents/sdd-*.md
 .pi/chains/sdd-*.chain.md
 ```
 
-Manual commands are recovery/debug paths, not the happy path.
+Manual install commands are recovery/debug paths, not the happy path. `/gentle-ai:sdd-preflight` and `/gentle:sdd-preflight` are the explicit preflight commands for agent/orchestrator use. If the user explicitly changes SDD preferences later in the same session, follow the new instruction.
 
 ## Init Guard
 
@@ -220,7 +229,7 @@ When Engram or another callable memory package is available, the parent owns mem
 
 ## Execution Mode
 
-For substantial SDD flows, choose or ask once per change:
+Use the session's SDD preflight choice:
 
 - `interactive`: default, pause between major phases and ask whether to continue.
 - `auto`: run phases back-to-back when the user explicitly wants speed and trusts the flow.

package/extensions/gentle-ai.ts

@@ -14,6 +14,14 @@ import type {
 	ToolCallEventResult,
 } from "@earendil-works/pi-coding-agent";
 import { matchesKey, truncateToWidth } from "@earendil-works/pi-tui";
+import {
+	ensureSddPreflight,
+	getSddPreflightPreferences,
+	installSddAssets,
+	isSddPreflightTrigger,
+	renderSddPreflightPrompt,
+	type SddPreflightPreferences,
+} from "../lib/sdd-preflight.ts";
 
 const PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
 const ASSETS_DIR = join(PACKAGE_ROOT, "assets");
@@ -182,62 +190,6 @@ async function confirmCommand(
 	};
 }
 
-function copyDirectoryFiles(
-	sourceDir: string,
-	targetDir: string,
-	force: boolean,
-): { copied: number; skipped: number } {
-	if (!existsSync(sourceDir)) return { copied: 0, skipped: 0 };
-	mkdirSync(targetDir, { recursive: true });
-	let copied = 0;
-	let skipped = 0;
-	for (const entry of readdirSync(sourceDir, { withFileTypes: true })) {
-		const sourcePath = join(sourceDir, entry.name);
-		const targetPath = join(targetDir, entry.name);
-		if (entry.isDirectory()) {
-			const child = copyDirectoryFiles(sourcePath, targetPath, force);
-			copied += child.copied;
-			skipped += child.skipped;
-			continue;
-		}
-		if (!entry.isFile()) continue;
-		if (!force && existsSync(targetPath)) {
-			skipped += 1;
-			continue;
-		}
-		writeFileSync(targetPath, readFileSync(sourcePath));
-		copied += 1;
-	}
-	return { copied, skipped };
-}
-
-function installSddAssets(
-	cwd: string,
-	force: boolean,
-): { agents: number; chains: number; support: number; skipped: number } {
-	const agents = copyDirectoryFiles(
-		join(ASSETS_DIR, "agents"),
-		join(cwd, ".pi", "agents"),
-		force,
-	);
-	const chains = copyDirectoryFiles(
-		join(ASSETS_DIR, "chains"),
-		join(cwd, ".pi", "chains"),
-		force,
-	);
-	const support = copyDirectoryFiles(
-		join(ASSETS_DIR, "support"),
-		join(cwd, ".pi", "gentle-ai", "support"),
-		force,
-	);
-	return {
-		agents: agents.copied,
-		chains: chains.copied,
-		support: support.copied,
-		skipped: agents.skipped + chains.skipped + support.skipped,
-	};
-}
-
 function isRecord(value: unknown): value is Record<string, unknown> {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -294,7 +246,7 @@ function normalizeRoutingEntry(value: unknown): AgentRoutingEntry | undefined {
 	return { model, thinking };
 }
 
-function readModelConfig(cwd: string): AgentModelConfig {
+export function readModelConfig(cwd: string): AgentModelConfig {
 	const path = modelConfigPath(cwd);
 	if (!existsSync(path)) return {};
 	try {
@@ -465,7 +417,7 @@ function updateBuiltinModelOverride(
 	return true;
 }
 
-function applyModelConfig(
+export function applyModelConfig(
 	cwd: string,
 	config: AgentModelConfig,
 ): { updated: number; skipped: number } {
@@ -953,18 +905,16 @@ async function handlePersonaCommand(ctx: ExtensionContext): Promise<void> {
 }
 
 export default function gentleAi(pi: ExtensionAPI): void {
+	function runSddPreflight(ctx: ExtensionContext): Promise<SddPreflightPreferences> {
+		return ensureSddPreflight(ctx, {
+			pi,
+			installAssets: (cwd) => installSddAssets(cwd, false),
+			applyModelConfig: (cwd) => applyModelConfig(cwd, readModelConfig(cwd)),
+		});
+	}
+
 	pi.on("session_start", (_event, ctx) => {
-		const result = installSddAssets(ctx.cwd, false);
 		const modelResult = applyModelConfig(ctx.cwd, readModelConfig(ctx.cwd));
-		if (
-			ctx.hasUI &&
-			(result.agents > 0 || result.chains > 0 || result.support > 0)
-		) {
-			ctx.ui.notify(
-				`Gentle AI SDD assets auto-installed: ${result.agents} agent(s), ${result.chains} chain(s), ${result.support} support file(s).`,
-				"info",
-			);
-		}
 		if (ctx.hasUI && modelResult.updated > 0) {
 			ctx.ui.notify(
 				`el Gentleman applied SDD model config to ${modelResult.updated} agent(s).`,
@@ -973,9 +923,21 @@ export default function gentleAi(pi: ExtensionAPI): void {
 		}
 	});
 
-	pi.on("before_agent_start", (event, ctx) => ({
-		systemPrompt: `${event.systemPrompt}\n\n${buildGentlePrompt(readPersonaMode(ctx.cwd))}`,
-	}));
+	pi.on("input", async (event, ctx) => {
+		if (typeof event.text !== "string" || !isSddPreflightTrigger(event.text)) {
+			return { action: "continue" };
+		}
+		await runSddPreflight(ctx);
+		return { action: "continue" };
+	});
+
+	pi.on("before_agent_start", (event, ctx) => {
+		const prefs = getSddPreflightPreferences(ctx);
+		const sddPrompt = prefs ? `\n\n${renderSddPreflightPrompt(prefs)}` : "";
+		return {
+			systemPrompt: `${event.systemPrompt}\n\n${buildGentlePrompt(readPersonaMode(ctx.cwd))}${sddPrompt}`,
+		};
+	});
 
 	pi.on("tool_call", async (event, ctx) => {
 		if (event.toolName !== "bash") return undefined;
@@ -997,6 +959,21 @@ export default function gentleAi(pi: ExtensionAPI): void {
 		},
 	});
 
+	pi.registerCommand("gentle-ai:sdd-preflight", {
+		description:
+			"Run or reuse the lazy SDD preflight for this Pi session.",
+		handler: async (_args, ctx) => {
+			await runSddPreflight(ctx);
+		},
+	});
+
+	pi.registerCommand("gentle:sdd-preflight", {
+		description: "Compatibility alias for /gentle-ai:sdd-preflight.",
+		handler: async (_args, ctx) => {
+			await runSddPreflight(ctx);
+		},
+	});
+
 	pi.registerCommand("gentle:models", {
 		description: "Configure per-agent models for el Gentleman.",
 		handler: async (_args, ctx) => {

package/extensions/sdd-init.ts

@@ -6,6 +6,8 @@ import {
 	writeFileSync,
 } from "node:fs";
 import { basename, dirname, join, relative } from "node:path";
+import { applyModelConfig, readModelConfig } from "./gentle-ai.ts";
+import { ensureSddPreflight, installSddAssets } from "../lib/sdd-preflight.ts";
 type ExtensionAPI = any;
 
 const CONFIG_REL_PATH = "openspec/config.yaml";
@@ -773,6 +775,11 @@ export default function (pi: ExtensionAPI) {
 		description:
 			"Auto-detect project stack and bootstrap openspec/config.yaml for SDD.",
 		handler: async (_args: unknown, ctx: any) => {
+			await ensureSddPreflight(ctx, {
+				pi,
+				installAssets: (cwd) => installSddAssets(cwd, false),
+				applyModelConfig: (cwd) => applyModelConfig(cwd, readModelConfig(cwd)),
+			});
 			const configPath = join(ctx.cwd, CONFIG_REL_PATH);
 			if (existsSync(configPath)) {
 				ctx.ui.notify(

package/lib/sdd-preflight.ts

@@ -0,0 +1,253 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+const PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+const ASSETS_DIR = join(PACKAGE_ROOT, "assets");
+
+export type SddExecutionMode = "interactive" | "auto";
+export type SddArtifactStore = "openspec" | "engram" | "both";
+export type SddChainedPrStrategy =
+	| "auto-forecast"
+	| "ask-always"
+	| "single-pr-default"
+	| "force-chained";
+
+export interface SddPreflightPreferences {
+	executionMode: SddExecutionMode;
+	artifactStore: SddArtifactStore;
+	chainedPrStrategy: SddChainedPrStrategy;
+	reviewBudgetLines: number;
+	engramAvailable: boolean;
+}
+
+interface SddPreflightCallbacks {
+	pi: ExtensionAPI;
+	installAssets?: (cwd: string) => {
+		agents: number;
+		chains: number;
+		support: number;
+		skipped: number;
+	};
+	applyModelConfig?: (cwd: string) => { updated: number; skipped: number };
+}
+
+const DEFAULT_SDD_PREFLIGHT: SddPreflightPreferences = {
+	executionMode: "interactive",
+	artifactStore: "openspec",
+	chainedPrStrategy: "auto-forecast",
+	reviewBudgetLines: 400,
+	engramAvailable: false,
+};
+
+const sddPreflightBySession = new Map<string, SddPreflightPreferences>();
+const sddPreflightInFlight = new Map<string, Promise<SddPreflightPreferences>>();
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function copyDirectoryFiles(
+	sourceDir: string,
+	targetDir: string,
+	force: boolean,
+): { copied: number; skipped: number } {
+	if (!existsSync(sourceDir)) return { copied: 0, skipped: 0 };
+	mkdirSync(targetDir, { recursive: true });
+	let copied = 0;
+	let skipped = 0;
+	for (const entry of readdirSync(sourceDir, { withFileTypes: true })) {
+		const sourcePath = join(sourceDir, entry.name);
+		const targetPath = join(targetDir, entry.name);
+		if (entry.isDirectory()) {
+			const child = copyDirectoryFiles(sourcePath, targetPath, force);
+			copied += child.copied;
+			skipped += child.skipped;
+			continue;
+		}
+		if (!entry.isFile()) continue;
+		if (!force && existsSync(targetPath)) {
+			skipped += 1;
+			continue;
+		}
+		writeFileSync(targetPath, readFileSync(sourcePath));
+		copied += 1;
+	}
+	return { copied, skipped };
+}
+
+export function installSddAssets(
+	cwd: string,
+	force: boolean,
+): { agents: number; chains: number; support: number; skipped: number } {
+	const agents = copyDirectoryFiles(
+		join(ASSETS_DIR, "agents"),
+		join(cwd, ".pi", "agents"),
+		force,
+	);
+	const chains = copyDirectoryFiles(
+		join(ASSETS_DIR, "chains"),
+		join(cwd, ".pi", "chains"),
+		force,
+	);
+	const support = copyDirectoryFiles(
+		join(ASSETS_DIR, "support"),
+		join(cwd, ".pi", "gentle-ai", "support"),
+		force,
+	);
+	return {
+		agents: agents.copied,
+		chains: chains.copied,
+		support: support.copied,
+		skipped: agents.skipped + chains.skipped + support.skipped,
+	};
+}
+
+export function isSddPreflightTrigger(text: string): boolean {
+	return /^\/sdd-[^\s]*(?:\s|$)/i.test(text.trim());
+}
+
+export function sddPreflightSessionKey(ctx: ExtensionContext): string {
+	const manager = (ctx as unknown as { sessionManager?: unknown }).sessionManager;
+	if (isRecord(manager)) {
+		const getSessionFile = manager.getSessionFile;
+		if (typeof getSessionFile === "function") {
+			const value = getSessionFile.call(manager);
+			if (typeof value === "string" && value.length > 0) return value;
+		}
+		const getSessionId = manager.getSessionId;
+		if (typeof getSessionId === "function") {
+			const value = getSessionId.call(manager);
+			if (typeof value === "string" && value.length > 0) return value;
+		}
+	}
+	return ctx.cwd;
+}
+
+function hasWritableEngramTool(pi: ExtensionAPI): boolean {
+	try {
+		const getActiveTools = (pi as unknown as { getActiveTools?: () => unknown[] })
+			.getActiveTools;
+		if (typeof getActiveTools !== "function") return false;
+		const tools = getActiveTools.call(pi);
+		return tools.some((tool) => {
+			const name =
+				typeof tool === "string"
+					? tool
+					: isRecord(tool) && typeof tool.name === "string"
+						? tool.name
+						: "";
+			return (
+				name === "mem_save" ||
+				name === "engram_mem_save" ||
+				name.endsWith(".mem_save") ||
+				name.endsWith(".engram_mem_save")
+			);
+		});
+	} catch {
+		return false;
+	}
+}
+
+function normalizeSddReviewBudget(value: string): number {
+	const parsed = Number.parseInt(value.trim(), 10);
+	return Number.isFinite(parsed) && parsed > 0 ? parsed : 400;
+}
+
+async function collectSddPreflightPreferences(
+	ctx: ExtensionContext,
+	engramAvailable: boolean,
+): Promise<SddPreflightPreferences> {
+	if (!ctx.hasUI) return { ...DEFAULT_SDD_PREFLIGHT, engramAvailable };
+	const executionMode = await ctx.ui.select("SDD execution mode", [
+		"interactive",
+		"auto",
+	]);
+	const artifactOptions = engramAvailable
+		? ["openspec", "engram", "both"]
+		: ["openspec"];
+	const artifactStore = await ctx.ui.select("SDD artifact store", artifactOptions);
+	const chainedPrStrategy = await ctx.ui.select("SDD PR chaining", [
+		"auto-forecast",
+		"ask-always",
+		"single-pr-default",
+		"force-chained",
+	]);
+	const reviewBudgetLines = normalizeSddReviewBudget(
+		(await ctx.ui.input("SDD review budget lines", "400")) ?? "400",
+	);
+	return {
+		executionMode:
+			executionMode === "auto" ? "auto" : DEFAULT_SDD_PREFLIGHT.executionMode,
+		artifactStore:
+			artifactStore === "engram" || artifactStore === "both"
+				? artifactStore
+				: DEFAULT_SDD_PREFLIGHT.artifactStore,
+		chainedPrStrategy:
+			chainedPrStrategy === "ask-always" ||
+			chainedPrStrategy === "single-pr-default" ||
+			chainedPrStrategy === "force-chained"
+				? chainedPrStrategy
+				: DEFAULT_SDD_PREFLIGHT.chainedPrStrategy,
+		reviewBudgetLines,
+		engramAvailable,
+	};
+}
+
+export function renderSddPreflightPrompt(prefs: SddPreflightPreferences): string {
+	return [
+		"## SDD Session Preflight",
+		"The user already chose these SDD preferences for this Pi session. Reuse them unless the user explicitly changes them.",
+		`- Execution mode: ${prefs.executionMode}`,
+		`- Artifact store: ${prefs.artifactStore}${prefs.engramAvailable ? "" : " (Engram unavailable in this session)"}`,
+		`- Chained PR strategy: ${prefs.chainedPrStrategy}`,
+		`- Review budget: ${prefs.reviewBudgetLines} changed lines`,
+		"- If task/workload forecasts conflict with these preferences, pause before sdd-apply and ask the user for a delivery decision.",
+	].join("\n");
+}
+
+export async function ensureSddPreflight(
+	ctx: ExtensionContext,
+	callbacks: SddPreflightCallbacks,
+): Promise<SddPreflightPreferences> {
+	const sessionKey = sddPreflightSessionKey(ctx);
+	const existing = sddPreflightBySession.get(sessionKey);
+	if (existing) return existing;
+	const inFlight = sddPreflightInFlight.get(sessionKey);
+	if (inFlight) return inFlight;
+	const promise = (async () => {
+		const engramAvailable = hasWritableEngramTool(callbacks.pi);
+		const prefs = await collectSddPreflightPreferences(ctx, engramAvailable);
+		const result = callbacks.installAssets?.(ctx.cwd) ?? installSddAssets(ctx.cwd, false);
+		const modelResult = callbacks.applyModelConfig?.(ctx.cwd) ?? { updated: 0, skipped: 0 };
+		if (ctx.hasUI) {
+			ctx.ui.notify(
+				[
+					"Gentle AI SDD preflight complete.",
+					`Mode: ${prefs.executionMode}`,
+					`Artifacts: ${prefs.artifactStore}`,
+					`PR chaining: ${prefs.chainedPrStrategy}`,
+					`Review budget: ${prefs.reviewBudgetLines} changed lines`,
+					`Assets installed: ${result.agents} agent(s), ${result.chains} chain(s), ${result.support} support file(s), ${result.skipped} skipped.`,
+					`Model-routed agents updated: ${modelResult.updated}`,
+				].join("\n"),
+				"info",
+			);
+		}
+		sddPreflightBySession.set(sessionKey, prefs);
+		return prefs;
+	})();
+	sddPreflightInFlight.set(sessionKey, promise);
+	try {
+		return await promise;
+	} finally {
+		sddPreflightInFlight.delete(sessionKey);
+	}
+}
+
+export function getSddPreflightPreferences(
+	ctx: ExtensionContext,
+): SddPreflightPreferences | undefined {
+	return sddPreflightBySession.get(sddPreflightSessionKey(ctx));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gentle-pi",
-  "version": "0.2.8",
+  "version": "0.3.0",
   "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",
@@ -25,6 +25,7 @@
   "files": [
     "assets/",
     "extensions/",
+    "lib/",
     "prompts/",
     "skills/",
     "scripts/",

package/scripts/verify-package-files.mjs

@@ -12,6 +12,7 @@ const requiredPaths = [
   "extensions/gentle-ai.ts",
   "extensions/sdd-init.ts",
   "extensions/skill-registry.ts",
+  "lib/sdd-preflight.ts",
   "prompts/gcl.md",
   "prompts/gis.md",
   "prompts/gpr.md",

package/tests/runtime-harness.mjs

@@ -1,8 +1,10 @@
 #!/usr/bin/env node
 import assert from "node:assert/strict";
+import { existsSync } from "node:fs";
 import { mkdtemp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
+import { discoverAndLoadExtensions } from "@earendil-works/pi-coding-agent";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
 const ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
@@ -15,6 +17,8 @@ const EXTENSIONS = [
 
 const EXPECTED_COMMANDS = [
 	"gentle-ai:install-sdd",
+	"gentle-ai:sdd-preflight",
+	"gentle:sdd-preflight",
 	"gentle:models",
 	"gentle-ai:models",
 	"gentleman:models",
@@ -31,6 +35,7 @@ function createPi() {
 	const commands = new Map();
 	const flags = new Map();
 	const flagValues = new Map([["no-skill-registry", true]]);
+	let activeTools = ["read", "bash", "edit", "write"];
 
 	const pi = {
 		on(name, handler) {
@@ -53,12 +58,19 @@ function createPi() {
 		getCommands() {
 			return Array.from(commands, ([name, definition]) => ({ name, ...definition }));
 		},
+		getActiveTools() {
+			return activeTools;
+		},
+		setActiveTools(value) {
+			activeTools = value;
+		},
 		getAllTools() {
 			return [
 				{ name: "read" },
 				{ name: "bash" },
 				{ name: "edit" },
 				{ name: "write" },
+				{ name: "mem_save" },
 			];
 		},
 	};
@@ -68,15 +80,18 @@ function createPi() {
 
 function createUi() {
 	const notifications = [];
+	const selections = [];
 	return {
 		notifications,
+		selections,
 		notify(message, level = "info") {
 			notifications.push({ message, level });
 		},
 		async confirm() {
 			return false;
 		},
-		async select(_label, options) {
+		async select(label, options) {
+			selections.push({ label, options });
 			return options[0];
 		},
 		async input(_label, placeholder) {
@@ -88,11 +103,19 @@ function createUi() {
 	};
 }
 
-function createCtx(cwd, hasUI = false) {
+function createCtx(cwd, hasUI = false, sessionId = "session-1") {
 	return {
 		cwd,
 		hasUI,
 		ui: createUi(),
+		sessionManager: {
+			getSessionFile() {
+				return join(cwd, `${sessionId}.jsonl`);
+			},
+			getSessionId() {
+				return sessionId;
+			},
+		},
 		modelRegistry: {
 			async getAvailable() {
 				return [];
@@ -122,9 +145,17 @@ async function run() {
 	}
 	assert.ok(flags.has("no-skill-registry"), "missing no-skill-registry flag");
 	assert.ok(hooks.has("session_start"), "missing session_start hook");
+	assert.ok(hooks.has("input"), "missing input hook");
 	assert.ok(hooks.has("before_agent_start"), "missing before_agent_start hook");
 	assert.ok(hooks.has("tool_call"), "missing tool_call hook");
 
+	const discovered = await discoverAndLoadExtensions(["./extensions"], ROOT);
+	assert.deepEqual(
+		discovered.errors,
+		[],
+		"declared extension directory must load without invalid helper modules",
+	);
+
 	const promptCwd = await tempWorkspace();
 	try {
 		const promptHook = hooks.get("before_agent_start")[0];
@@ -154,10 +185,146 @@ async function run() {
 		for (const handler of hooks.get("session_start")) {
 			await handler({ reason: "startup" }, createCtx(noUiCwd, false));
 		}
+		assert.equal(
+			existsSync(join(noUiCwd, ".pi", "agents", "sdd-apply.md")),
+			false,
+			"session_start must not install SDD agents before first SDD intent",
+		);
+		assert.equal(
+			existsSync(join(noUiCwd, ".pi", "chains", "sdd-full.chain.md")),
+			false,
+			"session_start must not install SDD chains before first SDD intent",
+		);
 	} finally {
 		await rm(noUiCwd, { recursive: true, force: true });
 	}
 
+	const lazySddCwd = await tempWorkspace();
+	try {
+		await mkdir(join(lazySddCwd, ".pi", "gentle-ai"), { recursive: true });
+		await writeFile(
+			join(lazySddCwd, ".pi", "gentle-ai", "models.json"),
+			JSON.stringify({ "sdd-apply": { model: "openai/gpt-5", thinking: "high" } }, null, 2),
+		);
+		const ctx = createCtx(lazySddCwd, true);
+		const inputHook = hooks.get("input")[0];
+		assert.deepEqual(
+			await inputHook({ text: "hola, solo mirando", source: "interactive" }, ctx),
+			{ action: "continue" },
+		);
+		assert.deepEqual(
+			await inputHook({ text: "what is SDD?", source: "interactive" }, ctx),
+			{ action: "continue" },
+		);
+		assert.deepEqual(
+			await inputHook({ text: "what can I do with SDD?", source: "interactive" }, ctx),
+			{ action: "continue" },
+		);
+		assert.deepEqual(
+			await inputHook({ text: "how do I use SDD?", source: "interactive" }, ctx),
+			{ action: "continue" },
+		);
+		assert.deepEqual(
+			await inputHook({ text: "Can I use SDD?", source: "interactive" }, ctx),
+			{ action: "continue" },
+		);
+		assert.deepEqual(
+			await inputHook({ text: "don't use sdd for this", source: "interactive" }, ctx),
+			{ action: "continue" },
+		);
+		assert.deepEqual(
+			await inputHook({ text: "sin usar SDD por ahora", source: "interactive" }, ctx),
+			{ action: "continue" },
+		);
+		assert.deepEqual(
+			await inputHook({ text: "let's not use SDD for this", source: "interactive" }, ctx),
+			{ action: "continue" },
+		);
+		assert.deepEqual(
+			await inputHook({ text: "never use SDD here", source: "interactive" }, ctx),
+			{ action: "continue" },
+		);
+		assert.deepEqual(
+			await inputHook({ text: "no quiero usar SDD por ahora", source: "interactive" }, ctx),
+			{ action: "continue" },
+		);
+		assert.deepEqual(
+			await inputHook({ text: "I use SDD sometimes", source: "interactive" }, ctx),
+			{ action: "continue" },
+		);
+		assert.deepEqual(
+			await inputHook({ text: "I'm using SDD in another repo", source: "interactive" }, ctx),
+			{ action: "continue" },
+		);
+		assert.equal(existsSync(join(lazySddCwd, ".pi", "agents", "sdd-apply.md")), false);
+
+		assert.deepEqual(
+			await inputHook({ text: "please use sdd for this change", source: "interactive" }, ctx),
+			{ action: "continue" },
+		);
+		assert.deepEqual(
+			await inputHook({ text: "/sdd", source: "interactive" }, ctx),
+			{ action: "continue" },
+		);
+		assert.deepEqual(
+			await inputHook({ text: "/sdd plan", source: "interactive" }, ctx),
+			{ action: "continue" },
+		);
+		assert.deepEqual(
+			await inputHook({ text: "/sdd:plan", source: "interactive" }, ctx),
+			{ action: "continue" },
+		);
+		assert.equal(existsSync(join(lazySddCwd, ".pi", "agents", "sdd-apply.md")), false);
+
+		assert.deepEqual(
+			await inputHook({ text: "/sdd-plan this change", source: "interactive" }, ctx),
+			{ action: "continue" },
+		);
+		assert.equal(existsSync(join(lazySddCwd, ".pi", "agents", "sdd-apply.md")), true);
+		assert.equal(existsSync(join(lazySddCwd, ".pi", "chains", "sdd-full.chain.md")), true);
+		const lazyAppliedAgent = await readFile(
+			join(lazySddCwd, ".pi", "agents", "sdd-apply.md"),
+			"utf8",
+		);
+		assert.match(lazyAppliedAgent, /model: openai\/gpt-5/);
+		assert.match(lazyAppliedAgent, /thinking: high/);
+		assert.equal(ctx.ui.selections.length, 3);
+		assert.deepEqual(ctx.ui.selections[1].options, ["openspec"]);
+		assert.match(ctx.ui.notifications.at(-1).message, /SDD preflight complete/);
+
+		await inputHook({ text: "/sdd-plan another change", source: "interactive" }, ctx);
+		assert.equal(ctx.ui.selections.length, 3, "preflight should run only once per session");
+		const promptHook = hooks.get("before_agent_start")[0];
+		const promptResult = promptHook({ systemPrompt: "base" }, ctx);
+		assert.match(promptResult.systemPrompt, /SDD Session Preflight/);
+		assert.match(promptResult.systemPrompt, /Execution mode: interactive/);
+	} finally {
+		await rm(lazySddCwd, { recursive: true, force: true });
+	}
+
+	const commandSddCwd = await tempWorkspace();
+	try {
+		const ctx = createCtx(commandSddCwd, true, "command-session");
+		await commands.get("gentle-ai:sdd-preflight").handler("", ctx);
+		assert.equal(existsSync(join(commandSddCwd, ".pi", "agents", "sdd-apply.md")), true);
+		assert.equal(ctx.ui.selections.length, 3);
+		await commands.get("gentle:sdd-preflight").handler("", ctx);
+		assert.equal(ctx.ui.selections.length, 3, "manual preflight command should reuse session choices");
+	} finally {
+		await rm(commandSddCwd, { recursive: true, force: true });
+	}
+
+	const engramSddCwd = await tempWorkspace();
+	try {
+		pi.setActiveTools(["read", "bash", "edit", "write", "mem_save"]);
+		const ctx = createCtx(engramSddCwd, true, "engram-session");
+		await commands.get("gentle-ai:sdd-preflight").handler("", ctx);
+		assert.deepEqual(ctx.ui.selections[1].options, ["openspec", "engram", "both"]);
+	} finally {
+		pi.setActiveTools(["read", "bash", "edit", "write"]);
+		await rm(engramSddCwd, { recursive: true, force: true });
+	}
+
 	const installCwd = await tempWorkspace();
 	try {
 		const ctx = createCtx(installCwd, true);
@@ -171,7 +338,14 @@ async function run() {
 	try {
 		const ctx = createCtx(sddCwd, true);
 		await commands.get("sdd-init").handler("", ctx);
+		assert.equal(existsSync(join(sddCwd, ".pi", "agents", "sdd-apply.md")), true);
+		assert.equal(existsSync(join(sddCwd, ".pi", "chains", "sdd-full.chain.md")), true);
+		assert.equal(ctx.ui.selections.length, 3);
+		assert.match(ctx.ui.notifications[0].message, /SDD preflight complete/);
 		assert.match(ctx.ui.notifications.at(-1).message, /Wrote openspec\/config\.yaml/);
+
+		await commands.get("gentle-ai:sdd-preflight").handler("", ctx);
+		assert.equal(ctx.ui.selections.length, 3, "/sdd-init preflight should be reused by later manual preflight");
 	} finally {
 		await rm(sddCwd, { recursive: true, force: true });
 	}