gentle-pi 3.1.1 → 3.2.1

package/tests/gentle-shell.test.ts

@@ -6,7 +6,7 @@ import { join } from "node:path";
 import test from "node:test";
 import { initTheme, type ExtensionAPI, type ExtensionContext, type SlashCommandInfo, type SourceInfo } from "@earendil-works/pi-coding-agent";
 import type { TUI } from "@earendil-works/pi-tui";
-import installGentleShell, { buildShellBarModel, createActiveProfileReader, changesShortcut, devBinaryCard, fetchCodexUsage, loadFileDiff, shellGitRunner, openInExternalEditor, type GentlePromptEditor } from "../extensions/gentle-shell.ts";
+import installGentleShell, { buildShellBarModel, createActiveProfileReader, changesShortcut, devBinaryCard, fetchCodexUsage, fetchNanUsage, loadFileDiff, shellGitRunner, openInExternalEditor, type GentlePromptEditor } from "../extensions/gentle-shell.ts";
 import { CHANGE_STATUS } from "../lib/shell-changes.ts";
 import { sidebarState, type SidebarRail } from "../lib/shell-sidebar.ts";
 import type { ShellBarTheme } from "../lib/shell-bar.ts";
@@ -715,9 +715,9 @@ const JWT = `h.${Buffer.from(JSON.stringify({ "https://api.openai.com/auth": { c
 const USAGE_PAYLOAD = { plan_type: "pro", rate_limit: { primary_window: { used_percent: 40, limit_window_seconds: 604_800, reset_at: 1_788_777_491 } } };
 
 function fakeFetch(payload: unknown = USAGE_PAYLOAD, ok = true) {
-	const calls: Array<{ url: string; headers: Record<string, string> }> = [];
+	const calls: Array<{ url: string; headers: Record<string, string>; init: RequestInit }> = [];
 	const fetchFn = (async (url: string | URL, init?: RequestInit) => {
-		calls.push({ url: String(url), headers: (init?.headers ?? {}) as Record<string, string> });
+		calls.push({ url: String(url), headers: (init?.headers ?? {}) as Record<string, string>, init: init ?? {} });
 		return { ok, json: async () => payload } as Response;
 	}) as typeof fetch;
 	return { fetchFn, calls };
@@ -738,6 +738,94 @@ test("fetchCodexUsage sends the token and account id and parses the payload", as
 	assert.equal(await fetchCodexUsage(undefined, plain.fetchFn, 0), undefined);
 });
 
+const NAN_QUOTA_PAYLOAD = {
+	periodEnd: "2026-10-01T00:00:00.000Z",
+	models: [
+		{
+			model: "glm5.3",
+			cap: 3_000_000_000,
+			fullCap: 3_000_000_000,
+			tokensUsed: 820_000_000,
+			windowHours: 4,
+			windowTokens: 400_000_000,
+			windowTokensUsed: 120_000_000,
+			windowResetsAt: 1_788_620_161,
+		},
+	],
+};
+
+test("fetchNanUsage sends the key to the fixed quota origin and never follows a redirect", async () => {
+	const { fetchFn, calls } = fakeFetch(NAN_QUOTA_PAYLOAD);
+	const usage = await fetchNanUsage("sk-nan-secret", fetchFn, 1_788_600_000_000);
+	assert.equal(usage?.provider, "nan");
+	assert.equal(usage?.limits[0].name, "glm5.3");
+	assert.equal(calls.length, 1);
+	assert.equal(calls[0].url, "https://cloud-api.nan.builders/api/usage/quota");
+	assert.equal(calls[0].headers.Authorization, "Bearer sk-nan-secret");
+	assert.equal(calls[0].init.redirect, "error", "a redirect would forward the bearer to another origin");
+	assert.equal(calls[0].init.cache, "no-store");
+	assert.equal(JSON.stringify(usage).includes("sk-nan-secret"), false);
+});
+
+test("fetchNanUsage degrades to no snapshot without ever throwing", async () => {
+	const noKey = fakeFetch(NAN_QUOTA_PAYLOAD);
+	assert.equal(await fetchNanUsage(undefined, noKey.fetchFn, 0), undefined);
+	assert.equal(await fetchNanUsage("", noKey.fetchFn, 0), undefined);
+	assert.equal(noKey.calls.length, 0, "no key, no request");
+
+	assert.equal(await fetchNanUsage("sk-nan-secret", fakeFetch(NAN_QUOTA_PAYLOAD, false).fetchFn, 0), undefined, "a non-OK response is not a snapshot");
+	assert.equal(await fetchNanUsage("sk-nan-secret", fakeFetch({ models: [] }).fetchFn, 0), undefined, "an empty quota is not a snapshot");
+	assert.equal(await fetchNanUsage("sk-nan-secret", fakeFetch({ models: [{ model: "glm5.3", cap: 0, tokensUsed: 0 }] }).fetchFn, 0), undefined);
+	const refused = (async () => {
+		throw new TypeError("redirect mode is not supported");
+	}) as unknown as typeof fetch;
+	assert.equal(await fetchNanUsage("sk-nan-secret", refused, 0), undefined, "a refused redirect degrades silently");
+});
+
+test("gentleShell fetches NaN quota on session start and shows it in the bar", async () => {
+	const { pi, handlers } = fakePi();
+	const { fetchFn, calls } = fakeFetch(NAN_QUOTA_PAYLOAD);
+	gentleShell(pi, { GENTLE_PI_SHELL_CHANGES_WATCH_MS: "off" }, { fetch: fetchFn, now: () => 1_788_600_000_000 });
+	const { ctx, ui } = fakeContext({ token: "sk-nan-secret" });
+	(ctx as unknown as { model: { provider: string } }).model.provider = "nan";
+	await fire(handlers, "session_start", ctx);
+	await new Promise((resolve) => setTimeout(resolve, 0));
+	assert.equal(calls.length, 1);
+	assert.equal(calls[0].url, "https://cloud-api.nan.builders/api/usage/quota");
+	// The fixture's session model holds no NaN allowance of its own, so the
+	// account names the meter: a NaN payload of one model is still per-model data.
+	assert.match(renderFooter(ui), /\$0\.000 sub ⟡ nan total ▰+▱+ 27%/);
+
+	await fire(handlers, "agent_end", ctx);
+	await new Promise((resolve) => setTimeout(resolve, 0));
+	assert.equal(calls.length, 1, "agent_end must not refetch within the refresh window");
+});
+
+test("a failed NaN refresh keeps the last valid snapshot", async () => {
+	const { pi, handlers } = fakePi();
+	const calls: string[] = [];
+	let fail = false;
+	const fetchFn = (async (url: string | URL) => {
+		calls.push(String(url));
+		if (fail) throw new TypeError("network down");
+		return { ok: true, json: async () => NAN_QUOTA_PAYLOAD } as Response;
+	}) as typeof fetch;
+	let now = 1_788_600_000_000;
+	gentleShell(pi, { GENTLE_PI_SHELL_CHANGES_WATCH_MS: "off" }, { fetch: fetchFn, now: () => now });
+	const { ctx, ui } = fakeContext({ token: "sk-nan-secret" });
+	(ctx as unknown as { model: { provider: string } }).model.provider = "nan";
+	await fire(handlers, "session_start", ctx);
+	await new Promise((resolve) => setTimeout(resolve, 0));
+	assert.match(renderFooter(ui), /nan total ▰+▱+/);
+
+	fail = true;
+	now += 6 * 60_000;
+	await fire(handlers, "agent_end", ctx);
+	await new Promise((resolve) => setTimeout(resolve, 0));
+	assert.equal(calls.length, 2, "the refresh window elapsed, so the retry was attempted");
+	assert.match(renderFooter(ui), /nan total ▰+▱+/, "a failed refresh cannot erase the last valid snapshot");
+});
+
 test("gentleShell fetches Codex usage on session start and shows it in the bar", async () => {
 	const { pi, handlers } = fakePi();
 	const { fetchFn, calls } = fakeFetch();
@@ -753,6 +841,24 @@ test("gentleShell fetches Codex usage on session start and shows it in the bar",
 	assert.equal(calls.length, 1, "agent_end must not refetch within the refresh window");
 });
 
+test("a provider switch refreshes the new provider inside the same window", async () => {
+	const { pi, handlers } = fakePi();
+	const { fetchFn, calls } = fakeFetch(NAN_QUOTA_PAYLOAD);
+	gentleShell(pi, { GENTLE_PI_SHELL_CHANGES_WATCH_MS: "off" }, { fetch: fetchFn, now: () => 1_788_600_000_000 });
+	const { ctx } = fakeContext({ token: JWT });
+	await fire(handlers, "session_start", ctx);
+	await new Promise((resolve) => setTimeout(resolve, 0));
+	assert.equal(calls.length, 1);
+
+	// The 5-minute rule is per provider: the timestamp one provider set cannot
+	// leave the next one waiting for a fetch it never made.
+	(ctx as unknown as { model: { provider: string } }).model.provider = "nan";
+	await fire(handlers, "agent_end", ctx);
+	await new Promise((resolve) => setTimeout(resolve, 0));
+	assert.equal(calls.length, 2, "a provider switch is a reason to fetch, not to wait");
+	assert.equal(calls[1].url, "https://cloud-api.nan.builders/api/usage/quota");
+});
+
 test("gentleShell records SSE rate-limit headers from provider responses", async () => {
 	const { pi, handlers } = fakePi();
 	gentleShell(pi, { GENTLE_PI_SHELL_CHANGES_WATCH_MS: "off" }, { fetch: fakeFetch({}, false).fetchFn, now: () => 0 });

package/tests/native-review-capability-contract.test.ts

@@ -275,11 +275,37 @@ test("3.0.1 repeats 3.0.0 because the negotiated lane Pi consumes is unchanged",
 	assert.deepEqual(contract, NATIVE_CLI_CONTRACTS["3.0.0"] as Record<string, boolean>);
 });
 
+test("3.1.0 repeats 3.0.1 because the negotiated lane Pi consumes is unchanged", () => {
+	// v3.1.0 changed the ODD orchestrator contract only (gentle-ai #4714).
+	// Diffing contracts/review-integration/v2 and
+	// contracts/review-provider-contract between the v3.0.2 and v3.1.0 tags
+	// in the gentle-ai source tree showed zero byte changes (provider contract
+	// stays 1.2.0), so this row repeats 3.0.1. riskEvidence and hint remain
+	// dark because neither is proven to reach Pi's negotiated START path.
+	const contract = NATIVE_CLI_CONTRACTS["3.1.0"] as Record<string, boolean>;
+	assert.equal(contract.riskEvidence, false);
+	assert.equal(contract.hint, false);
+	assert.deepEqual(contract, NATIVE_CLI_CONTRACTS["3.0.1"] as Record<string, boolean>);
+});
+
+test("3.2.1 repeats 3.1.0 because the negotiated lane Pi consumes is unchanged", () => {
+	// v3.2.1 changed the ODD orchestrator contract only (gentle-ai #4714
+	// follow-up). Diffing contracts/review-integration/v2 and
+	// contracts/review-provider-contract between the v3.1.0 and v3.2.1 tags
+	// in the gentle-ai source tree showed zero byte changes (provider contract
+	// stays 1.2.0), so this row repeats 3.1.0. riskEvidence and hint remain
+	// dark because neither is proven to reach Pi's negotiated START path.
+	const contract = NATIVE_CLI_CONTRACTS["3.2.1"] as Record<string, boolean>;
+	assert.equal(contract.riskEvidence, false);
+	assert.equal(contract.hint, false);
+	assert.deepEqual(contract, NATIVE_CLI_CONTRACTS["3.1.0"] as Record<string, boolean>);
+});
+
 test("no shipped version key was added beyond the pin bump", () => {
 	// Rows are promises to consumers, so a new key only ever appears in a
 	// dedicated commit alongside a pin bump, never as a side effect. v2.2.4 and
 	// v2.3.0 shipped upstream while Pi stayed on 2.2.3 and were never pinned,
 	// so they get no row: a row asserts ground truth measured against a binary
 	// Pi actually ran, and the table only has to be ascending, not gapless.
-	assert.deepEqual(Object.keys(NATIVE_CLI_CONTRACTS), [...DARK_VERSIONS, "2.2.0", "2.2.1", "2.2.2", "2.2.3", "2.4.0", "2.5.0-rc.3", "2.5.0", "2.6.0", "2.7.0", "2.8.0", "2.8.1", "2.8.2", "2.9.0", "2.9.1", "3.0.0", "3.0.1"]);
+	assert.deepEqual(Object.keys(NATIVE_CLI_CONTRACTS), [...DARK_VERSIONS, "2.2.0", "2.2.1", "2.2.2", "2.2.3", "2.4.0", "2.5.0-rc.3", "2.5.0", "2.6.0", "2.7.0", "2.8.0", "2.8.1", "2.8.2", "2.9.0", "2.9.1", "3.0.0", "3.0.1", "3.1.0", "3.2.1"]);
 });

package/tests/odd-routing-canonical-ratchet.test.ts

@@ -0,0 +1,293 @@
+import assert from "node:assert/strict";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import test from "node:test";
+import {
+	ODD_ROUTING_BLOCK_PREFIX,
+	ODD_ROUTING_FIXTURE_RELATIVE,
+	ODD_ROUTING_SOURCE_PATH,
+	ODD_ROUTING_SOURCE_REPO,
+	assertCleanGentleAiCheckout,
+	parseOddRoutingFixture,
+	renderOddRoutingFixture,
+	resolveOddRoutingProvenance,
+	sha256Hex,
+} from "../scripts/mirror-odd-routing.mjs";
+
+// ---------------------------------------------------------------------------
+// ODD routing drift ratchet (gentle-pi#1147 follow-up)
+//
+// gentle-pi hand-mirrors the always-on ODD routing block rendered by gentle-ai
+// `internal/components/agentguidance/routing.go` (RenderRouting). There is no
+// automated sync, so a canonical change leaves the pi mirror stale with nothing
+// catching it. This ratchet vendored-snapshots the canonical block into
+// `fixtures/odd-routing-canonical.md` (regenerated via `npm run
+// mirror:odd-routing`) and fails when a mandatory-delegation clause is dropped
+// either from the canonical fixture or from a pi mirror surface.
+//
+// Regeneration writes ONLY the fixture; this ratchet never auto-rewrites mirror
+// assets, so drift stays visible as a deliberate diff.
+// ---------------------------------------------------------------------------
+
+const REPO_ROOT = join(import.meta.dirname, "..");
+const FIXTURE_PATH = join(REPO_ROOT, ...ODD_ROUTING_FIXTURE_RELATIVE.split("/"));
+const DELEGATION_PATH = join(REPO_ROOT, "assets", "orchestrator-delegation.md");
+const CORE_PATH = join(REPO_ROOT, "assets", "orchestrator.md");
+const EXTENSION_PATH = join(REPO_ROOT, "extensions", "gentle-ai.ts");
+
+const readRepo = (absolutePath: string): string => readFileSync(absolutePath, "utf8");
+
+// A mandatory-delegation semantic anchor: the clause the canonical block must
+// still carry, plus the wording each pi mirror surface is expected to carry.
+// A canonical change that drops `canonical` is caught here on regeneration
+// because the fixture no longer carries it.
+interface RoutingAnchor {
+	label: string;
+	canonical: string;
+	mirrors: ReadonlyArray<{ surface: string; includes: string }>;
+}
+
+const DELEGATION = "assets/orchestrator-delegation.md";
+const CORE = "assets/orchestrator.md";
+const EXTENSION = "extensions/gentle-ai.ts";
+
+const ANCHORS: readonly RoutingAnchor[] = [
+	{
+		label: "mandatory delegation triggers heading",
+		canonical: "### Mandatory Delegation Triggers",
+		mirrors: [
+			{ surface: DELEGATION, includes: "#### Mandatory Delegation Triggers" },
+			{ surface: CORE, includes: "Mandatory Delegation Triggers" },
+		],
+	},
+	{
+		label: "triggers are mandatory, not advisory",
+		canonical: "These triggers are mandatory, not advisory.",
+		mirrors: [
+			{ surface: DELEGATION, includes: "These triggers are mandatory, not advisory." },
+			{ surface: EXTENSION, includes: "These triggers are mandatory, not advisory" },
+		],
+	},
+	{
+		label: "stop and delegate through the runtime's subagent mechanism",
+		canonical: "stop and delegate through the runtime's subagent mechanism before continuing",
+		mirrors: [
+			{ surface: DELEGATION, includes: "stop and delegate through the runtime's subagent mechanism before continuing" },
+		],
+	},
+	{
+		label: "executing past a fired trigger is a routing defect",
+		canonical: "executing past a fired trigger inline is a routing defect even if the work succeeds",
+		mirrors: [
+			{ surface: DELEGATION, includes: "executing past a fired trigger inline is a routing defect even if the work succeeds" },
+			{ surface: EXTENSION, includes: "executing past a fired trigger inline is a routing defect even if the work succeeds" },
+		],
+	},
+	{
+		label: "mapping trigger at 4 or more files",
+		canonical: "**Mapping trigger:** when understanding the work requires 4 or more files",
+		mirrors: [
+			{ surface: DELEGATION, includes: "**Mapping trigger (4-file rule):** when understanding the work requires 4 or more files" },
+			{ surface: CORE, includes: "**4-file rule** — 4+ files to understand" },
+		],
+	},
+	{
+		label: "writer trigger at 2 or more non-trivial files",
+		canonical: "**Writer trigger:** when implementation touches 2 or more non-trivial files",
+		mirrors: [
+			{ surface: DELEGATION, includes: "**Writer trigger (Multi-file write rule):** when implementation touches 2 or more non-trivial files" },
+			{ surface: CORE, includes: "**Multi-file write rule** — 2+ non-trivial files touched" },
+		],
+	},
+	{
+		label: "preparation trigger",
+		canonical: "**Preparation trigger:**",
+		mirrors: [{ surface: DELEGATION, includes: "**Preparation trigger:**" }],
+	},
+	{
+		label: "long-session backstop",
+		canonical: "**Long-session backstop:**",
+		mirrors: [
+			{ surface: DELEGATION, includes: "**Long-session backstop (Long-session rule):**" },
+			{ surface: CORE, includes: "**Long-session rule** — ~20 tool calls, 5 exploratory reads, or 2 non-mechanical edits without delegation" },
+		],
+	},
+	{
+		label: "route declaration records the chosen route per task",
+		canonical: "**Route declaration:**",
+		mirrors: [
+			{ surface: DELEGATION, includes: "record the chosen route per task" },
+		],
+	},
+	{
+		label: "triggers never select SDD",
+		canonical: "These triggers never select SDD and never create SDD artifacts",
+		mirrors: [
+			{ surface: DELEGATION, includes: "These triggers never select SDD and never create SDD artifacts" },
+		],
+	},
+	{
+		label: "ODD step 6 honors its mandatory delegation triggers",
+		canonical: "honoring its mandatory delegation triggers",
+		mirrors: [{ surface: EXTENSION, includes: "honoring its mandatory delegation triggers" }],
+	},
+];
+
+// Condensed trigger rows that live only in the always-on core prompt; the
+// canonical RenderRouting block does not carry the incident or verification
+// rows, so they are mirror-only and not fixture-derived anchors.
+const CORE_ONLY_TRIGGERS = [
+	"**Incident rule** — diagnose wrong cwd/worktree/git/tooling incidents separately",
+	"**Verification rule** — executing/delegating verification commands",
+] as const;
+
+function fixtureBody(): string {
+	assert.ok(
+		existsSync(FIXTURE_PATH),
+		`missing canonical fixture ${ODD_ROUTING_FIXTURE_RELATIVE}; regenerate it with \`npm run mirror:odd-routing\``,
+	);
+	return parseOddRoutingFixture(readRepo(FIXTURE_PATH)).body;
+}
+
+// ---------------------------------------------------------------------------
+// 1 — Fixture provenance readback
+// ---------------------------------------------------------------------------
+
+test("the canonical routing fixture exists with managed provenance (source repo, commit, digest)", () => {
+	assert.ok(
+		existsSync(FIXTURE_PATH),
+		`missing canonical fixture ${ODD_ROUTING_FIXTURE_RELATIVE}; regenerate it with \`npm run mirror:odd-routing\``,
+	);
+	const { header } = parseOddRoutingFixture(readRepo(FIXTURE_PATH));
+	assert.equal(header.source_repo, ODD_ROUTING_SOURCE_REPO);
+	assert.equal(header.source_path, ODD_ROUTING_SOURCE_PATH);
+	assert.match(header.source_commit ?? "", /^[0-9a-f]{40}$/, "fixture must record the gentle-ai source commit");
+	assert.match(header.generated_at ?? "", /^\d{4}-\d{2}-\d{2}T/, "fixture must record a generation date");
+	assert.match(header.block_sha256 ?? "", /^[0-9a-f]{64}$/, "fixture must record the block body digest");
+});
+
+test("the fixture digest matches its block body byte-for-byte", () => {
+	const { header, body } = parseOddRoutingFixture(readRepo(FIXTURE_PATH));
+	assert.equal(header.block_sha256, sha256Hex(body), "the fixture body was hand-edited without regenerating its digest");
+});
+
+// ---------------------------------------------------------------------------
+// 2 — Canonical fixture carries every mandatory anchor
+// ---------------------------------------------------------------------------
+
+test("the canonical fixture carries every mandatory-delegation anchor", () => {
+	const body = fixtureBody();
+	for (const anchor of ANCHORS) {
+		assert.ok(body.includes(anchor.canonical), `canonical fixture dropped anchor: ${anchor.label}`);
+	}
+});
+
+// ---------------------------------------------------------------------------
+// 3 — Every pi mirror surface carries the mapped anchor
+// ---------------------------------------------------------------------------
+
+test("the pi mirror surfaces carry every mapped mandatory-delegation anchor", () => {
+	const surfaces: Record<string, string> = {
+		[DELEGATION]: readRepo(DELEGATION_PATH),
+		[CORE]: readRepo(CORE_PATH),
+		[EXTENSION]: readRepo(EXTENSION_PATH),
+	};
+	for (const anchor of ANCHORS) {
+		for (const mirror of anchor.mirrors) {
+			const text = surfaces[mirror.surface];
+			assert.ok(text !== undefined, `unknown mirror surface ${mirror.surface}`);
+			assert.ok(
+				text.includes(mirror.includes),
+				`${mirror.surface} is missing the mirror of "${anchor.label}": ${JSON.stringify(mirror.includes)}`,
+			);
+		}
+	}
+});
+
+test("the always-on core prompt carries the condensed incident and verification trigger rows", () => {
+	const core = readRepo(CORE_PATH);
+	for (const row of CORE_ONLY_TRIGGERS) {
+		assert.ok(core.includes(row), `assets/orchestrator.md is missing condensed trigger row: ${JSON.stringify(row)}`);
+	}
+});
+
+// ---------------------------------------------------------------------------
+// 4 — Regeneration provenance: idempotent and fail-closed
+// ---------------------------------------------------------------------------
+
+// The fixture header claims provenance from the source commit, so regeneration
+// must be byte-reproducible: the same gentle-ai commit must not produce a
+// date-only diff. `generated_at` therefore tracks the source commit's committer
+// date instead of wall-clock time.
+test("fixture rendering is idempotent and derives generated_at from the source commit", () => {
+	const sourceCommit = "e7729359fd9d6cb691ed2a88e8f72b1372f7c92e";
+	const committerDate = "2026-09-18T13:49:03+02:00";
+	const fakeGit = (args: readonly string[]): string => {
+		switch (args[0]) {
+			case "status":
+				return "";
+			case "rev-parse":
+				return `${sourceCommit}\n`;
+			case "show":
+				return `${committerDate}\n`;
+			default:
+				throw new Error(`unexpected git invocation: ${args.join(" ")}`);
+		}
+	};
+	const block = `${ODD_ROUTING_BLOCK_PREFIX}\n\n- a canonical clause\n`;
+	const first = renderOddRoutingFixture(block, resolveOddRoutingProvenance("/fake/gentle-ai", fakeGit));
+	const second = renderOddRoutingFixture(block, resolveOddRoutingProvenance("/fake/gentle-ai", fakeGit));
+	assert.equal(first, second, "rendering the same source commit twice must be byte-identical");
+	const { header } = parseOddRoutingFixture(first);
+	assert.equal(header.source_commit, sourceCommit);
+	assert.equal(
+		header.generated_at,
+		committerDate,
+		"generated_at must track the source commit's committer date, not wall-clock time",
+	);
+});
+
+// A dirty checkout would render uncommitted content under the committed
+// provenance claim, so the mirror fails closed before rendering and names the
+// tracked paths. Untracked files (the odd/tasks notes) must never block.
+test("the mirror fails closed on a dirty source checkout and names the tracked paths", () => {
+	const recordedCalls: string[][] = [];
+	const cleanGit = (args: readonly string[]): string => {
+		recordedCalls.push([...args]);
+		switch (args[0]) {
+			case "status":
+				return "";
+			case "rev-parse":
+				return `${"a".repeat(40)}\n`;
+			case "show":
+				return "2026-09-18T13:49:03+02:00\n";
+			default:
+				throw new Error(`unexpected git invocation: ${args.join(" ")}`);
+		}
+	};
+	resolveOddRoutingProvenance("/fake/gentle-ai", cleanGit);
+	assert.deepEqual(
+		recordedCalls.find((args) => args[0] === "status"),
+		["status", "--porcelain", "--untracked-files=no"],
+		"the dirty guard must ignore untracked files",
+	);
+
+	assert.doesNotThrow(() => assertCleanGentleAiCheckout(""));
+	const dirtyGit = (args: readonly string[]): string => {
+		if (args[0] === "status") {
+			return " M internal/components/agentguidance/routing.go\n M scripts/other.mjs\n";
+		}
+		throw new Error(`unexpected git invocation: ${args.join(" ")}`);
+	};
+	assert.throws(
+		() => resolveOddRoutingProvenance("/fake/gentle-ai", dirtyGit),
+		(error: unknown) => {
+			assert.ok(error instanceof Error);
+			assert.match(
+				error.message,
+				/gentle-ai checkout is dirty; provenance would be unverifiable: internal\/components\/agentguidance\/routing\.go, scripts\/other\.mjs\. Commit or stash first\./,
+			);
+			return true;
+		},
+	);
+});

package/tests/odd-routing-contract.test.ts

@@ -94,8 +94,8 @@ test("assumption challenge and task checks do not activate or duplicate native r
 		"high-consequence unproven premise",
 		"Deterministic failures need fixes",
 		"native RDD refuter",
-		"functional checks per task, not an RDD cycle per TODO",
-		"deliverable candidate boundary",
+		"functional checks per task",
+		"native review runs at that work-unit commit or PR slice boundary",
 		"native candidate risk assessment",
 		"gentle_review` with `{\"operation\":\"assess\"}",
 		"Passive/low",
@@ -107,6 +107,48 @@ test("assumption challenge and task checks do not activate or duplicate native r
 	]);
 });
 
+test("ODD closes each task with a work-unit commit and reviews the commit or PR slice", () => {
+	containsAll(wrapper, [
+		"Every task closes with at least one work-unit commit on the feature branch, branch first when on the default branch",
+		"with tests and docs alongside the behavior, using a Conventional Commit message",
+		"record the commit identity in the feature document as evidence",
+		"Work-unit commits on the feature branch are part of authorized substantial ODD implementation; push, pull request creation, and merge remain the user's decisions",
+		"The native review candidate is a work-unit commit or a PR slice, never a TODO checkbox and never the accumulated feature branch",
+		"close each task with a work-unit commit",
+	]);
+	containsAll(delegation, [
+		'after each work-unit commit, assess it with that same call and `{"baseRef":"<last reviewed boundary>","committedOnly":true}`',
+		"Passive/low: silent structural checks, no reviewer or consent ceremony, and the boundary advances",
+		'start native review on it right away at that base with `gentle_review` `{"operation":"start"}`',
+		"Medium: defer to the PR slice",
+		"bounded by the delivery budget of about 400 authored changed lines",
+		"The first boundary is the branch point, and every reviewed boundary becomes the next base",
+		"Record per task the assessed tier and outcome: granted, declined, passive, deferred to slice, or unavailable",
+		"Delivery follows work units",
+		"forecast authored changed lines (additions plus deletions, generated files excluded) from the task list",
+		"keep a running count from work-unit commits",
+		"`ask-on-risk` (default), `auto-chain`, `single-pr`, or `exception-ok`",
+		"apply the chosen strategy before the next commit",
+		"`ask-on-risk` asks once for the chain strategy, `stacked-to-main` or `feature-branch-chain`",
+		"`auto-chain` asks only for a missing chain strategy and slices automatically",
+		"Cache both choices, and record slice boundaries",
+		"Resolve the `work-unit-commits` and `chained-pr` skills by registry name",
+		"never hardcode their paths",
+		"The delivery budget below reads the accumulated branch, not this per-task heuristic",
+	]);
+	const docs = read("docs/readme-reference.md");
+	containsAll(docs, [
+		"Every task closes with at least one work-unit commit on the feature branch (branch first when on the default branch)",
+		"the feature document records the commit identity as evidence",
+		"The native review candidate is a work-unit commit or a PR slice, never a TODO checkbox and never the accumulated feature branch",
+		"**Delivery:**",
+		"Close task with a work-unit commit",
+		"RDD enabled at work-unit commit boundary",
+		"Running authored lines over 400",
+		"Apply delivery strategy: chained PR slice",
+	]);
+});
+
 test("user documentation shows recovery and candidate-level consent without claiming model proof", () => {
 	const docs = read("docs/readme-reference.md");
 	containsAll(docs, [
@@ -162,6 +204,63 @@ test("ODD forwards configured TDD without equating test presence with enablement
 	assert.doesNotMatch(wrapper, /If tests exist, use strict TDD/);
 });
 
+test("mandatory delegation triggers are behavioral in the lazy canonical port and the always-on ODD step", () => {
+	for (const clause of [
+		"These triggers are mandatory, not advisory.",
+		"stop and delegate through the runtime's subagent mechanism before continuing",
+		"executing past a fired trigger inline is a routing defect even if the work succeeds",
+		"**Mapping trigger",
+		"**Writer trigger",
+		"**Preparation trigger:**",
+		"**Long-session backstop",
+		"pause and delegate the next bounded unit of work",
+		"**Route declaration:**",
+		"record the chosen route per task",
+		"so skipped delegation is observable instead of silent",
+		"These triggers never select SDD and never create SDD artifacts",
+	]) {
+		assert.ok(delegation.includes(clause), `lazy canonical port is missing mandatory delegation clause: ${clause}`);
+	}
+	assert.ok(
+		wrapper.includes("honoring its mandatory delegation triggers"),
+		"the always-on ODD step 6 must honor its mandatory delegation triggers",
+	);
+	assert.ok(
+		wrapper.includes("executing past a fired trigger inline is a routing defect"),
+		"the always-on ODD protocol must state that skipping a fired trigger is a routing defect",
+	);
+});
+
+test("core and lazy canonical trigger lists agree in numbering and semantics", () => {
+	for (const entry of [
+		"1. **4-file rule**",
+		"2. **Multi-file write rule**",
+		"3. **Incident rule**",
+		"4. **Long-session rule**",
+		"5. **Verification rule**",
+	]) {
+		assert.ok(core.includes(entry), `always-on core trigger list is missing: ${entry}`);
+	}
+	for (const entry of [
+		"1. **Mapping trigger (4-file rule):**",
+		"2. **Writer trigger (Multi-file write rule):**",
+		"3. **Incident rule:**",
+		"4. **Long-session backstop (Long-session rule):**",
+		"5. **Verification rule**",
+	]) {
+		assert.ok(delegation.includes(entry), `lazy canonical trigger list is missing: ${entry}`);
+	}
+	for (const stale of [
+		"**Bounded read rule**",
+		"**Write rule**",
+		"**Context rule**",
+		"**Per-action rule**",
+		"**Optional SDD rule**",
+	]) {
+		assert.ok(!delegation.includes(stale), `reconciled canonical list retains stale trigger framing: ${stale}`);
+	}
+});
+
 test("ODD protocol is always-on in the rendered system prompt and runs by default", () => {
 	const orderedClauses = [
 		"Default workflow: Organic Driven Development (MANDATORY)",