gentle-pi 0.11.0 → 0.11.1

package/README.md

@@ -119,7 +119,7 @@ The goal is not ceremony. The goal is to avoid accidental chaos. Once a task sto
 
 ### Delegation triggers
 
-`gentle-pi` keeps the parent session thin and delegates at the narrowest useful point. When the Pi Subagents extension is installed, the preferred runtime is the `subagent_*` tool family because it runs the user's configured project/global subagent definitions and preserves history/background behavior. If those tools are unavailable, the parent should fall back to Pi's native `Agent` tool or another available delegation mechanism. The requirement is delegation; the runtime is capability-dependent.
+`gentle-pi` keeps the parent session thin and delegates at the narrowest useful point. When the Pi Subagents extension is installed, the preferred runtime is the `subagent_*` tool family because it runs the user's configured project/global subagent definitions and preserves history/background behavior. Use waiting/task mode when the parent must consume the result and continue the workflow; use background mode only for independent work where parent continuation is not required. If those tools are unavailable, the parent should fall back to Pi's native `Agent` tool or another available delegation mechanism. The requirement is delegation; the runtime is capability-dependent.
 
 | Trigger                                                                                                                     | Required behavior                                                             |
 | --------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |

package/assets/agents/sdd-init.md

@@ -7,6 +7,7 @@ tools:
   - grep
   - glob
   - write
+  - edit
   - bash
   - mem_search
   - mem_get_observation

package/assets/orchestrator.md

@@ -82,7 +82,12 @@ Examples:
 - run tests/builds and summarize results;
 - fresh-context review.
 
-Use the configured subagent runtime when available. Prefer the `subagent_*` tools (`subagent_run`, status/result helpers) when the Pi Subagents extension is installed, because they run the user's configured project/global subagent definitions and preserve history/background behavior. Prefer `subagent_run` with `mode: "background"` for long independent exploration, implementation, tests, or review, and `mode: "task"` when the parent needs the result before continuing.
+Use the configured subagent runtime when available. Prefer the `subagent_*` tools (`subagent_run`, status/result helpers) when the Pi Subagents extension is installed, because they run the user's configured project/global subagent definitions and preserve history/background behavior.
+
+Choose subagent mode by orchestration dependency, not by task length:
+
+- Use `mode: "task"` when the parent must consume the result and continue the workflow, including SDD phases, implementation batches, verification, review gates, and any delegated work whose output determines the next action.
+- Use `mode: "background"` only for independent work where automatic parent continuation is not required. Background completion may notify the user and preserve history, but it is not a guarantee that the parent model will resume orchestration.
 
 If `subagent_*` tools are unavailable, fall back to Pi's native `Agent` tool or another available delegation mechanism. The delegation trigger remains mandatory; the fallback changes the runtime, not the requirement to delegate. If no delegation mechanism is available, stop the complex work and explain the blocker instead of silently continuing inline.
 

package/assets/sdd-orchestrator-workflow.md

@@ -132,6 +132,10 @@ skill_resolution
 
 The parent should synthesize these envelopes, not paste long raw reports unless needed.
 
+## SDD Phase Delegation Mode
+
+Launch SDD phase subagents with `subagent_run` `mode: "task"` when the parent needs the phase result to route the next step. Do not use `mode: "background"` for SDD phases that must feed continuation; background completion is a notification/history mechanism, not an orchestration resume guarantee.
+
 ## Strict TDD Forwarding
 
 For `sdd-apply` and `sdd-verify`, read `openspec/config.yaml` when present.

package/extensions/gentle-ai.ts

@@ -93,33 +93,26 @@ function sddGlobalAssetDriftCount(): number {
 	return stale;
 }
 
-function sddLocalOverrideDriftCount(cwd: string): number {
-	let stale = 0;
-	for (const [assetSubdir, installedSubdir] of [
-		["agents", join(".pi", "agents")],
-		["chains", join(".pi", "chains")],
-		["support", join(".pi", "gentle-ai", "support")],
-	] as const) {
-		const assetDir = join(ASSETS_DIR, assetSubdir);
-		const installedDir = join(cwd, installedSubdir);
-		if (!existsSync(assetDir) || !existsSync(installedDir)) continue;
-		for (const entry of readdirSync(assetDir, { withFileTypes: true })) {
-			if (!entry.isFile()) continue;
-			const installedPath = join(installedDir, entry.name);
-			if (!existsSync(installedPath)) continue;
-			try {
-				if (
-					readFileSync(join(assetDir, entry.name), "utf8") !==
-					readFileSync(installedPath, "utf8")
-				) {
-					stale += 1;
-				}
-			} catch {
-				stale += 1;
-			}
-		}
-	}
-	return stale;
+function sddLocalAgentOverrideCount(cwd: string): number {
+	const packageSddAgentsDir = join(ASSETS_DIR, "agents");
+	const packageSddAgentNames = existsSync(packageSddAgentsDir)
+		? new Set(
+				readdirSync(packageSddAgentsDir, { withFileTypes: true })
+					.filter((entry) => entry.isFile() && /^sdd-.*\.md$/i.test(entry.name))
+					.map((entry) => entry.name),
+			)
+		: new Set<string>();
+	let count = 0;
+	for (const installedDir of [
+		join(cwd, ".pi", "agents"),
+		join(cwd, ".pi", "subagents"),
+	]) {
+		if (!existsSync(installedDir)) continue;
+		for (const entry of readdirSync(installedDir, { withFileTypes: true })) {
+			if (entry.isFile() && packageSddAgentNames.has(entry.name)) count += 1;
+		}
+	}
+	return count;
 }
 
 let orchestratorPromptCache: string | null = null;
@@ -2302,7 +2295,7 @@ export default function gentleAi(pi: ExtensionAPI): void {
 				join(ctx.cwd, ".atl", "skill-registry.md"),
 			);
 			const staleSddAssets = sddGlobalAssetDriftCount();
-			const staleLocalOverrides = sddLocalOverrideDriftCount(ctx.cwd);
+			const localSddAgentOverrides = sddLocalAgentOverrideCount(ctx.cwd);
 			const modelConfig = await readSavedModelConfigAsync(ctx.cwd);
 			const engramActive = hasWritableEngramTool(pi);
 			const lines = [
@@ -2310,7 +2303,7 @@ export default function gentleAi(pi: ExtensionAPI): void {
 				`${agentsInstalled ? "pass" : "fail"}: Global SDD agents ${agentsInstalled ? "installed" : "missing"}`,
 				`${chainsInstalled ? "pass" : "fail"}: Global SDD chains ${chainsInstalled ? "installed" : "missing"}`,
 				`${staleSddAssets === 0 ? "pass" : "warn"}: Global SDD asset drift ${staleSddAssets} file(s)`,
-				`${staleLocalOverrides === 0 ? "pass" : "warn"}: Project-local SDD override drift ${staleLocalOverrides} file(s)`,
+				`${localSddAgentOverrides === 0 ? "pass" : "warn"}: Project-local SDD agent overrides ${localSddAgentOverrides} file(s)`,
 				`${openspecConfigured ? "pass" : "warn"}: OpenSpec config ${openspecConfigured ? "present" : "missing"}`,
 				`${skillRegistryPresent ? "pass" : "warn"}: Skill registry ${skillRegistryPresent ? "present" : "missing"}`,
 				`${modelConfig.status === "invalid" ? "fail" : "pass"}: Global model config ${modelConfig.status}`,
@@ -2323,6 +2316,9 @@ export default function gentleAi(pi: ExtensionAPI): void {
 			if (modelConfig.status === "invalid") {
 				lines.push(`remedy: fix or remove ${modelConfig.path}`);
 			}
+			if (localSddAgentOverrides > 0) {
+				lines.push("remedy: remove project-local SDD agent overrides unless intentionally debugging package assets");
+			}
 			ctx.ui.notify(
 				lines.join("\n"),
 				lines.some((line) => line.startsWith("fail:")) ? "warning" : "info",
@@ -2343,7 +2339,7 @@ export default function gentleAi(pi: ExtensionAPI): void {
 				join(ctx.cwd, "openspec", "config.yaml"),
 			);
 			const staleSddAssets = sddGlobalAssetDriftCount();
-			const staleLocalOverrides = sddLocalOverrideDriftCount(ctx.cwd);
+			const localSddAgentOverrides = sddLocalAgentOverrideCount(ctx.cwd);
 			const modelConfig = await readModelConfigAsync(ctx.cwd);
 			ctx.ui.notify(
 				[
@@ -2356,16 +2352,16 @@ export default function gentleAi(pi: ExtensionAPI): void {
 							? " — run /gentle-ai:install-sdd --force to refresh intentionally"
 							: ""
 					}`,
-					`Project-local SDD override drift: ${staleLocalOverrides} file(s)${
-						staleLocalOverrides > 0
-							? " — run /gentle-ai:install-sdd --force only if you intentionally want to replace local overrides"
+					`Project-local SDD agent overrides: ${localSddAgentOverrides} file(s)${
+						localSddAgentOverrides > 0
+							? " — local SDD agents shadow package assets; remove them unless intentionally debugging"
 							: ""
 					}`,
 					`OpenSpec config: ${openspecConfigured ? "present" : "missing"}`,
 					`Global model config: ${existsSync(modelConfigPath(ctx.cwd)) ? "present" : "missing"}`,
 					...describeModelConfig(ctx.cwd, modelConfig),
 				].join("\n"),
-				staleSddAssets > 0 || staleLocalOverrides > 0 ? "warning" : "info",
+				staleSddAssets > 0 || localSddAgentOverrides > 0 ? "warning" : "info",
 			);
 		},
 	});

package/package.json

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

@@ -673,12 +673,13 @@ async function run() {
 		await mkdir(join(staleAssetsCwd, ".pi", "gentle-ai", "support"), { recursive: true });
 		await writeFile(join(staleAssetsCwd, ".pi", "agents", "sdd-apply.md"), "stale apply\n");
 		await writeFile(join(staleAssetsCwd, ".pi", "agents", "sdd-spec.md"), "stale spec\n");
+		await writeFile(join(staleAssetsCwd, ".pi", "agents", "sdd-custom-debug.md"), "custom debug agent\n");
 		await writeFile(join(staleAssetsCwd, ".pi", "chains", "sdd-full.chain.md"), "stale chain\n");
 		await writeFile(join(staleAssetsCwd, ".pi", "gentle-ai", "support", "sdd-status-contract.md"), "stale status contract\n");
 		const ctx = createCtx(staleAssetsCwd, true);
 		await commands.get("gentle-ai:status").handler("", ctx);
-		assert.match(ctx.ui.notifications.at(-1).message, /Project-local SDD override drift: \d+ file\(s\)/);
-		assert.match(ctx.ui.notifications.at(-1).message, /gentle-ai:install-sdd --force/);
+		assert.match(ctx.ui.notifications.at(-1).message, /Project-local SDD agent overrides: 2 file\(s\)/);
+		assert.match(ctx.ui.notifications.at(-1).message, /local SDD agents shadow package assets/);
 		await commands.get("gentle-ai:doctor").handler("", ctx);
 		assert.match(ctx.ui.notifications.at(-1).message, /el Gentleman doctor/);
 		assert.match(ctx.ui.notifications.at(-1).message, /Sensitive-path guard active/);

package/tests/sdd-agent-tools.test.ts

@@ -0,0 +1,70 @@
+import assert from "node:assert/strict";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import test from "node:test";
+
+const repoRoot = process.cwd();
+const assetsAgentsDir = join(repoRoot, "assets", "agents");
+
+function readFrontmatter(path: string): string {
+	const text = readFileSync(path, "utf8");
+	const match = text.match(/^---\n([\s\S]*?)\n---/);
+	assert.ok(match, `${path} must have YAML frontmatter`);
+	return match[1];
+}
+
+function readTools(path: string): string[] {
+	const frontmatter = readFrontmatter(path);
+	const lines = frontmatter.split("\n");
+	const toolsIndex = lines.findIndex((line) => line === "tools:");
+	assert.notEqual(toolsIndex, -1, `${path} must declare tools as a YAML array`);
+
+	const scalarTools = lines.find((line) => /^tools:\s+/.test(line));
+	assert.equal(scalarTools, undefined, `${path} must not declare scalar comma-separated tools`);
+
+	const tools: string[] = [];
+	for (const line of lines.slice(toolsIndex + 1)) {
+		if (!line.startsWith("  - ")) break;
+		tools.push(line.slice(4).trim());
+	}
+	assert.ok(tools.length > 0, `${path} must declare at least one tool`);
+	return tools;
+}
+
+const requiredToolsByAgent: Record<string, string[]> = {
+	"sdd-apply.md": ["read", "grep", "glob", "edit", "write", "bash", "mem_search", "mem_get_observation", "mem_save", "mem_update"],
+	"sdd-archive.md": ["read", "grep", "glob", "edit", "write", "bash", "mem_search", "mem_get_observation", "mem_save"],
+	"sdd-design.md": ["read", "grep", "glob", "edit", "write", "mem_search", "mem_get_observation", "mem_save"],
+	"sdd-explore.md": ["read", "grep", "glob", "mem_save"],
+	"sdd-init.md": ["read", "grep", "glob", "edit", "write", "bash", "mem_search", "mem_get_observation", "mem_save", "mem_update"],
+	"sdd-onboard.md": ["read", "grep", "glob", "edit", "write", "bash", "mem_search", "mem_get_observation", "mem_save", "mem_update"],
+	"sdd-proposal.md": ["read", "grep", "glob", "edit", "write", "mem_search", "mem_get_observation", "mem_save"],
+	"sdd-spec.md": ["read", "grep", "glob", "edit", "write", "mem_search", "mem_get_observation", "mem_save"],
+	"sdd-status.md": ["read", "grep", "glob", "bash", "mem_search", "mem_get_observation"],
+	"sdd-sync.md": ["read", "grep", "glob", "edit", "write", "bash", "mem_search", "mem_get_observation", "mem_save", "mem_update"],
+	"sdd-tasks.md": ["read", "grep", "glob", "edit", "write", "mem_search", "mem_get_observation", "mem_save"],
+	"sdd-verify.md": ["read", "grep", "glob", "edit", "write", "bash", "mem_search", "mem_get_observation", "mem_save"],
+};
+
+test("SDD package agents declare role-appropriate tools as YAML arrays", () => {
+	for (const [fileName, requiredTools] of Object.entries(requiredToolsByAgent)) {
+		const path = join(assetsAgentsDir, fileName);
+		assert.ok(existsSync(path), `${fileName} must exist`);
+		const tools = readTools(path);
+		for (const tool of requiredTools) {
+			assert.ok(tools.includes(tool), `${fileName} must include ${tool}`);
+		}
+		for (const tool of tools) {
+			assert.ok(!tool.startsWith("subagent_"), `${fileName} must not allow child subagent tool ${tool}`);
+		}
+	}
+});
+
+test("project does not ship local SDD agent overrides", () => {
+	for (const relativeDir of [join(".pi", "agents"), join(".pi", "subagents")]) {
+		const dir = join(repoRoot, relativeDir);
+		if (!existsSync(dir)) continue;
+		const overrides = readdirSync(dir).filter((entry) => /^sdd-.*\.md$/i.test(entry));
+		assert.deepEqual(overrides, [], `${relativeDir} must not shadow package SDD agents`);
+	}
+});