gentle-pi 4.2.0 → 4.4.0

package/tests/startup-home-repo.test.ts

@@ -168,3 +168,37 @@ test("startup returns before the native review negotiation finishes, and the fir
 	await __testing.startupNegotiationSettled();
 	assert.equal(calls.target, 1, "the negotiation still completes after startup");
 });
+
+// gentle-shell#2195: the RDD line sits in the cached system-prompt prefix, so a
+// session keeps the line it first rendered and re-renders only when RDD turns
+// off or back on.
+test("a session keeps its first RDD status line until the off state changes", async (t) => {
+	const { cwd, environment } = fixture(t, false);
+	let status: { effective: string; source: string } | undefined;
+	const cli = {
+		reviewMode: async () => {
+			if (status === undefined) throw new Error("native review CLI unavailable");
+			return { operation: "status", scope: "clone", status: { global: "", cloneLocal: status.effective, ...status } };
+		},
+	} as unknown as NativeReviewCli;
+	const { handlers, ctx } = start(cli, cwd, environment);
+	const line = async () => {
+		__testing.clearRddStatusMemoForTesting();
+		const event = { systemPrompt: "base", systemPromptOptions: { appendSystemPrompt: "" } };
+		await handlers.get("before_agent_start")!(event, ctx);
+		return /Receipt-driven development: [^;\n]*/.exec(event.systemPromptOptions.appendSystemPrompt)?.[0];
+	};
+	await handlers.get("session_shutdown")!({}, ctx);
+	assert.equal(await line(), "Receipt-driven development: unknown (native status unavailable)");
+	status = { effective: "on", source: "clone_local" };
+	assert.equal(await line(), "Receipt-driven development: unknown (native status unavailable)", "unknown to on keeps the prompt prefix");
+	status = { effective: "on", source: "global" };
+	assert.equal(await line(), "Receipt-driven development: unknown (native status unavailable)", "a source change keeps the prompt prefix");
+	status = { effective: "off", source: "clone_local" };
+	assert.equal(await line(), "Receipt-driven development: off (decided by clone_local)", "turning RDD off re-renders");
+	status = { effective: "on", source: "global" };
+	assert.equal(await line(), "Receipt-driven development: on (decided by global)", "turning RDD back on re-renders");
+	await handlers.get("session_shutdown")!({}, ctx);
+	status = { effective: "on", source: "clone_local" };
+	assert.equal(await line(), "Receipt-driven development: on (decided by clone_local)", "a new session renders the current line");
+});

package/tests/support/orchestrator-modules.ts

@@ -6,6 +6,7 @@ import { join } from "node:path";
 // so a moved clause stays pinned instead of silently disappearing.
 export const DELEGATION_MODULES = [
 	"orchestrator-delegation.md",
+	"orchestrator-delegation-reference.md",
 	"orchestrator-tracking.md",
 	"orchestrator-verification.md",
 	"orchestrator-writer.md",

package/tests/task-size-routing-contract.test.ts

@@ -61,7 +61,7 @@ test("AC2: counts never classify, and the step-count classifier is gone", () =>
 test("AC3: small work runs its checks inline and keeps test-first", () => {
 	const size = sectionOf(core, "## Task Size");
 	for (const clause of [
-		"run the focused test and the suite inline, once each",
+		"run the focused test and the suite inline in one command",
 		"observe RED inline before the fix",
 		"No explore, worker, or verifier",
 		"no feature document, mirror, or commits unless the user asks",
@@ -80,7 +80,8 @@ test("AC3: small work runs its checks inline and keeps test-first", () => {
 test("AC4: each mechanism turns on only by its own trigger and size is re-evaluated after", () => {
 	const triggers = sectionOf(core, "## Mechanisms");
 	for (const clause of [
-		"each mechanism turns on only by its own trigger",
+		// Writer-rule fix: a trigger holds only when its condition truly holds.
+		"each mechanism turns on only when its own trigger condition truly holds",
 		"re-evaluate task size",
 		"1. **Ask**",
 		"2. **Evidence-budget rule**",
@@ -90,7 +91,8 @@ test("AC4: each mechanism turns on only by its own trigger and size is re-evalua
 		"6. **Incident rule**",
 		"7. **Context backstop**",
 		"open product or design decision",
-		"high risk",
+		// Verification by named risk: rule 3 names the escalated high-risk item.
+		"named high-risk item (assess `escalate`)",
 		"never by file count",
 		// gentle-shell#1731: the writer fires on reasons, not on size alone.
 		"never by file count or a large task alone",
@@ -134,15 +136,29 @@ test("AC5: the high-risk list lives once in the core, native tier wins, unclear
 const MODULE_BUDGETS: Record<string, number> = {
 	// gentle-shell#1731 merge with main: main's session subject/state guidance plus the reason-based Writer rule (20,000 -> 20,500 B).
 	// gentle-shell#1269: capability-compatible routing rule checked before delegation (20,500 -> 20,800 B).
-	"orchestrator-delegation.md": 20_800,
+	// S9 canon change: conditional triggers, behavior-unit writer threshold, named-risk verifier, invariants,
+	// and the PRESERVE differential pointer mirrored from gentle-ai 5f6faa16 (20,800 -> 21,900 B).
+	// Pain-point iteration S11 T2: the parent read this module in most runs and kept ~5K tokens of it in the
+	// transcript on every later call, so it became the lean delegation card (21,900 -> 7,000 B) and the
+	// reference material moved to orchestrator-delegation-reference.md, read only when a situation names it.
+	// Pain-point iteration S13 (C10): the Preparation trigger tells the parent not to read what the worker will
+	// read and to pass paths, not content (7,000 -> 7,100 B; every other card sentence is pinned by a contract).
+	// S15: units of about 100 changed lines or less always run inline (7,100 -> 7,300 B).
+	"orchestrator-delegation.md": 7_300,
+	"orchestrator-delegation-reference.md": 14_800,
 	// gentle-shell#1731 T23: Close gate accepts one Needs your decision result as a stop (12,500 -> 12,600 B).
-	"orchestrator-tracking.md": 12_600,
+	// S14: close the open slice before a high-risk commit; outcomes per commit (12,600 -> 12,850 B).
+	"orchestrator-tracking.md": 12_850,
 	// gentle-shell#1731 T3: parallel review protocol; lazy (delegation or high risk only), core and normative rule untouched.
 	// gentle-shell#1731 T11/T12: verify-per-unit timing and the every-S# verify handoff (6,000 -> 6,400 B).
 	// gentle-shell#1731 T15: one end-of-feature verify for same-model inline deliveries (6,400 -> 6,500 B).
 	// gentle-shell#1731 T23: bounded self-review and partial/blocked writer -> Needs your decision (7,000 -> 7,300 B).
-	"orchestrator-verification.md": 7_300,
-	"orchestrator-writer.md": 4_500,
+	// Verification by named risk: escalate-only tier table and the concrete-occasions rule (7,300 -> 7,500 B).
+	"orchestrator-verification.md": 7_500,
+	// Writer-rule fix (size threshold, one behavior per unit) and C3 (writer prompts name the helpers and
+	// invariants to reuse): 4,500 -> 5,300 B.
+	// Pain-point iteration S10 (C7): writer handoffs keep test scratch outside the worktree (5,300 -> 5,500 B).
+	"orchestrator-writer.md": 5_500,
 	"orchestrator-prompts.md": 13_000,
 };
 
@@ -167,6 +183,46 @@ test("AC7: each delegation module stays under its byte budget and is loaded by i
 	}
 });
 
+// Pain-point iteration S11 T2: once read, a lazy module rides along on every later model call, so the
+// default delegation read must be the lean card; reference material loads only when a pointer names it.
+test("S11: the default delegation pointer resolves to the lean card and the reference loads only by name", () => {
+	const card = read("assets/orchestrator-delegation.md");
+	const reference = read("assets/orchestrator-delegation-reference.md");
+	assert.ok(Buffer.byteLength(card, "utf8") <= MODULE_BUDGETS["orchestrator-delegation.md"], "the delegation card is over its budget");
+	// Every core line that names a delegation module names the card, except the one reference pointer.
+	const pointerLines = core.split("\n").filter((line) => line.includes("`orchestrator-delegation"));
+	const referenceLines = pointerLines.filter((line) => line.includes("`orchestrator-delegation-reference.md`"));
+	assert.equal(referenceLines.length, 1, "the core names the reference exactly once");
+	for (const name of ["Per-action table", "Work Routing Ladder", "Canonical Workflows"]) {
+		assert.ok(referenceLines[0].includes(name), `the reference pointer must name ${name}`);
+	}
+	assert.ok(pointerLines.some((line) => line.includes("`orchestrator-delegation.md`")), "the core must point at the card");
+	// The card carries what the parent needs at the moment it delegates.
+	for (const clause of [
+		"#### Delegation Triggers",
+		"Each trigger holds only when its condition truly holds",
+		"A unit is one independent piece of behavior with its code, tests, and docs together",
+		"`## Allowed edit surfaces`",
+		"Spec: odd/tasks/<feature>.md (read until \"## Log\"). Do T#; S#.",
+		"`## Skills to load before work`",
+		"`orchestrator-verification.md`",
+		"#### Key Learnings closing block",
+		"disjoint Allowed edit surfaces",
+		"Subagent-facing prompts should be written in English by default",
+		"technical artifacts default to English",
+		"returns a task id",
+		"`orchestrator-delegation-reference.md`",
+	]) {
+		assert.ok(card.includes(clause), `the delegation card is missing: ${clause}`);
+	}
+	// Reference material lives once, in the reference.
+	for (const heading of ["### Work Routing Ladder", "#### Background Subagent Policy", "### Canonical Lightweight Workflows", "#### Pi Subagent Model Routing"]) {
+		assert.ok(reference.includes(heading), `the reference is missing: ${heading}`);
+		assert.ok(!card.includes(heading), `the card still carries reference material: ${heading}`);
+	}
+	assert.ok(!reference.includes("#### Delegation Triggers"), "the triggers live once, in the card");
+});
+
 // gentle-shell#1269/#1598: the capability rule is the substantive part of the fix,
 // so losing it must fail a test instead of quietly passing the AC7 budget gate.
 // Focused on the two claims that carry the fix, not on the exact wording around them.
@@ -178,9 +234,11 @@ test("delegation reports a capability gap instead of substituting inline work fo
 });
 
 test("work usage stays complete in the human guide while routing precedence stays canonical", () => {
-	const asset = read("assets/orchestrator-delegation.md");
+	// S11 T2: the work-publication pointer and the runtime bindings moved to the reference; the writer
+	// fallback stays in the card, so the counts read the card plus the reference.
+	const asset = `${read("assets/orchestrator-delegation.md")}\n${read("assets/orchestrator-delegation-reference.md")}`;
 	const guide = read("docs/gentle-agents-activity.md");
-	assert.ok(asset.includes("tool schemas and `docs/gentle-agents-activity.md`"));
+	assert.ok(read("assets/orchestrator-delegation-reference.md").includes("tool schemas and `docs/gentle-agents-activity.md`"));
 	for (const clause of [
 		'`{"area":"Auth","topic":"Login","tags":["Review"],"refs":[{"kind":"issue","repository":"github.com/Owner/Repo","id":"12"}]}`',
 		'`filter: {"related_to":{"session_id":"<stable owner ID>"}}`',
@@ -216,8 +274,10 @@ test("T4: tracking updates edit in place and mirror without re-emitting the docu
 test("T6: each delegation module carries its own clauses and names the modules it depends on", () => {
 	const placement: Record<string, readonly string[]> = {
 		"orchestrator-tracking.md": ["#### Authorization and progress", "Delivery follows work units", "Raise a candidate you know is high risk"],
+		// The tier table header lost "Native risk" with verification by named
+		// risk: the high row is reached only through escalate, not a native tier.
 		"orchestrator-verification.md": [
-			"| Native risk tier | Verification (any RDD state) |",
+			"| Tier | Verification (any RDD state) |",
 			"## Agent escalation (gentle-shell#1494)",
 			"## Parallel review protocol (gentle-shell#1731)",
 		],

package/tests/test-scratch-contract.test.ts

@@ -0,0 +1,102 @@
+import assert from "node:assert/strict";
+import { readFileSync, readdirSync } from "node:fs";
+import { join, relative } from "node:path";
+import test from "node:test";
+
+// Pain-point iteration S10 (C7): blind reviewers flagged tool artifacts in every
+// Gentle Shell delivery. Orchestrators told writers to create a scratch
+// directory in the repository root and point TMPDIR at it, so test state and
+// tool caches entered the diff. Test scratch now lives outside the worktree by
+// default. These are instruction-delivery contracts, not proof of model adherence.
+
+const ROOT = join(import.meta.dirname, "..");
+const read = (path: string): string => readFileSync(join(ROOT, path), "utf8");
+const worker = read("assets/agents/gentle-ai-worker.md");
+const writer = read("assets/orchestrator-writer.md");
+const verifier = read("assets/agents/gentle-ai-verify.md");
+
+function section(text: string, heading: string): string {
+	const start = text.indexOf(`\n## ${heading}\n`);
+	assert.ok(start >= 0, `missing section: ${heading}`);
+	const end = text.indexOf("\n## ", start + heading.length + 4);
+	return text.slice(start, end < 0 ? undefined : end);
+}
+
+function containsAll(text: string, clauses: readonly string[], label: string): void {
+	for (const clause of clauses) assert.ok(text.includes(clause), `${label} is missing: ${clause}`);
+}
+
+test("S10: the worker keeps test scratch outside the worktree and checks git status before returning", () => {
+	const discipline = section(worker, "Test discipline");
+	containsAll(discipline, [
+		"Test scratch lives outside the worktree",
+		"`mktemp -d`",
+		"never point `TMPDIR` or a cache directory into the repository",
+		"use an excluded path that the test removes before it ends",
+		"Never leave tool caches or scratch paths in the change",
+	], "worker test discipline");
+	const finish = discipline.split("\n").find((line) => line.includes("`git status --short`"));
+	assert.ok(finish, "worker finish checks must run `git status --short`");
+	containsAll(finish, ["Before returning", "no tool cache or scratch path", "`risks`"], "worker finish check");
+});
+
+test("S10: writer handoffs never place test scratch inside the repository", () => {
+	const line = writer.split("\n").find((entry) => entry.includes("Test scratch"));
+	assert.ok(line, "orchestrator-writer.md must state where writers put test scratch");
+	containsAll(line, [
+		"outside the worktree",
+		"`mktemp -d`",
+		"never in the repository",
+		"`TMPDIR`",
+		"excluded path",
+	], "writer handoff scratch rule");
+});
+
+test("S10: no shipped guidance points test temp state into the repository", () => {
+	const offenders: string[] = [];
+	const walk = (dir: string): void => {
+		for (const entry of readdirSync(dir, { withFileTypes: true })) {
+			const path = join(dir, entry.name);
+			if (entry.isDirectory()) walk(path);
+			else if (/\.(md|ts)$/.test(entry.name) && /TMPDIR=\$(PWD|\(pwd\))|\.test-tmp|\.atl\/test-tmp/.test(readFileSync(path, "utf8"))) {
+				offenders.push(relative(ROOT, path));
+			}
+		}
+	};
+	for (const dir of ["assets", "extensions", "docs"]) walk(join(ROOT, dir));
+	assert.deepEqual(offenders, []);
+});
+
+// S10 follow-up (user, 2026-10-14: "lo de los temporales tambien hacemos limpieza luego?"):
+// scratch outside the worktree was never removed; verifier scratch copies piled up
+// in the system temp directory. The verifier removes only the exact directory its
+// own `mktemp -d` printed; the worker, which may not delete, has tests clean up in
+// teardown and names any leftover outside directory so the parent removes it.
+test("S10: scratch outside the worktree is removed after use", () => {
+	// Independent verification of C7 found child safety blocks `rm -rf` in every
+	// subagent (lib/destructive-command-guard.ts), so a verifier told to delete its
+	// own scratch always failed and nobody removed it. Subagents now report exact
+	// scratch paths and the parent, where deletion is only confirmed, removes them.
+	containsAll(
+		verifier,
+		["list every scratch directory you created by exact path in your result so the parent removes it", "never delete it yourself"],
+		"gentle-ai-verify scratch report",
+	);
+	assert.ok(!/\brm\s+-r/.test(verifier), "gentle-ai-verify must not instruct a deletion child safety blocks");
+	containsAll(
+		section(worker, "Test discipline"),
+		[
+			"Tests delete the temp directories they create in teardown",
+			"name any scratch directory you created outside the worktree in `risks` so the parent removes it",
+		],
+		"worker scratch cleanup",
+	);
+	// Session scratch and artifact ledger: the runtime owns the parent session's
+	// TMPDIR (subagent TMPDIRs nest under it) and records clones and worktrees,
+	// so the writer rule points at the command instead of a model cleanup step.
+	containsAll(writer, ["The runtime owns session scratch", "`/gentle:scratch` lists or cleans recorded clones and worktrees"], "writer runtime-owned cleanup");
+	// The verifier's mktemp copy lives in its own TMPDIR, which the runner removes.
+	const verification = read("assets/orchestrator-verification.md");
+	containsAll(verification, ["the runtime removes each subagent's own TMPDIR, which holds that copy"], "verification runtime cleanup");
+	assert.ok(!verification.includes("the parent removes the scratch paths the verifier reports"), "the parent no longer removes verifier scratch");
+});

package/tests/test-strength-contract.test.ts

@@ -111,7 +111,7 @@ test("T31: high-risk item 3 is about unrequested breaks, not the requested chang
 	);
 });
 
-// T33 (L74): in p31 x5 both runs declared `Risk: none` after adding --year to
+// T33 (L74): in a benchmark run both cells declared `Risk: none` after adding --year to
 // the shared budget options; one shipped `budget set --year` silently saving a
 // wrong budget, the regression verify used to catch. The Risk line must check
 // shared code before claiming none.
@@ -122,3 +122,38 @@ test("T33: the Close step checks shared code before Risk: none", () => {
 		assert.ok(step?.includes(SHARED_CHECK), `${persona} Close step must check shared code before Risk: none`);
 	}
 });
+
+// C8 (benchmark finding): the PRESERVE test alone missed the `budget set
+// --year` regression in 1 of 2 runs. A differential run of every existing
+// command that shares the changed code, old code against new, caught it in
+// 2 of 2. Inline work and the worker carry the same check.
+// S15: the differential check runs in scratch and is never committed as a test (blind round 4 found tests pinning a git commit).
+const DIFFERENTIAL = "Only when your diff changes shared code (options, parsers, helpers) that an existing command the request did not name also uses, run one differential check before finishing, as a single script: for each such command, run it with the new or changed input (for example a new option passed to a sibling subcommand) against the previous code (a copy of the base commit in a `mktemp -d` scratch directory, never committed as a test; committed tests never read git history or a fixed commit) and against your change, and compare stdout, stderr, and exit code; any difference nobody asked for is a regression to fix and pin with a test.";
+test("C8: inline test-first and the worker PRESERVE step run the differential check", () => {
+	for (const persona of ["gentleman", "neutral"] as const) {
+		const principle = __testing.buildGentlePrompt(persona).split("\n").find((line) => line.includes("use test-first by default"));
+		assert.ok(principle?.includes(`${TOUCHED}. ${DIFFERENTIAL}`), `${persona} principle must run the differential check after PRESERVE`);
+	}
+	const step = read("assets/agents/gentle-ai-worker.md").split("\n").find((line) => line.startsWith("3. PRESERVE — "));
+	assert.ok(step?.includes(DIFFERENTIAL), "worker step 3 must run the differential check");
+});
+
+// C3 (benchmark finding): parallel workers appended a shared `Fees` entry
+// inline, unsorted, instead of reusing the helper that keeps the order. The
+// worker reuses the existing function for shared state, and each writer prompt
+// names the helpers to reuse, because parallel units cannot see each other.
+test("C3: the worker reuses the existing function for shared state and keeps its invariants", () => {
+	const worker = read("assets/agents/gentle-ai-worker.md");
+	assert.ok(
+		worker.includes("- Before you create or change shared state (a record, list entry, file, or setting that other commands also create or read), find the existing function that already does it and reuse it, keeping every invariant it enforces (ordering, uniqueness, validation, normalization). Never re-implement that step inline with a different shape."),
+		"worker must reuse the existing shared-state function",
+	);
+	const invariants = read("assets/orchestrator-writer.md").split("\n").find((line) => line.startsWith("- **Invariants**"));
+	for (const clause of [
+		"each writer prompt names the existing helpers its unit must reuse for shared state",
+		"and the invariants they keep",
+		"units built in parallel cannot see each other",
+	]) {
+		assert.ok(invariants?.includes(clause), `writer module invariants reason is missing: ${clause}`);
+	}
+});

package/tests/tool-batching-contract.test.ts

@@ -0,0 +1,64 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import test from "node:test";
+
+// Pain-point iteration S13 (C9/C10, from the S12 session analysis): subagents
+// spent 78% of their turns on a single tool call, and 31% of their turns were
+// consecutive read-only calls one turn could batch; the parent read repo files
+// and then delegated, and 69% of the files it read were read again by the
+// worker. Codex reads 8 files with one command. These are instruction-delivery
+// contracts, not proof of model adherence.
+
+const ROOT = join(import.meta.dirname, "..");
+const read = (path: string): string => readFileSync(join(ROOT, path), "utf8");
+
+function containsAll(text: string, clauses: readonly string[], label: string): void {
+	for (const clause of clauses) assert.ok(text.includes(clause), `${label} is missing: ${clause}`);
+}
+
+function declaredTools(prompt: string): string[] {
+	const frontmatter = prompt.split("\n---\n")[0];
+	return [...frontmatter.matchAll(/^\s+- (\S+)$/gm)].map((match) => match[1]);
+}
+
+test("S13 C9: every generic subagent prompt batches independent tool calls in one turn", () => {
+	for (const agent of ["gentle-ai-worker", "gentle-ai-verify", "gentle-ai-explore"]) {
+		const prompt = read(`assets/agents/${agent}.md`);
+		const rule = prompt.split("\n").find((line) => line.includes("**Batch tool calls:**"));
+		assert.ok(rule, `${agent} must carry the batch tool calls rule`);
+		containsAll(rule, [
+			"issue independent calls together in the same turn (parallel tool calls)",
+			"read each relevant file whole once instead of many small ranges",
+		], agent);
+		const tools = declaredTools(prompt);
+		// A shell-less agent must not be told to read files or run tests with a command it cannot run.
+		if (tools.includes("bash")) {
+			containsAll(rule, ["read several files with one command", "the focused test and the suite without status-only turns"], agent);
+		} else {
+			assert.doesNotMatch(rule, /one command|the suite/, `${agent} has no shell, so its rule must not name a command`);
+		}
+		if (tools.includes("edit")) containsAll(rule, ["all edits to one file in one `edit` call"], agent);
+	}
+});
+
+test("S13 C10: the delegation card keeps the parent from reading what the worker will read", () => {
+	const card = read("assets/orchestrator-delegation.md");
+	const rule = card.split("\n").find((line) => line.startsWith("**Preparation trigger:**"));
+	assert.ok(rule, "the delegation card must carry the Preparation trigger");
+	containsAll(rule, [
+		"When delegating, read only what decides the route",
+		"never the files the worker will read",
+		"pass paths, the spec reference, and what to change, not file contents",
+	], "delegation card preparation trigger");
+});
+
+// S13 C9 parent: 95 of 389 parent turns did only coordination (todo 55, orchestrator_session_id 17,
+// gentle_review assess 14, subagent_list_agents 8) and parent multi-tool turns were ~0.
+test("S13 C9: the always-on orchestrator batches independent calls and never spends a turn only on coordination", () => {
+	const core = read("assets/orchestrator.md");
+	containsAll(core, [
+		"Batch independent tool calls in one turn (parallel calls or one multi-file command).",
+		"Never spend a turn only on a `todo` or status update.",
+	], "orchestrator core");
+});

package/tests/verification-proportionality.test.ts

@@ -0,0 +1,46 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import test from "node:test";
+
+const read = (path: string) => readFileSync(new URL(`../${path}`, import.meta.url), "utf8");
+const verify = read("assets/agents/gentle-ai-verify.md");
+const policy = read("assets/orchestrator-verification.md");
+const parent = read("assets/orchestrator.md");
+
+// Instruction-delivery checks, not evidence of model adherence or delivery time.
+test("unit verification keeps whole-feature context without blocking on future work", () => {
+  for (const text of [verify, policy]) {
+    assert.ok(text.includes("out of scope, not unmet"));
+    assert.ok(text.includes("affected interactions"));
+  }
+  assert.ok(!verify.includes("no partial-scope carve-out"));
+  assert.ok(verify.includes("At final feature verification, cover every requirement"));
+  assert.ok(policy.includes("final feature verification covers every `S#`"));
+  assert.ok(verify.includes("met, unmet, not implemented, or out of scope"));
+  assert.ok(verify.includes("unrelated future work must not block that unit"));
+});
+
+test("observed writer evidence is reusable but does not replace independent probes", () => {
+  assert.ok(verify.includes("Reuse observed writer checks when their candidate and scope remain valid"));
+  assert.ok(verify.includes("independent probes"));
+  assert.ok(!verify.includes("never evidence of correctness"));
+});
+
+test("auxiliary gates must protect a concrete requirement or threat", () => {
+  assert.ok(parent.includes("gates/overengineering: `orchestrator-verification.md`"));
+  assert.ok(policy.includes("acceptance criterion, concrete threat, or authoritative contract"));
+  assert.ok(policy.includes("must not become a delivery blocker"));
+  assert.ok(policy.includes("Do not build a framework for a bounded capability probe"));
+});
+
+test("overengineering warnings visibly simplify the plan without weakening safeguards", () => {
+  assert.ok(policy.includes("remove or collapse optional artifacts and checks"));
+  assert.ok(policy.includes("State what was removed, what remains indispensable, and the next application outcome"));
+  assert.ok(policy.includes("Keep required functional checks, security controls, and native review authority intact"));
+});
+
+test("existing verification isolation and bounded correction remain required", () => {
+  assert.ok(verify.includes("run it only against isolated state"));
+  assert.ok(verify.includes("one correction batch and one recheck limited to the reported blockers"));
+  assert.ok(policy.includes("Advisories never start a correction"));
+});

package/tests/verifier-admission.test.ts

@@ -0,0 +1,154 @@
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { createGentleAiExtension } from "../extensions/gentle-ai.ts";
+import { rejectUnriskedVerifierLaunch } from "../lib/verifier-admission.ts";
+
+// odd/tasks/verifier-admission.md S2: a bench gate run launched `gentle-ai-verify` on a small, not high-risk task
+// although the prompt's Verification rule reserves the independent verifier for a named high-risk item. The runtime
+// now admits a primary-session verifier launch only with a `Risk: item N` line, a feature-document task, or a
+// measured context at the backstop.
+
+const quiet = { tokens: 20_000, contextWindow: 400_000 };
+
+function workspace(withDocument: boolean): string {
+	const root = mkdtempSync(join(tmpdir(), "verifier-admission-"));
+	if (withDocument) {
+		mkdirSync(join(root, "odd", "tasks"), { recursive: true });
+		writeFileSync(join(root, "odd", "tasks", "ledger.md"), "# Ledger\n");
+	}
+	return root;
+}
+
+test("S3/S4: a verifier launch without a high-risk line is rejected with an inline instruction", (t) => {
+	const root = workspace(false);
+	t.after(() => rmSync(root, { recursive: true, force: true }));
+	for (const task of ["Verify the annual budget change.", "Verify it.\nRisk: none", "Verify it.\nRisk: none (local rename)"]) {
+		const denied = rejectUnriskedVerifierLaunch({ agent: "gentle-ai-verify", task }, { root, contextUsage: quiet });
+		assert.ok(denied?.block, `${JSON.stringify(task)} must be blocked`);
+		assert.match(denied.reason, /independent verifier runs only for a change that declares a named high-risk item/);
+		assert.match(denied.reason, /focused test and suite inline/);
+		assert.match(denied.reason, /do not retry the launch/);
+		assert.match(denied.reason, /never add a Risk line or create a feature document only to get a verifier admitted/);
+		assert.doesNotMatch(denied.reason, /claude|gpt|openai|anthropic|gemini|sonnet|opus/i, "the message stays generic");
+	}
+});
+
+test("S3: a Risk line naming a Task Size high-risk item admits the verifier", (t) => {
+	const root = workspace(false);
+	t.after(() => rmSync(root, { recursive: true, force: true }));
+	for (const line of ["Risk: item 3 (shared parser)", "- Risk: item 2, item 3 (auth and parser)", "Risk: item 6", "  Risk:item 1"]) {
+		assert.equal(rejectUnriskedVerifierLaunch({ agent: "gentle-ai-verify", task: `Verify the change.\n${line}\n` }, { root, contextUsage: quiet }), undefined, line);
+	}
+	const viaContext = { agent: "gentle-ai-verify", task: "Verify the change.", context: "Risk: item 4 (migration)" };
+	assert.equal(rejectUnriskedVerifierLaunch(viaContext, { root, contextUsage: quiet }), undefined, "the context carries the line");
+});
+
+// gentle-shell-bench model-economy L9: a DeepSeek verifier launch was refused twice because its valid declaration
+// opened a sentence mid-paragraph ("... on top of commit ebf3f35). Risk: item 1 (...)"), not a line.
+test("S3: a Risk declaration that opens a sentence admits the verifier", (t) => {
+	const root = workspace(false);
+	t.after(() => rmSync(root, { recursive: true, force: true }));
+	for (const task of [
+		"Independently verify an ODD change on top of commit ebf3f35. Risk: item 1 (schema migration of stored data).",
+		"Verify the parser change! Risk: item 3 (shared parser)",
+		"Is the guard still sound? Risk: item 2",
+	]) {
+		assert.equal(rejectUnriskedVerifierLaunch({ agent: "gentle-ai-verify", task }, { root, contextUsage: quiet }), undefined, task);
+	}
+	for (const task of ["Verify it. Risk: none (local rename)", "Verify it. Do not write Risk: item 3 here.", "Verify it.Risk: item 3"]) {
+		assert.ok(rejectUnriskedVerifierLaunch({ agent: "gentle-ai-verify", task }, { root, contextUsage: quiet })?.block, task);
+	}
+});
+
+test("S3: an item outside 1-6, a Risk mention inside prose, or none first is rejected", (t) => {
+	const root = workspace(false);
+	t.after(() => rmSync(root, { recursive: true, force: true }));
+	for (const line of ["Risk: item 7", "Risk: item 0", "Risk: item 12", "Do not write Risk: item 3 here.", "Risk: none; item 3 does not apply", "Risk: items"]) {
+		assert.ok(rejectUnriskedVerifierLaunch({ agent: "gentle-ai-verify", task: `Verify it.\n${line}` }, { root, contextUsage: quiet })?.block, line);
+	}
+});
+
+test("S3: a task of an existing feature document admits the verifier; a missing document does not", (t) => {
+	const documented = workspace(true);
+	const bare = workspace(false);
+	t.after(() => { rmSync(documented, { recursive: true, force: true }); rmSync(bare, { recursive: true, force: true }); });
+	const input = { agent: "gentle-ai-verify", task: 'Spec: odd/tasks/ledger.md (read until "## Log"). Verify T2; S3.' };
+	assert.equal(rejectUnriskedVerifierLaunch(input, { root: documented, contextUsage: quiet }), undefined);
+	assert.ok(rejectUnriskedVerifierLaunch(input, { root: bare, contextUsage: quiet })?.block, "a missing document does not admit");
+});
+
+test("S3: the measured context backstop admits the verifier", (t) => {
+	const root = workspace(false);
+	t.after(() => rmSync(root, { recursive: true, force: true }));
+	const input = { agent: "gentle-ai-verify", task: "Verify the change." };
+	assert.equal(rejectUnriskedVerifierLaunch(input, { root, contextUsage: { tokens: 150_000, contextWindow: 1_000_000 } }), undefined);
+	assert.equal(rejectUnriskedVerifierLaunch(input, { root, contextUsage: { tokens: 19_200, contextWindow: 128_000 } }), undefined, "15% of a small window admits");
+	assert.ok(rejectUnriskedVerifierLaunch(input, { root, contextUsage: { tokens: 149_999, contextWindow: 1_000_000 } })?.block);
+	assert.ok(rejectUnriskedVerifierLaunch(input, { root, contextUsage: undefined })?.block, "missing context usage does not admit");
+});
+
+test("S5: other agents are not gated by the verifier admission", (t) => {
+	const root = workspace(false);
+	t.after(() => rmSync(root, { recursive: true, force: true }));
+	for (const agent of ["gentle-ai-worker", "worker", "gentle-ai-explore", "jd-fix-agent", "jd-judge-a", "jd-judge-b", "review-risk", "verify"]) {
+		assert.equal(rejectUnriskedVerifierLaunch({ agent, task: "Check src/budget.ts" }, { root, contextUsage: quiet }), undefined, agent);
+	}
+	for (const input of [undefined, null, "gentle-ai-verify", ["gentle-ai-verify"], { task: "Verify it." }]) {
+		assert.equal(rejectUnriskedVerifierLaunch(input, { root, contextUsage: quiet }), undefined, JSON.stringify(input));
+	}
+});
+
+type ToolCallHandler = (event: { toolName: string; input: unknown }, ctx: ExtensionContext) => Promise<{ block?: boolean; reason?: string } | undefined>;
+
+function toolCallThroughHook(toolName: string, input: Record<string, unknown>, cwd: string, tokens: number, processEnv: NodeJS.ProcessEnv = {}) {
+	const handlers = new Map<string, ToolCallHandler>();
+	const pi = { on(name: string, handler: ToolCallHandler) { handlers.set(name, handler); }, events: { emit() {} }, registerCommand() {}, registerTool() {} } as unknown as ExtensionAPI;
+	createGentleAiExtension({ nativeReviewCli: null, processEnv })(pi);
+	return handlers.get("tool_call")!({ toolName, input }, {
+		cwd, hasUI: false, ui: { confirm: async () => true },
+		getContextUsage: () => ({ tokens, contextWindow: 272_000, percent: Math.round((tokens / 272_000) * 100) }),
+	} as unknown as ExtensionContext);
+}
+
+test("S3/S5: the orchestrator tool_call hook gates only primary verifier launches", async (t) => {
+	const bare = workspace(false);
+	const documented = workspace(true);
+	t.after(() => { rmSync(bare, { recursive: true, force: true }); rmSync(documented, { recursive: true, force: true }); });
+	const blocked = await toolCallThroughHook("subagent_run", { agent: "gentle-ai-verify", mode: "task", task: "Verify the budget change." }, bare, 20_000);
+	assert.equal(blocked?.block, true);
+	assert.match(blocked?.reason ?? "", /focused test and suite inline/);
+	const risked = await toolCallThroughHook("subagent_run", { agent: "gentle-ai-verify", mode: "task", task: "Verify the budget change.\nRisk: item 3 (shared parser)" }, bare, 20_000);
+	assert.equal(risked?.block, undefined, "a named high-risk item admits");
+	const documentedLaunch = await toolCallThroughHook("subagent_run", { agent: "gentle-ai-verify", mode: "task", workspace_root: documented, task: "Spec: odd/tasks/ledger.md, T1. Verify it." }, bare, 20_000);
+	assert.equal(documentedLaunch?.block, undefined, "the feature document resolves under the selected workspace root");
+	const backstop = await toolCallThroughHook("subagent_run", { agent: "gentle-ai-verify", mode: "task", task: "Verify the budget change." }, bare, 136_000);
+	assert.equal(backstop?.block, undefined, "half of the measured window admits");
+	const child = await toolCallThroughHook("subagent_run", { agent: "gentle-ai-verify", mode: "task", task: "Verify it." }, bare, 0, { GENTLE_PI_AGENTS_CHILD: "1" });
+	assert.equal(child?.block, undefined, "a child session is not gated");
+	const continuation = await toolCallThroughHook("subagent_continue", { agent: "gentle-ai-verify", task_id: "t-1", task: "Recheck it." }, bare, 0);
+	assert.notEqual(continuation?.reason, blocked?.reason, "a continuation is not gated by the verifier admission");
+	for (const agent of ["gentle-ai-explore", "jd-judge-a", "jd-judge-b"]) {
+		const other = await toolCallThroughHook("subagent_run", { agent, mode: "task", task: "Map src/budget.ts" }, bare, 0);
+		assert.equal(other?.block, undefined, `${agent} is unaffected`);
+	}
+	// A native review relay keeps its own candidate-view gate, which already rejects a dispatch without a frozen view.
+	const relay = await toolCallThroughHook("subagent_run", { agent: "review-risk", mode: "task", task: "Review the candidate." }, bare, 0);
+	assert.match(relay?.reason ?? "", /^review subagent dispatch /, "review relays keep their previous gate");
+	const writer = await toolCallThroughHook("subagent_run", { agent: "gentle-ai-worker", mode: "background", task: "Implement it.\nRisk: item 3\n\n## Allowed edit surfaces\nsrc/budget.ts\n" }, bare, 0);
+	assert.match(writer?.reason ?? "", /write this unit inline yourself/, "writer admission is unchanged and ignores Risk lines");
+});
+
+test("S6: the Verification rule and the reference docs point at the runtime admission", () => {
+	const read = (path: string) => readFileSync(join(import.meta.dirname, "..", path), "utf8");
+	assert.ok(read("assets/orchestrator.md").includes("independent `gentle-ai-verify`; else inline; runtime admission, gates/overengineering"), "the core rule names the runtime check");
+	assert.ok(read("assets/orchestrator-verification.md").includes("(runtime admits its launch on a `Risk: item N` line or sentence, a feature-document task line, or past the context backstop)"), "the normative rule names the admitted line");
+	const docs = read("docs/readme-reference.md");
+	const writer = docs.indexOf("A second admission check stops small-task delegation");
+	const verifier = docs.indexOf("A third admission check keeps the independent verifier for high-risk changes");
+	assert.ok(writer >= 0 && verifier > writer, "the verifier admission is documented right after the writer admission");
+	assert.match(docs.slice(verifier, docs.indexOf("\n\n", verifier)), /`gentle-ai-verify` launch is admitted only when[^]*`Risk: item N`[^]*context backstop/);
+});