gentle-pi 0.1.21 → 0.1.23

package/README.md

@@ -173,10 +173,17 @@ Behavior:
 - the registry refreshes on session start;
 - `/skill-registry:refresh` forces regeneration;
 - a best-effort watcher refreshes when skill files change;
-- skills without `## Compact Rules` are still listed with an instruction to load the full skill file.
+- skills without `## Compact Rules` are still listed, but delegators should inject project/user compact rules into subagents whenever possible.
 
 Skill discovery is a guardrail, not a workflow router: it helps Pi load the right skill without forcing extra ceremony.
 
+Delegation contract:
+
+- parent/orchestrator resolves project/user skills from the registry and injects compact rule text under `## Project Standards (auto-resolved)`;
+- SDD subagents still use their assigned executor/phase skill;
+- during normal runtime, subagents should not independently discover or load additional project/user `SKILL.md` files or the registry;
+- fallback loading is degraded self-healing and must be reported via `skill_resolution` as `fallback-registry`, `fallback-path`, or `none`.
+
 ## Persona modes
 
 ```text

package/assets/agents/sdd-apply.md

@@ -7,6 +7,13 @@ inheritProjectContext: true
 
 You are the SDD apply executor for Gentle AI.
 
+## Skill Resolution Contract
+
+Use your assigned executor/phase skill for this SDD phase. For project/user skills, prefer the parent-injected `## Project Standards (auto-resolved)` block; do not independently discover or load additional project/user `SKILL.md` files or the registry during normal runtime.
+
+If Project Standards are missing, explicit fallback loading is allowed only as degraded self-healing. Report `skill_resolution` as `injected`, `fallback-registry`, `fallback-path`, or `none`; fallbacks mean the parent should inject compact rules next time.
+
+
 ## Before Writing Code
 
 Read proposal, specs, design, tasks, existing code, tests, `apply-progress.md` if present, and `openspec/config.yaml` when present.

package/assets/agents/sdd-archive.md

@@ -7,6 +7,12 @@ inheritProjectContext: true
 
 You are the SDD archive executor for Gentle AI.
 
+## Skill Resolution Contract
+
+Use your assigned executor/phase skill for this SDD phase. For project/user skills, prefer the parent-injected `## Project Standards (auto-resolved)` block; do not independently discover or load additional project/user `SKILL.md` files or the registry during normal runtime.
+
+If Project Standards are missing, explicit fallback loading is allowed only as degraded self-healing. Report `skill_resolution` as `injected`, `fallback-registry`, `fallback-path`, or `none`; fallbacks mean the parent should inject compact rules next time.
+
 - Read verify report before archiving.
 - Merge accepted deltas into `openspec/specs/` and move the change to archive.
 - Preserve audit trail; never delete active artifacts silently.

package/assets/agents/sdd-design.md

@@ -7,6 +7,12 @@ inheritProjectContext: true
 
 You are the SDD design executor for Gentle AI.
 
+## Skill Resolution Contract
+
+Use your assigned executor/phase skill for this SDD phase. For project/user skills, prefer the parent-injected `## Project Standards (auto-resolved)` block; do not independently discover or load additional project/user `SKILL.md` files or the registry during normal runtime.
+
+If Project Standards are missing, explicit fallback loading is allowed only as degraded self-healing. Report `skill_resolution` as `injected`, `fallback-registry`, `fallback-path`, or `none`; fallbacks mean the parent should inject compact rules next time.
+
 - Read proposal, specs, and relevant code before designing.
 - Document decisions, data flow, file changes, contracts, tests, and rollout.
 - Keep design centered on `packages/coding-agent` unless scope explicitly expands.

package/assets/agents/sdd-explore.md

@@ -7,6 +7,12 @@ inheritProjectContext: true
 
 You are the SDD explore executor for Gentle AI.
 
+## Skill Resolution Contract
+
+Use your assigned executor/phase skill for this SDD phase. For project/user skills, prefer the parent-injected `## Project Standards (auto-resolved)` block; do not independently discover or load additional project/user `SKILL.md` files or the registry during normal runtime.
+
+If Project Standards are missing, explicit fallback loading is allowed only as degraded self-healing. Report `skill_resolution` as `injected`, `fallback-registry`, `fallback-path`, or `none`; fallbacks mean the parent should inject compact rules next time.
+
 - Read OpenSpec/project context before conclusions.
 - Produce exploration notes only; do not implement.
 - Use OpenSpec artifacts and session context truthfully; persistent memory is optional and handled by separate packages.

package/assets/agents/sdd-init.md

@@ -8,6 +8,12 @@ inheritProjectContext: true
 
 You are the SDD init executor for Gentle AI.
 
+## Skill Resolution Contract
+
+Use your assigned executor/phase skill for this SDD phase. For project/user skills, prefer the parent-injected `## Project Standards (auto-resolved)` block; do not independently discover or load additional project/user `SKILL.md` files or the registry during normal runtime.
+
+If Project Standards are missing, explicit fallback loading is allowed only as degraded self-healing. Report `skill_resolution` as `injected`, `fallback-registry`, `fallback-path`, or `none`; fallbacks mean the parent should inject compact rules next time.
+
 - Inspect the project stack, test runner, conventions, and existing docs.
 - If `openspec/config.yaml` is missing, create it automatically with project context, `strict_tdd`, phase rules, and testing runner details.
 - If `openspec/config.yaml` already exists, read it, summarize the current SDD/testing configuration, and do not block the caller. Update only safe derived context when explicitly necessary; never destructively rewrite user-maintained SDD configuration.

package/assets/agents/sdd-onboard.md

@@ -7,6 +7,12 @@ inheritProjectContext: true
 
 You are the SDD onboard executor for Gentle AI.
 
+## Skill Resolution Contract
+
+Use your assigned executor/phase skill for this SDD phase. For project/user skills, prefer the parent-injected `## Project Standards (auto-resolved)` block; do not independently discover or load additional project/user `SKILL.md` files or the registry during normal runtime.
+
+If Project Standards are missing, explicit fallback loading is allowed only as degraded self-healing. Report `skill_resolution` as `injected`, `fallback-registry`, `fallback-path`, or `none`; fallbacks mean the parent should inject compact rules next time.
+
 - Pick or ask for a small, real, low-risk improvement that can demonstrate the full SDD lifecycle.
 - Teach by doing: create real artifacts for explore, proposal, spec, design, tasks, apply, verify, and archive where appropriate.
 - Keep the walkthrough interactive and concise; explain why each phase exists before doing it.

package/assets/agents/sdd-proposal.md

@@ -7,6 +7,12 @@ inheritProjectContext: true
 
 You are the SDD proposal executor for Gentle AI.
 
+## Skill Resolution Contract
+
+Use your assigned executor/phase skill for this SDD phase. For project/user skills, prefer the parent-injected `## Project Standards (auto-resolved)` block; do not independently discover or load additional project/user `SKILL.md` files or the registry during normal runtime.
+
+If Project Standards are missing, explicit fallback loading is allowed only as degraded self-healing. Report `skill_resolution` as `injected`, `fallback-registry`, `fallback-path`, or `none`; fallbacks mean the parent should inject compact rules next time.
+
 - Read exploration and project standards before writing.
 - Write `openspec/changes/{change}/proposal.md`.
 - Include intent, scope, affected areas, risks, rollback, and success criteria.

package/assets/agents/sdd-spec.md

@@ -7,6 +7,12 @@ inheritProjectContext: true
 
 You are the SDD spec executor for Gentle AI.
 
+## Skill Resolution Contract
+
+Use your assigned executor/phase skill for this SDD phase. For project/user skills, prefer the parent-injected `## Project Standards (auto-resolved)` block; do not independently discover or load additional project/user `SKILL.md` files or the registry during normal runtime.
+
+If Project Standards are missing, explicit fallback loading is allowed only as degraded self-healing. Report `skill_resolution` as `injected`, `fallback-registry`, `fallback-path`, or `none`; fallbacks mean the parent should inject compact rules next time.
+
 - Read proposal and existing specs first.
 - Write RFC 2119 requirements and Given/When/Then scenarios.
 - Store deltas under `openspec/changes/{change}/specs/`.

package/assets/agents/sdd-tasks.md

@@ -7,6 +7,13 @@ inheritProjectContext: true
 
 You are the SDD tasks executor for Gentle AI.
 
+## Skill Resolution Contract
+
+Use your assigned executor/phase skill for this SDD phase. For project/user skills, prefer the parent-injected `## Project Standards (auto-resolved)` block; do not independently discover or load additional project/user `SKILL.md` files or the registry during normal runtime.
+
+If Project Standards are missing, explicit fallback loading is allowed only as degraded self-healing. Report `skill_resolution` as `injected`, `fallback-registry`, `fallback-path`, or `none`; fallbacks mean the parent should inject compact rules next time.
+
+
 ## Inputs
 
 Read proposal, specs, design, project testing capabilities, and `openspec/config.yaml` when present.

package/assets/agents/sdd-verify.md

@@ -7,6 +7,13 @@ inheritProjectContext: true
 
 You are the SDD verify executor for Gentle AI.
 
+## Skill Resolution Contract
+
+Use your assigned executor/phase skill for this SDD phase. For project/user skills, prefer the parent-injected `## Project Standards (auto-resolved)` block; do not independently discover or load additional project/user `SKILL.md` files or the registry during normal runtime.
+
+If Project Standards are missing, explicit fallback loading is allowed only as degraded self-healing. Report `skill_resolution` as `injected`, `fallback-registry`, `fallback-path`, or `none`; fallbacks mean the parent should inject compact rules next time.
+
+
 ## Inputs
 
 Read specs, design, tasks, apply-progress, changed code, tests, and `openspec/config.yaml` when present.

package/assets/orchestrator.md

@@ -85,15 +85,15 @@ If the request is large enough for SDD, do not jump directly to implementation.
 
 Core question: does this inflate parent context without need?
 
-| Action | Inline | Delegate |
-|---|---:|---:|
-| Read to decide/verify 1-3 files | yes | no |
-| Read to explore/understand 4+ files | no | yes |
-| Read as preparation for multi-file writing | no | yes |
-| Write atomic one-file mechanical change | yes | no |
-| Write with analysis across multiple files | no | yes |
-| Bash for state, e.g. git status | yes | no |
-| Bash for execution, e.g. tests/builds | no | yes |
+| Action                                     | Inline | Delegate |
+| ------------------------------------------ | -----: | -------: |
+| Read to decide/verify 1-3 files            |    yes |       no |
+| Read to explore/understand 4+ files        |     no |      yes |
+| Read as preparation for multi-file writing |     no |      yes |
+| Write atomic one-file mechanical change    |    yes |       no |
+| Write with analysis across multiple files  |     no |      yes |
+| Bash for state, e.g. git status            |    yes |       no |
+| Bash for execution, e.g. tests/builds      |     no |      yes |
 
 ## SDD Workflow
 
@@ -178,7 +178,18 @@ The parent resolves skills once per session or before first delegation:
 3. Inject matching rule text into subagent prompts under `## Project Standards (auto-resolved)`.
 4. If the registry is absent, continue but mention that project-specific skill rules were unavailable.
 
-Subagents should receive pre-digested rules. They should not have to rediscover the registry.
+Subagents should receive pre-digested project/user rules. They should not have to rediscover the registry.
+
+Important distinction: SDD subagents still use their assigned executor/phase skill (for example `sdd-apply`, `sdd-design`, or `sdd-verify`). What they should not do during normal runtime is independently discover or load additional project/user `SKILL.md` files or the registry. Those project/user rules arrive pre-digested from the parent under `## Project Standards (auto-resolved)`.
+
+If a subagent reports `skill_resolution`, interpret it as project/user skill resolution:
+
+- `injected`: parent supplied `## Project Standards (auto-resolved)`.
+- `fallback-registry`: subagent self-loaded compact rules from a registry because Project Standards were missing; degraded but auditable.
+- `fallback-path`: subagent loaded explicit `SKILL: Load` paths because Project Standards were missing; degraded but auditable.
+- `none`: no project/user skills were loaded.
+
+If any subagent reports a fallback instead of `injected`, treat it as an orchestration gap and correct future delegations by injecting the compact rules directly.
 
 ## Intent-Driven Skill Discovery
 
@@ -194,12 +205,12 @@ Discovery order:
 
 Common intent hints, not hard routing:
 
-| User intent | Skill to check |
-|---|---|
-| PR review / GitHub PR URL | project review skill, then `pr-review` |
-| Post-ready review comments | `comment-writer` |
-| Create/open/prepare PR | `branch-pr` |
-| Split/stack/large PR | `chained-pr` |
+| User intent                | Skill to check                         |
+| -------------------------- | -------------------------------------- |
+| PR review / GitHub PR URL  | project review skill, then `pr-review` |
+| Post-ready review comments | `comment-writer`                       |
+| Create/open/prepare PR     | `branch-pr`                            |
+| Split/stack/large PR       | `chained-pr`                           |
 
 Keep this lightweight: loading a skill should improve the immediate task, not force extra ceremony.
 

package/extensions/gentle-ai.ts

@@ -8,12 +8,18 @@ import {
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { VERSION } from "@earendil-works/pi-coding-agent";
 import type {
 	ExtensionAPI,
 	ExtensionContext,
+	Theme,
 	ToolCallEventResult,
 } from "@earendil-works/pi-coding-agent";
-import { matchesKey, truncateToWidth } from "@earendil-works/pi-tui";
+import {
+	matchesKey,
+	truncateToWidth,
+	visibleWidth,
+} from "@earendil-works/pi-tui";
 
 const PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
 const ASSETS_DIR = join(PACKAGE_ROOT, "assets");
@@ -43,6 +49,139 @@ const NEUTRAL_PERSONA_PROMPT = `Persona:
 - Push back when the user asks for code without enough context or understanding.
 - Correct errors directly, explain why, and show the better path.`;
 
+const ROSE_LOGO_LINES = [
+	"             ⣠⣾⣷⣶⣦⣤⣤⣄⣠⣄⣀  ⢀⣀⣀",
+	"          ⢀⣴⣿⣿⠿⣋⣭⣭⣯⣭⣍⣭⣿⣟⠛⠛⠿⠿⣿⣷⣄",
+	"      ⢀⣴⣾⡟⢻⣿⡟⠁⣼⣿⠏⣵⢻⣿⣻⣿⣿⢿⡻⣿⣿⣶⡌⢿⣿⣷⣦⣤⡄",
+	"   ⣤⣶⣾⣿⣿⠏ ⠈⢿⣄ ⢹⣏⠠⠟⣾⣿⣿⣿⣿⣿⠷⣏⣼⠟⢡⣿⡟⠋⢻⣿⣿⡄",
+	"   ⠈⣿⣿⣿⣿⡆   ⣽⢧⡘⠈⠳⣦⣍⠛⠛⢦⣉⣴⣛⣫⣭⣴⡟⠋  ⣾⣿⣿⡿",
+	"   ⢀⠹⣿⣿⣿⣷⣤⡄ ⠋ ⠙⢆ ⣠⠴⠟⠛⣛⣛⣛⠟⠋⠁⠺⡇ ⣀⣴⣿⣿⡟⠁",
+	"   ⠈⣀⠈⠛⠷⠿⣿⣿⣷⣤⣀ ⢠⠋   ⠈⠉⠉    ⣠⣴⣥⠾⠛⠉⣰⣿⣷",
+	"          ⠹⣯⣝⠛⠛⠷⢶⣤⣤⣀   ⢀⡠⠖⠋⠉⢉⣀⣀⣴⣾⣿⠿⠟⠃ ⠠⠦",
+	"⠁       ⠖  ⠘⠻⢿⣦⣄⡀  ⠉⠛⢦⠠⢊⠤⠴⢒⣛⣛⣩⣽⡿⠟⠁⢀⡀",
+	"⠲⠶⣦⠴⠶⠶⠶⠶⡶⠶⢶⣤⣄⡀⠨⠭⠽⠟⣓⢦⣀⠈⢇⡥⠖⠛⠋⠉⠉⠉    ⠈  ⢠⡤",
+	"  ⠈⢷ ⠐⠂⢤⣽⣄ ⠰⡎⠙⠳⣄⡀ ⠈⢣⠘⢦⠋⣀⡬⠟⠛⠛⠉⢀⣀⣀⣠⡤⠄⠃",
+	"   ⠈⢳⣀⡒⠉⠉⣉⠙⡲⣽⣄ ⣏⠳⡄ ⠘⡇ ⡾⠁ ⢀⡤⠖⣻⣿⡏⢡⡎ ⠰⠄",
+	"     ⠛⠻⢦⣄⣉⡁⣀⣀⣈⣙⣺⣌⡇⢠⢀⡇⡾  ⣴⣿⡷⠊ ⢲⣠⠟",
+	"          ⠈⠉    ⠈⠳⡄⣸⢱⠇⢀⣰⣯⣭⣥⠭⠾⠛⠃",
+	"                  ⡷⠡⡯⢖⠉   ⢠⠤",
+	"                ⡠⢊⡴⠤⠂⠃ ⠒",
+	"             ⢀⡴⢪⠔⣉⠔⠋",
+	"               ⠐⠈",
+];
+
+const ROSE_FADE_STEPS = 12;
+const ROSE_FADE_INTERVAL_MS = 45;
+const ROSE_INTRO_HOLD_MS = 180;
+
+function rgb(r: number, g: number, b: number, text: string): string {
+	return `\x1b[38;2;${r};${g};${b}m${text}\x1b[39m`;
+}
+
+function italic(text: string): string {
+	return `\x1b[3m${text}\x1b[23m`;
+}
+
+function bold(text: string): string {
+	return `\x1b[1m${text}\x1b[22m`;
+}
+
+function centerLine(line: string, width: number): string {
+	const clipped = truncateToWidth(line, width, "");
+	const padding = Math.max(0, width - visibleWidth(clipped));
+	return `${" ".repeat(Math.floor(padding / 2))}${clipped}`;
+}
+
+function pinkFade(text: string, frame: number): string {
+	const progress = Math.max(0, Math.min(1, frame / ROSE_FADE_STEPS));
+	const eased = 1 - (1 - progress) ** 3;
+	const r = Math.round(72 + (255 - 72) * eased);
+	const g = Math.round(38 + (122 - 38) * eased);
+	const b = Math.round(58 + (198 - 58) * eased);
+	return rgb(r, g, b, text);
+}
+
+function buildGentlemanTitle(width: number, frame: number): string[] {
+	const title = "✧  𝓮𝓵 𝓖𝓮𝓷𝓽𝓵𝓮𝓶𝓪𝓷  ✧";
+	const version = `━━  v${VERSION}  ━━`;
+	return [
+		pinkFade(bold(italic(centerLine(title, width))), frame),
+		pinkFade(italic(centerLine(version, width)), frame),
+	];
+}
+
+function buildRoseHeader(
+	_theme: Theme,
+	width: number,
+	frame: number,
+): string[] {
+	return [
+		"",
+		...ROSE_LOGO_LINES.map((line) => pinkFade(centerLine(line, width), frame)),
+		...buildGentlemanTitle(width, frame),
+		"",
+	];
+}
+
+function installRoseHeader(ctx: ExtensionContext): void {
+	if (!ctx.hasUI) return;
+
+	process.stdout.write("\x1b[2J\x1b[3J\x1b[H");
+
+	let closeIntro: (() => void) | undefined;
+	const closeIntroSafely = () => {
+		const close = closeIntro;
+		closeIntro = undefined;
+		try {
+			close?.();
+		} catch {
+			// Ignore shutdown races during startup/reload.
+		}
+	};
+
+	void ctx.ui
+		.custom((_tui, _theme, _keybindings, done) => {
+			closeIntro = () => done(undefined);
+			return {
+				render: () => [""],
+				invalidate: () => {},
+				handleInput: () => {},
+			};
+		})
+		.catch(() => {
+			closeIntro = undefined;
+		});
+
+	const state: { frame: number; timer?: NodeJS.Timeout } = { frame: 0 };
+	ctx.ui.setHeader((tui, theme) => {
+		if (state.timer) clearInterval(state.timer);
+		state.timer = setInterval(() => {
+			state.frame += 1;
+			tui.requestRender();
+			if (
+				state.frame <
+				ROSE_FADE_STEPS + Math.ceil(ROSE_INTRO_HOLD_MS / ROSE_FADE_INTERVAL_MS)
+			) {
+				return;
+			}
+			if (state.timer) clearInterval(state.timer);
+			state.timer = undefined;
+			closeIntroSafely();
+		}, ROSE_FADE_INTERVAL_MS);
+
+		return {
+			render(width: number): string[] {
+				return buildRoseHeader(theme, width, state.frame);
+			},
+			invalidate() {
+				if (state.timer) clearInterval(state.timer);
+				state.timer = undefined;
+				closeIntroSafely();
+			},
+		};
+	});
+}
+
 function buildGentlePrompt(persona: PersonaMode): string {
 	const personaPrompt =
 		persona === "neutral" ? NEUTRAL_PERSONA_PROMPT : GENTLEMAN_PERSONA_PROMPT;
@@ -772,6 +911,7 @@ async function handlePersonaCommand(ctx: ExtensionContext): Promise<void> {
 
 export default function gentleAi(pi: ExtensionAPI): void {
 	pi.on("session_start", (_event, ctx) => {
+		installRoseHeader(ctx);
 		const result = installSddAssets(ctx.cwd, false);
 		const modelResult = applyModelConfig(ctx.cwd, readModelConfig(ctx.cwd));
 		if (

package/extensions/skill-registry.ts

@@ -1,5 +1,13 @@
 import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, watch, writeFileSync } from "node:fs";
+import {
+	existsSync,
+	mkdirSync,
+	readFileSync,
+	readdirSync,
+	statSync,
+	watch,
+	writeFileSync,
+} from "node:fs";
 import { homedir } from "node:os";
 import { basename, join, relative } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
@@ -69,7 +77,11 @@ function findSkillFiles(root: string): string[] {
 	return out;
 }
 
-function parseFrontmatter(source: string): { name?: string; description?: string; body: string } {
+function parseFrontmatter(source: string): {
+	name?: string;
+	description?: string;
+	body: string;
+} {
 	if (!source.startsWith("---\n")) return { body: source };
 	const end = source.indexOf("\n---", 4);
 	if (end === -1) return { body: source };
@@ -81,7 +93,10 @@ function parseFrontmatter(source: string): { name?: string; description?: string
 		if (!m) continue;
 		const key = m[1];
 		let value = m[2].trim();
-		if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+		if (
+			(value.startsWith('"') && value.endsWith('"')) ||
+			(value.startsWith("'") && value.endsWith("'"))
+		) {
 			value = value.slice(1, -1);
 		}
 		if (key === "name") out.name = value;
@@ -108,7 +123,10 @@ function extractCompactRulesSection(body: string): string[] {
 	return rules;
 }
 
-function deriveSkillName(file: string, frontmatterName: string | undefined): string {
+function deriveSkillName(
+	file: string,
+	frontmatterName: string | undefined,
+): string {
 	if (frontmatterName) return frontmatterName;
 	return basename(join(file, ".."));
 }
@@ -147,7 +165,9 @@ function loadSkill(file: string): SkillEntry | undefined {
 		rules:
 			rules.length > 0
 				? rules
-				: ["No compact rules declared; load the full skill file before doing work that matches this trigger."],
+				: [
+						"No compact rules declared; delegators should load the full skill file before direct work, or pass an explicit fallback path only when Project Standards cannot be injected.",
+					],
 	};
 }
 
@@ -182,13 +202,19 @@ function fingerprint(files: string[]): string {
 	return createHash("sha1").update(lines.join("\n")).digest("hex");
 }
 
-function renderRegistry(cwd: string, sources: string[], entries: SkillEntry[]): string {
+function renderRegistry(
+	cwd: string,
+	sources: string[],
+	entries: SkillEntry[],
+): string {
 	const projectName = basename(cwd);
 	const today = new Date().toISOString().slice(0, 10);
 	const lines: string[] = [];
 	lines.push(`# Skill Registry — ${projectName}`);
 	lines.push("");
-	lines.push("<!-- Auto-generated by .pi/extensions/skill-registry.ts. Run /skill-registry:refresh to regenerate. -->");
+	lines.push(
+		"<!-- Auto-generated by .pi/extensions/skill-registry.ts. Run /skill-registry:refresh to regenerate. -->",
+	);
 	lines.push("");
 	lines.push(`Last updated: ${today}`);
 	lines.push("");
@@ -198,6 +224,16 @@ function renderRegistry(cwd: string, sources: string[], entries: SkillEntry[]):
 		lines.push(`- ${src}`);
 	}
 	lines.push("");
+	lines.push("## Contract");
+	lines.push("");
+	lines.push(
+		"**Delegator use only.** Any agent that launches subagents reads this registry to resolve compact rules, then injects matching rule text into subagent prompts under `## Project Standards (auto-resolved)`.",
+	);
+	lines.push("");
+	lines.push(
+		"Subagents still read their assigned executor/phase skill. During normal runtime, they do **not** independently discover or load additional project/user `SKILL.md` files or this registry; project/user rules arrive pre-digested. Explicit fallback loading is degraded self-healing and must be reported in `skill_resolution` as `fallback-registry` or `fallback-path`.",
+	);
+	lines.push("");
 	lines.push(SECTION_MARKER);
 	lines.push("");
 	for (const entry of entries) {
@@ -233,12 +269,20 @@ function ensureAtlIgnored(cwd: string): void {
 		.some((line) => line === ".atl" || line === ATL_IGNORE_ENTRY);
 	if (hasAtlIgnore) return;
 	const prefix = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
-	const header = existing.includes("# Local Pi runtime state") ? "" : "# Local Pi runtime state\n";
-	writeFileSync(gitignorePath, `${existing}${prefix}${header}${ATL_IGNORE_ENTRY}\n`);
+	const header = existing.includes("# Local Pi runtime state")
+		? ""
+		: "# Local Pi runtime state\n";
+	writeFileSync(
+		gitignorePath,
+		`${existing}${prefix}${header}${ATL_IGNORE_ENTRY}\n`,
+	);
 }
 
 function regenerateRegistry(cwd: string, force: boolean): RegenResult {
-	const existingDirs = uniqueExistingDirs([...projectSkillDirs(cwd), ...userSkillDirs()]);
+	const existingDirs = uniqueExistingDirs([
+		...projectSkillDirs(cwd),
+		...userSkillDirs(),
+	]);
 	const files = existingDirs.flatMap(findSkillFiles).sort();
 	const cachePath = join(cwd, CACHE_REL_PATH);
 	const registryPath = join(cwd, REGISTRY_REL_PATH);
@@ -246,7 +290,9 @@ function regenerateRegistry(cwd: string, force: boolean): RegenResult {
 	let cached: string | undefined;
 	if (existsSync(cachePath)) {
 		try {
-			cached = (JSON.parse(readFileSync(cachePath, "utf8")) as { fingerprint?: string }).fingerprint;
+			cached = (
+				JSON.parse(readFileSync(cachePath, "utf8")) as { fingerprint?: string }
+			).fingerprint;
 		} catch {
 			cached = undefined;
 		}
@@ -266,15 +312,25 @@ function regenerateRegistry(cwd: string, force: boolean): RegenResult {
 	mkdirSync(join(cwd, ".atl"), { recursive: true });
 	writeFileSync(registryPath, md);
 	writeFileSync(cachePath, JSON.stringify({ fingerprint: fp }, null, 2));
-	return { regenerated: true, skillCount: deduped.length, reason: force ? "forced" : "fingerprint-changed" };
+	return {
+		regenerated: true,
+		skillCount: deduped.length,
+		reason: force ? "forced" : "fingerprint-changed",
+	};
 }
 
 const watchedCwds = new Set<string>();
 
-function startSkillRegistryWatcher(cwd: string, notify: (message: string) => void): void {
+function startSkillRegistryWatcher(
+	cwd: string,
+	notify: (message: string) => void,
+): void {
 	if (watchedCwds.has(cwd)) return;
 	watchedCwds.add(cwd);
-	const dirs = uniqueExistingDirs([...projectSkillDirs(cwd), ...userSkillDirs()]);
+	const dirs = uniqueExistingDirs([
+		...projectSkillDirs(cwd),
+		...userSkillDirs(),
+	]);
 	let timer: ReturnType<typeof setTimeout> | undefined;
 	const refresh = () => {
 		if (timer) clearTimeout(timer);
@@ -304,7 +360,10 @@ export default function (pi: ExtensionAPI) {
 			ensureAtlIgnored(ctx.cwd);
 			const result = regenerateRegistry(ctx.cwd, false);
 			if (result.regenerated && ctx.hasUI) {
-				ctx.ui.notify(`Skill registry refreshed (${result.skillCount} skills)`, "info");
+				ctx.ui.notify(
+					`Skill registry refreshed (${result.skillCount} skills)`,
+					"info",
+				);
 			}
 			startSkillRegistryWatcher(ctx.cwd, (message) => {
 				if (ctx.hasUI) ctx.ui.notify(message, "info");

package/package.json

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