@pmelab/gtd 9.14.1 → 10.1.0

package/README.md

@@ -108,8 +108,8 @@ commit everything with this message: gtd(human): idle → unwind
 (run `gtd land --json=script | sh` to get the landing script)
 ```
 
-You could run that commit by hand. Take the script instead — it adds the
-precondition checks and retries you would otherwise have to remember:
+You could run that commit by hand. Take the script instead — it spells out the
+exact message and reports what landed:
 
 ```bash
 gtd land --json=script | sh
@@ -256,14 +256,19 @@ coding agent:
 ```
 
 It prints a self-contained briefing that teaches the agent to set the project
-up, build two commands for itself in whatever shell or runtime it runs, and ask
+up, build four commands for itself in whatever shell or runtime it runs, and ask
 you what you want before it starts driving. You get one prompt to paste, not a
-state name to choose. The two commands: a **loop command** that drives beats
-until the process rests, and an **edit command** that opens the steering file
-the process is waiting on right now — falling back to `.gtd/TODO.md` when the
-resting state declares none. That fallback is also how you begin: on a clean
-repository the edit command opens the empty `.gtd/TODO.md`, and whatever you
-write there is the first sketch the whole process gets planned from.
+state name to choose. The four commands: **`gtd-build`** drives beats until the
+process rests; **`gtd-edit`** opens the steering file the process is waiting on
+right now — falling back to `.gtd/TODO.md` when the resting state declares none;
+**`gtd-review <commitish>`** starts a review round over that commitish and
+drives it; **`gtd-fix`** enters the fix process and drives it. The
+`.gtd/TODO.md` fallback is also how you begin: on a clean repository the edit
+command opens the empty `.gtd/TODO.md`, and whatever you write there is the
+first sketch the whole process gets planned from. As a final step, if it finds
+an LSP-capable editor, the briefing also offers to wire up live diagnostics and
+review actions in it — asking first and naming the exact file, and merging
+rather than overwriting your editor's config.
 
 ### The workflow it ships with
 

package/dist/gtd.bundle.mjs

@@ -6514,14 +6514,6 @@ const Equivalence$3 = (self, that) => matchWith(self, that, {
 * @since 2.0.0
 * @category math
 */
-const times = /*#__PURE__*/ dual(2, (self, times) => match$7(self, {
-	onMillis: (millis) => make$42(millis * times),
-	onNanos: (nanos) => make$42(nanos * BigInt(times))
-}));
-/**
-* @since 2.0.0
-* @category math
-*/
 const sum = /*#__PURE__*/ dual(2, (self, that) => matchWith(self, that, {
 	onMillis: (self, that) => make$42(self + that),
 	onNanos: (self, that) => make$42(self + that)
@@ -8120,7 +8112,7 @@ const catchAll$1 = /*#__PURE__*/ dual(2, (self, f) => matchEffect$1(self, {
 	onFailure: f,
 	onSuccess: succeed$8
 }));
-const catchIf$1 = /*#__PURE__*/ dual(3, (self, predicate, f) => catchAllCause$1(self, (cause) => {
+const catchIf = /*#__PURE__*/ dual(3, (self, predicate, f) => catchAllCause$1(self, (cause) => {
 	const either = failureOrCause$1(cause);
 	switch (either._tag) {
 		case "Left": return predicate(either.left) ? f(either.left) : failCause$7(cause);
@@ -9869,10 +9861,6 @@ const defaultServicesWith = (f) => withFiberRuntime$1((fiber) => f(fiber.current
 const clockWith = (f) => defaultServicesWith((services) => f(services.unsafeMap.get(clockTag.key)));
 /** @internal */
 const currentTimeMillis$1 = /*#__PURE__*/ clockWith((clock) => clock.currentTimeMillis);
-/** @internal */
-const randomWith = (f) => defaultServicesWith((services) => f(services.unsafeMap.get(randomTag.key)));
-/** @internal */
-const next$1 = /*#__PURE__*/ randomWith((random) => random.next);
 //#endregion
 //#region node_modules/effect/dist/esm/Boolean.js
 /**
@@ -11367,7 +11355,7 @@ const catchTag$1 = /*#__PURE__*/ dual((args) => isEffect$1(args[0]), (self, ...a
 		for (let i = 0; i < args.length - 1; i++) if (args[i] === tag) return true;
 		return false;
 	};
-	return catchIf$1(self, predicate, f);
+	return catchIf(self, predicate, f);
 });
 const diffFiberRefs = (self) => summarized(self, fiberRefs, diff$2);
 const diffFiberRefsAndRuntimeFlags = (self) => summarized(self, zip$3(fiberRefs, runtimeFlags), ([refs, flags], [refsNew, flagsNew]) => [diff$2(refs, refsNew), diff$3(flags, flagsNew)]);
@@ -11879,7 +11867,7 @@ const fromIterable = (iterable) => {
 	return new MetricBoundariesImpl(pipe(iterable, appendAll$2(of$1(Number.POSITIVE_INFINITY)), dedupe));
 };
 /** @internal */
-const exponential$2 = (options) => pipe(makeBy(options.count - 1, (i) => options.start * Math.pow(options.factor, i)), unsafeFromArray, fromIterable);
+const exponential = (options) => pipe(makeBy(options.count - 1, (i) => options.start * Math.pow(options.factor, i)), unsafeFromArray, fromIterable);
 /** @internal */
 const MetricKeyTypeTypeId = /*#__PURE__*/ Symbol.for("effect/MetricKeyType");
 /** @internal */
@@ -12953,7 +12941,7 @@ const fiberSuccesses = /*#__PURE__*/ counter("effect_fiber_successes", { increme
 /** @internal */
 const fiberFailures = /*#__PURE__*/ counter("effect_fiber_failures", { incremental: true });
 /** @internal */
-const fiberLifetimes = /*#__PURE__*/ tagged$1(/*#__PURE__*/ histogram("effect_fiber_lifetimes", /*#__PURE__*/ exponential$2({
+const fiberLifetimes = /*#__PURE__*/ tagged$1(/*#__PURE__*/ histogram("effect_fiber_lifetimes", /*#__PURE__*/ exponential({
 	start: .5,
 	factor: 2,
 	count: 35
@@ -14396,7 +14384,7 @@ const isEmpty$3 = (self) => {
 	return self.startMillis >= self.endMillis;
 };
 /** @internal */
-const intersect$5 = /*#__PURE__*/ dual(2, (self, that) => {
+const intersect$4 = /*#__PURE__*/ dual(2, (self, that) => {
 	const start = Math.max(self.startMillis, that.startMillis);
 	const end = Math.min(self.endMillis, that.endMillis);
 	return make$23(start, end);
@@ -14449,7 +14437,7 @@ const isEmpty$2 = isEmpty$3;
 * @since 2.0.0
 * @category ordering
 */
-const intersect$4 = intersect$5;
+const intersect$3 = intersect$4;
 /**
 * Calculates the size of the `Interval` as the `Duration` from the start of the
 * interval to the end of the interval.
@@ -14476,14 +14464,14 @@ const make$21 = (intervals) => {
 	};
 };
 /** @internal */
-const intersect$3 = /*#__PURE__*/ dual(2, (self, that) => intersectLoop(self.intervals, that.intervals, empty$24()));
+const intersect$2 = /*#__PURE__*/ dual(2, (self, that) => intersectLoop(self.intervals, that.intervals, empty$24()));
 /** @internal */
 const intersectLoop = (_left, _right, _acc) => {
 	let left = _left;
 	let right = _right;
 	let acc = _acc;
 	while (isNonEmpty$4(left) && isNonEmpty$4(right)) {
-		const interval = pipe(headNonEmpty(left), intersect$4(headNonEmpty(right)));
+		const interval = pipe(headNonEmpty(left), intersect$3(headNonEmpty(right)));
 		const intervals = isEmpty$2(interval) ? acc : pipe(acc, prepend$1(interval));
 		if (pipe(headNonEmpty(left), lessThan$3(headNonEmpty(right)))) left = tailNonEmpty(left);
 		else right = tailNonEmpty(right);
@@ -14520,7 +14508,7 @@ const make$20 = make$21;
 * @since 2.0.0
 * @category utils
 */
-const intersect$2 = intersect$3;
+const intersect$1 = intersect$2;
 /**
 * The start of the earliest interval in the specified `Intervals`.
 *
@@ -15886,15 +15874,6 @@ const uncapitalize = (self) => {
 * @since 2.0.0
 */
 const isNonEmpty$1 = (self) => self.length > 0;
-//#endregion
-//#region node_modules/effect/dist/esm/Random.js
-/**
-* Returns the next numeric value from the pseudo-random number generator.
-*
-* @since 2.0.0
-* @category constructors
-*/
-const next = next$1;
 /** @internal */
 const ScheduleTypeId = /*#__PURE__*/ Symbol.for("effect/Schedule");
 /** @internal */
@@ -16021,18 +16000,9 @@ const checkEffect = /*#__PURE__*/ dual(2, (self, test) => makeWithState(self.ini
 	]);
 })));
 /** @internal */
-const delayedEffect = /*#__PURE__*/ dual(2, (self, f) => modifyDelayEffect(self, (_, delay) => f(delay)));
-/** @internal */
-const delayedSchedule = (schedule) => addDelay(schedule, (x) => x);
-/** @internal */
 const driver = (self) => pipe(make$30([none$4(), self.initial]), map$8((ref) => new ScheduleDriverImpl(self, ref)));
 /** @internal */
-const exponential$1 = (baseInput, factor = 2) => {
-	const base = decode(baseInput);
-	return delayedSchedule(map$5(forever, (i) => times(base, Math.pow(factor, i))));
-};
-/** @internal */
-const intersect$1 = /*#__PURE__*/ dual(2, (self, that) => intersectWith(self, that, intersect$2));
+const intersect = /*#__PURE__*/ dual(2, (self, that) => intersectWith(self, that, intersect$1));
 /** @internal */
 const intersectWith = /*#__PURE__*/ dual(3, (self, that, f) => makeWithState([self.initial, that.initial], (now, input, state) => pipe(zipWith$2(self.step(now, input, state[0]), that.step(now, input, state[1]), (a, b) => [a, b]), flatMap$7(([[lState, out, lDecision], [rState, out2, rDecision]]) => {
 	if (isContinue(lDecision) && isContinue(rDecision)) return intersectWithLoop(self, that, input, lState, out, lDecision.intervals, rState, out2, rDecision.intervals, f);
@@ -16068,23 +16038,6 @@ const intersectWithLoop = (self, that, input, lState, out, lInterval, rState, ou
 	});
 };
 /** @internal */
-const jittered$1 = (self) => jitteredWith(self, {
-	min: .8,
-	max: 1.2
-});
-/** @internal */
-const jitteredWith = /*#__PURE__*/ dual(2, (self, options) => {
-	const { max, min } = Object.assign({
-		min: .8,
-		max: 1.2
-	}, options);
-	return delayedEffect(self, (duration) => map$8(next, (random) => {
-		const d = toMillis(duration);
-		const jittered = d * min * (1 - random) + d * max * random;
-		return millis(jittered);
-	}));
-});
-/** @internal */
 const map$5 = /*#__PURE__*/ dual(2, (self, f) => mapEffect(self, (out) => sync$2(() => f(out))));
 /** @internal */
 const mapEffect = /*#__PURE__*/ dual(2, (self, f) => makeWithState(self.initial, (now, input, state) => flatMap$7(self.step(now, input, state), ([state, out, decision]) => map$8(f(out), (out2) => [
@@ -16122,7 +16075,7 @@ const passthrough = (self) => makeWithState(self.initial, (now, input, state) =>
 	decision
 ])));
 /** @internal */
-const recurs$1 = (n) => whileOutput(forever, (out) => out < n);
+const recurs = (n) => whileOutput(forever, (out) => out < n);
 /** @internal */
 const spaced$1 = (duration) => addDelay(forever, () => duration);
 /** @internal */
@@ -16171,7 +16124,7 @@ const repeat_combined = /*#__PURE__*/ dual(2, (self, options) => {
 		if (typeof applied === "boolean") return succeed$8(applied);
 		return scheduleDefectWrap(applied);
 	}) : withWhile;
-	const withTimes = options.times ? intersect$1(withUntil, recurs$1(options.times)).pipe(map$5((intersectionPair) => intersectionPair[0])) : withUntil;
+	const withTimes = options.times ? intersect(withUntil, recurs(options.times)).pipe(map$5((intersectionPair) => intersectionPair[0])) : withUntil;
 	return scheduleDefectRefail(repeat_Effect(self, withTimes));
 });
 /** @internal */
@@ -16207,7 +16160,7 @@ const fromRetryOptions = (options) => {
 		if (typeof applied === "boolean") return succeed$8(applied);
 		return scheduleDefectWrap(applied);
 	}) : withWhile;
-	return options.times !== void 0 ? intersect$1(withUntil, recurs$1(options.times)) : withUntil;
+	return options.times !== void 0 ? intersect(withUntil, recurs(options.times)) : withUntil;
 };
 /** @internal */
 const retryOrElse_Effect = /*#__PURE__*/ dual(3, (self, policy, orElse) => flatMap$7(driver(policy), (driver) => retryOrElse_EffectLoop(provideServiceEffect(self, CurrentIterationMetadata, get$4(driver.iterationMeta)), driver, (e, out) => provideServiceEffect(orElse(e, out), CurrentIterationMetadata, get$4(driver.iterationMeta)))));
@@ -17449,59 +17402,6 @@ const catchAll = catchAll$1;
 */
 const catchAllCause = catchAllCause$1;
 /**
-* Recovers from specific errors based on a predicate.
-*
-* **When to Use**
-*
-* `catchIf` works similarly to {@link catchSome}, but it allows you to
-* recover from errors by providing a predicate function. If the predicate
-* matches the error, the recovery effect is applied. This function doesn't
-* alter the error type, so the resulting effect still carries the original
-* error type unless a user-defined type guard is used to narrow the type.
-*
-* **Example** (Catching Specific Errors with a Predicate)
-*
-* ```ts
-* import { Effect, Random } from "effect"
-*
-* class HttpError {
-*   readonly _tag = "HttpError"
-* }
-*
-* class ValidationError {
-*   readonly _tag = "ValidationError"
-* }
-*
-* //      ┌─── Effect<string, HttpError | ValidationError, never>
-* //      ▼
-* const program = Effect.gen(function* () {
-*   const n1 = yield* Random.next
-*   const n2 = yield* Random.next
-*   if (n1 < 0.5) {
-*     yield* Effect.fail(new HttpError())
-*   }
-*   if (n2 < 0.5) {
-*     yield* Effect.fail(new ValidationError())
-*   }
-*   return "some result"
-* })
-*
-* //      ┌─── Effect<string, ValidationError, never>
-* //      ▼
-* const recovered = program.pipe(
-*   Effect.catchIf(
-*     // Only handle HttpError errors
-*     (error) => error._tag === "HttpError",
-*     () => Effect.succeed("Recovering from HttpError")
-*   )
-* )
-* ```
-*
-* @since 2.0.0
-* @category Error handling
-*/
-const catchIf = catchIf$1;
-/**
 * Catches and handles specific errors by their `_tag` field, which is used as a
 * discriminator.
 *
@@ -22675,79 +22575,6 @@ const updateContext = updateContext$1;
 //#endregion
 //#region node_modules/effect/dist/esm/Schedule.js
 /**
-* Creates a schedule that recurs indefinitely with exponentially increasing
-* delays.
-*
-* **Details**
-*
-* This schedule starts with an initial delay of `base` and increases the delay
-* exponentially on each repetition using the formula `base * factor^n`, where
-* `n` is the number of times the schedule has executed so far. If no `factor`
-* is provided, it defaults to `2`, causing the delay to double after each
-* execution.
-*
-* @since 2.0.0
-* @category Constructors
-*/
-const exponential = exponential$1;
-/**
-* Combines two schedules, continuing only if both schedules want to continue,
-* using the longer delay.
-*
-* **Details**
-*
-* This function takes two schedules and creates a new schedule that only
-* continues execution if both schedules allow it. The interval between
-* recurrences is determined by the longer delay between the two schedules.
-*
-* The output of the resulting schedule is a tuple containing the outputs of
-* both schedules. The input type is the intersection of both schedules' input
-* types.
-*
-* This is useful when coordinating multiple scheduling conditions where
-* execution should proceed only when both schedules permit it.
-*
-* @see {@link intersectWith} If you need to use a custom merge function.
-*
-* @since 2.0.0
-* @category Composition
-*/
-const intersect = intersect$1;
-/**
-* Returns a new schedule that randomly adjusts the interval size within a
-* range.
-*
-* **Details**
-*
-* This function modifies a schedule so that its delay between executions is
-* randomly varied within a range. By default, the delay is adjusted between
-* `80%` (`0.8 * interval`) and `120%` (`1.2 * interval`) of the original
-* interval size.
-*
-* This is useful for adding randomness to repeated executions, reducing
-* contention in distributed systems, and avoiding synchronized execution
-* patterns that can cause bottlenecks.
-*
-* @see {@link jitteredWith} If you need to specify custom min/max values.
-*
-* @since 2.0.0
-* @category Timing & Delay
-*/
-const jittered = jittered$1;
-/**
-* A schedule that recurs a fixed number of times before terminating.
-*
-* **Details**
-*
-* This schedule will continue executing until it has been stepped `n` times,
-* after which it will stop. The output of the schedule is the current count of
-* recurrences.
-*
-* @category Constructors
-* @since 2.0.0
-*/
-const recurs = recurs$1;
-/**
 * Returns a schedule that recurs continuously, with each repetition
 * spaced by the specified `duration` from the last run.
 *
@@ -192377,7 +192204,7 @@ const ERRORS_MD_PATHS = /* @__PURE__ */ new Set([".gtd/ERRORS.md", "ERRORS.md"])
 * there. An unresolvable `ref` (an empty repo) yields an empty map, so every
 * candidate reads as "not at `ref`".
 */
-const blobsAtRef = (exec, ref, paths) => exec("git", "ls-tree", "-r", "-z", ref, "--", ...paths).pipe(catchIf((e) => !isIndexLockError(e), () => succeed$3("")), map$4((out) => {
+const blobsAtRef = (exec, ref, paths) => exec("git", "ls-tree", "-r", "-z", ref, "--", ...paths).pipe(catchAll(() => succeed$3("")), map$4((out) => {
 	const blobs = /* @__PURE__ */ new Map();
 	for (const entry of splitNul(out)) {
 		const tab = entry.indexOf("	");
@@ -192403,14 +192230,14 @@ const blobsAtRef = (exec, ref, paths) => exec("git", "ls-tree", "-r", "-z", ref,
 * A symlink is the one residual inexactness: hash-object hashes the target's
 * content rather than the link text git stores, and reads as `M`, never `D`.
 */
-const hashObjects = (exec, paths) => exec("git", "hash-object", "--", ...paths).pipe(map$4((out) => new Map(out.trim().split("\n").map((oid, i) => [paths[i] ?? "", oid.trim()]))), catchIf((e) => !isIndexLockError(e), () => succeed$3(/* @__PURE__ */ new Map())));
+const hashObjects = (exec, paths) => exec("git", "hash-object", "--", ...paths).pipe(map$4((out) => new Map(out.trim().split("\n").map((oid, i) => [paths[i] ?? "", oid.trim()]))), catchAll(() => succeed$3(/* @__PURE__ */ new Map())));
 /**
 * Classify every untracked path against `ref`'s tree, by CONTENT: not at
 * `ref` → `A`; different bytes → `M`; identical bytes → no entry. The latter
-* two exist because "untracked" does not mean "new" — the review window's
-* `git reset --mixed <base>` leaves every file the reviewed range ADDED
-* untracked while it's still present at the window's saved head. "Different
-* bytes" goes through `hashObjects`'s clean filters, matching how git itself
+* two exist because "untracked" does not mean "new": against a `ref` older
+* than HEAD, a path can be absent from the index yet already present in
+* `ref`'s tree with the same or different bytes. "Different bytes" goes
+* through `hashObjects`'s clean filters, matching how git itself
 * decides it, so an untouched `text=auto` file is never over-reported `M`.
 */
 const classifyUntracked = (exec, ref, untrackedPaths) => gen(function* () {
@@ -192430,34 +192257,12 @@ const classifyUntracked = (exec, ref, untrackedPaths) => gen(function* () {
 	});
 });
 /**
-* True when `error` is git's `index.lock` contention failure. gtd shares one
-* worktree index with every git-aware tool the reviewer runs, each of which
-* writes the index to refresh its stat cache whenever the review window's
-* `git reset --mixed` wakes it — a pure "couldn't start" failure, so the
-* losing command is safe to retry verbatim.
-*/
-const isIndexLockError = (error) => /index\.lock[\s\S]*File exists|Another git process seems to be running/i.test(error.message);
-const withIndexLockRetry = (eff) => retry(eff, {
-	schedule: intersect(recurs(6), exponential(millis(10), 2)).pipe(jittered),
-	while: (error) => isIndexLockError(error)
-});
-/**
-* Wrap every operation of a `GitOperations` implementation in
-* `withIndexLockRetry`. The ONE place the retry is applied — both
-* `GitService.Live` and the in-memory test layer build their service through
-* this. Never feed a `strictGitOperations` Proxy through this: `Object.keys`
-* on the Proxy only sees the overrides, not the full port.
-*/
-const withIndexLockRetries = (ops) => Object.fromEntries(Object.entries(ops).map(([name, fn]) => [name, (...args) => withIndexLockRetry(fn(...args))]));
-/**
 * Run a command and return its stdout — FAILING on a non-zero exit code with
 * the command line and stderr in the error message. `Command.string` alone
 * silently ignores exit codes, which used to make gtd report success on
 * rejected commits and lose files whose quoted paths broke a swallowed
 * `git add`. Callers that expect a probe to fail handle it with an explicit
-* `catchAll`; `index.lock` contention is retried transparently
-* (`withIndexLockRetries`, applied once to the whole port) before any
-* caller's `catchAll` sees it.
+* `catchAll`.
 */
 const run = (root, ...args) => scoped$3(gen(function* () {
 	const process = yield* (yield* CommandExecutor).start(make$8(...args).pipe(workingDirectory(root), stdout("pipe"), stderr("pipe")));
@@ -192486,7 +192291,7 @@ const makeGitImpl = (executor, root) => {
 		readFileAtRef: (ref, path) => exec("git", "show", `${ref}:${path}`),
 		changedPaths: (base) => gen(function* () {
 			const ref = base ?? "HEAD";
-			const nameStatusOut = yield* exec("git", "diff", "--name-status", "-z", ref).pipe(catchIf((e) => !isIndexLockError(e), () => succeed$3("")));
+			const nameStatusOut = yield* exec("git", "diff", "--name-status", "-z", ref).pipe(catchAll(() => succeed$3("")));
 			const trackedPaths = parseNameStatus(splitNul(nameStatusOut));
 			const untrackedRaw = yield* exec("git", "ls-files", "--others", "--exclude-standard", "-z");
 			const untrackedPaths = splitNul(untrackedRaw);
@@ -192554,7 +192359,7 @@ const makeLiveEffect = gen(function* () {
 	return makeGitImpl(executor, root);
 });
 var GitService = class GitService extends Tag("GitService")() {
-	static Live = effect$1(GitService, makeLiveEffect.pipe(map$4(withIndexLockRetries)));
+	static Live = effect$1(GitService, makeLiveEffect);
 };
 //#endregion
 //#region src/RepoFiles.ts
@@ -193200,146 +193005,13 @@ const updateRef = (ref, hash) => `git update-ref ${shellQuote(ref)} ${shellQuote
 /** `git update-ref -d <ref>` — idempotent: deleting a missing ref is already a no-op in real git. */
 const deleteRef = (ref) => `git update-ref -d ${shellQuote(ref)}`;
 //#endregion
-//#region src/OutcomeScript.ts
-/** The plain-text twin of `printfLine`: substitutes `args` into `fmt`'s `%s` placeholders, in order. */
-const renderFormat = (fmt, ...args) => {
-	let i = 0;
-	return fmt.replace(/%s/g, () => args[i++] ?? "");
-};
-/**
-* A `printf '<fmt>' <args...>` bash statement — `args` are already-valid bash
-* tokens (a variable reference like `"$from"`), never re-quoted here: a value
-* reaches the script as a printf ARGUMENT, never interpolated into the format
-* itself, so a subject or state name containing `%` can never be read as a
-* conversion spec.
-*/
-const printfLine = (fmt, args) => `printf ${shellQuote(fmt)} ${args.join(" ")}`;
-const FMT_ABANDON_NOOP = "no gtd process is underway (resting at \"%s\") — nothing to abandon\n";
-const FMT_ABANDONED = "abandoned the process resting at \"%s\" — HEAD is back at %s (\"%s\"), resting at \"%s\".\nEverything the process produced is kept as uncommitted changes (`git status`); discard them with `git checkout -- . && git clean -fd .gtd` for a clean tree.\n";
-const FMT_RESTORED = "restored the retained history — HEAD is back at %s (\"%s\"), resting at \"%s\". Resume with the loop, or `git reset` to any earlier turn to restart from there.\n";
-/** `no gtd process is underway (resting at "<initial>") — nothing to abandon` — `gtd abandon`'s no-op plain-text line. */
-const abandonNoopText = (initial) => renderFormat(FMT_ABANDON_NOOP, initial);
-/**
-* The bash preamble every outcome-carrying script includes, ONE block (no
-* blank lines) so `assembleScript`'s blank-line-joined sections stay intact.
-* The `${TERM:-}` form (never a bare `$TERM`) is deliberate: `TERM` is
-* legitimately unset in plenty of real shells, and a bare reference would
-* trip `set -u` in the embedding script.
-*/
-const OUTCOME_PREAMBLE = [
-	"# gtd: human-facing outcome rendering (see src/OutcomeScript.ts)",
-	"if [ -t 1 ] && [ -z \"${NO_COLOR:-}\" ] && [ \"${TERM:-}\" != dumb ]; then",
-	"  gtd_c_reset=$(printf '\\033[0m'); gtd_c_bold=$(printf '\\033[1m'); gtd_c_dim=$(printf '\\033[2m')",
-	"  gtd_c_cyan=$(printf '\\033[36m'); gtd_c_green=$(printf '\\033[32m')",
-	"  gtd_m_trans=\"➡️\"; gtd_m_commit=\"✅\"; gtd_m_ellipsis=\"…\"",
-	"else",
-	"  gtd_c_reset=\"\"; gtd_c_bold=\"\"; gtd_c_dim=\"\"",
-	"  gtd_c_cyan=\"\"; gtd_c_green=\"\"",
-	"  gtd_m_trans=\"->\"; gtd_m_commit=\"[commit]\"; gtd_m_ellipsis=\"...\"",
-	"fi",
-	"gtd_files() {",
-	"  gtd_files_sha=\"$1\"",
-	"  gtd_files_shown=0",
-	"  gtd_files_total=0",
-	"  gtd_files_list=\"$(git diff-tree --no-commit-id --name-only -r --root \"$gtd_files_sha\" 2>/dev/null || true)\"",
-	"  [ -z \"$gtd_files_list\" ] && { unset gtd_files_sha gtd_files_f gtd_files_shown gtd_files_total gtd_files_list; return 0; }",
-	"  while IFS= read -r gtd_files_f; do [ -n \"$gtd_files_f\" ] && gtd_files_total=$((gtd_files_total + 1)); done <<EOF",
-	"$gtd_files_list",
-	"EOF",
-	"  while IFS= read -r gtd_files_f; do",
-	"    [ -z \"$gtd_files_f\" ] && continue",
-	"    if [ \"$gtd_files_shown\" -ge 3 ]; then",
-	"      printf '   %s%s (%d more)%s\\n' \"$gtd_c_dim\" \"$gtd_m_ellipsis\" \"$((gtd_files_total - 3))\" \"$gtd_c_reset\"",
-	"      break",
-	"    fi",
-	"    printf '   %s%s%s\\n' \"$gtd_c_dim\" \"$gtd_files_f\" \"$gtd_c_reset\"",
-	"    gtd_files_shown=$((gtd_files_shown + 1))",
-	"  done <<EOF",
-	"$gtd_files_list",
-	"EOF",
-	"  unset gtd_files_sha gtd_files_f gtd_files_shown gtd_files_total gtd_files_list",
-	"}",
-	"gtd_report_transition() {",
-	"  gtd_rt_from=\"$1\"",
-	"  gtd_rt_to=\"$2\"",
-	"  printf '%s %s%s → %s%s\\n' \"$gtd_m_trans\" \"${gtd_c_bold}${gtd_c_cyan}\" \"$gtd_rt_from\" \"$gtd_rt_to\" \"$gtd_c_reset\"",
-	"  gtd_files HEAD",
-	"  unset gtd_rt_from gtd_rt_to",
-	"}",
-	"gtd_report_commit() {",
-	"  gtd_rc_subject=\"$1\"",
-	"  printf '%s %s%s%s\\n' \"$gtd_m_commit\" \"$gtd_c_green\" \"$gtd_rc_subject\" \"$gtd_c_reset\"",
-	"  gtd_files HEAD",
-	"  unset gtd_rc_subject",
-	"}",
-	"gtd_report_note() {",
-	"  printf '%s\\n' \"$1\"",
-	"}",
-	"gtd_report_abandoned() {",
-	"  gtd_ra_from=\"$1\"",
-	"  gtd_ra_head=\"$2\"",
-	"  gtd_ra_state=\"$3\"",
-	"  gtd_ra_short=\"$(git rev-parse --short \"$gtd_ra_head\")\"",
-	"  gtd_ra_subject=\"$(git log -1 --format=%s \"$gtd_ra_head\")\"",
-	`  ${printfLine(FMT_ABANDONED, [
-		"\"$gtd_ra_from\"",
-		"\"$gtd_ra_short\"",
-		"\"$gtd_ra_subject\"",
-		"\"$gtd_ra_state\""
-	])}`,
-	"  unset gtd_ra_from gtd_ra_head gtd_ra_state gtd_ra_short gtd_ra_subject",
-	"}",
-	"gtd_report_restored() {",
-	"  gtd_rr_to=\"$1\"",
-	"  gtd_rr_state=\"$2\"",
-	"  gtd_rr_short=\"$(git rev-parse --short \"$gtd_rr_to\")\"",
-	"  gtd_rr_subject=\"$(git log -1 --format=%s \"$gtd_rr_to\")\"",
-	`  ${printfLine(FMT_RESTORED, [
-		"\"$gtd_rr_short\"",
-		"\"$gtd_rr_subject\"",
-		"\"$gtd_rr_state\""
-	])}`,
-	"  unset gtd_rr_to gtd_rr_state gtd_rr_short gtd_rr_subject",
-	"}"
-].join("\n");
-/** `gtd_report_transition <from> <to>` — a landed self-loop/target-change transition, with its changed-file rows. */
-const transitionOutcome = (from, to) => `gtd_report_transition ${shellQuote(from)} ${shellQuote(to)}`;
-/** `gtd_report_commit <subject>` — a bare capture (a self-loop commit), with its changed-file rows. */
-const commitOutcome = (subject) => `gtd_report_commit ${shellQuote(subject)}`;
-/** `gtd_report_note <text>` — one already-rendered plain line, no marker. */
-const noteOutcome = (text) => `gtd_report_note ${shellQuote(text)}`;
-/** `gtd_report_abandoned <from> <head> <state>` — resolves the post-hoc short hash/subject from `head` (a commitish) in-script. */
-const abandonedOutcome = (from, head, state) => `gtd_report_abandoned ${shellQuote(from)} ${shellQuote(head)} ${shellQuote(state)}`;
-/** `gtd abandon`'s no-op outcome — the same wording `abandonNoopText` renders, printed via `gtd_report_note`. */
-const abandonNoopOutcome = (initial) => noteOutcome(abandonNoopText(initial));
-/** `gtd_report_restored <to> <state>` — resolves the post-hoc short hash/subject from `to` (a commitish) in-script. */
-const restoredOutcome = (to, state) => `gtd_report_restored ${shellQuote(to)} ${shellQuote(state)}`;
-//#endregion
 //#region src/Emit.ts
 /**
-* Closes the time-of-check/time-of-use gap between the CLI resolving
-* `expectedHead` at decide time and the script running later in an unrelated
-* process. A plain `[ ... ] || { ...; exit 1; }`, not `if`/`fi`, so it stays
-* safe under `set -e` (an OR list's left side failing never trips `-e` on its
-* own). Exported so `src/testing/EmittedScriptRecognizer.ts` can re-derive
-* and string-compare this exact shape.
-*
-* The probe is `--verify --quiet`, not bare `git rev-parse HEAD` — load-
-* bearing: against an unborn HEAD (no commits), the bare form prints the
-* literal string `"HEAD"` and exits 128, so it could never match an
-* `expectedHead === ""` comparison. `--verify --quiet` reads an unborn HEAD
-* back as an empty string instead.
-*/
-const headAssertion = (expectedHead) => {
-	const q = shellQuote(expectedHead);
-	return `[ "$(git rev-parse --verify --quiet HEAD 2>/dev/null)" = ${q} ] || { printf 'gtd: repository changed since this script was generated (expected HEAD %s) — re-run gtd\\n' ${q} >&2; exit 1; }`;
-};
-/**
 * `resolveValidateScript`'s guard: when the declared steering file is absent
 * (e.g. before the producing agent has written it at all), there's nothing
 * to format or validate, so the script exits 0 cleanly rather than running
-* the mode's commands against a missing file. An OR list, not `if`, for the
-* same `set -eu` safety `headAssertion` documents.
+* the mode's commands against a missing file. An OR list, not `if`: an OR
+* list's left side failing never trips `set -e` on its own.
 */
 const fileExistsGuard = (file) => `[ -f ${shellQuote(file)} ] || exit 0`;
 /**
@@ -193360,66 +193032,15 @@ const failurePromptWrapper = (command, prompt) => {
 		`fi`
 	].join("\n");
 };
-/**
-* `gtd_retry` `eval`s one already-`shellQuote`d command, mirroring
-* `src/Git.ts`'s `withIndexLockRetry`: retry only on the same two
-* `isIndexLockError` substrings, jittered exponential backoff (~10ms
-* doubling, 6 total attempts), propagating any other failure immediately.
-* `awk` (not the shell — no fractional `sleep`, and no `$RANDOM` under POSIX
-* `sh`/`dash`) computes both the fractional-second delay and its own jitter
-* deterministically, so no external entropy source is needed. POSIX `sh` has
-* no `local`, so every variable is `gtd_`-prefixed and `unset` before each
-* `return` to avoid leaking into the rest of the assembled script.
-*/
-const RETRY_HELPER = [
-	`gtd_retry() {`,
-	`  gtd_cmd=$1`,
-	`  gtd_attempt=1`,
-	`  gtd_delay_ms=10`,
-	`  while true; do`,
-	`    if gtd_out=$(eval "$gtd_cmd" 2>&1); then`,
-	`      [ -n "$gtd_out" ] && printf '%s\\n' "$gtd_out"`,
-	`      unset gtd_cmd gtd_attempt gtd_delay_ms gtd_out gtd_total_ms`,
-	`      return 0`,
-	`    fi`,
-	`    case "$gtd_out" in`,
-	`      *"index.lock"*|*"Another git process seems to be running"*) ;;`,
-	`      *)`,
-	`        printf '%s\\n' "$gtd_out" >&2`,
-	`        unset gtd_cmd gtd_attempt gtd_delay_ms gtd_out gtd_total_ms`,
-	`        return 1`,
-	`        ;;`,
-	`    esac`,
-	`    if [ "$gtd_attempt" -ge 6 ]; then`,
-	`      printf '%s\\n' "$gtd_out" >&2`,
-	`      unset gtd_cmd gtd_attempt gtd_delay_ms gtd_out gtd_total_ms`,
-	`      return 1`,
-	`    fi`,
-	`    gtd_total_ms=$(awk -v attempt="$gtd_attempt" -v ms="$gtd_delay_ms" 'BEGIN { jitter = (attempt * 2654435761) % ms + 1; printf "%.3f", (ms + jitter) / 1000 }')`,
-	`    sleep "$gtd_total_ms"`,
-	`    gtd_delay_ms=$(( gtd_delay_ms * 2 ))`,
-	`    gtd_attempt=$(( gtd_attempt + 1 ))`,
-	`  done`,
-	`}`
-].join("\n");
 const renderStep = (step) => {
-	if (step.kind === "gitWrite") return `gtd_retry ${shellQuote(step.command)}`;
 	if (step.kind === "command" && step.onFailure !== void 0) return failurePromptWrapper(step.command, step.onFailure);
 	return step.command;
 };
-const assembleScript = (preconditions, steps) => {
-	if (steps.length === 0) return "";
-	const sections = ["set -eu"];
-	if (preconditions.expectedHead !== void 0) sections.push(headAssertion(preconditions.expectedHead));
-	if (steps.some((step) => step.kind === "gitWrite")) sections.push(RETRY_HELPER);
-	if (steps.some((step) => step.kind === "outcome")) sections.push(OUTCOME_PREAMBLE);
-	sections.push(...steps.map(renderStep));
-	return sections.join("\n\n");
-};
+const assembleScript = (steps) => steps.length === 0 ? "" : ["set -eu", ...steps.map(renderStep)].join("\n\n");
 /** Build both halves from already-rendered command strings; an empty (or omitted) array produces the empty-string result, so a driver checking `if [ -n "$required" ]` never has to special-case a bare preamble. */
-const emitScripts = (preconditions, required = [], optional = []) => ({
-	required: assembleScript(preconditions, required),
-	optional: assembleScript(preconditions, optional)
+const emitScripts = (required = [], optional = []) => ({
+	required: assembleScript(required),
+	optional: assembleScript(optional)
 });
 /** Exported so `src/testing/EmittedScriptRecognizer.ts` can recognize these by exact string comparison. `printf`, not `echo`, avoids shell-specific backslash-escape quirks. */
 const DID_NOT_RUN_COMMENT = "# gtd emitted this and did NOT run it — pipe it into `sh` to land the turn";
@@ -193444,6 +193065,66 @@ const combinedScript = (required, optional) => {
 	].join("\n");
 };
 //#endregion
+//#region src/OutcomeScript.ts
+/** The plain-text twin of `printfLine`: substitutes `args` into `fmt`'s `%s` placeholders, in order. */
+const renderFormat = (fmt, ...args) => {
+	let i = 0;
+	return fmt.replace(/%s/g, () => args[i++] ?? "");
+};
+/**
+* A `printf '<fmt>' <args...>` bash statement — `args` are already-valid bash
+* tokens (a `shellQuote`d literal, a `"$(git …)"` substitution), never
+* re-quoted here: a value reaches the script as a printf ARGUMENT, never
+* interpolated into the format itself, so a subject or state name containing
+* `%` can never be read as a conversion spec. Markers like `->` are arguments
+* too, keeping every format string free of a leading `-` that a shell's
+* `printf` could mistake for an option. A real newline in `fmt` is emitted as
+* the two-character `\n` escape `printf` itself expands, keeping every emitted
+* statement on one line.
+*/
+const printfLine = (fmt, args) => `${OUTCOME_MARKER}\nprintf ${shellQuote(fmt.replace(/\n/g, "\\n"))} ${args.join(" ")}`;
+/**
+* Marks an emitted block as print-only. Load-bearing beyond documentation:
+* `src/testing/EmittedScriptRecognizer.ts` recognizes an outcome block by
+* this line, and a bare `printf` would be ambiguous with a workflow
+* `script:` command that happens to start the same way.
+*/
+const OUTCOME_MARKER = "# gtd: outcome (print-only)";
+const FMT_ABANDON_NOOP = "no gtd process is underway (resting at \"%s\") — nothing to abandon\n";
+const FMT_ABANDONED = "abandoned the process resting at \"%s\" — HEAD is back at %s (\"%s\"), resting at \"%s\".\nEverything the process produced is kept as uncommitted changes (`git status`); discard them with `git checkout -- . && git clean -fd .gtd` for a clean tree.\n";
+const FMT_RESTORED = "restored the retained history — HEAD is back at %s (\"%s\"), resting at \"%s\". Resume with the loop, or `git reset` to any earlier turn to restart from there.\n";
+/** `no gtd process is underway (resting at "<initial>") — nothing to abandon` — `gtd abandon`'s no-op plain-text line. */
+const abandonNoopText = (initial) => renderFormat(FMT_ABANDON_NOOP, initial);
+/** A landed self-loop/target-change transition. */
+const transitionOutcome = (from, to) => printfLine("%s %s → %s\n", [
+	"'->'",
+	shellQuote(from),
+	shellQuote(to)
+]);
+/** A bare capture (a self-loop commit). */
+const commitOutcome = (subject) => printfLine("%s %s\n", ["'[commit]'", shellQuote(subject)]);
+/** One already-rendered plain line. */
+const noteOutcome = (text) => printfLine("%s\n", [shellQuote(text)]);
+/**
+* Resolves the post-hoc short hash/subject from `head` (a commitish) in-script
+* — this line runs AFTER the reset that made `head` the new HEAD, so neither
+* value is knowable when gtd generates it.
+*/
+const abandonedOutcome = (from, head, state) => printfLine(FMT_ABANDONED, [
+	shellQuote(from),
+	`"$(git rev-parse --short ${shellQuote(head)})"`,
+	`"$(git log -1 --format=%s ${shellQuote(head)})"`,
+	shellQuote(state)
+]);
+/** `gtd abandon`'s no-op outcome — the same wording `abandonNoopText` renders. */
+const abandonNoopOutcome = (initial) => noteOutcome(abandonNoopText(initial));
+/** Resolves the post-hoc short hash/subject from `to` (a commitish) in-script, for the same reason `abandonedOutcome` does. */
+const restoredOutcome = (to, state) => printfLine(FMT_RESTORED, [
+	`"$(git rev-parse --short ${shellQuote(to)})"`,
+	`"$(git log -1 --format=%s ${shellQuote(to)})"`,
+	shellQuote(state)
+]);
+//#endregion
 //#region src/Edge.ts
 const EMPTY_TREE$1 = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
 const subjectOf = (message) => (message.split("\n")[0] ?? "").trim();
@@ -193608,10 +193289,7 @@ const walkProcessBoundary = (history, initialState, includeClosingBoundary) => {
 * would pool across them). HEAD itself being such a boundary yields an EMPTY
 * run (`trace: []`).
 *
-* `head` overrides the literal `HEAD` the walk would otherwise end at:
-* `restAt`'s window-aware branch passes the saved-head hash here while a
-* review window is open, so the trace still covers commits a real `git log`
-* would miss with HEAD rewound to the review base.
+* `head` overrides the literal `HEAD` the walk would otherwise end at.
 *
 * `includeClosingBoundary` (default `false`) is `summaryRun`'s one-flag
 * difference from `currentRun`'s ordinary walk: when set AND the walk's very
@@ -193979,15 +193657,8 @@ const renderDecision = (rest, decision, cost, model) => {
 		command: commitAll(withCostTrailer(decision.subject, cost, model))
 	}, commitDecisionOutcome(decision)];
 };
-/**
-* The `EmitPreconditions` a step's/entry's assembled scripts assert against:
-* `expectedHead` is the resolved HEAD hash the `Rest` snapshot was taken at.
-*/
-const buildPreconditions = (rest) => ({ expectedHead: rest.context.currentCommit });
 /** The `EmittedScripts` a `"commit"` `StepPlan` carries alongside `perform` — built from `renderDecision`'s output. */
-const buildStepScripts = (rest, decision, cost, model) => {
-	return emitScripts(buildPreconditions(rest), renderDecision(rest, decision, cost, model));
-};
+const buildStepScripts = (rest, decision, cost, model) => emitScripts(renderDecision(rest, decision, cost, model));
 /**
 * A no-op is TERMINAL only at a `script` rest: gtd rendered the script, the
 * driver ran it, it left nothing any pattern claims, and re-running it can't
@@ -194095,17 +193766,16 @@ const planEntry = (rest, actor, entry) => gen(function* () {
 		base = resolvedBase.right;
 	}
 	const subject = stateSubject(actor, entryState);
-	const message = withEntryTrailers(subject, {
-		...base !== void 0 ? { base } : {},
-		vars: varOverrides
-	});
 	return {
 		kind: "entry",
 		state: entryState,
 		subject,
-		scripts: emitScripts(buildPreconditions(rest), [{
+		scripts: emitScripts([{
 			kind: "gitWrite",
-			command: commitAll(message)
+			command: commitAll(withEntryTrailers(subject, {
+				...base !== void 0 ? { base } : {},
+				vars: varOverrides
+			}))
 		}, {
 			kind: "outcome",
 			command: commitOutcome(subject)
@@ -205944,7 +205614,7 @@ const landFields = (input) => ({
 const renderLandJson = (fields) => JSON.stringify(fields) + "\n";
 const FMT_NOOP = "nothing to do at \"%s\"\n";
 const FMT_LAND_PROSE = "commit everything with this message: %s\n";
-/** `nothing to do at "<state>"` — a no-op step's plain-text line, and the text a print-only script's `gtd_report_note` carries. */
+/** `nothing to do at "<state>"` — a no-op step's plain-text line, and the text a print-only script's own `printf` carries. */
 const noopText = (state) => renderFormat(FMT_NOOP, state);
 /** `commit everything with this message: <subject>` — plain `gtd land`'s own stdout at a pending diff (no script); `--json` keeps emitting the script itself, unaffected. */
 const landProseText = (subject) => renderFormat(FMT_LAND_PROSE, subject);
@@ -206235,6 +205905,24 @@ f="$(gtd next --json=file)"
 f="\${f:-.gtd/TODO.md}"
 mkdir -p "$(dirname "$f")"
 exec "\${EDITOR:-vi}" "$f"`;
+const REVIEW_COMMAND = `#!/usr/bin/env sh
+set -eu
+GTD_BUILD=~/.local/bin/gtd-build
+if [ -z "\${1:-}" ]; then
+  echo "usage: gtd-review <commitish>" >&2
+  exit 2
+fi
+cd "$(git rev-parse --show-toplevel)"
+script="$(gtd --entry review-gate.check --var reviewBase="$1")"
+sh -c "$script"
+exec "$GTD_BUILD"`;
+const FIX_COMMAND = `#!/usr/bin/env sh
+set -eu
+GTD_BUILD=~/.local/bin/gtd-build
+cd "$(git rev-parse --show-toplevel)"
+script="$(gtd --entry fix-precheck)"
+sh -c "$script"
+exec "$GTD_BUILD"`;
 const HEADER = () => `gtd ${GTD_VERSION$1} — driver protocol\n\ngtd decides and prints; the driver executes. gtd never runs git, never runs\nyour agent, never runs a check script, and never runs a steering mode's own\nformat:/validate: command either — that pair is text in the script gtd next\n--json's validate field (or gtd validate) prints, for the driver to run\nitself ahead of gtd land.\n`;
 const BEAT_PROTOCOL = `
 ## The beat protocol
@@ -206412,14 +206100,14 @@ since moved refuses loudly instead of corrupting anything. Scripts are
 re-runnable and assert their own HEAD precondition — a driver needs no retry
 logic beyond "ask gtd again".
 `;
-const referenceImplementation = () => `
-## Building the user's driver: interview first, then adapt
+const commandSuite = () => `
+## Building the user's command suite: interview first, then adapt
 
-The obligations above are the contract; the sh block below is one WORKED
-EXAMPLE of it. Do not copy it blindly, and do not guess the user's setup —
-INVESTIGATE first, then INTERVIEW, then build a driver shaped by both. Hold
-ONE conversation, not two: the setup steps below come first, because a repo
-that is not set up yet cannot be driven, and the driver-shape questions
+The obligations above are the contract; the four command bodies below are one
+WORKED EXAMPLE of it. Do not copy them blindly, and do not guess the user's
+setup — INVESTIGATE first, then INTERVIEW, then build a suite shaped by both.
+Hold ONE conversation, not four: the setup steps below come first, because a
+repo that is not set up yet cannot be driven, and the suite-shape questions
 follow in the same numbered list.
 
 1. **Investigate the repository and ask the user what they want before
@@ -206438,29 +206126,59 @@ follow in the same numbered list.
    uncommitted config is a pending change, so starting a process without
    committing it first turns the config into the very first thing the
    process plans against. Commit it, THEN start driving.
-4. **Which agent should run the turns?** Whatever coding-agent CLI they
-   already use (default: \`claude\`). Map \`session.id\`/\`session.resume\`
-   onto THAT agent's continuation mechanism (obligation 5); an agent with
-   no session concept just ignores them — memory is an optimization, every
-   prompt is self-contained.
-5. **Under which permission model?** Fully autonomous turns (e.g.
+4. **Which agent should run the turns?** Probe \`PATH\` for the known
+   coding-agent CLIs — \`claude\`, \`codex\`, \`gemini\`, \`cursor-agent\`,
+   \`aider\`, \`opencode\`, \`amp\` — show the user which are actually
+   installed, and ask which one to drive with (default: \`claude\`). Accept
+   a name that was not on the list; the probe is a convenience, not a
+   restriction. The chosen CLI's own flags then replace the \`claude\` lines
+   in the reference body below — its session flags (obligation 5) and its
+   permission model (question 5).
+5. **Under which permission model, and should the workflow's model hints be
+   honored at all?** Fully autonomous turns (e.g.
    \`--dangerously-skip-permissions\`), a sandbox, or the agent's default
-   prompting — their risk tolerance, their call. Also whether the workflow's
-   own \`model\` hints should be honored (default: yes).
-6. **How do they want to invoke it?** A command on PATH (default:
-   \`~/.local/bin/gtd-loop\`), a project task-runner entry, a CI job step —
-   or no artifact at all: YOU drive the beats yourself, following the
-   obligations directly. Pick the runtime to match: bash, their language of
-   choice, anything that reads \`--json=<path>\` and spawns subprocesses.
+   prompting — their risk tolerance, their call. Also ask whether the
+   workflow's own \`model\` hints (resolved in question 6 below) should be
+   honored (default: yes) — answering no means dropping \`--model\` entirely
+   from every prompt line and writing no model exports, so every turn runs
+   on the chosen CLI's own default tier.
+6. **If model hints are honored, resolve them to real model identifiers.**
+   The bundled workflow ships \`plannerModel: smart\` and \`coderModel: base\`.
+   **Those are opaque hints, not model names** — gtd never interprets them,
+   and passing \`--model smart\` to a real CLI fails on the first prompt
+   beat. Derive the chosen CLI's own available models at install time — its
+   \`--help\`, its docs, its own config — never a hardcoded table (a vendor
+   renames a model and a baked-in list goes stale the day it ships). **When
+   the heavier/cheaper mapping is not obvious, ask**: list the CLI's models
+   and let the user pick one per tier — the heavier tier for
+   \`plannerModel\` (triage, design, review), the cheaper tier for
+   \`coderModel\` (build, fix). Write the resolved names as
+   \`GTD_PLANNERMODEL\`/\`GTD_CODERMODEL\` exports at the top of \`gtd-build\`,
+   wrapped in \`# gtd-install: model exports\` / \`# gtd-install: end\`
+   markers — NOT into \`.gtdrc\`. They stay per machine and are never
+   committed, so one person's model choice binds nobody else on the repo.
+   Two consequences follow, both worth stating to the user: \`gtd-review\`
+   and \`gtd-fix\` inherit these exports only because they \`exec\`
+   \`gtd-build\` — anything that drives beats without going through
+   \`gtd-build\` sees the raw \`smart\`/\`base\` hints and fails; and \`GTD_*\` is
+   the highest-precedence config layer, so these exports silently win over
+   a \`plannerModel\`/\`coderModel\` a teammate later commits to \`.gtdrc\`.
 7. **What should happen at the boundaries?** Where the log goes (obligation
    4), and whether halting at a human gate should do anything richer than
    print — desktop notification, terminal-multiplexer status, editor focus —
    which belongs in their wrapper, never in gtd.
-8. **Which editor should the edit command spawn?** Default \`$EDITOR\`, never
-   a hardcoded editor.
-9. **What should the edit command be named?** Suggest
-   \`~/.local/bin/gtd-edit\`, matching the loop command's own default
-   (\`~/.local/bin/gtd-loop\`) — the interview can override either name.
+8. **How do they want to invoke it?** A command on PATH (default:
+   \`~/.local/bin/gtd-build\`), a project task-runner entry, a CI job step —
+   or no artifact at all: YOU drive the beats yourself, following the
+   obligations directly. Pick the runtime to match: bash, their language of
+   choice, anything that reads \`--json=<path>\` and spawns subprocesses.
+9. **Where should the suite live, which editor should \`gtd-edit\` spawn, and
+   does anything need renaming?** Suggest \`~/.local/bin\` for all four —
+   \`gtd-build\`, \`gtd-edit\`, \`gtd-review\`, \`gtd-fix\` — and \`$EDITOR\` (never
+   a hardcoded editor) for the one that opens files. The interview can
+   rename any of the four; whatever name is chosen for \`gtd-build\` is the
+   RESOLVED path baked into \`GTD_BUILD\` in the other two bodies below —
+   never the literal string \`gtd-build\`.
 
 Then build it, and verify safely before the first real drive:
 \`gtd next --json=<path>\`/\`gtd next\` are both pure reads — read/parse them,
@@ -206468,20 +206186,20 @@ check your kind dispatch against the table above, call them as often as you
 like. Nothing happens until you run an emitted script.
 
 The reference rendering in sh (no \`jq\`, no JSON parser at all — each
-\`--json=<path>\` call prints its one value directly; the \`claude\` lines are
-what answers 1–2 replace):
+\`--json=<path>\` call prints its one value directly). Two of the four bodies
+below share one convention: \`GTD_BUILD\` is set once, at the top, to the
+suite's resolved \`gtd-build\` path.
+
+### \`gtd-build\` — the driver loop
+
+The \`claude\` lines are what interview answers 4 and 6 replace. Default path:
+\`~/.local/bin/gtd-build\`.
 
 \`\`\`bash
 ${MINIMAL_DRIVER}
 \`\`\`
-`;
-const editCommand = () => `
-## Building the user's edit command
 
-The loop command above drives beats; it never opens a file for the human. Add
-a second artifact to the same interview (questions 8–9 above): an edit
-command that opens the steering file the process is resting at right now,
-suggested at \`~/.local/bin/gtd-edit\`.
+### \`gtd-edit\` — open the steering file the process is resting at
 
 \`gtd next --json=file\` already reports the file for every state that
 declares one — the edit command needs no new engine surface, just a read and
@@ -206501,12 +206219,115 @@ the first sketch the whole process gets planned from. The same command does
 the same thing at every rest, whether or not a state declares a \`file:\`.
 
 The edit command stops when the editor exits — it never drives the loop. It
-opens a file and returns; the human runs the loop command themselves when
-they are ready.
+opens a file and returns; the human runs \`gtd-build\` themselves when they
+are ready. Default path: \`~/.local/bin/gtd-edit\`.
 
 \`\`\`bash
 ${EDIT_COMMAND}
 \`\`\`
+
+### \`gtd-review <commitish>\` — start a review round and drive it
+
+Runs \`gtd --entry review-gate.check --var reviewBase=<commitish>\`, captured
+by command substitution — never a pipe: a pipeline reports only its LAST
+command's exit status, so \`gtd --entry ... | sh\` under \`set -e\` would sail
+past a refusal and \`exec\` a loop over a process that was never started. It
+runs the captured script, then \`exec\`s the suite's RESOLVED \`gtd-build\`
+path — never the literal string \`gtd-build\`. This is one invocation that
+carries the review all the way to its next human gate, not just a starter:
+\`gtd-review\` on a RED baseline hands off to \`gtd-build\`, which halts at the
+blocked gate and prints it, rather than starting the review. Refuses with
+\`usage: gtd-review <commitish>\` on stderr and exit \`2\` when the commitish is
+missing — nothing was even attempted. Default path: \`~/.local/bin/gtd-review\`.
+
+\`\`\`bash
+${REVIEW_COMMAND}
+\`\`\`
+
+### \`gtd-fix\` — enter the fix process and drive it
+
+Runs \`gtd --entry fix-precheck\`, captured the same way, then \`exec\`s the
+suite's RESOLVED \`gtd-build\` path. \`gtd-fix\` on a GREEN suite is a no-op
+straight back to \`idle\` — the exec'd \`gtd-build\` exits immediately on it.
+Default path: \`~/.local/bin/gtd-fix\`.
+
+\`\`\`bash
+${FIX_COMMAND}
+\`\`\`
+${REINSTALL}`;
+const REINSTALL = `
+## Re-installing: detect and adapt, don't blindly overwrite
+
+A second install on a machine that already has a suite is not a fresh
+install — read each of the four suite paths before writing anything
+(\`gtd-build\`, \`gtd-edit\`, \`gtd-review\`, \`gtd-fix\`), and branch per path:
+
+- Absent — install it, as in a fresh install.
+- Present and content-equal to what this gtd version would emit — say so,
+  change nothing, and skip that command's interview questions entirely.
+- Present and different — show the difference, name the likely cause (a gtd
+  upgrade, or the user's own edit), and ask before overwriting. Never
+  silently replace a file the user may have customised.
+- Unreadable, or present as a directory instead of a file — report it and
+  ask about it, the same as a differing file. Never overwritten.
+
+Drift is detected by comparing CONTENT, never by parsing a version out of
+the installed file — an installed command carries no version marker to
+parse.
+
+\`gtd-build\` needs one exemption before that comparison: the region between
+\`# gtd-install: model exports\` and \`# gtd-install: end\` gets stripped from
+the installed file first. A \`gtd-build\` differing only inside those
+markers is unchanged, and re-asks nothing — the resolved model names are
+per machine, so without this exemption every single re-install would
+report drift on the one command everybody has.
+
+This check scopes to exactly the four suite paths above. \`gtd-loop\` is
+outside it entirely — never read, never diffed, never touched by it in any
+way — an existing \`gtd-loop\` survives untouched beside the new
+\`gtd-build\`, and cleaning it up is the human's own call.
+`;
+const EDITOR_INTEGRATION = `
+## Editor integration: offer it, don't bury it
+
+\`gtd lsp\` runs a language server, started by \`gtd lsp\` itself, speaking LSP
+over \`stdio\`, applying to files under \`.gtd/\`. That is the whole integration
+contract, identical for every editor — this briefing names no specific editor
+and carries no per-editor config recipe.
+
+Find the user's editor from their OWN shell configuration, never a guess:
+check \`$EDITOR\`/\`$VISUAL\` first, then look for an alias or export in their
+shell rc files (\`.zshrc\`, \`.bashrc\`, \`.config/fish/config.fish\`). Ask the
+user outright when that turns up nothing or turns up more than one. When the
+shell configuration names no editor and the user names none either, say
+nothing and move on — don't pitch editor integration to somebody with no
+editor to integrate.
+
+Once an editor is identified, look ITS OWN LSP configuration format up
+yourself — there is no bundled recipe for it. If it is LSP-capable, offer to
+wire \`gtd lsp\` up with a brief explanation (three or four lines, not a copy
+of \`docs/setup.md\`): live diagnostics on \`.gtd/\` steering files, an outline
+of what is left to review, click-to-check review hunks, pick-an-option
+actions on open questions, and a \`gtd.openSteeringFile\` command that jumps
+to the current state's file. Two facts belong in that offer because both
+bite on a fresh repo: \`gtd lsp\` never creates \`.gtd/\`, so
+\`gtd.openSteeringFile\` may point at a path that does not exist yet before
+the first sketch; and \`gtd lsp\` needs no repository root — it is one of the
+commands that skips the root guard.
+
+On yes, edit the editor's own config file yourself — never print a snippet
+and walk away. Integration works without the human touching anything. Three
+guards apply to that write, because it lands outside the repository in a
+file the user shares across every project:
+
+- **Ask first, per editor, naming the exact file** about to change. Silence
+  is not consent for a machine-wide config.
+- **Merge, never overwrite.** Read the existing config, add only the gtd
+  language-server entry, and leave every other key byte-identical.
+- **Skip and report when the entry is already present** — a second install
+  must not append a duplicate server registration. A malformed existing
+  config (unparseable JSON, a TOML syntax error) is a stop-and-report, not a
+  rewrite: name the file that could not be parsed and leave it untouched.
 `;
 const PREREQUISITES = `
 ## Prerequisites and portability
@@ -206523,7 +206344,7 @@ const PREREQUISITES = `
 Any runtime works: the contract is \`--json\`/\`--json=<path>\` in, subprocesses
 out.
 `;
-const renderBriefing = () => HEADER() + BEAT_PROTOCOL + JSON_FIELD_REFERENCE + DRIVER_OBLIGATIONS + RECOVERY + referenceImplementation() + editCommand() + PREREQUISITES;
+const renderBriefing = () => HEADER() + BEAT_PROTOCOL + JSON_FIELD_REFERENCE + DRIVER_OBLIGATIONS + RECOVERY + commandSuite() + EDITOR_INTEGRATION + PREREQUISITES;
 //#endregion
 //#region src/Select.ts
 /**
@@ -206654,7 +206475,6 @@ const runInitCommand = (out) => gen(function* () {
 */
 const normalizeScriptNewline = (script) => script.length === 0 ? script : `${script.replace(/\n+$/, "")}\n`;
 const EMPTY_TREE = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
-const headPreconditions = (currentCommit) => ({ expectedHead: currentCommit });
 /** True for a `"commit"` decision that is an ATTEMPT (`PatternMachine.StepCommit.attempt`) — the one flag `enforceStepGuards` bypasses its own steps for (see its call site). */
 const isAttemptDecision = (decision) => decision.kind === "commit" && decision.attempt === true;
 /** The subject the required script will produce. */
@@ -206665,7 +206485,7 @@ const previewSubject = (decision) => succeed$3(decision.subject);
 * landing script — that's a driver contract now (`gtd next --json`'s
 * `validate` field), not a gtd guarantee (see `resolveSelfValidateCommand`).
 */
-const buildRequiredScript = (rest, decision, cost, model) => succeed$3(emitScripts(headPreconditions(rest.context.currentCommit), renderDecision(rest, decision, cost, model)).required);
+const buildRequiredScript = (rest, decision, cost, model) => succeed$3(emitScripts(renderDecision(rest, decision, cost, model)).required);
 /**
 * Decide the one resulting transition (a commit) for `gtd land`
 * without performing it, authenticating as `rest.actor`. Refusals fail the
@@ -206677,7 +206497,7 @@ const planLanding = (opts = {}) => gen(function* () {
 	const plan = yield* planStep(rest, opts);
 	if (plan.kind === "refusal") return yield* fail$2(new Error(plan.message));
 	if (plan.kind === "noop") {
-		const required = emitScripts({}, [{
+		const required = emitScripts([{
 			kind: "outcome",
 			command: noteOutcome(noopText(plan.state))
 		}]).required;
@@ -206814,7 +206634,7 @@ const runAbandonCommand = (out) => gen(function* () {
 	const initial = initialStateOf(def);
 	const run = yield* currentRun;
 	if (run.trace.length === 0) {
-		const required = emitScripts({}, [{
+		const required = emitScripts([{
 			kind: "outcome",
 			command: abandonNoopOutcome(initial)
 		}]).required;
@@ -206823,11 +206643,10 @@ const runAbandonCommand = (out) => gen(function* () {
 	}
 	const restState = run.trace[run.trace.length - 1].state;
 	if (run.startParentHash === EMPTY_TREE) return yield* fail$2(/* @__PURE__ */ new Error(`gtd abandon: the process underway (resting at "${restState}") starts at the repository's first commit — there is no earlier commit to rewind to`));
-	const tip = yield* git.resolveRef("HEAD");
-	const steps = [
+	const required = emitScripts([
 		{
 			kind: "gitWrite",
-			command: updateRef(HISTORY_REF, tip)
+			command: updateRef(HISTORY_REF, yield* git.resolveRef("HEAD"))
 		},
 		{
 			kind: "gitWrite",
@@ -206837,8 +206656,7 @@ const runAbandonCommand = (out) => gen(function* () {
 			kind: "outcome",
 			command: abandonedOutcome(restState, run.startParentHash, initial)
 		}
-	];
-	const required = emitScripts(headPreconditions(tip), steps).required;
+	]).required;
 	out.write(combinedScript(required, ""));
 });
 /**
@@ -206858,7 +206676,7 @@ const runRestoreCommand = (out) => gen(function* () {
 	const check = yield* restorability(git, headHash, tip);
 	if (!check.ok) return yield* fail$2(/* @__PURE__ */ new Error(`gtd restore: ${check.reason} — HEAD ${headHash.slice(0, 7)} is ahead of the retained tip ${tip.slice(0, 7)}.`));
 	const after = yield* restAt(tip);
-	const steps = [
+	const required = emitScripts([
 		{
 			kind: "gitWrite",
 			command: hardResetTo(tip)
@@ -206871,8 +206689,7 @@ const runRestoreCommand = (out) => gen(function* () {
 			kind: "outcome",
 			command: restoredOutcome(tip, after.state)
 		}
-	];
-	const required = emitScripts(headPreconditions(headHash), steps).required;
+	]).required;
 	out.write(combinedScript(required, ""));
 });
 /**
@@ -206996,18 +206813,17 @@ const resolveValidateScript = (rest) => gen(function* () {
 	if (file === void 0 || mode === void 0) return void 0;
 	const resolved = resolveSteeringMode(rest.def, mode);
 	if (resolved === void 0) return yield* fail$2(new Error(unknownModeMessage(rest.def, rest.state, mode)));
-	const steps = [
-		...yield* modeContradictionSteps(resolved, mode, rest.context),
-		{
-			kind: "command",
-			command: fileExistsGuard(file)
-		},
-		...yield* renderSteeringModeCommandSteps(resolved, file, rest.context)
-	];
 	return {
 		file,
 		mode,
-		script: emitScripts(headPreconditions(rest.context.currentCommit), steps).required
+		script: emitScripts([
+			...yield* modeContradictionSteps(resolved, mode, rest.context),
+			{
+				kind: "command",
+				command: fileExistsGuard(file)
+			},
+			...yield* renderSteeringModeCommandSteps(resolved, file, rest.context)
+		]).required
 	};
 });
 /** The driver-facing `BeatKind` for a currently-resolved rest, the one computation `gatherBeatFields` reads — so a driver's `kind` field can never drift from what it assembled. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmelab/gtd",
-  "version": "9.14.1",
+  "version": "10.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": {