gentle-pi 0.10.9 → 0.11.0

package/assets/orchestrator.md

@@ -188,103 +188,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 Workflow (lazy-loaded)
 
-SDD phases:
+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:
 
-```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.
+`{{GENTLE_PI_SDD_WORKFLOW_PATH}}`
 
-## Init Guard
+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.
 
-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 +237,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 +283,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,153 @@
+# 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.
+
+## 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

@@ -123,12 +123,18 @@ function sddLocalOverrideDriftCount(cwd: string): number {
 }
 
 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;
 }

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.0",
   "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',

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");