gentle-pi 4.2.0 → 4.3.0

package/tests/odd-integration.test.ts

@@ -48,7 +48,11 @@ test("applicability, fallback and honest evidence flow through ODD actors", () =
 test("retired SDD routes and assets are absent while ODD entry and generic workers remain", () => {
 	const core = read("assets/orchestrator.md");
 	const delegation = readDelegationDetail();
-	assert.match(core, /ODD \(Default Workflow, harness section above\) is mandatory on every request/);
+	// S11 T3: deduplicated. The core's "ODD (Default Workflow, harness section
+	// above) is mandatory on every request" restated the harness; the mandatory
+	// ODD entry is stated once, in the harness that renders above the core.
+	assert.match(read("extensions/gentle-ai.ts"), /Default workflow: Organic Driven Development \(MANDATORY\)\nOrganic Driven Development \(ODD\) is the predefined workflow of this orchestrator\. Every request enters it/);
+	assert.doesNotMatch(core, /ODD \(Default Workflow, harness section above\)/);
 	assert.match(delegation, /generic writer chain is unavailable/);
 	for (const path of [
 		"assets/agents/gentle-ai-worker.md",

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

@@ -1,46 +1,36 @@
 import assert from "node:assert/strict";
-import { existsSync, readFileSync } from "node:fs";
+import { 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";
+import { __testing } from "../extensions/gentle-ai.ts";
+import { PI_RUNTIME_IDENTITY, ROUTING_REQUIRED_SINCE_MINOR, verifyProviderContractBundleTree } from "../lib/provider-contract-bundle.ts";
+import { PROVIDER_CONTRACT_LOCK_FILE, PROVIDER_CONTRACT_MIRROR_ROOT } from "../scripts/mirror-provider-contract.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.
+// gentle-ai renders the always-on ODD routing block for Pi
+// (`internal/components/agentguidance/routing.go`) and publishes it in the
+// provider contract bundle as `routing/pi.md` (contract 1.4.0). The mirrored
+// bundle (`contracts/review-provider-contract-mirror/`, refreshed with
+// `scripts/mirror-provider-contract.mjs`) is the canonical reference: the
+// harness ODD steps are rendered from it, and this ratchet fails when a
+// mandatory-delegation clause is dropped either from the canonical block or
+// from a Pi surface that restates it (the `assets/orchestrator*.md` modules
+// stay Pi's own and keep their anchors).
 // ---------------------------------------------------------------------------
 
 const REPO_ROOT = join(import.meta.dirname, "..");
-const FIXTURE_PATH = join(REPO_ROOT, ...ODD_ROUTING_FIXTURE_RELATIVE.split("/"));
+const MIRROR_ROOT = join(REPO_ROOT, ...PROVIDER_CONTRACT_MIRROR_ROOT.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.
+// A canonical change that drops `canonical` is caught here once the bundle is re-mirrored
+// because the mirrored routing block no longer carries it.
 interface RoutingAnchor {
 	label: string;
 	canonical: string;
@@ -49,23 +39,33 @@ interface RoutingAnchor {
 
 const DELEGATION = "assets/orchestrator-delegation.md";
 const CORE = "assets/orchestrator.md";
-const EXTENSION = "extensions/gentle-ai.ts";
+// The harness prompt rendered by extensions/gentle-ai.ts, including the ODD
+// steps it takes from the mirrored routing/pi.md.
+const EXTENSION = "rendered harness prompt";
 
 const ANCHORS: readonly RoutingAnchor[] = [
 	{
-		label: "mandatory delegation triggers heading",
-		canonical: "### Mandatory Delegation Triggers",
+		// S9 canon change (gentle-ai 87a3b2eb): the heading dropped "Mandatory";
+		// a trigger is mandatory only once its condition truly holds.
+		label: "delegation triggers heading",
+		canonical: "### Delegation Triggers",
 		mirrors: [
-			{ surface: DELEGATION, includes: "#### Mandatory Delegation Triggers" },
-			{ surface: CORE, includes: "Mandatory Delegation Triggers" },
+			{ surface: DELEGATION, includes: "#### Delegation Triggers" },
+			// Writer-rule fix: the core names them "Delegation Triggers" and says
+			// each holds only when its condition truly holds; the lazy port keeps
+			// the canonical heading.
+			{ surface: CORE, includes: "Delegation Triggers — each mechanism turns on only when its own trigger condition truly holds" },
 		],
 	},
 	{
-		label: "triggers are mandatory, not advisory",
-		canonical: "These triggers are mandatory, not advisory.",
+		// S9 canon change: "These triggers are mandatory, not advisory." read as a
+		// default to delegate (L8); a trigger now holds only when its condition
+		// truly holds, none by default, inline when in doubt.
+		label: "triggers hold only when their condition truly holds",
+		canonical: "Each trigger holds only when its condition truly holds, and only then is it mandatory, not advisory; no trigger holds by default, and when in doubt work inline.",
 		mirrors: [
-			{ surface: DELEGATION, includes: "These triggers are mandatory, not advisory." },
-			{ surface: EXTENSION, includes: "These triggers are mandatory, not advisory" },
+			{ surface: DELEGATION, includes: "Each trigger holds only when its condition truly holds, and only then is it mandatory, not advisory; no trigger holds by default, and when in doubt work inline." },
+			{ surface: EXTENSION, includes: "No trigger holds by default and, when in doubt, work inline" },
 		],
 	},
 	{
@@ -94,17 +94,64 @@ const ANCHORS: readonly RoutingAnchor[] = [
 		],
 	},
 	{
-		label: "writer trigger fires only for a large task, never by file count",
-		canonical: "**Writer trigger:** a large task delegates one bounded writer per task; file count never fires this trigger",
-		// Gentle Shell intentionally leads the canon here (gentle-shell#1731): the
-		// writer fires on named reasons (parallelism, context), never on size
-		// alone; T24 turned the price-ratio reason off. The canon port is G1 in
-		// odd/tasks/delegate-for-reason.md.
+		// S9 canon change: exploration never reads files an inline write reads anyway.
+		label: "never explore to read files an inline write reads anyway",
+		canonical: "Never explore to read files you will read anyway before writing inline.",
+		mirrors: [
+			{ surface: DELEGATION, includes: "Never explore to read files you will read anyway before writing inline." },
+			{ surface: CORE, includes: "never for reading before an inline write" },
+		],
+	},
+	{
+		label: "writer trigger fires only for a named reason, never by size or file count",
+		// S9 canon change (gentle-ai 87a3b2eb): the canon caught up with Gentle
+		// Shell (gentle-shell#1731): the writer fires on named reasons
+		// (parallelism, context), never on size alone or a price ratio.
+		canonical: "**Writer trigger:** a writer is delegated only for a named reason, one bounded writer per unit",
 		mirrors: [
 			{ surface: DELEGATION, includes: "**Writer trigger (Writer rule):** a large task alone never delegates, and file count never fires this trigger" },
 			{ surface: CORE, includes: "**Writer rule** — never by file count or a large task alone" },
 		],
 	},
+	{
+		// S9 canon change: a writer unit is one independent behavior with its
+		// code, tests, and docs together, never split across writers.
+		label: "a writer unit is one independent behavior",
+		canonical: "A unit is one independent piece of behavior with its code, tests, and docs together",
+		mirrors: [
+			{ surface: DELEGATION, includes: "A unit is one independent piece of behavior with its code, tests, and docs together" },
+			{ surface: CORE, includes: "Tests, docs, and code of the same behavior are one unit, never separate writers" },
+		],
+	},
+	{
+		// S9 canon change: a unit qualifies only with several minutes of work,
+		// because a subagent spends one to two minutes reading before it writes.
+		label: "a writer unit needs several minutes of work",
+		canonical: "several files or roughly 100+ changed lines",
+		mirrors: [
+			{ surface: DELEGATION, includes: "several files or ~100+ changed lines; a subagent spends 1-2 minutes reading before it writes" },
+			{ surface: CORE, includes: "several files or roughly 100+ changed lines" },
+		],
+	},
+	{
+		// S9 canon change (gentle-ai c3763aa7, C3): whoever writes reuses the
+		// existing shared-state helper and keeps its invariants.
+		label: "writers reuse the existing shared-state function",
+		canonical: "reuses the existing function for shared state",
+		mirrors: [
+			{ surface: DELEGATION, includes: "reuses the existing function for shared state and keeps its invariants (ordering, uniqueness, validation, normalization)" },
+		],
+	},
+	{
+		// S9 canon change (gentle-ai c3763aa7, C8): PRESERVE diffs each existing
+		// command that shares the changed code against the previous code.
+		label: "differential check against the previous code",
+		canonical: "run a differential check",
+		mirrors: [
+			{ surface: DELEGATION, includes: "**Differential check (PRESERVE):**" },
+			{ surface: EXTENSION, includes: "run a differential check" },
+		],
+	},
 	{
 		label: "task size decides the route (gentle-shell#1494)",
 		canonical: "### Task Size",
@@ -114,11 +161,14 @@ const ANCHORS: readonly RoutingAnchor[] = [
 		],
 	},
 	{
-		label: "verification trigger is reserved for high risk",
-		canonical: "**Verification trigger:** a high-risk change gets an independent verifier",
+		label: "verification trigger is reserved for a named high-risk item",
+		// S9 canon change (gentle-ai 6b9a71ef): only a change whose Risk line
+		// names a high-risk item gets the independent verifier.
+		canonical: "**Verification trigger:** only a change whose Risk line names a high-risk item gets an independent verifier",
 		mirrors: [
-			{ surface: CORE, includes: "**Verification rule** — high risk → independent `gentle-ai-verify`" },
-			{ surface: DELEGATION, includes: "a high-risk change (Task Size) gets an independent `gentle-ai-verify` run" },
+			// Verification by named risk: the core row names the escalate-only verifier.
+			{ surface: CORE, includes: "**Verification rule** — only a named high-risk item (assess `escalate`) → independent `gentle-ai-verify`" },
+			{ surface: DELEGATION, includes: "only a change whose Risk line names a high-risk item (Task Size, assess `escalate`) gets an independent `gentle-ai-verify` run" },
 		],
 	},
 	{
@@ -138,10 +188,12 @@ const ANCHORS: readonly RoutingAnchor[] = [
 		label: "long-session backstop",
 		canonical: "**Long-session backstop:**",
 		// Gentle Shell intentionally leads the canon here: a parent-context token
-		// backstop replaces the tool-call count (tracked by gentle-ai#5139).
+		// backstop replaces the tool-call count (tracked by gentle-ai#5139), and the
+		// runtime measures it and signals it instead of the canon's advisory ~150k
+		// estimate (harness roadmap R1), so the Pi anchor names the runtime signal.
 		mirrors: [
-			{ surface: DELEGATION, includes: "**Context backstop:** when the parent context passes ~150k tokens" },
-			{ surface: CORE, includes: "**Context backstop** — parent context past ~150k tokens" },
+			{ surface: DELEGATION, includes: "**Context backstop:** when the runtime signals it" },
+			{ surface: CORE, includes: "**Context backstop** — when the runtime signals it" },
 		],
 	},
 	{
@@ -173,58 +225,52 @@ const ANCHORS: readonly RoutingAnchor[] = [
 		],
 	},
 	{
-		label: "ODD step 6 honors its mandatory delegation triggers",
-		canonical: "honoring its mandatory delegation triggers",
-		mirrors: [{ surface: EXTENSION, includes: "honoring its mandatory delegation triggers" }],
+		// S9 canon change: step 6 honors its triggers only when their conditions truly hold.
+		label: "ODD step 6 honors its delegation triggers when their conditions hold",
+		canonical: "honoring its delegation triggers when their conditions truly hold",
+		mirrors: [{ surface: EXTENSION, includes: "honoring its delegation triggers when their conditions truly hold" }],
 	},
 ];
 
 // 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.
+// rows, so they are mirror-only and not anchors of the canonical routing block.
 const CORE_ONLY_TRIGGERS = [
 	"**Incident rule** — diagnose wrong cwd/worktree/git/tooling incidents separately",
-	"**Verification rule** — high risk → independent `gentle-ai-verify`",
+	"**Verification rule** — only a named high-risk item (assess `escalate`) → independent `gentle-ai-verify`",
 ] 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;
+// The verified mirrored routing/pi.md: the bundle tree must pass the strict
+// decoder, so a hand edit to the canonical block fails here as well as in
+// `pnpm run check:provider-contract`.
+function canonicalRoutingBlock(): string {
+	const lock = JSON.parse(readFileSync(join(MIRROR_ROOT, PROVIDER_CONTRACT_LOCK_FILE), "utf8")) as { contract_semver: string };
+	const bundle = verifyProviderContractBundleTree(join(MIRROR_ROOT, `v${lock.contract_semver}`, "bundle"));
+	const block = bundle.routing.get(PI_RUNTIME_IDENTITY);
+	assert.ok(block !== undefined, `the mirrored provider contract ${bundle.contractSemver} carries no routing/${PI_RUNTIME_IDENTITY}.md`);
+	return block;
 }
 
 // ---------------------------------------------------------------------------
-// 1 — Fixture provenance readback
+// 1 — The canonical reference is the verified mirrored bundle
 // ---------------------------------------------------------------------------
 
-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");
+test("the canonical routing reference is the verified mirrored routing/pi.md (contract >= 1.4.0)", () => {
+	const lock = JSON.parse(readFileSync(join(MIRROR_ROOT, PROVIDER_CONTRACT_LOCK_FILE), "utf8")) as { contract_semver: string; entries: Record<string, string> };
+	const [major, minor] = lock.contract_semver.split(".").map(Number);
+	assert.ok(major === 1 && (minor ?? 0) >= ROUTING_REQUIRED_SINCE_MINOR, `mirrored contract ${lock.contract_semver} predates routing`);
+	assert.match(lock.entries[`routing/${PI_RUNTIME_IDENTITY}.md`] ?? "", /^[0-9a-f]{64}$/);
+	assert.ok(canonicalRoutingBlock().startsWith("## Implementation Routing\n"));
 });
 
 // ---------------------------------------------------------------------------
-// 2 — Canonical fixture carries every mandatory anchor
+// 2 — The canonical block carries every mandatory anchor
 // ---------------------------------------------------------------------------
 
-test("the canonical fixture carries every mandatory-delegation anchor", () => {
-	const body = fixtureBody();
+test("the canonical routing block carries every mandatory-delegation anchor", () => {
+	const body = canonicalRoutingBlock();
 	for (const anchor of ANCHORS) {
-		assert.ok(body.includes(anchor.canonical), `canonical fixture dropped anchor: ${anchor.label}`);
+		assert.ok(body.includes(anchor.canonical), `canonical routing block dropped anchor: ${anchor.label}`);
 	}
 });
 
@@ -236,7 +282,7 @@ 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),
+		[EXTENSION]: __testing.buildGentlePrompt("gentleman"),
 	};
 	for (const anchor of ANCHORS) {
 		for (const mirror of anchor.mirrors) {
@@ -256,84 +302,3 @@ test("the always-on core prompt carries the condensed incident and verification
 		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;
-		},
-	);
-});