gentle-pi 2.1.2 → 2.3.0

package/tests/orchestrator-budget.test.ts

@@ -1,6 +1,6 @@
 import assert from "node:assert/strict";
 import { spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import test, { after } from "node:test";
@@ -9,8 +9,8 @@ import test, { after } from "node:test";
 // orchestrator-lazy-diet migration tests
 //
 // Locks the split of the always-on `assets/orchestrator.md` into a thin core
-// plus three path-substituted lazy reference files (see design.md "Core
-// budget rebuilt from measured drafts" and "Appendix: drafted core texts").
+// plus lazy reference files (see design.md "Core budget rebuilt from measured
+// drafts" and "Appendix: drafted core texts").
 //
 // `getOrchestratorPrompt`'s rendered return value is memoized in a
 // module-level cache (first-read-wins for the process lifetime — see design.md
@@ -19,17 +19,19 @@ import test, { after } from "node:test";
 // ambient environment variables, so production runtime asset resolution stays
 // deterministic. The representative production assets directory below is
 // populated by COPYING the real repo assets (dynamically, at test-run time)
-// into a short-path tmpdir — this isolates byte-budget measurement from the
-// real repo's absolute path length while keeping content representative of
-// production. Tests that need to inspect the real repo files directly (the
-// disposition-mapped union sweep, the core-alone token assertions) read
-// `assets/*.md` directly via `readFileSync`, sidestepping the cache entirely.
+// into short and deliberately long tmpdir paths. This isolates byte-budget
+// measurement from the real repo's absolute path length while keeping content
+// representative of production. Tests that need to inspect the real repo files
+// directly (the disposition-mapped union sweep, the core-alone token
+// assertions) read `assets/*.md` directly via `readFileSync`, sidestepping the
+// cache entirely.
 // ---------------------------------------------------------------------------
 
 const REPO_ROOT = join(import.meta.dirname, "..");
 const REAL_ASSETS_DIR = join(REPO_ROOT, "assets");
 const FIXTURE_PATH = join(import.meta.dirname, "fixtures", "orchestrator.pre-diet.md");
-const BUDGET_BYTES = 10240;
+const BUDGET_BYTES = 8192;
+const MIN_CONTROLLED_LONG_ASSETS_ROOT_CHARS = 93;
 
 const LAZY_ASSET_NAMES = [
 	"orchestrator.md",
@@ -38,42 +40,56 @@ const LAZY_ASSET_NAMES = [
 	"orchestrator-memory.md",
 	"orchestrator-skills.md",
 ] as const;
+const LAZY_REFERENCE_FILE_NAMES = LAZY_ASSET_NAMES.slice(1);
 
-const representativeProductionAssetsDir = mkdtempSync(join(tmpdir(), "gp-b-"));
-for (const name of LAZY_ASSET_NAMES) {
-	const src = join(REAL_ASSETS_DIR, name);
-	writeFileSync(
-		join(representativeProductionAssetsDir, name),
-		existsSync(src) ? readFileSync(src) : `stub placeholder for ${name} (not authored yet)\n`,
-	);
+function copyRequiredLazyAssets(destination: string): void {
+	for (const name of LAZY_ASSET_NAMES) {
+		const source = join(REAL_ASSETS_DIR, name);
+		assert.ok(existsSync(source), `missing packaged lazy asset: ${name}`);
+		copyFileSync(source, join(destination, name));
+	}
 }
-const { __testing } = await import("../extensions/gentle-ai.ts");
 
-const MIN_REALISTIC_INSTALL_ASSETS_PATH_CHARS = 59;
+const representativeProductionAssetsDir = mkdtempSync(join(tmpdir(), "gp-b-"));
+copyRequiredLazyAssets(representativeProductionAssetsDir);
+const { __testing } = await import("../extensions/gentle-ai.ts");
 
-// Realistic-length assets path: mirrors an actual installed path such as
-// `~/.pi/agent/npm/node_modules/gentle-pi/assets`, so the budget assertion is
-// not laundered through an artificially short mkdtemp path. The helper is also
-// exercised in a fresh child process (`tests/fixtures/measure-orchestrator-prompt.mjs`)
-// to keep production cache behavior separate from fixture measurements.
-const realisticBaseDir = mkdtempSync(join(tmpdir(), "gp-realistic-"));
-const realisticDir = join(realisticBaseDir, ".pi", "agent", "npm", "node_modules", "gentle-pi", "assets");
-mkdirSync(realisticDir, { recursive: true });
+// A controlled long assets root proves the parent prompt remains within the
+// canonical budget independently of the checkout or installed-package path.
+// The child-process measurement keeps production cache behavior separate from
+// fixture measurements.
+// The root is built to one exact length rather than "tmpdir plus a long
+// suffix". The prompt declares the absolute root once, so it grows one byte
+// per root character, and a 48-character macOS tmpdir pushed the previous
+// construction to 164 characters where a 4-character Linux /tmp gave 121.
+// A fixed length makes every platform measure the same budget claim.
+const CONTROLLED_LONG_ASSETS_ROOT_CHARS = 128;
+const controlledLongBaseDir = mkdtempSync(join(tmpdir(), "gp-long-"));
+const controlledLongSegmentChars = CONTROLLED_LONG_ASSETS_ROOT_CHARS - join(controlledLongBaseDir, "x", "assets").length + 1;
 assert.ok(
-	realisticDir.length >= MIN_REALISTIC_INSTALL_ASSETS_PATH_CHARS,
-	`realistic scratch assets path is only ${realisticDir.length} chars, need >= ${MIN_REALISTIC_INSTALL_ASSETS_PATH_CHARS} to mirror a real install path`,
+	controlledLongSegmentChars >= 1,
+	`tmpdir ${tmpdir()} is too long to build a ${CONTROLLED_LONG_ASSETS_ROOT_CHARS}-char controlled assets root`,
 );
-for (const name of LAZY_ASSET_NAMES) {
-	const src = join(REAL_ASSETS_DIR, name);
-	writeFileSync(
-		join(realisticDir, name),
-		existsSync(src) ? readFileSync(src) : `stub placeholder for ${name} (not authored yet)\n`,
-	);
-}
+const controlledLongAssetsDir = join(
+	controlledLongBaseDir,
+	"path-independent-prompt-budget-".repeat(Math.ceil(controlledLongSegmentChars / 31)).slice(0, controlledLongSegmentChars),
+	"assets",
+);
+mkdirSync(controlledLongAssetsDir, { recursive: true });
+assert.equal(
+	controlledLongAssetsDir.length,
+	CONTROLLED_LONG_ASSETS_ROOT_CHARS,
+	`controlled long assets root is ${controlledLongAssetsDir.length} chars, want exactly ${CONTROLLED_LONG_ASSETS_ROOT_CHARS}`,
+);
+assert.ok(
+	controlledLongAssetsDir.length >= MIN_CONTROLLED_LONG_ASSETS_ROOT_CHARS,
+	`controlled long assets root is only ${controlledLongAssetsDir.length} chars, need >= ${MIN_CONTROLLED_LONG_ASSETS_ROOT_CHARS}`,
+);
+copyRequiredLazyAssets(controlledLongAssetsDir);
 
 after(() => {
 	rmSync(representativeProductionAssetsDir, { recursive: true, force: true });
-	rmSync(realisticBaseDir, { recursive: true, force: true });
+	rmSync(controlledLongBaseDir, { recursive: true, force: true });
 });
 
 function readRealAsset(name: string): string {
@@ -98,7 +114,7 @@ function measureOrchestratorPromptBytes(assetsDir: string): number {
 // 2.2 — Byte budget (Spec: Always-On Injection Byte Budget)
 // ---------------------------------------------------------------------------
 
-test("getOrchestratorPrompt return value stays within the 10,240 B budget (short-path stub sanity check)", () => {
+test("getOrchestratorPrompt return value stays within the canonical 8,192 B budget at a short assets root", () => {
 	const rendered = __testing.renderOrchestratorPrompt(representativeProductionAssetsDir);
 	const bytes = Buffer.byteLength(rendered, "utf8");
 	assert.ok(
@@ -107,33 +123,46 @@ test("getOrchestratorPrompt return value stays within the 10,240 B budget (short
 	);
 });
 
-test(`getOrchestratorPrompt return value stays within the 10,240 B budget at a realistic (>= ${MIN_REALISTIC_INSTALL_ASSETS_PATH_CHARS} char) install path length`, () => {
-	const bytes = measureOrchestratorPromptBytes(realisticDir);
+test(`getOrchestratorPrompt keeps a controlled long (>= ${MIN_CONTROLLED_LONG_ASSETS_ROOT_CHARS} char) assets root within the canonical budget`, () => {
+	const rendered = __testing.renderOrchestratorPrompt(controlledLongAssetsDir);
+	const bytes = measureOrchestratorPromptBytes(controlledLongAssetsDir);
+	assert.equal(bytes, Buffer.byteLength(rendered, "utf8"), "child-process and direct render byte counts must match");
 	assert.ok(
 		bytes <= BUDGET_BYTES,
-		`getOrchestratorPrompt() returned ${bytes} B at a realistic ${realisticDir.length}-char ASSETS_DIR path, exceeds the ${BUDGET_BYTES} B budget`,
+		`getOrchestratorPrompt() returned ${bytes} B at controlled ${controlledLongAssetsDir.length}-char assets root, exceeds the ${BUDGET_BYTES} B budget`,
 	);
+	assert.equal(
+		rendered.split(controlledLongAssetsDir).length - 1,
+		1,
+		"the absolute assets root must be declared exactly once",
+	);
+	assert.ok(
+		rendered.includes(`Package assets root: \`${controlledLongAssetsDir}\`. Lazy asset paths below are relative to this root.`),
+		"the parent prompt must declare how to resolve relative lazy asset paths",
+	);
+	for (const name of LAZY_REFERENCE_FILE_NAMES) {
+		assert.ok(rendered.includes(`\`${name}\``), `lazy asset filename is missing: ${name}`);
+	}
+	assert.doesNotMatch(rendered, /\{\{/, "unresolved {{...}} placeholder leaked into the rendered prompt");
 });
 
 // ---------------------------------------------------------------------------
 // 2.3 — Disposition-mapped union sweep (Spec: No Normative Content Loss +
 // Pointer reachability)
 //
-// Every normative line of the frozen pre-diet fixture is assigned to exactly
-// one documented disposition: CORE_VERBATIM (byte-identical in the new
-// 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.
+// Every normative line of the frozen pre-diet fixture is assigned to a
+// documented disposition: CORE_VERBATIM (byte-identical in the core),
+// LAZY_VERBATIM (byte-identical in one specific lazy file), OBSOLETE
+// (intentionally absent), or REPLACED (superseded by the focused #3417 asset
+// policy ratchets below). REPLACED preserves the historical fixture without
+// treating a retired prompt mirror as a current normative source.
 // ---------------------------------------------------------------------------
 
 type Target = "core" | "delegation" | "memory" | "skills";
 
 interface DispositionRange {
 	lines: [number, number];
-	target: Target | "obsolete";
+	target: Target | "obsolete" | "replaced";
 	label: string;
 }
 
@@ -158,13 +187,37 @@ const DISPOSITION_MAP: DispositionRange[] = [
 	{ lines: [25, 29], target: "delegation", label: "Language Boundary LB5 (exceptions)" },
 	{ lines: [31, 40], target: "core", label: "Mental Model" },
 	{ lines: [42, 42], target: "core", label: "Work Routing Ladder heading" },
-	{ lines: [44, 110], target: "delegation", label: "Work Routing Ladder body + Pi Subagent Model Routing" },
+	{
+		lines: [44, 97],
+		target: "replaced",
+		label: "Pre-RDD routing detail replaced by focused direct-delegation guidance (#3417)",
+	},
+	{
+		lines: [98, 107],
+		target: "obsolete",
+		label: "Size/risk-selected SDD tier replaced by explicit-request/accepted-proposal selection (#312)",
+	},
+	{
+		lines: [108, 108],
+		target: "replaced",
+		label: "Earlier SDD trigger wording replaced by the focused SDD boundary (#3417)",
+	},
+	{
+		lines: [109, 110],
+		target: "obsolete",
+		label: "Size-gated SDD entry replaced by explicit-selection gating (#312)",
+	},
 	{ lines: [112, 112], target: "core", label: "Delegation Rules heading" },
 	{ lines: [114, 114], target: "core", label: "Delegation Rules core question" },
 	{
-		lines: [116, 132],
-		target: "delegation",
-		label: "Delegation Rules table + Mandatory Triggers preamble",
+		lines: [116, 126],
+		target: "obsolete",
+		label: "Pre-canon delegation table replaced by the mirrored gentle-ai canon table (#312)",
+	},
+	{
+		lines: [128, 132],
+		target: "replaced",
+		label: "Pre-RDD trigger wording replaced by focused direct-delegation guidance (#3417)",
 	},
 	{
 		lines: [133, 133],
@@ -172,14 +225,27 @@ const DISPOSITION_MAP: DispositionRange[] = [
 		label: "Superseded no-runtime inline exception",
 	},
 	{
-		lines: [134, 181],
-		target: "delegation",
-		label: "Mandatory Triggers remainder + Cost/Context Balance + Canonical Workflows + Review Lens Selection",
+		lines: [134, 167],
+		target: "replaced",
+		label: "Pre-RDD trigger and workflow wording replaced by focused delegation guidance (#3417)",
+	},
+	{
+		lines: [169, 181],
+		target: "obsolete",
+		label: "Parent-selected review lens table replaced by native RAR lens ownership (#312)",
 	},
 	{ lines: [183, 191], target: "core", label: "SDD Workflow pointer" },
 	{ lines: [193, 193], target: "core", label: "Memory Contract heading" },
-	{ lines: [195, 195], target: "core", label: "Memory Contract intro" },
-	{ lines: [197, 201], target: "core", label: "Memory Contract Non-SDD delegation" },
+	{
+		lines: [195, 195],
+		target: "replaced",
+		label: "Verbose memory introduction replaced by compact parent/subagent ownership (#3417)",
+	},
+	{
+		lines: [197, 201],
+		target: "replaced",
+		label: "Verbose non-SDD memory forwarding replaced by compact ownership (#3417)",
+	},
 	{ lines: [203, 230], target: "memory", label: "Memory Contract SDD phases table + artifact keys + lifecycle rule" },
 	{ lines: [232, 232], target: "core", label: "Skill Registry Protocol heading" },
 	{ lines: [234, 253], target: "skills", label: "Skill Registry Protocol detail" },
@@ -198,9 +264,18 @@ function isNormativeLine(line: string): boolean {
 }
 
 const fixtureLines = readFileSync(FIXTURE_PATH, "utf8").split("\n");
+// Fixture lines 187 and 191 predate the root-relative lazy-asset contract and
+// canonical-authority resolution. Keep their coverage by asserting the
+// intentionally updated production wording instead of weakening the range.
+const CURRENT_SDD_WORKFLOW_PATH = "`sdd-orchestrator-workflow.md`";
+const CURRENT_HARD_PREFLIGHT_INVARIANT = "Hard preflight invariant: `openspec/config.yaml`, existing SDD changes, installed `.pi`/global SDD assets, or a todo named \"preflight\" are not session preflight. Do not mark SDD preflight complete, start `sdd-init`, launch SDD subagents/chains, or move to explore/proposal/spec/design/tasks until this session has an injected `## SDD Session Preflight` block or a canonical-authority resolution. Defaults and capability constraints may resolve fields without confirmation prompts; preserve unresolved-choice and safety gates.";
 const SUPERSEDED_LIFECYCLE_REVIEW_LINES = new Set([
 	70,
+	// 74/77: the loose mode-choice background lines were replaced by the
+	// marked gentle-pi:background-subagents policy block (issue #256).
+	74,
 	76,
+	77,
 	92,
 	125,
 	126,
@@ -215,6 +290,7 @@ const SUPERSEDED_LIFECYCLE_REVIEW_LINES = new Set([
 ]);
 
 for (const range of DISPOSITION_MAP) {
+	if (range.target === "replaced") continue;
 	test(
 		`disposition-mapped union: ${range.label} (fixture:${range.lines[0]}-${range.lines[1]}) -> ${range.target}`,
 		() => {
@@ -226,6 +302,12 @@ for (const range of DISPOSITION_MAP) {
 				const raw = fixtureLines[ln - 1];
 				if (raw === undefined || !isNormativeLine(raw)) continue;
 				const trimmed = raw.trim();
+				const expected =
+					ln === 187
+						? CURRENT_SDD_WORKFLOW_PATH
+						: ln === 191
+							? CURRENT_HARD_PREFLIGHT_INVARIANT
+							: trimmed;
 				if (SUPERSEDED_LIFECYCLE_REVIEW_LINES.has(ln)) {
 					assert.ok(
 						!targetContent.includes(trimmed),
@@ -241,8 +323,8 @@ for (const range of DISPOSITION_MAP) {
 					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})`,
+					targetContent.includes(expected),
+					`normative line lost: fixture:${ln} "${expected}" not found verbatim in ${TARGET_FILE[range.target]} (disposition: ${range.target}, section: ${range.label})`,
 				);
 			}
 		},
@@ -254,32 +336,28 @@ for (const range of DISPOSITION_MAP) {
 // string alone, no lazy union.
 // ---------------------------------------------------------------------------
 
-test("core-alone: load-bearing delegation tokens present without lazy union", () => {
+test("core-alone: load-bearing direct-delegation tokens remain without lazy union", () => {
 	const core = readRealAsset("orchestrator.md");
 	assert.match(core, /4-file rule/);
 	assert.match(core, /Multi-file write rule/);
-	assert.match(core, /Lifecycle gate rule/);
 	assert.match(core, /Incident rule/);
+	assert.match(core, /Verification rule/);
 	assert.match(core, /Long-session rule/);
-	assert.match(core, /Review actor rule/);
 });
 
-test("core-alone: receipt-only lifecycle and independent safety are present without lazy union", () => {
+test("core-alone: dynamic Gentle AI ownership replaces package lifecycle instructions", () => {
 	const core = readRealAsset("orchestrator.md");
-	assert.match(core, /start -> finalize -> validate/i);
-	assert.match(core, /Compact gates use zero actors/i);
-	assert.match(core, /Release from protected `main` may bypass receipt validation only when/i);
-	assert.match(core, /Major and post-incident releases require explicit extraordinary review/i);
-	assert.match(core, /Dangerous-command safety remains independent and authoritative/i);
-	assert.match(core, /SDD completion adds no review or Judgment Day pass/i);
+	assert.match(core, /dynamically supplies runtime-specific RDD instructions via generated Pi APPEND_SYSTEM composition/);
+	assert.match(core, /if absent or unsupported, this package does not invent or fall back/);
+	assert.doesNotMatch(core, /start -> finalize -> validate/i);
+	assert.doesNotMatch(core, /receipt validation/i);
 });
 
-test("lazy bounded-review contract lists all four review lens names", () => {
-	const content = `${readRealAsset("orchestrator.md")}\n${readRealAsset("orchestrator-delegation.md")}`;
-	assert.match(content, /review-risk/);
-	assert.match(content, /review-reliability/);
-	assert.match(content, /review-resilience/);
-	assert.match(content, /review-readability/);
+test("lazy delegation detail has no native RDD controller markers", () => {
+	const delegation = readRealAsset("orchestrator-delegation.md");
+	for (const marker of ["next_transition", "review.capture-result", "reconcile-terminal-mirrors"]) {
+		assert.ok(!delegation.includes(marker), `stale RDD marker retained: ${marker}`);
+	}
 });
 
 test("live orchestrator assets remove the stale strong-gate retry contract", () => {
@@ -320,20 +398,11 @@ test("relocated lazy bodies are not double-delivered in the always-on core", ()
 	);
 });
 
-test("relocated lazy files are reachable via in-core pointer paths", () => {
+test("relocated lazy files are reachable via root-relative in-core filenames", () => {
 	const rendered = __testing.getOrchestratorPrompt();
-	assert.ok(
-		rendered.includes(join(REAL_ASSETS_DIR, "orchestrator-delegation.md")),
-		"core is missing a reachable pointer to orchestrator-delegation.md",
-	);
-	assert.ok(
-		rendered.includes(join(REAL_ASSETS_DIR, "orchestrator-memory.md")),
-		"core is missing a reachable pointer to orchestrator-memory.md",
-	);
-	assert.ok(
-		rendered.includes(join(REAL_ASSETS_DIR, "orchestrator-skills.md")),
-		"core is missing a reachable pointer to orchestrator-skills.md",
-	);
+	for (const name of LAZY_REFERENCE_FILE_NAMES) {
+		assert.ok(rendered.includes(`\`${name}\``), `core is missing a reachable pointer to ${name}`);
+	}
 });
 
 // ---------------------------------------------------------------------------

package/tests/orchestrator-rdd-ownership.test.ts

@@ -0,0 +1,103 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import test from "node:test";
+
+const ROOT = join(import.meta.dirname, "..");
+const ASSETS = join(ROOT, "assets");
+const BOUNDARY =
+	"Gentle AI dynamically supplies runtime-specific RDD instructions via generated Pi APPEND_SYSTEM composition. Follow only those exact native instructions; if absent or unsupported, this package does not invent or fall back.";
+
+function read(relativePath: string): string {
+	return readFileSync(join(ROOT, relativePath), "utf8");
+}
+
+const core = read("assets/orchestrator.md");
+const delegation = read("assets/orchestrator-delegation.md");
+const staticPrompts = `${core}\n${delegation}`;
+
+test("static prompts omit stale native RDD lifecycle mirrors", () => {
+	for (const marker of [
+		"Authority-First Terminal Procedure",
+		"reconcile-terminal-mirrors",
+		"Native Bounded Review Orchestration",
+		"Continue after a stop reason code",
+		"gentle-ai review status",
+		"next_transition",
+		"start -> finalize -> validate",
+		"review.capture-result",
+		"review.validate",
+		"reviewGate.result",
+	]) {
+		assert.ok(!staticPrompts.includes(marker), `stale RDD marker remains: ${marker}`);
+	}
+});
+
+test("lossless blocking prompts route every closed single-select envelope through the native closed tool", () => {
+	for (const clause of [
+		"For every strictly closed single-select envelope",
+		"ask_user_choice",
+		"envelope-owned canonical option token as opaque `value`",
+		"returns exactly one `value`",
+		"externally owned open/free-text questionnaire",
+		"never for a closed domain",
+		"exact captured provider-owned choice invocation",
+	]) {
+		assert.ok(delegation.includes(clause), `lossless prompt is missing: ${clause}`);
+	}
+});
+
+test("static prompts declare one dynamic Gentle AI RDD ownership boundary", () => {
+	assert.equal(staticPrompts.split(BOUNDARY).length - 1, 1, "expected one dynamic RDD ownership boundary");
+	assert.ok(core.includes(BOUNDARY), "the Pi parent prompt owns the single boundary");
+	assert.ok(!delegation.includes(BOUNDARY), "generic delegation detail must not gain RDD text");
+});
+
+test("rendered parent prompt keeps the RDD boundary while omitting lifecycle mirrors", async () => {
+	const { __testing } = await import("../extensions/gentle-ai.ts");
+	const rendered = __testing.getOrchestratorPrompt();
+	assert.ok(rendered.includes(BOUNDARY));
+	for (const marker of ["Authority-First Terminal Procedure", "reconcile-terminal-mirrors", "next_transition"]) {
+		assert.ok(!rendered.includes(marker), `rendered parent prompt leaked: ${marker}`);
+	}
+	assert.ok(Buffer.byteLength(rendered, "utf8") <= 8192, "the rendered parent prompt must stay below the reduced 8 KiB budget");
+});
+
+test("static prompts retain normal SDD and delegated-work guidance", () => {
+	for (const heading of ["## SDD Workflow (lazy-loaded)", "## Memory Contract"]) {
+		assert.ok(core.includes(heading), `core lost ${heading}`);
+	}
+	for (const heading of [
+		"### Delegation Rules",
+		"#### Background Subagent Policy",
+		"#### Allowed edit surfaces (MANDATORY)",
+		"### 3. SDD (optional)",
+	]) {
+		assert.ok(delegation.includes(heading), `delegation lost ${heading}`);
+	}
+});
+
+test("always-on parent prompt requires a narrow writer edit surface before launch", () => {
+	assert.match(core, /Before launching (?:a )?bounded writer/i);
+	assert.match(core, /`gentle-ai-worker`/);
+	assert.match(core, /`worker`/);
+	assert.match(core, /## Allowed edit surfaces/);
+	assert.match(core, /repository-relative/i);
+	assert.match(core, /never `\.`|never a bare repository root/i);
+	assert.match(core, /do not ask the human to author paths or globs/i);
+});
+
+test("review integration documents the opaque Pi adapter and Go-owned authority boundary", () => {
+	const docs = read("docs/review-integration.md");
+	for (const marker of [
+		"Buffer → Buffer/error",
+		"exact Go-issued materialize/submission tokens",
+		"typed Pi transport refusal fails closed",
+		"Go owns worktree, lineage, candidate freeze, lens selection, correction, validator, approval burn, and review semantics",
+		"Delivery commands remain ordinary repository-policy operations.",
+		"package has no durable receipt or policy authority",
+		"static assets intentionally omit lifecycle instructions",
+	]) {
+		assert.ok(docs.includes(marker), `review integration doc is missing: ${marker}`);
+	}
+});