gentle-pi 0.2.8 → 0.3.1

package/README.md

@@ -49,6 +49,7 @@ Most coding-agent sessions fail for operational reasons, not model reasons:
 | **Rose startup intro**         | Adds a pink rose fade-in, compact project/runtime panel, and visible startup collaboration credit for @aporcelli's `pi-gentle-startup` ideas. |
 | **Work routing discipline**    | Small tasks stay inline. Context-heavy exploration can be delegated. Large or risky changes go through SDD/OpenSpec.                          |
 | **SDD/OpenSpec assets**        | Installs phase agents and chains for `init`, `explore`, `proposal`, `spec`, `design`, `tasks`, `apply`, `verify`, and `archive`.              |
+| **Lazy SDD preflight**         | Asks once per session for SDD mode, artifact store, PR chaining strategy, and review budget before the first SDD flow.                       |
 | **Subagent orchestration**     | Keeps one parent session responsible while child agents explore, implement, test, or review with focused context.                             |
 | **Strict TDD support**         | When project config declares a test command, apply/verify phases must record RED → GREEN → TRIANGULATE → REFACTOR evidence.                   |
 | **Reviewer protection**        | Surfaces review workload risk before a task turns into an oversized PR.                                                                       |
@@ -81,23 +82,24 @@ 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 flow in a session, then runs a one-time SDD preflight and installs local SDD assets without overwriting your edits. Slash SDD commands trigger this automatically; for natural-language requests, el Gentleman decides when SDD is needed and runs the explicit preflight first.
 
 ## Quick start
 
 ```text
-/gentle-ai:status      Check package, SDD assets, OpenSpec, and model config.
-/sdd-init              Create or refresh openspec/config.yaml.
-/gentle:models         Assign models to SDD/custom agents.
-/gentle:persona        Switch between gentleman and neutral persona modes.
+/gentle-ai:status          Check package, SDD assets, OpenSpec, and model config.
+/gentle-ai:sdd-preflight   Run or reuse the session SDD preflight explicitly.
+/sdd-init                  Create or refresh openspec/config.yaml.
+/gentle:models             Assign models to SDD/custom agents.
+/gentle:persona            Switch between gentleman and neutral persona modes.
 ```
 
 Typical flow:
 
 1. Open Pi in your repo.
 2. Run `/gentle-ai:status`.
-3. Run `/sdd-init` once per project, or when test/project capabilities change.
-4. For a substantial change, ask Pi to use SDD.
+3. Run `/sdd-init` once per project, or when test/project capabilities change. This also runs the session SDD preflight.
+4. For a substantial change, ask Pi to use SDD. Natural-language requests are classified by the parent agent, not by brittle runtime regexes.
 5. Review the phase artifacts instead of trusting floating chat context.
 
 ## How the harness decides what to do
@@ -147,9 +149,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 +160,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

@@ -5,6 +5,13 @@ import {
 	readFileSync,
 	writeFileSync,
 } from "node:fs";
+import {
+	access,
+	mkdir,
+	readFile,
+	readdir,
+	writeFile,
+} from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -14,13 +21,37 @@ 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");
-const ORCHESTRATOR_PROMPT = readFileSync(
-	join(ASSETS_DIR, "orchestrator.md"),
-	"utf8",
-).trim();
+
+let orchestratorPromptCache: string | null = null;
+function getOrchestratorPrompt(): string {
+	if (orchestratorPromptCache === null) {
+		orchestratorPromptCache = readFileSync(
+			join(ASSETS_DIR, "orchestrator.md"),
+			"utf8",
+		).trim();
+	}
+	return orchestratorPromptCache;
+}
+
+async function pathExists(path: string): Promise<boolean> {
+	try {
+		await access(path);
+		return true;
+	} catch {
+		return false;
+	}
+}
 
 type PersonaMode = "gentleman" | "neutral";
 
@@ -68,7 +99,7 @@ Harness principles:
 - Protect the human reviewer: avoid oversized changes, surface review workload risk, and ask before turning one task into a large multi-area change.
 - Never claim persistent memory is available because of this package. Memory is provided by separate packages or MCP tools when installed and callable.
 
-${ORCHESTRATOR_PROMPT}`;
+${getOrchestratorPrompt()}`;
 }
 
 const DENIED_BASH_PATTERNS: RegExp[] = [
@@ -182,62 +213,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 +269,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 {
@@ -311,6 +286,25 @@ function readModelConfig(cwd: string): AgentModelConfig {
 	}
 }
 
+export async function readModelConfigAsync(
+	cwd: string,
+): Promise<AgentModelConfig> {
+	const path = modelConfigPath(cwd);
+	if (!(await pathExists(path))) return {};
+	try {
+		const parsed: unknown = JSON.parse(await readFile(path, "utf8"));
+		if (!isRecord(parsed)) return {};
+		const config: AgentModelConfig = {};
+		for (const [name, value] of Object.entries(parsed)) {
+			const entry = normalizeRoutingEntry(value);
+			if (entry) config[name] = entry;
+		}
+		return config;
+	} catch {
+		return {};
+	}
+}
+
 function writeModelConfig(cwd: string, config: AgentModelConfig): void {
 	const path = modelConfigPath(cwd);
 	mkdirSync(dirname(path), { recursive: true });
@@ -371,6 +365,23 @@ function parseAgentName(filePath: string): string | undefined {
 	return packageName ? `${packageName}.${name}` : name;
 }
 
+async function parseAgentNameAsync(
+	filePath: string,
+): Promise<string | undefined> {
+	let content: string;
+	try {
+		content = await readFile(filePath, "utf8");
+	} catch {
+		return undefined;
+	}
+	const name = content.match(/^name:\s*["']?([^"'\n]+)["']?\s*$/m)?.[1]?.trim();
+	if (!name) return undefined;
+	const packageName = content
+		.match(/^package:\s*["']?([^"'\n]+)["']?\s*$/m)?.[1]
+		?.trim();
+	return packageName ? `${packageName}.${name}` : name;
+}
+
 function listAgentFilesRecursive(dir: string): string[] {
 	if (!existsSync(dir)) return [];
 	const files: string[] = [];
@@ -387,6 +398,30 @@ function listAgentFilesRecursive(dir: string): string[] {
 	return files;
 }
 
+async function listAgentFilesRecursiveAsync(dir: string): Promise<string[]> {
+	if (!(await pathExists(dir))) return [];
+	const files: string[] = [];
+	let entries;
+	try {
+		entries = await readdir(dir, { withFileTypes: true });
+	} catch {
+		return files;
+	}
+	for (const entry of entries) {
+		const path = join(dir, entry.name);
+		if (entry.isDirectory()) {
+			files.push(...(await listAgentFilesRecursiveAsync(path)));
+		} else if (
+			entry.isFile() &&
+			entry.name.endsWith(".md") &&
+			!entry.name.endsWith(".chain.md")
+		) {
+			files.push(path);
+		}
+	}
+	return files;
+}
+
 function listAgentsFromDir(dir: string, source: AgentSource): AgentEntry[] {
 	return listAgentFilesRecursive(dir)
 		.map((filePath): AgentEntry | undefined => {
@@ -396,6 +431,19 @@ function listAgentsFromDir(dir: string, source: AgentSource): AgentEntry[] {
 		.filter((entry): entry is AgentEntry => entry !== undefined);
 }
 
+async function listAgentsFromDirAsync(
+	dir: string,
+	source: AgentSource,
+): Promise<AgentEntry[]> {
+	const filePaths = await listAgentFilesRecursiveAsync(dir);
+	const entries: AgentEntry[] = [];
+	for (const filePath of filePaths) {
+		const name = await parseAgentNameAsync(filePath);
+		if (name) entries.push({ name, source, filePath });
+	}
+	return entries;
+}
+
 function listDiscoverableAgents(cwd: string): AgentEntry[] {
 	const builtinDirs = [
 		join(PACKAGE_ROOT, "..", "pi-subagents", "agents"),
@@ -421,6 +469,37 @@ function listDiscoverableAgents(cwd: string): AgentEntry[] {
 	return [...sddFirst, ...rest];
 }
 
+async function listDiscoverableAgentsAsync(cwd: string): Promise<AgentEntry[]> {
+	const builtinDirs = [
+		join(PACKAGE_ROOT, "..", "pi-subagents", "agents"),
+		join(cwd, ".pi", "npm", "node_modules", "pi-subagents", "agents"),
+		join(homedir(), ".local", "lib", "node_modules", "pi-subagents", "agents"),
+	];
+	const agents: AgentEntry[] = [];
+	for (const dir of builtinDirs) {
+		agents.push(...(await listAgentsFromDirAsync(dir, "builtin")));
+	}
+	const otherDirs: Array<[string, AgentSource]> = [
+		[join(homedir(), ".pi", "agent", "agents"), "user"],
+		[join(homedir(), ".agents"), "user"],
+		[join(cwd, ".agents"), "project"],
+		[join(cwd, ".pi", "agents"), "project"],
+	];
+	for (const [dir, source] of otherDirs) {
+		agents.push(...(await listAgentsFromDirAsync(dir, source)));
+	}
+	const byName = new Map<string, AgentEntry>();
+	for (const agent of agents) byName.set(agent.name, agent);
+	const discovered = Array.from(byName.values());
+	const sddFirst = SDD_AGENT_NAMES.map((name) =>
+		discovered.find((agent) => agent.name === name),
+	).filter((agent): agent is AgentEntry => agent !== undefined);
+	const rest = discovered
+		.filter((agent) => !SDD_AGENT_NAMES.includes(agent.name as SddAgentName))
+		.sort((left, right) => left.name.localeCompare(right.name));
+	return [...sddFirst, ...rest];
+}
+
 function projectSettingsPath(cwd: string): string {
 	return join(cwd, ".pi", "settings.json");
 }
@@ -465,7 +544,47 @@ function updateBuiltinModelOverride(
 	return true;
 }
 
-function applyModelConfig(
+async function updateBuiltinModelOverrideAsync(
+	cwd: string,
+	name: string,
+	entry: AgentRoutingEntry | undefined,
+): Promise<boolean> {
+	const path = projectSettingsPath(cwd);
+	let settings: Record<string, unknown> = {};
+	if (await pathExists(path)) {
+		try {
+			const parsed: unknown = JSON.parse(await readFile(path, "utf8"));
+			if (isRecord(parsed)) settings = parsed;
+		} catch {
+			settings = {};
+		}
+	}
+	const subagents = isRecord(settings.subagents)
+		? { ...settings.subagents }
+		: {};
+	const agentOverrides = isRecord(subagents.agentOverrides)
+		? { ...subagents.agentOverrides }
+		: {};
+	const current = isRecord(agentOverrides[name])
+		? { ...agentOverrides[name] }
+		: {};
+	if (entry?.model === undefined) delete current.model;
+	else current.model = entry.model;
+	if (entry?.thinking === undefined) delete current.thinking;
+	else current.thinking = entry.thinking;
+	if (Object.keys(current).length > 0) agentOverrides[name] = current;
+	else delete agentOverrides[name];
+	if (Object.keys(agentOverrides).length > 0)
+		subagents.agentOverrides = agentOverrides;
+	else delete subagents.agentOverrides;
+	if (Object.keys(subagents).length > 0) settings.subagents = subagents;
+	else delete settings.subagents;
+	await mkdir(dirname(path), { recursive: true });
+	await writeFile(path, `${JSON.stringify(settings, null, "\t")}\n`);
+	return true;
+}
+
+export function applyModelConfig(
 	cwd: string,
 	config: AgentModelConfig,
 ): { updated: number; skipped: number } {
@@ -494,6 +613,36 @@ function applyModelConfig(
 	return { updated, skipped };
 }
 
+export async function applyModelConfigAsync(
+	cwd: string,
+	config: AgentModelConfig,
+): Promise<{ updated: number; skipped: number }> {
+	let updated = 0;
+	let skipped = 0;
+	for (const agent of await listDiscoverableAgentsAsync(cwd)) {
+		const entry = config[agent.name];
+		if (agent.source === "builtin") {
+			if (await updateBuiltinModelOverrideAsync(cwd, agent.name, entry))
+				updated += 1;
+			else skipped += 1;
+			continue;
+		}
+		if (!agent.filePath || !(await pathExists(agent.filePath))) {
+			skipped += 1;
+			continue;
+		}
+		const original = await readFile(agent.filePath, "utf8");
+		const next = updateFrontmatterRouting(original, entry);
+		if (next === original) {
+			skipped += 1;
+			continue;
+		}
+		await writeFile(agent.filePath, next);
+		updated += 1;
+	}
+	return { updated, skipped };
+}
+
 function describeModelConfig(cwd: string, config: AgentModelConfig): string[] {
 	return listDiscoverableAgents(cwd).map((agent) => {
 		const entry = config[agent.name];
@@ -953,29 +1102,52 @@ async function handlePersonaCommand(ctx: ExtensionContext): Promise<void> {
 }
 
 export default function gentleAi(pi: ExtensionAPI): void {
-	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",
-			);
+	function runSddPreflight(ctx: ExtensionContext): Promise<SddPreflightPreferences> {
+		return ensureSddPreflight(ctx, {
+			pi,
+			installAssets: (cwd) => installSddAssets(cwd, false),
+			applyModelConfig: async (cwd) =>
+				applyModelConfigAsync(cwd, await readModelConfigAsync(cwd)),
+		});
+	}
+
+	pi.on("session_start", async (_event, ctx) => {
+		try {
+			const config = await readModelConfigAsync(ctx.cwd);
+			const modelResult = await applyModelConfigAsync(ctx.cwd, config);
+			if (ctx.hasUI && modelResult.updated > 0) {
+				ctx.ui.notify(
+					`el Gentleman applied SDD model config to ${modelResult.updated} agent(s).`,
+					"info",
+				);
+			}
+		} catch (error) {
+			if (ctx.hasUI) {
+				const message =
+					error instanceof Error ? error.message : String(error);
+				ctx.ui.notify(
+					`el Gentleman model config sweep failed: ${message}`,
+					"warning",
+				);
+			}
 		}
-		if (ctx.hasUI && modelResult.updated > 0) {
-			ctx.ui.notify(
-				`el Gentleman applied SDD model config to ${modelResult.updated} agent(s).`,
-				"info",
-			);
+	});
+
+	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) => ({
-		systemPrompt: `${event.systemPrompt}\n\n${buildGentlePrompt(readPersonaMode(ctx.cwd))}`,
-	}));
+	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 +1169,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 { applyModelConfigAsync, readModelConfigAsync } 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,12 @@ 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: async (cwd) =>
+					applyModelConfigAsync(cwd, await readModelConfigAsync(cwd)),
+			});
 			const configPath = join(ctx.cwd, CONFIG_REL_PATH);
 			if (existsSync(configPath)) {
 				ctx.ui.notify(