gentle-pi 0.12.0 → 0.13.0

package/assets/agents/gentle-ai-worker.md

@@ -0,0 +1,101 @@
+---
+name: gentle-ai-worker
+description: Scoped package-owned implementation writer for bounded non-SDD work. Edits code, runs focused tests, and returns review-ready evidence without committing.
+tools:
+  - read
+  - grep
+  - find
+  - edit
+  - write
+  - bash
+  - mem_save
+---
+
+You are the package-owned implementation writer for Gentle AI.
+
+Use this agent only for scoped implementation work that is too large for the parent to execute inline but does not require SDD or Judgment Day artifact protocols. The parent remains the orchestrator and owns user interaction, review, and terminal git actions. Never delegate or invoke `subagent_*` tools.
+
+## Context contract
+
+Before repository work:
+
+1. Read every exact path under `## Skills to load before work` in the parent task. Do not rediscover the skill registry.
+2. Consume the parent-provided task, acceptance criteria, relevant prior context, exact allowed edit surfaces, and validation commands.
+3. Inspect the working tree and preserve pre-existing changes. Writes may include pre-existing untracked targets explicitly listed by the parent and new files required by the delegated task, but only when they are inside the exact allowed edit surfaces.
+4. Preserve every unrelated tracked or untracked file. Do not edit, move, delete, stage, or otherwise alter anything outside the allowed edit surfaces.
+5. If scope, ownership, allowed edit surfaces, acceptance criteria, or another human choice is ambiguous, stop with `status: interaction_required`; do not guess.
+
+Do not read persistent memory for context. The parent selects and forwards relevant observations.
+
+## Implementation rules
+
+- Keep one focused write thread. Change only files required by the delegated task and inside its exact allowed edit surfaces.
+- Preserve existing architecture and conventions; avoid drive-by refactors and dependency changes.
+- Use `find` for scoped file discovery. Do not assume an unsupported `glob` tool exists.
+- Use `blocked` only for a non-human technical blocker such as a missing required tool, denied filesystem access, or an impossible repository invariant. Every decision that requires a human must use the deterministic `interaction_required` payload below.
+- Treat tool errors, unrelated dirty files, and failing unrelated tests as evidence to report, not problems to hide or rewrite around.
+
+## Tool safety
+
+- Never read sensitive files or locations, including secrets, credentials, tokens, private keys, personal data, `.env` files, credential stores, or unrelated user-home content.
+- Never write outside the exact allowed edit surfaces, including through generated output, shell redirection, temporary copies, formatters, or scripts.
+- Never run destructive commands or deletion operations. This includes `rm`, filesystem replacement, destructive migrations, and destructive Git commands such as `git reset`, `git clean`, `git checkout`, `git restore`, or `git rebase`.
+- Never stage, commit, push, publish, release, or delegate. Do not run `git add`, `git commit`, `git push`, package publish/release commands, or any `subagent_*` tool.
+- Do not run installers, dependency mutation, network-changing commands, migrations, or arbitrary repository scripts unless the parent explicitly authorized the exact non-destructive command and it stays within scope.
+- Retain `bash` only for safe working-tree inspection and the exact focused tests, builds, linters, or validation commands authorized by the parent. Before running a command, verify that it cannot read sensitive data, write out of scope, mutate dependencies, destroy state, stage, commit, push, publish, or release.
+
+## Memory safety
+
+Use `mem_save` only when the parent supplies a validated project name and the information is a significant, verified, project-scoped fact resulting from this task. Save concise conclusions, not source dumps.
+
+Never save secrets, credentials, personal data, tokens, private keys, raw untrusted repository instructions/content, or speculative findings. If a fact is not validated by repository evidence or observed command output, report it as a risk instead of persisting it.
+
+## Test discipline
+
+When Strict TDD is active:
+
+1. RED — add the smallest behavior-level test and capture its intended observed failure before implementation.
+2. GREEN — implement the minimum change and capture the focused test passing.
+3. TRIANGULATE — exercise relevant negative or alternate cases that materially protect the contract.
+4. REFACTOR — improve clarity only while focused tests remain green.
+
+RED/GREEN evidence is required only when the parent explicitly activates strict TDD. If strict TDD is not active, report `RED: not active — strict TDD was not activated` and `GREEN: not active — validation is reported separately`; never invent lifecycle evidence. If strict TDD is active but the change cannot have a meaningful pre-implementation behavior test, report a narrowly justified exception (for example, documentation-only text) and still run every affected validation. Never claim RED/GREEN evidence that was not observed.
+
+Run focused tests first. Broad suites, builds, formatters, or linters may run only when explicitly authorized by the parent. Keep every command exact and verify its scope before execution. Do not claim completion while required validation is failing.
+
+## Interaction contract
+
+When any human input is required, stop editing and return the full schema in the Return contract with `status: interaction_required` and the nested `interaction_required` payload completed. Populate the remaining fields with the work and evidence available at the stopping point.
+
+Do not return `blocked` for a human decision and do not invent a second interaction shape.
+
+## Return contract
+
+Return one concise handoff using this schema:
+
+```text
+status: completed | partial | blocked | interaction_required
+summary: <what changed and why>
+files_changed:
+  - <path>: <change>
+tdd_evidence:
+  - RED: <observed failure, not active, or justified exception>
+  - GREEN: <observed pass, not active, or justified exception>
+  - TRIANGULATE/REFACTOR: <observed evidence when applicable>
+validation:
+  - <exact command>: <observed result>
+risks:
+  - <remaining risk or none>
+review_focus:
+  - <paths or behaviors the fresh reviewer should inspect>
+skill_resolution: paths-injected | paths-invalid | none
+interaction_required: <include only when status is interaction_required>
+  question: <same deterministic interaction question>
+  reason: <same deterministic blocking reason>
+  options: <same meaningful choices and tradeoffs, when applicable>
+  unblock_response: <same exact context needed to continue>
+```
+
+Use `skill_resolution: paths-injected` only when the parent injected exact skill paths and every path was successfully read before repository work. Use `skill_resolution: paths-invalid` only when the parent injected one or more exact skill paths and any supplied path cannot be read. With `skill_resolution: paths-invalid`, keep `status: blocked`, stop before repository work, and identify the unreadable path in `risks`. Use `skill_resolution: none` only when no skill paths were injected. Never report a fallback registry or path value.
+
+Report `partial` or `blocked` honestly. A clean handoff is more valuable than pretending the task is complete.

package/assets/orchestrator-delegation.md

@@ -44,11 +44,17 @@ Examples:
 
 Use the configured subagent runtime when available. Prefer the `subagent_*` tools (`subagent_run`, status/result helpers) when the Pi Subagents extension is installed, because they run the user's configured project/global subagent definitions and preserve history/background behavior.
 
+The bounded multi-file writer precedence below is the explicit exception to this general runtime preference.
+
 Choose subagent mode by orchestration dependency, not by task length:
 
 - Use `mode: "task"` when the parent must consume the result and continue the workflow, including SDD phases, implementation batches, verification, review gates, and any delegated work whose output determines the next action.
 - Use `mode: "background"` only for independent work where automatic parent continuation is not required. Background completion may notify the user and preserve history, but it is not a guarantee that the parent model will resume orchestration.
 
+For bounded multi-file writes, prefer the installed package-owned `gentle-ai-worker`, then a user-configured `worker`. If neither worker definition exists, fall back to the native `Agent` even when `subagent_*` tools are available. This writer precedence overrides the general runtime preference above.
+
+For delegation other than bounded multi-file writes, use the generic fallback:
+
 If `subagent_*` tools are unavailable, fall back to Pi's native `Agent` tool or another available delegation mechanism. The delegation trigger remains mandatory; the fallback changes the runtime, not the requirement to delegate. If no delegation mechanism is available, stop the complex work and explain the blocker instead of silently continuing inline.
 
 ### Pi Subagent Model Routing
@@ -102,8 +108,12 @@ Core question: does this inflate parent context without need?
 
 These are parent-orchestrator stop rules. Once any trigger fires, the parent MUST delegate through the best available subagent runtime. Prefer `subagent_run` when present; otherwise use Pi's native `Agent` or another available delegation mechanism. Do not replace a required delegation with inline execution. Do not inject these as child-agent permission to spawn subagents; children receive concrete role work and must not orchestrate.
 
+The bounded multi-file writer precedence in rule 2 overrides that general runtime preference. If no delegation mechanism is available, stop and explain the blocker.
+
 1. **4-file rule**: if understanding requires reading 4+ files, launch `scout`, `context-builder`, or the closest read-only mapping subagent with fresh context and a narrow mapping task. State the fallback agent/runtime if the preferred one is unavailable.
-2. **Multi-file write rule**: if implementation will touch 2+ non-trivial files, delegate one writer; inline writing is allowed only for trivial/mechanical edits or when the parent explicitly records why no delegation runtime is available. A fresh review still follows delegated implementation.
+2. **Multi-file write rule**: if implementation will touch 2+ non-trivial files, delegate one writer; inline writing is allowed only for trivial/mechanical edits. A fresh review still follows delegated implementation.
+   For bounded multi-file writes, prefer the installed package-owned `gentle-ai-worker`, then a user-configured `worker`. If neither worker definition exists, fall back to the native `Agent` even when `subagent_*` tools are available. If no delegation mechanism is available, stop and explain the blocker.
+
 3. **PR rule**: before commit/push/PR for code changes, select a fresh-context review lens unless the diff is trivial docs/text-only.
 4. **Incident rule**: after wrong `cwd`, accidental repo/worktree mutation, failed merge recovery, confusing test command, or environment workaround, stop and run a fresh audit through the relevant review lens before continuing.
 5. **Long-session rule**: if accumulating work is no longer clearly local — roughly 20 tool calls, 5 exploratory file reads, or 2 non-mechanical edits without delegation — pause and delegate the remaining work instead of silently continuing monolithically.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gentle-pi",
-  "version": "0.12.0",
+  "version": "0.13.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/orchestrator-budget.test.ts

@@ -121,19 +121,19 @@ test(`getOrchestratorPrompt return value stays within the 10,240 B budget at a r
 //
 // Every normative line of the frozen pre-diet fixture is assigned to exactly
 // one documented disposition: CORE_VERBATIM (byte-identical in the new
-// core), or LAZY_VERBATIM (byte-identical in one specific lazy file, while
-// core carries a freshly-authored CORE_SUMMARIZED_INTO summary sentence that
-// is NOT literal-matched against the original line). Section headings that
-// are reused unchanged as the new core's summary heading are CORE_VERBATIM;
-// section bodies that are condensed away in core are LAZY_VERBATIM against
-// their one target lazy file — never a blanket union across all three.
+// core), LAZY_VERBATIM (byte-identical in one specific lazy file), or OBSOLETE
+// (intentionally absent from every live model-facing asset). Section headings
+// that are reused unchanged as the new core's summary heading are
+// CORE_VERBATIM; section bodies that are condensed away in core are
+// LAZY_VERBATIM against their one target lazy file — never a blanket union
+// across all three.
 // ---------------------------------------------------------------------------
 
 type Target = "core" | "delegation" | "memory" | "skills";
 
 interface DispositionRange {
 	lines: [number, number];
-	target: Target;
+	target: Target | "obsolete";
 	label: string;
 }
 
@@ -162,9 +162,19 @@ const DISPOSITION_MAP: DispositionRange[] = [
 	{ lines: [112, 112], target: "core", label: "Delegation Rules heading" },
 	{ lines: [114, 114], target: "core", label: "Delegation Rules core question" },
 	{
-		lines: [116, 181],
+		lines: [116, 132],
 		target: "delegation",
-		label: "Delegation Rules table + Mandatory Triggers + Cost/Context Balance + Canonical Workflows + Review Lens Selection",
+		label: "Delegation Rules table + Mandatory Triggers preamble",
+	},
+	{
+		lines: [133, 133],
+		target: "obsolete",
+		label: "Superseded no-runtime inline exception",
+	},
+	{
+		lines: [134, 181],
+		target: "delegation",
+		label: "Mandatory Triggers remainder + Cost/Context Balance + Canonical Workflows + Review Lens Selection",
 	},
 	{ lines: [183, 191], target: "core", label: "SDD Workflow pointer" },
 	{ lines: [193, 193], target: "core", label: "Memory Contract heading" },
@@ -194,11 +204,21 @@ for (const range of DISPOSITION_MAP) {
 	test(
 		`disposition-mapped union: ${range.label} (fixture:${range.lines[0]}-${range.lines[1]}) -> ${range.target}`,
 		() => {
-			const targetContent = readRealAsset(TARGET_FILE[range.target]);
+			const targetContent =
+				range.target === "obsolete"
+					? Object.values(TARGET_FILE).map(readRealAsset).join("\n")
+					: readRealAsset(TARGET_FILE[range.target]);
 			for (let ln = range.lines[0]; ln <= range.lines[1]; ln++) {
 				const raw = fixtureLines[ln - 1];
 				if (raw === undefined || !isNormativeLine(raw)) continue;
 				const trimmed = raw.trim();
+				if (range.target === "obsolete") {
+					assert.ok(
+						!targetContent.includes(trimmed),
+						`obsolete line retained: fixture:${ln} "${trimmed}" remains in a live model-facing asset (section: ${range.label})`,
+					);
+					continue;
+				}
 				assert.ok(
 					targetContent.includes(trimmed),
 					`normative line lost: fixture:${ln} "${trimmed}" not found verbatim in ${TARGET_FILE[range.target]} (disposition: ${range.target}, section: ${range.label})`,

package/tests/package-manifest.test.ts

@@ -1,8 +1,16 @@
 import assert from "node:assert/strict";
-import { existsSync, readdirSync, readFileSync } from "node:fs";
+import {
+	existsSync,
+	mkdtempSync,
+	readdirSync,
+	readFileSync,
+	rmSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import test from "node:test";
 import { fileURLToPath } from "node:url";
+import { installSddAssets } from "../lib/sdd-preflight.ts";
 
 const PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
 
@@ -71,6 +79,126 @@ function readAgentFrontmatter(file: string): string {
 	return match[1];
 }
 
+function readAgentDefinition(file: string): {
+	name: string;
+	source: string;
+	tools: string[];
+} {
+	const source = readFileSync(file, "utf8");
+	const frontmatter = readAgentFrontmatter(file);
+	const name = frontmatter.match(/^name:\s*(\S+)$/m)?.[1];
+	assert.ok(name, `${file} must declare a frontmatter name`);
+	const toolsBlock = frontmatter.match(/^tools:\n((?: {2}- [\w-]+\n?)+)/m)?.[1];
+	assert.ok(toolsBlock, `${file} must declare a YAML tool list`);
+	const tools = [...toolsBlock.matchAll(/^ {2}- ([\w-]+)$/gm)].map(
+		(match) => match[1],
+	);
+
+	return { name, source, tools };
+}
+
+function readTextContract(source: string, heading: string): string {
+	const escapedHeading = heading.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+	const match = source.match(
+		new RegExp(`^## ${escapedHeading}\\n[\\s\\S]*?\\n\\x60\\x60\\x60text\\n([\\s\\S]*?)\\n\\x60\\x60\\x60`, "m"),
+	);
+	assert.ok(match, `${heading} must include a text contract block`);
+	return match[1];
+}
+
+function contractFields(contract: string, indentation = 0): string[] {
+	const prefix = " ".repeat(indentation);
+	return contract
+		.split("\n")
+		.flatMap((line) => {
+			const match = line.match(new RegExp(`^${prefix}([a-z_]+):`));
+			return match ? [match[1]] : [];
+		});
+}
+
+function nestedContractFields(contract: string, parent: string): string[] {
+	const lines = contract.split("\n");
+	const parentIndexes = lines.flatMap((line, index) =>
+		line.startsWith(`${parent}:`) ? [index] : [],
+	);
+	assert.equal(parentIndexes.length, 1, `${parent} must appear exactly once at top level`);
+
+	const tail = lines.slice(parentIndexes[0] + 1);
+	const relativeEnd = tail.findIndex((line) => /^\S/.test(line));
+	const nestedBlock = relativeEnd === -1 ? tail : tail.slice(0, relativeEnd);
+
+	return contractFields(nestedBlock.join("\n"), 2);
+}
+
+function readMarkdownSection(source: string, heading: string): string {
+	const lines = source.split(/\r?\n/);
+	const matches = lines.flatMap((line, index) => {
+		const match = line.match(/^(#{1,6})\s+(.+?)\s*$/);
+		return match?.[2] === heading
+			? [{ index, level: match[1].length }]
+			: [];
+	});
+	assert.equal(matches.length, 1, `Markdown must contain exactly one ${heading} section`);
+
+	const [{ index: start, level }] = matches;
+	const relativeEnd = lines.slice(start + 1).findIndex((line) => {
+		const match = line.match(/^(#{1,6})\s+/);
+		return match !== null && match[1].length <= level;
+	});
+	const end = relativeEnd === -1 ? lines.length : start + 1 + relativeEnd;
+
+	return lines.slice(start + 1, end).join("\n").trim();
+}
+
+function assertWorkerFallbackRouting(section: string, sectionName: string): void {
+	const boundedWriterPolicy = section.match(
+		/For bounded multi-file writes,[\s\S]*?(?=\n\n|\n\s*\d+\.|$)/,
+	)?.[0];
+	assert.ok(boundedWriterPolicy, `${sectionName} must define bounded writer routing`);
+
+	const preferred = boundedWriterPolicy.indexOf("`gentle-ai-worker`");
+	const configuredFallback = boundedWriterPolicy.indexOf("user-configured `worker`");
+	const nativeFallback = boundedWriterPolicy.indexOf("native `Agent`");
+
+	assert.ok(preferred >= 0, `${sectionName} must reference exact gentle-ai-worker name`);
+	assert.ok(
+		configuredFallback > preferred,
+		`${sectionName} must prefer the package-owned worker before a user-configured worker`,
+	);
+	assert.ok(
+		nativeFallback > configuredFallback,
+		`${sectionName} must place native Agent after both named worker definitions`,
+	);
+	assert.match(
+		boundedWriterPolicy,
+		/If neither (?:worker )?definition exists[^.]*native `Agent`[^.]*even when `subagent_\*` tools are available\./,
+		`${sectionName} must choose native Agent when neither worker definition exists`,
+	);
+	assert.match(
+		section,
+		/If no delegation mechanism is available, stop/,
+		`${sectionName} must stop when delegation is impossible`,
+	);
+}
+
+test("Markdown section extraction isolates policy text from sibling sections", () => {
+	const markdown = [
+		"# Agent",
+		"## Context contract",
+		"context-only policy",
+		"### Context detail",
+		"nested context policy",
+		"## Tool safety",
+		"tool-only policy",
+	].join("\n");
+
+	const context = readMarkdownSection(markdown, "Context contract");
+
+	assert.match(context, /context-only policy/);
+	assert.match(context, /nested context policy/);
+	assert.doesNotMatch(context, /tool-only policy/);
+});
+
 test("packaged agents use YAML list syntax for tool allowlists", () => {
 	const agentsDir = join(PACKAGE_ROOT, "assets", "agents");
 	const agentFiles = readdirSync(agentsDir).flatMap((entry) =>
@@ -100,6 +228,184 @@ test("jd-fix-agent packaged allowlist includes write tools", () => {
 	}
 });
 
+test("gentle-ai-worker packages the exact scoped writer contract", () => {
+	const agentsDir = join(PACKAGE_ROOT, "assets", "agents");
+	const agentPath = join(agentsDir, "gentle-ai-worker.md");
+	assert.ok(existsSync(agentPath), "gentle-pi must package gentle-ai-worker.md");
+	for (const genericName of ["worker.md", "generic-writer.md"]) {
+		assert.ok(
+			!existsSync(join(agentsDir, genericName)),
+			`the package-owned writer must not use collision-prone ${genericName}`,
+		);
+	}
+
+	const { name, source, tools } = readAgentDefinition(agentPath);
+	assert.equal(name, "gentle-ai-worker");
+	assert.deepEqual(tools, [
+		"read",
+		"grep",
+		"find",
+		"edit",
+		"write",
+		"bash",
+		"mem_save",
+	]);
+	assert.ok(
+		tools.every((tool) => !tool.startsWith("subagent_")),
+		"a subagent must not be able to delegate",
+	);
+	assert.ok(!tools.includes("glob"), "the unsupported glob tool must not return");
+
+	const interactionContract = readMarkdownSection(source, "Interaction contract");
+	assert.doesNotMatch(
+		interactionContract,
+		/```text/,
+		"the interaction section must not define a second normative envelope",
+	);
+	assert.match(interactionContract, /stop editing/i);
+	assert.match(interactionContract, /full schema in the Return contract/);
+	assert.match(interactionContract, /`status: interaction_required`/);
+	assert.match(interactionContract, /nested `interaction_required` payload/);
+
+	const returnContract = readTextContract(source, "Return contract");
+	assert.deepEqual(contractFields(returnContract), [
+		"status",
+		"summary",
+		"files_changed",
+		"tdd_evidence",
+		"validation",
+		"risks",
+		"review_focus",
+		"skill_resolution",
+		"interaction_required",
+	]);
+	assert.deepEqual(nestedContractFields(returnContract, "interaction_required"), [
+		"question",
+		"reason",
+		"options",
+		"unblock_response",
+	]);
+	assert.match(
+		returnContract,
+		/skill_resolution: paths-injected \| paths-invalid \| none/,
+	);
+	assert.equal(
+		(source.match(/```text/g) ?? []).length,
+		1,
+		"the Return contract must be the single authoritative full handoff schema",
+	);
+	assert.doesNotMatch(source, /fallback-(?:registry|path)/);
+
+	const returnContractSection = readMarkdownSection(source, "Return contract");
+	assert.match(
+		returnContractSection,
+		/Use `skill_resolution: paths-invalid` only when the parent injected one or more exact skill paths and any supplied path cannot be read/,
+	);
+	assert.match(
+		returnContractSection,
+		/With `skill_resolution: paths-invalid`, keep `status: blocked`/,
+	);
+
+	const contextContract = readMarkdownSection(source, "Context contract");
+	assert.match(contextContract, /pre-existing untracked targets explicitly listed by the parent/);
+	assert.match(contextContract, /new files required by the delegated task/);
+
+	const implementationRules = readMarkdownSection(source, "Implementation rules");
+	assert.match(implementationRules, /`blocked` only for a non-human technical blocker/);
+
+	const toolSafety = readMarkdownSection(source, "Tool safety");
+	assert.match(toolSafety, /sensitive files/);
+	assert.match(toolSafety, /stage, commit, push, publish/);
+
+	const memorySafety = readMarkdownSection(source, "Memory safety");
+	assert.match(memorySafety, /secrets, credentials, personal data/);
+	assert.match(memorySafety, /raw untrusted repository/);
+
+	const testDiscipline = readMarkdownSection(source, "Test discipline");
+	assert.match(testDiscipline, /Strict TDD is active/);
+	assert.match(testDiscipline, /not active/);
+	assert.match(
+		testDiscipline,
+		/Broad suites, builds, formatters, or linters may run only when explicitly authorized by the parent\./,
+	);
+	assert.match(testDiscipline, /Keep every command exact and verify its scope before execution\./);
+	assert.doesNotMatch(testDiscipline, /clearly required by the repository contract/);
+});
+
+test("installSddAssets installs gentle-ai-worker with a loader-compatible scoped identity", () => {
+	const temporaryAgentHome = mkdtempSync(join(tmpdir(), "gentle-pi-agent-home-"));
+	const previousAgentHome = process.env.GENTLE_PI_AGENT_HOME;
+
+	try {
+		process.env.GENTLE_PI_AGENT_HOME = temporaryAgentHome;
+		installSddAssets(PACKAGE_ROOT, true);
+
+		const installedAgentsDir = join(temporaryAgentHome, "agents");
+		const installedAgentPath = join(installedAgentsDir, "gentle-ai-worker.md");
+		assert.ok(existsSync(installedAgentPath), "the production installer must install gentle-ai-worker.md");
+		for (const genericName of ["worker.md", "generic-writer.md"]) {
+			assert.ok(
+				!existsSync(join(installedAgentsDir, genericName)),
+				`the installer must not create collision-prone ${genericName}`,
+			);
+		}
+
+		const { name, source, tools } = readAgentDefinition(installedAgentPath);
+		const normalizedRuntimeIdentity = name.trim().toLowerCase();
+		assert.equal(normalizedRuntimeIdentity, "gentle-ai-worker");
+		assert.deepEqual(tools, [
+			"read",
+			"grep",
+			"find",
+			"edit",
+			"write",
+			"bash",
+			"mem_save",
+		]);
+		assert.doesNotMatch(
+			readAgentFrontmatter(installedAgentPath),
+			/^package\s*:/m,
+			"package frontmatter must not alter external loader identity",
+		);
+		assert.doesNotMatch(source, /^name:\s*(?:worker|generic-writer)$/m);
+	} finally {
+		if (previousAgentHome === undefined) {
+			delete process.env.GENTLE_PI_AGENT_HOME;
+		} else {
+			process.env.GENTLE_PI_AGENT_HOME = previousAgentHome;
+		}
+		rmSync(temporaryAgentHome, { recursive: true, force: true });
+	}
+
+	assert.equal(process.env.GENTLE_PI_AGENT_HOME, previousAgentHome);
+	assert.ok(
+		!existsSync(temporaryAgentHome),
+		"the integration test must delete only its temporary agent home",
+	);
+});
+
+test("bounded implementation routing uses the same explicit fallback in both policy sections", () => {
+	const routing = readFileSync(
+		join(PACKAGE_ROOT, "assets", "orchestrator-delegation.md"),
+		"utf8",
+	);
+	const simpleDelegation = readMarkdownSection(routing, "2. Simple Delegation");
+	const mandatoryDelegation = readMarkdownSection(routing, "Mandatory Delegation Triggers");
+
+	assertWorkerFallbackRouting(simpleDelegation, "Simple Delegation");
+	assertWorkerFallbackRouting(mandatoryDelegation, "Mandatory Delegation Triggers");
+	assert.doesNotMatch(
+		routing,
+		/non-normative compatibility quotation|former wording is retained|no-runtime inline exception|superseded by the stop requirement/,
+		"model-facing routing must not retain contradictory dead prose",
+	);
+	assert.doesNotMatch(
+		routing,
+		/`generic-writer`/,
+		"routing must not revive the collision-prone generic package name",
+	);
+});
+
 test("pi-pretty wrapper uses real package path resolution for pnpm symlink installs", () => {
 	const wrapper = readFileSync(
 		join(PACKAGE_ROOT, "extensions", "pi-pretty.ts"),