gentle-pi 0.3.3 → 0.3.5

package/extensions/gentle-ai.ts

@@ -33,6 +33,68 @@ import {
 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");
+}
+
+function sddGlobalAssetDriftCount(): number {
+	let stale = 0;
+	for (const [assetSubdir, installedSubdir] of [
+		["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(gentlePiAgentHome(), installedSubdir, entry.name);
+			try {
+				if (!existsSync(installedPath)) {
+					stale += 1;
+					continue;
+				}
+				if (
+					readFileSync(join(assetDir, entry.name), "utf8") !==
+					readFileSync(installedPath, "utf8")
+				) {
+					stale += 1;
+				}
+			} catch {
+				stale += 1;
+			}
+		}
+	}
+	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) {
@@ -128,6 +190,7 @@ const SDD_AGENT_NAMES = [
 	"sdd-tasks",
 	"sdd-apply",
 	"sdd-verify",
+	"sdd-sync",
 	"sdd-archive",
 ] as const;
 const SDD_AGENT_NAME_SET = new Set<string>(SDD_AGENT_NAMES);
@@ -181,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"]),
@@ -189,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(
@@ -517,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"),
@@ -542,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"),
@@ -551,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"],
@@ -1204,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(
@@ -1214,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",
 				);
 			}
@@ -1239,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}`,
 		};
 	});
 
@@ -1258,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",
 			);
 		},
@@ -1330,26 +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 = 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"}`,
+					`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"),
-				"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/openspec-deltas.ts

@@ -0,0 +1,156 @@
+export interface RequirementBlock {
+	name: string;
+	content: string;
+	start: number;
+	end: number;
+}
+
+export interface DeltaSpec {
+	added: RequirementBlock[];
+	modified: RequirementBlock[];
+	removed: RequirementBlock[];
+}
+
+type DeltaOperation = keyof DeltaSpec;
+
+const REQUIREMENT_HEADING = /^### Requirement:\s*(.+?)\s*$/gm;
+const DELTA_SECTION_HEADING = /^##\s+(ADDED|MODIFIED|REMOVED)\s+Requirements\s*$/gim;
+
+function normalizeMarkdown(markdown: string): string {
+	return markdown.replace(/\r\n/g, "\n");
+}
+
+function nextTopLevelSection(markdown: string, from: number): number {
+	const match = /^##\s+/gm;
+	match.lastIndex = from;
+	const next = match.exec(markdown);
+	return next?.index ?? markdown.length;
+}
+
+function cleanRequirementContent(content: string): string {
+	return content.trimEnd().replace(/\n\s*---\s*$/m, "").trimEnd();
+}
+
+function operationKey(label: string): DeltaOperation {
+	switch (label.toUpperCase()) {
+		case "ADDED":
+			return "added";
+		case "MODIFIED":
+			return "modified";
+		case "REMOVED":
+			return "removed";
+		default:
+			throw new Error(`Unsupported delta operation: ${label}`);
+	}
+}
+
+export function parseRequirementBlocks(markdown: string): RequirementBlock[] {
+	const source = normalizeMarkdown(markdown);
+	const matches = [...source.matchAll(REQUIREMENT_HEADING)];
+	return matches.map((match, index) => {
+		const start = match.index ?? 0;
+		const end = matches[index + 1]?.index ?? nextTopLevelSection(source, start + match[0].length);
+		return {
+			name: match[1].trim(),
+			content: cleanRequirementContent(source.slice(start, end)),
+			start,
+			end,
+		};
+	});
+}
+
+export function parseDeltaSpec(markdown: string): DeltaSpec {
+	const source = normalizeMarkdown(markdown);
+	const sectionMatches = [...source.matchAll(DELTA_SECTION_HEADING)];
+	const delta: DeltaSpec = { added: [], modified: [], removed: [] };
+	const seen = new Map<string, string>();
+
+	for (const [index, match] of sectionMatches.entries()) {
+		const sectionStart = (match.index ?? 0) + match[0].length;
+		const sectionEnd = sectionMatches[index + 1]?.index ?? source.length;
+		const key = operationKey(match[1]);
+		const section = source.slice(sectionStart, sectionEnd);
+		const blocks = parseRequirementBlocks(section);
+		delta[key].push(...blocks);
+	}
+
+	for (const [operation, blocks] of Object.entries(delta) as [DeltaOperation, RequirementBlock[]][]) {
+		for (const block of blocks) {
+			const previous = seen.get(block.name);
+			if (previous) {
+				throw new Error(
+					`Duplicate delta operation for requirement "${block.name}" (${previous} and ${operation})`,
+				);
+			}
+			seen.set(block.name, operation);
+		}
+	}
+
+	return delta;
+}
+
+function requirementMap(blocks: RequirementBlock[]): Map<string, RequirementBlock> {
+	const out = new Map<string, RequirementBlock>();
+	for (const block of blocks) {
+		if (out.has(block.name)) throw new Error(`Duplicate canonical requirement "${block.name}"`);
+		out.set(block.name, block);
+	}
+	return out;
+}
+
+function requireCanonicalBlock(
+	canonical: Map<string, RequirementBlock>,
+	name: string,
+	operation: string,
+): RequirementBlock {
+	const block = canonical.get(name);
+	if (!block) throw new Error(`Missing canonical requirement "${name}" for ${operation}`);
+	return block;
+}
+
+function appendAddedRequirements(markdown: string, added: RequirementBlock[]): string {
+	if (added.length === 0) return markdown;
+	const addition = added.map((block) => block.content.trim()).join("\n\n---\n\n");
+	const requirementsHeading = /^## Requirements\s*$/m.exec(markdown);
+	if (!requirementsHeading) return `${markdown.trimEnd()}\n\n## Requirements\n\n${addition}\n`;
+
+	const sectionStart = requirementsHeading.index + requirementsHeading[0].length;
+	const sectionEnd = nextTopLevelSection(markdown, sectionStart);
+	const before = markdown.slice(0, sectionEnd).trimEnd();
+	const after = markdown.slice(sectionEnd).replace(/^\n+/, "");
+	return after
+		? `${before}\n\n---\n\n${addition}\n\n${after}`
+		: `${before}\n\n---\n\n${addition}\n`;
+}
+
+export function applyDeltaSpec(canonicalMarkdown: string, deltaMarkdown: string): string {
+	let result = normalizeMarkdown(canonicalMarkdown);
+	const delta = parseDeltaSpec(deltaMarkdown);
+	const canonical = requirementMap(parseRequirementBlocks(result));
+
+	for (const block of delta.added) {
+		if (canonical.has(block.name)) {
+			throw new Error(`Cannot add existing canonical requirement "${block.name}"`);
+		}
+	}
+
+	const replacements: Array<{ start: number; end: number; content: string }> = [];
+	for (const block of delta.modified) {
+		const target = requireCanonicalBlock(canonical, block.name, "MODIFIED");
+		replacements.push({ start: target.start, end: target.end, content: block.content.trimEnd() });
+	}
+	for (const block of delta.removed) {
+		const target = requireCanonicalBlock(canonical, block.name, "REMOVED");
+		replacements.push({ start: target.start, end: target.end, content: "" });
+	}
+
+	for (const replacement of replacements.sort((a, b) => b.start - a.start)) {
+		const prefix = result.slice(0, replacement.start).trimEnd();
+		const suffix = result.slice(replacement.end).replace(/^\n+/, "");
+		result = replacement.content
+			? `${prefix}\n\n${replacement.content}\n\n${suffix}`.trimEnd() + "\n"
+			: `${prefix}\n\n${suffix}`.trimEnd() + "\n";
+	}
+
+	return appendAddedRequirements(result, delta.added).trimEnd() + "\n";
+}