gentle-pi 0.3.0 → 0.3.2

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
 ```
 
-`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.
+`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 global 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 global model/effort routing 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
@@ -282,12 +284,14 @@ Recommended model/effort shape:
 | Verify / review            | Strong fresh-context model.                          | `high`                          |
 | Tiny utilities             | Inherit active/default model unless they bottleneck. | `inherit`                       |
 
-Saved at:
+Saved globally at:
 
 ```text
-.pi/gentle-ai/models.json
+~/.pi/gentle-ai/models.json
 ```
 
+Existing project-local `.pi/gentle-ai/models.json` files are still read as a legacy fallback when no global model config exists, but `/gentle:models` writes the shared global config.
+
 Config shape (per agent):
 
 ```json
@@ -306,15 +310,15 @@ Legacy string entries are still accepted and treated as `model`-only config.
 
 ## Commands
 
-| Command                          | What it does                                                 |
-| -------------------------------- | ------------------------------------------------------------ |
-| `/gentle-ai:status`              | Shows package, SDD asset, OpenSpec, and model config status. |
-| `/gentle:models`                 | Opens model + effort assignment UI.                          |
-| `/gentle:persona`                | Switches persona mode.                                       |
-| `/sdd-init`                      | Initializes or refreshes `openspec/config.yaml`.             |
-| `/gentle-ai:install-sdd`         | Reinstalls SDD assets without overwriting local files.       |
-| `/gentle-ai:install-sdd --force` | Force-refreshes installed SDD assets.                        |
-| `/skill-registry:refresh`        | Regenerates `.atl/skill-registry.md`.                        |
+| Command                          | What it does                                                        |
+| -------------------------------- | ------------------------------------------------------------------- |
+| `/gentle-ai:status`              | Shows package, SDD asset, OpenSpec, and global model config status. |
+| `/gentle:models`                 | Opens global model + effort assignment UI.                          |
+| `/gentle:persona`                | Switches persona mode.                                              |
+| `/sdd-init`                      | Initializes or refreshes `openspec/config.yaml`.                    |
+| `/gentle-ai:install-sdd`         | Reinstalls SDD assets without overwriting local files.              |
+| `/gentle-ai:install-sdd --force` | Force-refreshes installed SDD assets.                               |
+| `/skill-registry:refresh`        | Regenerates `.atl/skill-registry.md`.                               |
 
 Startup flag:
 

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";
@@ -25,10 +32,26 @@ import {
 
 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";
 
@@ -76,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[] = [
@@ -115,6 +138,10 @@ interface AgentRoutingEntry {
 	thinking?: ThinkingLevel;
 }
 type AgentModelConfig = Record<string, AgentRoutingEntry>;
+type ModelConfigFileResult =
+	| { status: "missing" }
+	| { status: "invalid"; path: string }
+	| { status: "valid"; config: AgentModelConfig };
 type AgentSource = "project" | "user" | "builtin";
 
 interface AgentEntry {
@@ -194,7 +221,15 @@ function isRecord(value: unknown): value is Record<string, unknown> {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
-function modelConfigPath(cwd: string): string {
+function gentleAiConfigHome(): string {
+	return process.env.GENTLE_PI_CONFIG_HOME ?? join(homedir(), ".pi", "gentle-ai");
+}
+
+function modelConfigPath(_cwd: string): string {
+	return join(gentleAiConfigHome(), "models.json");
+}
+
+function legacyProjectModelConfigPath(cwd: string): string {
 	return join(cwd, ".pi", "gentle-ai", "models.json");
 }
 
@@ -246,23 +281,72 @@ function normalizeRoutingEntry(value: unknown): AgentRoutingEntry | undefined {
 	return { model, thinking };
 }
 
-export function readModelConfig(cwd: string): AgentModelConfig {
-	const path = modelConfigPath(cwd);
-	if (!existsSync(path)) return {};
+function readModelConfigFile(path: string): ModelConfigFileResult {
+	if (!existsSync(path)) return { status: "missing" };
 	try {
 		const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
-		if (!isRecord(parsed)) return {};
+		if (!isRecord(parsed)) return { status: "invalid", path };
+		const config: AgentModelConfig = {};
+		for (const [name, value] of Object.entries(parsed)) {
+			const entry = normalizeRoutingEntry(value);
+			if (entry) config[name] = entry;
+		}
+		return { status: "valid", config };
+	} catch {
+		return { status: "invalid", path };
+	}
+}
+
+async function readModelConfigFileAsync(
+	path: string,
+): Promise<ModelConfigFileResult> {
+	if (!(await pathExists(path))) return { status: "missing" };
+	try {
+		const parsed: unknown = JSON.parse(await readFile(path, "utf8"));
+		if (!isRecord(parsed)) return { status: "invalid", path };
 		const config: AgentModelConfig = {};
 		for (const [name, value] of Object.entries(parsed)) {
 			const entry = normalizeRoutingEntry(value);
 			if (entry) config[name] = entry;
 		}
-		return config;
+		return { status: "valid", config };
 	} catch {
-		return {};
+		return { status: "invalid", path };
 	}
 }
 
+function readSavedModelConfig(cwd: string): ModelConfigFileResult {
+	const globalResult = readModelConfigFile(modelConfigPath(cwd));
+	if (globalResult.status !== "missing") return globalResult;
+	const legacyResult = readModelConfigFile(legacyProjectModelConfigPath(cwd));
+	if (legacyResult.status === "invalid") return { status: "valid", config: {} };
+	return legacyResult;
+}
+
+async function readSavedModelConfigAsync(
+	cwd: string,
+): Promise<ModelConfigFileResult> {
+	const globalResult = await readModelConfigFileAsync(modelConfigPath(cwd));
+	if (globalResult.status !== "missing") return globalResult;
+	const legacyResult = await readModelConfigFileAsync(
+		legacyProjectModelConfigPath(cwd),
+	);
+	if (legacyResult.status === "invalid") return { status: "valid", config: {} };
+	return legacyResult;
+}
+
+export function readModelConfig(cwd: string): AgentModelConfig {
+	const result = readSavedModelConfig(cwd);
+	return result.status === "valid" ? result.config : {};
+}
+
+export async function readModelConfigAsync(
+	cwd: string,
+): Promise<AgentModelConfig> {
+	const result = await readSavedModelConfigAsync(cwd);
+	return result.status === "valid" ? result.config : {};
+}
+
 function writeModelConfig(cwd: string, config: AgentModelConfig): void {
 	const path = modelConfigPath(cwd);
 	mkdirSync(dirname(path), { recursive: true });
@@ -323,6 +407,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[] = [];
@@ -339,6 +440,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 => {
@@ -348,6 +473,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"),
@@ -373,6 +511,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");
 }
@@ -417,6 +586,46 @@ function updateBuiltinModelOverride(
 	return true;
 }
 
+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,
@@ -446,6 +655,49 @@ export 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 };
+}
+
+export async function applySavedModelConfig(
+	ctx: ExtensionContext,
+): Promise<{ updated: number; skipped: number; invalidPath?: string }> {
+	const result = await readSavedModelConfigAsync(ctx.cwd);
+	if (result.status === "invalid") {
+		return { updated: 0, skipped: 0, invalidPath: result.path };
+	}
+	return applyModelConfigAsync(
+		ctx.cwd,
+		result.status === "valid" ? result.config : {},
+	);
+}
+
 function describeModelConfig(cwd: string, config: AgentModelConfig): string[] {
 	return listDiscoverableAgents(cwd).map((agent) => {
 		const entry = config[agent.name];
@@ -836,7 +1088,15 @@ async function showSddModelPanel(
 }
 
 async function handleModelsCommand(ctx: ExtensionContext): Promise<void> {
-	let config = readModelConfig(ctx.cwd);
+	const savedConfig = await readSavedModelConfigAsync(ctx.cwd);
+	if (savedConfig.status === "invalid") {
+		ctx.ui.notify(
+			`el Gentleman cannot open model config because ${savedConfig.path} is invalid JSON or not an object. Fix or remove the file, then run /gentle:models again.`,
+			"warning",
+		);
+		return;
+	}
+	let config = savedConfig.status === "valid" ? savedConfig.config : {};
 	let result = await showSddModelPanel(ctx, config);
 	while (result.type === "custom") {
 		config = cloneModelConfig(result.config);
@@ -874,11 +1134,11 @@ async function handleModelsCommand(ctx: ExtensionContext): Promise<void> {
 	}
 	if (result.type !== "save") return;
 	writeModelConfig(ctx.cwd, result.config);
-	const applyResult = applyModelConfig(ctx.cwd, result.config);
+	const applyResult = await applyModelConfigAsync(ctx.cwd, result.config);
 	ctx.ui.notify(
 		[
-			"el Gentleman model config saved.",
-			`Config: ${modelConfigPath(ctx.cwd)}`,
+			"el Gentleman global model config saved.",
+			`Global config: ${modelConfigPath(ctx.cwd)}`,
 			`Agents updated: ${applyResult.updated}`,
 			...describeModelConfig(ctx.cwd, result.config),
 		].join("\n"),
@@ -909,17 +1169,35 @@ export default function gentleAi(pi: ExtensionAPI): void {
 		return ensureSddPreflight(ctx, {
 			pi,
 			installAssets: (cwd) => installSddAssets(cwd, false),
-			applyModelConfig: (cwd) => applyModelConfig(cwd, readModelConfig(cwd)),
+			applyModelConfig: async () => applySavedModelConfig(ctx),
 		});
 	}
 
-	pi.on("session_start", (_event, ctx) => {
-		const modelResult = applyModelConfig(ctx.cwd, readModelConfig(ctx.cwd));
-		if (ctx.hasUI && modelResult.updated > 0) {
-			ctx.ui.notify(
-				`el Gentleman applied SDD model config to ${modelResult.updated} agent(s).`,
-				"info",
-			);
+	pi.on("session_start", async (_event, ctx) => {
+		try {
+			const modelResult = await applySavedModelConfig(ctx);
+			if (ctx.hasUI && modelResult.invalidPath) {
+				ctx.ui.notify(
+					`el Gentleman skipped model config because ${modelResult.invalidPath} is invalid JSON or not an object. Fix or remove the file, then run /gentle:models again.`,
+					"warning",
+				);
+				return;
+			}
+			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",
+				);
+			}
 		}
 	});
 
@@ -975,7 +1253,7 @@ export default function gentleAi(pi: ExtensionAPI): void {
 	});
 
 	pi.registerCommand("gentle:models", {
-		description: "Configure per-agent models for el Gentleman.",
+		description: "Configure global per-agent models for el Gentleman.",
 		handler: async (_args, ctx) => {
 			await handleModelsCommand(ctx);
 		},
@@ -1028,7 +1306,7 @@ export default function gentleAi(pi: ExtensionAPI): void {
 			const openspecConfigured = existsSync(
 				join(ctx.cwd, "openspec", "config.yaml"),
 			);
-			const modelConfig = readModelConfig(ctx.cwd);
+			const modelConfig = await readModelConfigAsync(ctx.cwd);
 			ctx.ui.notify(
 				[
 					"el Gentleman package is active.",
@@ -1036,7 +1314,7 @@ export default function gentleAi(pi: ExtensionAPI): void {
 					`SDD agents: ${agentsInstalled ? "installed" : "not installed"}`,
 					`SDD chains: ${chainsInstalled ? "installed" : "not installed"}`,
 					`OpenSpec config: ${openspecConfigured ? "present" : "missing"}`,
-					`Model config: ${existsSync(modelConfigPath(ctx.cwd)) ? "present" : "missing"}`,
+					`Global model config: ${existsSync(modelConfigPath(ctx.cwd)) ? "present" : "missing"}`,
 					...describeModelConfig(ctx.cwd, modelConfig),
 				].join("\n"),
 				"info",

package/extensions/sdd-init.ts

@@ -6,7 +6,7 @@ import {
 	writeFileSync,
 } from "node:fs";
 import { basename, dirname, join, relative } from "node:path";
-import { applyModelConfig, readModelConfig } from "./gentle-ai.ts";
+import { applySavedModelConfig } from "./gentle-ai.ts";
 import { ensureSddPreflight, installSddAssets } from "../lib/sdd-preflight.ts";
 type ExtensionAPI = any;
 
@@ -778,7 +778,7 @@ export default function (pi: ExtensionAPI) {
 			await ensureSddPreflight(ctx, {
 				pi,
 				installAssets: (cwd) => installSddAssets(cwd, false),
-				applyModelConfig: (cwd) => applyModelConfig(cwd, readModelConfig(cwd)),
+				applyModelConfig: () => applySavedModelConfig(ctx),
 			});
 			const configPath = join(ctx.cwd, CONFIG_REL_PATH);
 			if (existsSync(configPath)) {