gentle-pi 2.2.0 → 2.4.0

package/skills/rdd-defect-workflow/SKILL.md

@@ -15,13 +15,13 @@ This skill guides public collaboration. It does not grant issue approval, label,
 
 ## Hard Rules
 
-- Check the user-owned RDD kill switch first. When disabled, do not start receipt reviews or fabricate approval; follow ordinary policy and report `disabled/unmanaged`.
+- Review and Judgment Day evidence is review-only. Pi never mints delivery authority: ordinary commit, push, PR, and release always follow repository policy, regardless of RDD mode.
 - Require an approved issue (`status:approved`) and clean current `main` reproduction before implementation. Audit existing PRs for supersession or conflict; stop or narrow stale claims.
 - Group by causal authority invariant. Use one issue and one PR or explicit chain per independent invariant and rollback boundary. Split independent causes; never merge a superseded or conflicting authority line.
 - Inventory every operator flow claimed by the issue or PR, including entry, mode, environment, expectation, and negative controls. Require one truthful black-box bench journey per CLI or lifecycle flow, or actual runtime E2E proof when the core bench cannot represent it. Synthetic proxy coverage never proves another runtime.
 - Use CodeGraph-first impact mapping, a dedicated worktree, and behavior-first tests. Run source-mutating normalization before candidate freeze.
 - Forecast authored changes before edits. The hard limit is 400 additions plus deletions; above it, STOP for a chain or explicit maintainer-approved exception.
-- Only when RDD is enabled, bind receipts, lineage, correction, recovery, and delivery gates to the exact candidate. Keep bounded review defects in one correction transaction.
+- When RDD is enabled, bind review receipts, lineage, correction, and recovery evidence to the exact candidate. Keep bounded review defects in one correction transaction; never treat that evidence as delivery authority.
 - Require independent read-only candidate validation before publication. Validation cannot edit source or authority; findings require a new candidate.
 - Keep communication humane and evidence-based. Repository labels and workflow metadata are maintainer-owned, never evidence of contributor blame.
 
@@ -29,7 +29,7 @@ This skill guides public collaboration. It does not grant issue approval, label,
 
 | Condition | Action |
 | --- | --- |
-| RDD disabled | Ordinary policy; `disabled/unmanaged`; no receipt or approval claim. |
+| Any RDD mode | Review evidence remains review-only; ordinary commit, push, PR, and release follow repository policy with no Pi delivery authority. |
 | Issue gate or reproduction fails | Wait, stop, or narrow with evidence. |
 | Invariant or rollback is independent | Separate issue and authoritative PR line. |
 | Core bench fits / does not fit | Bench journey / actual runtime E2E; never proxy. |

package/skills/release/SKILL.md

@@ -17,8 +17,8 @@ Use this skill when preparing, publishing, or verifying a `gentle-pi` release.
 - npm publishing MUST go through the GitHub Actions workflow `.github/workflows/publish.yml` so provenance, environment protection, and registry credentials are controlled by GitHub.
 - Dispatch the trusted workflow definition from protected default `main`, never from a release tag. Its only caller input is the exact annotated version tag.
 - Use a clean worktree for release commits. Do not package unrelated local files or scratch artifacts.
-- Validate the approved receipt against the exact immutable release target with zero review actors before publication.
-- Release from protected `main` may bypass receipt validation only when the tag targets the current immutable `origin/main` SHA, required CI for that exact SHA is successful, the remote head is rechecked before tag push, and no fresh risk evidence exists; otherwise fail closed through native receipt validation. Never infer the tag target from local `HEAD`. Major and post-incident releases require explicit extraordinary review even when fast-path checks pass.
+- Review outcomes are informational. Release delivery follows ordinary repository policy and must not be blocked, authorized, or rewritten by RDD.
+- Never infer the release tag target from local `HEAD`; use the freshly fetched `origin/main` commit and the repository's normal release safeguards.
 - Never skip package verification. The publish workflow runs verification again, but local validation should still pass before tagging.
 
 ## Release Procedure
@@ -114,7 +114,7 @@ Use this skill when preparing, publishing, or verifying a `gentle-pi` release.
 
 ## Failure Handling
 
-- A publication failure never reopens the closed review lineage. Diagnose and retry publication separately without resetting review counters.
+- A publication failure is handled through ordinary repository policy. It does not reopen or alter a review lineage.
 - Never attempt or retry `npm publish` locally. Re-dispatch from trusted `main` only when the same tag still targets the current remote `main` and the failure was publication-only.
 - If remote `main` advances, do not move or recreate the existing tag. Prepare a new release commit/version and create a new annotated version tag.
 - If the workflow fails, inspect logs with:

package/skills/skill-registry/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: skill-registry
+name: gentle-ai-skill-registry
 description: "Trigger: update skills, skill registry, actualizar skills, after skill changes. Index available skills by trigger and path."
 license: MIT
 metadata:

package/skills/work-unit-commits/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: work-unit-commits
+name: gentle-ai-work-unit-commits
 description: "Plan commits as reviewable work units. Trigger: implementation, commit splitting, chained PRs, or keeping tests and docs with code."
 license: Apache-2.0
 metadata:
@@ -30,6 +30,7 @@ Use it for:
 | Tell a story | A reviewer should understand why each commit exists from its diff and message. |
 | Future PR-ready | Each commit should be a candidate chained PR when the change grows. |
 | SDD workload guard | If SDD tasks forecast a >400-line change, group commits into chained PR slices before implementation. |
+| Budget is not code-golf | Never shrink a diff by deleting comments, blank lines, docs, or tests, or by compressing code, to fit the review budget (400 by default, or the session `review_budget_lines`). Slice by work unit or report the overage. |
 
 ## Work Unit Checklist
 
@@ -66,6 +67,7 @@ When `sdd-tasks` produces a Review Workload Forecast:
 - Low risk: keep work-unit commits inside one PR.
 - Medium risk: commit by work unit and monitor changed lines before PR creation.
 - High risk: follow SDD `delivery_strategy` — ask on `ask-on-risk`, auto-slice on `auto-chain`, require `size:exception` on over-budget `single-pr`, or record accepted `size:exception` on `exception-ok`.
+- Splitting is bounded: after one honest slicing pass, if no cohesive work-unit split fits the budget, stop and report the smallest honest count with a `size:exception` recommendation. Do not iterate shrinking the code to reach the number.
 
 Each SDD work unit should map cleanly to a commit or PR with:
 

package/tests/artifact-language.test.ts

@@ -67,14 +67,15 @@ test("rendered SDD preflight prompt is English artifact copy", () => {
 	const prefs: SddPreflightPreferences = {
 		executionMode: "interactive",
 		artifactStore: "openspec",
-		chainedPrStrategy: "ask-always",
+		chainedPrStrategy: "ask-on-risk",
 		reviewBudgetLines: 400,
 		engramAvailable: false,
 		prompted: true,
 	};
 	const prompt = renderSddPreflightPrompt(prefs);
 
-	assert.match(prompt, /The user already chose these SDD preferences/);
+	assert.match(prompt, /These SDD preferences are explicit current-session choices/);
+	assert.match(prompt, /Delivery strategy: ask-on-risk/);
 	assert.match(prompt, /Review budget: 400 changed lines/);
 	assert.match(prompt, /complete only the current SDD phase/i);
 	assert.match(prompt, /Do not start the next SDD phase/i);
@@ -82,9 +83,15 @@ test("rendered SDD preflight prompt is English artifact copy", () => {
 	assert.match(prompt, /offer the user a proposal question round/i);
 	assert.match(prompt, /business rules, implications, impact, edge cases/i);
 	assert.match(prompt, /second question round/i);
+	assert.match(prompt, /explicit acceptance of `size:exception`/);
+	assert.match(prompt, /human-controlled consent, authorization, security, destructive\/publishing/);
 	for (const pattern of SPANISH_PREFLIGHT_COPY) {
 		assert.doesNotMatch(prompt, pattern);
 	}
+
+	const headless = renderSddPreflightPrompt({ ...prefs, executionMode: "auto", prompted: false });
+	assert.match(headless, /canonical defaults or persisted choices/);
+	assert.match(headless, /ambiguous-scope/);
 });
 
 test("orchestrator Memory Contract carries the Engram memory lifecycle rule", async () => {
@@ -159,7 +166,12 @@ test("orchestrator lazy-loads detailed SDD workflow", async () => {
 	const workflow = await readFile(join(ROOT, "assets/sdd-orchestrator-workflow.md"), "utf8");
 
 	assert.match(orchestrator, /## SDD Workflow \(lazy-loaded\)/);
-	assert.match(orchestrator, /\{\{GENTLE_PI_SDD_WORKFLOW_PATH\}\}/);
+	assert.match(orchestrator, /Package assets root: `\{\{GENTLE_PI_ASSETS_ROOT\}\}`\. Lazy asset paths below are relative to this root\./);
+	assert.match(orchestrator, /`sdd-orchestrator-workflow\.md`/);
+	assert.doesNotMatch(orchestrator, /\{\{GENTLE_PI_SDD_WORKFLOW_PATH\}\}/);
+	assert.match(orchestrator, /injected `## SDD Session Preflight` block or a canonical-authority resolution/);
+	assert.match(orchestrator, /Defaults and capability constraints may resolve fields without confirmation prompts/);
+	assert.doesNotMatch(orchestrator, /or an explicit user answer covering the preflight choices/);
 	assert.doesNotMatch(orchestrator, /## Native SDD Dispatcher/);
 	assert.match(workflow, /## Native SDD Dispatcher/);
 	assert.match(workflow, /## SDD Status Contract/);
@@ -188,7 +200,7 @@ test("persistent harness prompt assets do not hardcode Spanish SDD artifact copy
 	assert.deepEqual(failures, []);
 });
 
-test("SDD assets define ownership markers and yield post-apply lifecycle to the parent", async () => {
+test("SDD assets route completed implementation directly through verify, sync, and archive", async () => {
 	const [tasks, apply, status, contract, chain] = await Promise.all([
 		readFile(join(ROOT, "assets/agents/sdd-tasks.md"), "utf8"),
 		readFile(join(ROOT, "assets/agents/sdd-apply.md"), "utf8"),
@@ -196,15 +208,16 @@ test("SDD assets define ownership markers and yield post-apply lifecycle to the
 		readFile(join(ROOT, "assets/support/sdd-status-contract.md"), "utf8"),
 		readFile(join(ROOT, "assets/chains/sdd-full.chain.md"), "utf8"),
 	]);
+	const assets = [tasks, apply, status, contract, chain].join("\n");
 
 	assert.match(tasks, /<!-- sdd-owner: implementation -->/);
-	assert.match(tasks, /<!-- sdd-owner: parent -->/);
-	assert.match(apply, /only implementation-owned/);
-	assert.match(apply, /MUST NOT start bounded-review/);
-	assert.match(status, /malformed/i);
-	assert.match(contract, /deferredParentActions/);
-	assert.match(contract, /parent-lifecycle/);
-	assert.match(chain, /parent.lifecycle/i);
+	assert.match(apply, /next_recommended: "sdd-verify"/);
+	assert.match(status, /verify.*ready/i);
+	assert.match(contract, /apply.*verify.*sync.*archive/is);
+	assert.match(chain, /apply.*verification/is);
+	assert.doesNotMatch(assets, /<!-- sdd-owner: parent -->/);
+	assert.doesNotMatch(assets, /parent-lifecycle/);
+	assert.doesNotMatch(assets, /approved receipt|bounded review/i);
 	assert.doesNotMatch(chain, /## sdd-review/);
 });
 

package/tests/ask-user-choice.test.ts

@@ -0,0 +1,264 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import askUserChoice from "../extensions/ask-user-choice.ts";
+
+interface ChoiceResult {
+	content: Array<{ type: string; text: string }>;
+	details: Record<string, unknown>;
+}
+
+interface ChoiceOptionSchema {
+	additionalProperties?: boolean;
+	properties?: Record<string, unknown>;
+}
+
+interface ChoiceParameters {
+	additionalProperties?: boolean;
+	properties?: {
+		question?: unknown;
+		options?: {
+			minItems?: number;
+			maxItems?: number;
+			items?: ChoiceOptionSchema;
+		};
+	};
+}
+
+interface ChoiceTool {
+	name: string;
+	parameters: ChoiceParameters;
+	execute: (...args: unknown[]) => Promise<ChoiceResult>;
+}
+
+interface ChoiceLifecycleEvent {
+	channel: string;
+	data: { active: boolean };
+}
+
+type BeforeAgentStart = (event: unknown, ctx: { mode: string }) => void | Promise<void>;
+
+function registerChoiceTool(
+	initialTools: string[] = [],
+	onLifecycleEvent?: (event: ChoiceLifecycleEvent) => void,
+) {
+	let activeTools = initialTools;
+	let runtimeActionsAllowed = false;
+	let getActiveToolsCalls = 0;
+	let setActiveToolsCalls = 0;
+	let tool: ChoiceTool | undefined;
+	const hooks: BeforeAgentStart[] = [];
+	const registeredToolNames: string[] = [];
+	const emittedEvents: ChoiceLifecycleEvent[] = [];
+	const pi = {
+		getActiveTools: () => {
+			getActiveToolsCalls++;
+			if (!runtimeActionsAllowed) {
+				throw new Error("runtime actions are unavailable while the extension is loading");
+			}
+			return activeTools;
+		},
+		setActiveTools: (names: string[]) => {
+			setActiveToolsCalls++;
+			if (!runtimeActionsAllowed) {
+				throw new Error("runtime actions are unavailable while the extension is loading");
+			}
+			activeTools = names;
+		},
+		registerTool: (candidate: unknown) => {
+			tool = candidate as ChoiceTool;
+			registeredToolNames.push(tool.name);
+		},
+		on: (event: string, handler: BeforeAgentStart) => {
+			if (event === "before_agent_start") hooks.push(handler);
+		},
+		events: {
+			emit(channel: string, data: { active: boolean }) {
+				const event = { channel, data };
+				emittedEvents.push(event);
+				onLifecycleEvent?.(event);
+			},
+		},
+	};
+	askUserChoice(pi as never);
+	assert.ok(tool, "ask_user_choice must register");
+	return {
+		hooks,
+		tool,
+		registeredToolNames,
+		activeTools: () => [...activeTools],
+		emittedEvents: () => [...emittedEvents],
+		runtimeActionCalls: () => ({ getActiveTools: getActiveToolsCalls, setActiveTools: setActiveToolsCalls }),
+		allowRuntimeActions: () => {
+			runtimeActionsAllowed = true;
+		},
+	};
+}
+
+const options = [
+	{ label: "Authorize observed hash", description: "Accept the baseline hash observed in this runtime.", value: "authorize_observed_hash" },
+	{ label: "Preserve requested hash", description: "Keep the hash from the original request.", value: "preserve_requested_hash" },
+];
+
+function tuiContext(inputs: readonly string[], rendered: { value: string }) {
+	return {
+		mode: "tui",
+		ui: {
+			custom: async (factory: (tui: { requestRender(): void }, theme: { fg(_color: string, text: string): string; bold(text: string): string }, keybindings: unknown, done: (value: unknown) => void) => { render(width: number): string[]; handleInput(data: string): void }) => {
+				let result: unknown;
+				const component = factory(
+					{ requestRender() {} },
+					{ fg: (_color, text) => text, bold: (text) => text },
+					{},
+					(value) => {
+						result = value;
+					},
+				);
+				rendered.value = component.render(100).join("\n");
+				for (const input of inputs) component.handleInput(input);
+				return result;
+			},
+		},
+	};
+}
+
+test("ask_user_choice registers without runtime actions or overriding the open questionnaire", () => {
+	const registration = registerChoiceTool(["read", "ask_user_question"]);
+
+	assert.deepEqual(registration.registeredToolNames, ["ask_user_choice"]);
+	assert.deepEqual(registration.runtimeActionCalls(), { getActiveTools: 0, setActiveTools: 0 });
+	assert.deepEqual(registration.activeTools(), ["read", "ask_user_question"]);
+});
+
+test("ask_user_choice exposes a strict closed single-select schema", () => {
+	const { tool } = registerChoiceTool();
+	const optionsSchema = tool.parameters.properties?.options;
+	const optionSchema = optionsSchema?.items;
+
+	assert.equal(tool.name, "ask_user_choice");
+	assert.equal(tool.parameters.additionalProperties, false);
+	assert.deepEqual(Object.keys(tool.parameters.properties ?? {}).sort(), ["options", "question"]);
+	assert.equal(optionsSchema?.minItems, 2);
+	assert.equal(optionsSchema?.maxItems, 4);
+	assert.equal(optionSchema?.additionalProperties, false);
+	assert.deepEqual(Object.keys(optionSchema?.properties ?? {}).sort(), ["description", "label", "value"]);
+});
+
+test("ask_user_choice handles a closed Kilo hash decision with an opaque envelope value", async () => {
+	const { tool } = registerChoiceTool(["read"]);
+	const rendered = { value: "" };
+	const result = await tool.execute("call", { question: "Proceed?", options }, new AbortController().signal, undefined, tuiContext(["\x1b[B", "\r"], rendered));
+	assert.match(rendered.value, /Proceed\?|Authorize observed hash|Accept the baseline hash|Preserve requested hash|Keep the hash/);
+	assert.doesNotMatch(rendered.value, /Type something|authorize_observed_hash|preserve_requested_hash/);
+	assert.deepEqual(result.details.selection, { value: "preserve_requested_hash", label: "Preserve requested hash", index: 2 });
+	assert.equal(result.content[0]?.text, "User selected: 2. Preserve requested hash (value: preserve_requested_hash)");
+});
+
+test("ask_user_choice cancels without a value and remains unavailable outside the TUI", async () => {
+	const { tool } = registerChoiceTool();
+	const rendered = { value: "" };
+	const cancelled = await tool.execute("call", { question: "Proceed?", options }, new AbortController().signal, undefined, tuiContext(["\x1b"], rendered));
+	assert.equal(cancelled.details.selection, undefined);
+	assert.equal(cancelled.details.cancelled, true);
+	await assert.rejects(
+		() => tool.execute("call", { question: "Proceed?", options }, new AbortController().signal, undefined, { mode: "print" }),
+		/unavailable outside the interactive TUI/,
+	);
+});
+
+test("ask_user_choice emits a private balanced lifecycle around selection and cancellation", async () => {
+	const sequence: string[] = [];
+	const selectedRegistration = registerChoiceTool([], ({ data }) => {
+		sequence.push(data.active ? "active" : "inactive");
+	});
+	const selected = await selectedRegistration.tool.execute(
+		"call",
+		{ question: "private choice question", options },
+		new AbortController().signal,
+		undefined,
+		{
+			mode: "tui",
+			ui: {
+				custom: async () => {
+					sequence.push("custom");
+					return { value: "preserve_requested_hash", label: "Preserve requested hash", index: 2 };
+				},
+			},
+		},
+	);
+	assert.equal(selected.details.selection?.value, "preserve_requested_hash");
+	assert.deepEqual(sequence, ["active", "custom", "inactive"]);
+	assert.deepEqual(selectedRegistration.emittedEvents(), [
+		{ channel: "gentle-pi:ask-user-choice:blocked", data: { active: true } },
+		{ channel: "gentle-pi:ask-user-choice:blocked", data: { active: false } },
+	]);
+	assert.doesNotMatch(
+		JSON.stringify(selectedRegistration.emittedEvents()),
+		/private choice question|Authorize observed hash|Accept the baseline hash|preserve_requested_hash/,
+	);
+
+	const cancelledRegistration = registerChoiceTool();
+	const cancelled = await cancelledRegistration.tool.execute(
+		"call",
+		{ question: "Proceed?", options },
+		new AbortController().signal,
+		undefined,
+		{ mode: "tui", ui: { custom: async () => undefined } },
+	);
+	assert.equal(cancelled.details.cancelled, true);
+	assert.deepEqual(cancelledRegistration.emittedEvents(), [
+		{ channel: "gentle-pi:ask-user-choice:blocked", data: { active: true } },
+		{ channel: "gentle-pi:ask-user-choice:blocked", data: { active: false } },
+	]);
+});
+
+test("ask_user_choice settles its lifecycle after a custom UI error and emits nothing outside the TUI", async () => {
+	const failedRegistration = registerChoiceTool();
+	const customError = new Error("custom UI failed");
+	await assert.rejects(
+		failedRegistration.tool.execute(
+			"call",
+			{ question: "Proceed?", options },
+			new AbortController().signal,
+			undefined,
+			{ mode: "tui", ui: { custom: async () => { throw customError; } } },
+		),
+		(error) => error === customError,
+	);
+	assert.deepEqual(failedRegistration.emittedEvents(), [
+		{ channel: "gentle-pi:ask-user-choice:blocked", data: { active: true } },
+		{ channel: "gentle-pi:ask-user-choice:blocked", data: { active: false } },
+	]);
+
+	const nonTuiRegistration = registerChoiceTool();
+	let customCalled = false;
+	await assert.rejects(
+		nonTuiRegistration.tool.execute(
+			"call",
+			{ question: "Proceed?", options },
+			new AbortController().signal,
+			undefined,
+			{
+				mode: "print",
+				ui: {
+					custom: async () => {
+						customCalled = true;
+						return undefined;
+					},
+				},
+			},
+		),
+		/unavailable outside the interactive TUI/,
+	);
+	assert.equal(customCalled, false);
+	assert.deepEqual(nonTuiRegistration.emittedEvents(), []);
+});
+
+test("ask_user_choice is offered only for interactive TUI turns and preserves the open questionnaire", async () => {
+	const registration = registerChoiceTool(["read", "ask_user_question"]);
+	registration.allowRuntimeActions();
+
+	for (const hook of registration.hooks) await hook({}, { mode: "tui" });
+	assert.deepEqual(registration.activeTools(), ["read", "ask_user_question", "ask_user_choice"]);
+	for (const hook of registration.hooks) await hook({}, { mode: "print" });
+	assert.deepEqual(registration.activeTools(), ["read", "ask_user_question"]);
+});

package/tests/codegraph-tools.test.ts

@@ -1,6 +1,6 @@
 import assert from "node:assert/strict";
 import { execFileSync } from "node:child_process";
-import { mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { join } from "node:path";
 import test from "node:test";
@@ -11,14 +11,14 @@ import codeGraphTools, {
 } from "../extensions/codegraph-tools.ts";
 
 function workspace(t: test.TestContext): string {
-	const cwd = mkdtempSync(join(tmpdir(), "gentle-pi-codegraph-"));
+	const cwd = realpathSync(mkdtempSync(join(tmpdir(), "gentle-pi-codegraph-")));
 	execFileSync("git", ["init", "-b", "main"], { cwd, stdio: "ignore" });
 	t.after(() => rmSync(cwd, { recursive: true, force: true }));
 	return cwd;
 }
 
 test("CodeGraph tool rejects non-project, nested-project, HOME, and temporary workspaces before init", async (t) => {
-	const nonProject = mkdtempSync(join(tmpdir(), "gentle-pi-codegraph-non-project-"));
+	const nonProject = realpathSync(mkdtempSync(join(tmpdir(), "gentle-pi-codegraph-non-project-")));
 	t.after(() => rmSync(nonProject, { recursive: true, force: true }));
 	const root = workspace(t);
 	const nested = join(root, "nested");