gentle-pi 0.10.9 → 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.
 
@@ -188,103 +193,15 @@ stop writes → parent captures git status → selected review lens audits affec
 
 If multiple rows match, run the narrow set that covers the risk. Example: shell integration that mutates live state should use `review-reliability` plus `review-resilience`, not `review-readability` by default.
 
-## SDD Workflow
-
-SDD phases:
-
-```text
-init → explore → proposal → spec → design → tasks → apply → verify → sync → archive
-```
-
-Dependency graph:
-
-```text
-proposal → spec ─┬→ tasks → apply → verify → sync → archive
-proposal → design ┘
-```
-
-`/sdd-status [change]` is the read-only status action for resolving the active change, artifact paths, task progress, dependency readiness, and action context before apply/verify/sync/archive.
-
-## Native SDD Dispatcher
-
-The user expresses intent; they should not have to administer phases manually. For natural-language SDD requests and `/sdd-continue`, the parent/orchestrator must use the native status engine as the state authority, decide the next phase, and delegate only the phase that status marks ready.
-
-Flow:
-
-```text
-user intent → preflight/init guard → native status engine → phase decision → subagent gets status JSON + generated instructions → artifact/progress write → status recalculation → continue or stop
-```
-
-Rules:
-
-- `/sdd-status` is a debug/status command, not the main UX.
-- `/sdd-continue` is the native dispatcher command: resolve status, choose the next ready phase, and carry status/instructions into the subagent prompt.
-- `sdd-apply`, `sdd-verify`, `sdd-sync`, and `sdd-archive` must obey parent-provided native status; they must not reconstruct readiness from prompt inference when status JSON is present.
-- Do not launch a phase when native status marks that dependency `blocked`.
-- `sdd-archive` cannot proceed unless native status says `dependencies.archive` is `ready` or `all_done` — UNLESS the store carve-out is active (`nextRecommended: "resolve-via-engram"`), in which case resolve archive readiness from Engram instead of treating `not_applicable` as a gate failure.
-- **Non-authoritative store carve-out:** when `nextRecommended: "resolve-via-engram"` is set, native status is **not authoritative**. This applies to `artifactStore: engram`, `artifactStore: none`, and `artifactStore: both` when the `openspec/` directory does not exist. For non-authoritative stores: resolve readiness from Engram using the Engram memory tools injected by the memory provider on the change topic keys (`sdd/{change-name}/proposal`, `sdd/{change-name}/spec`, `sdd/{change-name}/design`, `sdd/{change-name}/tasks`, etc.). Do **not** treat `blockedReasons` or `not_applicable` dependency states from the native engine as real blockers when the store carve-out is active.
-
-## SDD Status Contract
-
-Before `/sdd-continue`, `sdd-apply`, `sdd-verify`, `sdd-sync`, or `sdd-archive`, resolve and carry structured status. Lookup order: parent-provided status, then project override `.pi/gentle-ai/support/sdd-status-contract.md`, then globally installed `~/.pi/agent/gentle-ai/support/sdd-status-contract.md`, then the embedded `sdd-status` prompt contract. Do not use `assets/support/...` as a runtime path; that is only the package source path before installation.
-
-Status must include:
-
-- active change selection and how it was resolved;
-- artifact store and paths/topics for proposal, specs, design, tasks, apply-progress, verify-report, and sync-report;
-- task progress with exact unchecked `- [ ]` implementation task lines;
-- dependency states for apply, verify, sync, and archive;
-- `actionContext` with mode, workspace root, allowed edit roots, and warnings;
-- next recommended action.
-
-Do not guess the active change. If change selection is ambiguous, ask the user and stop. If `actionContext.mode: workspace-planning` and no allowed edit roots are provided, stop before apply/verify/sync/archive and ask for an explicit implementation/edit scope.
-
-## Lazy SDD Preflight
+## SDD Workflow (lazy-loaded)
 
-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 detailed SDD workflow is intentionally not embedded in this always-on parent prompt. Before handling any `/sdd-*` command, natural-language SDD request, SDD continuation/routing, apply/verify/sync/archive work, or SDD/Judgment-Day phase delegation, read this package asset first:
 
-**Hard gate:** `openspec/config.yaml`, existing SDD changes, installed `.pi`/global SDD assets, or a todo named "preflight" are not session preflight. They are project context only. Do not mark SDD preflight complete, start `sdd-init`, launch SDD subagents/chains, or move to explore/proposal/spec/design/tasks until this session has either:
-
-1. an injected `## SDD Session Preflight` block, or
-2. an explicit user answer in the current conversation covering all four preflight choices below.
-
-If neither exists and `/gentle-ai:sdd-preflight` cannot be invoked from the current context, ask the four choices manually with `ask_user_question` before any SDD phase work. Treat missing Engram availability as a reason to ask/confirm artifact store, not as permission to assume defaults.
-
-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.
-
-The package should ensure SDD assets are present as global Pi runtime assets without the user needing to remember per-project setup commands. If assets are missing, install them non-destructively into:
-
-```text
-~/.pi/agent/agents/sdd-*.md
-~/.pi/agent/chains/sdd-*.chain.md
-```
+`{{GENTLE_PI_SDD_WORKFLOW_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.
+That lazy surface contains the SDD phases, native dispatcher rules, status contract, preflight/init guards, artifact-store policy, execution mode, Strict TDD forwarding, phase result contract, and review workload guard.
 
-## Init Guard
-
-Before any SDD flow, make sure project context exists.
-
-In this Pi package, the default local artifact is:
-
-```text
-openspec/config.yaml
-```
-
-If it is missing, ask the user for the minimal information needed or run `/sdd-init` if available. This init guard runs after the session preflight gate above; project config presence or absence never substitutes for session preflight choices. Do not proceed with a substantial SDD flow while pretending project context, testing capability, or session preflight choices are known.
-
-## Artifact Store Policy
-
-This package does not provide persistent memory by itself.
-
-- Default: `openspec` artifacts in the repo.
-- If a separate memory package is installed and callable, memory/hybrid flows may be used.
-- Never claim memory exists because Gentle AI is installed.
+Hard preflight invariant: `openspec/config.yaml`, existing SDD changes, installed `.pi`/global SDD assets, or a todo named "preflight" are not session preflight. Do not mark SDD preflight complete, start `sdd-init`, launch SDD subagents/chains, or move to explore/proposal/spec/design/tasks until this session has either an injected `## SDD Session Preflight` block or an explicit user answer covering the preflight choices.
 
 ## Memory Contract
 
@@ -325,38 +242,6 @@ Memory lifecycle rule (when Engram exposes lifecycle metadata/tooling):
 - When a retrieved memory is marked `needs_review`, surface that stale context to the user and verify it against current evidence before relying on it.
 - Do NOT call the injected Engram review tool with action `mark_reviewed` automatically. Only call `mark_reviewed` after explicit user confirmation or through a dedicated memory maintenance command.
 
-## Execution Mode
-
-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.
-
-In interactive mode, between phases:
-
-1. show concise phase result;
-2. state next phase;
-3. ask whether to continue or adjust.
-
-Interactive approval is phase-scoped. A user response such as "continue", "dale", or "go on" approves only the immediate next phase, not the rest of the SDD pipeline. Do not treat a generated artifact as approved until the user has had a chance to review or explicitly delegate that review.
-
-Before `sdd-proposal` in interactive mode, offer the user a proposal question round instead of silently deciding whether the proposal is clear enough. Explain that the questions are meant to improve the PRD/proposal by uncovering business understanding, business rules, implications, impact, edge cases, and product tradeoffs. Prefer 3–5 concrete product questions per round, then summarize the resulting assumptions and ask whether the user wants to correct anything or run a second question round. Cover business/product/PRD decisions: business problem, target users and situations, business rules, product outcome, current-state gap, implications and impact, edge cases, decision gaps, first-slice scope boundaries, non-goals, product constraints, and business tradeoffs. Do not ask about test commands, PR shape, changed-line budget, or other harness mechanics at proposal time unless the user explicitly asks to discuss delivery.
-
-## Result Contract
-
-Every phase result should include:
-
-```text
-status
-executive_summary
-artifacts
-next_recommended
-risks
-skill_resolution
-```
-
-The parent should synthesize these envelopes, not paste long raw reports unless needed.
-
 ## Skill Registry Protocol
 
 The parent resolves skills once per session or before first delegation:
@@ -403,26 +288,6 @@ Common intent hints, not hard routing:
 
 Keep this lightweight: loading a skill should improve the immediate task, not force extra ceremony.
 
-## Strict TDD Forwarding
-
-For `sdd-apply` and `sdd-verify`, read `openspec/config.yaml` when present.
-
-If it declares strict TDD and a test command, include a non-negotiable instruction in the phase prompt:
-
-```text
-STRICT TDD MODE IS ACTIVE. Test runner: <command>. Follow RED, GREEN, TRIANGULATE, REFACTOR. Record evidence.
-```
-
-Do not rely on the child agent to discover this independently.
-
-## Review Workload Guard
-
-After `sdd-tasks` and before `sdd-apply`, inspect the task output for review workload risk.
-
-If estimated changed lines exceed 400, chained PRs are recommended, or a decision is needed, pause and ask unless the user already approved a delivery strategy.
-
-Automatic mode does not override reviewer burnout protection.
-
 ## Safety
 
 - Never commit unless the user explicitly asks.

package/assets/sdd-orchestrator-workflow.md

@@ -0,0 +1,157 @@
+# SDD Orchestrator Workflow
+
+This is the lazy-loaded SDD workflow surface for el Gentleman on Pi. Read this file before handling `/sdd-*`, natural-language SDD requests, SDD continuation/routing, apply/verify/sync/archive work, or SDD/Judgment-Day phase delegation.
+
+## SDD Workflow
+
+SDD phases:
+
+```text
+init → explore → proposal → spec → design → tasks → apply → verify → sync → archive
+```
+
+Dependency graph:
+
+```text
+proposal → spec ─┬→ tasks → apply → verify → sync → archive
+proposal → design ┘
+```
+
+`/sdd-status [change]` is the read-only status action for resolving the active change, artifact paths, task progress, dependency readiness, and action context before apply/verify/sync/archive.
+
+## Native SDD Dispatcher
+
+The user expresses intent; they should not have to administer phases manually. For natural-language SDD requests and `/sdd-continue`, the parent/orchestrator must use the native status engine as the state authority, decide the next phase, and delegate only the phase that status marks ready.
+
+Flow:
+
+```text
+user intent → preflight/init guard → native status engine → phase decision → subagent gets status JSON + generated instructions → artifact/progress write → status recalculation → continue or stop
+```
+
+Rules:
+
+- `/sdd-status` is a debug/status command, not the main UX.
+- `/sdd-continue` is the native dispatcher command: resolve status, choose the next ready phase, and carry status/instructions into the subagent prompt.
+- `sdd-apply`, `sdd-verify`, `sdd-sync`, and `sdd-archive` must obey parent-provided native status; they must not reconstruct readiness from prompt inference when status JSON is present.
+- Do not launch a phase when native status marks that dependency `blocked`.
+- `sdd-archive` cannot proceed unless native status says `dependencies.archive` is `ready` or `all_done` — UNLESS the store carve-out is active (`nextRecommended: "resolve-via-engram"`), in which case resolve archive readiness from Engram instead of treating `not_applicable` as a gate failure.
+- **Non-authoritative store carve-out:** when `nextRecommended: "resolve-via-engram"` is set, native status is **not authoritative**. This applies to `artifactStore: engram`, `artifactStore: none`, and `artifactStore: both` when the `openspec/` directory does not exist. For non-authoritative stores: resolve readiness from Engram using the Engram memory tools injected by the memory provider on the change topic keys (`sdd/{change-name}/proposal`, `sdd/{change-name}/spec`, `sdd/{change-name}/design`, `sdd/{change-name}/tasks`, etc.). Do **not** treat `blockedReasons` or `not_applicable` dependency states from the native engine as real blockers when the store carve-out is active.
+
+## SDD Status Contract
+
+Before `/sdd-continue`, `sdd-apply`, `sdd-verify`, `sdd-sync`, or `sdd-archive`, resolve and carry structured status. Lookup order: parent-provided status, then project override `.pi/gentle-ai/support/sdd-status-contract.md`, then globally installed `~/.pi/agent/gentle-ai/support/sdd-status-contract.md`, then the embedded `sdd-status` prompt contract. Do not use `assets/support/...` as a runtime path; that is only the package source path before installation.
+
+Status must include:
+
+- active change selection and how it was resolved;
+- artifact store and paths/topics for proposal, specs, design, tasks, apply-progress, verify-report, and sync-report;
+- task progress with exact unchecked `- [ ]` implementation task lines;
+- dependency states for apply, verify, sync, and archive;
+- `actionContext` with mode, workspace root, allowed edit roots, and warnings;
+- next recommended action.
+
+Do not guess the active change. If change selection is ambiguous, ask the user and stop. If `actionContext.mode: workspace-planning` and no allowed edit roots are provided, stop before apply/verify/sync/archive and ask for an explicit implementation/edit scope.
+
+## Lazy SDD Preflight
+
+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.
+
+**Hard gate:** `openspec/config.yaml`, existing SDD changes, installed `.pi`/global SDD assets, or a todo named "preflight" are not session preflight. They are project context only. Do not mark SDD preflight complete, start `sdd-init`, launch SDD subagents/chains, or move to explore/proposal/spec/design/tasks until this session has either:
+
+1. an injected `## SDD Session Preflight` block, or
+2. an explicit user answer in the current conversation covering all four preflight choices below.
+
+If neither exists and `/gentle-ai:sdd-preflight` cannot be invoked from the current context, ask the four choices manually with `ask_user_question` before any SDD phase work. Treat missing Engram availability as a reason to ask/confirm artifact store, not as permission to assume defaults.
+
+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.
+
+The package should ensure SDD assets are present as global Pi runtime assets without the user needing to remember per-project setup commands. If assets are missing, install them non-destructively into:
+
+```text
+~/.pi/agent/agents/sdd-*.md
+~/.pi/agent/chains/sdd-*.chain.md
+```
+
+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
+
+Before any SDD flow, make sure project context exists.
+
+In this Pi package, the default local artifact is:
+
+```text
+openspec/config.yaml
+```
+
+If it is missing, ask the user for the minimal information needed or run `/sdd-init` if available. This init guard runs after the session preflight gate above; project config presence or absence never substitutes for session preflight choices. Do not proceed with a substantial SDD flow while pretending project context, testing capability, or session preflight choices are known.
+
+## Artifact Store Policy
+
+This package does not provide persistent memory by itself.
+
+- Default: `openspec` artifacts in the repo.
+- If a separate memory package is installed and callable, memory/hybrid flows may be used.
+- Never claim memory exists because Gentle AI is installed.
+
+## Execution Mode
+
+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.
+
+In interactive mode, between phases:
+
+1. show concise phase result;
+2. state next phase;
+3. ask whether to continue or adjust.
+
+Interactive approval is phase-scoped. A user response such as "continue", "dale", or "go on" approves only the immediate next phase, not the rest of the SDD pipeline. Do not treat a generated artifact as approved until the user has had a chance to review or explicitly delegate that review.
+
+Before `sdd-proposal` in interactive mode, offer the user a proposal question round instead of silently deciding whether the proposal is clear enough. Explain that the questions are meant to improve the PRD/proposal by uncovering business understanding, business rules, implications, impact, edge cases, and product tradeoffs. Prefer 3–5 concrete product questions per round, then summarize the resulting assumptions and ask whether the user wants to correct anything or run a second question round. Cover business/product/PRD decisions: business problem, target users and situations, business rules, product outcome, current-state gap, implications and impact, edge cases, decision gaps, first-slice scope boundaries, non-goals, product constraints, and business tradeoffs. Do not ask about test commands, PR shape, changed-line budget, or other harness mechanics at proposal time unless the user explicitly asks to discuss delivery.
+
+## Result Contract
+
+Every phase result should include:
+
+```text
+status
+executive_summary
+artifacts
+next_recommended
+risks
+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.
+
+If it declares strict TDD and a test command, include a non-negotiable instruction in the phase prompt:
+
+```text
+STRICT TDD MODE IS ACTIVE. Test runner: <command>. Follow RED, GREEN, TRIANGULATE, REFACTOR. Record evidence.
+```
+
+Do not rely on the child agent to discover this independently.
+
+## Review Workload Guard
+
+After `sdd-tasks` and before `sdd-apply`, inspect the task output for review workload risk.
+
+If estimated changed lines exceed 400, chained PRs are recommended, or a decision is needed, pause and ask unless the user already approved a delivery strategy.
+
+Automatic mode does not override reviewer burnout protection.

package/extensions/gentle-ai.ts

@@ -93,42 +93,41 @@ 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;
+function getSddWorkflowPath(): string {
+	return join(ASSETS_DIR, "sdd-orchestrator-workflow.md");
+}
+
 function getOrchestratorPrompt(): string {
 	if (orchestratorPromptCache === null) {
 		orchestratorPromptCache = readFileSync(
 			join(ASSETS_DIR, "orchestrator.md"),
 			"utf8",
-		).trim();
+		)
+			.replaceAll("{{GENTLE_PI_SDD_WORKFLOW_PATH}}", getSddWorkflowPath())
+			.trim();
 	}
 	return orchestratorPromptCache;
 }
@@ -2296,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 = [
@@ -2304,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}`,
@@ -2317,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",
@@ -2337,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(
 				[
@@ -2350,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/extensions/skill-registry.ts

@@ -21,7 +21,7 @@ const EXCLUDE_NAMES = new Set(["_shared", "skill-registry"]);
 const EXCLUDE_PREFIXES = ["sdd-"];
 const ATL_IGNORE_ENTRY = ".atl/";
 const WATCH_DEBOUNCE_MS = 500;
-const REGISTRY_SCHEMA_VERSION = 5;
+const REGISTRY_SCHEMA_VERSION = 6;
 const NO_SKILL_REGISTRY_FLAG = "no-skill-registry";
 const NO_SKILL_REGISTRY_ENV = "GENTLE_PI_NO_SKILL_REGISTRY";
 const LEGACY_PROJECT_REGISTRY_REL_PATH = ".pi/extensions/skill-registry.ts";
@@ -96,23 +96,30 @@ function projectSkillDirs(cwd: string): string[] {
 
 async function findSkillFiles(root: string): Promise<string[]> {
 	if (!(await pathExists(root))) return [];
+	let entries;
+	try {
+		entries = await readdir(root, { withFileTypes: true });
+	} catch {
+		return [];
+	}
+
 	const out: string[] = [];
-	const stack: string[] = [root];
-	while (stack.length > 0) {
-		const dir = stack.pop()!;
-		let entries;
+	for (const entry of entries) {
+		const skillDir = join(root, entry.name);
+		let dirInfo;
 		try {
-			entries = await readdir(dir, { withFileTypes: true });
+			dirInfo = await stat(skillDir);
 		} catch {
 			continue;
 		}
-		for (const entry of entries) {
-			const full = join(dir, entry.name);
-			if (entry.isDirectory()) {
-				stack.push(full);
-			} else if (entry.isFile() && entry.name === "SKILL.md") {
-				out.push(full);
-			}
+		if (!dirInfo.isDirectory()) continue;
+
+		const candidate = join(skillDir, "SKILL.md");
+		try {
+			const skillInfo = await stat(candidate);
+			if (skillInfo.isFile()) out.push(candidate);
+		} catch {
+			// Missing or unreadable skill files are ignored; the registry is best-effort.
 		}
 	}
 	return out.sort();
@@ -512,6 +519,7 @@ async function startSkillRegistryWatcher(
 export const __testing = {
 	projectSkillDirs,
 	userSkillDirs,
+	findSkillFiles,
 	uniqueExistingDirs,
 	dedupeBySkillName,
 	scopeForPath,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gentle-pi",
-  "version": "0.10.9",
+  "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/artifact-language.test.ts

@@ -146,6 +146,21 @@ test("SDD chain assets distinguish interactive gates from auto execution", async
 	assert.match(fullChain, /must stop at each phase boundary/i);
 });
 
+test("orchestrator lazy-loads detailed SDD workflow", async () => {
+	const orchestrator = await readFile(join(ROOT, "assets/orchestrator.md"), "utf8");
+	const workflow = await readFile(join(ROOT, "assets/sdd-orchestrator-workflow.md"), "utf8");
+
+	assert.match(orchestrator, /## SDD Workflow \(lazy-loaded\)/);
+	assert.match(orchestrator, /\{\{GENTLE_PI_SDD_WORKFLOW_PATH\}\}/);
+	assert.doesNotMatch(orchestrator, /## Native SDD Dispatcher/);
+	assert.match(workflow, /## Native SDD Dispatcher/);
+	assert.match(workflow, /## SDD Status Contract/);
+	assert.match(workflow, /## Execution Mode/);
+	assert.match(workflow, /## Strict TDD Forwarding/);
+	assert.match(workflow, /## Review Workload Guard/);
+	assert.match(workflow, /## Result Contract/);
+});
+
 test("persistent harness prompt assets do not hardcode Spanish SDD artifact copy", async () => {
 	const files = [
 		...(await collectTextFiles(join(ROOT, "assets"))),

package/tests/runtime-harness.mjs

@@ -203,6 +203,11 @@ async function run() {
 		assert.doesNotMatch(promptResult.systemPrompt, /default\s*\|\s*sonnet\s*\|\s*Non-SDD general delegation/);
 		assert.match(promptResult.systemPrompt, /openspec\/config\.yaml.*not session preflight/s);
 		assert.match(promptResult.systemPrompt, /Do not mark SDD preflight complete/);
+		assert.match(
+			promptResult.systemPrompt,
+			new RegExp(`${ROOT.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}.*assets.*sdd-orchestrator-workflow\\.md`),
+		);
+		assert.doesNotMatch(promptResult.systemPrompt, /\{\{GENTLE_PI_SDD_WORKFLOW_PATH\}\}/);
 		await writeFile(
 			join(globalConfigHome, "persona.json"),
 			'{"mode":"neutral"}\n',
@@ -668,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`);
+	}
+});

package/tests/skill-registry.test.ts

@@ -1,5 +1,5 @@
 import assert from "node:assert/strict";
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync, symlinkSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import test from "node:test";
@@ -114,6 +114,36 @@ test("uniqueExistingDirs normalizes duplicates and ignores missing roots", async
 	);
 });
 
+test("findSkillFiles scans one skill directory level only", async () => {
+	const root = join(tmpdir(), `gentle-pi-shallow-${Date.now()}`);
+	const skillPath = join(root, "docs", "SKILL.md");
+	const nestedSkillPath = join(root, "fixtures", "nested", "SKILL.md");
+	mkdirSync(dirname(skillPath), { recursive: true });
+	mkdirSync(dirname(nestedSkillPath), { recursive: true });
+	writeFileSync(skillPath, "---\nname: docs\ndescription: Docs.\n---\n");
+	writeFileSync(nestedSkillPath, "---\nname: nested\ndescription: Nested fixture.\n---\n");
+
+	assert.deepEqual(await __testing.findSkillFiles(root), [skillPath]);
+});
+
+test("findSkillFiles follows symlinked skill directories", async (t) => {
+	const root = join(tmpdir(), `gentle-pi-symlink-root-${Date.now()}`);
+	const realSkillDir = join(tmpdir(), `gentle-pi-symlink-target-${Date.now()}`);
+	const linkedSkillDir = join(root, "linked");
+	const skillPath = join(linkedSkillDir, "SKILL.md");
+	mkdirSync(root, { recursive: true });
+	mkdirSync(realSkillDir, { recursive: true });
+	writeFileSync(join(realSkillDir, "SKILL.md"), "---\nname: linked\ndescription: Linked skill.\n---\n");
+	try {
+		symlinkSync(realSkillDir, linkedSkillDir, "dir");
+	} catch (error) {
+		t.skip(`symlink creation unavailable: ${error instanceof Error ? error.message : String(error)}`);
+		return;
+	}
+
+	assert.deepEqual(await __testing.findSkillFiles(root), [skillPath]);
+});
+
 test("skill registry watchers close on shutdown", async () => {
 	const root = join(tmpdir(), `gentle-pi-watchers-${Date.now()}`);
 	const skillPath = join(root, "skills", "docs", "SKILL.md");