gentle-pi 0.3.4 → 0.3.5

package/extensions/gentle-ai.ts

@@ -33,17 +33,21 @@ import {
 const PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
 const ASSETS_DIR = join(PACKAGE_ROOT, "assets");
 
-function sddAssetDriftCount(cwd: string): number {
+function gentlePiAgentHome(): string {
+	return process.env.GENTLE_PI_AGENT_HOME ?? join(homedir(), ".pi", "agent");
+}
+
+function sddGlobalAssetDriftCount(): number {
 	let stale = 0;
 	for (const [assetSubdir, installedSubdir] of [
-		["agents", join(".pi", "agents")],
-		["chains", join(".pi", "chains")],
+		["agents", "agents"],
+		["chains", "chains"],
 	] as const) {
 		const assetDir = join(ASSETS_DIR, assetSubdir);
 		if (!existsSync(assetDir)) continue;
 		for (const entry of readdirSync(assetDir, { withFileTypes: true })) {
 			if (!entry.isFile()) continue;
-			const installedPath = join(cwd, installedSubdir, entry.name);
+			const installedPath = join(gentlePiAgentHome(), installedSubdir, entry.name);
 			try {
 				if (!existsSync(installedPath)) {
 					stale += 1;
@@ -63,6 +67,34 @@ function sddAssetDriftCount(cwd: string): number {
 	return stale;
 }
 
+function sddLocalOverrideDriftCount(cwd: string): number {
+	let stale = 0;
+	for (const [assetSubdir, installedSubdir] of [
+		["agents", join(".pi", "agents")],
+		["chains", join(".pi", "chains")],
+	] 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;
+}
+
 let orchestratorPromptCache: string | null = null;
 function getOrchestratorPrompt(): string {
 	if (orchestratorPromptCache === null) {
@@ -212,7 +244,18 @@ function readStringPath(value: unknown, path: string[]): string | undefined {
 }
 
 function isSddAgentStartEvent(event: unknown): boolean {
-	const candidates = [
+	const candidates = readAgentStartNames(event);
+	if (candidates.some((value) => SDD_AGENT_NAME_SET.has(value))) return true;
+
+	const systemPrompt = readStringPath(event, ["systemPrompt"]) ?? "";
+	return SDD_AGENT_NAMES.some((name) => {
+		const phase = name.replace(/^sdd-/, "");
+		return new RegExp(`\\bSDD ${phase} executor\\b`, "i").test(systemPrompt);
+	});
+}
+
+function readAgentStartNames(event: unknown): string[] {
+	return [
 		readStringPath(event, ["agentName"]),
 		readStringPath(event, ["agent"]),
 		readStringPath(event, ["name"]),
@@ -220,14 +263,12 @@ function isSddAgentStartEvent(event: unknown): boolean {
 		readStringPath(event, ["subagent", "name"]),
 	]
 		.filter((value): value is string => value !== undefined)
-		.map((value) => value.trim());
-	if (candidates.some((value) => SDD_AGENT_NAME_SET.has(value))) return true;
+		.map((value) => value.trim())
+		.filter((value) => value.length > 0);
+}
 
-	const systemPrompt = readStringPath(event, ["systemPrompt"]) ?? "";
-	return SDD_AGENT_NAMES.some((name) => {
-		const phase = name.replace(/^sdd-/, "");
-		return new RegExp(`\\bSDD ${phase} executor\\b`, "i").test(systemPrompt);
-	});
+function isNamedAgentStartEvent(event: unknown): boolean {
+	return readAgentStartNames(event).length > 0;
 }
 
 function evaluateDeniedCommand(
@@ -548,13 +589,13 @@ async function listAgentsFromDirAsync(
 
 function listDiscoverableAgents(cwd: string): AgentEntry[] {
 	const builtinDirs = [
+		join(gentlePiAgentHome(), "agents"),
 		join(PACKAGE_ROOT, "..", "pi-subagents", "agents"),
 		join(cwd, ".pi", "npm", "node_modules", "pi-subagents", "agents"),
 		join(homedir(), ".local", "lib", "node_modules", "pi-subagents", "agents"),
 	];
 	const agents = [
 		...builtinDirs.flatMap((dir) => listAgentsFromDir(dir, "builtin")),
-		...listAgentsFromDir(join(homedir(), ".pi", "agent", "agents"), "user"),
 		...listAgentsFromDir(join(homedir(), ".agents"), "user"),
 		...listAgentsFromDir(join(cwd, ".agents"), "project"),
 		...listAgentsFromDir(join(cwd, ".pi", "agents"), "project"),
@@ -573,6 +614,7 @@ function listDiscoverableAgents(cwd: string): AgentEntry[] {
 
 async function listDiscoverableAgentsAsync(cwd: string): Promise<AgentEntry[]> {
 	const builtinDirs = [
+		join(gentlePiAgentHome(), "agents"),
 		join(PACKAGE_ROOT, "..", "pi-subagents", "agents"),
 		join(cwd, ".pi", "npm", "node_modules", "pi-subagents", "agents"),
 		join(homedir(), ".local", "lib", "node_modules", "pi-subagents", "agents"),
@@ -582,7 +624,6 @@ async function listDiscoverableAgentsAsync(cwd: string): Promise<AgentEntry[]> {
 		agents.push(...(await listAgentsFromDirAsync(dir, "builtin")));
 	}
 	const otherDirs: Array<[string, AgentSource]> = [
-		[join(homedir(), ".pi", "agent", "agents"), "user"],
 		[join(homedir(), ".agents"), "user"],
 		[join(cwd, ".agents"), "project"],
 		[join(cwd, ".pi", "agents"), "project"],
@@ -1235,6 +1276,7 @@ export default function gentleAi(pi: ExtensionAPI): void {
 
 	pi.on("session_start", async (_event, ctx) => {
 		try {
+			const installResult = installSddAssets(ctx.cwd, false);
 			const modelResult = await applySavedModelConfig(ctx);
 			if (ctx.hasUI && modelResult.invalidPath) {
 				ctx.ui.notify(
@@ -1245,7 +1287,7 @@ export default function gentleAi(pi: ExtensionAPI): void {
 			}
 			if (ctx.hasUI && modelResult.updated > 0) {
 				ctx.ui.notify(
-					`el Gentleman applied SDD model config to ${modelResult.updated} agent(s).`,
+					`el Gentleman applied SDD model config to ${modelResult.updated} agent(s). Global SDD assets ready: ${installResult.agents} new agent(s), ${installResult.chains} new chain(s), ${installResult.support} new support file(s).`,
 					"info",
 				);
 			}
@@ -1270,13 +1312,21 @@ export default function gentleAi(pi: ExtensionAPI): void {
 	});
 
 	pi.on("before_agent_start", async (event, ctx) => {
-		if (isSddAgentStartEvent(event) && !getSddPreflightPreferences(ctx)) {
+		const isSddAgent = isSddAgentStartEvent(event);
+		const isNamedAgent = isNamedAgentStartEvent(event);
+		if (isSddAgent && !getSddPreflightPreferences(ctx)) {
 			await runSddPreflight(ctx);
 		}
 		const prefs = getSddPreflightPreferences(ctx);
-		const sddPrompt = prefs ? `\n\n${renderSddPreflightPrompt(prefs)}` : "";
+		const sddPrompt =
+			prefs && (!isNamedAgent || isSddAgent)
+				? `\n\n${renderSddPreflightPrompt(prefs)}`
+				: "";
+		const gentlePrompt = isNamedAgent || isSddAgent
+			? ""
+			: `\n\n${buildGentlePrompt(readPersonaMode(ctx.cwd))}`;
 		return {
-			systemPrompt: `${event.systemPrompt}\n\n${buildGentlePrompt(readPersonaMode(ctx.cwd))}${sddPrompt}`,
+			systemPrompt: `${event.systemPrompt}${gentlePrompt}${sddPrompt}`,
 		};
 	});
 
@@ -1289,12 +1339,12 @@ export default function gentleAi(pi: ExtensionAPI): void {
 
 	pi.registerCommand("gentle-ai:install-sdd", {
 		description:
-			"Install Gentle AI SDD subagent and chain assets into this project.",
+			"Repair or refresh global Gentle AI SDD subagent and chain assets.",
 		handler: async (args, ctx) => {
 			const force = args.includes("--force");
 			const result = installSddAssets(ctx.cwd, force);
 			ctx.ui.notify(
-				`Gentle AI SDD assets installed: ${result.agents} agent(s), ${result.chains} chain(s), ${result.support} support file(s), ${result.skipped} skipped.`,
+				`Global Gentle AI SDD assets installed: ${result.agents} agent(s), ${result.chains} chain(s), ${result.support} support file(s), ${result.skipped} already present.`,
 				"info",
 			);
 		},
@@ -1361,32 +1411,38 @@ export default function gentleAi(pi: ExtensionAPI): void {
 		description: "Show Gentle AI package status for this project.",
 		handler: async (_args, ctx) => {
 			const agentsInstalled = existsSync(
-				join(ctx.cwd, ".pi", "agents", "sdd-apply.md"),
+				join(gentlePiAgentHome(), "agents", "sdd-apply.md"),
 			);
 			const chainsInstalled = existsSync(
-				join(ctx.cwd, ".pi", "chains", "sdd-full.chain.md"),
+				join(gentlePiAgentHome(), "chains", "sdd-full.chain.md"),
 			);
 			const openspecConfigured = existsSync(
 				join(ctx.cwd, "openspec", "config.yaml"),
 			);
-			const staleSddAssets = sddAssetDriftCount(ctx.cwd);
+			const staleSddAssets = sddGlobalAssetDriftCount();
+			const staleLocalOverrides = sddLocalOverrideDriftCount(ctx.cwd);
 			const modelConfig = await readModelConfigAsync(ctx.cwd);
 			ctx.ui.notify(
 				[
 					"el Gentleman package is active.",
 					`Persona: ${readPersonaMode(ctx.cwd)}`,
-					`SDD agents: ${agentsInstalled ? "installed" : "not installed"}`,
-					`SDD chains: ${chainsInstalled ? "installed" : "not installed"}`,
-					`SDD assets stale: ${staleSddAssets} file(s)${
+					`Global SDD agents: ${agentsInstalled ? "installed" : "not installed"}`,
+					`Global SDD chains: ${chainsInstalled ? "installed" : "not installed"}`,
+					`Global SDD assets stale: ${staleSddAssets} file(s)${
 						staleSddAssets > 0
 							? " — 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"
+							: ""
+					}`,
 					`OpenSpec config: ${openspecConfigured ? "present" : "missing"}`,
 					`Global model config: ${existsSync(modelConfigPath(ctx.cwd)) ? "present" : "missing"}`,
 					...describeModelConfig(ctx.cwd, modelConfig),
 				].join("\n"),
-				staleSddAssets > 0 ? "warning" : "info",
+				staleSddAssets > 0 || staleLocalOverrides > 0 ? "warning" : "info",
 			);
 		},
 	});

package/extensions/skill-registry.ts

@@ -15,12 +15,12 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
 const REGISTRY_REL_PATH = ".atl/skill-registry.md";
 const CACHE_REL_PATH = ".atl/.skill-registry.cache.json";
-const SECTION_MARKER = "## Selected skills and compact rules";
+const SECTION_MARKER = "## Skills";
 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 = 4;
+const REGISTRY_SCHEMA_VERSION = 5;
 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";
@@ -39,7 +39,7 @@ interface SkillEntry {
 	name: string;
 	path: string;
 	description: string;
-	rules: string[];
+	scope?: string;
 }
 
 function userSkillDirs(): string[] {
@@ -114,12 +114,28 @@ function parseFrontmatter(source: string): { name?: string; description?: string
 	const fm = source.slice(4, end);
 	const body = source.slice(end + 4).replace(/^\n/, "");
 	const out: { name?: string; description?: string } = {};
-	for (const line of fm.split("\n")) {
+	const lines = fm.split("\n");
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i];
 		const m = line.match(/^(\w+):\s*(.*)$/);
 		if (!m) continue;
 		const key = m[1];
 		let value = m[2].trim();
-		if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+		if (value === ">" || value === ">-" || value === "|" || value === "|-") {
+			const block: string[] = [];
+			while (i + 1 < lines.length) {
+				const next = lines[i + 1];
+				if (next.trim() === "") {
+					block.push("");
+					i++;
+					continue;
+				}
+				if (!next.startsWith(" ") && !next.startsWith("\t")) break;
+				block.push(next.trim());
+				i++;
+			}
+			value = block.join(" ").trim();
+		} else if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
 			value = value.slice(1, -1);
 		}
 		if (key === "name") out.name = value;
@@ -128,76 +144,6 @@ function parseFrontmatter(source: string): { name?: string; description?: string
 	return { ...out, body };
 }
 
-const FALLBACK_RULE_HEADINGS = ["Hard Rules", "Critical Rules", "Critical Patterns", "Voice Rules", "Decision Gates"];
-const MAX_EXTRACTED_RULE_COUNT = 15;
-
-function extractCompactRulesSection(body: string): string[] {
-	const compactRules = extractRulesFromHeadings(body, ["Compact Rules"]);
-	if (compactRules.length > 0) return compactRules;
-	return extractRulesFromHeadings(body, FALLBACK_RULE_HEADINGS);
-}
-
-function extractRulesFromHeadings(body: string, headings: string[]): string[] {
-	const wanted = new Set(headings.map(normalizeHeading));
-	let inSection = false;
-	const rules: string[] = [];
-	for (const raw of body.split("\n")) {
-		const line = raw.trimEnd();
-		const heading = line.match(/^##\s+(.+?)\s*$/);
-		if (heading) {
-			inSection = wanted.has(normalizeHeading(heading[1]));
-			continue;
-		}
-		if (!inSection) continue;
-		if (/^##\s+/.test(line)) {
-			inSection = false;
-			continue;
-		}
-		const rule = extractRuleLine(line);
-		if (rule) {
-			rules.push(rule);
-			if (rules.length >= MAX_EXTRACTED_RULE_COUNT) return rules;
-		}
-	}
-	return rules;
-}
-
-function extractRuleLine(line: string): string | undefined {
-	const trimmed = line.trim();
-	if (!trimmed) return undefined;
-	const bullet = trimmed.match(/^-\s+(.+)$/);
-	if (bullet) return bullet[1].trim();
-	const ordered = trimmed.match(/^\d+[.)]\s+(.+)$/);
-	if (ordered) return ordered[1].trim();
-	if (trimmed.startsWith("|") && trimmed.endsWith("|")) return extractRuleTableRow(trimmed);
-	return undefined;
-}
-
-function extractRuleTableRow(line: string): string | undefined {
-	const cells = line
-		.slice(1, -1)
-		.split("|")
-		.map((cell) => cell.trim());
-	if (cells.length < 2) return undefined;
-	if (isTableSeparator(cells) || isTableHeader(cells) || !cells[0] || !cells[1]) return undefined;
-	return `${cells[0]}: ${cells[1]}`;
-}
-
-function isTableSeparator(cells: string[]): boolean {
-	return cells.every((cell) => cell.replace(/[\s:-]/g, "") === "");
-}
-
-function isTableHeader(cells: string[]): boolean {
-	if (cells.length < 2) return false;
-	const first = normalizeHeading(cells[0]);
-	const second = normalizeHeading(cells[1]);
-	return (first === "rule" && second === "requirement") || (first === "target" && second === "test pattern");
-}
-
-function normalizeHeading(heading: string): string {
-	return heading.trim().toLowerCase();
-}
-
 function deriveSkillName(file: string, frontmatterName: string | undefined): string {
 	if (frontmatterName) return frontmatterName;
 	return basename(join(file, ".."));
@@ -235,21 +181,15 @@ async function loadSkill(file: string): Promise<SkillEntry | undefined> {
 	const fm = parseFrontmatter(source);
 	const name = deriveSkillName(file, fm.name);
 	if (isExcluded(name)) return undefined;
-	const rules = extractCompactRulesSection(fm.body);
 	return {
 		name,
 		path: file,
-		description: extractTriggerDescription(fm.description ?? ""),
-		rules:
-			rules.length > 0
-				? rules
-				: ["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."],
+		description: normalizeSkillDescription(fm.description ?? ""),
 	};
 }
 
-function extractTriggerDescription(description: string): string {
-	const match = description.match(/\bTrigger:\s*(.+)$/i);
-	return match ? match[1].trim() : description;
+function normalizeSkillDescription(description: string): string {
+	return description.replace(/\s+/g, " ").trim();
 }
 
 function dedupeBySkillName(entries: SkillEntry[], cwd: string): SkillEntry[] {
@@ -269,6 +209,26 @@ function dedupeBySkillName(entries: SkillEntry[], cwd: string): SkillEntry[] {
 	return out.sort((a, b) => a.name.localeCompare(b.name));
 }
 
+function scopeForPath(cwd: string, path: string): string {
+	const cleanCwd = comparablePath(cwd);
+	const projectPrefix = cleanCwd.endsWith(sep) ? cleanCwd : `${cleanCwd}${sep}`;
+	return comparablePath(path).startsWith(projectPrefix) ? "project" : "user";
+}
+
+function markdownCell(value: string): string {
+	const trimmed = value.replace(/\n/g, " ").replace(/\|/g, "\\|").trim();
+	return trimmed.length > 0 ? trimmed : "—";
+}
+
+function isCacheFile(value: unknown): value is { fingerprint: string } {
+	return (
+		typeof value === "object" &&
+		value !== null &&
+		"fingerprint" in value &&
+		typeof value.fingerprint === "string"
+	);
+}
+
 async function fingerprint(files: string[]): Promise<string> {
 	const lines: string[] = [`schema:${REGISTRY_SCHEMA_VERSION}`];
 	for (const file of files) {
@@ -301,24 +261,24 @@ function renderRegistry(cwd: string, sources: string[], entries: SkillEntry[]):
 	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("**Delegator use only.** This registry is an index, not a summary. Any agent that launches subagents reads it to select relevant skills, then passes exact `SKILL.md` paths for the subagent to read before work.");
 	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("`SKILL.md` remains the source of truth. Do not inject generated summaries or compact rules by default; pass paths so subagents load the full runtime contract and preserve author intent.");
 	lines.push("");
 	lines.push(SECTION_MARKER);
 	lines.push("");
+	lines.push("| Skill | Trigger / description | Scope | Path |");
+	lines.push("| --- | --- | --- | --- |");
 	for (const entry of entries) {
-		lines.push(`### ${entry.name}`);
-		lines.push(`- Path: ${entry.path}`);
-		if (entry.description) {
-			lines.push(`- Trigger: ${entry.description}`);
-		}
-		lines.push("- Rules:");
-		for (const rule of entry.rules) {
-			lines.push(`  - ${rule}`);
-		}
-		lines.push("");
+		lines.push(`| \`${markdownCell(entry.name)}\` | ${markdownCell(entry.description)} | ${markdownCell(entry.scope ?? scopeForPath(cwd, entry.path))} | \`${markdownCell(entry.path)}\` |`);
 	}
+	lines.push("");
+	lines.push("## Loading protocol");
+	lines.push("");
+	lines.push("1. Match task context and target files against the `Trigger / description` column.");
+	lines.push("2. Pass only the matching `Path` values to the subagent under `## Skills to load before work`.");
+	lines.push("3. Instruct the subagent to read those exact `SKILL.md` files before reading, writing, reviewing, testing, or creating artifacts.");
+	lines.push("4. If no matching skill exists, proceed without project skill injection and report `skill_resolution: none`.");
 	return `${lines.join("\n").trimEnd()}\n`;
 }
 
@@ -403,11 +363,8 @@ async function regenerateRegistry(
 	let cached: string | undefined;
 	if (await pathExists(cachePath)) {
 		try {
-			cached = (
-				JSON.parse(await readFile(cachePath, "utf8")) as {
-					fingerprint?: string;
-				}
-			).fingerprint;
+			const parsed: unknown = JSON.parse(await readFile(cachePath, "utf8"));
+			cached = isCacheFile(parsed) ? parsed.fingerprint : undefined;
 		} catch {
 			cached = undefined;
 		}
@@ -496,10 +453,12 @@ async function startSkillRegistryWatcher(
 export const __testing = {
 	projectSkillDirs,
 	userSkillDirs,
-	extractCompactRulesSection,
-	extractTriggerDescription,
 	uniqueExistingDirs,
 	dedupeBySkillName,
+	scopeForPath,
+	normalizeSkillDescription,
+	parseFrontmatter,
+	renderRegistry,
 	shouldSkipSkillRegistryStartup,
 };
 

package/lib/sdd-preflight.ts

@@ -1,4 +1,5 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
@@ -6,6 +7,10 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 const PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
 const ASSETS_DIR = join(PACKAGE_ROOT, "assets");
 
+function gentlePiAgentHome(): string {
+	return process.env.GENTLE_PI_AGENT_HOME ?? join(homedir(), ".pi", "agent");
+}
+
 export type SddExecutionMode = "interactive" | "auto";
 export type SddArtifactStore = "openspec" | "engram" | "both";
 export type SddChainedPrStrategy =
@@ -89,22 +94,23 @@ function copyDirectoryFiles(
 }
 
 export function installSddAssets(
-	cwd: string,
+	_cwd: string,
 	force: boolean,
 ): { agents: number; chains: number; support: number; skipped: number } {
+	const agentHome = gentlePiAgentHome();
 	const agents = copyDirectoryFiles(
 		join(ASSETS_DIR, "agents"),
-		join(cwd, ".pi", "agents"),
+		join(agentHome, "agents"),
 		force,
 	);
 	const chains = copyDirectoryFiles(
 		join(ASSETS_DIR, "chains"),
-		join(cwd, ".pi", "chains"),
+		join(agentHome, "chains"),
 		force,
 	);
 	const support = copyDirectoryFiles(
 		join(ASSETS_DIR, "support"),
-		join(cwd, ".pi", "gentle-ai", "support"),
+		join(agentHome, "gentle-ai", "support"),
 		force,
 	);
 	return {
@@ -248,7 +254,7 @@ export async function ensureSddPreflight(
 					`Artifacts: ${prefs.artifactStore}`,
 					`PR chaining: ${prefs.chainedPrStrategy}`,
 					`Review budget: ${prefs.reviewBudgetLines} changed lines`,
-					`Assets installed: ${result.agents} agent(s), ${result.chains} chain(s), ${result.support} support file(s), ${result.skipped} skipped.`,
+					`Global SDD assets ready: ${result.agents} agent(s), ${result.chains} chain(s), ${result.support} support file(s), ${result.skipped} already present.`,
 					modelRoutingLine,
 				].join("\n"),
 				modelResult.invalidPath ? "warning" : "info",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gentle-pi",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "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/skills/gentle-ai/SKILL.md

@@ -55,4 +55,4 @@ Hard delegation triggers:
 - **Incident rule**: after wrong cwd, accidental worktree/repo mutation, merge recovery, confusing test command, or environment workaround, run fresh audit.
 - **Long-session rule**: after roughly 20 tool calls, 5 exploratory reads, or 2 non-mechanical edits with no delegation and accumulating complexity, pause and choose a subagent or justify not doing so.
 
-The package auto-installs SDD agents and chains into the project when a Pi session starts. Use `/gentle-ai:install-sdd --force` only for recovery or intentional overwrite.
+The package ensures SDD agents and chains are available as global Pi runtime assets. Project-local SDD files are overrides/debug copies only. Use `/gentle-ai:install-sdd --force` only for recovery or intentional global refresh.

package/skills/judgment-day/SKILL.md

@@ -13,7 +13,7 @@ Load this skill only when the user explicitly asks for Judgment Day, dual/advers
 
 ## Hard Rules
 
-- Resolve project skills before launching agents: read skill registry, match compact rules by target files/task, and inject the same `Project Standards` block into both judge prompts and fix prompts.
+- Resolve project skills before launching agents: read skill registry, match indexed paths by target files/task, and pass the same `Skills to load before work` block into both judge prompts and fix prompts.
 - Launch **two blind judges in parallel** with identical target and criteria; never review the code yourself.
 - Wait for both judges before synthesis; never accept a partial verdict.
 - Classify warnings as `WARNING (real)` only if normal intended use can trigger them; otherwise downgrade to INFO as `WARNING (theoretical)`.

package/skills/judgment-day/references/prompts-and-formats.md

@@ -8,8 +8,8 @@ You are an adversarial code reviewer. Your ONLY job is to find problems.
 ## Target
 {files, feature, architecture, component}
 
-## Project Standards (auto-resolved)
-{matching compact rules, if available}
+## Skills to load before work
+{matching SKILL.md paths, if available}
 
 ## Review Criteria
 - Correctness: logical errors and behavior mismatches
@@ -33,7 +33,7 @@ WARNING rule: normal intended use can trigger it → `WARNING (real)`; contrived
 
 If clean: `VERDICT: CLEAN — No issues found.`
 
-Always end with: `Skill Resolution: {injected|fallback-registry|fallback-path|none} — {details}`.
+Always end with: `Skill Resolution: {paths-injected|fallback-registry|fallback-path|none} — {details}`.
 ```
 
 ## Fix Agent Prompt
@@ -44,8 +44,8 @@ You are a surgical fix agent. Apply ONLY the confirmed issues listed below.
 ## Confirmed Issues to Fix
 {confirmed findings table}
 
-## Project Standards (auto-resolved)
-{matching compact rules, if available}
+## Skills to load before work
+{matching SKILL.md paths, if available}
 
 ## Instructions
 - Fix only confirmed issues.
@@ -54,7 +54,7 @@ You are a surgical fix agent. Apply ONLY the confirmed issues listed below.
 - If fixing a repeated pattern in touched files, fix all occurrences of that same pattern.
 - Return changed file, line, and fix summary.
 
-End with: `Skill Resolution: {injected|fallback-registry|fallback-path|none} — {details}`.
+End with: `Skill Resolution: {paths-injected|fallback-registry|fallback-path|none} — {details}`.
 ```
 
 ## Verdict Table

package/skills/skill-registry/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: skill-registry
+description: "Trigger: update skills, skill registry, actualizar skills, after skill changes. Index available skills by trigger and path."
+license: MIT
+metadata:
+  author: gentleman-programming
+  version: "1.0"
+---
+
+## Activation Contract
+
+Use this skill after installing, removing, creating, moving, or renaming skills, or when a delegator needs a fresh skill index.
+
+## Hard Rules
+
+- The registry is an index, not a compiler or summary. `SKILL.md` remains the source of truth.
+- Do not generate or inject compact rules by default; preserve author intent by passing exact skill paths to subagents.
+- Always write `.atl/skill-registry.md` regardless of SDD persistence mode.
+- Save the registry to Engram as `topic_key: skill-registry` when available, with `capture_prompt: false`.
+- Skip `sdd-*`, `_shared`, and `skill-registry`; deduplicate by skill name, preferring project-level skills over user-level skills.
+- Add `.atl/` to `.gitignore` when possible unless explicitly disabled.
+
+## Decision Gates
+
+| Situation | Action |
+| --- | --- |
+| Same skill exists globally and in project | Keep the project-level skill |
+| Same skill exists in multiple global locations | Keep the first source in scan order |
+| No skills found | Write an empty registry so agents stop searching blindly |
+| Agent will delegate work | Select matching registry rows and pass their `SKILL.md` paths |
+
+## Execution Steps
+
+1. Scan all known user and project skill directories for `*/SKILL.md`.
+2. Read frontmatter only as needed to extract `name` and `description` trigger text.
+3. Render `.atl/skill-registry.md` with scanned sources, registry contract, skill name, trigger/description, scope, and exact path.
+4. Persist to Engram when available using `title: skill-registry`, `topic_key: skill-registry`, `type: config`, and `capture_prompt: false`.
+5. Return the registry path, skill count, cache status, and whether Engram was updated.
+
+## Output Contract
+
+Return:
+- Project name and `.atl/skill-registry.md` path.
+- Number of indexed skills.
+- Whether the cache was hit or regenerated.
+- Any skipped or duplicate skills when relevant.
+
+## References
+
+- `docs/skill-style-guide.md` — how skills should be authored before indexing.
+- `skills/_shared/skill-resolver.md` — how delegators use the index.