@pmelab/gtd 26.1.0 → 27.1.0

package/dist/testkit.mjs

@@ -1,7 +1,7 @@
 import { checkScript, configProblems, configure, installContext, isFactoryWorkflow, moveScript, protocolMismatch, removeScript, restoreScript, revertScript, showScript, t as flows_exports } from "./flows.mjs";
-import { O as renderFormat, T as ACCESS_REFUSAL, _ as demandOf, a as landFields, c as renderLandJson, d as renderBeatPlain, f as beatDocument, g as beatKindOf, i as judgeJson, l as renderLandPlain, m as statusOf, n as resolveSession, p as renderBeatJson, r as selectPath, s as noopText, t as globMatches } from "./chunks/wire-DA7q2ikx.mjs";
+import { E as ACCESS_REFUSAL, _ as demandOf, a as landFields, c as renderLandJson, d as renderBeatPlain, f as beatDocument, g as beatKindOf, i as judgeJson, k as renderFormat, l as renderLandPlain, m as statusOf, n as resolveSession, p as renderBeatJson, r as selectPath, s as noopText, t as globMatches } from "./chunks/wire-BY1S-obW.mjs";
 import { C as headingSections, S as headingSectionBodies, a as unansweredQuestions, b as parseThreadsWithFindings, n as openThreads, r as steeringFormatFor, s as parseCodeThreads, t as BUILT_IN_MODE_NAMES, w as formatFinding } from "./chunks/steering-DVILanVf.mjs";
-import { $ as makeSemaphore, $i as toJSON, $n as mapBoth, $r as none$1, $t as provideMerge$1, A as catchTag, Ai as getOption, An as scopeTag, Ar as interrupt$2, At as sync$2, B as flatten$4, Bi as isSome, Bn as make$16, Br as tap$1, Bt as unsafeMakeSemaphore$1, C as all$1, Ci as unsafeFromArray, Cn as isInterruptedOnly, Cr as exitFailCause, Ct as scope, D as async, Di as Tag, Dn as ensuring$3, Dr as fiberId, Dt as serviceOption, E as asVoid$1, Ei as GenericTag, En as squash, Er as exitZipRight, Et as scopedWith$1, F as exit, Fi as filter$1, Fn as sequential, Fr as onInterrupt, Ft as tryPromise, G as forkScoped, Gi as isLeft, Gn as Class, Gr as withFiberRuntime, Gt as zipRight$3, H as forEach$2, Hi as match$4, Hn as set$1, Hr as uninterruptibleMask$1, Ht as withFiberRuntime$1, I as fail$5, Ii as flatMap$5, In as bind, Ir as scopeClose, It as try_, J as interrupt$4, Ji as right, Jn as die, Jr as empty$6, Jt as TaggedError$1, K as gen, Ki as left, Kn as spanTag, Kr as zipRight$1, Kt as zipWith, L as failCause$4, Li as fromNullable, Ln as bindTo, Lr as succeed$4, Lt as uninterruptible$1, M as dieMessage, Mi as empty$5, Mn as inheritAll$1, Mr as interruptFiber, Mt as tapErrorCause, N as either, Ni as fromIterable, Nn as interruptAllAs$1, Nr as interruptible$1, Nt as timeout, O as catchAll$1, Oi as add, On as forEachConcurrentDiscard, Or as fiberRefLocally, Ot as succeed$6, P as ensuring$2, Pi as splitAt, Pn as join$3, Pr as map$3, Pt as tryMap, Q as logWarning, Qi as format, Qn as map$5, Qr as make$19, Qt as provide$1, R as fiberIdWith, Ri as getOrElse, Rn as sleep, Rr as suspend$4, Rt as uninterruptibleMask, S as addFinalizer$1, Si as toArray, Sn as isInterrupted, Sr as exitFail, St as sandbox, T as as, Ti as unsafeHead, Tn as reduceWithContext, Tr as exitVoid, Tt as scoped$4, U as forkDaemon, Ui as none, Un as update$1, Ur as void_$2, Ut as zip$1, V as fnUntraced, Vi as map$8, Vn as modify$1, Vr as uninterruptible, Vt as when, W as forkIn, Wi as some, Wn as TypeId$10, Wr as whenEffect, Wt as zipLeft, X as intoDeferred, Xi as BaseProto, Xn as failCause$3, Xr as combineAll, Xt as fromEffect$5, Y as interruptible, Yi as pipeArguments, Yn as fail$4, Yr as combine, Yt as tagged, Z as isEffect, Zi as NodeInspectSymbol, Zn as isFailure, Zr as ids, Zt as mergeAll$2, _ as decodeSync, _i as prepend, _n as failureOrCause, _r as deferredMake, _t as repeat, a as Literal, aa as constVoid, ai as decode, an as forkIn$1, ar as as$1, at as matchCauseEffect, b as acquireRelease, bi as take$2, bn as interruptors, br as deferredUnsafeMake, bt as runPromiseExit$1, c as String$, ca as pipe, ci as appendAll, cn as addFinalizer, cr as catchAll, ct as onError, d as Union, di as filter, dn as extend, dr as deferredComplete, dt as orElseSucceed, ea as equals, ei as get$4, en as scoped$3, er as match$3, et as map$4, f as between, fi as fromIterable$1, fn as fork, fr as deferredFail, ft as promise, gi as of, gn as fail$3, gr as deferredIsDone, gt as raceWith, hi as map$7, hn as die$1, hr as deferredInterruptWith, ht as race, i as Defect, ia as constUndefined, ii as size$2, in as updateContext$1, ir as zipRight$2, it as matchCause, j as die$2, ji as omit, jn as _await$2, jr as interruptAsFiber, jt as tap, k as catchAllCause, ki as get$5, kn as scopeMake, kr as flatMap$3, kt as suspend$5, l as Struct, li as drop, ln as addFinalizerExit, lr as currentContext$1, lt as orDie, m as optional$1, mi as isEmpty$2, mn as NoSuchElementException, mr as deferredInterrupt, mt as provideService, n as Boolean$, na as constFalse, ni as set$2, nn as unsafeFork, nr as void_$3, nt as mapError, o as Never, oa as dual, oi as isFinite, on as unsafeMakeSemaphore, or as asVoid, ot as matchEffect, p as decodeUnknown, pi as isChunk, pn as make$18, pr as deferredFailCause, pt as provide$2, q as ignore, qi as match$2, qn as all, qr as DeferredTypeId$1, qt as spaced$1, r as Cause, ra as constTrue, ri as has, rn as unsafeRunPromiseExit, rr as zip$2, rt as match$5, s as Number$, sa as identity, si as append$1, sn as Scope, sr as asyncInterrupt, st as negate, t as Array$, ta as hasProperty, ti as make$17, tn as succeed$3, tr as succeed$5, tt as mapBoth$1, u as TaggedError, ui as empty$4, un as close, ur as deferredAwait, ut as orElse, v as encodeSync, vi as reduce, vn as flipCauseOption, vr as deferredSucceed, vt as retry, w as annotateLogs, wi as unsafeGet, wn as map$6, wr as exitSucceed, wt as scopeWith, x as acquireUseRelease$2, xi as takeRight, xn as isDieType, xr as exitAs, xt as runtime, y as _void, yi as reverse, yn as interrupt$3, yr as deferredUnsafeDone, yt as runPromise, z as flatMap$4, zi as isNone, zn as get$3, zr as sync$1, zt as unsafeMakeLatch } from "./chunks/Schema-B5yK7QrT.mjs";
+import { $ as logWarning, $i as format, $n as map$5, $r as make$19, $t as provide$1, A as catchIf, Ai as get$5, An as scopeMake, Ar as flatMap$3, At as suspend$5, B as flatMap$4, Bi as isNone, Bn as get$3, Br as sync$1, Bt as unsafeMakeLatch, C as all$1, Ci as toArray, Cn as isInterrupted, Cr as exitFail, Ct as sandbox, D as async, Di as GenericTag, Dn as squash, Dr as exitZipRight, Dt as scopedWith$1, E as asVoid$1, Ei as unsafeHead, En as reduceWithContext, Er as exitVoid, Et as scoped$4, F as ensuring$2, Fi as splitAt, Fn as join$3, Fr as map$3, Ft as tryMap, G as forkIn, Gi as some, Gn as TypeId$10, Gr as whenEffect, Gt as zipLeft, H as fnUntraced, Hi as map$8, Hn as modify$1, Hr as uninterruptible, Ht as when, I as exit, Ii as filter$1, In as sequential, Ir as onInterrupt, It as tryPromise, J as ignore, Ji as match$2, Jn as all, Jr as DeferredTypeId$1, Jt as spaced$1, K as forkScoped, Ki as isLeft, Kn as Class, Kr as withFiberRuntime, Kt as zipRight$3, L as fail$5, Li as flatMap$5, Ln as bind, Lr as scopeClose, Lt as try_, M as die$2, Mi as omit, Mn as _await$2, Mr as interruptAsFiber, Mt as tap, N as dieMessage, Ni as empty$5, Nn as inheritAll$1, Nr as interruptFiber, Nt as tapErrorCause, O as catchAll$1, Oi as Tag, On as ensuring$3, Or as fiberId, Ot as serviceOption, P as either, Pi as fromIterable, Pn as interruptAllAs$1, Pr as interruptible$1, Pt as timeout, Q as isEffect, Qi as NodeInspectSymbol, Qn as isFailure, Qr as ids, Qt as mergeAll$2, R as failCause$4, Ri as fromNullable, Rn as bindTo, Rr as succeed$4, Rt as uninterruptible$1, S as addFinalizer$1, Si as takeRight, Sn as isDieType, Sr as exitAs, St as runtime, T as as, Ti as unsafeGet, Tn as map$6, Tr as exitSucceed, Tt as scopeWith, U as forEach$2, Ui as match$4, Un as set$1, Ur as uninterruptibleMask$1, Ut as withFiberRuntime$1, V as flatten$4, Vi as isSome, Vn as make$16, Vr as tap$1, Vt as unsafeMakeSemaphore$1, W as forkDaemon, Wi as none, Wn as update$1, Wr as void_$2, Wt as zip$1, X as interruptible, Xi as pipeArguments, Xn as fail$4, Xr as combine, Xt as tagged, Y as interrupt$4, Yi as right, Yn as die, Yr as empty$6, Yt as TaggedError$1, Z as intoDeferred, Zi as BaseProto, Zn as failCause$3, Zr as combineAll, Zt as fromEffect$5, _ as decodeSync, _i as of, _n as fail$3, _r as deferredIsDone, _t as raceWith, a as Literal, aa as constUndefined, ai as size$2, an as updateContext$1, ar as zipRight$2, at as matchCause, b as acquireRelease, bi as reverse, bn as interrupt$3, br as deferredUnsafeDone, bt as runPromise, c as String$, ca as identity, ci as append$1, cn as Scope, cr as asyncInterrupt, ct as negate, d as Union, di as empty$4, dn as close, dr as deferredAwait, dt as orElse, ea as toJSON, ei as none$1, en as provideMerge$1, er as mapBoth, et as makeSemaphore, f as between, fi as filter, fn as extend, fr as deferredComplete, ft as orElseSucceed, gi as map$7, gn as die$1, gr as deferredInterruptWith, gt as race, hi as isEmpty$2, hn as NoSuchElementException, hr as deferredInterrupt, ht as provideService, i as Defect, ia as constTrue, ii as has, in as unsafeRunPromiseExit, ir as zip$2, it as match$5, j as catchTag, ji as getOption, jn as scopeTag, jr as interrupt$2, jt as sync$2, k as catchAllCause, ki as add, kn as forEachConcurrentDiscard, kr as fiberRefLocally, kt as succeed$6, l as Struct, la as pipe, li as appendAll, ln as addFinalizer, lr as catchAll, lt as onError, m as optional$1, mi as isChunk, mn as make$18, mr as deferredFailCause, mt as provide$2, n as Boolean$, na as hasProperty, ni as make$17, nn as succeed$3, nr as succeed$5, nt as mapBoth$1, o as Never, oa as constVoid, oi as decode, on as forkIn$1, or as as$1, ot as matchCauseEffect, p as decodeUnknown, pi as fromIterable$1, pn as fork, pr as deferredFail, pt as promise, q as gen, qi as left, qn as spanTag, qr as zipRight$1, qt as zipWith, r as Cause, ra as constFalse, ri as set$2, rn as unsafeFork, rr as void_$3, rt as mapError, s as Number$, sa as dual, si as isFinite, sn as unsafeMakeSemaphore, sr as asVoid, st as matchEffect, t as Array$, ta as equals, ti as get$4, tn as scoped$3, tr as match$3, tt as map$4, u as TaggedError, ui as drop, un as addFinalizerExit, ur as currentContext$1, ut as orDie, v as encodeSync, vi as prepend, vn as failureOrCause, vr as deferredMake, vt as repeat, w as annotateLogs, wi as unsafeFromArray, wn as isInterruptedOnly, wr as exitFailCause, wt as scope, x as acquireUseRelease$2, xi as take$2, xn as interruptors, xr as deferredUnsafeMake, xt as runPromiseExit$1, y as _void, yi as reduce, yn as flipCauseOption, yr as deferredSucceed, yt as retry, z as fiberIdWith, zi as getOrElse, zn as sleep, zr as suspend$4, zt as uninterruptibleMask } from "./chunks/Schema-CyImoHTj.mjs";
 import { createRequire } from "node:module";
 import * as Crypto from "node:crypto";
 import { createHash } from "node:crypto";
@@ -5401,6 +5401,7 @@ const makeGitImpl = (executor, root) => {
 		}))),
 		hasCommits: () => exec("git", "rev-parse", "--verify", "HEAD").pipe(map$4(() => true), catchAll$1(() => succeed$6(false))),
 		readFileAtRef: (ref, path) => exec("git", "show", `${ref}:${path}`),
+		diffPaths: (base, tip) => exec("git", "diff", "--name-only", "-z", "--no-renames", "--no-relative", "--ignore-submodules=none", "--end-of-options", base, tip, "--").pipe(map$4(splitNul)),
 		changedPaths: (base) => gen(function* () {
 			const ref = base ?? "HEAD";
 			const nameStatusOut = yield* exec("git", "diff", "--name-status", "-z", ref).pipe(catchAll$1(() => succeed$6("")));
@@ -8467,6 +8468,10 @@ const resolveBase = (commandLabel, value) => gen(function* () {
 	return mergeBase.value;
 });
 //#endregion
+//#region src/step/strayPaths.ts
+/** Globs use the `access.write` dialect (`globMatches`). */
+const strayPaths = (touched, allow) => touched.filter((path) => !allow.some((glob) => globMatches(path, glob))).sort();
+//#endregion
 //#region src/edge/Edge.ts
 const EMPTY_TREE$1 = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
 const ACTORS = /* @__PURE__ */ new Set([
@@ -9763,6 +9768,24 @@ const writeSelection = (out, fields, path) => gen(function* () {
 	else if (selection.kind === "unknown") return yield* fail$5(new SelectorUsageError(`gtd: unknown --json selector "${selection.path}" — see \`gtd --help\``));
 });
 //#endregion
+//#region src/cli/Strays.ts
+const resolveSide = (git, side) => git.resolveRef(`${side}^{commit}`).pipe(mapError(() => new GtdError(`gtd strays: unknown revision '${side}'`)));
+/** stdout carries the array alone; the summary is ungated stderr so a quiet run still explains its exit code, the per-path lines are narration. */
+const runStraysCommand = (command, json, out) => gen(function* () {
+	const git = yield* GitService;
+	const narrator = yield* Narrator;
+	const base = yield* resolveSide(git, command.base);
+	const tip = yield* resolveSide(git, command.tip);
+	const touched = yield* git.diffPaths(base, tip);
+	const strays = strayPaths(touched, command.globs);
+	const total = touched.length;
+	if (json.kind === "select") yield* writeSelection(out, strays, json.path).pipe(catchIf((error) => error instanceof SelectorUsageError && /^\d+$/.test(json.path), () => _void));
+	else out.write(`${JSON.stringify(strays)}\n`);
+	for (const path of strays) yield* narrator.narrate(`stray: ${JSON.stringify(path)}`);
+	yield* narrator.warn(strays.length === 0 ? `gtd strays: no strays — ${total} touched files, all inside the allowlist` : `gtd strays: ${strays.length} of ${total} touched files outside the allowlist`);
+	return strays.length === 0 ? 0 : 10;
+});
+//#endregion
 //#region src/cli/History.ts
 /** Newest tip first. */
 const historyEntries = gen(function* () {
@@ -10415,7 +10438,8 @@ const needsOf = (kind) => {
 		case "lsp":
 		case "install":
 		case "loop":
-		case "judgeRun": return "none";
+		case "judgeRun":
+		case "strays": return "none";
 		case "check":
 		case "uncheck": return "fs";
 		default: return "state";
@@ -10424,10 +10448,13 @@ const needsOf = (kind) => {
 /**
 * Dispatches to the named `run*Command` handler for every `Command.kind` —
 * the counterpart of `Cli.ts`'s `parseArgv`, which has already validated
-* every field a handler receives. A command choosing its own exit code is
-* unrepresentable: every branch returns `Effect<void>`, and `Cli.ts`'s
-* `runCli` supplies `EXIT_OK` once, after this Effect succeeds.
+* every field a handler receives. Only `strays` chooses its exit code; every
+* other branch returns `Effect<void>` and resolves to `EXIT_OK`.
 */
+const dispatchCommand = (command, json, out) => {
+	if (command.kind === "strays") return runStraysCommand(command, json, out);
+	return as(dispatchVoidCommand(command, json, out), 0);
+};
 const dispatchVoidCommand = (command, json, out) => {
 	switch (command.kind) {
 		case "lsp": return runLspCommand();
@@ -10467,7 +10494,7 @@ const dispatchVoidCommand = (command, json, out) => {
 * so a refusal writes nothing and emits no script by construction.
 */
 const runCommand$1 = (command, json, out) => {
-	const dispatch = dispatchVoidCommand(command, json, out);
+	const dispatch = dispatchCommand(command, json, out);
 	if (needsOf(command.kind) !== "state") return dispatch;
 	return gen(function* () {
 		const git = yield* GitService;
@@ -10480,7 +10507,7 @@ const runCommand$1 = (command, json, out) => {
 			warn: () => _void
 		}));
 		for (const warning of config.warnings) yield* narrator.warn(`gtd: warning: ${formatDiagnostic(warning)}`);
-		yield* dispatch;
+		return yield* dispatch;
 	});
 };
 //#endregion
@@ -10495,13 +10522,13 @@ const FLAGS = [
 		name: "--json",
 		arity: "optional",
 		repeatable: false,
-		scope: (kind) => kind === "next" || kind === "land" || kind === "judge" || kind === "judgeAnswer" || kind === "doors" || kind === "historyList" || kind === "historyShow",
+		scope: (kind) => kind === "next" || kind === "land" || kind === "judge" || kind === "judgeAnswer" || kind === "doors" || kind === "historyList" || kind === "historyShow" || kind === "strays",
 		decode: ([raw]) => right(raw ?? ""),
-		scopeError: "gtd: --json is only valid for `gtd next`/`gtd land`/`gtd judge`/`gtd judge answer`/`gtd doors`/`gtd history list`/`gtd history show` — every other command prints plain text; see `gtd install` for the driver protocol briefing",
+		scopeError: "gtd: --json is only valid for `gtd next`/`gtd land`/`gtd judge`/`gtd judge answer`/`gtd doors`/`gtd history list`/`gtd history show`/`gtd strays` — every other command prints plain text; see `gtd install` for the driver protocol briefing",
 		valueHint: "<path>",
 		help: [
 			"(gtd next/gtd land/gtd judge/gtd judge answer/gtd doors/gtd history",
-			"list/gtd history show only) output structured JSON. Bare --json prints the whole document;",
+			"list/gtd history show/gtd strays only) output structured JSON. Bare --json prints the whole document;",
 			"--json=<path> (a dotted key path into that document, e.g.",
 			"kind, content, session.id) prints just that value: a",
 			"scalar raw and unquoted, a boolean as true/false, a list",
@@ -11010,6 +11037,28 @@ const COMMAND_ROWS = [
 			"every question, with nothing on stdout"
 		]
 	},
+	{
+		token: "strays",
+		kind: "strays",
+		arity: {
+			name: "range",
+			variadic: "glob"
+		},
+		details: [
+			"List the files <range> (<base>..<tip>, an empty side is HEAD)",
+			"touched in its committed net diff that match none of the",
+			"globs. Anchored at the repo root: * stays within one path",
+			"segment, ** crosses them, everything else is literal — quote",
+			"globs in the shell. stdout: a sorted JSON array, [] when",
+			"clean; stderr: a summary, plus one stray: line per path with",
+			"--verbose. --json=<n> picks one entry, nothing past the end;",
+			"a symlink is a path like any other, never followed; a",
+			"submodule counts as its path, whatever diff.ignoreSubmodules",
+			"or .gitmodules ignore say. Runs in any git repository, no",
+			"process needed. Exits 10 when",
+			"strays were found, 1 on an unknown revision, 2 on a bad range"
+		]
+	},
 	{
 		token: "history list",
 		kind: "historyList",
@@ -11352,6 +11401,22 @@ const parseArgv = (argv) => {
 		json,
 		verbose
 	};
+	if (kind === "strays") {
+		const [range, ...globs] = restPositionals;
+		const at = range.indexOf("..");
+		if (at < 0 || range.includes("...") || range.indexOf("..", at + 1) >= 0) return usagePlan(`gtd strays: <range> must be <base>..<tip> (an empty side is HEAD) — got '${range}'`, jsonSeen);
+		return {
+			kind: "command",
+			command: {
+				kind: "strays",
+				base: range.slice(0, at) || "HEAD",
+				tip: range.slice(at + 2) || "HEAD",
+				globs
+			},
+			json,
+			verbose
+		};
+	}
 	if (kind === "uncheck") return {
 		kind: "command",
 		command: {
@@ -11430,9 +11495,9 @@ const runCli = (argv, io) => {
 	return flatMap$4(Host, ({ env }) => try_({
 		try: () => resolveFlags(env, io.flags),
 		catch: (e) => new GtdError(e.message)
-	})).pipe(flatMap$4(() => runCommand$1(plan.command, plan.json, out)), map$4(() => {
+	})).pipe(flatMap$4(() => runCommand$1(plan.command, plan.json, out)), map$4((code) => {
 		out.flush();
-		io.exit(0);
+		io.exit(code);
 	}), provide$2(io.layers(plan.verbose)), sandbox, catchAll$1((cause) => isInterruptedOnly(cause) ? failCause$4(cause) : report(io, plan.json.kind !== "off")(cause)));
 };
 //#endregion
@@ -11629,6 +11694,10 @@ var InMemRepo = class InMemRepo {
 	changedPathsWorktree(base) {
 		return diffTrees(this.treeAt(base), new Map(this.worktree));
 	}
+	diffPaths(base, tip) {
+		for (const ref of [base, tip]) if (this.resolveRef(ref) === null) throw new Error(`Invalid ref: ${ref}`);
+		return diffTrees(this.treeAt(base), this.treeAt(tip)).map((e) => e.path);
+	}
 	/** The worktree content of `path`, or `undefined` when absent. A LIVE read — never a snapshot. */
 	readFile(path) {
 		return this.worktree.get(path);
@@ -11927,7 +11996,8 @@ const makeGitReaderOps = (repo, root) => ({
 	gitCommonDir: () => succeed$6(`${root}/.git`),
 	commitHistory: (base, head) => succeed$6(repo.commitHistory(base, head)),
 	subjectHistory: (pageSize, skip, head) => succeed$6(repo.subjectHistory(pageSize, skip, head)),
-	changedPaths: (base) => succeed$6(repo.changedPathsWorktree(base))
+	changedPaths: (base) => succeed$6(repo.changedPathsWorktree(base)),
+	diffPaths: (base, tip) => tryCatch(() => repo.diffPaths(base, tip))
 });
 const failOn = (output) => {
 	if (output !== void 0) throw new Error(output);
@@ -12064,6 +12134,13 @@ const missingToolCommands = {
 };
 /** The fine-grained `GitService` layer alone — for unit tests that need only git. */
 const gitTestLayer = (repo, root = "/repo") => succeed$1(GitService, fakeGitOperations(repo, root));
+/**
+* The one sanctioned leak of the real `process.env` into the in-memory `Host`:
+* the runner's `GTD_FLAG_*` state, so a flag-on `npm test` state exercises the
+* flag in memory as it does live. A test asserting one flag side sets the flag
+* itself; explicit env wins.
+*/
+const ambientFlagEnv = (env = process.env) => Object.fromEntries(Object.entries(env).filter((e) => e[0].startsWith("GTD_FLAG_") && e[1] !== void 0));
 /** Every layer `makeProgram` needs — `CommandRequirements`'s return type here IS the guarantee: a new port added there fails this function's typecheck instead of silently under-providing. */
 function testLayers(repo, opts = {}) {
 	const root = opts.root ?? "/repo";
@@ -12071,7 +12148,10 @@ function testLayers(repo, opts = {}) {
 	return mergeAll$1(gitTestLayer(repo, root), succeed$1(Workspace, makeInMemoryWorkspaceOps(repo, root)), Host.layer({
 		root,
 		home,
-		env: opts.env ?? {},
+		env: {
+			...ambientFlagEnv(),
+			...opts.env
+		},
 		realPath: () => succeed$6(root)
 	}), ConfigService.Live, makeInMemoryConfigDiscovery(repo, root), Narrator.layer(opts.narrate ?? (() => {}), opts.verbose ?? true), succeed$1(ToolCommands, {
 		...missingToolCommands,
@@ -13395,7 +13475,7 @@ const PATHOLOGICAL_PATHS = [
 	}
 ];
 /**
-* Exercise all 21 `GitOperations` methods identically against `makeTier()` —
+* Exercise every `GitOperations` methods identically against `makeTier()` —
 * called once per tier by `src/platform/Git.test.ts`. A capability-gated group
 * (`t.capabilities.X`) is skipped, not faked, on a tier that can't support it.
 */
@@ -13430,7 +13510,8 @@ const runGitServiceContract = (makeTier) => {
 			g.subjectHistory(10, 0),
 			g.readFileAtRef("HEAD", "second.txt"),
 			g.changedPaths(),
-			g.changedPaths("HEAD~1")
+			g.changedPaths("HEAD~1"),
+			g.diffPaths("HEAD~1", "HEAD")
 		]));
 		expect(await t.observe.snapshot()).toBe(before);
 		await runGit(t, (g) => g.updateRef("refs/gtd/marker", t.observe.resolveRef("HEAD")));
@@ -13835,6 +13916,71 @@ const runGitServiceContract = (makeTier) => {
 			expect(isFailure(await runGitExit(t, (g) => g.readFileAtRef("HEAD", "nonexistent.txt")))).toBe(true);
 		});
 	});
+	describe("diffPaths", () => {
+		const sorted = (paths) => [...paths].sort();
+		it("reports added, modified and deleted paths between two commits", async () => {
+			t.seed.commit("chore: seed", {
+				"mod.txt": "one",
+				"del.txt": "bye"
+			});
+			const base = t.observe.resolveRef("HEAD");
+			t.seed.writeFile("mod.txt", "two");
+			t.seed.stageAll();
+			t.seed.commitDeletion("del.txt", "chore: delete");
+			t.seed.commit("feat: add", {
+				"add.txt": "new",
+				"mod.txt": "two"
+			});
+			const tip = t.observe.resolveRef("HEAD");
+			const paths = await runGit(t, (g) => g.diffPaths(base, tip));
+			expect(sorted(paths)).toEqual([
+				"add.txt",
+				"del.txt",
+				"mod.txt"
+			]);
+		});
+		it("reports both paths of a rename", async () => {
+			t.seed.commit("chore: seed", { "old.txt": "same content unique-marker\n" });
+			const base = t.observe.resolveRef("HEAD");
+			t.seed.deleteFile("old.txt");
+			t.seed.commit("refactor: rename", { "new.txt": "same content unique-marker\n" });
+			const tip = t.observe.resolveRef("HEAD");
+			expect(sorted(await runGit(t, (g) => g.diffPaths(base, tip)))).toEqual(["new.txt", "old.txt"]);
+		});
+		it("omits a file changed then restored between the endpoints", async () => {
+			t.seed.commit("chore: seed", { "flip.txt": "one" });
+			const base = t.observe.resolveRef("HEAD");
+			t.seed.commit("chore: change", { "flip.txt": "two" });
+			t.seed.commit("chore: restore", { "flip.txt": "one" });
+			const tip = t.observe.resolveRef("HEAD");
+			expect(await runGit(t, (g) => g.diffPaths(base, tip))).toEqual([]);
+		});
+		it("never reports staged, unstaged or untracked changes", async () => {
+			t.seed.commit("chore: seed", {
+				"a.txt": "a",
+				"b.txt": "b"
+			});
+			const base = t.observe.resolveRef("HEAD");
+			t.seed.writeFile("a.txt", "staged");
+			t.seed.stageAll();
+			t.seed.writeFile("b.txt", "unstaged");
+			t.seed.writeFile("untracked.txt", "u");
+			expect(await runGit(t, (g) => g.diffPaths(base, "HEAD"))).toEqual([]);
+		});
+		it("is [] for diffPaths(x, x)", async () => {
+			const head = t.observe.resolveRef("HEAD");
+			expect(await runGit(t, (g) => g.diffPaths(head, head))).toEqual([]);
+		});
+		for (const { label, path } of PATHOLOGICAL_PATHS) it(`reports a path containing ${label}, verbatim`, async () => {
+			const base = t.observe.resolveRef("HEAD");
+			t.seed.commit("feat: pathological", { [path]: "content" });
+			expect(await runGit(t, (g) => g.diffPaths(base, "HEAD"))).toEqual([path]);
+		});
+		it("fails when either side does not resolve", async () => {
+			expect(isFailure(await runGitExit(t, (g) => g.diffPaths("totally-invalid-ref-xyz", "HEAD")))).toBe(true);
+			expect(isFailure(await runGitExit(t, (g) => g.diffPaths("HEAD", "totally-invalid-ref-xyz")))).toBe(true);
+		});
+	});
 	describe("changedPaths", () => {
 		it("unions a tracked modification, a tracked deletion, and an untracked addition, deduplicated by path", async () => {
 			t.seed.commit("chore: seed", {

package/dist/wire.mjs

@@ -1,2 +1,2 @@
-import { C as EXIT_SIGTERM, D as WIRE_SCHEMA, E as UNATTRIBUTED_MODEL, O as renderFormat, S as EXIT_SIGINT, T as ACCESS_REFUSAL, _ as demandOf, a as landFields, b as EXIT_OK, c as renderLandJson, d as renderBeatPlain, f as beatDocument, g as beatKindOf, h as BEAT_KINDS, i as judgeJson, l as renderLandPlain, m as statusOf, n as resolveSession, o as landProseText, p as renderBeatJson, r as selectPath, s as noopText, t as globMatches, u as DEMAND_BRIEFING, v as stallDiagnosis, w as EXIT_USAGE_ERROR, x as EXIT_RUNTIME_ERROR, y as EXIT_CODES } from "./chunks/wire-DA7q2ikx.mjs";
-export { ACCESS_REFUSAL, BEAT_KINDS, DEMAND_BRIEFING, EXIT_CODES, EXIT_OK, EXIT_RUNTIME_ERROR, EXIT_SIGINT, EXIT_SIGTERM, EXIT_USAGE_ERROR, UNATTRIBUTED_MODEL, WIRE_SCHEMA, beatDocument, beatKindOf, demandOf, globMatches, judgeJson, landFields, landProseText, noopText, renderBeatJson, renderBeatPlain, renderFormat, renderLandJson, renderLandPlain, resolveSession, selectPath, stallDiagnosis, statusOf };
+import { C as EXIT_SIGTERM, D as UNATTRIBUTED_MODEL, E as ACCESS_REFUSAL, O as WIRE_SCHEMA, S as EXIT_SIGINT, T as EXIT_USAGE_ERROR, _ as demandOf, a as landFields, b as EXIT_OK, c as renderLandJson, d as renderBeatPlain, f as beatDocument, g as beatKindOf, h as BEAT_KINDS, i as judgeJson, k as renderFormat, l as renderLandPlain, m as statusOf, n as resolveSession, o as landProseText, p as renderBeatJson, r as selectPath, s as noopText, t as globMatches, u as DEMAND_BRIEFING, v as stallDiagnosis, w as EXIT_STRAYS_FOUND, x as EXIT_RUNTIME_ERROR, y as EXIT_CODES } from "./chunks/wire-BY1S-obW.mjs";
+export { ACCESS_REFUSAL, BEAT_KINDS, DEMAND_BRIEFING, EXIT_CODES, EXIT_OK, EXIT_RUNTIME_ERROR, EXIT_SIGINT, EXIT_SIGTERM, EXIT_STRAYS_FOUND, EXIT_USAGE_ERROR, UNATTRIBUTED_MODEL, WIRE_SCHEMA, beatDocument, beatKindOf, demandOf, globMatches, judgeJson, landFields, landProseText, noopText, renderBeatJson, renderBeatPlain, renderFormat, renderLandJson, renderLandPlain, resolveSession, selectPath, stallDiagnosis, statusOf };

package/dist/workflows/feature.mjs

@@ -1,6 +1,6 @@
 import { answered, changes, changesSince, glob, hasThreadFor, head, human, judge, numeric, read, refuse, removeScript, requireAnswers, requireProgress, requireReplies, requireRevert, requireThreadsClosed, restoreScript, revertScript, run, scope, start, vars } from "../flows.mjs";
 import { review as review$1 } from "../workflow-kit.mjs";
-import { $ as unwindFailedMessage, A as architectureDecomposePrompt, B as designSystem, C as fixRisks, D as agentWithSkills, E as reviewing, F as buildReviewFixNitsPrompt, G as packagesItemBuildingPrompt, I as buildReviewTriageMessage, J as reviewEditsCapture, K as packagesItemFixSuitePrompt, L as builderSystem, M as buildReviewAnswerQuestionsPrompt, N as buildReviewAwaitAfterDeferMessage, O as architectSystem, P as buildReviewCollectingPrompt, Q as startGateBlockedMessage, R as deferNotesScript, S as fixCheck, T as reviewMissing, V as designTriagePrompt, W as idleMessage, X as reviewNotesCapture, Z as reviewerSystem, _ as FEEDBACK, b as awaitReview, c as refusePendingHandOff, d as defaults, et as unwindFailure, f as envDefaults, g as ARCHITECTURE, h as healthy, i as skills, j as architectureGateAnswerMessage, k as architectureAuthorPrompt, l as tail, m as gate, n as summary, o as closeReview, q as reviewEditNotesCapture, r as access, t as steering, u as shipped, v as REQUIREMENTS, w as planner, x as coder, y as REVIEW, z as designGateAnswerMessage } from "../chunks/reserved-6pAgFGgB.mjs";
+import { $ as unwindFailedMessage, A as architectureDecomposePrompt, B as designSystem, C as fixRisks, D as agentWithSkills, E as reviewing, F as buildReviewFixNitsPrompt, G as packagesItemBuildingPrompt, I as buildReviewTriageMessage, J as reviewEditsCapture, K as packagesItemFixSuitePrompt, L as builderSystem, M as buildReviewAnswerQuestionsPrompt, N as buildReviewAwaitAfterDeferMessage, O as architectSystem, P as buildReviewCollectingPrompt, Q as startGateBlockedMessage, R as deferNotesScript, S as fixCheck, T as reviewMissing, V as designTriagePrompt, W as idleMessage, X as reviewNotesCapture, Z as reviewerSystem, _ as FEEDBACK, b as awaitReview, c as refusePendingHandOff, d as defaults, et as unwindFailure, f as envDefaults, g as ARCHITECTURE, h as healthy, i as skills, j as architectureGateAnswerMessage, k as architectureAuthorPrompt, l as tail, m as gate, n as summary, o as closeReview, q as reviewEditNotesCapture, r as access, t as steering, u as shipped, v as REQUIREMENTS, w as planner, x as coder, y as REVIEW, z as designGateAnswerMessage } from "../chunks/reserved-BL9krPao.mjs";
 //#region src/workflows/feature/steps.ts
 /** Turn the sketch since `base` into `.gtd/REQUIREMENTS.md`. */
 const triage = (base) => agentWithSkills("triage", designTriagePrompt(base), {

package/dist/workflows/fix.mjs

@@ -1,6 +1,6 @@
 import { read, refuse, removeScript, run, scope, start } from "../flows.mjs";
 import { d as reviewNotes, f as reviewRisks } from "../chunks/steering-DVILanVf.mjs";
-import { D as agentWithSkills, H as finisherSystem, U as fixReviewNotesPrompt, a as REVIEW_ORIG, d as defaults, f as envDefaults, i as skills, n as summary, p as baseline, r as access, s as handOffTail, t as steering, u as shipped, x as coder, y as REVIEW } from "../chunks/reserved-6pAgFGgB.mjs";
+import { D as agentWithSkills, H as finisherSystem, U as fixReviewNotesPrompt, a as REVIEW_ORIG, d as defaults, f as envDefaults, i as skills, n as summary, p as baseline, r as access, s as handOffTail, t as steering, u as shipped, x as coder, y as REVIEW } from "../chunks/reserved-BL9krPao.mjs";
 //#region src/workflows/fix/fix.ts
 /**
 * Fix every note a human left in a handed-off `.gtd/REVIEW.md` and every

package/dist/workflows/review.mjs

@@ -1,5 +1,5 @@
 import { start } from "../flows.mjs";
-import { Y as reviewGateBlockedMessage, c as refusePendingHandOff, d as defaults, f as envDefaults, i as skills, m as gate, n as summary, r as access, s as handOffTail, t as steering, u as shipped } from "../chunks/reserved-6pAgFGgB.mjs";
+import { Y as reviewGateBlockedMessage, c as refusePendingHandOff, d as defaults, f as envDefaults, i as skills, m as gate, n as summary, r as access, s as handOffTail, t as steering, u as shipped } from "../chunks/reserved-BL9krPao.mjs";
 //#region src/workflows/review/review.ts
 /**
 * Pure review of everything since `reviewBase`: a green gate, the quality

package/dist/workflows.mjs

@@ -295,6 +295,11 @@ const requireRevert = (edited, base) => {
 	const quoted = residue.map((path) => `'${path.replace(/'/g, "'\\''")}'`).join(" ");
 	refuse(`gtd land: require-revert: ${residue.join(", ")} still differ from ${base}~1 — the revert did not take. Run \`git checkout ${base}~1 -- ${quoted}\`, then \`gtd land\` again.`);
 };
+[
+	"land: every stray is incidental (a needed import, a test fixture, a renamed call site).",
+	"refactor-first: the strays are a seam change the task needs; land them first as a behaviour-neutral refactor.",
+	"reject: the naive pass solved the task the wrong way; discard it and re-implement, no human; strays a refactor could absorb never count as reject."
+].join("\n");
 //#endregion
 //#region src/flows/factory.ts
 const FACTORY = Symbol.for("@pmelab/gtd/workflow-factory");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmelab/gtd",
-  "version": "26.1.0",
+  "version": "27.1.0",
   "private": false,
   "description": "Git-aware CLI that emits the next prompt for an autonomous coding agent based on the current repository state",
   "bin": {
@@ -106,7 +106,7 @@
     "postbuild": "node scripts/assert-no-test-doubles.mjs",
     "watch": "tsdown --watch",
     "bench:replay": "node scripts/bench-replay.mjs",
-    "test": "turbo run format:check typecheck lint lint:sh lint:boundaries test:unit test:workflows test:e2e:inmem test:e2e:live test:web analyze",
+    "test": "jiti scripts/test-states.main.ts",
     "test:unit": "vitest run --project unit",
     "test:workflows": "vitest run --project workflows",
     "test:watch": "vitest",

package/src/cli/Cli.test.ts

@@ -981,9 +981,60 @@ describe("parseArgv — gtd history", () => {
   })
 })
 
+describe("parseArgv — gtd strays", () => {
+  const strays = (...args: string[]): CliPlan => parseArgv(["node", "gtd.js", "strays", ...args])
+
+  it("splits the range at '..' and carries the globs", () => {
+    const plan = strays("main..feature", "src/**", "*.md")
+    expect(plan).toMatchObject({
+      kind: "command",
+      command: { kind: "strays", base: "main", tip: "feature", globs: ["src/**", "*.md"] },
+    })
+  })
+
+  it("an empty side becomes HEAD; no globs is an empty list", () => {
+    expect(strays("main..")).toMatchObject({
+      command: { base: "main", tip: "HEAD", globs: [] },
+    })
+    expect(strays("..main")).toMatchObject({ command: { base: "HEAD", tip: "main" } })
+    expect(strays("..")).toMatchObject({ command: { base: "HEAD", tip: "HEAD" } })
+  })
+
+  it("a missing range, a range without '..', a '...' range and a second '..' are usage errors", () => {
+    for (const args of [[], ["main"], ["main...feature"], ["a..b..c"]]) {
+      expect(strays(...args).kind).toBe("usage")
+    }
+    const plan = strays("main")
+    if (plan.kind === "usage") expect(plan.message).toContain("<base>..<tip>")
+  })
+
+  it("--json is in scope: bare and selected", () => {
+    expect(strays("a..b", "--json")).toMatchObject({ kind: "command", json: { kind: "document" } })
+    expect(strays("a..b", "--json=0")).toMatchObject({
+      kind: "command",
+      json: { kind: "select", path: "0" },
+    })
+  })
+
+  it("--json's scope error and help name strays", () => {
+    const plan = parseArgv(["node", "gtd.js", "lsp", "--json"])
+    if (plan.kind === "usage") expect(plan.message).toContain("`gtd strays`")
+    expect(renderHelp()).toContain("strays <range> [glob...]")
+    expect(renderHelp()).toContain("gtd strays only")
+  })
+})
+
 describe("standaloneKinds / needsOf", () => {
   it("pins the standalone kinds", () => {
-    expect(standaloneKinds()).toEqual(["lsp", "check", "uncheck", "install", "loop", "judgeRun"])
+    expect(standaloneKinds()).toEqual([
+      "lsp",
+      "check",
+      "uncheck",
+      "install",
+      "loop",
+      "judgeRun",
+      "strays",
+    ])
   })
 
   it("needsOf matches none/fs for the standalone kinds and state for everything else", () => {
@@ -993,6 +1044,7 @@ describe("standaloneKinds / needsOf", () => {
     expect(needsOf("install")).toBe("none")
     expect(needsOf("loop")).toBe("none")
     expect(needsOf("judgeRun")).toBe("none")
+    expect(needsOf("strays")).toBe("none")
     for (const kind of [
       "land",
       "start",

package/src/cli/Cli.ts

@@ -29,7 +29,7 @@ import {
   type JsonMode,
 } from "./Program.js"
 import type { ToolCommands } from "./ToolCommands.js"
-import { EXIT_OK, EXIT_RUNTIME_ERROR, EXIT_USAGE_ERROR } from "../wire/index.js"
+import { EXIT_RUNTIME_ERROR, EXIT_USAGE_ERROR } from "../wire/index.js"
 
 export type { Command, CommandRequirements } from "./Program.js"
 export { needsOf, standaloneKinds } from "./Program.js"
@@ -96,15 +96,16 @@ const FLAGS: readonly FlagRow[] = [
       kind === "judgeAnswer" ||
       kind === "doors" ||
       kind === "historyList" ||
-      kind === "historyShow",
+      kind === "historyShow" ||
+      kind === "strays",
     decode: ([raw]) => Either.right(raw ?? ""),
     scopeError:
-      "gtd: --json is only valid for `gtd next`/`gtd land`/`gtd judge`/`gtd judge answer`/`gtd doors`/`gtd history list`/`gtd history show` — " +
+      "gtd: --json is only valid for `gtd next`/`gtd land`/`gtd judge`/`gtd judge answer`/`gtd doors`/`gtd history list`/`gtd history show`/`gtd strays` — " +
       "every other command prints plain text; see `gtd install` for the driver protocol briefing",
     valueHint: "<path>",
     help: [
       "(gtd next/gtd land/gtd judge/gtd judge answer/gtd doors/gtd history",
-      "list/gtd history show only) output structured JSON. Bare --json prints the whole document;",
+      "list/gtd history show/gtd strays only) output structured JSON. Bare --json prints the whole document;",
       "--json=<path> (a dotted key path into that document, e.g.",
       "kind, content, session.id) prints just that value: a",
       "scalar raw and unquoted, a boolean as true/false, a list",
@@ -667,6 +668,25 @@ const COMMAND_ROWS: readonly CommandRow[] = [
       "every question, with nothing on stdout",
     ],
   },
+  {
+    token: "strays",
+    kind: "strays",
+    arity: { name: "range", variadic: "glob" },
+    details: [
+      "List the files <range> (<base>..<tip>, an empty side is HEAD)",
+      "touched in its committed net diff that match none of the",
+      "globs. Anchored at the repo root: * stays within one path",
+      "segment, ** crosses them, everything else is literal — quote",
+      "globs in the shell. stdout: a sorted JSON array, [] when",
+      "clean; stderr: a summary, plus one stray: line per path with",
+      "--verbose. --json=<n> picks one entry, nothing past the end;",
+      "a symlink is a path like any other, never followed; a",
+      "submodule counts as its path, whatever diff.ignoreSubmodules",
+      "or .gitmodules ignore say. Runs in any git repository, no",
+      "process needed. Exits 10 when",
+      "strays were found, 1 on an unknown revision, 2 on a bad range",
+    ],
+  },
   {
     token: "history list",
     kind: "historyList",
@@ -1228,6 +1248,28 @@ export const parseArgv = (argv: readonly string[]): CliPlan => {
     }
   }
 
+  if (kind === "strays") {
+    const [range, ...globs] = restPositionals as [string, ...string[]]
+    const at = range.indexOf("..")
+    if (at < 0 || range.includes("...") || range.indexOf("..", at + 1) >= 0) {
+      return usagePlan(
+        `gtd strays: <range> must be <base>..<tip> (an empty side is HEAD) — got '${range}'`,
+        jsonSeen,
+      )
+    }
+    return {
+      kind: "command",
+      command: {
+        kind: "strays",
+        base: range.slice(0, at) || "HEAD",
+        tip: range.slice(at + 2) || "HEAD",
+        globs,
+      },
+      json,
+      verbose,
+    }
+  }
+
   if (kind === "uncheck") {
     return {
       kind: "command",
@@ -1419,9 +1461,9 @@ export const runCli = (argv: readonly string[], io: CliIo): Effect.Effect<void,
     // where the whole buffered artifact is known-complete and safe to hand
     // to stdout (a failure discards the buffer instead — see
     // `bufferedArtifactOut`).
-    Effect.map(() => {
+    Effect.map((code) => {
       out.flush()
-      io.exit(EXIT_OK)
+      io.exit(code)
     }),
     Effect.provide(io.layers(plan.verbose)),
     Effect.sandbox,

package/src/cli/Output.ts

@@ -1,6 +1,6 @@
 import { Effect } from "effect"
 import { CommandRunner, GitService, Host, Narrator, Workspace } from "../platform/index.js"
-import { selectPath } from "../wire/index.js"
+import { selectPath, type EXIT_OK, type EXIT_STRAYS_FOUND } from "../wire/index.js"
 import { ConfigDiscovery, ConfigService } from "../workflow/index.js"
 import type { ToolCommands } from "./ToolCommands.js"
 
@@ -66,3 +66,5 @@ export type CommandRequirements =
   | Narrator
   | CommandRunner
   | ToolCommands
+
+export type SuccessExit = typeof EXIT_OK | typeof EXIT_STRAYS_FOUND

package/src/cli/Program.test.ts

@@ -1693,6 +1693,7 @@ describe("runCommand — refuses in a repository with no commits", () => {
     historyList: { kind: "historyList" },
     historyShow: { kind: "historyShow", ref: "x" },
     historyFetch: { kind: "historyFetch", remote: "origin" },
+    strays: { kind: "strays", base: "HEAD", tip: "HEAD", globs: [] },
   }
 
   const stateKinds = (Object.keys(commandFor) as Command["kind"][]).filter(