gentle-pi 4.2.0 → 4.4.0

package/tests/context-backstop.test.ts

@@ -0,0 +1,225 @@
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test, { type TestContext } from "node:test";
+import type { ContextUsage, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { createGentleAiExtension } from "../extensions/gentle-ai.ts";
+import {
+	CONTEXT_BACKSTOP_FRACTION_ENV,
+	CONTEXT_BACKSTOP_TOKENS_ENV,
+	contextBackstopReached,
+	contextBackstopThreshold,
+	createThrottledContextMeasure,
+	type MeasuredContext,
+} from "../lib/context-backstop.ts";
+
+// Harness roadmap R1: the parent-context backstop was a fixed "~150k tokens" in prompt text, so the model had to
+// estimate its own context. The runtime now measures it against min(absolute cap, fraction x context window) and
+// tells the primary session once per crossing.
+
+test("the threshold is the smaller of the absolute cap and 15% of the context window", () => {
+	assert.equal(contextBackstopThreshold(1_000_000, {}), 150_000, "a large window keeps the absolute cap");
+	assert.equal(contextBackstopThreshold(400_000, {}), 60_000);
+	// Bench gate (T12): a 272k window reaches it near 41k, where delegating the wide task paid off.
+	assert.equal(contextBackstopThreshold(272_000, {}), 40_800);
+	assert.equal(contextBackstopThreshold(200_000, {}), 30_000, "a small window reaches it at 15% of its size");
+	assert.equal(contextBackstopThreshold(128_000, {}), 19_200);
+	for (const unknown of [undefined, null, 0, -1, Number.NaN, Number.POSITIVE_INFINITY]) {
+		assert.equal(contextBackstopThreshold(unknown, {}), 150_000, `window ${unknown} falls back to the cap`);
+	}
+});
+
+test("the cap and the fraction are overridable by environment; invalid values keep the defaults", () => {
+	assert.equal(contextBackstopThreshold(1_000_000, { [CONTEXT_BACKSTOP_TOKENS_ENV]: "100000" }), 100_000);
+	assert.equal(contextBackstopThreshold(4_000_000, { [CONTEXT_BACKSTOP_TOKENS_ENV]: "300000" }), 300_000, "a raised cap applies where the fraction allows it");
+	assert.equal(contextBackstopThreshold(1_000_000, { [CONTEXT_BACKSTOP_FRACTION_ENV]: "0.1" }), 100_000);
+	assert.equal(contextBackstopThreshold(200_000, { [CONTEXT_BACKSTOP_TOKENS_ENV]: "80000", [CONTEXT_BACKSTOP_FRACTION_ENV]: "1" }), 80_000);
+	for (const value of ["", "abc", "0", "-5", "1.5e999"]) {
+		assert.equal(contextBackstopThreshold(1_000_000, { [CONTEXT_BACKSTOP_TOKENS_ENV]: value }), 150_000, `tokens ${JSON.stringify(value)}`);
+	}
+	for (const value of ["", "abc", "0", "-0.5", "1.5"]) {
+		assert.equal(contextBackstopThreshold(200_000, { [CONTEXT_BACKSTOP_FRACTION_ENV]: value }), 30_000, `fraction ${JSON.stringify(value)}`);
+	}
+});
+
+// R1 review advisory: a tiny window or fraction floored the threshold to 0, so an
+// empty context counted as reaching the backstop (and admitted every writer).
+test("the threshold is never below one token, so an empty context never reaches it", () => {
+	assert.equal(contextBackstopThreshold(200_000, { [CONTEXT_BACKSTOP_FRACTION_ENV]: "0.000001" }), 1);
+	assert.equal(contextBackstopThreshold(1, {}), 1);
+	assert.equal(contextBackstopReached({ tokens: 0, contextWindow: 1 }, {}), false);
+	assert.equal(contextBackstopReached({ tokens: 1, contextWindow: 1 }, {}), true);
+});
+
+test("unknown tokens never count as reaching the backstop", () => {
+	assert.equal(contextBackstopReached({ tokens: 150_000, contextWindow: 1_000_000 }, {}), true);
+	assert.equal(contextBackstopReached({ tokens: 149_999, contextWindow: 1_000_000 }, {}), false);
+	assert.equal(contextBackstopReached({ tokens: 19_200, contextWindow: 128_000 }, {}), true);
+	assert.equal(contextBackstopReached({ tokens: 19_199, contextWindow: 128_000 }, {}), false);
+	assert.equal(contextBackstopReached({ tokens: null, contextWindow: 128_000 }, {}), false, "null right after compaction");
+	assert.equal(contextBackstopReached(undefined, {}), false);
+});
+
+type Handler = (event: unknown, ctx: ExtensionContext) => unknown;
+type Patch = { content?: Array<{ type: string; text?: string }>; structuredContent?: unknown; isError?: boolean } | undefined;
+
+function session(t: TestContext, child: boolean, options: { now?: () => number; minIntervalMs?: number } = {}) {
+	const cwd = realpathSync(mkdtempSync(join(tmpdir(), "context-backstop-")));
+	const configHome = mkdtempSync(join(tmpdir(), "context-backstop-config-"));
+	const previous = process.env.GENTLE_PI_CONFIG_HOME;
+	process.env.GENTLE_PI_CONFIG_HOME = configHome;
+	t.after(() => {
+		if (previous === undefined) delete process.env.GENTLE_PI_CONFIG_HOME;
+		else process.env.GENTLE_PI_CONFIG_HOME = previous;
+		rmSync(cwd, { recursive: true, force: true });
+		rmSync(configHome, { recursive: true, force: true });
+	});
+	const handlers = new Map<string, Handler>();
+	const pi = { on: (name: string, handler: Handler) => { handlers.set(name, handler); }, events: { on() {}, emit() {} }, registerCommand() {}, registerTool() {} } as unknown as ExtensionAPI;
+	// Semantic tests without options keep per-call measuring (minIntervalMs 0); callers that pass
+	// options (a fake clock) keep the production window resolution.
+	const measureOptions = Object.keys(options).length === 0 ? { minIntervalMs: 0 } : options;
+	createGentleAiExtension({
+		nativeReviewCli: null,
+		processEnv: { GENTLE_PI_AGENTS_CHILD: child ? "1" : "0", GENTLE_AI_TELEMETRY: "0" },
+		contextBackstopMeasure: measureOptions,
+	})(pi);
+	let usage: ContextUsage | undefined = { tokens: 10_000, contextWindow: 1_000_000, percent: 1 };
+	let measures = 0;
+	const sessionManager = { getSessionId: () => "session-backstop", getCwd: () => cwd, getEntries: () => [], getBranch: () => [] };
+	const ctx = { cwd, hasUI: false, ui: { notify() {} }, sessionManager, getContextUsage: () => { measures++; return usage; } } as unknown as ExtensionContext;
+	const measureCount = () => measures;
+	const setTokens = (tokens: number | null, contextWindow = 1_000_000) => {
+		usage = { tokens, contextWindow, percent: tokens === null ? null : (tokens / contextWindow) * 100 };
+	};
+	const read = (overrides: Record<string, unknown> = {}) => handlers.get("tool_result")!({
+		toolName: "read", toolCallId: "call-read", isError: false, input: { path: "a.ts" },
+		content: [{ type: "text", text: "file body" }], structuredContent: { lines: 1 }, ...overrides,
+	}, ctx) as Promise<Patch>;
+	return { cwd, ctx, handlers, setTokens, read, measureCount, options };
+}
+
+test("the primary session gets one notice when its measured context first reaches the backstop", async (t) => {
+	const s = session(t, false);
+	assert.equal(await s.read(), undefined, "below the backstop nothing is appended");
+	s.setTokens(160_000);
+	const crossed = await s.read();
+	assert.equal(crossed?.content?.[0]?.text, "file body", "the tool output is kept first");
+	const notice = crossed?.content?.[1]?.text ?? "";
+	assert.match(notice, /Context backstop/);
+	assert.match(notice, /160,000 tokens/, "measured tokens");
+	assert.match(notice, /16% of the 1,000,000-token context window/, "percent of the window");
+	assert.match(notice, /150,000-token backstop/, "the threshold");
+	assert.match(notice, /delegate the next bounded unit that needs several steps \(its reads, edits, and checks\) with a short handoff/);
+	assert.match(notice, /single small edits and state checks stay inline/);
+	assert.deepEqual(crossed?.structuredContent, { lines: 1 }, "structured content is kept");
+	assert.equal(crossed && "isError" in crossed, false, "the error flag is never altered");
+	assert.equal(await s.read(), undefined, "once per crossing");
+	s.setTokens(null);
+	assert.equal(await s.read(), undefined, "unknown tokens neither notify nor re-arm");
+	s.setTokens(170_000);
+	assert.equal(await s.read(), undefined, "still past the same crossing");
+	s.setTokens(40_000);
+	assert.equal(await s.read(), undefined, "dropping below the backstop re-arms it");
+	s.setTokens(19_200, 128_000);
+	const again = await s.read({ isError: true, structuredContent: undefined });
+	assert.match(again?.content?.[1]?.text ?? "", /19,200 tokens \(15% of the 128,000-token context window\), at or past the 19,200-token backstop/, "a small window reaches it at 15% of its size");
+	assert.equal(again && "structuredContent" in again, false, "absent structured content stays absent");
+	assert.equal(again && "isError" in again, false, "an error result keeps its flag");
+});
+
+test("child sessions never get the notice", async (t) => {
+	const s = session(t, true);
+	s.setTokens(390_000);
+	assert.equal(await s.read(), undefined);
+});
+
+test("a parent commit result carries both the slice line and the backstop notice", async (t) => {
+	const s = session(t, false);
+	const git = (...args: string[]) => execFileSync("git", ["-c", "user.name=Fixture", "-c", "user.email=fixture@example.com", "-c", "commit.gpgsign=false", ...args], { cwd: s.cwd, encoding: "utf8" });
+	git("init", "-q", "-b", "main");
+	writeFileSync(join(s.cwd, "README.md"), "base\n");
+	git("add", "README.md");
+	git("commit", "-q", "-m", "base");
+	git("switch", "-q", "-c", "feat/x");
+	writeFileSync(join(s.cwd, "a.ts"), "one\n");
+	git("add", "a.ts");
+	git("commit", "-q", "-m", "feat: a");
+	s.setTokens(200_000);
+	const result = await s.handlers.get("tool_result")!({
+		toolName: "bash", toolCallId: "call-1", isError: false, input: { command: "git commit -m 'feat: a'" },
+		content: [{ type: "text", text: "[feat/x 1234567] feat: a" }], structuredContent: { exitCode: 0 },
+	}, s.ctx) as Patch;
+	assert.equal(result?.content?.[0]?.text, "[feat/x 1234567] feat: a");
+	assert.match(result?.content?.[1]?.text ?? "", /Commit slice: 1 authored changed lines/);
+	assert.match(result?.content?.[2]?.text ?? "", /Context backstop/);
+	assert.deepEqual(result?.structuredContent, { exitCode: 0 });
+});
+
+test("a parent write result carries the notice after its own bookkeeping", async (t) => {
+	const s = session(t, false);
+	s.setTokens(150_000);
+	const result = await s.handlers.get("tool_result")!({
+		toolName: "write", toolCallId: "call-w", isError: false, input: { path: "src/a.ts" },
+		content: [{ type: "text", text: "Wrote src/a.ts" }],
+	}, s.ctx) as Patch;
+	assert.equal(result?.content?.[0]?.text, "Wrote src/a.ts");
+	assert.match(result?.content?.[1]?.text ?? "", /Context backstop/);
+});
+
+// The measurement behind the backstop (ctx.getContextUsage()) rebuilds the whole session
+// projection, so it is sampled at most once per window per session instead of once per
+// tool result. The window never decides the notice: it only decides when the context is
+// looked at again.
+test("the throttled measure samples once per window and the first sample of a session is immediate", () => {
+	let clock = 1_000;
+	const measure = createThrottledContextMeasure({ now: () => clock });
+	let calls = 0;
+	const sample = (value: MeasuredContext | undefined) => measure("session-a", () => { calls++; return value; });
+	assert.deepEqual(sample({ tokens: 10_000 }), { tokens: 10_000 }, "the first sample of a session measures immediately");
+	assert.equal(calls, 1);
+	clock = 2_000;
+	sample({ tokens: 10_000 });
+	assert.equal(calls, 1, "a sample inside the window skips the measurement");
+	clock = 6_001;
+	sample({ tokens: 10_000 });
+	assert.equal(calls, 2, "the window expired: measure again");
+	clock = 6_002;
+	sample({ tokens: 10_000 });
+	assert.equal(calls, 2, "the window restarts at every measurement");
+});
+
+test("the throttled measure is per session and a throwing measure never poisons the window", () => {
+	let clock = 0;
+	const measure = createThrottledContextMeasure({ now: () => clock });
+	assert.ok(measure("session-a", () => ({ tokens: 1 })), "session a measures");
+	assert.ok(measure("session-b", () => ({ tokens: 2 })), "session b inside the same window still measures");
+	assert.equal(measure("session-a", () => ({ tokens: 3 })), undefined, "session a inside its own window skips");
+	clock = 5_001;
+	let boom = false;
+	assert.equal(measure("session-a", () => { boom = true; throw new Error("boom"); }), undefined, "a throwing measure returns undefined");
+	assert.equal(boom, true, "the measure itself actually ran");
+	assert.equal(measure("session-a", () => ({ tokens: 4 }))?.tokens, undefined, "the failed measurement still consumed its window");
+	clock = 10_002;
+	assert.equal(measure("session-a", () => ({ tokens: 4 }))?.tokens, 4, "the next window measures again");
+});
+
+test("the extension samples the backstop context at most once per window per session", async (t) => {
+	let clock = 0;
+	const s = session(t, false, { now: () => clock });
+	assert.equal(s.measureCount(), 0);
+	await s.read();
+	assert.equal(s.measureCount(), 1, "the first tool result measures immediately");
+	await s.read();
+	await s.read();
+	assert.equal(s.measureCount(), 1, "tool results inside the window skip the measurement");
+	clock = 5_001;
+	s.setTokens(160_000);
+	const crossed = await s.read();
+	assert.equal(s.measureCount(), 2, "the window expired: measure again");
+	assert.match(crossed?.content?.[1]?.text ?? "", /Context backstop/, "a crossing is announced on the next sampled result");
+	await s.read();
+	assert.equal(s.measureCount(), 2, "and the window restarts after that sample");
+});

package/tests/delegate-for-reason-contract.test.ts

@@ -30,11 +30,19 @@ function lineStarting(text: string, prefix: string): string {
 const coreWriter = lineStarting(core, "5. **Writer rule**");
 const delegationWriter = lineStarting(delegation, "5. **Writer trigger (Writer rule):**");
 
+// Writer-rule fix (benchmark finding): a low-effort orchestrator read "2+
+// independent units, disjoint files" as tests vs README and split one behavior
+// across writers. The core rule now defines a unit as independent behavior,
+// keeps tests, docs, and code of one behavior together, and sets a size floor.
 test("AC1: the core writer rule fires on named reasons, never on size or file count", () => {
 	for (const clause of [
 		"never by file count or a large task alone",
 		"`orchestrator-writer.md`",
-		"2+ independent units, disjoint files, each heavier than a subagent start",
+		"2+ independent units of behavior (separate features or fixes that do not depend on each other), each heavier than a subagent start",
+		"a unit qualifies only when it needs several minutes of work: several files or roughly 100+ changed lines",
+		"a small change to one module or one command is done inline even when several such changes are independent",
+		"Tests, docs, and code of the same behavior are one unit, never separate writers",
+		"a delivery that depends on an earlier one is not independent",
 		"Context backstop",
 	]) {
 		assert.ok(coreWriter.includes(clause), `core Writer rule is missing: ${clause}`);
@@ -65,13 +73,19 @@ test("AC1: the lazy writer trigger names its reasons and keeps the logbook on th
 	assert.ok(skill.includes("a writer reason (parallel units or context)"), "the skill must name the writer reasons");
 });
 
-test("AC2: parallelism needs 2+ independent units, disjoint files, each heavier than a subagent start", () => {
-	assert.ok(
-		delegationWriter.includes(
-			"(a) parallelism — 2+ independent units with disjoint files, each clearly heavier than starting a subagent; medium tasks included",
-		),
-		"lazy Writer trigger must state the parallelism threshold",
-	);
+// S9 canon change (gentle-ai 87a3b2eb): the lazy trigger mirrors the canon's
+// behavior unit and size threshold instead of "clearly heavier than starting a
+// subagent; medium tasks included".
+test("AC2: parallelism needs 2+ independent behavior units, disjoint surfaces, each worth several minutes", () => {
+	for (const clause of [
+		"(a) parallelism — 2+ independent units of behavior with disjoint edit surfaces, each needing several minutes of work (several files or ~100+ changed lines; a subagent spends 1-2 minutes reading before it writes), launched together",
+		"A unit is one independent piece of behavior with its code, tests, and docs together: never split one behavior into test, docs, and code writers",
+		"a delivery that depends on another is not independent",
+		"several small independent changes run inline, one after another",
+	]) {
+		assert.ok(delegationWriter.includes(clause), `lazy Writer trigger is missing: ${clause}`);
+	}
+	assert.ok(!delegationWriter.includes("medium tasks included"), "lazy Writer trigger keeps the retired medium-task clause");
 	assert.ok(writer.includes("parallel units"), "the writer module must name the parallelism reason");
 });
 
@@ -96,16 +110,20 @@ test("T24/L49: configured per-agent model routing still applies to writers launc
 	);
 });
 
+// Verification by named risk changed the core rule 3 text: only a named
+// high-risk item, passed as assess `escalate`, adds the independent verifier.
+// odd/tasks/verifier-admission.md S6: the rule names the runtime admission of the verifier launch.
 test("AC4: verification stays risk-gated and the writer reasons never include risk", () => {
 	assert.ok(
 		core.includes(
-			"3. **Verification rule** — high risk → independent `gentle-ai-verify` after the change's own checks (`orchestrator-verification.md`); otherwise checks run inline.",
+			"3. **Verification rule** — only a named high-risk item (assess `escalate`) → independent `gentle-ai-verify`; else inline; runtime admission, gates/overengineering: `orchestrator-verification.md`.",
 		),
 		"core Verification rule changed",
 	);
 	assert.ok(
 		delegation.includes(
-			"3. **Verification rule** (gentle-pi#661/#662, RDD-aware): a high-risk change (Task Size) gets an independent `gentle-ai-verify` run after the change's own checks; otherwise whoever made the change runs its focused test and suite inline, small tasks included.",
+			// S9 canon change (gentle-ai 6b9a71ef): only a named high-risk item adds the verifier.
+			"3. **Verification rule** (gentle-pi#661/#662, RDD-aware): only a change whose Risk line names a high-risk item (Task Size, assess `escalate`) gets an independent `gentle-ai-verify` run after the change's own checks, as rarely as possible; otherwise whoever made the change runs its focused test and suite inline, small tasks included.",
 		),
 		"lazy Verification rule changed",
 	);
@@ -177,38 +195,41 @@ test("T12/S6: one independent verify per delegated unit after its self-review, n
 		"once, after its final self-review",
 		"never per worker cycle or retry",
 		"its Risk line",
-		"small-model bias per the tier table",
+		"high-risk list in Task Size",
 	]) {
 		assert.ok(item.includes(clause), `independent verify timing is missing: ${clause}`);
 	}
 	assert.ok(!item.includes("(1) "), "the timing rule restates the high-risk list");
+	// Verification by named risk retired the small-model bias.
+	assert.ok(!item.includes("small-model bias"), "the per-unit verify must not add a verifier for the writer's model");
 });
 
-// T15 (S6, L38): after3 B x4 paid two same-model verifies with 0 defects,
-// while verify caught real defects in smaller-model (Luna) writer code.
-test("T15/S6: same-model inline code over several deliveries gets one verify at the feature's end; smaller-model writer code stays per unit", () => {
+// T15 (S6, L38): after3 B x4 paid two same-model verifies with 0 defects.
+// Verification by named risk (user decision: the verifier follows the change's
+// risk, never the model that wrote it) dropped the smaller-model exception.
+test("T15/S6: inline code over several deliveries gets one verify at the feature's end, whatever model wrote it", () => {
 	const item = reviewItem("2. **Independent verify per unit**");
 	for (const clause of [
-		"Same-model inline code over several deliveries of one feature",
+		"Inline code over several deliveries of one feature",
 		"one verify at the feature's end",
-		"smaller-model writer code stays per unit",
 		"only when that unit is high risk",
-		"small-model bias per the tier table",
 	]) {
 		assert.ok(item.includes(clause), `independent verify exception is missing: ${clause}`);
 	}
+	assert.ok(!item.includes("smaller-model"), "the writer's model never keeps a per-unit verify");
 });
 
 test("T11/S4: the parent hands verify the whole spec, authorizes its probes and resolves every unmet item", () => {
 	const item = reviewItem("4. **Verify handoff**");
 	for (const clause of [
 		"the whole feature document",
-		"every `S#`, never one task",
+		"the assigned unit and its linked `S#` plus affected interactions",
+		"final feature verification covers every `S#`",
 		"the baseline commit",
 		"probes on isolated state",
 		"typecheck",
 		"`gentle-ai-verify` holds the checklist",
-		"every unmet item before closing",
+		"every in-scope unmet item before closing the unit",
 		"the writer commits its probes as regression tests",
 	]) {
 		assert.ok(item.includes(clause), `verify handoff item is missing: ${clause}`);
@@ -216,12 +237,17 @@ test("T11/S4: the parent hands verify the whole spec, authorizes its probes and
 });
 
 // verify-always-rdd-high S1 deliberately rewrote this section: verification follows the
-// risk tier in every RDD state. The pin still guards against accidental drift.
+// risk tier in every RDD state. Verification by named risk deliberately rewrote
+// the tier table again (escalate-only verifier, no small-model bias), and
+// verifier admission (odd/tasks/verifier-admission.md S6) names the runtime
+// check of the verifier launch; the PR #2290 review (odd/tasks/pr-2290-review.md S4)
+// names every line that admits it. The pin still guards against accidental drift.
 test("AC4/S4: the normative verification rule text is unchanged by the review protocol", () => {
 	const normative = sectionFrom(verification, "## Verification rule (normative)");
+	// Re-pinned on purpose: the runtime admission now also accepts a `Risk: item N` sentence (verifier-admission.ts).
 	assert.equal(
 		createHash("sha256").update(normative).digest("hex"),
-		"1f66f6998c4659fb08d81b83d350dcf5e8279b3f04a9e1a3a2951ed2abe7e54b",
+		"f052518b2905e4560d629397876057079aa71b45352272646261a611fb4a1e17",
 		"the normative Verification rule section changed",
 	);
 	assert.ok(verification.includes("or a delegated writer returns"), "the module must still load when a delegated writer returns");
@@ -298,7 +324,8 @@ test("T10: escalate labels name the core high-risk items", () => {
 test("T9/AC2: the parallelism reason launches every unit together in background and waits for all", () => {
 	const parallel = lineStarting(writer, "- **Parallelism**");
 	for (const clause of [
-		"every disjoint unit in the same turn",
+		// Writer-rule fix: a unit is one independent piece of behavior.
+		"every independent unit in the same turn",
 		'`subagent_run` with `mode: "background"`',
 		"wait for all completions",
 		"serial launches void the reason",
@@ -317,11 +344,52 @@ test("AC6: parallel writers need disjoint Allowed edit surfaces (runtime-enforce
 	const harness = read("extensions/gentle-ai.ts");
 	const docs = read("docs/readme-reference.md");
 	assert.ok(core.includes(`- P${rule}.`), "core Safety must carry the relaxed writer rule");
-	assert.ok(harness.includes(`- P${rule}.`), "harness principles must carry the relaxed writer rule");
-	for (const [path, text] of Object.entries({ core, delegation, harness, skill, docs })) {
+	// S11 T3: deduplicated. The harness principle repeated core Safety in the same
+	// parent prompt; the rendered prompt now carries the rule once, from Safety.
+	assert.ok(!harness.includes(rule), "harness principles restate the core Safety writer rule");
+	for (const persona of ["gentleman", "neutral"] as const) {
+		assert.equal(__testing.buildGentlePrompt(persona).split(rule).length - 1, 1, `[${persona}] the parent prompt must carry the writer rule once`);
+	}
+	for (const [path, text] of Object.entries({ core, delegation, skill, docs })) {
 		assert.ok(text.includes(rule), `${path} is missing the relaxed writer rule`);
+	}
+	for (const [path, text] of Object.entries({ core, delegation, harness, skill, docs })) {
 		for (const retired of ["single-threaded", "Never run parallel writers in one worktree", "do not run parallel writers unless isolated worktrees", "preserves a single writer thread", "one writer per task"]) {
 			assert.ok(!text.includes(retired), `${path} keeps the single-writer wording: ${retired}`);
 		}
 	}
 });
+
+// Writer-rule fix (benchmark finding): "Mandatory Delegation Triggers ...
+// and is then mandatory" read as a default to delegate. The core heading now
+// says a trigger holds only when its condition truly holds, inline when in doubt.
+test("the core delegation triggers hold only when their condition truly holds, none by default", () => {
+	const intro = lineStarting(core, "Delegation Triggers — ");
+	for (const clause of [
+		"each mechanism turns on only when its own trigger condition truly holds, and only then is it mandatory",
+		"no trigger holds by default",
+		"when in doubt work inline",
+	]) {
+		assert.ok(intro.includes(clause), `core delegation triggers are missing: ${clause}`);
+	}
+	assert.ok(!core.includes("Mandatory Delegation Triggers"), "the core must not read the triggers as mandatory by default");
+});
+
+test("the writer module sets the size threshold and keeps one behavior in one unit", () => {
+	const size = lineStarting(writer, "- **Size threshold**");
+	for (const clause of [
+		"a subagent costs one to two minutes of reading and setup before it writes anything",
+		"delegate a unit only when it needs several minutes of work (several files or roughly 100+ changed lines)",
+		"Several small independent changes are faster inline, one after another",
+	]) {
+		assert.ok(size.includes(clause), `writer size threshold is missing: ${clause}`);
+	}
+	const parallel = lineStarting(writer, "- **Parallelism**");
+	for (const clause of [
+		"a unit is one independent piece of behavior with its own code, tests, and docs",
+		"never split one behavior into a test writer, a docs writer, and inline code",
+		"never delegate a unit that depends on another unit still in progress",
+	]) {
+		assert.ok(parallel.includes(clause), `writer parallelism unit rule is missing: ${clause}`);
+	}
+});

package/tests/delivered-test-lint.test.ts

@@ -0,0 +1,105 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { deliveredTestViolation, evaluateDeliveredTestTool, isTestFilePath } from "../lib/delivered-test-lint.ts";
+
+// Harness roadmap T5 (R1): blind review found delivered tests that ran
+// `git show <baseline commit>` and failed in another clone, and orchestrators
+// that pointed TMPDIR into the repository. The prompt rule did not hold, so the
+// runtime blocks writing such a test instead of asking the model not to.
+
+test("isTestFilePath recognizes common test layouts and nothing else", () => {
+	for (const path of ["tests/ledger.test.ts", "src/__tests__/a.ts", "test/cli.spec.js", "pkg/store_test.go", "tests/test_cli.py", "/abs/repo/test/x.mjs"]) {
+		assert.equal(isTestFilePath(path), true, path);
+	}
+	for (const path of ["src/ledger.ts", "README.md", "src/testing-utils.ts", "docs/tests.md"]) {
+		assert.equal(isTestFilePath(path), false, path);
+	}
+});
+
+test("a test that reads a literal commit from git history is a violation", () => {
+	for (const content of [
+		'const old = execSync("git show 3f9c2e1:src/ledger.ts").toString();',
+		"execFileSync('git', ['show', 'a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0:src/cli.ts']);",
+		"git checkout 9e8d7c6 -- src/cli.ts",
+		"git diff 4c5d6e7f HEAD -- src",
+		"git archive 77aa12b | tar -x -C \"$scratch\"",
+	]) {
+		assert.match(deliveredTestViolation(content) ?? "", /git history/, content);
+	}
+});
+
+test("a test that points TMPDIR inside the working directory is a violation", () => {
+	for (const content of [
+		"TMPDIR=$PWD/.test-tmp node --test",
+		'const env = { ...process.env, TMPDIR: join(process.cwd(), ".tmp") };',
+		"process.env.TMPDIR = path.join(__dirname, 'tmp');",
+		"export TMPDIR=\"$(pwd)/tmp\"",
+		'os.environ["TMPDIR"] = os.getcwd()',
+	]) {
+		assert.match(deliveredTestViolation(content) ?? "", /TMPDIR/, content);
+	}
+});
+
+// PR #2290 review: a relative TMPDIR resolves against the working directory just
+// like `$PWD/...`, so test scratch entered the diff unflagged.
+test("a test that sets TMPDIR to a relative path is a violation", () => {
+	for (const content of [
+		"TMPDIR=./.tmp node --test",
+		"TMPDIR=.tmp node --test",
+		"export TMPDIR=tmp/x",
+		'const env = { ...process.env, TMPDIR: "./.tmp" };',
+		"process.env.TMPDIR = '.tmp';",
+		'process.env.TMPDIR = "tmp/x";',
+		'os.environ["TMPDIR"] = "../scratch"',
+	]) {
+		assert.match(deliveredTestViolation(content) ?? "", /TMPDIR/, content);
+	}
+	for (const content of [
+		'TMPDIR="$TMPDIR/ledger" node --test',
+		"TMPDIR=${TMPDIR:-/tmp}/ledger node --test",
+		"export TMPDIR=/var/tmp/ledger",
+		'const env = { TMPDIR: "/tmp/ledger" };',
+		"const env = { TMPDIR: os.tmpdir() };",
+		"const env = { TMPDIR: path.join(tmpdir(), 'ledger') };",
+		"TMPDIR=~/scratch node --test",
+		'process.env.TMPDIR = "C:\\\\Temp";',
+		"const env = { TMPDIR: `${tmpdir()}/ledger` };",
+		'const task = runner.run(request({ env: { TMPDIR: "reltmp" } }));',
+	]) {
+		assert.equal(deliveredTestViolation(content), undefined, content);
+	}
+});
+
+test("ordinary tests, git use in throwaway repos, and outside scratch stay allowed", () => {
+	for (const content of [
+		'const dir = mkdtempSync(join(tmpdir(), "ledger-"));',
+		'execFileSync("git", ["init", "-q"], { cwd: dir }); execFileSync("git", ["stash"], { cwd: dir });',
+		'git show HEAD:src/a.ts',
+		"const env = { TMPDIR: scratch, PATH: [dirname(process.execPath)].join(':') };",
+		"git log -1 --format='%h' 53d62fbf3",
+		'assert.equal(hash("deadbeef"), "cafebabe");',
+		"assert.equal(env.TMPDIR === process.cwd(), false);",
+	]) {
+		assert.equal(deliveredTestViolation(content), undefined, content);
+	}
+});
+
+test("evaluateDeliveredTestTool blocks write and edit of a test file, never a source file", () => {
+	const bad = 'execSync("git show 3f9c2e1:src/ledger.ts")';
+	const write = evaluateDeliveredTestTool("write", { path: "tests/ledger.test.ts", content: bad });
+	assert.equal(write?.block, true);
+	assert.match(write?.reason ?? "", /tests\/ledger\.test\.ts/);
+	assert.match(write?.reason ?? "", /mktemp/);
+	assert.equal(evaluateDeliveredTestTool("edit", { path: "tests/ledger.test.ts", edits: [{ oldText: "a", newText: bad }] })?.block, true);
+	assert.equal(evaluateDeliveredTestTool("edit", { path: "tests/ledger.test.ts", oldText: "a", newText: bad })?.block, true);
+	assert.equal(evaluateDeliveredTestTool("write", { path: "scripts/diff-check.sh", content: bad }), undefined);
+	assert.equal(evaluateDeliveredTestTool("read", { path: "tests/ledger.test.ts" }), undefined);
+	assert.equal(evaluateDeliveredTestTool("write", { path: "tests/ledger.test.ts", content: "assert.ok(true);" }), undefined);
+});
+
+test("absolute paths are judged relative to the session cwd, so a project under a test/ directory is not a test", () => {
+	const bad = 'execSync("git show 3f9c2e1:src/ledger.ts")';
+	assert.equal(evaluateDeliveredTestTool("write", { path: "/home/u/test/app/src/release.ts", content: bad }, "/home/u/test/app"), undefined);
+	assert.equal(evaluateDeliveredTestTool("write", { path: "/home/u/test/app/tests/a.test.ts", content: bad }, "/home/u/test/app")?.block, true);
+	assert.equal(evaluateDeliveredTestTool("write", { path: "/elsewhere/tests/a.ts", content: bad }, "/home/u/test/app")?.block, true, "outside the cwd the path is judged whole");
+});