gentle-pi 3.1.0 → 3.2.0

package/lib/background-subagents-policy.ts

@@ -0,0 +1,148 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { gentlePiConfigHome } from "./agent-home.ts";
+
+// ---------------------------------------------------------------------------
+// Background subagents policy — project > global > env > default off
+//
+// Pure resolver, extracted from extensions/gentle-ai.ts so the runtime side
+// (extensions/gentle-agents.ts) can read the effective policy without
+// importing the pi extension surface. No pi imports belong in this file.
+// ---------------------------------------------------------------------------
+
+export type BackgroundSubagentsPolicy = "on" | "off";
+
+/** Which of the four sources decided the effective policy. */
+export type BackgroundSubagentsSource =
+	| "project_file"
+	| "global_file"
+	| "environment"
+	| "default";
+
+export interface BackgroundSubagentsResolution {
+	policy: BackgroundSubagentsPolicy;
+	source: BackgroundSubagentsSource;
+	/** The deciding file was present but failed the strict decode. */
+	malformed: boolean;
+	projectFile: string;
+	globalFile: string;
+	projectFileExists: boolean;
+	globalFileExists: boolean;
+	/** The raw env value, reported even when it is unrecognized and inert. */
+	envValue: string | undefined;
+}
+
+export interface LoadBackgroundSubagentsOptions {
+	/** Override the config home directory (used in tests to avoid touching ~/.pi). */
+	gentlePiConfigHome?: string;
+	/** Override the environment lookup (used in tests). */
+	env?: Record<string, string | undefined>;
+}
+
+export const BACKGROUND_SUBAGENTS_SCHEMA = "gentle-pi.background-subagents/v1";
+export const BACKGROUND_SUBAGENTS_FILE = "background-subagents.json";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Strict decode of {"schema":"gentle-pi.background-subagents/v1","policy":"on"|"off"}.
+ * Any malformed shape (bad JSON, wrong schema, unknown keys, invalid policy)
+ * returns undefined so the caller fails closed to "off".
+ */
+export function parseBackgroundSubagentsPolicyFile(
+	raw: string,
+): BackgroundSubagentsPolicy | undefined {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		return undefined;
+	}
+	if (!isRecord(parsed)) return undefined;
+	if (parsed.schema !== BACKGROUND_SUBAGENTS_SCHEMA) return undefined;
+	if (parsed.policy !== "on" && parsed.policy !== "off") return undefined;
+	if (Object.keys(parsed).length !== 2) return undefined;
+	return parsed.policy;
+}
+
+/**
+ * Resolve the background-subagents policy AND the source that decided it.
+ *
+ * Resolution order (first hit wins, mirroring loadRuntimeGuardrailsConfig):
+ *   1. Project file `${cwd}/.pi/gentle-ai/background-subagents.json`
+ *   2. Global file `${configHome}/background-subagents.json`
+ *      (configHome honors GENTLE_PI_CONFIG_HOME, default ~/.pi/gentle-ai)
+ *   3. Env var GENTLE_PI_BACKGROUND_SUBAGENTS ("on" | "off")
+ *   4. Default "off"
+ *
+ * A present-but-malformed file fails closed to "off" instead of falling
+ * through to a lower-priority source, and it stays attributed to that file:
+ * "off decided by a broken project file" and "off by default" are different
+ * situations, and only the first one is a mistake to fix.
+ *
+ * Four sources with first-hit-wins is exactly the shape that makes an edit
+ * look like it did nothing, so the deciding source is part of the result
+ * rather than something a caller has to re-derive.
+ */
+export function resolveBackgroundSubagentsPolicy(
+	cwd: string,
+	options: LoadBackgroundSubagentsOptions = {},
+): BackgroundSubagentsResolution {
+	const env = options.env ?? process.env;
+	const envValue = env.GENTLE_PI_BACKGROUND_SUBAGENTS;
+	let projectFile = "";
+	let globalFile = "";
+	try {
+		const configHome = options.gentlePiConfigHome ?? gentlePiConfigHome();
+		projectFile = join(cwd, ".pi", "gentle-ai", BACKGROUND_SUBAGENTS_FILE);
+		globalFile = join(configHome, BACKGROUND_SUBAGENTS_FILE);
+		const projectFileExists = existsSync(projectFile);
+		const globalFileExists = existsSync(globalFile);
+		const locations = { projectFile, globalFile, projectFileExists, globalFileExists, envValue };
+		for (const [source, path, present] of [
+			["project_file", projectFile, projectFileExists],
+			["global_file", globalFile, globalFileExists],
+		] as const) {
+			if (!present) continue;
+			let decoded: BackgroundSubagentsPolicy | undefined;
+			try {
+				decoded = parseBackgroundSubagentsPolicyFile(readFileSync(path, "utf8"));
+			} catch {
+				// Unreadable is indistinguishable from unusable at this layer, and
+				// both must fail closed on the file that claimed the decision.
+				decoded = undefined;
+			}
+			return decoded === undefined
+				? { policy: "off", source, malformed: true, ...locations }
+				: { policy: decoded, source, malformed: false, ...locations };
+		}
+		if (envValue === "on" || envValue === "off") {
+			return { policy: envValue, source: "environment", malformed: false, ...locations };
+		}
+		return { policy: "off", source: "default", malformed: false, ...locations };
+	} catch {
+		return {
+			policy: "off",
+			source: "default",
+			malformed: false,
+			projectFile,
+			globalFile,
+			projectFileExists: false,
+			globalFileExists: false,
+			envValue,
+		};
+	}
+}
+
+/**
+ * The effective policy alone, for callers that do not report a source.
+ * It delegates so the loader and the resolver can never disagree.
+ */
+export function loadBackgroundSubagentsPolicy(
+	cwd: string,
+	options: LoadBackgroundSubagentsOptions = {},
+): BackgroundSubagentsPolicy {
+	return resolveBackgroundSubagentsPolicy(cwd, options).policy;
+}

package/lib/native-review-cli.ts

@@ -986,6 +986,15 @@ export const NATIVE_CLI_CONTRACTS = Object.freeze({
 	// and hint remain dark because neither is proven to reach the negotiated
 	// START path Pi consumes.
 	"3.0.1": Object.freeze({ start: true, finalize: true, validate: true, bindSdd: true, status: true, inventory: true, reclaim: true, recover: true, abandon: true, quarantineLegacy: true, reconcileAuthority: true, repairLegacyAlias: true, mode: true, riskEvidence: false, hint: false, delivery: true }),
+	// v3.1.0 changed the ODD orchestrator contract only (gentle-ai #4714).
+	// Ground-truthed by 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: zero bytes changed (provider contract
+	// stays 1.2.0). Neither change touches the closed START/STATUS fields
+	// this row negotiates, so it repeats 3.0.1 exactly. riskEvidence and hint
+	// remain dark because neither is proven to reach the negotiated START
+	// path Pi consumes.
+	"3.1.0": Object.freeze({ start: true, finalize: true, validate: true, bindSdd: true, status: true, inventory: true, reclaim: true, recover: true, abandon: true, quarantineLegacy: true, reconcileAuthority: true, repairLegacyAlias: true, mode: true, riskEvidence: false, hint: false, delivery: true }),
 });
 
 export interface NativeReviewProcessDiagnostics {

package/lib/review-candidate-view.ts

@@ -659,6 +659,8 @@ function isFullCommitId(selector: string): boolean {
 	return /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/i.test(selector);
 }
 
+export const BASE_REF_ACCEPTED_FORMS = "HEAD, a full 40- or 64-character commit id, or a ref name (branch, tag, remote, or refs/...); abbreviated commit ids are not accepted";
+
 function explicitBaseRefCandidates(cwd: string, selector: string, env: NodeJS.ProcessEnv, executor: CandidateGitExecutor): string[] {
 	if (selector === "HEAD" || isFullCommitId(selector)) return [selector];
 	const refs = new Set(git(cwd, ["for-each-ref", "--format=%(refname)"], env, executor).split("\n").filter((ref) => ref.length > 0));
@@ -719,8 +721,27 @@ function resolveEmptyTree(cwd: string, env: NodeJS.ProcessEnv, executor: Candida
 	return git(cwd, ["mktree"], env, executor);
 }
 
+// Resolves `<selector>^{commit}` to a commit id. For an explicit (caller-
+// supplied) baseRef, a nonzero exit is reported as base-ref-unresolvable with
+// the accepted forms rather than as a generic git failure: the selector may
+// be well-formed (a full commit id, a resolvable ref) and still not name a
+// commit, e.g. a full hex id that names a tree object. Timeouts and output-
+// limit failures still propagate as real git failures through
+// probeCandidateGit, the same way isUnbornSymbolicHead handles them. The
+// implicit default (HEAD, no baseRef) keeps the original fail-closed
+// git-failure behavior, since HEAD not resolving signals repository
+// corruption rather than a caller mistake.
+function resolveCommitSelector(cwd: string, selector: string, env: NodeJS.ProcessEnv, executor: CandidateGitExecutor, explicit: boolean): string {
+	const arguments_ = ["rev-parse", "--verify", "--end-of-options", `${selector}^{commit}`];
+	if (!explicit) return git(cwd, arguments_, env, executor);
+	const probe = probeCandidateGit(cwd, arguments_, env, executor);
+	if (probe.status !== 0) throw new CandidateViewError(`candidate base reference is unresolvable; it does not name a commit; accepted forms: ${BASE_REF_ACCEPTED_FORMS}`, "base-ref-unresolvable");
+	return probe.stdout;
+}
+
 function resolveCandidateBase(cwd: string, baseRef: string | undefined, env: NodeJS.ProcessEnv, executor: CandidateGitExecutor): ResolvedCandidateBase {
 	const selector = baseRef ?? "HEAD";
+	const explicit = baseRef !== undefined;
 	// An unborn repository has a symbolic HEAD pointing at a branch with no
 	// commits yet. Its review base is Git's repository-native empty tree, not a
 	// missing or malformed commit. Only the default/HEAD selector is entitled to
@@ -729,21 +750,21 @@ function resolveCandidateBase(cwd: string, baseRef: string | undefined, env: Nod
 		return { commit: "HEAD", tree: resolveEmptyTree(cwd, env, executor) };
 	}
 	try {
-		if (baseRef !== undefined) {
+		if (explicit) {
 			const candidates = explicitBaseRefCandidates(cwd, selector, env, executor);
-			if (candidates.length > 1) throw new CandidateViewError("candidate base reference is ambiguous", "base-ref-ambiguous");
-			if (candidates.length === 0) throw new CandidateViewError("candidate base reference is unresolvable", "base-ref-unresolvable");
+			if (candidates.length > 1) throw new CandidateViewError(`candidate base reference is ambiguous (matches more than one ref); accepted forms: ${BASE_REF_ACCEPTED_FORMS}`, "base-ref-ambiguous");
+			if (candidates.length === 0) throw new CandidateViewError(`candidate base reference is unresolvable; accepted forms: ${BASE_REF_ACCEPTED_FORMS}`, "base-ref-unresolvable");
 		}
-		const firstCommit = git(cwd, ["rev-parse", "--verify", "--end-of-options", `${selector}^{commit}`], env, executor);
+		const firstCommit = resolveCommitSelector(cwd, selector, env, executor, explicit);
 		const tree = git(cwd, ["rev-parse", "--verify", "--end-of-options", `${firstCommit}^{tree}`], env, executor);
-		const confirmedCommit = git(cwd, ["rev-parse", "--verify", "--end-of-options", `${selector}^{commit}`], env, executor);
+		const confirmedCommit = resolveCommitSelector(cwd, selector, env, executor, explicit);
 		if (firstCommit !== confirmedCommit) throw new CandidateViewError("candidate base reference moved during resolution", "base-ref-moved");
 		const confirmedTree = git(cwd, ["rev-parse", "--verify", "--end-of-options", `${confirmedCommit}^{tree}`], env, executor);
 		if (tree !== confirmedTree) throw new CandidateViewError("candidate base tree changed during resolution", "base-ref-moved");
 		return { commit: confirmedCommit, tree: confirmedTree };
 	} catch (error) {
 		if (error instanceof CandidateViewError && (error.diagnostics !== undefined || error.reason === "base-ref-ambiguous" || error.reason === "base-ref-moved" || error.reason === "base-ref-unresolvable")) throw error;
-		throw new CandidateViewError("candidate base reference is unresolvable", "base-ref-unresolvable");
+		throw new CandidateViewError(`candidate base reference is unresolvable; accepted forms: ${BASE_REF_ACCEPTED_FORMS}`, "base-ref-unresolvable");
 	}
 }
 

package/lib/sdd-preflight.ts

@@ -835,26 +835,12 @@ export function installPackageAssets(
 	}, lockOptions);
 }
 
-function hasAffirmativeSddIntent(text: string): boolean {
-	// Natural-language routing must not depend on a closed list of complete
-	// phrases. An SDD mention becomes an invocation only with an imperative,
-	// request, or first-person intent marker; a neutral statement such as
-	// "I use SDD sometimes" remains ordinary conversation.
-	if (!/\bsdd\b/i.test(text)) return false;
-	return /(?:\b(?:please|por\s+favor)\b|\b(?:want|need|would\s+like|let'?s|quiero|queremos|necesito|quisiera|me\s+gustar[ií]a|vamos|vayamos|hagamos|usemos)\b|^(?:use|run|start|build|create|implement|handle|make|usa|usá|corre|corré|arranca|arrancá|inicia|iniciá|empeza|empezá|hacelo|hazlo|hacerlo)\b)/i.test(text);
-}
-
+// Input interception is intentionally syntax-only. Natural-language SDD intent
+// belongs to the parent/orchestrator; dispatch and before_agent_start gates run
+// or reuse preflight when an SDD action is actually attempted. This keeps mere
+// mentions side-effect free without trying to encode language in a regex.
 export function isSddPreflightTrigger(text: string): boolean {
-	const trimmed = text.trim();
-	if (/^\/(?:gentle-)?sdd(?:[-:][^\s]*)?(?:\s|$)/i.test(trimmed)) return true;
-	if (/[?？]\s*$/.test(trimmed)) return false;
-	if (
-		/(?:\b(?:don't|do\s+not|never)\b|\bnot\s+(?:want|need|plan(?:ning)?|intend|use|using)\b)[^.!?\n]{0,80}\bsdd\b/i.test(trimmed) ||
-		/\b(?:sin\s+usar|no\s+(?:quiero|queremos|necesito|necesitamos|quisiera|quisiéramos|vamos\s+a|pienso|planeo|usar))\b[^.!?\n]{0,80}\bsdd\b/i.test(trimmed)
-	) {
-		return false;
-	}
-	return hasAffirmativeSddIntent(trimmed);
+	return /^\/(?:gentle-)?sdd(?:[-:][^\s]*)?(?:\s|$)/i.test(text.trim());
 }
 
 export function sddPreflightSessionKey(ctx: ExtensionContext): string {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "gentle-pi",
-	"version": "3.1.0",
+	"version": "3.2.0",
 	"description": "Turn Pi into el Gentleman: a senior-architect development harness with SDD/OpenSpec, subagents, strict TDD evidence, review guardrails, and skill discovery.",
 	"license": "MIT",
 	"type": "module",

package/runtime/native-review-cli.mjs

@@ -987,6 +987,15 @@ export const NATIVE_CLI_CONTRACTS = Object.freeze({
 	// and hint remain dark because neither is proven to reach the negotiated
 	// START path Pi consumes.
 	"3.0.1": Object.freeze({ start: true, finalize: true, validate: true, bindSdd: true, status: true, inventory: true, reclaim: true, recover: true, abandon: true, quarantineLegacy: true, reconcileAuthority: true, repairLegacyAlias: true, mode: true, riskEvidence: false, hint: false, delivery: true }),
+	// v3.1.0 changed the ODD orchestrator contract only (gentle-ai #4714).
+	// Ground-truthed by 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: zero bytes changed (provider contract
+	// stays 1.2.0). Neither change touches the closed START/STATUS fields
+	// this row negotiates, so it repeats 3.0.1 exactly. riskEvidence and hint
+	// remain dark because neither is proven to reach the negotiated START
+	// path Pi consumes.
+	"3.1.0": Object.freeze({ start: true, finalize: true, validate: true, bindSdd: true, status: true, inventory: true, reclaim: true, recover: true, abandon: true, quarantineLegacy: true, reconcileAuthority: true, repairLegacyAlias: true, mode: true, riskEvidence: false, hint: false, delivery: true }),
 });
 
 

package/scripts/gentle-ai-installer.mjs

@@ -36,7 +36,7 @@ const WINDOWS_SYSTEM_ROOT = "C:\\Windows";
 // version check below) derives from this constant instead of repeating the
 // literal, so a pin bump cannot leave a stale copy behind. See
 // scripts/install-gentle-ai.mjs for the incident that motivated this.
-export const INSTALLER_VERSION = "3.0.1";
+export const INSTALLER_VERSION = "3.1.0";
 export const RELEASE_BASE_URL = `https://github.com/Gentleman-Programming/gentle-ai/releases/download/v${INSTALLER_VERSION}/`;
 export const GENTLE_AI_INSTALL_METHOD = Object.freeze({
 	SIGNED_RELEASE_ASSET: "signed-release-asset",
@@ -45,10 +45,10 @@ export const GENTLE_AI_INSTALL_METHOD = Object.freeze({
 export const GENTLE_AI_WINDOWS_SOURCE_PACKAGE_PATH = "github.com/gentleman-programming/gentle-ai/v3/cmd/gentle-ai";
 export const GENTLE_AI_WINDOWS_SOURCE_MODULE = "github.com/gentleman-programming/gentle-ai/v3";
 export const GENTLE_AI_WINDOWS_SOURCE_TAG = `v${INSTALLER_VERSION}`;
-// `go mod download -json github.com/gentleman-programming/gentle-ai/v3@v3.0.1`
+// `go mod download -json github.com/gentleman-programming/gentle-ai/v3@v3.1.0`
 // with GOSUMDB=sum.golang.org reports this exact module SumDB checksum, and the
-// tag resolves to commit 2594581e, the published v3.0.1 release head.
-export const GENTLE_AI_WINDOWS_SOURCE_MODULE_CHECKSUM = "h1:r2z8yf0CdL0ZPPkMEKI3km6SitjOIC/DQDvtipc1Igs=";
+// tag resolves to commit cfc415ce, the published v3.1.0 release head.
+export const GENTLE_AI_WINDOWS_SOURCE_MODULE_CHECKSUM = "h1:CrZlui5N8/RSmxvn/7usKe6q1EvRt7y6dyfEwjstmJw=";
 export const GENTLE_AI_WINDOWS_SOURCE_PACKAGE = `${GENTLE_AI_WINDOWS_SOURCE_PACKAGE_PATH}@${GENTLE_AI_WINDOWS_SOURCE_TAG}`;
 export const GENTLE_AI_WINDOWS_MINIMUM_GO_VERSION = "1.25.10";
 export const GENTLE_AI_GO_TOOLCHAIN_UNAVAILABLE_CODE = "GENTLE_AI_GO_TOOLCHAIN_UNAVAILABLE";
@@ -67,7 +67,7 @@ export class GentleAiInstallerError extends Error {
 // Sentinel used while a re-pinned gentle-ai release is not yet published. A
 // sentinel digest can never match a real SHA-256, so installation fails closed,
 // and verify-package-files.mjs refuses to pack/publish while any digest below
-// still holds it. The v3.0.1 digests are pinned from the published release:
+// still holds it. The v3.1.0 digests are pinned from the published release:
 // archive sha256 values verified against the minisign-signed checksums.txt and
 // freshly computed hashes; binary sha256 values computed from the extracted
 // executables.
@@ -109,15 +109,15 @@ async function downloadPinnedGentleAiAsset(asset, destination, options) {
 }
 
 // Windows is absent from signed release archives on purpose. gentle-ai stopped
-// distributing unsigned Windows builds in c4b764d0, so v3.0.1 publishes signed
+// distributing unsigned Windows builds in c4b764d0, so v3.1.0 publishes signed
 // Darwin/Linux archives only. Windows x64/arm64 uses the separately verified
 // exact-tag Go SumDB source-build path below; restore archive rows only when
 // upstream ships signed Windows assets.
 export const GENTLE_AI_RELEASE_ASSETS = Object.freeze({
-	"darwin/amd64": asset("gentle-ai_3.0.1_darwin_amd64.tar.gz", "fce899fbdada3781624cc03aa6adaf9b21041915240ef092ff89f222151c9efd", "01dec1aea73a0e70d44432d021bdafc9309382f597ce247f58e6c523caed1345", "gentle-ai"),
-	"darwin/arm64": asset("gentle-ai_3.0.1_darwin_arm64.tar.gz", "17f12008a056e43042daa6d72b37923a2a071f0d52cca80606410eb096caa9c2", "74c0f14c9806a786ae2cd78989d8ca95e0c01e6c7cc3b80c738f284c1064212e", "gentle-ai"),
-	"linux/amd64": asset("gentle-ai_3.0.1_linux_amd64.tar.gz", "920ad99189a655452006e96a7b25f1e04d745973e36b75130a3b4a16c53deda8", "201b79d4e6e7551cdfde3ad44e56ad0638173b1093f87fc1156a24652fa24448", "gentle-ai"),
-	"linux/arm64": asset("gentle-ai_3.0.1_linux_arm64.tar.gz", "e54a588c4ce5adfd9ded4c59c6cc5c1eb369fd88f8c54fa892f2cceb7fdbac8d", "9dbd481f5854c568411a8030fdd2192a23ff011270f8994ae181655786dca638", "gentle-ai"),
+	"darwin/amd64": asset("gentle-ai_3.1.0_darwin_amd64.tar.gz", "613f0e11adeebb421daae4c68cb9f207f55c559a70595549ff25f988559226e4", "98340df0102825072431a2c0373ea4d9db1bacafced234f51fb58661ed3d731f", "gentle-ai"),
+	"darwin/arm64": asset("gentle-ai_3.1.0_darwin_arm64.tar.gz", "bfcbf8df2682fcf1535b26c604e8dbb445df0ca00a651de204fdc2d013dfe472", "3cdc9689ea0d71186b896341b4181e2df13a82b64d236a26a3273171150d802f", "gentle-ai"),
+	"linux/amd64": asset("gentle-ai_3.1.0_linux_amd64.tar.gz", "dc55c44a2eb46212a38eca0dfd4d778481ec37e765f40d5a0752d03c28e1ee49", "70e335d25809a0d358c12f48b2f0d1da00741e725584ceeb8c1318c60d0a6e9e", "gentle-ai"),
+	"linux/arm64": asset("gentle-ai_3.1.0_linux_arm64.tar.gz", "3a89d5f5a549004cc2b01949014ed59f9c28e1ff0c9958531bb539504286e407", "6cf9f20fc390b13e2b9b427ca1c2df404d1bbb9248201f9a592c7f0a37ef5416", "gentle-ai"),
 });
 
 // A pinned asset is either a signed archive or, for a prerelease pin only,

package/scripts/verify-package-files.mjs

@@ -339,7 +339,7 @@ async function main() {
   });
 
   if (driftedContracts.length > 0) {
-    console.error("gentle-pi packaged review-integration/v1 and review-integration/v2 contract bytes drifted from the pinned v3.0.1 runtime's vendored Gentle AI contract artifacts:");
+    console.error("gentle-pi packaged review-integration/v1 and review-integration/v2 contract bytes drifted from the pinned v3.1.0 runtime's vendored Gentle AI contract artifacts:");
     for (const drift of driftedContracts) console.error(`- ${drift.relativePath}: expected ${drift.expected}, got ${drift.actual}`);
     process.exit(1);
   }
@@ -384,7 +384,7 @@ async function main() {
     process.exit(1);
   }
 
-  console.log(`gentle-pi package resource check passed (${requiredPaths.length} files; ${Object.keys(contractHashes).length} exact byte-pinned contract artifacts for the v3.0.1 runtime).`);
+  console.log(`gentle-pi package resource check passed (${requiredPaths.length} files; ${Object.keys(contractHashes).length} exact byte-pinned contract artifacts for the v3.1.0 runtime).`);
 }
 
 const isMainModule = process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href;

package/skills/chained-pr/SKILL.md

@@ -9,7 +9,7 @@ metadata:
 
 ## Activation Contract
 
-Load this skill when a planned PR may exceed **400 changed lines**, SDD forecasts `400-line budget risk: High` or `Chained PRs recommended: Yes`, or the user asks for chained/stacked PRs, review slices, or reviewer-load control.
+Load this skill when a planned PR may exceed **400 changed lines**, SDD forecasts `400-line budget risk: High` or `Chained PRs recommended: Yes`, an ODD feature's forecast or running authored changed-line count from work-unit commits exceeds about 400, or the user asks for chained/stacked PRs, review slices, or reviewer-load control.
 
 ## Hard Rules
 
@@ -34,6 +34,7 @@ Load this skill when a planned PR may exceed **400 changed lines**, SDD forecast
 | Generated/vendor/migration diff cannot split cleanly | Ask maintainer for `size:exception`. |
 | No cohesive split fits the budget after one slicing pass | Stop; deliver the best split, report the overage and why it cannot shrink further, and recommend `size:exception`. |
 | SDD provides `delivery_strategy` | Follow it before apply/PR creation. |
+| ODD provides `delivery_strategy` and `chain_strategy` | Follow them before the next work-unit commit or PR creation. |
 
 ## Execution Steps
 

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

@@ -18,6 +18,7 @@ Use it for:
 - Turning a large change into chained or stacked PRs.
 - Keeping reviewer cognitive load healthy.
 - Applying SDD tasks without accidentally producing a PR above 400 changed lines.
+- Closing an ODD task with a work-unit commit.
 
 ## Critical Rules
 
@@ -76,6 +77,14 @@ Each SDD work unit should map cleanly to a commit or PR with:
 - verification in the same unit,
 - rollback that does not remove unrelated work.
 
+## ODD Relationship
+
+Every ODD task closes with at least one work-unit commit:
+
+- The native review candidate is that commit, or the PR slice it belongs to when review is deferred, evaluated against the previous reviewed boundary.
+- The running authored line count from work-unit commits feeds the same delivery-strategy vocabulary as SDD.
+- The feature document records the commit identity and, once a delivery strategy applies, the slice boundaries.
+
 ## Commands
 
 ```bash

package/tests/background-subagents-default-mode.test.ts

@@ -0,0 +1,105 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { AGENT_MODE } from "../lib/agents-config.ts";
+import { resolveDefaultSubagentMode } from "../extensions/gentle-agents.ts";
+
+// ---------------------------------------------------------------------------
+// resolveDefaultSubagentMode: the runtime default for subagent_run when
+// neither an explicit params.mode nor an agent-defined mode was given.
+//
+// Background is a runtime default only when the background-subagents policy
+// is "on" AND the parent can receive background results. Print mode exits
+// before a parent session exists to deliver a background result to, so it
+// must keep the configured default even when the policy is on (see the
+// `ctx.mode === "print"` guard in gentle-agents.ts `launch`).
+// ---------------------------------------------------------------------------
+
+test("policy on + interactive parent -> background", () => {
+	assert.equal(
+		resolveDefaultSubagentMode({
+			configuredDefault: AGENT_MODE.TASK,
+			policy: "on",
+			parentMode: "interactive",
+		}),
+		AGENT_MODE.BACKGROUND,
+	);
+});
+
+test("policy on + rpc parent -> background", () => {
+	assert.equal(
+		resolveDefaultSubagentMode({
+			configuredDefault: AGENT_MODE.TASK,
+			policy: "on",
+			parentMode: "rpc",
+		}),
+		AGENT_MODE.BACKGROUND,
+	);
+});
+
+test("policy on + print parent -> configured default (task), never background", () => {
+	assert.equal(
+		resolveDefaultSubagentMode({
+			configuredDefault: AGENT_MODE.TASK,
+			policy: "on",
+			parentMode: "print",
+		}),
+		AGENT_MODE.TASK,
+	);
+});
+
+test("policy off -> configured default regardless of parent mode", () => {
+	for (const parentMode of ["interactive", "rpc", "print", undefined]) {
+		assert.equal(
+			resolveDefaultSubagentMode({
+				configuredDefault: AGENT_MODE.TASK,
+				policy: "off",
+				parentMode,
+			}),
+			AGENT_MODE.TASK,
+			`parentMode ${String(parentMode)} must not change an off policy`,
+		);
+	}
+});
+
+test("configured default background + policy off -> background (the configured default wins when the policy is off)", () => {
+	assert.equal(
+		resolveDefaultSubagentMode({
+			configuredDefault: AGENT_MODE.BACKGROUND,
+			policy: "off",
+			parentMode: "interactive",
+		}),
+		AGENT_MODE.BACKGROUND,
+	);
+});
+
+test("configured default background + policy on + interactive -> background (both agree)", () => {
+	assert.equal(
+		resolveDefaultSubagentMode({
+			configuredDefault: AGENT_MODE.BACKGROUND,
+			policy: "on",
+			parentMode: "interactive",
+		}),
+		AGENT_MODE.BACKGROUND,
+	);
+});
+
+test("parentMode undefined with policy on is treated as not print -> background", () => {
+	assert.equal(
+		resolveDefaultSubagentMode({
+			configuredDefault: AGENT_MODE.TASK,
+			policy: "on",
+			parentMode: undefined,
+		}),
+		AGENT_MODE.BACKGROUND,
+	);
+});
+
+// Explicit request mode always wins over the resolved default: this is
+// asserted at the wiring site (extensions/gentle-agents.ts `run` and
+// `continue` tools), not inside this pure helper, which has no notion of
+// "explicit" at all — it is called only when params.mode and agent.mode are
+// both absent. tests/agents-integration.test.ts does not currently exercise
+// subagent_run with a fake child process, so that wiring-level assertion is
+// not covered by an automated test in this change; it is covered by reading
+// the call site, where `params.mode ?? agent.mode ?? resolveDefaultSubagentMode(...)`
+// short-circuits on any explicit value before this helper is ever invoked.

package/tests/gentle-agents.test.ts

@@ -83,9 +83,22 @@ const root = realpathSync(mkdtempSync(join(tmpdir(), "gentle-agents-ext-")));
 const activeSessionTeardowns = new Set<() => Promise<void>>();
 const stopActiveSessions = () => Promise.all([...activeSessionTeardowns].map((shutdown) => shutdown()));
 afterEach(stopActiveSessions);
+// subagent_run's default mode now reads the background-subagents policy
+// in-process (gentle-pi#background-subagents-default-mode), which falls
+// back to the real ~/.pi/gentle-ai/background-subagents.json when
+// GENTLE_PI_CONFIG_HOME is unset. Point it at an empty scratch directory so
+// this file's expectations never depend on the developer's own global
+// policy file (a real "on" file on the runner's machine would otherwise
+// flip every unrelated fixture's default mode to background).
+const previousGentlePiConfigHome = process.env.GENTLE_PI_CONFIG_HOME;
+process.env.GENTLE_PI_CONFIG_HOME = join(root, "gentle-ai-config-home");
 after(async () => {
 	try { await stopActiveSessions(); }
-	finally { rmSync(root, { recursive: true, force: true }); }
+	finally {
+		if (previousGentlePiConfigHome === undefined) delete process.env.GENTLE_PI_CONFIG_HOME;
+		else process.env.GENTLE_PI_CONFIG_HOME = previousGentlePiConfigHome;
+		rmSync(root, { recursive: true, force: true });
+	}
 });
 const home = join(root, "home");
 const cwd = join(root, "project");

package/tests/gentle-ai-binary.test.ts

@@ -97,7 +97,7 @@ async function writeWindowsSourceBinary(packageRoot: string): Promise<{ binaryPa
 		method: "go-sumdb-source-build",
 		package: "github.com/gentleman-programming/gentle-ai/v3/cmd/gentle-ai",
 		module: "github.com/gentleman-programming/gentle-ai/v3",
-		tag: "v3.0.1",
+		tag: "v3.1.0",
 		architecture: process.arch === "x64" ? "x64" : "arm64",
 		binarySha256: createHash("sha256").update(binary).digest("hex"),
 		moduleChecksum: GENTLE_AI_WINDOWS_SOURCE_MODULE_CHECKSUM,