gentle-pi 0.3.1 → 0.3.3

package/README.md

@@ -49,7 +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.                       |
+| **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.                                                                       |
@@ -87,10 +87,10 @@ pi
 ## Quick start
 
 ```text
-/gentle-ai:status          Check package, SDD assets, OpenSpec, and model config.
+/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 models to SDD/custom agents.
+/gentle:models             Assign global model/effort routing to SDD/custom agents.
 /gentle:persona            Switch between gentleman and neutral persona modes.
 ```
 
@@ -284,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
@@ -308,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

@@ -130,6 +130,7 @@ const SDD_AGENT_NAMES = [
 	"sdd-verify",
 	"sdd-archive",
 ] as const;
+const SDD_AGENT_NAME_SET = new Set<string>(SDD_AGENT_NAMES);
 
 type SddAgentName = (typeof SDD_AGENT_NAMES)[number];
 type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
@@ -138,6 +139,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 {
@@ -166,6 +171,34 @@ const MODEL_CONTROL_OPTIONS = [
 	CUSTOM_MODEL,
 ] as const;
 
+function readStringPath(value: unknown, path: string[]): string | undefined {
+	let current = value;
+	for (const key of path) {
+		if (!isRecord(current)) return undefined;
+		current = current[key];
+	}
+	return typeof current === "string" ? current : undefined;
+}
+
+function isSddAgentStartEvent(event: unknown): boolean {
+	const candidates = [
+		readStringPath(event, ["agentName"]),
+		readStringPath(event, ["agent"]),
+		readStringPath(event, ["name"]),
+		readStringPath(event, ["agent", "name"]),
+		readStringPath(event, ["subagent", "name"]),
+	]
+		.filter((value): value is string => value !== undefined)
+		.map((value) => value.trim());
+	if (candidates.some((value) => SDD_AGENT_NAME_SET.has(value))) return true;
+
+	const systemPrompt = readStringPath(event, ["systemPrompt"]) ?? "";
+	return SDD_AGENT_NAMES.some((name) => {
+		const phase = name.replace(/^sdd-/, "");
+		return new RegExp(`\\bSDD ${phase} executor\\b`, "i").test(systemPrompt);
+	});
+}
+
 function evaluateDeniedCommand(
 	command: string,
 ): ToolCallEventResult | undefined {
@@ -217,7 +250,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");
 }
 
@@ -269,42 +310,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 config;
+		return { status: "valid", config };
 	} catch {
-		return {};
+		return { status: "invalid", path };
 	}
 }
 
-export async function readModelConfigAsync(
-	cwd: string,
-): Promise<AgentModelConfig> {
-	const path = modelConfigPath(cwd);
-	if (!(await pathExists(path))) return {};
+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 {};
+		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 });
@@ -643,6 +714,19 @@ export async function applyModelConfigAsync(
 	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];
@@ -1033,7 +1117,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);
@@ -1071,11 +1163,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"),
@@ -1106,15 +1198,20 @@ export default function gentleAi(pi: ExtensionAPI): void {
 		return ensureSddPreflight(ctx, {
 			pi,
 			installAssets: (cwd) => installSddAssets(cwd, false),
-			applyModelConfig: async (cwd) =>
-				applyModelConfigAsync(cwd, await readModelConfigAsync(cwd)),
+			applyModelConfig: async () => applySavedModelConfig(ctx),
 		});
 	}
 
 	pi.on("session_start", async (_event, ctx) => {
 		try {
-			const config = await readModelConfigAsync(ctx.cwd);
-			const modelResult = await applyModelConfigAsync(ctx.cwd, config);
+			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).`,
@@ -1141,7 +1238,10 @@ export default function gentleAi(pi: ExtensionAPI): void {
 		return { action: "continue" };
 	});
 
-	pi.on("before_agent_start", (event, ctx) => {
+	pi.on("before_agent_start", async (event, ctx) => {
+		if (isSddAgentStartEvent(event) && !getSddPreflightPreferences(ctx)) {
+			await runSddPreflight(ctx);
+		}
 		const prefs = getSddPreflightPreferences(ctx);
 		const sddPrompt = prefs ? `\n\n${renderSddPreflightPrompt(prefs)}` : "";
 		return {
@@ -1185,7 +1285,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);
 		},
@@ -1238,7 +1338,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.",
@@ -1246,7 +1346,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 { applyModelConfigAsync, readModelConfigAsync } from "./gentle-ai.ts";
+import { applySavedModelConfig } from "./gentle-ai.ts";
 import { ensureSddPreflight, installSddAssets } from "../lib/sdd-preflight.ts";
 type ExtensionAPI = any;
 
@@ -778,8 +778,7 @@ export default function (pi: ExtensionAPI) {
 			await ensureSddPreflight(ctx, {
 				pi,
 				installAssets: (cwd) => installSddAssets(cwd, false),
-				applyModelConfig: async (cwd) =>
-					applyModelConfigAsync(cwd, await readModelConfigAsync(cwd)),
+				applyModelConfig: () => applySavedModelConfig(ctx),
 			});
 			const configPath = join(ctx.cwd, CONFIG_REL_PATH);
 			if (existsSync(configPath)) {

package/lib/sdd-preflight.ts

@@ -40,8 +40,8 @@ interface SddPreflightCallbacks {
 	applyModelConfig?: (
 		cwd: string,
 	) =>
-		| { updated: number; skipped: number }
-		| Promise<{ updated: number; skipped: number }>;
+		| { updated: number; skipped: number; invalidPath?: string }
+		| Promise<{ updated: number; skipped: number; invalidPath?: string }>;
 }
 
 const DEFAULT_SDD_PREFLIGHT: SddPreflightPreferences = {
@@ -238,6 +238,9 @@ export async function ensureSddPreflight(
 			skipped: 0,
 		};
 		if (ctx.hasUI) {
+			const modelRoutingLine = modelResult.invalidPath
+				? `Model routing skipped: ${modelResult.invalidPath} is invalid JSON or not an object.`
+				: `Model-routed agents updated: ${modelResult.updated}`;
 			ctx.ui.notify(
 				[
 					"Gentle AI SDD preflight complete.",
@@ -246,9 +249,9 @@ export async function ensureSddPreflight(
 					`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}`,
+					modelRoutingLine,
 				].join("\n"),
-				"info",
+				modelResult.invalidPath ? "warning" : "info",
 			);
 		}
 		sddPreflightBySession.set(sessionKey, prefs);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gentle-pi",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "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

@@ -137,6 +137,9 @@ async function loadExtensions(pi) {
 }
 
 async function run() {
+	const globalConfigHome = await tempWorkspace();
+	process.env.GENTLE_PI_CONFIG_HOME = globalConfigHome;
+	const globalModelsPath = join(globalConfigHome, "models.json");
 	const { pi, hooks, commands, flags } = createPi();
 	await loadExtensions(pi);
 
@@ -159,9 +162,14 @@ async function run() {
 	const promptCwd = await tempWorkspace();
 	try {
 		const promptHook = hooks.get("before_agent_start")[0];
-		const promptResult = promptHook({ systemPrompt: "base" }, createCtx(promptCwd));
+		const promptResult = await promptHook({ systemPrompt: "base" }, createCtx(promptCwd));
 		assert.match(promptResult.systemPrompt, /base/);
 		assert.match(promptResult.systemPrompt, /el Gentleman/);
+		assert.equal(
+			existsSync(join(promptCwd, ".pi", "agents", "sdd-apply.md")),
+			false,
+			"normal agent startup must not run SDD preflight",
+		);
 	} finally {
 		await rm(promptCwd, { recursive: true, force: true });
 	}
@@ -201,9 +209,8 @@ async function run() {
 
 	const lazySddCwd = await tempWorkspace();
 	try {
-		await mkdir(join(lazySddCwd, ".pi", "gentle-ai"), { recursive: true });
 		await writeFile(
-			join(lazySddCwd, ".pi", "gentle-ai", "models.json"),
+			globalModelsPath,
 			JSON.stringify({ "sdd-apply": { model: "openai/gpt-5", thinking: "high" } }, null, 2),
 		);
 		const ctx = createCtx(lazySddCwd, true);
@@ -295,11 +302,12 @@ async function run() {
 		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);
+		const promptResult = await 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 });
+		await rm(globalModelsPath, { force: true });
 	}
 
 	const commandSddCwd = await tempWorkspace();
@@ -314,6 +322,47 @@ async function run() {
 		await rm(commandSddCwd, { recursive: true, force: true });
 	}
 
+	const sddAgentGuardCwd = await tempWorkspace();
+	try {
+		const ctx = createCtx(sddAgentGuardCwd, true, "sdd-agent-guard-session");
+		const promptHook = hooks.get("before_agent_start")[0];
+		const promptResult = await promptHook(
+			{
+				systemPrompt: "You are the SDD proposal executor for Gentle AI.",
+			},
+			ctx,
+		);
+		assert.equal(existsSync(join(sddAgentGuardCwd, ".pi", "agents", "sdd-apply.md")), true);
+		assert.equal(existsSync(join(sddAgentGuardCwd, ".pi", "chains", "sdd-full.chain.md")), true);
+		assert.equal(ctx.ui.selections.length, 3);
+		assert.match(promptResult.systemPrompt, /SDD Session Preflight/);
+		assert.match(ctx.ui.notifications.at(-1).message, /SDD preflight complete/);
+
+		await promptHook(
+			{
+				agentName: "sdd-tasks",
+				systemPrompt: "You are the SDD tasks executor for Gentle AI.",
+			},
+			ctx,
+		);
+		assert.equal(ctx.ui.selections.length, 3, "SDD agent guard should reuse session choices");
+	} finally {
+		await rm(sddAgentGuardCwd, { recursive: true, force: true });
+	}
+
+	const invalidPreflightCwd = await tempWorkspace();
+	try {
+		await writeFile(globalModelsPath, "{ invalid json");
+		const ctx = createCtx(invalidPreflightCwd, true, "invalid-preflight-session");
+		await commands.get("gentle-ai:sdd-preflight").handler("", ctx);
+		assert.equal(ctx.ui.notifications.at(-1).level, "warning");
+		assert.match(ctx.ui.notifications.at(-1).message, /Model routing skipped:/);
+		assert.match(ctx.ui.notifications.at(-1).message, /invalid JSON or not an object/);
+	} finally {
+		await rm(invalidPreflightCwd, { recursive: true, force: true });
+		await rm(globalModelsPath, { force: true });
+	}
+
 	const engramSddCwd = await tempWorkspace();
 	try {
 		pi.setActiveTools(["read", "bash", "edit", "write", "mem_save"]);
@@ -350,6 +399,92 @@ async function run() {
 		await rm(sddCwd, { recursive: true, force: true });
 	}
 
+	const invalidSddInitCwd = await tempWorkspace();
+	try {
+		await mkdir(join(invalidSddInitCwd, ".pi", "agents"), { recursive: true });
+		await writeFile(
+			join(invalidSddInitCwd, ".pi", "agents", "sdd-apply.md"),
+			`---\nname: sdd-apply\ndescription: Apply phase\nmodel: keep/provider-model\n---\n\nbody\n`,
+		);
+		await writeFile(globalModelsPath, "{ invalid json");
+		const ctx = createCtx(invalidSddInitCwd, true, "invalid-sdd-init-session");
+		await commands.get("sdd-init").handler("", ctx);
+		assert.equal(ctx.ui.notifications[0].level, "warning");
+		assert.match(ctx.ui.notifications[0].message, /Model routing skipped:/);
+		assert.match(ctx.ui.notifications[0].message, /models\.json/);
+		assert.match(ctx.ui.notifications.at(-1).message, /Wrote openspec\/config\.yaml/);
+		const preservedAgent = await readFile(
+			join(invalidSddInitCwd, ".pi", "agents", "sdd-apply.md"),
+			"utf8",
+		);
+		assert.match(preservedAgent, /model: keep\/provider-model/);
+	} finally {
+		await rm(invalidSddInitCwd, { recursive: true, force: true });
+		await rm(globalModelsPath, { force: true });
+	}
+
+	const legacyModelsCwd = await tempWorkspace();
+	try {
+		await mkdir(join(legacyModelsCwd, ".pi", "agents"), { recursive: true });
+		await mkdir(join(legacyModelsCwd, ".pi", "gentle-ai"), { recursive: true });
+		await writeFile(
+			join(legacyModelsCwd, ".pi", "agents", "sdd-apply.md"),
+			`---\nname: sdd-apply\ndescription: Apply phase\n---\n\nbody\n`,
+		);
+		await writeFile(
+			join(legacyModelsCwd, ".pi", "gentle-ai", "models.json"),
+			JSON.stringify({ "sdd-apply": "legacy/provider-model" }, null, 2),
+		);
+		const legacyCtx = createCtx(legacyModelsCwd, true);
+		await hooks.get("session_start")[0]({ reason: "startup" }, legacyCtx);
+		const legacyAgent = await readFile(
+			join(legacyModelsCwd, ".pi", "agents", "sdd-apply.md"),
+			"utf8",
+		);
+		assert.match(legacyAgent, /model: legacy\/provider-model/);
+		await writeFile(
+			globalModelsPath,
+			JSON.stringify({ "sdd-apply": "global/provider-model" }, null, 2),
+		);
+		await hooks.get("session_start")[0]({ reason: "startup" }, legacyCtx);
+		const globalWinsAgent = await readFile(
+			join(legacyModelsCwd, ".pi", "agents", "sdd-apply.md"),
+			"utf8",
+		);
+		assert.match(globalWinsAgent, /model: global\/provider-model/);
+		assert.doesNotMatch(globalWinsAgent, /model: legacy\/provider-model/);
+		await writeFile(globalModelsPath, "{ invalid json");
+		await hooks.get("session_start")[0]({ reason: "startup" }, legacyCtx);
+		const invalidGlobalSkippedAgent = await readFile(
+			join(legacyModelsCwd, ".pi", "agents", "sdd-apply.md"),
+			"utf8",
+		);
+		assert.match(invalidGlobalSkippedAgent, /model: global\/provider-model/);
+		assert.doesNotMatch(invalidGlobalSkippedAgent, /model: legacy\/provider-model/);
+		assert.equal(legacyCtx.ui.notifications.at(-1).level, "warning");
+		assert.match(legacyCtx.ui.notifications.at(-1).message, /skipped model config/);
+		let modelPanelOpened = false;
+		legacyCtx.ui.custom = () => {
+			modelPanelOpened = true;
+			return Promise.resolve({ type: "save", config: {} });
+		};
+		await commands.get("gentle:models").handler("", legacyCtx);
+		assert.equal(modelPanelOpened, false);
+		assert.equal(await readFile(globalModelsPath, "utf8"), "{ invalid json");
+		assert.equal(legacyCtx.ui.notifications.at(-1).level, "warning");
+		assert.match(legacyCtx.ui.notifications.at(-1).message, /cannot open model config/);
+		await writeFile(globalModelsPath, JSON.stringify({}, null, 2));
+		await hooks.get("session_start")[0]({ reason: "startup" }, legacyCtx);
+		const emptyGlobalSuppressesLegacyAgent = await readFile(
+			join(legacyModelsCwd, ".pi", "agents", "sdd-apply.md"),
+			"utf8",
+		);
+		assert.doesNotMatch(emptyGlobalSuppressesLegacyAgent, /model:/);
+	} finally {
+		await rm(legacyModelsCwd, { recursive: true, force: true });
+		await rm(globalModelsPath, { force: true });
+	}
+
 	const modelsCwd = await tempWorkspace();
 	try {
 		await mkdir(join(modelsCwd, ".pi", "agents"), { recursive: true });
@@ -373,9 +508,8 @@ async function run() {
 			join(modelsCwd, ".pi", "agents", "sdd-apply.md"),
 			`---\nname: sdd-apply\ndescription: Apply phase\n---\n\nbody\n`,
 		);
-		await mkdir(join(modelsCwd, ".pi", "gentle-ai"), { recursive: true });
 		await writeFile(
-			join(modelsCwd, ".pi", "gentle-ai", "models.json"),
+			globalModelsPath,
 			JSON.stringify({ "sdd-apply": "openai/gpt-5" }, null, 2),
 		);
 
@@ -399,12 +533,17 @@ async function run() {
 		await commands.get("gentle:models").handler("", ctx);
 
 		const savedConfig = JSON.parse(
-			await readFile(join(modelsCwd, ".pi", "gentle-ai", "models.json"), "utf8"),
+			await readFile(globalModelsPath, "utf8"),
 		);
 		assert.deepEqual(savedConfig["sdd-apply"], {
 			model: "openai/gpt-5",
 			thinking: "high",
 		});
+		assert.equal(
+			existsSync(join(modelsCwd, ".pi", "gentle-ai", "models.json")),
+			false,
+			"/gentle:models must save model routing globally, not per project",
+		);
 
 		const applyAgent = await readFile(
 			join(modelsCwd, ".pi", "agents", "sdd-apply.md"),
@@ -440,7 +579,7 @@ async function run() {
 		await commands.get("gentle:models").handler("", ctx);
 
 		const customSavedConfig = JSON.parse(
-			await readFile(join(modelsCwd, ".pi", "gentle-ai", "models.json"), "utf8"),
+			await readFile(globalModelsPath, "utf8"),
 		);
 		assert.deepEqual(customSavedConfig["sdd-apply"], {
 			model: "custom/provider-model",
@@ -448,6 +587,7 @@ async function run() {
 		});
 	} finally {
 		await rm(modelsCwd, { recursive: true, force: true });
+		await rm(globalModelsPath, { force: true });
 	}
 
 	const registryCwd = await tempWorkspace();