gentle-pi 2.7.0 → 3.1.0

package/tests/gentle-shell.test.ts

@@ -4,7 +4,7 @@ import { mkdirSync, mkdtempSync, realpathSync, renameSync, rmSync, writeFileSync
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import test from "node:test";
-import { initTheme, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+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 { CHANGE_STATUS } from "../lib/shell-changes.ts";
@@ -63,12 +63,25 @@ interface ShortcutRegistration {
 type MessageRenderer = (message: { customType: string; content: unknown }, options: { expanded: boolean }, theme: unknown) => { render(width: number): string[] };
 const renderers = new Map<string, MessageRenderer>();
 
-function fakePi(script: GitScript[] = [{ numstat: "", porcelain: "" }]) {
+const FAKE_SOURCE_INFO: SourceInfo = { path: "extensions/gentle-shell.ts", source: "gentle-shell", scope: "project", origin: "top-level" };
+
+const DEFAULT_COMMANDS: SlashCommandInfo[] = [
+	{ name: "gentle:models", description: "Configure models", source: "extension", sourceInfo: FAKE_SOURCE_INFO },
+	{ name: "gentle:changes", description: "Browse changes", source: "extension", sourceInfo: FAKE_SOURCE_INFO },
+	{ name: "gentle:status", description: "Show Gentle AI status", source: "extension", sourceInfo: FAKE_SOURCE_INFO },
+	{ name: "skill-registry:refresh", description: "Regenerate the skill registry", source: "extension", sourceInfo: FAKE_SOURCE_INFO },
+	{ name: "gentle:commands", description: "Open the command palette", source: "extension", sourceInfo: FAKE_SOURCE_INFO },
+	{ name: "gentle:not-in-catalog", description: "Not a curated command", source: "extension", sourceInfo: FAKE_SOURCE_INFO },
+	{ name: "skill:foo", description: "A skill", source: "skill", sourceInfo: FAKE_SOURCE_INFO },
+];
+
+function fakePi(script: GitScript[] = [{ numstat: "", porcelain: "" }], commandsList: SlashCommandInfo[] = DEFAULT_COMMANDS) {
 	const handlers = new Map<string, Array<(event: unknown, ctx: ExtensionContext) => unknown>>();
 	const commands = new Map<string, CommandRegistration>();
 	const shortcuts = new Map<string, ShortcutRegistration>();
 	const git: string[][] = [];
 	let entries: unknown[] = [];
+	const sentMessages: Array<{ content: string; options?: { deliverAs?: "steer" | "followUp"; expandPromptTemplates?: boolean } }> = [];
 	const tools = new Map<string, { renderShell?: string; execute(id: string, params: unknown, signal: undefined, update: undefined, ctx: ExtensionContext): Promise<unknown> }>();
 	const listeners = new Map<string, (data: unknown) => void>();
 	let round = 0;
@@ -94,6 +107,12 @@ function fakePi(script: GitScript[] = [{ numstat: "", porcelain: "" }]) {
 		getThinkingLevel() {
 			return "medium";
 		},
+		getCommands() {
+			return commandsList;
+		},
+		sendUserMessage(content: string, options?: { deliverAs?: "steer" | "followUp"; expandPromptTemplates?: boolean }) {
+			sentMessages.push({ content, options });
+		},
 		async exec(_command: string, args: string[]) {
 			git.push(args);
 			if (args.includes("worktree")) return { stdout: "worktree /repo\0branch refs/heads/main\0\0", stderr: "", code: 0, killed: false };
@@ -102,7 +121,7 @@ function fakePi(script: GitScript[] = [{ numstat: "", porcelain: "" }]) {
 			return { stdout: isNumstat ? step.numstat : step.porcelain, stderr: "", code: 0, killed: false };
 		},
 	} as unknown as ExtensionAPI;
-	return { pi, handlers, git, commands, shortcuts, tools };
+	return { pi, handlers, git, commands, shortcuts, tools, sentMessages };
 }
 
 async function fire(handlers: Map<string, Array<(event: unknown, ctx: ExtensionContext) => unknown>>, event: string, ctx: ExtensionContext): Promise<void> {
@@ -149,11 +168,15 @@ function fakeContext(options: { hasUI?: boolean; entries?: unknown[]; oauth?: bo
 			setWorkingVisible(visible: boolean) {
 				ui.workingVisible = visible;
 			},
-			custom(factory: (tui: unknown, theme: unknown, keybindings: unknown, done: (value: null) => void) => { render(width: number): string[]; handleInput(data: string): void }) {
+			// Generic over the result type: real callers resolve `custom` with
+			// whatever their `done` callback is given (see ExtensionUIContext.custom
+			// in pi-coding-agent), not always null. `closeOverlay` stays a
+			// null-resolving escape hatch for tests that only need to end the wait.
+			custom<T>(factory: (tui: unknown, theme: unknown, keybindings: unknown, done: (value: T) => void) => { render(width: number): string[]; handleInput(data: string): void }) {
 				ui.overlay = factory;
-				return new Promise<null>((resolve) => {
+				return new Promise<T | null>((resolve) => {
 					ui.closeOverlay = () => resolve(null);
-					ui.overlayView = factory(fakeTui, plainTheme, fakeKeybindings, () => resolve(null));
+					ui.overlayView = factory(fakeTui, plainTheme, fakeKeybindings, (value: T) => resolve(value));
 					resolveOverlay();
 				});
 			},
@@ -382,15 +405,41 @@ test("gentleShell shows working while the agent runs and queued when messages wa
 	const editor = installedPrompt(ctx, ui, handlers);
 
 	for (const handler of handlers.get("agent_start") ?? []) handler({}, ctx);
-	assert.match(stripAnsi(editor.render(60)[0]), /^╭─ [✿❀❁✾] working ─+╮$/);
+	assert.match(stripAnsi(editor.render(60)[0]), /^╭─ ✿ working… ─+╮$/);
 	pending.value = true;
 	assert.match(stripAnsi(editor.render(60)[0]), /^╭─ [✿❀❁✾] queued ─+╮$/);
 	for (const handler of handlers.get("agent_end") ?? []) handler({}, ctx);
+	assert.match(stripAnsi(editor.render(60)[0]), /queued/, "low-level run end is not settled");
 	pending.value = false;
+	for (const handler of handlers.get("agent_settled") ?? []) handler({}, ctx);
 	assert.match(stripAnsi(editor.render(60)[0]), /^╭─ ✿ ─+╮$/);
 	editor.dispose();
 });
 
+test("prompt uses the compact banner cadence and releases its unref timer at settlement", (t) => {
+	const delays: number[] = [];
+	let active = 0;
+	let unrefs = 0;
+	t.mock.method(globalThis, "setInterval", (_callback: () => void, delay: number) => {
+		delays.push(delay);
+		active++;
+		return { unref() { unrefs++; } };
+	});
+	t.mock.method(globalThis, "clearInterval", () => { active--; });
+	const { pi, handlers } = fakePi();
+	gentleShell(pi, {});
+	const { ctx, ui } = fakeContext();
+	const editor = installedPrompt(ctx, ui, handlers);
+	assert.equal(active, 0);
+	for (const handler of handlers.get("agent_start") ?? []) handler({}, ctx);
+	assert.deepEqual(delays, [80]);
+	assert.equal(unrefs, 1);
+	for (const handler of handlers.get("agent_settled") ?? []) handler({}, ctx);
+	assert.equal(active, 0);
+	editor.dispose();
+	assert.equal(active, 0);
+});
+
 test("gentleShell leaves an editor another extension already installed", () => {
 	const { pi, handlers } = fakePi();
 	gentleShell(pi, {});
@@ -398,6 +447,26 @@ test("gentleShell leaves an editor another extension already installed", () => {
 	const { ctx, ui } = fakeContext({ editorFactory: theirs });
 	for (const handler of handlers.get("session_start") ?? []) handler({}, ctx);
 	assert.equal(ui.editorFactory, theirs);
+	assert.notEqual(ui.workingVisible, false, "a custom owner still needs native working feedback");
+});
+
+test("Gentle replaces its retained factory on reload so new lifecycle handlers own the prompt", () => {
+	const first = fakePi();
+	gentleShell(first.pi, {});
+	const { ctx, ui } = fakeContext();
+	const oldEditor = installedPrompt(ctx, ui, first.handlers);
+	const previousFactory = ui.editorFactory;
+	const next = fakePi();
+	gentleShell(next.pi, {});
+	const editor = installedPrompt(ctx, ui, next.handlers);
+	try {
+		assert.notEqual(ui.editorFactory, previousFactory);
+		for (const handler of next.handlers.get("agent_start") ?? []) handler({}, ctx);
+		assert.match(stripAnsi(editor.render(60)[0]), /working/);
+	} finally {
+		oldEditor.dispose();
+		editor.dispose();
+	}
 });
 
 const footerData = { getGitBranch: () => "main", getExtensionStatuses: () => new Map(), getAvailableProviderCount: () => 1, onBranchChange: () => () => {} };
@@ -428,6 +497,13 @@ test("captured changes update the widget and bar without repository scans", asyn
  const factory=ui.widgets.get("gentle-shell-changes") as any;
  assert.match(factory(fakeTui,plainTheme).render(140)[0],/1 file · \+2 −0/);
  assert.match(renderFooter(ui),/main ±1/);
+ const rail = sidebarState(fakeTui as unknown as TUI).parts.get("footer")!;
+ const digest = rail.digest!();
+ assert.match(rail.render(46).join("\n"), /1 file · \+2 −0/);
+ sessionChange(ctx,"b","/repo","lib/b.ts","one\ntwo\n","one\ntwo\nthree\n");
+ await fire(handlers,"agent_end",ctx);
+ assert.notEqual(rail.digest!(), digest, "same-count line changes invalidate the unified Status");
+ assert.match(rail.render(46).join("\n"), /1 file · \+3 −0/);
  assert.equal(git.length,0);
  await fire(handlers,"session_shutdown",ctx);
 });
@@ -619,7 +695,7 @@ test("gentleShell binds the changes shortcut to the same handler as the command"
 
 	const silent = fakePi();
 	gentleShell(silent.pi, { GENTLE_PI_SHELL_CHANGES_KEY: "off" });
-	assert.equal(silent.shortcuts.size, 0);
+	assert.equal(silent.shortcuts.has("alt+g"), false, "the changes shortcut must not register when disabled");
 });
 
 test("external edits do not pollute Changes or trigger background Git scans", async () => {
@@ -756,3 +832,120 @@ test("gentleShell keeps a dev-binary override visible above the editor for the w
 
 	assert.equal(devBinaryCard({ state: "invalid", reason: "binary missing" }).tone, "error");
 });
+
+test("gentle:commands registers alt+k by default", () => {
+	const { pi, shortcuts } = fakePi();
+	gentleShell(pi, {});
+	assert.ok(shortcuts.has("alt+k"));
+});
+
+test("gentle:commands honors GENTLE_PI_COMMANDS_KEY", () => {
+	const { pi, shortcuts } = fakePi();
+	gentleShell(pi, { GENTLE_PI_COMMANDS_KEY: "ctrl+p" });
+	assert.ok(shortcuts.has("ctrl+p"));
+	assert.equal(shortcuts.has("alt+k"), false);
+});
+
+test("GENTLE_PI_COMMANDS_KEY=off registers no command-palette shortcut", () => {
+	const { pi, shortcuts } = fakePi();
+	gentleShell(pi, { GENTLE_PI_COMMANDS_KEY: "off" });
+	assert.equal(shortcuts.has("alt+k"), false);
+	assert.ok(shortcuts.has("alt+g"), "the unrelated changes shortcut still registers");
+});
+
+test("/gentle:commands shows only curated, registered commands, grouped, by their labels", async () => {
+	const { pi, commands } = fakePi();
+	gentleShell(pi, {});
+	const { ctx, ui, overlayReady } = fakeContext();
+	const opened = commands.get("gentle:commands")!.handler("", ctx);
+	await overlayReady;
+	const lines = ui.overlayView!.render(100);
+	const rendered = lines.join("\n");
+	assert.match(rendered, /Configuration/);
+	assert.match(rendered, /Session/);
+	assert.match(rendered, /Diagnostics/);
+	assert.match(rendered, /Skills/);
+	assert.doesNotMatch(rendered, /\bSDD\b/, "the SDD group has no registered commands and must not appear");
+	assert.match(rendered, /Assign models and effort/);
+	assert.match(rendered, /Browse captured changes/);
+	assert.match(rendered, /Gentle AI status/);
+	assert.match(rendered, /Refresh skill registry/);
+	assert.doesNotMatch(rendered, /gentle:models|gentle:changes|gentle:status|skill-registry:refresh/, "raw command names must not leak; only labels are shown");
+	assert.doesNotMatch(rendered, /gentle:not-in-catalog/);
+	assert.doesNotMatch(rendered, /skill:foo/);
+	const changesLine = lines.find((line) => line.includes("Browse captured changes"));
+	assert.match(changesLine ?? "", /alt\+g/, "expected the configured alt+g shortcut hint next to Browse captured changes");
+	ui.overlayView!.handleInput("\x1b");
+	await opened;
+});
+
+test("selecting a command from the palette by its label sends the underlying command as a slash message", async () => {
+	const { pi, commands, sentMessages } = fakePi();
+	gentleShell(pi, {});
+	const { ctx, ui, overlayReady } = fakeContext();
+	const opened = commands.get("gentle:commands")!.handler("", ctx);
+	await overlayReady;
+	// "mod" only matches the "Assign models and effort" label (it contains
+	// "mod" via "models"); nothing else in the fixture does.
+	for (const ch of "mod") ui.overlayView!.handleInput(ch);
+	assert.match(ui.overlayView!.render(100).join("\n"), /Assign models and effort/);
+	ui.overlayView!.handleInput("\r");
+	await opened;
+	assert.deepEqual(sentMessages, [{ content: "/gentle:models", options: { expandPromptTemplates: true } }]);
+});
+
+test("escaping the palette sends no message", async () => {
+	const { pi, commands, sentMessages } = fakePi();
+	gentleShell(pi, {});
+	const { ctx, ui, overlayReady } = fakeContext();
+	const opened = commands.get("gentle:commands")!.handler("", ctx);
+	await overlayReady;
+	ui.overlayView!.handleInput("\x1b");
+	await opened;
+	assert.deepEqual(sentMessages, []);
+});
+
+test("/gentle:commands notifies when nothing in the catalog is registered", async () => {
+	const { pi, commands } = fakePi(undefined, [
+		{ name: "skill:foo", description: "A skill", source: "skill", sourceInfo: FAKE_SOURCE_INFO },
+		{ name: "gentle:not-in-catalog", description: "Not curated", source: "extension", sourceInfo: FAKE_SOURCE_INFO },
+	]);
+	gentleShell(pi, {});
+	const { ctx, ui } = fakeContext();
+	await commands.get("gentle:commands")!.handler("", ctx);
+	assert.match(ui.notices.join("\n"), /No Gentle commands are registered\./);
+	assert.equal(ui.overlay, undefined);
+});
+
+test("/gentle:commands does nothing in a headless context", async () => {
+	const { pi, commands, sentMessages } = fakePi();
+	gentleShell(pi, {});
+	const { ctx, ui } = fakeContext({ hasUI: false });
+	await commands.get("gentle:commands")!.handler("", ctx);
+	assert.equal(ui.overlay, undefined);
+	assert.deepEqual(sentMessages, []);
+});
+
+test("the alt+k shortcut opens the same command palette as the command", async () => {
+	const { pi, shortcuts } = fakePi();
+	gentleShell(pi, {});
+	const { ctx, ui, overlayReady } = fakeContext();
+	const shortcut = shortcuts.get("alt+k");
+	assert.ok(shortcut, "alt+k not registered");
+	const opened = shortcut.handler(ctx);
+	await overlayReady;
+	assert.match(ui.overlayView!.render(100).join("\n"), /Assign models and effort/);
+	ui.overlayView!.handleInput("\x1b");
+	await opened;
+});
+
+test("resolving the overlay through closeOverlay sends nothing and does not throw", async () => {
+	const { pi, commands, sentMessages } = fakePi();
+	gentleShell(pi, {});
+	const { ctx, ui, overlayReady } = fakeContext();
+	const opened = commands.get("gentle:commands")!.handler("", ctx);
+	await overlayReady;
+	ui.closeOverlay?.();
+	await opened;
+	assert.deepEqual(sentMessages, []);
+});

package/tests/native-choice-list.test.ts

@@ -85,6 +85,19 @@ test("native choice list presents one hovered wrapped option without changing se
 	assert.doesNotMatch(list.render(56).join("\n"), new RegExp(hoverBackground.replace(/[\[\]]/g, "\\$&")));
 });
 
+test("native choice list refreshes existing item content without changing selection", () => {
+	const items = [
+		{ id: "first", label: "First", description: "Initial detail." },
+		{ id: "second", label: "Second", description: "Second detail." },
+	];
+	const list = new NativeChoiceList(items, theme);
+	list.setSelectedIndex(1);
+	items[1]!.description = "Updated detail.";
+	list.refreshItems();
+	assert.equal(list.getSelectedItem()?.id, "second");
+	assert.match(stripTerminalSequences(list.render(40).join("\n")), /Updated detail\./);
+});
+
 test("native choice list ignores Kitty key releases", () => {
 	const list = new NativeChoiceList(
 		[{ id: "first", label: "First" }, { id: "second", label: "Second" }],

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

@@ -246,11 +246,40 @@ test("2.9.1 repeats 2.9.0 because the negotiated lane Pi consumes is unchanged",
 	assert.deepEqual(contract, NATIVE_CLI_CONTRACTS["2.9.0"] as Record<string, boolean>);
 });
 
+test("3.0.0 repeats 2.9.1 because the negotiated lane Pi consumes is unchanged", () => {
+	// v3.0.0 shipped ODD as the orchestrator's mandatory default protocol and
+	// integrated the simplified SDD workflow into it (gentle-ai #4642, #4644),
+	// with the provider contract byte-frozen at 1.2.0. Diffing
+	// contracts/review-integration/v2 and contracts/review-provider-contract
+	// between the v2.9.1 and v3.0.0 tags in the gentle-ai source tree showed
+	// zero byte changes, so this row repeats 2.9.1. riskEvidence and hint
+	// remain dark because neither is proven to reach Pi's negotiated START
+	// path.
+	const contract = NATIVE_CLI_CONTRACTS["3.0.0"] as Record<string, boolean>;
+	assert.equal(contract.riskEvidence, false);
+	assert.equal(contract.hint, false);
+	assert.deepEqual(contract, NATIVE_CLI_CONTRACTS["2.9.1"] as Record<string, boolean>);
+});
+
+test("3.0.1 repeats 3.0.0 because the negotiated lane Pi consumes is unchanged", () => {
+	// v3.0.1 moved the Go module path to
+	// github.com/gentleman-programming/gentle-ai/v3 with no contract change
+	// (gentle-ai #4683). Diffing contracts/review-integration/v2 and
+	// contracts/review-provider-contract between the v3.0.0 and v3.0.1 tags
+	// in the gentle-ai source tree showed zero byte changes, so this row
+	// repeats 3.0.0. riskEvidence and hint remain dark because neither is
+	// proven to reach Pi's negotiated START path.
+	const contract = NATIVE_CLI_CONTRACTS["3.0.1"] as Record<string, boolean>;
+	assert.equal(contract.riskEvidence, false);
+	assert.equal(contract.hint, false);
+	assert.deepEqual(contract, NATIVE_CLI_CONTRACTS["3.0.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"]);
+	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"]);
 });

package/tests/native-review-cli.test.ts

@@ -1023,36 +1023,3 @@ test("all twelve native actions retain their exact tokens without prose routing"
 		assert.equal(decodeNativeSddStatusV2(status, { workspaceRoot: "/repo" }).nextRecommended, nextRecommended);
 	}
 });
-
-
-test("compact SDD bracket transports exact selection and remediation binding", async () => {
-	const revision = `sha256:${"a".repeat(64)}`;
-	const queued = queuedAdapter([{ stdout: JSON.stringify({ state: "proceed", token: revision }) }, { stdout: '{"state":"complete"}' }]);
-	const cli = client(queued.adapter);
-	const request = { workspaceRoot: "/repo", changeName: "fix", requestId: "acquire-one", workUnit: "correction", evidenceGoal: "Observed correction", maxAttempts: 1, maxChangedLines: 300, remediatesEvidenceRevision: revision };
-	assert.deepEqual(await cli.sddAttemptAcquire(request), { state: "proceed", token: revision });
-	assert.deepEqual(queued.calls[0].arguments, ["sdd-attempt", "acquire", "--cwd", "/repo", "--change", "fix", "--request-id", "acquire-one", "--work-unit", "correction", "--evidence-goal", "Observed correction", "--max-attempts", "1", "--max-changed-lines", "300", "--remediates-evidence-revision", revision]);
-	assert.deepEqual(await cli.sddAttemptSettle({ workspaceRoot: "/repo", changeName: "fix", token: revision, requestId: "settle-one", outcome: "interrupted", diagnosis: "Child could not spawn", harnessDisposition: "invalidated", cleanupEvidence: "No process created", processEvidence: "Spawn rejected", remediatesEvidenceRevision: revision }), { state: "complete" });
-	assert.equal(queued.calls[1].arguments.includes("--evidence-revision"), false);
-	assert.equal(queued.calls[1].timeoutMs, undefined);
-});
-
-test("compact SDD refuses malformed result and invalid terminal evidence before execution", async () => {
-	const queued = queuedAdapter([{ stdout: '{"state":"proceed"}' }, { stdout: '{"state":"blocked","reason":"budget"}' }]);
-	const cli = client(queued.adapter);
-	const request = { workspaceRoot: "/repo", changeName: "fix", requestId: "one", workUnit: "correction", evidenceGoal: "Observed correction" };
-	await assert.rejects(cli.sddAttemptAcquire(request), /schema incompatible/);
-	assert.deepEqual(await cli.sddAttemptAcquire(request), { state: "blocked", reason: "budget" });
-	await assert.rejects(cli.sddAttemptSettle({ ...request, token: `sha256:${"a".repeat(64)}`, outcome: "failed", diagnosis: "Test failed", harnessDisposition: "reused", cleanupEvidence: "Process exited", processEvidence: "Exit one" }), /evidence/i);
-	assert.equal(queued.calls.length, 2);
-});
-
-
-test("compact admission accepts native empty CAS and never redirects uncertainty into review", async () => {
-	const queued = queuedAdapter([{ stdout: '{"state":"blocked","reason":"budget"}' }, { stdout: "", timedOut: true }]);
-	const cli = client(queued.adapter);
-	const request = { workspaceRoot: "/repo", changeName: "fix", requestId: "one", workUnit: "fix", evidenceGoal: "Observed correction", expectedRevision: "" };
-	await cli.sddAttemptAcquire(request);
-	assert.equal(queued.calls[0].arguments[queued.calls[0].arguments.indexOf("--expected-revision") + 1], "");
-	await assert.rejects(cli.sddAttemptAcquire({ ...request, expectedRevision: undefined }), error => error instanceof NativeReviewCliError && error.mutationOutcome === "unknown" && error.nextAction === undefined);
-});

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

@@ -0,0 +1,208 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import test from "node:test";
+import { __testing } from "../extensions/gentle-ai.ts";
+
+// These are instruction-delivery contracts, not proof of autonomous model adherence.
+const read = (path: string) => readFileSync(join(import.meta.dirname, "..", path), "utf8");
+const core = read("assets/orchestrator.md");
+const delegation = read("assets/orchestrator-delegation.md");
+const memory = read("assets/orchestrator-memory.md");
+const wrapper = read("extensions/gentle-ai.ts");
+
+function containsAll(text: string, clauses: readonly string[]): void {
+	for (const clause of clauses) assert.ok(text.includes(clause), `missing contract: ${clause}`);
+}
+
+test("organic entry stays read-only without authorization and loads detail before work", () => {
+	containsAll(core, [
+		"Substantial authorized work: use ODD",
+		"ODD (Default Workflow, harness section above) is mandatory on every request",
+		"orchestrator-delegation.md",
+		"orchestrator-memory.md",
+	]);
+	containsAll(delegation, [
+		"Investigation, explanation, review, comparison, and proposal-only requests remain read-only",
+		"without a task or storage permission prompt",
+		"Small, understood work creates no durable task artifacts",
+	]);
+	assert.doesNotMatch(core + wrapper, /Prefer SDD\/OpenSpec artifacts|Substantial feature: suggest SDD organically/);
+	assert.doesNotMatch(core + delegation, /Suggest it when proposal\/spec\/design\/tasks|propose SDD only when durable proposal\/spec\/design\/tasks/);
+});
+
+test("research uses adaptive evidence gathering and existing general workers only", () => {
+	containsAll(delegation, [
+		"problem, intended outcome, constraints, and current evidence",
+		"no fixed questionnaire or mandatory rounds",
+		"one focused user question",
+		"stop and wait",
+		"workers return gaps to the parent",
+		"available authorized documentation/web tools",
+		"prefer primary sources",
+		"URLs or code locations",
+		"verified facts, assumptions, contradictions, freshness, and gaps",
+		"recommendation, tradeoffs, open questions, and implementation implications",
+		"Forward these research instructions",
+		"existing fresh general exploration/research worker",
+		"do not create a specialized agent or invoke `sdd-research`",
+		"no new persistence or readiness machinery",
+	]);
+});
+
+test("task sizing is explicitly advisory and forwarded without cosmetic savings", () => {
+	containsAll(delegation, [
+		"about 400 authored changed lines",
+		"additions plus deletions",
+		"not a task acceptance criterion, hard cap, counter-trigger, automatic stop, forced split, or RDD trigger",
+		"Forward this same advisory-only instruction",
+		"Never delete spaces, blank lines, or comments",
+		"never omit tests, minify, add gratuitous abstractions, or split artificially",
+		"Existing PR size gates remain unchanged",
+	]);
+});
+
+test("organic progress preserves both complete feature copies and reconciles actual evidence", () => {
+	containsAll(memory, [
+		"odd/tasks/<feature-name>.md",
+		"odd/<feature-name>/tasks",
+		"stable task IDs",
+		"full current document",
+		"repository-relative file locator",
+		"preserve valid completed and unrelated work",
+		"reopen invalidated items",
+		"Check off only observed outcomes",
+		"Read back both writes",
+		"not atomic",
+		"mirror pending",
+		"Preserve both versions",
+		"mem_context",
+		"mem_search",
+		"mem_get_observation",
+		"read the actual task file",
+		"not a third authority",
+	]);
+});
+
+test("assumption challenge and task checks do not activate or duplicate native review", () => {
+	containsAll(delegation, [
+		"at most one scoped independent read-only assumption challenge",
+		"high-consequence unproven premise",
+		"Deterministic failures need fixes",
+		"native RDD refuter",
+		"functional checks per task, not an RDD cycle per TODO",
+		"deliverable candidate boundary",
+		"native candidate risk assessment",
+		"gentle_review` with `{\"operation\":\"assess\"}",
+		"Passive/low",
+		"no reviewer or consent ceremony",
+		"only on grant",
+		"decline continues under ordinary policy",
+		"never infer low risk from a failed assessment",
+		"When RDD is disabled, do not start or prompt for RDD",
+	]);
+});
+
+test("user documentation shows recovery and candidate-level consent without claiming model proof", () => {
+	const docs = read("docs/readme-reference.md");
+	containsAll(docs, [
+		"## Organic Driven Development",
+		"```mermaid",
+		"Full feature memory and actual task file",
+		"Native candidate risk",
+		"advisory",
+		"Static prompt tests",
+		"autonomous",
+	]);
+	assert.ok(read("README.md").includes("#organic-driven-development"));
+});
+
+
+test("one feature document carries intent, accepted rationale and worker context", () => {
+	containsAll(memory, [
+		"one feature document, not a separate plan file or topic",
+		"objective, problem, why, scope, constraints",
+		"progress, verification evidence, and next step",
+		"concise rationale for meaningful accepted changes",
+		"Routine corrections stay with their tasks; no exhaustive decision journal",
+		"Accepted user, review, or verification changes",
+		"automatically update affected intent and TODOs",
+		"add genuinely new tasks or reopen invalidated items with a reason",
+		"Findings alone never authorize scope expansion or automatic acceptance",
+		"Before implementation or resume, the parent reads both the actual file and full observation",
+		"passes the locator and relevant context; workers read the document before edits",
+	]);
+	containsAll(read("assets/agents/gentle-ai-worker.md"), [
+		"Read the parent's ODD feature document locator before edits",
+		"Preserve valid completed work; return proposed intent/task changes and their reasons",
+	]);
+});
+
+test("ODD forwards configured TDD without equating test presence with enablement", () => {
+	containsAll(delegation, [
+		"Resolve effective TDD on/off from existing project/session configuration or explicit user choice",
+		"retain its source and exact test runner",
+		"Record resolved mode, source, and runner in the feature document when present",
+		"Tests or frameworks being present does not enable TDD",
+		"Forward mode, source, and runner on every implementation delegation; refresh on resume",
+		"When enabled, require observed RED before implementation, GREEN, then REFACTOR",
+		"When disabled, run ordinary functional checks, not no checks",
+		"If mode is unknown/conflicting or the runner is missing",
+		"resolve only the ambiguity affecting the next action",
+		"never invent precedence or a command, and never invoke sdd-init to determine ODD TDD",
+	]);
+	containsAll(read("assets/agents/gentle-ai-worker.md"), [
+		"Consume the parent's effective TDD mode, configuration/choice source, and exact runner",
+		"Missing or conflicting mode/source/runner is not disabled TDD",
+	]);
+	assert.doesNotMatch(wrapper, /If tests exist, use strict TDD/);
+});
+
+test("ODD protocol is always-on in the rendered system prompt and runs by default", () => {
+	const orderedClauses = [
+		"Default workflow: Organic Driven Development (MANDATORY)",
+		"predefined workflow of this orchestrator",
+		"SDD is a branch inside ODD",
+		"Never describe this workflow only when asked about it: run it.",
+		"1. **Authorize.**",
+		"2. **Explore.**",
+		"3. **Resolve uncertainty.**",
+		"4. **Classify.**",
+		"two or more meaningful implementation steps",
+		"5. **Track before the first write.**",
+		"Tell the user in one line which feature document was created and how many tasks it holds",
+		"6. **Implement task by task.**",
+		"7. **Close.**",
+		"Harness principles:",
+		"# el Gentleman Orchestrator",
+	];
+	for (const persona of ["gentleman", "neutral"] as const) {
+		const prompt = __testing.buildGentlePrompt(persona);
+		let cursor = -1;
+		for (const clause of orderedClauses) {
+			const index = prompt.indexOf(clause);
+			assert.ok(index !== -1, `[${persona}] missing contract: ${clause}`);
+			assert.ok(
+				index > cursor,
+				`[${persona}] clause out of order (must appear after the previous one): ${clause}`,
+			);
+			cursor = index;
+		}
+	}
+
+	assert.ok(
+		wrapper.includes("Organic Driven Development (ODD) is the predefined workflow for every request"),
+		"missing contract: extensions/gentle-ai.ts harness principle",
+	);
+	assert.ok(
+		wrapper.includes(
+			"I run Organic Driven Development by default and SDD/OpenSpec when explicitly selected",
+		),
+		"missing contract: extensions/gentle-ai.ts identity sentence",
+	);
+	assert.ok(
+		core.includes("ODD (Default Workflow, harness section above) is mandatory on every request"),
+		"missing contract: assets/orchestrator.md pointer sentence",
+	);
+	containsAll(core, ["orchestrator-delegation.md", "orchestrator-memory.md"]);
+});

package/tests/orchestrator-budget.test.ts

@@ -281,8 +281,8 @@ function isNormativeLine(line: string): boolean {
 }
 
 const fixtureLines = readFileSync(FIXTURE_PATH, "utf8").split("\n");
-// Fixture lines 187 and 191 predate the root-relative lazy-asset contract and
-// canonical-authority resolution. Keep their coverage by asserting the
+// Fixture line 36 is superseded by ODD (#1035); 187 and 191 predate
+// root-relative lazy assets and canonical-authority resolution. Keep coverage by asserting the
 // intentionally updated production wording instead of weakening the range.
 const CURRENT_SDD_WORKFLOW_PATH = "`sdd-orchestrator-workflow.md`";
 const CURRENT_HARD_PREFLIGHT_INVARIANT = "Hard preflight invariant: `openspec/config.yaml`, existing SDD changes, installed `.pi`/global SDD assets, or a todo named \"preflight\" are not session preflight. Do not mark SDD preflight complete, start `sdd-init`, launch SDD subagents/chains, or move to explore/proposal/spec/design/tasks until this session has an injected `## SDD Session Preflight` block or a canonical-authority resolution. Defaults and capability constraints may resolve fields without confirmation prompts; preserve unresolved-choice and safety gates.";
@@ -320,11 +320,26 @@ for (const range of DISPOSITION_MAP) {
 				if (raw === undefined || !isNormativeLine(raw)) continue;
 				const trimmed = raw.trim();
 				const expected =
+					ln === 36 ? "- Substantial authorized work: use ODD; track feature progress automatically." :
+					// #1051 keeps the selected store when memory is unavailable.
+					ln === 221 ? "do not switch the selected store" :
+					// Research returns findings; other phases keep direct backend ownership.
+					ln === 205 ? trimmed.replace("Each SDD phase", "Except for output-only `sdd-research`, each SDD phase") :
+					ln === 185 ? trimmed.replace("apply/verify/sync/archive", "apply/verify/archive") :
 					ln === 187
 						? CURRENT_SDD_WORKFLOW_PATH
 						: ln === 191
 							? CURRENT_HARD_PREFLIGHT_INVARIANT
 							: trimmed;
+				// #1051 retires the standalone sync row and its artifact key, not
+				// the surrounding memory/recovery contract or historical fixture.
+				if (ln === 216 || ln === 220) {
+					assert.ok(!targetContent.includes(trimmed), `retired sync contract remains at fixture:${ln}`);
+					assert.match(targetContent, /sdd\/<change>\/archive-report/);
+					assert.match(targetContent, /sdd\/<change>\/verify-report/);
+					assert.doesNotMatch(targetContent, /sdd\/<change>\/sync-report|\| `sdd-sync`/);
+					continue;
+				}
 				if (SUPERSEDED_LIFECYCLE_REVIEW_LINES.has(ln)) {
 					assert.ok(
 						!targetContent.includes(trimmed),