@pmelab/gtd 8.3.0 → 8.4.0

package/dist/gtd.bundle.mjs

@@ -6541,6 +6541,14 @@ const Equivalence$3 = (self, that) => matchWith(self, that, {
 * @since 2.0.0
 * @category math
 */
+const times = /*#__PURE__*/ dual(2, (self, times) => match$6(self, {
+	onMillis: (millis) => make$40(millis * times),
+	onNanos: (nanos) => make$40(nanos * BigInt(times))
+}));
+/**
+* @since 2.0.0
+* @category math
+*/
 const sum = /*#__PURE__*/ dual(2, (self, that) => matchWith(self, that, {
 	onMillis: (self, that) => make$40(self + that),
 	onNanos: (self, that) => make$40(self + that)
@@ -9804,6 +9812,10 @@ 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
 /**
@@ -11786,7 +11798,7 @@ const fromIterable = (iterable) => {
 	return new MetricBoundariesImpl(pipe(iterable, appendAll$2(of$1(Number.POSITIVE_INFINITY)), dedupe));
 };
 /** @internal */
-const exponential = (options) => pipe(makeBy(options.count - 1, (i) => options.start * Math.pow(options.factor, i)), unsafeFromArray, fromIterable);
+const exponential$2 = (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 */
@@ -12860,7 +12872,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({
+const fiberLifetimes = /*#__PURE__*/ tagged$1(/*#__PURE__*/ histogram("effect_fiber_lifetimes", /*#__PURE__*/ exponential$2({
 	start: .5,
 	factor: 2,
 	count: 35
@@ -14303,7 +14315,7 @@ const isEmpty$3 = (self) => {
 	return self.startMillis >= self.endMillis;
 };
 /** @internal */
-const intersect$4 = /*#__PURE__*/ dual(2, (self, that) => {
+const intersect$5 = /*#__PURE__*/ dual(2, (self, that) => {
 	const start = Math.max(self.startMillis, that.startMillis);
 	const end = Math.min(self.endMillis, that.endMillis);
 	return make$22(start, end);
@@ -14356,7 +14368,7 @@ const isEmpty$2 = isEmpty$3;
 * @since 2.0.0
 * @category ordering
 */
-const intersect$3 = intersect$4;
+const intersect$4 = intersect$5;
 /**
 * Calculates the size of the `Interval` as the `Duration` from the start of the
 * interval to the end of the interval.
@@ -14383,14 +14395,14 @@ const make$20 = (intervals) => {
 	};
 };
 /** @internal */
-const intersect$2 = /*#__PURE__*/ dual(2, (self, that) => intersectLoop(self.intervals, that.intervals, empty$24()));
+const intersect$3 = /*#__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$3(headNonEmpty(right)));
+		const interval = pipe(headNonEmpty(left), intersect$4(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);
@@ -14427,7 +14439,7 @@ const make$19 = make$20;
 * @since 2.0.0
 * @category utils
 */
-const intersect$1 = intersect$2;
+const intersect$2 = intersect$3;
 /**
 * The start of the earliest interval in the specified `Intervals`.
 *
@@ -15740,6 +15752,15 @@ 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 */
@@ -15866,9 +15887,18 @@ 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$29([none$4(), self.initial]), map$8((ref) => new ScheduleDriverImpl(self, ref)));
 /** @internal */
-const intersect = /*#__PURE__*/ dual(2, (self, that) => intersectWith(self, that, intersect$1));
+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));
 /** @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$6(([[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);
@@ -15904,6 +15934,23 @@ 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$6(self.step(now, input, state), ([state, out, decision]) => map$8(f(out), (out2) => [
@@ -15941,7 +15988,7 @@ const passthrough = (self) => makeWithState(self.initial, (now, input, state) =>
 	decision
 ])));
 /** @internal */
-const recurs = (n) => whileOutput(forever, (out) => out < n);
+const recurs$1 = (n) => whileOutput(forever, (out) => out < n);
 /** @internal */
 const spaced$1 = (duration) => addDelay(forever, () => duration);
 /** @internal */
@@ -15990,7 +16037,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(withUntil, recurs(options.times)).pipe(map$5((intersectionPair) => intersectionPair[0])) : withUntil;
+	const withTimes = options.times ? intersect$1(withUntil, recurs$1(options.times)).pipe(map$5((intersectionPair) => intersectionPair[0])) : withUntil;
 	return scheduleDefectRefail(repeat_Effect(self, withTimes));
 });
 /** @internal */
@@ -16026,7 +16073,7 @@ const fromRetryOptions = (options) => {
 		if (typeof applied === "boolean") return succeed$8(applied);
 		return scheduleDefectWrap(applied);
 	}) : withWhile;
-	return options.times !== void 0 ? intersect(withUntil, recurs(options.times)) : withUntil;
+	return options.times !== void 0 ? intersect$1(withUntil, recurs$1(options.times)) : withUntil;
 };
 /** @internal */
 const retryOrElse_Effect = /*#__PURE__*/ dual(3, (self, policy, orElse) => flatMap$6(driver(policy), (driver) => retryOrElse_EffectLoop(provideServiceEffect(self, CurrentIterationMetadata, get$4(driver.iterationMeta)), driver, (e, out) => provideServiceEffect(orElse(e, out), CurrentIterationMetadata, get$4(driver.iterationMeta)))));
@@ -20184,6 +20231,79 @@ const provideMerge = provideMerge$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.
 *
@@ -189175,20 +189295,26 @@ const isCommitState = (state) => state.commit !== void 0;
 const contentOf = (state) => state.script ?? state.prompt ?? state.message;
 /** True when a rest at `state` should open the review checkout window (see `StateDef.reviewWindow`). Safe for an unknown state name (returns `false`). */
 const isReviewWindowState = (def, state) => def.states[state]?.reviewWindow === true;
-/** True when `state` anchors the review window's diff base (see `StateDef.reviewBase`). Safe for an unknown state name (returns `false`). */
+/** True when `state` anchors the review window's diff base (see `StateDef.reviewBase`). Safe for an unknown state name (returns `false`). The string/template form of `reviewBase` is NOT a window anchor — this stays narrowed to `=== true` on purpose, never truthy. */
 const isReviewBaseState = (def, state) => def.states[state]?.reviewBase === true;
+/** The named state's `reviewBase` when it is a STRING (an Eta template rendering a commitish that fixes the whole process's diff base — see `StateDef.reviewBase`) — `undefined` when `reviewBase` is `true`, absent, or `state` doesn't exist. Pure accessor only: rendering the template is an edge concern. */
+const entryBaseTemplateOf = (def, state) => {
+	const reviewBase = def.states[state]?.reviewBase;
+	return typeof reviewBase === "string" ? reviewBase : void 0;
+};
 /** True when a step at `state` must be refused if its only change is deleting the state's `file:` (see `StateDef.requireProgress`). Safe for an unknown state name (returns `false`). */
 const isRequireProgressState = (def, state) => def.states[state]?.requireProgress === true;
 /** True when a step at `state` must be refused unless every open question in its `qa`-mode file is answered (see `StateDef.answerGate`). Safe for an unknown state name (returns `false`). */
 const isAnswerGateState = (def, state) => def.states[state]?.answerGate === true;
-/** The workflow's declared review-entry state name (see `StateDef.reviewEntry`) — `gtd review <commitish>` (`src/program.ts`) enters this state to start a new review process. `undefined` when no state declares one; `validateDefinition` guarantees at most one does, so the first (only) match wins. */
-const reviewEntryStateOf = (def) => {
-	for (const [name, state] of Object.entries(def.states)) if (state.reviewEntry === true) return name;
-};
-/** The workflow's declared fix-entry state name (see `StateDef.fixEntry`) — `gtd fix` (`src/program.ts`) enters this state to start a new fix process. `undefined` when no state declares one; `validateDefinition` guarantees at most one does, so the first (only) match wins. */
-const fixEntryStateOf = (def) => {
-	for (const [name, state] of Object.entries(def.states)) if (state.fixEntry === true) return name;
-};
+/**
+* Every declared state that is NOT a commit state, sorted (plain string
+* sort). This is intentionally ALL non-commit states, not just ones that
+* declared `entry: true` — `entry: true` is a reachability/visualizer
+* concern (it seeds `entries.manual`), while this drives the CLI's
+* `--entry <state>` guard and its error message (naming every legal choice),
+* a broader set on purpose.
+*/
+const enterableStates = (def) => Object.keys(def.states).filter((name) => !isCommitState(def.states[name])).sort();
 /** The ` → ` that separates a transition subject's source state from its target. */
 const TRANSITION_SEP = " → ";
 /**
@@ -189197,8 +189323,9 @@ const TRANSITION_SEP = " → ";
 * state being ENTERED and `<from>` the state the authored changes were made
 * in, so the subject reads as what this commit DID, not just where the machine
 * is headed. `from` is optional: when it is omitted or equals `to` (a
-* self-loop, or a manual entry like `gtd review` that has no meaningful
-* source), the subject collapses to the bare `gtd(<actor>): <to>` form.
+* self-loop, or a manual entry like `gtd step <actor> --entry <state>` that
+* has no meaningful source), the subject collapses to the bare
+* `gtd(<actor>): <to>` form.
 * `resolveState` reads back only `<to>` — the ` → ` prefix is human context.
 */
 const stateSubject = (actor, to, from) => from === void 0 || from === to ? `gtd(${actor}): ${to}` : `gtd(${actor}): ${from}${TRANSITION_SEP}${to}`;
@@ -189231,17 +189358,8 @@ const parseStateSubject = (subject) => {
 		from
 	};
 };
-/**
-* The workflow's declared initial state (exactly one `initial: true` state
-* is assumed — `validateDefinition` enforces this at config-load time).
-* Throws if none is declared: a caller invoking `resolveState`/`step`
-* against an unvalidated, malformed definition is a programmer error, not a
-* value this module tries to guess through.
-*/
-const initialStateOf = (def) => {
-	for (const [name, state] of Object.entries(def.states)) if (state.initial === true) return name;
-	throw new Error("workflow definition has no initial state");
-};
+/** The workflow's declared initial state (`entries.default` — required, so there is always a value). */
+const initialStateOf = (def) => def.entries.default;
 /**
 * Every actor declared by ANY state in the workflow — the closed-world
 * vocabulary a parsed subject's actor is checked against by `resolveState`.
@@ -189385,6 +189503,54 @@ const applyRetry = (def, target, trace, visited = /* @__PURE__ */ new Set()) =>
 	return applyRetry(def, targetDef.retry.otherwise, trace, /* @__PURE__ */ new Set([...visited, target]));
 };
 /**
+* A plain string-prefix test: is `state` inside `scope`'s subtree? Sound
+* because `src/Machines.ts` already refuses any local name containing a
+* `.` (a compile-time error), so a qualified name's dotted path segments are
+* unambiguous — no tree walk or parent map needed. `scope === ""` is the
+* root scope and matches every state. Otherwise it's an exact match, or a
+* TRUE dotted descendant (`state.startsWith(scope + ".")`) — a same-prefix
+* SIBLING is deliberately not a match: `inScope("packages.itemx.building",
+* "packages.item")` is `false`, because `"packages.itemx"` merely starts
+* with the characters `"packages.item"` without the `.` separator that
+* would make it an actual descendant.
+*/
+const inScope = (state, scope) => scope === "" || state === scope || state.startsWith(`${scope}.`);
+/**
+* Resolve the memory scope for `state`, given the process `trace` so far.
+* This is a pure primitive a later package's memory-key computation is
+* built on — it never touches git or the filesystem.
+*
+* `undefined` means `state` itself isn't in `scopes` — memory is an
+* optimization, never a correctness input, so this ambiguous case resolves
+* toward "fresh" by refusing to resolve at all. Otherwise the result always
+* carries `state`'s own scope `M = scopes[state]`, plus an `entryIndex`:
+* the trace position where the CURRENT unbroken run of "in `M`'s subtree"
+* rows began, so a state's own conversation can dip into child scopes
+* (`packages.item.health`, `packages.item.spec`, ...) and back without
+* losing its place — only a trace row whose scope is a sibling or ancestor
+* of `M` (not inside `M`'s subtree) breaks the run. `entryIndex: -1` covers
+* both an empty `trace` and a `trace` with nothing ever inside `M`'s
+* subtree — both are "fresh", just for different reasons. A trace row
+* naming a state absent from `scopes` is skipped rather than thrown on —
+* treated as not-in-scope for both membership and run-continuity.
+*/
+const memoryScopeAt = (scopes, state, trace) => {
+	const scope = scopes[state];
+	if (scope === void 0) return void 0;
+	let entryIndex = -1;
+	for (let k = 0; k < trace.length; k++) {
+		const rowScope = scopes[trace[k]];
+		if (rowScope === void 0 || !inScope(rowScope, scope)) continue;
+		const prevScope = k === 0 ? void 0 : scopes[trace[k - 1]];
+		const prevInScope = prevScope !== void 0 && inScope(prevScope, scope);
+		if (k === 0 || !prevInScope) entryIndex = k;
+	}
+	return {
+		scope,
+		entryIndex
+	};
+};
+/**
 * Decide what invoking `invoker` at `state` does — a pure decision, not an
 * effect. Refusals: `invoker` isn't `state`'s declared actor (out-of-turn),
 * or the tree is dirty and no `on` pattern matches (no-match, naming the
@@ -189448,12 +189614,33 @@ const CONTENT_KEYS$1 = [
 	"message",
 	"commit"
 ];
-/** Exactly one `initial: true` state, and it must not be a commit state. */
-const validateInitial = (def, names) => {
-	const initialNames = names.filter((name) => def.states[name].initial === true);
-	if (initialNames.length !== 1) return [`workflow must declare exactly one initial state (found ${initialNames.length}${initialNames.length > 0 ? `: ${initialNames.join(", ")}` : ""})`];
-	const only = initialNames[0];
-	return isCommitState(def.states[only]) ? [`initial state "${only}" must not be a commit state`] : [];
+/**
+* `entries.default` names a defined, non-commit state. Every entry in
+* `entries.manual`, when present, must likewise name a defined, non-commit
+* state distinct from `entries.default` — a manual entry is a DELIBERATE,
+* distinct starting point from the workflow's ordinary "no active cycle"
+* rest (a manual entry requires resting at the default entry before it acts
+* — see `src/program.ts`), so the two must stay distinguishable — and
+* `entries.manual` must carry no duplicate state name within itself.
+*/
+const validateEntries = (def, names) => {
+	const errors = [];
+	const checkEntry = (key, state) => {
+		if (!names.includes(state)) {
+			errors.push(`entries.${key} "${state}" is not a defined state`);
+			return;
+		}
+		if (isCommitState(def.states[state])) errors.push(`entries.${key} "${state}" must not be a commit state`);
+		if (key !== "default" && state === def.entries.default) errors.push(`entries.${key} "${state}" must not be the same state as entries.default`);
+	};
+	checkEntry("default", def.entries.default);
+	const seen = /* @__PURE__ */ new Set();
+	for (const state of def.entries.manual) {
+		checkEntry("manual", state);
+		if (seen.has(state)) errors.push(`entries.manual declares "${state}" more than once`);
+		seen.add(state);
+	}
+	return errors;
 };
 /** Exactly one of script/prompt/message/commit. */
 const validateContentKind = (name, state) => {
@@ -189475,14 +189662,7 @@ const validateModel = (name, state) => {
 	if (isCommitState(state) && state.model !== void 0) errors.push(`state "${name}": a commit state cannot declare "model"`);
 	return errors;
 };
-/** `memory`, when present, must be a non-empty string; forbidden on a commit state — same rule family as `model` (`validateModel`): a commit state is never at rest, so no agent turn there could carry or continue a memory scope. */
-const validateMemory = (name, state) => {
-	const errors = [];
-	if (state.memory !== void 0 && state.memory === "") errors.push(`state "${name}": "memory" must be a non-empty string`);
-	if (isCommitState(state) && state.memory !== void 0) errors.push(`state "${name}": a commit state cannot declare "memory"`);
-	return errors;
-};
-/** `label`, when present, must be a non-empty string; forbidden on a commit state — same rule family as `model`/`memory` (`validateModel`/`validateMemory`): a commit state is never at rest and emits nothing for a driver/viewer to display a label for. */
+/** `label`, when present, must be a non-empty string; forbidden on a commit state — same rule family as `model` (`validateModel`): a commit state is never at rest and emits nothing for a driver/viewer to display a label for. */
 const validateLabel = (name, state) => {
 	const errors = [];
 	if (state.label !== void 0 && state.label === "") errors.push(`state "${name}": "label" must be a non-empty string`);
@@ -189535,10 +189715,10 @@ const validateMode = (def, name, state) => {
 	return errors;
 };
 /**
-* `reviewWindow`/`reviewBase`, when present, are booleans (the compiler
-* enforces the type) — forbidden on a commit state, same rule family as
-* `model`/`file`/`mode`: a commit state is never at rest, so no window ever
-* opens or anchors there.
+* `reviewWindow`/`reviewBase`, when present, are a boolean and a
+* boolean-or-string respectively (the compiler enforces the type) —
+* forbidden on a commit state, same rule family as `model`/`file`/`mode`: a
+* commit state is never at rest, so no window ever opens or anchors there.
 */
 const validateReviewWindow = (name, state) => {
 	if (!isCommitState(state)) return [];
@@ -189548,36 +189728,16 @@ const validateReviewWindow = (name, state) => {
 	return errors;
 };
 /**
-* `reviewEntry`, when present, is forbidden on a commit state (never at
-* rest — same rule family as `reviewWindow`/`reviewBase`) and on the initial
-* state: a review entry is a deliberate, distinct starting point from the
-* workflow's ordinary "no active cycle" rest (`gtd review` itself REQUIRES
-* resting at the initial state before it will act — see `src/program.ts` —
-* so the two must stay distinguishable rather than collapsing into one).
-* The at-most-one-state rule is checked separately, over the whole
-* definition (see `validateReviewEntryUniqueness`), since it isn't a
-* per-state finding.
+* When `reviewBase` is a STRING (the template form — see `StateDef.reviewBase`),
+* its source must be non-blank: a literal `reviewBase: ""` (or whitespace-only)
+* is an authoring error, distinct from the runtime concern of the RENDERED
+* result coming out blank (that refusal lives at the edge, at CLI time — not
+* checked here). Deliberately does NOT check that the template mentions a
+* declared var: a base may legitimately be a literal commitish like `main`.
 */
-const validateReviewEntry = (name, state) => {
-	if (state.reviewEntry === void 0) return [];
-	const errors = [];
-	if (isCommitState(state)) errors.push(`state "${name}": a commit state cannot declare "reviewEntry"`);
-	if (state.initial === true) errors.push(`state "${name}": the initial state cannot declare "reviewEntry"`);
-	return errors;
-};
-/**
-* `fixEntry`, when present, is forbidden on a commit state and on the initial
-* state — the same rule family as `reviewEntry` (see `validateReviewEntry`):
-* `gtd fix` REQUIRES resting at the initial state before it acts, so its entry
-* target must be a distinct state. The at-most-one-state rule is checked
-* separately over the whole definition (see `validateFixEntryUniqueness`).
-*/
-const validateFixEntry = (name, state) => {
-	if (state.fixEntry === void 0) return [];
-	const errors = [];
-	if (isCommitState(state)) errors.push(`state "${name}": a commit state cannot declare "fixEntry"`);
-	if (state.initial === true) errors.push(`state "${name}": the initial state cannot declare "fixEntry"`);
-	return errors;
+const validateReviewBaseTemplate = (name, state) => {
+	if (typeof state.reviewBase !== "string") return [];
+	return state.reviewBase.trim() === "" ? [`state "${name}": "reviewBase" template must not be blank`] : [];
 };
 /**
 * `requireProgress`, when present, is forbidden on a commit state (never at
@@ -189607,16 +189767,6 @@ const validateAnswerGate = (name, state) => {
 	if (state.file === void 0) errors.push(`state "${name}": "answerGate" requires "file"`);
 	return errors;
 };
-/** At most one state may declare `reviewEntry: true` — `gtd review <commitish>` (`src/program.ts`) needs a single, unambiguous state name to enter (see `reviewEntryStateOf`). */
-const validateReviewEntryUniqueness = (def, names) => {
-	const entryNames = names.filter((name) => def.states[name].reviewEntry === true);
-	return entryNames.length > 1 ? [`at most one state may declare "reviewEntry" (found ${entryNames.length}: ${entryNames.join(", ")})`] : [];
-};
-/** At most one state may declare `fixEntry: true` — `gtd fix` (`src/program.ts`) needs a single, unambiguous state name to enter (see `fixEntryStateOf`). */
-const validateFixEntryUniqueness = (def, names) => {
-	const entryNames = names.filter((name) => def.states[name].fixEntry === true);
-	return entryNames.length > 1 ? [`at most one state may declare "fixEntry" (found ${entryNames.length}: ${entryNames.join(", ")})`] : [];
-};
 /** Every `on` row parses, and its target names a defined state. */
 const validateOnEdges = (name, state, names) => {
 	const errors = [];
@@ -189638,28 +189788,25 @@ const validateRetry = (name, state, names) => {
 * Every state is reachable from an ENTRY ROOT by walking `on` targets and
 * `retry.otherwise` redirects (a redirect ENTERS its `otherwise` state exactly
 * like an `on` match enters its target — see `applyRetry` — so both are real
-* edges). The roots are the initial state PLUS the CLI-command entry states
-* (`reviewEntry`/`fixEntry`): a command enters those directly, so a state
-* reachable only from one of them is legitimately reachable, not dead config
-* (without seeding them, e.g. a `fixEntry` check whose only inbound path is
-* `gtd fix` would be wrongly flagged). Plain BFS; targets naming undefined
-* states are skipped here (they are `validateOnEdges`/`validateRetry` findings
-* of their own). Only called when `validateInitial` found no problem: with zero
-* or several `initial` states there is no well-defined start to walk from, and
-* reporting every state as unreachable would bury the real finding.
+* edges). The roots are `def.entries` — `default` PLUS every state named in
+* `entries.manual`: a manual entry is entered directly (`gtd step <actor>
+* --entry <state>`), so a state reachable only from one of them is
+* legitimately reachable, not dead config (without seeding them, e.g. a
+* manual entry whose only inbound path is `--entry` would be wrongly
+* flagged). Plain BFS; targets naming undefined states are skipped here (they
+* are `validateOnEdges`/`validateRetry` findings of their own). Only called
+* when `validateEntries` found no problem: with an invalid `entries` there is
+* no well-defined start to walk from, and reporting every state as
+* unreachable would bury the real finding.
 *
 * An unreachable state is an ERROR, not a warning: a workflow is bound to a
-* project and edited as a project-wide change, so "kept on purpose for manual
-* entry via a hand-authored subject" is not a supported authoring pattern —
-* an unreachable state is a typo'd rename or a leftover, and silently-dead
+* project and edited as a project-wide change, so "kept on purpose for entry
+* via a hand-authored subject" is not a supported authoring pattern — an
+* unreachable state is a typo'd rename or a leftover, and silently-dead
 * config is exactly what load-time validation exists to catch.
 */
 const validateReachability = (def, names) => {
-	const roots = [
-		names.find((name) => def.states[name].initial === true),
-		reviewEntryStateOf(def),
-		fixEntryStateOf(def)
-	].filter((name) => name !== void 0);
+	const roots = [def.entries.default, ...def.entries.manual];
 	const visited = new Set(roots);
 	const queue = [...roots];
 	while (queue.length > 0) {
@@ -189682,13 +189829,11 @@ const validateState = (def, name, names) => {
 		...validateOnEdges(name, state, names),
 		...validateRetry(name, state, names),
 		...validateModel(name, state),
-		...validateMemory(name, state),
 		...validateLabel(name, state),
 		...validateFile(name, state),
 		...validateMode(def, name, state),
 		...validateReviewWindow(name, state),
-		...validateReviewEntry(name, state),
-		...validateFixEntry(name, state),
+		...validateReviewBaseTemplate(name, state),
 		...validateRequireProgress(name, state),
 		...validateAnswerGate(name, state)
 	];
@@ -189696,104 +189841,42 @@ const validateState = (def, name, names) => {
 /**
 * Validate a `WorkflowDefinition`, returning human-readable error strings
 * (empty = valid). Pure — Phase 2 calls this at config-load time. Checks:
-* at least one state; exactly one `initial: true` state (and it must not be
-* a commit state — a workflow can't start already finished, a small
-* addition beyond the plan's literal list, called out here since it's easy
-* to drop if a later phase disagrees); every state declares exactly one
-* content kind; commit states carry no `actor` and no `on`; non-commit
-* states carry an `actor`; every `on` pattern parses and every `on` target
-* and `retry.otherwise` names a defined state; `retry.max` is a
+* at least one state; `entries.default` names a defined, non-commit state,
+* and every entry in `entries.manual`, when present, names a defined,
+* non-commit state distinct from `entries.default` with no duplicate within
+* `entries.manual` itself (see `validateEntries`); every state declares
+* exactly one content kind; commit states carry no `actor` and no `on`;
+* non-commit states carry an `actor`; every `on` pattern parses and every
+* `on` target and `retry.otherwise` names a defined state; `retry.max` is a
 * non-negative integer; `model`, when present, is a non-empty string and is
-* never declared on a commit state; `memory`, when present, is a non-empty
+* never declared on a commit state; `label`, when present, is a non-empty
 * string and is never declared on a commit state (same rule family as
-* `model`); `label`, when present, is a non-empty string and is never
-* declared on a commit state (same rule family as `model`); `file`, when
-* present, is a non-empty
-* string and is never declared on a commit state; `mode`, when present, names
-* a mode the definition knows (a built-in or a `modes:` entry — see
-* `knownModes`), requires a sibling `file`, and is never declared on a commit
-* state; every `modes:` entry declares at least one non-blank
-* `format`/`validate` command; `reviewWindow`/`reviewBase`, when
-* present, are never declared on a commit state; `reviewEntry`/`fixEntry`, when
-* present, are never declared on a commit state or the initial state, and at
-* most one state across the whole workflow may declare each; every state is
-* reachable from an entry root (the initial state plus any `reviewEntry`/
-* `fixEntry` state) by walking `on` targets and `retry.otherwise` redirects
-* (checked only when the initial-state rule itself passed — see
-* `validateReachability`).
+* `model`); `file`, when
+* present, is a non-empty string and is never declared on a commit state;
+* `mode`, when present, names a mode the definition knows (a built-in or a
+* `modes:` entry — see `knownModes`), requires a sibling `file`, and is
+* never declared on a commit state; every `modes:` entry declares at least
+* one non-blank `format`/`validate` command; `reviewWindow`/`reviewBase`,
+* when present, are never declared on a commit state, and a string-form
+* `reviewBase` template must not be blank (see `validateReviewBaseTemplate`);
+* every state is reachable from an entry root (`def.entries` — `default`
+* plus every `entries.manual` state) by walking `on` targets and
+* `retry.otherwise` redirects (checked only when `validateEntries` itself
+* found no problem — see `validateReachability`).
 */
 const validateDefinition = (def) => {
 	const names = Object.keys(def.states);
 	if (names.length === 0) return ["workflow must declare at least one state"];
-	const initialErrors = validateInitial(def, names);
+	const entriesErrors = validateEntries(def, names);
 	return [
-		...initialErrors,
+		...entriesErrors,
 		...validateModes(def),
 		...names.flatMap((name) => validateState(def, name, names)),
-		...validateReviewEntryUniqueness(def, names),
-		...validateFixEntryUniqueness(def, names),
-		...initialErrors.length === 0 ? validateReachability(def, names) : []
+		...entriesErrors.length === 0 ? validateReachability(def, names) : []
 	];
 };
 //#endregion
-//#region src/Submachines.ts
-/**
-* Compile-time SUB-MACHINE EXPANSION (Option C) — a raw → raw pre-pass that runs
-* at the very top of `compileWorkflowConfig` (src/PatternConfig.ts), BEFORE any
-* per-state compilation. It turns two OPTIONAL top-level `workflow:` keys —
-*
-* ```yaml
-* submachines:                 # reusable, parameterized clusters of states
-*   <name>:
-*     params: [<param>, ...]
-*     states: { <local>: <StateDef, with `$param` placeholders> }
-* use:                         # invocations, each expanded into concrete states
-*   - submachine: <name>
-*     as:   { <local>: <concreteName>, ... }   # rename map (default: identity)
-*     with: { <param>: <value>, ... }          # bind each `$param`
-*     set:  { <local>: { <field>: <value> } }  # extra per-instance state fields
-* ```
-*
-* — into ordinary concrete `states`, then strips `submachines`/`use` from its
-* output so the rest of the compiler (and `KNOWN_TOP_KEYS`) only ever sees the
-* familiar `{ vars?, states, modes? }` shape. The pure engine (`PatternMachine`)
-* is entirely unaware sub-machines exist: expansion is a source-authoring
-* convenience with NO runtime footprint. Aliasing
-* each invocation's local state names (via `as:`) to the exact concrete names a
-* hand-written workflow would use makes the expanded definition BYTE-IDENTICAL to
-* the flat one — the guarantee the bundled template's golden test pins
-* (src/workflows/templates.test.ts).
-*
-* ## Two uses of one mechanism
-*
-* - **Dedup** — a multi-instance sub-machine (a gate/loop authored once, invoked
-*   several times with different `with:`/`as:`) removes duplicated states.
-* - **Encapsulation** — a single-instance sub-machine groups a complex cluster
-*   into one named block for source comprehension. It expands 1:1, so it has no
-*   runtime effect; its value is authoring clarity (and a hook for a future
-*   viewer).
-*
-* ## Substitution
-*
-* A `$name` token is resolved from the invocation's `with:` bindings. It is
-* matched ONLY as a WHOLE string value — a field whose entire value is `$name`,
-* or an `on`/`retry.otherwise` target that is exactly `$name` — never as a
-* substring, so bash `$var`/`${var}` inside a `script:` and Eta
-* `<%= it.vars.x %>` inside any content are left untouched. Text that varies per
-* instance (a message, a describe sentence, a prompt) is therefore passed WHOLE
-* as a `$name` binding, not spliced in.
-*
-* An `on`/`retry.otherwise` target that names one of the sub-machine's OWN local
-* states is rewritten through the `as:` rename map (so intra-cluster edges point
-* at the renamed concrete states); any other target passes through verbatim (it
-* names a concrete top-level state, resolved after the merge). `on` PATTERN keys
-* are never touched (they are literal, exactly as the engine treats them).
-*
-* All findings are collected into the shared `errors` array the caller threads
-* through, aggregated with every other config-shape/validation finding into the
-* single error `compileWorkflowConfig` throws — a bad `submachines:`/`use:` fails
-* loudly at load time, never at step time.
-*/
+//#region src/Machines.ts
 const isPlainObject$2 = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
 const describeType$1 = (v) => {
 	if (v === null) return "null";
@@ -189802,256 +189885,325 @@ const describeType$1 = (v) => {
 };
 /** A whole-value parameter reference: a string that is EXACTLY `$name`. */
 const PARAM_REF = /^\$([A-Za-z_][A-Za-z0-9_]*)$/;
-const KNOWN_SUBMACHINE_KEYS = /* @__PURE__ */ new Set(["params", "states"]);
-const KNOWN_INVOCATION_KEYS = /* @__PURE__ */ new Set([
-	"submachine",
-	"as",
-	"with",
-	"set",
-	"name"
-]);
-/** Rewrite an `on`/`retry.otherwise` target: a local -> its concrete name, a `$param` -> its binding, anything else verbatim. */
-const resolveTarget = (target, ctx, errors) => {
-	const m = PARAM_REF.exec(target);
-	if (m) {
-		const value = ctx.params[m[1]];
-		if (value === void 0) {
-			errors.push(`${ctx.where}: target references unbound param "$${m[1]}"`);
-			return target;
-		}
-		if (typeof value !== "string") {
-			errors.push(`${ctx.where}: param "$${m[1]}" used as a target must be a string`);
-			return target;
+const qualify = (path, local) => path === "" ? local : `${path}.${local}`;
+/** A local is a REFERENCE iff its raw value carries a `machine` key. */
+const isRef = (v) => isPlainObject$2(v) && typeof v["machine"] === "string";
+/**
+* Resolve one `with:` value against the CALLER's own bindings: a whole-value
+* `$param` naming one of them passes that binding down verbatim (value AND
+* scope unchanged — the mechanism that makes a threaded param resolve in the
+* grandparent's namespace); anything else is a fresh binding scoped to the
+* caller's own instance (where it was written).
+*/
+const resolveWithValue = (value, callerBindings, callerPath) => {
+	if (typeof value === "string") {
+		const m = PARAM_REF.exec(value);
+		if (m) {
+			const existing = callerBindings[m[1]];
+			if (existing !== void 0) return existing;
 		}
-		return value;
 	}
-	if (ctx.locals.has(target)) return ctx.as[target] ?? target;
-	return target;
+	return {
+		value,
+		scope: callerPath
+	};
 };
-/** Substitute a WHOLE-value `$param` in any scalar string field; non-`$param` strings and non-strings pass through unchanged. */
-const substituteScalar = (value, ctx, errors) => {
+/**
+* Instantiate one local of `machineName` (a state or a reference) into
+* `locals`/`children`, pushing (and skipping only this local for) a dotted
+* name. A reference recurses via `instantiate`, first resolving its `with:`
+* bindings against the CALLER's own bindings (see `resolveWithValue`).
+*/
+const instantiateLocal = (localName, def, machineName, path, nextAncestors, bindings, ctx, locals, children) => {
+	if (localName.includes(".")) {
+		ctx.errors.push(`machine "${machineName}": local name "${localName}" must not contain "."`);
+		return;
+	}
+	if (!isRef(def)) {
+		locals.set(localName, { kind: "state" });
+		return;
+	}
+	locals.set(localName, {
+		kind: "ref",
+		refKey: localName
+	});
+	ctx.referenced.add(def.machine);
+	const withRaw = isPlainObject$2(def.with) ? def.with : {};
+	const childBindings = {};
+	for (const [key, value] of Object.entries(withRaw)) childBindings[key] = resolveWithValue(value, bindings, path);
+	const child = instantiate(def.machine, qualify(path, localName), nextAncestors, childBindings, ctx, `machines.${machineName}.${localName}`);
+	if (child !== void 0) children.push(child);
+};
+/**
+* Instantiate one machine at `path`, recursing into every local reference.
+* Pushes (and skips only the offending subtree/local for) a cycle, an
+* unknown `machine:` name, or a dotted local name. `unknownLocation` is the
+* finding's location prefix if `machineName` itself doesn't resolve (the
+* reference site for a child, `entry.default` for the root).
+*/
+const instantiate = (machineName, path, ancestorChain, bindings, ctx, unknownLocation) => {
+	if (ancestorChain.includes(machineName)) {
+		ctx.errors.push(`machine reference cycle: ${[...ancestorChain, machineName].join(" → ")}`);
+		return;
+	}
+	const rawMachine = ctx.machinesRaw[machineName];
+	if (rawMachine === void 0) {
+		ctx.errors.push(`${unknownLocation}: unknown machine "${machineName}"`);
+		return;
+	}
+	if (!isPlainObject$2(rawMachine) || !isPlainObject$2(rawMachine["states"])) {
+		ctx.errors.push(`machine "${machineName}": must declare a "states" mapping`);
+		return;
+	}
+	const statesRaw = rawMachine["states"];
+	const locals = /* @__PURE__ */ new Map();
+	const children = [];
+	const nextAncestors = [...ancestorChain, machineName];
+	for (const [localName, def] of Object.entries(statesRaw)) instantiateLocal(localName, def, machineName, path, nextAncestors, bindings, ctx, locals, children);
+	const instance = {
+		path,
+		machine: machineName,
+		bindings,
+		locals,
+		children
+	};
+	ctx.instancesByPath.set(path, instance);
+	return instance;
+};
+/** Resolve a `$param` target: recurse into the binding's own scope instance (see "Bindings carry their scope"), or report it unbound. */
+const resolveParamTarget = (name, instance, instancesByPath, machinesRaw, trail) => {
+	const binding = instance.bindings[name];
+	if (binding === void 0 || typeof binding.value !== "string") return {
+		kind: "unbound",
+		name,
+		trail
+	};
+	const scopeInstance = instancesByPath.get(binding.scope);
+	if (scopeInstance === void 0) return {
+		kind: "unbound",
+		name,
+		trail
+	};
+	return resolveCore(binding.value, scopeInstance, instancesByPath, machinesRaw, trail);
+};
+/** Resolve a local-of-`instance` target: a state (no remainder) qualifies directly; a reference recurses into its child, through its own `entry:` when there's no remainder. */
+const resolveLocalTarget = (first, remainder, instance, instancesByPath, machinesRaw, trail) => {
+	const local = instance.locals.get(first);
+	if (local === void 0 || local.kind === "state" && remainder !== void 0) return {
+		kind: "invalid",
+		machine: instance.machine,
+		trail
+	};
+	if (local.kind === "state") return {
+		kind: "ok",
+		value: qualify(instance.path, first),
+		trail
+	};
+	const child = instancesByPath.get(qualify(instance.path, first));
+	if (child === void 0) return {
+		kind: "invalid",
+		machine: instance.machine,
+		trail
+	};
+	if (remainder === void 0) {
+		const childMachine = machinesRaw[child.machine];
+		const childEntry = isPlainObject$2(childMachine) ? childMachine["entry"] : void 0;
+		if (typeof childEntry !== "string") return {
+			kind: "invalid",
+			machine: child.machine,
+			trail
+		};
+		return resolveCore(childEntry, child, instancesByPath, machinesRaw, [...trail, first]);
+	}
+	return resolveCore(remainder, child, instancesByPath, machinesRaw, trail);
+};
+/**
+* The pure target resolution at the heart of this module — see the "The
+* resolver" section of the module doc comment. `trail` accumulates the
+* reference-key breadcrumb for a "reference, no remainder" hop (recursing
+* into a machine's own `entry:`), so a finding surfacing from deep inside
+* that recursion can still name the reference it went through.
+*/
+const resolveCore = (target, instance, instancesByPath, machinesRaw, trail = []) => {
+	const paramMatch = PARAM_REF.exec(target);
+	if (paramMatch) return resolveParamTarget(paramMatch[1], instance, instancesByPath, machinesRaw, trail);
+	const dotIdx = target.indexOf(".");
+	const first = dotIdx === -1 ? target : target.slice(0, dotIdx);
+	const remainder = dotIdx === -1 ? void 0 : target.slice(dotIdx + 1);
+	return resolveLocalTarget(first, remainder, instance, instancesByPath, machinesRaw, trail);
+};
+const formatTrail = (where, trail) => trail.length > 0 ? `${where} (${trail.join(" → ")})` : where;
+/** Resolve an `on`/`retry.otherwise` target, pushing the "on target" sideways/upward wording on failure. */
+const resolveOnTarget = (target, instance, where, instancesByPath, machinesRaw, errors) => {
+	const result = resolveCore(target, instance, instancesByPath, machinesRaw);
+	const label = formatTrail(where, result.trail);
+	if (result.kind === "ok") return result.value;
+	if (result.kind === "unbound") {
+		errors.push(`${label}: references unbound param "$${result.name}"`);
+		return;
+	}
+	errors.push(`${label}: "on" target "${target}" is not a state or reference of machine "${result.machine}" — declare a "params:" entry and bind it at the reference site`);
+};
+/** Resolve the root machine's own `entry:` (`entry.default`), pushing the distinct "entry" wording on failure. */
+const resolveEntry = (entryKey, target, instance, instancesByPath, machinesRaw, errors) => {
+	const result = resolveCore(target, instance, instancesByPath, machinesRaw);
+	if (result.kind === "ok") return result.value;
+	if (result.kind === "unbound") {
+		errors.push(`"${entryKey}" references unbound param "$${result.name}"`);
+		return;
+	}
+	errors.push(`"${entryKey}" names "${target}", which is not a state or machine reference`);
+};
+/** Substitute a WHOLE-value `$param` in any scalar field against `instance`'s own bindings — a literal splice, no scope-aware resolution. */
+const substituteScalar = (value, instance, where, errors) => {
 	if (typeof value !== "string") return value;
 	const m = PARAM_REF.exec(value);
 	if (!m) return value;
-	const bound = ctx.params[m[1]];
-	if (bound === void 0) {
-		errors.push(`${ctx.where}: references unbound param "$${m[1]}"`);
+	const name = m[1];
+	const binding = instance.bindings[name];
+	if (binding === void 0) {
+		errors.push(`${where}: references unbound param "$${name}"`);
 		return value;
 	}
-	return bound;
+	return binding.value;
 };
-/** Rewrite the `on` mapping — each row's target (string, or `{ to, describe }`) — preserving pattern keys and declaration order. */
-const expandOn = (raw, ctx, errors) => {
+/** Rewrite one object-form `on` row (`{ to, describe?, action? }`): `to` through the resolver, `describe`/`action` through whole-value `$param` substitution. */
+const emitOnObjectEdge = (value, instance, where, instancesByPath, machinesRaw, errors) => {
+	const next = { ...value };
+	if (typeof value["to"] === "string") next["to"] = resolveOnTarget(value["to"], instance, where, instancesByPath, machinesRaw, errors) ?? value["to"];
+	if (typeof value["describe"] === "string") next["describe"] = substituteScalar(value["describe"], instance, where, errors);
+	if (typeof value["action"] === "string") next["action"] = substituteScalar(value["action"], instance, where, errors);
+	return next;
+};
+/** Rewrite the `on` mapping — each row's target (string, or `{ to, describe, action }`) — through the resolver, preserving pattern keys and declaration order. */
+const emitOn = (raw, instance, where, instancesByPath, machinesRaw, errors) => {
 	if (!isPlainObject$2(raw)) return raw;
 	const out = {};
-	for (const [pattern, value] of Object.entries(raw)) if (typeof value === "string") out[pattern] = resolveTarget(value, ctx, errors);
-	else if (isPlainObject$2(value)) {
-		const next = { ...value };
-		if (typeof value["to"] === "string") next["to"] = resolveTarget(value["to"], ctx, errors);
-		if (typeof value["describe"] === "string") next["describe"] = substituteScalar(value["describe"], ctx, errors);
-		if (typeof value["action"] === "string") next["action"] = substituteScalar(value["action"], ctx, errors);
-		out[pattern] = next;
-	} else out[pattern] = value;
+	for (const [pattern, value] of Object.entries(raw)) if (typeof value === "string") out[pattern] = resolveOnTarget(value, instance, where, instancesByPath, machinesRaw, errors) ?? value;
+	else if (isPlainObject$2(value)) out[pattern] = emitOnObjectEdge(value, instance, where, instancesByPath, machinesRaw, errors);
+	else out[pattern] = value;
 	return out;
 };
-/** Rewrite a `retry` block's `otherwise` target (and pass `max` through). */
-const expandRetry = (raw, ctx, errors) => {
+/** Rewrite a `retry` block's `otherwise` target through the resolver (and pass `max` through). */
+const emitRetry = (raw, instance, where, instancesByPath, machinesRaw, errors) => {
 	if (!isPlainObject$2(raw)) return raw;
 	const next = { ...raw };
-	if (typeof raw["otherwise"] === "string") next["otherwise"] = resolveTarget(raw["otherwise"], ctx, errors);
+	if (typeof raw["otherwise"] === "string") next["otherwise"] = resolveOnTarget(raw["otherwise"], instance, where, instancesByPath, machinesRaw, errors) ?? raw["otherwise"];
 	return next;
 };
-/** Clone one sub-machine local state, applying param substitution and target rewriting. */
-const expandState = (stateRaw, ctx, errors) => {
+/** Clone one instance's own local state, applying `$param` substitution and `on`/`retry` target resolution. */
+const emitState = (stateRaw, instance, localName, instancesByPath, machinesRaw, errors) => {
+	const where = `machines.${instance.machine}.${localName}`;
 	if (!isPlainObject$2(stateRaw)) {
-		errors.push(`${ctx.where}: sub-machine state must be an object, got ${describeType$1(stateRaw)}`);
+		errors.push(`${where}: state must be an object, got ${describeType$1(stateRaw)}`);
 		return {};
 	}
 	const out = {};
-	for (const [key, value] of Object.entries(stateRaw)) if (key === "on") out[key] = expandOn(value, ctx, errors);
-	else if (key === "retry") out[key] = expandRetry(value, ctx, errors);
-	else out[key] = substituteScalar(value, ctx, errors);
-	return out;
-};
-/** Validate the `submachines:` map's shape (findings pushed onto `errors`), returning it best-effort. */
-const readSubmachines = (raw, declared, errors) => {
-	const submachines = isPlainObject$2(raw) ? raw : {};
-	if (declared && !isPlainObject$2(raw)) errors.push(`"submachines" must be a mapping of name -> { params, states }, got ${describeType$1(raw)}`);
-	for (const [name, sm] of Object.entries(submachines)) {
-		if (!isPlainObject$2(sm)) {
-			errors.push(`submachine "${name}": must be an object with "params" and "states"`);
+	for (const [key, value] of Object.entries(stateRaw)) {
+		if (key === "on") {
+			out[key] = emitOn(value, instance, where, instancesByPath, machinesRaw, errors);
 			continue;
 		}
-		const unknown = Object.keys(sm).filter((k) => !KNOWN_SUBMACHINE_KEYS.has(k));
-		if (unknown.length > 0) errors.push(`submachine "${name}": unknown key(s) ${unknown.join(", ")}`);
-		if (!isPlainObject$2(sm["states"]) || Object.keys(sm["states"]).length === 0) errors.push(`submachine "${name}": "states" must be a non-empty mapping`);
-	}
-	return submachines;
-};
-/** Read one invocation's `as:` rename map (local -> concrete), validating against the sub-machine's locals. */
-const readAs = (raw, smStates, where, errors) => {
-	const as = {};
-	if (raw === void 0) return as;
-	if (!isPlainObject$2(raw)) {
-		errors.push(`${where}: "as" must be a mapping of local -> concrete name`);
-		return as;
-	}
-	for (const [local, concrete] of Object.entries(raw)) {
-		if (typeof concrete !== "string") {
-			errors.push(`${where}: "as.${local}" must be a string`);
+		if (key === "retry") {
+			out[key] = emitRetry(value, instance, where, instancesByPath, machinesRaw, errors);
 			continue;
 		}
-		if (!(local in smStates)) errors.push(`${where}: "as" names "${local}", not a state of it`);
-		as[local] = concrete;
+		const resolved = substituteScalar(value, instance, where, errors);
+		if (typeof value === "string" && PARAM_REF.test(value) && resolved === "") continue;
+		out[key] = resolved;
 	}
-	return as;
+	return out;
 };
-/** Read one invocation's `set:` overrides (local -> extra fields), validating against the sub-machine's locals. */
-const readSet = (raw, smStates, where, errors) => {
-	const set = {};
-	if (raw === void 0) return set;
+/**
+* Resolve an instance's own `model` value, substituting a whole-value
+* `$param` at the reference site. A whole-value `$param` that resolves to the
+* empty string compiles away to "field absent" (mirrors the same rule in
+* `emitState`) — an instance that doesn't bind a model for this machine
+* should not stamp `model: ""`.
+*/
+const resolveInstanceModel = (rawMachine, instance, errors) => {
+	const rawModel = rawMachine["model"];
+	if (rawModel === void 0) return void 0;
+	const substituted = substituteScalar(rawModel, instance, `machines.${instance.machine}`, errors);
+	if (typeof rawModel === "string" && PARAM_REF.test(rawModel) && substituted === "") return;
+	return substituted;
+};
+/** Walk the instance tree, emitting every instance's own direct states into `states` (qualified). */
+const emitTree = (instance, machinesRaw, states, scopes, instancesByPath, errors) => {
+	const rawMachine = machinesRaw[instance.machine];
+	const statesRaw = rawMachine["states"];
+	const resolvedModel = resolveInstanceModel(rawMachine, instance, errors);
+	for (const [localName, local] of instance.locals) {
+		if (local.kind !== "state") continue;
+		const qualified = qualify(instance.path, localName);
+		const emitted = emitState(statesRaw[localName], instance, localName, instancesByPath, machinesRaw, errors);
+		if (resolvedModel !== void 0 && typeof emitted["prompt"] === "string") emitted["model"] = resolvedModel;
+		states[qualified] = emitted;
+		scopes[qualified] = instance.path;
+	}
+	for (const child of instance.children) emitTree(child, machinesRaw, states, scopes, instancesByPath, errors);
+};
+/** Project an `Instance` tree into its `MachineNode` visualization tree. */
+const buildTree = (instance) => ({
+	key: instance.path === "" ? instance.machine : instance.path,
+	machine: instance.machine,
+	states: Array.from(instance.locals.entries()).filter(([, local]) => local.kind === "state").map(([local]) => qualify(instance.path, local)),
+	children: instance.children.map(buildTree)
+});
+/**
+* Flatten a raw `entry:`/`machines:` config into qualified states, resolved
+* entry points, and a visualization tree — see the module doc comment.
+* Findings are pushed onto `errors`; a structurally invalid `raw` (not an
+* object, or missing `entry.default`) yields the all-empty/`undefined`
+* shape without attempting the passes.
+*/
+const flattenMachines = (raw, errors) => {
+	const empty = {
+		states: {},
+		entries: void 0,
+		tree: void 0,
+		scopes: {}
+	};
 	if (!isPlainObject$2(raw)) {
-		errors.push(`${where}: "set" must be a mapping of local -> { field: value }`);
-		return set;
-	}
-	for (const [local, fields] of Object.entries(raw)) {
-		if (!isPlainObject$2(fields)) {
-			errors.push(`${where}: "set.${local}" must be an object of extra fields`);
-			continue;
-		}
-		if (!(local in smStates)) errors.push(`${where}: "set" names "${local}", not a state of it`);
-		set[local] = fields;
-	}
-	return set;
-};
-/** Validate one invocation's shape and resolve its named sub-machine; `undefined` (with a finding) on anything malformed. */
-const resolveInvocation = (invRaw, index, submachines, errors) => {
-	const where = `use[${index}]`;
-	if (!isPlainObject$2(invRaw)) {
-		errors.push(`${where}: each invocation must be an object with a "submachine" key`);
-		return;
-	}
-	const unknown = Object.keys(invRaw).filter((k) => !KNOWN_INVOCATION_KEYS.has(k));
-	if (unknown.length > 0) errors.push(`${where}: unknown key(s) ${unknown.join(", ")}`);
-	const smName = invRaw["submachine"];
-	if (typeof smName !== "string") {
-		errors.push(`${where}: "submachine" must be a string naming a declared sub-machine`);
-		return;
-	}
-	const sm = submachines[smName];
-	if (!isPlainObject$2(sm) || !isPlainObject$2(sm["states"])) {
-		errors.push(`${where}: unknown sub-machine "${smName}"`);
-		return;
+		errors.push(`workflow must be an object, got ${describeType$1(raw)}`);
+		return empty;
 	}
-	return {
-		smStates: sm["states"],
-		scope: `${where} (${smName})`,
-		invocation: invRaw
-	};
-};
-/** Clone each local state into its concrete name, claiming names (collision → finding) and applying `set:` overrides. */
-const produceStates = (smStates, ctx, set, claimed, errors) => {
-	const out = {};
-	for (const [local, stateRaw] of Object.entries(smStates)) {
-		const concrete = ctx.as[local] ?? local;
-		if (claimed.has(concrete)) {
-			errors.push(`${ctx.where}: expands to state "${concrete}", which collides with an existing state`);
-			continue;
-		}
-		claimed.add(concrete);
-		const state = expandState(stateRaw, ctx, errors);
-		const overrides = set[local];
-		out[concrete] = overrides !== void 0 ? {
-			...state,
-			...overrides
-		} : state;
+	const entryRaw = raw["entry"];
+	if (!isPlainObject$2(entryRaw) || typeof entryRaw["default"] !== "string") {
+		errors.push(`"entry.default" must name a machine`);
+		return empty;
 	}
-	return out;
-};
-/**
-* Expand ONE `use:` invocation into concrete states, tracking claimed names in
-* `claimed` (mutated) and pushing findings onto `errors`. Returns the produced
-* `concreteName -> stateDef` map (empty on a malformed invocation).
-*/
-const expandInvocation = (invRaw, index, submachines, claimed, errors) => {
-	const resolved = resolveInvocation(invRaw, index, submachines, errors);
-	if (resolved === void 0) return {};
-	const { smStates, scope, invocation } = resolved;
-	const as = readAs(invocation["as"], smStates, scope, errors);
-	const withRaw = invocation["with"];
-	const params = isPlainObject$2(withRaw) ? withRaw : {};
-	if (withRaw !== void 0 && !isPlainObject$2(withRaw)) errors.push(`${scope}: "with" must be a mapping of param -> value`);
-	const set = readSet(invocation["set"], smStates, scope, errors);
-	const ctx = {
-		locals: new Set(Object.keys(smStates)),
-		as,
-		params,
-		where: scope
+	const machinesRaw = isPlainObject$2(raw["machines"]) ? raw["machines"] : {};
+	const instancesByPath = /* @__PURE__ */ new Map();
+	const referenced = /* @__PURE__ */ new Set();
+	const rootMachineName = entryRaw["default"];
+	referenced.add(rootMachineName);
+	const root = instantiate(rootMachineName, "", [], {}, {
+		machinesRaw,
+		referenced,
+		instancesByPath,
+		errors
+	}, "entry.default");
+	for (const name of Object.keys(machinesRaw)) if (!referenced.has(name)) errors.push(`machine "${name}" is declared but never referenced`);
+	if (root === void 0) return empty;
+	const states = {};
+	const scopes = {};
+	emitTree(root, machinesRaw, states, scopes, instancesByPath, errors);
+	const tree = buildTree(root);
+	const rootEntry = machinesRaw[rootMachineName]["entry"];
+	const defaultResolved = typeof rootEntry === "string" ? resolveEntry("entry.default", rootEntry, root, instancesByPath, machinesRaw, errors) : (errors.push(`machine "${rootMachineName}": "entry" must be a string`), void 0);
+	if (defaultResolved === void 0) return {
+		states,
+		entries: void 0,
+		tree,
+		scopes
 	};
-	return produceStates(smStates, ctx, set, claimed, errors);
-};
-/**
-* Expand `submachines:`/`use:` into concrete `states`. Returns a NEW raw object
-* with those two keys removed and `states` augmented; a non-object input, or one
-* declaring NEITHER key, is returned unchanged (so ordinary workflows are a
-* pure passthrough). Findings are pushed onto `errors`.
-*/
-const expandSubmachines = (raw, errors) => {
-	if (!isPlainObject$2(raw)) return raw;
-	if (raw["submachines"] === void 0 && raw["use"] === void 0) return raw;
-	const submachines = readSubmachines(raw["submachines"], raw["submachines"] !== void 0, errors);
-	const useRaw = raw["use"];
-	const invocations = Array.isArray(useRaw) ? useRaw : [];
-	if (raw["use"] !== void 0 && !Array.isArray(useRaw)) errors.push(`"use" must be an array of invocations, got ${describeType$1(useRaw)}`);
-	const baseStates = isPlainObject$2(raw["states"]) ? { ...raw["states"] } : {};
-	const claimed = new Set(Object.keys(baseStates));
-	const expanded = {};
-	invocations.forEach((invRaw, index) => {
-		Object.assign(expanded, expandInvocation(invRaw, index, submachines, claimed, errors));
-	});
-	const result = {
-		...raw,
-		states: {
-			...baseStates,
-			...expanded
-		}
+	return {
+		states,
+		entries: { default: defaultResolved },
+		tree,
+		scopes
 	};
-	delete result["submachines"];
-	delete result["use"];
-	return result;
-};
-/**
-* Describe a raw workflow's `use:` invocations as visualization GROUPS — which
-* concrete states each sub-machine invocation produced — WITHOUT expanding or
-* validating (a best-effort read for tooling like `gtd visualize`; malformed
-* entries are skipped, not reported). A workflow with no `use:` yields `[]`.
-* This is the only way to recover the sub-machine grouping after
-* `compileWorkflowConfig` has flattened it away.
-*/
-const collectGroups = (raw) => {
-	if (!isPlainObject$2(raw)) return [];
-	const submachines = isPlainObject$2(raw["submachines"]) ? raw["submachines"] : {};
-	const use = Array.isArray(raw["use"]) ? raw["use"] : [];
-	const smUseCount = /* @__PURE__ */ new Map();
-	for (const inv of use) if (isPlainObject$2(inv) && typeof inv["submachine"] === "string") smUseCount.set(inv["submachine"], (smUseCount.get(inv["submachine"]) ?? 0) + 1);
-	const groups = [];
-	use.forEach((inv, index) => {
-		if (!isPlainObject$2(inv)) return;
-		const smName = inv["submachine"];
-		if (typeof smName !== "string") return;
-		const sm = submachines[smName];
-		if (!isPlainObject$2(sm) || !isPlainObject$2(sm["states"])) return;
-		const smStates = sm["states"];
-		const as = isPlainObject$2(inv["as"]) ? inv["as"] : {};
-		const states = Object.keys(smStates).map((local) => typeof as[local] === "string" ? as[local] : local);
-		const name = typeof inv["name"] === "string" ? inv["name"] : (smUseCount.get(smName) ?? 0) > 1 ? `${smName}#${index}` : smName;
-		groups.push({
-			submachine: smName,
-			name,
-			states
-		});
-	});
-	return groups;
 };
 //#endregion
 //#region src/PatternConfig.ts
@@ -190073,24 +190225,35 @@ const collectGroups = (raw) => {
 *   <name>:
 *     format: <shell command>    # at least one of format/validate
 *     validate: <shell command>
-* states:
+* entry:
+*   default: <machine name>     # which machine is the ROOT instance
+* machines:
 *   <name>:
-*     actor: <string>    # forbidden on a commit state, required otherwise
-*     script: <string>   # exactly one of script/prompt/message/commit
-*     on:                # a mapping, DECLARATION ORDER PRESERVED — each <pattern> KEY is itself an Eta template, rendered against `it.vars` at the edge (src/Edge.ts's renderOnEdges) before the pure engine ever sees it
-*       "<pattern>": <targetState>                    # short form
-*       "<pattern>": { to: <targetState>, describe: <sentence> }  # with a human-readable route description (describe is NEVER Eta-rendered, unlike the pattern key)
-*     initial: true       # exactly one state across the whole workflow
-*     retry:
-*       max: <number>
-*       otherwise: <targetState>
-*     model: <string>     # optional, opaque harness hint — never on a commit state
-*     memory: <string>    # optional, opaque memory-scope label — never on a commit state
-*     label: <string>     # optional, opaque display name — never on a commit state
-*     file: <string>      # optional, an Eta template naming the state's steering file — never on a commit state
-*     mode: <modeName>    # optional, requires "file" — a built-in (qa/review) or a `modes:` entry; never on a commit state
+*     params: [<param>, ...]?   # advisory only — documents which $params a caller may bind
+*     model: <string>?          # optional, opaque harness hint — stamped onto every one of THIS machine's own `prompt` states; a state may NOT declare its own
+*     entry: <local or ref key> # this machine's OWN default local, resolved recursively
+*     states:
+*       <local>:                # an ordinary state
+*         actor: <string>    # forbidden on a commit state, required otherwise
+*         script: <string>   # exactly one of script/prompt/message/commit
+*         on:                # a mapping, DECLARATION ORDER PRESERVED — each <pattern> KEY is itself an Eta template, rendered against `it.vars` at the edge (src/Edge.ts's renderOnEdges) before the pure engine ever sees it
+*           "<pattern>": <targetState>                    # short form
+*           "<pattern>": { to: <targetState>, describe: <sentence> }  # with a human-readable route description (describe is NEVER Eta-rendered, unlike the pattern key)
+*         retry:
+*           max: <number>
+*           otherwise: <targetState>
+*         label: <string>     # optional, opaque display name — never on a commit state
+*         file: <string>      # optional, an Eta template naming the state's steering file — never on a commit state
+*         mode: <modeName>    # optional, requires "file" — a built-in (qa/review) or a `modes:` entry; never on a commit state
+*         entry: true         # optional — an EXTRA reachability root (WorkflowEntries.manual), enterable via `gtd step <actor> --entry <this state's qualified name>`; distinct from the top-level `entry:` key above
+*       <local>: { machine: <name>, with: { ... } }       # a REFERENCE — instantiates <name> as a child, see src/Machines.ts
 * ```
 *
+* The raw `entry:`/`machines:` value is flattened by `src/Machines.ts`'s
+* `flattenMachines` into qualified states plus resolved entry points BEFORE any
+* per-state compilation below ever runs — this module never sees an unresolved
+* `$param` or a bare reference path.
+*
 * ## `vars:` — one of `it.vars`'s three layers
 *
 * A sibling `vars:` key INSIDE the `workflow:` value declares the workflow's
@@ -190252,25 +190415,166 @@ const KNOWN_STATE_KEYS = /* @__PURE__ */ new Set([
 	"actor",
 	...CONTENT_KEYS,
 	"on",
-	"initial",
 	"retry",
 	"model",
-	"memory",
 	"label",
 	"file",
 	"mode",
 	"reviewWindow",
 	"reviewBase",
-	"reviewEntry",
-	"fixEntry",
 	"requireProgress",
-	"answerGate"
+	"answerGate",
+	"entry"
 ]);
 const KNOWN_TOP_KEYS = /* @__PURE__ */ new Set([
+	"entry",
+	"machines",
 	"vars",
-	"states",
 	"modes"
 ]);
+const KNOWN_MACHINE_KEYS = /* @__PURE__ */ new Set([
+	"params",
+	"entry",
+	"states",
+	"model"
+]);
+const KNOWN_REF_KEYS = /* @__PURE__ */ new Set(["machine", "with"]);
+/** A state-level key removed by the `entry:`/`machines:` rewrite (or, for `memory`, by the machine-scoped-memory restructure), naming its replacement so a stale config's error points somewhere useful instead of a bare "unknown key". The state-level `model` case is instead caught pre-flatten by `LEGACY_AUTHORED_STATE_KEY_HINTS`/`validateMachineStateKeys`, because by the time a state reaches `KNOWN_STATE_KEYS`/`compileState` its `model` may be a legitimately machine-stamped key. */
+const LEGACY_STATE_KEY_HINTS = {
+	initial: `"initial" no longer exists — declare this state's qualified path in the top-level "entry.default" instead`,
+	reviewEntry: `"reviewEntry" no longer exists — declare "entry: true" on this state instead`,
+	fixEntry: `"fixEntry" no longer exists — declare "entry: true" on this state instead`,
+	memory: `"memory" no longer exists — a machine's memory scope is derived from its position in the tree and starts fresh on every entry`
+};
+/** A reference-level key from the old `use:` invocation shape, naming its replacement. */
+const LEGACY_REF_KEY_HINTS = {
+	as: `"as" no longer exists — a reference's local name (the key itself) IS the concrete name; there is nothing left to rename`,
+	name: `"name" no longer exists — a reference's local name (the key itself) names the instance`,
+	set: `"set" no longer exists — bind extra per-instance values via "with:" instead`
+};
+/** Render an unknown-key list, appending a legacy-key hint in parentheses for any key `hints` recognizes. */
+const formatUnknownKeys = (keys, hints) => keys.map((k) => hints[k] !== void 0 ? `${k} (${hints[k]})` : k).join(", ");
+/**
+* A top-level key from the pre-Package-02 raw shape (flat `states:`, or the
+* sub-machine expander's `submachines:`/`use:`). Detected and thrown FIRST, before
+* any other validation, so a stale config produces only this migration table —
+* never forty downstream "machines is required"-style findings piled on top.
+*/
+const LEGACY_TOP_KEY_MESSAGES = {
+	states: `top-level "states:" is no longer supported — declare a machine under "machines:" and name it in "entry.default:"`,
+	submachines: `top-level "submachines:" is no longer supported — declare machines directly under "machines:"`,
+	use: `top-level "use:" is no longer supported — reference a machine inline via a { machine, with } entry inside a machine's own "states:"`
+};
+const detectLegacyShape = (raw) => {
+	const found = Object.keys(LEGACY_TOP_KEY_MESSAGES).filter((k) => k in raw);
+	if (found.length === 0) return;
+	throw new Error(formatErrors(found.map((k) => LEGACY_TOP_KEY_MESSAGES[k])));
+};
+/**
+* A top-level `entry.review`/`entry.fix` key from the pre-`entry: true`
+* shape. Detected and thrown FIRST — right after `detectLegacyShape`, before
+* `flattenMachines` (or anything else) ever runs — so a stale config
+* migrating off the named review/fix entry points gets ONLY this message,
+* never mixed with `detectLegacyShape`'s own unrelated top-level findings or
+* any generic downstream complaint about an unknown key inside `entry:`.
+*/
+const LEGACY_ENTRY_KEY_MESSAGES = {
+	review: `entry.review is no longer supported — declare \`entry: true\` on that state and enter it with \`gtd --entry <state>\``,
+	fix: `entry.fix is no longer supported — declare \`entry: true\` on that state and enter it with \`gtd --entry <state>\``
+};
+const detectLegacyEntryKeys = (raw) => {
+	const entryRaw = raw["entry"];
+	if (!isPlainObject$1(entryRaw)) return;
+	const found = Object.keys(LEGACY_ENTRY_KEY_MESSAGES).filter((k) => k in entryRaw);
+	if (found.length === 0) return;
+	throw new Error(formatErrors(found.map((k) => LEGACY_ENTRY_KEY_MESSAGES[k])));
+};
+/**
+* Structural validation over the raw `machines:` map that `src/Machines.ts`'s
+* `flattenMachines` does not itself perform: unknown keys on a machine
+* (`KNOWN_MACHINE_KEYS`), keys that have MOVED off a state
+* (`LEGACY_AUTHORED_STATE_KEY_HINTS`), and unknown keys on a reference local
+* (`KNOWN_REF_KEYS`), the last surfacing the old `use:` invocation's
+* `as`/`name`/`set` keys through `LEGACY_REF_KEY_HINTS` rather than a bare
+* "unknown key". Findings are pushed onto `errors`; a malformed shape (not an
+* object, a non-object machine/state) is left for `flattenMachines`/
+* `compileState` to report — this pass only adds what they don't already cover.
+*/
+/** Validate one machine's own reference locals against `KNOWN_REF_KEYS`, pushing findings onto `errors`. */
+const validateMachineRefs = (machineName, machineRaw, errors) => {
+	const statesRaw = machineRaw["states"];
+	if (!isPlainObject$1(statesRaw)) return;
+	for (const [local, def] of Object.entries(statesRaw)) {
+		if (!isRefRaw(def)) continue;
+		const unknownRefKeys = Object.keys(def).filter((k) => !KNOWN_REF_KEYS.has(k));
+		if (unknownRefKeys.length > 0) errors.push(`machine "${machineName}": reference "${local}": unknown key(s) ${formatUnknownKeys(unknownRefKeys, LEGACY_REF_KEY_HINTS)}`);
+	}
+};
+/**
+* A key an author may no longer put on a STATE, mapped to the hint naming its
+* replacement. Checked against the AUTHORED `machines.<name>.states` map rather
+* than through `KNOWN_STATE_KEYS`/`compileState`, because those two see the
+* FLATTENED shape — where `src/Machines.ts` has already stamped the owning
+* machine's own `model` onto each of its `prompt` states, and a `model` key is
+* exactly what a well-formed emitted state carries.
+*/
+const LEGACY_AUTHORED_STATE_KEY_HINTS = { model: (machineName) => `"model" is no longer a state key — declare it once on the machine that owns this state ("machines.${machineName}.model")` };
+/** Flag any `LEGACY_AUTHORED_STATE_KEY_HINTS` key declared on one machine's own (non-reference) states. */
+const validateMachineStateKeys = (machineName, machineRaw, errors) => {
+	const statesRaw = machineRaw["states"];
+	if (!isPlainObject$1(statesRaw)) return;
+	for (const [local, def] of Object.entries(statesRaw)) {
+		if (!isPlainObject$1(def) || isRefRaw(def)) continue;
+		for (const [key, hint] of Object.entries(LEGACY_AUTHORED_STATE_KEY_HINTS)) {
+			if (!(key in def)) continue;
+			errors.push(`machine "${machineName}": state "${local}": unknown key(s) ${key} (${hint(machineName)})`);
+		}
+	}
+};
+/**
+* The machine-level `model:` field — the ONLY place a model may be authored
+* (`validateMachineStateKeys`, above, rejects the state-level form): a
+* non-empty string, else a load error naming the machine. Validates the value
+* a machine stamps onto its own `prompt` states (`src/Machines.ts`'s
+* `resolveInstanceModel`/`emitTree`); the per-state `compileModel` (below) is
+* then only the type guard over that STAMPED value.
+*/
+const compileMachineModel = (machineName, machineRaw, errors) => {
+	if (machineRaw.model === void 0) return;
+	if (typeof machineRaw.model !== "string" || machineRaw.model === "") errors.push(`machines.${machineName}: "model" must be a non-empty string`);
+};
+/** Does `machineRaw` declare at least one of its OWN (non-reference) states with content kind `prompt`? Mirrors exactly which states `src/Machines.ts` stamps a machine-level `model` onto — a reference local's states belong to the CHILD machine, never this one. */
+const machineHasPromptState = (machineRaw) => {
+	const statesRaw = machineRaw["states"];
+	if (!isPlainObject$1(statesRaw)) return false;
+	return Object.values(statesRaw).some((def) => isPlainObject$1(def) && !isRefRaw(def) && typeof def["prompt"] === "string");
+};
+/**
+* A machine declaring `model:` with no `prompt`-content state anywhere among
+* its own states is a load error, not a silent no-op — see this module's
+* "BOUNDARY CORRECTION" note in package 02: the model would never land on any
+* emitted state, so the declaration does nothing.
+*/
+const validateMachineModelHasPromptState = (machineName, machineRaw, errors) => {
+	if (machineRaw.model === void 0) return;
+	if (!machineHasPromptState(machineRaw)) errors.push(`machine "${machineName}": declares "model" but has no "prompt" state — this would never take effect`);
+};
+const validateMachinesShape = (raw, errors) => {
+	if (raw === void 0) return;
+	if (!isPlainObject$1(raw)) {
+		errors.push(`"machines" must be a mapping of machine name -> { params?, entry, states }, got ${describeType(raw)}`);
+		return;
+	}
+	for (const [machineName, machineRaw] of Object.entries(raw)) {
+		if (!isPlainObject$1(machineRaw)) continue;
+		const unknownMachineKeys = Object.keys(machineRaw).filter((k) => !KNOWN_MACHINE_KEYS.has(k));
+		if (unknownMachineKeys.length > 0) errors.push(`machine "${machineName}": unknown key(s) ${unknownMachineKeys.join(", ")}`);
+		validateMachineRefs(machineName, machineRaw, errors);
+		validateMachineStateKeys(machineName, machineRaw, errors);
+		compileMachineModel(machineName, machineRaw, errors);
+		validateMachineModelHasPromptState(machineName, machineRaw, errors);
+	}
+};
 const formatErrors = (errors) => `workflow config:\n${errors.map((e) => `  - ${e}`).join("\n")}`;
 /**
 * Resolve one content string: inline text passes through verbatim; a file
@@ -190293,6 +190597,8 @@ const resolveContent = (value, configDir, where, errors) => {
 		return;
 	}
 };
+/** A local is a REFERENCE iff its raw value carries a `machine` key — the same predicate `src/Machines.ts` uses. */
+const isRefRaw = (v) => isPlainObject$1(v) && typeof v["machine"] === "string";
 /**
 * Inline every `./`/`../` content file reference in ONE raw `workflow:` value
 * against `configDir` — the directory of the `.gtdrc` that DECLARED it — and
@@ -190301,39 +190607,53 @@ const resolveContent = (value, configDir, where, errors) => {
 * Used by `src/Config.ts`'s `loadMerged` to resolve each config level's
 * references against its OWN file's directory BEFORE the levels are
 * deep-merged. The merge collapses every level into one anonymous object, so it
-* erases which file a given `states.x.prompt` came from; resolving up front,
-* per level, is the only way `./gtd-prompts/x.md` in a parent `.gtdrc` resolves
-* against the parent (not the cwd a child repo runs from). `compileWorkflowConfig`
-* is then invoked with `inlineFileRefs: false` on the merged result.
-*
-* Malformed shapes (a non-object workflow, non-object `states`, a non-object
-* state, a non-string content value) pass through untouched —
+* erases which file a given `machines.x.states.y.prompt` came from; resolving up
+* front, per level, is the only way `./gtd-prompts/x.md` in a parent `.gtdrc`
+* resolves against the parent (not the cwd a child repo runs from).
+* `compileWorkflowConfig` is then invoked with `inlineFileRefs: false` on the
+* merged result. Walks `machines[*].states[*]`, skipping reference entries (an
+* object carrying a `machine` key) — a reference has no content of its own to
+* inline.
+*
+* Malformed shapes (a non-object workflow, non-object `machines`, a non-object
+* machine/state, a non-string content value) pass through untouched —
 * `compileWorkflowConfig`/`validateDefinition` own those findings; this pass
 * only rewrites the strings it recognizes as file references, collecting a load
 * error (via `resolveContent`) for any that is missing or unreadable.
 */
+/** Inline one ordinary (non-reference) state's own content file references; a reference passes through untouched. */
+const inlineStateFileRefs = (def, machineName, local, configDir, errors) => {
+	if (typeof def["machine"] === "string") return def;
+	const next = { ...def };
+	for (const key of CONTENT_KEYS) {
+		const value = def[key];
+		if (typeof value !== "string" || !isFileReference(value)) continue;
+		const resolved = resolveContent(value, configDir, `machine "${machineName}" state "${local}" (${key})`, errors);
+		if (resolved !== void 0) next[key] = resolved;
+	}
+	return next;
+};
+/** Inline every state's content file references for one machine; a malformed machine/states shape passes through untouched. */
+const inlineMachineFileRefs = (machineRaw, machineName, configDir, errors) => {
+	if (!isPlainObject$1(machineRaw)) return machineRaw;
+	const rawStates = machineRaw["states"];
+	if (!isPlainObject$1(rawStates)) return machineRaw;
+	const states = {};
+	for (const [local, def] of Object.entries(rawStates)) states[local] = isPlainObject$1(def) ? inlineStateFileRefs(def, machineName, local, configDir, errors) : def;
+	return {
+		...machineRaw,
+		states
+	};
+};
 const inlineWorkflowFileRefs = (rawWorkflow, configDir, errors) => {
 	if (!isPlainObject$1(rawWorkflow)) return rawWorkflow;
-	const rawStates = rawWorkflow["states"];
-	if (!isPlainObject$1(rawStates)) return rawWorkflow;
-	const states = {};
-	for (const [name, state] of Object.entries(rawStates)) {
-		if (!isPlainObject$1(state)) {
-			states[name] = state;
-			continue;
-		}
-		const next = { ...state };
-		for (const key of CONTENT_KEYS) {
-			const value = state[key];
-			if (typeof value !== "string" || !isFileReference(value)) continue;
-			const resolved = resolveContent(value, configDir, `state "${name}" (${key})`, errors);
-			if (resolved !== void 0) next[key] = resolved;
-		}
-		states[name] = next;
-	}
+	const rawMachines = rawWorkflow["machines"];
+	if (!isPlainObject$1(rawMachines)) return rawWorkflow;
+	const machines = {};
+	for (const [machineName, machineRaw] of Object.entries(rawMachines)) machines[machineName] = inlineMachineFileRefs(machineRaw, machineName, configDir, errors);
 	return {
 		...rawWorkflow,
-		states
+		machines
 	};
 };
 const KNOWN_EDGE_KEYS = /* @__PURE__ */ new Set([
@@ -190464,7 +190784,7 @@ const compileActor = (raw, name, errors) => {
 	}
 	return raw.actor;
 };
-/** The `model` field: an opaque string, or undefined (either absent or invalid — the type mismatch is its own error). Never interpreted or validated beyond "is it a string" — see `PatternMachine.StateDef.model`. */
+/** The `model` field as it reaches a FLATTENED state — never authored there (`validateMachineStateKeys` rejects that), only stamped on by the owning machine (`src/Machines.ts`'s `emitTree`). An opaque string, or undefined (either absent or invalid — the type mismatch is its own error). Never interpreted or validated beyond "is it a string" — see `PatternMachine.StateDef.model`. */
 const compileModel = (raw, name, errors) => {
 	if (raw.model === void 0) return void 0;
 	if (typeof raw.model !== "string") {
@@ -190473,15 +190793,6 @@ const compileModel = (raw, name, errors) => {
 	}
 	return raw.model;
 };
-/** The `memory` field: an opaque memory-scope label (Eta template), or undefined (either absent or invalid — the type mismatch is its own error). Never interpreted or validated beyond "is it a string" — see `PatternMachine.StateDef.memory`. */
-const compileMemory = (raw, name, errors) => {
-	if (raw.memory === void 0) return void 0;
-	if (typeof raw.memory !== "string") {
-		errors.push(`state "${name}": "memory" must be a string`);
-		return;
-	}
-	return raw.memory;
-};
 /** The `label` field: an opaque display name, or undefined (either absent or invalid — the type mismatch is its own error). Never interpreted or validated beyond "is it a string" — see `PatternMachine.StateDef.label`. */
 const compileLabel = (raw, name, errors) => {
 	if (raw.label === void 0) return void 0;
@@ -190509,13 +190820,13 @@ const compileMode = (raw, name, errors) => {
 	}
 	return raw.mode;
 };
-/** The `initial` field: `true` only when the raw value is the literal boolean `true`. */
-const compileInitial = (raw, name, errors) => compileBooleanFlag(raw, "initial", name, errors);
 /**
-* A boolean state flag (`initial`/`reviewWindow`/`reviewBase`/`reviewEntry`/`fixEntry`/`requireProgress`/`answerGate`): `true` only
-* when the raw value is the literal `true`; a non-boolean is a config error;
-* `false` (or absent) compiles away to `undefined` so it never lands in the
-* `StateDef` — `false` and "unset" mean the same thing for every such flag.
+* A boolean state flag (`reviewWindow`/`requireProgress`/`answerGate`/
+* `entry`): `true` only when the raw value is the literal `true`; a
+* non-boolean is a config error; `false` (or absent) compiles away to
+* `undefined` so it never lands in the `StateDef` — `false` and "unset" mean
+* the same thing for every such flag. `reviewBase` no longer goes through
+* this — see `compileBooleanOrTemplateFlag`.
 */
 const compileBooleanFlag = (raw, key, name, errors) => {
 	const value = raw[key];
@@ -190526,6 +190837,21 @@ const compileBooleanFlag = (raw, key, name, errors) => {
 	}
 	return value === true ? true : void 0;
 };
+/**
+* `reviewBase`'s own flag shape: the literal `true`, OR a non-blank string (an
+* Eta template rendering a commitish, returned verbatim — no trimming, just a
+* blank-after-trim rejection) — see `StateDef.reviewBase`'s widened type.
+* `false`, a number, an object, or a blank string are all rejected with the
+* same finding shape `compileBooleanFlag` uses; `undefined` (absent) passes
+* through untouched.
+*/
+const compileBooleanOrTemplateFlag = (raw, key, name, errors) => {
+	const value = raw[key];
+	if (value === void 0) return void 0;
+	if (value === true) return true;
+	if (typeof value === "string" && value.trim() !== "") return value;
+	errors.push(`state "${name}": "${key}" must be a boolean or a non-blank string`);
+};
 const assembleContentFields = (content) => ({
 	...content.script !== void 0 ? { script: content.script } : {},
 	...content.prompt !== void 0 ? { prompt: content.prompt } : {},
@@ -190544,94 +190870,143 @@ const assembleStateDef = (parts) => ({
 	...definedEntries({
 		actor: parts.actor,
 		on: parts.on,
-		initial: parts.initial,
 		retry: parts.retry,
 		model: parts.model,
-		memory: parts.memory,
 		label: parts.label,
 		file: parts.file,
 		mode: parts.mode,
 		reviewWindow: parts.reviewWindow,
 		reviewBase: parts.reviewBase,
-		reviewEntry: parts.reviewEntry,
-		fixEntry: parts.fixEntry,
 		requireProgress: parts.requireProgress,
 		answerGate: parts.answerGate
 	}),
 	...assembleContentFields(parts.content)
 });
-/** One state's full shape: actor, content, `on`, `initial`, `retry`. */
+/**
+* One state's full shape: actor, content, `on`, `retry`. Operates on a
+* QUALIFIED state entry from `FlattenedWorkflow.states` (`src/Machines.ts`) —
+* `$param`s already substituted, every `on`/`retry.otherwise` target already
+* an absolute qualified name — so this is exactly the flat compilation the
+* pre-`entry:`/`machines:` compiler already did. The old named entry-point
+* flags (`initial`/`reviewEntry`/`fixEntry`) are gone from this shape
+* entirely: the flattener resolves `entry.default` directly into
+* `WorkflowDefinition.entries.default`, and a state's own `entry: true` flag
+* (validated here, collected by the caller) seeds `entries.manual` instead —
+* neither ever lands on the compiled `StateDef`.
+*/
 const compileState = (name, raw, configDir, errors, inlineFileRefs) => {
 	if (!isPlainObject$1(raw)) {
 		errors.push(`state "${name}": must be an object, got ${describeType(raw)}`);
 		return {};
 	}
 	const unknownKeys = Object.keys(raw).filter((k) => !KNOWN_STATE_KEYS.has(k));
-	if (unknownKeys.length > 0) errors.push(`state "${name}": unknown key(s) ${unknownKeys.join(", ")}`);
-	return assembleStateDef({
+	if (unknownKeys.length > 0) errors.push(`state "${name}": unknown key(s) ${formatUnknownKeys(unknownKeys, LEGACY_STATE_KEY_HINTS)}`);
+	const def = assembleStateDef({
 		actor: compileActor(raw, name, errors),
 		content: compileContent(raw, name, configDir, errors, inlineFileRefs),
 		on: compileOn(raw.on, name, errors),
-		initial: compileInitial(raw, name, errors),
 		retry: compileRetry(raw.retry, name, errors),
 		model: compileModel(raw, name, errors),
-		memory: compileMemory(raw, name, errors),
 		label: compileLabel(raw, name, errors),
 		file: compileFile(raw, name, errors),
 		mode: compileMode(raw, name, errors),
 		reviewWindow: compileBooleanFlag(raw, "reviewWindow", name, errors),
-		reviewBase: compileBooleanFlag(raw, "reviewBase", name, errors),
-		reviewEntry: compileBooleanFlag(raw, "reviewEntry", name, errors),
-		fixEntry: compileBooleanFlag(raw, "fixEntry", name, errors),
+		reviewBase: compileBooleanOrTemplateFlag(raw, "reviewBase", name, errors),
 		requireProgress: compileBooleanFlag(raw, "requireProgress", name, errors),
 		answerGate: compileBooleanFlag(raw, "answerGate", name, errors)
 	});
+	compileBooleanFlag(raw, "entry", name, errors);
+	return def;
+};
+/**
+* Compiler invariant, not a workflow-author finding: `flattenMachines`
+* (`src/Machines.ts`) promises a `scopes` entry for EVERY state it emits (see
+* that module's doc comment, "Bindings carry their scope") — a mismatch here
+* means the flattener itself missed a state, which must fail loudly rather
+* than silently produce a memory key that reads as "outside every scope".
+* Exported so this invariant is directly testable against a contrived
+* `scopes` map, independent of whether `flattenMachines` itself can currently
+* be made to violate its own guarantee.
+*/
+const assertScopesCoverStates = (stateNames, scopes, errors) => {
+	for (const name of stateNames) if (!(name in scopes)) errors.push(`internal error: scopes map produced by the flattener is missing state "${name}"`);
 };
 /**
 * Compile the raw, decoded `workflow:` YAML value into a `WorkflowDefinition`
-* plus the workflow's own compiled `vars:` map. `configDir` is the config
-* file's own directory, used to resolve `./`/`../` file references. `rcModes`
-* is the already-compiled top-level `.gtdrc` `modes:` key (`src/Config.ts`),
-* layered over the workflow's own `modes:` per half BEFORE validation — so a
-* state may name a mode either layer declares. `inlineFileRefs` (default
-* `true`) inlines content file references against `configDir`; the real config
-* path (`src/Config.ts`'s `loadMerged`) passes `false` because it has already
-* inlined every reference per declaring file across the merge chain, so
-* `configDir` is then irrelevant. Throws a single `Error` (message:
-* `"workflow config:\n  - ..."`, one line per finding) on ANY config-shape
-* problem or `validateDefinition` finding — never partially succeeds.
+* plus the workflow's own compiled `vars:` map and its machine tree. `configDir`
+* is the config file's own directory, used to resolve `./`/`../` file
+* references. `rcModes` is the already-compiled top-level `.gtdrc` `modes:` key
+* (`src/Config.ts`), layered over the workflow's own `modes:` per half BEFORE
+* validation — so a state may name a mode either layer declares.
+* `inlineFileRefs` (default `true`) inlines content file references against
+* `configDir`; the real config path (`src/Config.ts`'s `loadMerged`) passes
+* `false` because it has already inlined every reference per declaring file
+* across the merge chain, so `configDir` is then irrelevant. Throws a single
+* `Error` (message: `"workflow config:\n  - ..."`, one line per finding) on ANY
+* config-shape problem or `validateDefinition` finding — never partially
+* succeeds.
+*
+* Four error-sequencing rules, in order:
+*
+* 1. `detectLegacyShape` short-circuits first — a stale pre-`entry:`/`machines:`
+*    config throws with ONLY the migration findings, never mixed with
+*    downstream noise.
+* 2. `detectLegacyEntryKeys` short-circuits next — a stale top-level
+*    `entry.review`/`entry.fix` key (the pre-`entry: true` named entry points)
+*    throws with ONLY its own migration findings, before `flattenMachines`
+*    (or anything else) has a chance to notice those same keys some other way.
+* 3. Unassemblable throws early: `flattenMachines`'s `entries` coming back
+*    `undefined` (no `entry.default`, no `machines`, an unresolvable root)
+*    means there is no definition for `validateDefinition` to add findings to
+*    — throw immediately with whatever findings exist so far.
+* 4. Otherwise the flattener's findings and `validateDefinition`'s findings
+*    merge into one de-duplicated, thrown error.
 */
 const compileWorkflowConfig = (raw, configDir, rcModes, inlineFileRefs = true) => {
 	if (!isPlainObject$1(raw)) throw new Error(`workflow config: must be an object, got ${describeType(raw)}`);
+	detectLegacyShape(raw);
+	detectLegacyEntryKeys(raw);
 	const errors = [];
-	const expanded = expandSubmachines(raw, errors);
-	const cfg = isPlainObject$1(expanded) ? expanded : raw;
-	const unknownTopKeys = Object.keys(cfg).filter((k) => !KNOWN_TOP_KEYS.has(k));
+	const unknownTopKeys = Object.keys(raw).filter((k) => !KNOWN_TOP_KEYS.has(k));
 	if (unknownTopKeys.length > 0) errors.push(`unknown top-level key(s) ${unknownTopKeys.join(", ")}`);
-	const vars = compileVarsMap(cfg.vars, errors);
-	const modes = mergeModes(compileModesMap(cfg.modes, errors), rcModes);
-	const rawStates = cfg.states;
-	if (!isPlainObject$1(rawStates) || Object.keys(rawStates).length === 0) {
-		errors.push(`"states" must be a non-empty object`);
-		throw new Error(formatErrors(errors));
-	}
+	const vars = compileVarsMap(raw.vars, errors);
+	const modes = mergeModes(compileModesMap(raw.modes, errors), rcModes);
+	validateMachinesShape(raw.machines, errors);
+	const flattened = flattenMachines(raw, errors);
+	if (flattened.entries === void 0) throw new Error(formatErrors(errors));
 	const states = {};
-	for (const [name, s] of Object.entries(rawStates)) states[name] = compileState(name, s, configDir, errors, inlineFileRefs);
+	const manualSet = /* @__PURE__ */ new Set();
+	for (const [name, s] of Object.entries(flattened.states)) {
+		states[name] = compileState(name, s, configDir, errors, inlineFileRefs);
+		if (isPlainObject$1(s) && s["entry"] === true) manualSet.add(name);
+	}
+	const manual = Array.from(manualSet).sort();
+	const entries = {
+		default: flattened.entries.default,
+		manual
+	};
 	const definition = modes !== void 0 ? {
 		states,
+		entries,
 		modes
-	} : { states };
+	} : {
+		states,
+		entries
+	};
+	assertScopesCoverStates(Object.keys(states), flattened.scopes, errors);
 	const definitionErrors = validateDefinition(definition);
 	const allErrors = Array.from(/* @__PURE__ */ new Set([...errors, ...definitionErrors]));
 	if (allErrors.length > 0) throw new Error(formatErrors(allErrors));
 	return {
 		definition,
-		vars
+		vars,
+		tree: flattened.tree,
+		scopes: flattened.scopes
 	};
 };
 //#endregion
 //#region src/workflows/unified.yaml
-var unified_default = "# The unified gtd workflow template — gtd's BUILT-IN DEFAULT workflow. When no\n# `workflow:` key is configured anywhere in the cwd→home config chain,\n# src/Config.ts runs this template directly, so a state command works with no\n# configuration at all. `gtd init` seeds only the settings a project tunes\n# (vars.testCommand + a modes: formatting suggestion), never the workflow\n# itself. See STATES.md §10 for the full walkthrough.\n#\n# Compiled through the exact same `compileWorkflowConfig` a user's `.gtdrc`\n# `workflow:` key goes through — no privileged code path\n# (src/workflows/templates.ts does the compiling). Every content string below\n# is INLINE (no `./`-relative file references): the bundled template ships\n# inside a single-file build (`dist/gtd.bundle.mjs`), so its content must\n# already be resolved at BUILD time. `renderInitConfig` (src/workflows/\n# templates.ts) can MATERIALIZE this inline source into a `.gtdrc.json`\n# `workflow:` value — the way to eject/customize the machine, and the hermetic\n# test fixture — but `gtd init` itself no longer writes the workflow.\n#\n# ── Authored with SUB-MACHINES (Option C) ──────────────────────────────────\n#\n# This template is written with `submachines:`/`use:` (see src/Submachines.ts).\n# Expansion is a compile-time raw → raw pre-pass with NO runtime footprint: the\n# pure engine only ever sees the flat concrete states, and each invocation's\n# `as:` rename map spells out the concrete state name every expanded state gets,\n# so the compiled `WorkflowDefinition` is exactly what a hand-written flat\n# workflow would produce. The sub-machines split into DEDUP (a gate/loop\n# authored once, invoked several times) and ENCAPSULATION (a single-instance\n# cluster grouped for reading):\n#\n#   * makeGreen (dedup ×2)    — the check/fix/escalate health triple shared by\n#                               the simple build tail and the advanced package\n#                               loop (identical script/prompt/message).\n#   * assertGreen (dedup ×3)  — the green-baseline gate (check + human blocked)\n#                               guarding the simple, advanced and review entries.\n#   * qaLoop (dedup ×2)       — the checkbox Q&A author/answer loop shared by the\n#                               product (product-qa) and technical (technical-qa)\n#                               phases of the advanced flow.\n#   * planLoop (encap)        — the simple flow's plan-iteration loop.\n#   * humanReview (encap)     — the shared review tail (reviewing → await-review →\n#                               review-deciding → feedback collect/build).\n#   * specGate (encap)        — the advanced flow's per-package agentic review.\n#   * packageLoop (encap)     — the advanced flow's per-package build queue.\n#\n# ── Four entry points behind a green-baseline gate, one shared tail ─────────\n#\n# EVERY entry first runs the test suite and only proceeds when it is GREEN — you\n# never start new work (or a review) on top of a red baseline. A red run halts\n# at a human `*-blocked` gate (fix the failures and re-run, exactly like\n# the `escalate` states), or is what `gtd fix` exists to repair.\n#\n# The initial `idle` state FORKS on which steering file the human creates,\n# routing into that flow's OWN start gate:\n#\n#   * the configured requirementsFile (default .gtd/REQUIREMENTS.md) ->\n#     `spec-precheck` -> the ADVANCED flow (product + technical Q&A, package\n#     decomposition, per-package parallel build + agentic spec-review).\n#   * anything else (e.g. the configured todoFile, default .gtd/TODO.md) ->\n#     `plan-precheck` -> the SIMPLE flow (one grilling Q&A loop, a monolithic\n#     build, no decomposition, no agentic review).\n#\n# A third entry, `gtd review <commitish>`, jumps to `review-precheck`\n# (reviewEntry) and, once green, to `reviewing` to review a foreign branch\n# through the same shared tail. A fourth, `gtd fix`, jumps to `fix-precheck`\n# (fixEntry): a red suite drops straight into the shared `fixing` loop and out\n# through the review + squash tail; a green suite is a no-op back to `idle`.\n#\n# All three converge at `reviewing` -> `await-review`. Ticking a REVIEW.md box\n# means only \"I reviewed this hunk\"; a COMMENT (not an unticked box) is what asks\n# for changes. Every human step at `await-review` goes to `review-deciding`,\n# which inspects the step and routes:\n#   * no comment (every box ticked, no REVIEW.md note, no code edit) -> the diff\n#     is a bare REVIEW.md deletion -> squashing -> done (the ONLY path to the\n#     finale — the whole cycle collapses into one commit).\n#   * any comment — a note in REVIEW.md OR a hand-edit to code — ->\n#     review-deciding writes REVIEW_FEEDBACK.md -> feedback-building implements\n#     it (completing any code the human hand-edited, never reverting their\n#     lines) -> checking -> reviewing regenerates an INCREMENTAL REVIEW.md\n#     (review-deciding carries `reviewBase: true`, so each feedback round's\n#     review + checkout window covers only `last-review..HEAD`, i.e. the agent's\n#     follow-through, not the human's own edit) -> await-review, looping until\n#     sign-off.\n# Two dead ends never commit: the sign-off gate (src/program.ts) REFUSES a step\n# that leaves a box unticked with no comment (finish reviewing first) and a\n# deleted REVIEW.md (restore it and tick the boxes).\n#\n# The shared health segment (`checking`/`fixing`/`escalate`) serves the simple\n# build and the feedback loop — its green edge targets\n# `reviewing`. The advanced per-package loop keeps its OWN health triple\n# (`package-checking`/`package-fixing`/`package-escalate`) because its green edge targets\n# the per-package `spec-review` gate instead.\n#\n# Every `on` pattern's path below is written as the matching var's Eta\n# template (e.g. `\"A <%= it.vars.feedbackFile %>\"`), not a literal `.gtd/...`\n# path — repointing a var reroutes the machine along with every template that\n# reads/writes it (see docs/configuration.md).\n\nvars:\n  testCommand: npm test\n  # Where gtd keeps its own scratch/bookkeeping (the check scripts' temp output\n  # file, review-deciding's state-file exclusion). Independent of the per-file\n  # vars below — relocating a file wholesale means setting both.\n  stateDir: .gtd\n  todoFile: .gtd/TODO.md\n  requirementsFile: .gtd/REQUIREMENTS.md\n  architectureFile: .gtd/ARCHITECTURE.md\n  packagesDir: .gtd/packages\n  nextFile: .gtd/NEXT.md\n  reviewFile: .gtd/REVIEW.md\n  reviewRawFile: .gtd/REVIEW_RAW.md\n  reviewFeedbackFile: .gtd/REVIEW_FEEDBACK.md\n  feedbackFile: .gtd/FEEDBACK.md\n  specFeedbackFile: .gtd/SPEC_FEEDBACK.md\n  commitMsgFile: .gtd/COMMIT_MSG.md\n  # The two opaque model tiers every agent state draws from — repoint them here\n  # (or via a top-level `.gtdrc` `vars:` key / a `GTD_PLANNERMODEL` env var)\n  # to change every state on that tier at once. `plannerModel` (default \"smart\")\n  # is the heavier tier for the one-shot planning/technical-qa/review turns;\n  # `coderModel` (default \"base\") is the tier for the build/fix turns.\n  plannerModel: smart\n  coderModel: base\n\nsubmachines:\n  # ── DEDUP: the check/fix/escalate health triple ───────────────────────────\n  # Runs the suite; a red run records the configured feedbackFile, a green run\n  # cleans it up.\n  # The `on` rules turn that into \"fix\" vs \"$onGreen\". The fix turn retries up to\n  # 3× before escalating to a human. Invoked for the shared build tail\n  # (checking/fixing/escalate -> reviewing) and the advanced package loop\n  # (package-checking/package-fixing/package-escalate -> spec-review).\n  makeGreen:\n    params: [onGreen, escalateDescribe, checkLabel, fixLabel, escalateLabel]\n    states:\n      check:\n        actor: check\n        label: $checkLabel\n        # NOT the shared `&suiteCheck` anchor (that lives on `assertGreen`,\n        # aliased by it and by `fix-precheck`): this script also sweeps spent\n        # steering files (`todoFile`, `reviewRawFile`, `reviewFeedbackFile`) —\n        # a mechanic the entry/fix gates must NOT run, since they execute\n        # before planning, while a fresh sketch legitimately still exists.\n        script: |\n          #!/usr/bin/env bash\n          # gtd check turn — run the suite; a red run records .gtd/FEEDBACK.md, a\n          # green run cleans it up. The `on` rules decide what that means.\n          set +e\n          mkdir -p \"<%~ it.vars.stateDir %>\"\n          # Hoist every path once, at the TOP: Eta's autoTrim eats the newline\n          # after an interpolation tag, so no tag may be the last token on a\n          # line — it would glue the next line's `else`/`fi` onto it and break\n          # the script. Below this point everything is plain bash.\n          feedback=\"<%~ it.vars.feedbackFile %>\"\n          mkdir -p \"$(dirname \"$feedback\")\"\n          # Sweep steering files spent by the states that led here: the plan\n          # (building), the raw review capture (feedback-collecting), and the\n          # feedback instructions (feedback-building) — each `rm -f` is a\n          # no-op when the file is already gone or never existed on this path.\n          todo=\"<%~ it.vars.todoFile %>\"\n          reviewRaw=\"<%~ it.vars.reviewRawFile %>\"\n          reviewFeedback=\"<%~ it.vars.reviewFeedbackFile %>\"\n          rm -f \"$todo\" \"$reviewRaw\" \"$reviewFeedback\"\n          <%~ it.vars.testCommand %> > <%~ it.vars.stateDir %>/.check-output 2>&1\n          code=$?\n          if [ \"$code\" -ne 0 ]; then\n            if [ -s <%~ it.vars.stateDir %>/.check-output ]; then\n              mv <%~ it.vars.stateDir %>/.check-output \"$feedback\"\n            else\n              rm -f <%~ it.vars.stateDir %>/.check-output\n              printf 'the test command failed with exit code %s and produced no output.' \"$code\" > \"$feedback\"\n            fi\n            # A repeat identical failure would otherwise leave FEEDBACK.md\n            # byte-identical to its committed copy — no diff, so the check would\n            # look GREEN. Stamp each red run with the current HEAD (which always\n            # advances between checks) so a still-red re-run always re-registers\n            # as an M/A edit and takes the red edge.\n            printf '\\n<!-- gtd check %s -->\\n' \"$(git rev-parse --short HEAD 2>/dev/null || echo pending)\" >> \"$feedback\"\n          else\n            rm -f <%~ it.vars.stateDir %>/.check-output\n            rm -f \"$feedback\"\n          fi\n        on:\n          \"A <%= it.vars.feedbackFile %>\": fix\n          \"M <%= it.vars.feedbackFile %>\": fix\n          \"* **\": $onGreen\n          \"C\": $onGreen\n      fix:\n        actor: agent\n        label: $fixLabel\n        file: <%= it.vars.feedbackFile %>\n        model: <%= it.vars.coderModel %>\n        memory: fix\n        retry:\n          max: 3\n          otherwise: escalate\n        prompt: |\n          You are an autonomous coding agent. This workflow steers itself\n          through its own state files — treat them as its private scratchpad,\n          never as project code or documentation. The only state file this\n          turn touches is `<%= it.vars.feedbackFile %>`; fix it per its\n          contents, or delete it if the feedback turns out to be wrong. Do not\n          create other files to hold notes or output.\n\n          Read `<%= it.vars.feedbackFile %>` (the failing test output) and fix the\n          code so the suite passes. Keep the change focused — do not refactor\n          unrelated code. If the feedback is wrong, empty or delete\n          `<%= it.vars.feedbackFile %>` instead of \"fixing\" a non-issue.\n\n          Leave everything uncommitted and finish your turn — do not commit.\n        on:\n          \"* **\": check\n      escalate:\n        actor: human\n        label: $escalateLabel\n        file: <%= it.vars.feedbackFile %>\n        message: |\n          The agent could not get the check to pass after repeated attempts.\n          `<%= it.vars.feedbackFile %>` holds the last failing output.\n\n          What each change does next (then run `gtd step human`):\n          <% it.edges.forEach(function (e) { if (e.describe) { %>\n          <%~ \"- \" + (e.action ? \"**\" + e.action + \"** — \" : \"\") + e.describe + \"\\n\" %>\n          <% } }) %>\n        on:\n          \"* **\":\n            to: check\n            action: Retry check\n            describe: $escalateDescribe\n\n  # ── DEDUP: the green-baseline gate ─────────────────────────────────────────\n  # Runs the suite before any work starts (its script is the health check's test\n  # wrapper — red -> the configured feedbackFile, green -> remove it); the `on` rules turn\n  # that into \"halt at blocked\" vs \"proceed to $onGreen\". The script and blocked\n  # message/describe differ per entry, so they ride in as `with:` params.\n  assertGreen:\n    params: [onGreen, blockedMessage, blockedDescribe, checkLabel, blockedLabel]\n    states:\n      check:\n        actor: check\n        label: $checkLabel\n        # Anchored here and aliased by `fix-precheck` (`gtd fix` entry): one\n        # suite-check script shared by all four call sites (this submachine's\n        # ×3 uses plus `fix-precheck`) instead of four source copies. These gates\n        # run BEFORE planning, so — unlike `makeGreen.check` — they must NOT\n        # sweep `todoFile`/`requirementsFile`: the human's fresh sketch still\n        # legitimately exists here.\n        script: &suiteCheck |\n          #!/usr/bin/env bash\n          # gtd check turn — run the suite; a red run records .gtd/FEEDBACK.md, a\n          # green run cleans it up. The `on` rules decide what that means.\n          set +e\n          mkdir -p \"<%~ it.vars.stateDir %>\"\n          # Hoist the feedback path once, at the TOP: Eta's autoTrim eats the\n          # newline after an interpolation tag, so no tag may be the last token on\n          # a line — it would glue the next line's `else`/`fi` onto it and break\n          # the script. Below this point everything is plain bash.\n          feedback=\"<%~ it.vars.feedbackFile %>\"\n          mkdir -p \"$(dirname \"$feedback\")\"\n          <%~ it.vars.testCommand %> > <%~ it.vars.stateDir %>/.check-output 2>&1\n          code=$?\n          if [ \"$code\" -ne 0 ]; then\n            if [ -s <%~ it.vars.stateDir %>/.check-output ]; then\n              mv <%~ it.vars.stateDir %>/.check-output \"$feedback\"\n            else\n              rm -f <%~ it.vars.stateDir %>/.check-output\n              printf 'the test command failed with exit code %s and produced no output.' \"$code\" > \"$feedback\"\n            fi\n            # A repeat identical failure would otherwise leave FEEDBACK.md\n            # byte-identical to its committed copy — no diff, so the check would\n            # look GREEN. Stamp each red run with the current HEAD (which always\n            # advances between checks) so a still-red re-run always re-registers\n            # as an M/A edit and takes the red edge.\n            printf '\\n<!-- gtd check %s -->\\n' \"$(git rev-parse --short HEAD 2>/dev/null || echo pending)\" >> \"$feedback\"\n          else\n            rm -f <%~ it.vars.stateDir %>/.check-output\n            rm -f \"$feedback\"\n          fi\n        on:\n          \"A <%= it.vars.feedbackFile %>\": blocked\n          \"M <%= it.vars.feedbackFile %>\": blocked\n          \"D <%= it.vars.feedbackFile %>\": $onGreen\n          \"C\": $onGreen\n      blocked:\n        actor: human\n        label: $blockedLabel\n        file: <%= it.vars.feedbackFile %>\n        message: $blockedMessage\n        on:\n          \"* **\":\n            to: check\n            action: Retry check\n            describe: $blockedDescribe\n\n  # ── DEDUP: the checkbox Q&A author/answer loop ─────────────────────────────\n  # The agent develops a plan file, surfacing `## Open Questions` as checkbox\n  # lists; the human answers (answerGate refuses an unanswered step) and either\n  # advances or sends it back. Invoked for the product (product-qa) and\n  # technical (technical-qa) phases of the advanced flow.\n  qaLoop:\n    params:\n      [\n        authorFile,\n        authorPrompt,\n        answerMessage,\n        onAdvance,\n        advanceDescribe,\n        editDescribe,\n        authorLabel,\n        answerLabel,\n      ]\n    states:\n      author:\n        actor: agent\n        label: $authorLabel\n        file: $authorFile\n        mode: qa\n        model: <%= it.vars.plannerModel %>\n        memory: plan\n        prompt: $authorPrompt\n        on:\n          \"* **\": answer\n      answer:\n        actor: human\n        label: $answerLabel\n        file: $authorFile\n        mode: qa\n        answerGate: true\n        message: $answerMessage\n        on:\n          \"C\":\n            to: $onAdvance\n            action: Accept answers\n            describe: $advanceDescribe\n          \"* **\":\n            to: author\n            action: Revise answers\n            describe: $editDescribe\n\n  # ── ENCAPSULATION: the simple flow's plan-iteration loop ───────────────────\n  planLoop:\n    params: [onAccept]\n    states:\n      planning:\n        actor: agent\n        label: Refining the plan\n        file: <%= it.vars.todoFile %>\n        mode: prose\n        model: <%= it.vars.plannerModel %>\n        memory: plan\n        prompt: |\n          You are an autonomous coding agent. This workflow steers itself\n          through its own state files — treat them as its private scratchpad,\n          never as project code or documentation. The only state file this\n          turn touches is `<%= it.vars.todoFile %>`; develop it into the plan.\n          Do not create other files to hold notes or output.\n\n          `<%= it.vars.todoFile %>` holds a short sketch of what to build — or, on a\n          return lap, the plan you already wrote plus the human's edits and comments\n          on it. Read it, explore the codebase, and develop it into a concrete\n          implementation plan: the files to change, the approach, and the steps to\n          take.\n\n          Do NOT ask questions and do NOT add an \"Open Questions\" section — decide\n          every open point yourself and write the plan as a set of concrete\n          decisions. Where a decision is genuinely a judgement call, state the\n          choice you made and, in one line, why. The human iterates on the plan by\n          editing it directly, not by answering questions.\n\n          On a return lap, `<%= it.vars.todoFile %>` carries the human's edits and\n          inline comments on your previous plan. Fold every edit and comment into a\n          revised, self-contained plan and remove the addressed comments — the plan\n          is always the current, clean proposal, never a diff.\n\n          Leave `<%= it.vars.todoFile %>` uncommitted and finish your turn — do\n          not commit, and do not run `gtd step agent` yourself; the harness does\n          that.\n        on:\n          \"* **\": await-plan\n\n      await-plan:\n        actor: human\n        label: Awaiting your review\n        file: <%= it.vars.todoFile %>\n        mode: prose\n        message: |\n          `<%= it.vars.todoFile %>` holds the proposed implementation plan. Read it,\n          then either accept it as-is or edit it — rewrite a step, add a\n          constraint, or drop an inline comment — to send it back for another round.\n\n          What each change does next (then run `gtd step human`):\n          <% it.edges.forEach(function (e) { if (e.describe) { %>\n          <%~ \"- \" + (e.action ? \"**\" + e.action + \"** — \" : \"\") + e.describe + \"\\n\" %>\n          <% } }) %>\n        on:\n          \"C\":\n            to: $onAccept\n            action: Accept plan\n            describe: >-\n              change nothing to move on to implementation (**building**).\n          \"* **\":\n            to: planning\n            action: Revise plan\n            describe: >-\n              rewrite a step, add a constraint, or leave an inline comment to\n              send it back for another round (**planning**).\n\n  # ── ENCAPSULATION: the shared review tail ──────────────────────────────────\n  humanReview:\n    params: [onSignoff]\n    states:\n      reviewing:\n        actor: agent\n        label: Reviewing\n        file: <%= it.vars.reviewFile %>\n        mode: review\n        model: <%= it.vars.plannerModel %>\n        memory: review\n        # `gtd review <commitish>` (a plain non-gtd branch, e.g. a colleague's PR)\n        # does NOT enter here directly — it enters `review-precheck` (reviewEntry)\n        # first, which runs the green-baseline gate and, once green, transitions\n        # here. The `Gtd-Review-Base:` trailer rides on that entry commit (the\n        # process's oldest), so everything below still reuses the same\n        # reviewing/await-review/feedback machinery over <commitish>..HEAD.\n        prompt: |\n          You are an autonomous coding agent. This workflow steers itself\n          through its own state files — treat them as its private scratchpad,\n          never as project code or documentation. The only state file this\n          turn touches is `<%= it.vars.reviewFile %>`; write it at exactly\n          that path. Do not create other files to hold notes or output.\n\n          Write `<%= it.vars.reviewFile %>` to help a human review the changes in\n          this EXACT format:\n\n          - First non-blank line: `# Review: <%= it.currentCommit.slice(0, 7) %>`\n          - Somewhere in the document: `<!-- base: <%= it.reviewBase %> -->`\n          - At least one `## <Chunk Title>` heading, grouping hunks semantically\n            (same feature/refactor/fix, even across files) — a short explanation of\n            what changed and why, then one `- [ ] ./path/to/file.ts#42 — note` file\n            pointer per hunk (checkboxes are for the human to tick, not you; every\n            path is `./`-relative, with an optional `#line` and an optional\n            ` — note`).\n\n          This prompt carries no diff — read the changes yourself. The range runs\n          from `<%= it.reviewBase %>` to the working tree (committed turns plus\n          anything still pending); on a feedback round that base is the previous\n          review's boundary, so it covers only what changed since then, not items\n          already signed off.\n\n          Leave `<%= it.vars.reviewFile %>` uncommitted and finish your turn.\n        on:\n          \"* **\": await-review\n\n      await-review:\n        actor: human\n        label: Awaiting your review\n        file: <%= it.vars.reviewFile %>\n        mode: review\n        # While the cycle rests here, gtd opens a \"review checkout window\": raw HEAD\n        # is rewound to the review base (the most-recent `review-deciding` commit —\n        # so a feedback round shows only `last-review..HEAD` — or the process start\n        # on the first review) with the working tree untouched, surfacing the diff\n        # as ordinary uncommitted changes. It closes on the next invocation.\n        #\n        # Every human step here routes to `review-deciding`, which decides sign-off\n        # vs. feedback from the step's CONTENT (a comment, not a tick). Ticking a box\n        # only records \"I reviewed this hunk\". Two dead ends can't be told apart by a\n        # file-pattern edge, so the sign-off gate (`enforceReviewSignoffGate` in\n        # src/program.ts) catches them BEFORE the step commits and refuses: an\n        # unfinished review (a box still `- [ ]` with no comment) and a deleted\n        # REVIEW.md.\n        reviewWindow: true\n        message: |\n          `<%= it.vars.reviewFile %>` holds the review record for the cycle — one\n          `- [ ]` checkbox per reviewable item, grouped into chunks. Tick a box\n          (`- [x]`) as you review each hunk; ticking only records that you've read\n          it, it is not sign-off.\n\n          When you've been through the whole diff, run `gtd step human`:\n\n          - **Sign off** — tick EVERY box and leave no comment — no note in\n            `<%= it.vars.reviewFile %>`, no code edit — to collapse the cycle into\n            one commit (**squashing**).\n          - **Request changes** — leave a comment: a note on a\n            `<%= it.vars.reviewFile %>` line, or a direct code edit — to send it to a\n            build + re-review round (**review-deciding** → **feedback-building**). A\n            code edit counts as your own fix: the agent completes the follow-through\n            it implies and never reverts your lines.\n\n          Stepping with a box still unticked and no comment is refused (finish\n          reviewing first); so is deleting `<%= it.vars.reviewFile %>`.\n        on:\n          \"* **\": review-deciding\n\n      review-deciding:\n        actor: check\n        label: Reviewing\n        file: <%= it.vars.reviewFile %>\n        mode: review\n        # Anchors the INCREMENTAL review base: its most-recent in-process commit is\n        # the point the previous review round ended, so the next `reviewing` turn\n        # (and the review checkout window) covers only the changes since then. On\n        # the first review there is no such commit, so the base is the cycle start.\n        reviewBase: true\n        script: |\n          #!/usr/bin/env bash\n          # gtd check turn — decide the human's review step from its CONTENT. HEAD is\n          # the human's `await-review -> review-deciding` commit; HEAD^ is the\n          # `reviewing` commit that wrote the agent's original REVIEW.md (the sign-off\n          # gate refuses an incomplete step, so review-deciding is entered exactly\n          # once per round — nothing commits in between). It is FEEDBACK when the\n          # human left a comment: a note in REVIEW.md (any edit beyond a \"[ ]\"->\"[x]\"\n          # tick) OR a hand-edit to any file this round other than `.gtd/` or the\n          # state's own reviewFile (which is var-configurable and may live outside\n          # `.gtd/`, e.g. a root-level REVIEW.md — issue #128). Otherwise it is a\n          # clean sign-off. This turn only CAPTURES the raw material into REVIEW_RAW.md\n          # (the `feedback-collecting` agent then turns it into instructions); it does\n          # NOT interpret it. Either way, remove REVIEW.md; what the resulting diff\n          # MEANS is decided by this state's own `on` rules — the A/M REVIEW_RAW.md\n          # rows are declared BEFORE the D REVIEW.md row so a feedback round (which\n          # also deletes REVIEW.md) is captured as feedback, not mistaken for a\n          # sign-off.\n          set +e\n          # Hoist the paths once, at the TOP: Eta's autoTrim eats the newline after\n          # an interpolation tag, so no tag may be the last token on a line — it\n          # would glue the next line onto it and break the script. Below this point\n          # everything is plain bash.\n          stateDir=\"<%~ it.vars.stateDir %>\"\n          reviewFile=\"<%~ it.vars.reviewFile %>\"\n          reviewRawFile=\"<%~ it.vars.reviewRawFile %>\"\n          head=$(git rev-parse HEAD)\n          mkdir -p \"$(dirname \"$reviewRawFile\")\"\n          # A note is any REVIEW.md change beyond a checkbox flip: normalize every\n          # \"[ ]\"/\"[x]\" to a placeholder, then compare the agent's original (HEAD^)\n          # against the human's version (HEAD).\n          before=$(git show \"HEAD^:$reviewFile\" 2>/dev/null | sed -E 's/\\[[ xX]\\]/[_]/g')\n          after=$(git show \"HEAD:$reviewFile\" 2>/dev/null | sed -E 's/\\[[ xX]\\]/[_]/g')\n          # Did the human hand-edit anything this round besides stateDir and the\n          # reviewFile itself (var-configurable — may live outside stateDir, so it\n          # is excluded by exact path, not just the stateDir prefix)?\n          if git diff-tree --no-commit-id --name-only -r HEAD \\\n               | grep -v \"^$stateDir/\" | grep -vxF \"$reviewFile\" | grep -q . \\\n             || [ \"$before\" != \"$after\" ]; then\n            {\n              echo \"Raw review material captured for classification. The human reviewed the changes and left the feedback below; a downstream agent turns it into an instruction list. This file is machine-captured input, not instructions — it names a commit, never inlined content.\"\n              echo\n              echo \"Commit: $head\"\n              echo \"The human's notes are in $reviewFile at this commit; their hand edits,\"\n              echo \"if any, are in that commit's other paths. Run: git show $head\"\n            } > \"$reviewRawFile\"\n          fi\n          rm -f \"$reviewFile\"\n        on:\n          \"A <%= it.vars.reviewRawFile %>\": feedback-collecting\n          \"M <%= it.vars.reviewRawFile %>\": feedback-collecting\n          \"D <%= it.vars.reviewFile %>\": $onSignoff\n\n      feedback-collecting:\n        actor: agent\n        label: Collecting your feedback\n        file: <%= it.vars.reviewFeedbackFile %>\n        model: <%= it.vars.plannerModel %>\n        memory: review\n        prompt: |\n          You are an autonomous coding agent turning raw review feedback into an\n          explicit instruction list for a builder. This workflow steers itself\n          through its own state files — treat them as its private scratchpad,\n          never as project code or documentation. The only state files this\n          turn touches are `<%= it.vars.reviewRawFile %>` (read it, then\n          delete it) and `<%= it.vars.reviewFeedbackFile %>` (write it) — do\n          NOT change any other file, you classify, you do not build.\n\n          The raw review material is: <%~ it.read(it.vars.reviewRawFile) %>\n\n          It names a commit — read that commit's diff yourself before classifying\n          anything.\n\n          Classify every piece of it into `<%= it.vars.reviewFeedbackFile %>` as a\n          flat, numbered instruction list. Each item is `N. ./path/to/file.ts#line —\n          <imperative>`. Apply these rules exactly:\n\n          1. NOTES the human added to REVIEW.md — each note is a MANDATORY change,\n             regardless of whether its checkbox is ticked (ticking means only \"I read\n             this hunk\", never sign-off). Anchor each to the `./path#line` its review\n             item names (or the chunk it sits under). Emit it as a concrete\n             imperative.\n          2. Every COMMENT the human ADDED this round (a `+` line that is a code\n             comment, in the hand-edited files) is a MANDATORY instruction the human\n             is giving the builder — even a plain-prose one, even if its box is\n             ticked. Emit an imperative to satisfy it and note that the comment line\n             itself must be REMOVED once addressed. If a comment turns out to describe\n             behaviour the code already has, the instruction is still \"confirm the\n             code matches and remove the comment line\".\n          3. Every NON-comment code line the human hand-edited is an already-committed\n             INTENT, NOT a do-then-delete item. Emit an instruction that names those\n             files and says: their lines are final — complete ONLY the follow-through\n             they imply (callers, tests, types, docs) and NEVER revert or rewrite\n             them. Do not turn their own edit into a task.\n\n          Split each hand-edited hunk per line: comment `+` lines follow rule 2, the\n          surrounding real code follows rule 3.\n\n          If — and only if — nothing in the raw material is actionable (e.g. the human\n          left only an approving remark), write `<%= it.vars.reviewFeedbackFile %>`\n          containing exactly one line: `NOTHING ACTIONABLE — <one-sentence reason>`.\n          Never invent work to satisfy a non-actionable remark.\n\n          Delete `<%= it.vars.reviewRawFile %>`, leave everything else uncommitted,\n          and finish your turn.\n        on:\n          \"A <%= it.vars.reviewFeedbackFile %>\": feedback-building\n          \"M <%= it.vars.reviewFeedbackFile %>\": feedback-building\n\n      feedback-building:\n        actor: agent\n        label: Addressing your feedback\n        file: <%= it.vars.reviewFeedbackFile %>\n        model: <%= it.vars.coderModel %>\n        memory: build\n        # Refuse a work-free turn: a step whose only pending change is deleting the\n        # instructions file (the original \"captured then discarded\" bug). The edge\n        # gate (`enforceFeedbackProgressGate` in src/program.ts) reads this flag and\n        # exempts a `NOTHING ACTIONABLE` sentinel (a non-actionable review round,\n        # which legitimately makes no code change). The pure engine carries it inert.\n        requireProgress: true\n        prompt: |\n          You are an autonomous coding agent addressing review feedback. This\n          workflow steers itself through its own state files — treat them as\n          its private scratchpad, never as project code or documentation. The\n          only state file this turn touches is\n          `<%= it.vars.reviewFeedbackFile %>`; address it, then delete it. Do\n          not create other files to hold notes or output.\n\n          The instructions to implement are: <%~ it.read(it.vars.reviewFeedbackFile) %>\n\n          This is a flat instruction list, not a diff — execute every item exactly as\n          written, no Q&A, no re-planning, using TDD discipline:\n\n          - An item that says the human's own lines are final: build ON TOP of them to\n            complete only the follow-through it names (callers, tests, types, docs).\n            NEVER revert or rewrite the lines they already committed.\n          - An item derived from a human comment: satisfy it AND delete that comment\n            line from the code (the human's review comments are transient — none of\n            them survive this round).\n\n          If the file's sole content is a `NOTHING ACTIONABLE` line, make no code\n          change; just delete the instructions file.\n\n          Delete `<%= it.vars.reviewFeedbackFile %>` once every item is addressed.\n          Leave everything else uncommitted and finish your turn. Deleting the\n          instructions file WITHOUT making the changes it asks for is refused — the\n          feedback must actually be addressed.\n        on:\n          \"* **\": checking\n\n  # ── ENCAPSULATION: the advanced flow's per-package agentic review ──────────\n  specGate:\n    params: [onApproved]\n    states:\n      spec-review:\n        actor: agent\n        label: Reviewing the package\n        model: <%= it.vars.plannerModel %>\n        memory: review\n        # Bounded per cycle: once entered `max` times, a transition into it is\n        # redirected to `closing` (force-close the package and move on — the\n        # unresolved concern is deferred to the shared human review at the tail,\n        # which sees the whole diff anyway). NOTE the cap is PROCESS-scoped, so it\n        # pools across packages — the same documented limitation the shared\n        # `fixing` cap has (see STATES.md / docs/configuration.md).\n        retry:\n          max: 3\n          otherwise: $onApproved\n        prompt: |\n          You are an autonomous coding agent reviewing a freshly-built work package\n          against its own spec. This workflow steers itself through its own\n          state files — treat them as its private scratchpad, never as project\n          code or documentation. The only state file this turn touches is\n          `<%= it.vars.specFeedbackFile %>`; write it only when — and only\n          when — you find problems. Do not create other files to hold notes or\n          output.\n\n          The package spec is: <%~ it.read(it.vars.nextFile) %>\n\n          Read that spec, then verify the package's implementation against it: are\n          all its tasks done, acceptance criteria met, and the code sound and\n          consistent with the codebase? This prompt carries no diff — read it\n          yourself: the range runs from `<%= it.startCommit %>` to the working\n          tree.\n\n          Note the range is process-wide (from the start of the whole build, not\n          just this package), so it can span earlier packages too.\n\n          - If it fully satisfies the spec, write NOTHING and finish your turn — a\n            clean turn is your approval.\n          - If it does not, write `<%= it.vars.specFeedbackFile %>` listing the\n            concrete problems for a fix turn to address. Be specific.\n\n          Do not fix anything yourself and do not delete the package file — a later\n          step owns that. Finish your turn.\n        on:\n          \"A <%= it.vars.specFeedbackFile %>\": spec-fix\n          \"M <%= it.vars.specFeedbackFile %>\": spec-fix\n          \"D <%= it.vars.specFeedbackFile %>\": $onApproved\n          \"C\": $onApproved\n\n      spec-fix:\n        actor: agent\n        label: Fixing review feedback\n        file: <%= it.vars.specFeedbackFile %>\n        model: <%= it.vars.coderModel %>\n        memory: fix\n        prompt: |\n          You are an autonomous coding agent. This workflow steers itself\n          through its own state files — treat them as its private scratchpad,\n          never as project code or documentation. The only state file this\n          turn touches is `<%= it.vars.specFeedbackFile %>`; address it, then\n          delete it. Do not create other files to hold notes or output.\n\n          Read `<%= it.vars.specFeedbackFile %>` (the reviewer's concerns about the\n          current package) and the package spec (`<%= it.read(it.vars.nextFile) %>`),\n          then fix the code to resolve every concern. Keep the change focused.\n\n          Delete `<%= it.vars.specFeedbackFile %>` once every concern is addressed.\n          Leave everything else uncommitted and finish your turn.\n        on:\n          \"* **\": package-checking\n\n  # ── ENCAPSULATION: the advanced flow's per-package build queue ─────────────\n  packageLoop:\n    params: [onDrained]\n    states:\n      picking:\n        actor: check\n        label: Picking the next package\n        script: |\n          #!/usr/bin/env bash\n          # gtd check turn (the package queue arbiter) — the loop driver executes\n          # this verbatim, then steps the check actor. Mechanics only: take the\n          # first package file (by name) under the packages dir into NEXT.md, or\n          # remove NEXT.md when the queue is empty. What NEXT.md's presence/absence\n          # MEANS (another package to build vs. the queue closing out to review) is\n          # decided by this state's own `on` rules at capture time — never here.\n          set +e\n          # Hoist the NEXT path once, at the TOP: Eta's autoTrim eats the newline\n          # after an interpolation tag, so no tag may be the last token on a line —\n          # it would glue the next line's `else`/`fi` onto it and break the script.\n          # Below this point everything is plain bash.\n          nextFile=\"<%~ it.vars.nextFile %>\"\n          # Sweep the advanced flow's spent Q&A steering files: requirementsFile\n          # is consumed by technical-qa, architectureFile by decompose — both are\n          # gone by the time the package queue starts. No-op if already removed.\n          requirements=\"<%~ it.vars.requirementsFile %>\"\n          architecture=\"<%~ it.vars.architectureFile %>\"\n          rm -f \"$requirements\" \"$architecture\"\n          next=$(ls <%~ it.vars.packagesDir %>/*.md 2>/dev/null | head -n 1)\n          if [ -n \"$next\" ]; then\n            mkdir -p \"$(dirname \"$nextFile\")\"\n            printf '%s' \"$next\" > \"$nextFile\"\n          else\n            rm -f \"$nextFile\"\n          fi\n        on:\n          \"D <%= it.vars.nextFile %>\": $onDrained\n          \"* <%= it.vars.nextFile %>\": package-building\n          \"C\": $onDrained\n\n      package-building:\n        actor: agent\n        label: Building\n        model: <%= it.vars.coderModel %>\n        memory: build\n        prompt: |\n          You are an autonomous coding agent. This workflow steers itself\n          through its own state files — treat them as its private scratchpad,\n          never as project code or documentation. This turn writes no state\n          file: do NOT delete the package file (the `spec-review` gate reads\n          it after you) and never touch `<%= it.vars.nextFile %>` — the\n          `picking` state owns it.\n\n          The package to implement is: <%~ it.read(it.vars.nextFile) %>\n\n          That file describes a set of INDEPENDENT tasks. Implement ALL of them in\n          this one turn, fanning the independent tasks out to parallel subagents\n          where your harness supports it — each task is self-contained and can be\n          built concurrently. Implement EXACTLY the tasks this package describes — no\n          more, no less; leave every other package file untouched. Use TDD\n          discipline within each task.\n\n          Leave the package file in place and everything else uncommitted, then\n          finish your turn.\n        on:\n          \"* **\": package-checking\n\n      closing:\n        actor: check\n        label: Closing out the package\n        script: |\n          #!/usr/bin/env bash\n          # gtd check turn (the package closer) — remove the just-reviewed package\n          # file (its path is in NEXT.md) plus any leftover spec feedback, so\n          # `picking` selects the NEXT package (or falls through to review when the\n          # queue is empty). Reached on approval (spec-review clean) and on the\n          # spec-review retry cap (force-close, deferring the concern to the tail).\n          set +e\n          pkg=$(cat <%~ it.vars.nextFile %> 2>/dev/null)\n          [ -n \"$pkg\" ] && rm -f \"$pkg\"\n          rm -f <%~ it.vars.specFeedbackFile %> <%~ it.vars.nextFile %>\n        on:\n          \"* **\": picking\n\nuse:\n  # Shared health triple: checking/fixing/escalate -> reviewing.\n  - submachine: makeGreen\n    name: build\n    as: { check: checking, fix: fixing, escalate: escalate }\n    with:\n      onGreen: reviewing\n      escalateDescribe: >-\n        edit the code and/or `.gtd/FEEDBACK.md` yourself (**checking**).\n      checkLabel: Running checks\n      fixLabel: Fixing the check\n      escalateLabel: Escalating to a human\n  # Advanced package health triple: package-checking/package-fixing/package-escalate -> spec-review.\n  - submachine: makeGreen\n    name: package\n    as: { check: package-checking, fix: package-fixing, escalate: package-escalate }\n    with:\n      onGreen: spec-review\n      escalateDescribe: >-\n        edit the code and/or `.gtd/FEEDBACK.md` yourself (**package-checking**).\n      checkLabel: Running checks\n      fixLabel: Fixing the check\n      escalateLabel: Escalating to a human\n\n  # Green-baseline gate: simple flow entry.\n  - submachine: assertGreen\n    name: plan\n    as: { check: plan-precheck, blocked: plan-blocked }\n    with:\n      onGreen: planning\n      blockedMessage: |\n        The test baseline is red — gtd will not start new work on a broken suite.\n        `<%= it.vars.feedbackFile %>` holds the failing output.\n\n        What each change does next (then run `gtd step human`):\n        <% it.edges.forEach(function (e) { if (e.describe) { %>\n        <%~ \"- \" + (e.action ? \"**\" + e.action + \"** — \" : \"\") + e.describe + \"\\n\" %>\n        <% } }) %>\n      blockedDescribe: >-\n        edit the code and/or `.gtd/FEEDBACK.md` to fix the failing tests\n        (**plan-precheck**). To repair the baseline as its own separate\n        reviewed commit instead, abandon this start and run `gtd fix` from a\n        clean `idle`.\n      checkLabel: Checking the baseline\n      blockedLabel: Baseline is red\n\n  # Green-baseline gate: advanced flow entry.\n  - submachine: assertGreen\n    name: spec\n    as: { check: spec-precheck, blocked: spec-blocked }\n    with:\n      onGreen: product-qa\n      blockedMessage: |\n        The test baseline is red — gtd will not start new work on a broken suite.\n        `<%= it.vars.feedbackFile %>` holds the failing output.\n\n        What each change does next (then run `gtd step human`):\n        <% it.edges.forEach(function (e) { if (e.describe) { %>\n        <%~ \"- \" + (e.action ? \"**\" + e.action + \"** — \" : \"\") + e.describe + \"\\n\" %>\n        <% } }) %>\n      blockedDescribe: >-\n        edit the code and/or `.gtd/FEEDBACK.md` to fix the failing tests\n        (**spec-precheck**). To repair the baseline as its own separate\n        reviewed commit instead, abandon this start and run `gtd fix` from a\n        clean `idle`.\n      checkLabel: Checking the baseline\n      blockedLabel: Baseline is red\n\n  # Green-baseline gate: `gtd review` entry (reviewEntry -> reviewing).\n  - submachine: assertGreen\n    name: review\n    as: { check: review-precheck, blocked: review-blocked }\n    set:\n      check: { reviewEntry: true }\n    with:\n      onGreen: reviewing\n      blockedMessage: |\n        The test baseline is red — gtd will not start a review on a broken suite.\n        `<%= it.vars.feedbackFile %>` holds the failing output.\n\n        What each change does next (then run `gtd step human`):\n        <% it.edges.forEach(function (e) { if (e.describe) { %>\n        <%~ \"- \" + (e.action ? \"**\" + e.action + \"** — \" : \"\") + e.describe + \"\\n\" %>\n        <% } }) %>\n      blockedDescribe: >-\n        edit the code and/or `.gtd/FEEDBACK.md` to fix the failing tests\n        (**review-precheck**).\n      checkLabel: Checking the baseline\n      blockedLabel: Baseline is red\n\n  # Advanced flow: product Q&A loop (product-qa/product-answer -> technical-qa).\n  - submachine: qaLoop\n    name: product\n    as: { author: product-qa, answer: product-answer }\n    with:\n      authorFile: <%= it.vars.requirementsFile %>\n      onAdvance: technical-qa\n      authorPrompt: |\n        You are an autonomous coding agent. This workflow steers itself\n        through its own state files — treat them as its private scratchpad,\n        never as project code or documentation. The only state file this turn\n        touches is `<%= it.vars.requirementsFile %>`; develop it. Do not\n        create other files to hold notes or output.\n\n        `<%= it.vars.requirementsFile %>` holds the product requirements (or the\n        plan you already wrote plus the human's answers on a return lap). Read it,\n        explore the codebase, and develop it into a concrete, PRODUCT-level plan\n        in this one turn.\n\n        Scope: product and user-facing decisions only. Leave implementation\n        details (file/module structure, data models, tech-stack choices) for the\n        next phase (`<%= it.vars.architectureFile %>`).\n\n        For every open point you cannot settle yourself, add a question under a\n        `## Open Questions` heading near the top: one `### <question>` sub-heading\n        each, followed by a checkbox list of candidate answers — aim for TWO\n        concrete options plus a final free-text slot, ALL left UNTICKED:\n\n            ### <the question>\n\n            - [ ] <first option — a concrete answer, a few words of rationale>\n            - [ ] <second option>\n            - [ ] _your answer_\n\n        Never tick a box yourself — the human ticks exactly one per question. The\n        last `- [ ] _your answer_` line is the human's own-answer slot; write it\n        with the literal `_your answer_` placeholder and leave it for them.\n\n        On a RETURN lap the human has ticked one option per question (or replaced\n        `_your answer_` with their own text). For each answered question: fold the\n        chosen answer into the plan prose, then MOVE the question down into a\n        `## Answered Questions` section as `### <question>` followed by the\n        resolved answer in plain PROSE (drop the checkboxes). Never re-raise a\n        question the human deleted; if the human deleted the whole\n        `## Open Questions` section, treat the plan as accepted and surface no new\n        questions unless something is genuinely still blocking. Omit\n        `## Open Questions` entirely once there are none left.\n\n        Leave `<%= it.vars.requirementsFile %>` uncommitted and finish your turn.\n      answerMessage: |\n        `<%= it.vars.requirementsFile %>` holds the product plan under\n        development. Each question under `## Open Questions` offers a few options\n        plus a `- [ ] _your answer_` slot. Answer EVERY question by ticking\n        exactly one box (`- [x]`); for your own answer, replace `_your answer_`\n        with your text and tick that line. Stepping is refused while any question\n        is unanswered.\n\n        What each change does next (then run `gtd step human`):\n        <% it.edges.forEach(function (e) { if (e.describe) { %>\n        <%~ \"- \" + (e.action ? \"**\" + e.action + \"** — \" : \"\") + e.describe + \"\\n\" %>\n        <% } }) %>\n      advanceDescribe: >-\n        with no open questions left (the agent surfaced none, or you deleted\n        the section and it finalized the plan), change nothing to move on to\n        technical Q&A (**technical-qa**).\n      editDescribe: >-\n        tick exactly one option per open question (replace `_your answer_` for\n        your own) to send the plan back for the agent to fold your answers in\n        (**product-qa**). Delete a question to skip it, or delete the whole\n        `## Open Questions` section to accept the plan as-is.\n      authorLabel: Refining the product plan\n      answerLabel: Awaiting your answers\n\n  # Advanced flow: technical Q&A loop (technical-qa/technical-answer -> decompose).\n  - submachine: qaLoop\n    name: technical\n    as: { author: technical-qa, answer: technical-answer }\n    with:\n      authorFile: <%= it.vars.architectureFile %>\n      onAdvance: decompose\n      authorPrompt: |\n        You are an autonomous coding agent. This workflow steers itself\n        through its own state files — treat them as its private scratchpad,\n        never as project code or documentation. The only state files this\n        turn touches are `<%= it.vars.architectureFile %>` (write it) and\n        `<%= it.vars.requirementsFile %>` (delete it once its content is\n        folded in). Do not create other files to hold notes or output.\n\n        Read `<%= it.vars.requirementsFile %>` (the converged product plan) and\n        develop `<%= it.vars.architectureFile %>` from it in this one turn:\n        file/module structure, data models, library/tech-stack choices,\n        error-handling strategy — the *how*, building on the *what* already\n        settled. Do not re-open product-level decisions; treat them as settled.\n\n        For every open point you cannot settle yourself, add a question under a\n        `## Open Questions` heading exactly as the grilling phase does: one\n        `### <question>` each, followed by a checkbox list — TWO concrete options\n        plus a final free-text slot, ALL left UNTICKED:\n\n            ### <the question>\n\n            - [ ] <first option>\n            - [ ] <second option>\n            - [ ] _your answer_\n\n        Never tick a box yourself. On a RETURN lap the human has ticked one option\n        per question (or replaced `_your answer_` with their own text): fold each\n        chosen answer into the plan prose, then MOVE the question into a\n        `## Answered Questions` section as `### <question>` + the resolved answer\n        in plain PROSE (drop the checkboxes). Never re-raise a deleted question;\n        treat a deleted `## Open Questions` section as acceptance. Omit\n        `## Open Questions` once there are none left.\n\n        Once `<%= it.vars.architectureFile %>` is written, delete\n        `<%= it.vars.requirementsFile %>` — its content has been folded in and it\n        must not linger. Leave everything uncommitted and finish your turn.\n      answerMessage: |\n        `<%= it.vars.architectureFile %>` holds the technical plan under\n        development. Each question under `## Open Questions` offers a few options\n        plus a `- [ ] _your answer_` slot. Answer EVERY question by ticking\n        exactly one box (`- [x]`); for your own answer, replace `_your answer_`\n        with your text and tick that line. Stepping is refused while any question\n        is unanswered.\n\n        What each change does next (then run `gtd step human`):\n        <% it.edges.forEach(function (e) { if (e.describe) { %>\n        <%~ \"- \" + (e.action ? \"**\" + e.action + \"** — \" : \"\") + e.describe + \"\\n\" %>\n        <% } }) %>\n      advanceDescribe: >-\n        with no open questions left (the agent surfaced none, or you deleted\n        the section and it finalized the plan), change nothing to move on to\n        decomposing the work into packages (**decompose**).\n      editDescribe: >-\n        tick exactly one option per open question (replace `_your answer_` for\n        your own) to send the plan back for the agent to fold your answers in\n        (**technical-qa**). Delete a question to skip it, or delete the whole\n        `## Open Questions` section to accept the plan as-is.\n      authorLabel: Refining the technical plan\n      answerLabel: Awaiting your answers\n\n  # Simple flow plan-iteration loop (planning/await-plan -> building).\n  - submachine: planLoop\n    with:\n      onAccept: building\n\n  # Shared review tail (reviewing -> await-review -> ... -> squashing).\n  - submachine: humanReview\n    with:\n      onSignoff: squashing\n\n  # Advanced per-package agentic review (spec-review/spec-fix -> closing).\n  - submachine: specGate\n    with:\n      onApproved: closing\n\n  # Advanced per-package build queue (picking/package-building/closing -> reviewing).\n  - submachine: packageLoop\n    with:\n      onDrained: reviewing\n\nstates:\n  # ── Shared entry ────────────────────────────────────────────────────────\n  idle:\n    actor: human\n    initial: true\n    label: Idle\n    # Every human-gate `message:` below closes with the same rendered \"What\n    # each change does next\" list, built from `it.edges` (the resting state's\n    # own `on` edges — each edge's `describe:` is the single source of truth).\n    message: |\n      No active gtd cycle.\n\n      To start one, create a steering file describing what you want built:\n\n      - `<%= it.vars.todoFile %>` — a short sketch — starts the SIMPLE flow\n        (plan, build, review).\n      - `<%= it.vars.requirementsFile %>` — the product requirements — starts\n        the ADVANCED flow (product + technical Q&A, package decomposition,\n        parallel build, per-package agentic review).\n\n      What each change does next (then run `gtd step human`):\n      <% it.edges.forEach(function (e) { if (e.describe) { %>\n      <%~ \"- \" + (e.action ? \"**\" + e.action + \"** — \" : \"\") + e.describe + \"\\n\" %>\n      <% } }) %>\n    on:\n      \"* <%= it.vars.requirementsFile %>\":\n        to: spec-precheck\n        action: Start advanced flow\n        describe: >-\n          save the product requirements to `.gtd/REQUIREMENTS.md` — gtd first\n          checks the test baseline is green, then the agent develops them\n          through product then technical Q&A, decomposes the work into\n          packages, and builds each in parallel (**spec-precheck**).\n      \"* **\":\n        to: plan-precheck\n        action: Start simple flow\n        describe: >-\n          save a short sketch to `.gtd/TODO.md` (or any other change) — gtd\n          first checks the test baseline is green, then the agent reads it,\n          explores the codebase, and develops it into a concrete\n          implementation plan (**plan-precheck**).\n\n  # ── Simple flow: monolithic build (plan loop is the `planLoop` sub-machine) ─\n  building:\n    actor: agent\n    label: Building\n    file: <%= it.vars.todoFile %>\n    model: <%= it.vars.coderModel %>\n    memory: build\n    prompt: |\n      You are an autonomous coding agent. This workflow steers itself through\n      its own state files — treat them as its private scratchpad, never as\n      project code or documentation. The only state file this turn touches is\n      `<%= it.vars.todoFile %>`; delete it once its work is complete. Do not\n      create other files to hold notes or output.\n\n      The plan to implement is: <%~ it.read(it.vars.todoFile) %>\n\n      Read that plan and implement it in full. Use TDD discipline: one test,\n      then the implementation that passes it, then the next — never write all\n      the tests first.\n\n      Delete `<%= it.vars.todoFile %>` once the work it describes is complete\n      and verified. Leave everything else uncommitted and finish your turn.\n    on:\n      \"* **\": checking\n\n  # ── Advanced flow: decomposition (Q&A loops are the `qaLoop` sub-machine) ───\n  decompose:\n    actor: agent\n    label: Decomposing into packages\n    model: <%= it.vars.coderModel %>\n    memory: build\n    prompt: |\n      You are an autonomous coding agent. This workflow steers itself through\n      its own state files — treat them as its private scratchpad, never as\n      project code or documentation. The only state files this turn touches\n      are the package files it writes under `<%= it.vars.packagesDir %>/` and\n      `<%= it.vars.architectureFile %>`, which it deletes. Do not create other\n      files to hold notes or output.\n\n      Read `<%= it.vars.architectureFile %>` (the converged technical plan) and\n      decompose it into an ordered set of WORK PACKAGES, one file each under\n      `<%= it.vars.packagesDir %>/` (e.g. `<%= it.vars.packagesDir %>/01-name.md`,\n      `<%= it.vars.packagesDir %>/02-name.md`, ...). Order the packages so the\n      test suite can pass again after each one lands.\n\n      Each package file describes a set of INDEPENDENT tasks that can be\n      implemented concurrently without ordering constraints between them — a\n      single build turn will fan them out to parallel subagents. Give each task\n      a clear description, acceptance criteria as `- [ ]` checkboxes, and the\n      relevant paths. Also state the package's overall requirement so it can be\n      reviewed against its spec. Do NOT put ordering-dependent tasks in the same\n      package — split them across ordered packages instead.\n\n      No package file may reference any other `.gtd/` file. Once the package\n      files are written, delete `<%= it.vars.architectureFile %>`. Leave\n      everything uncommitted and finish your turn.\n    on:\n      \"* <%= it.vars.packagesDir %>/**\": picking\n\n  # ── Green-baseline gate: `gtd fix` entry ──────────────────────────────────\n  # `gtd fix` enters HERE (fixEntry): run the suite, then a red run drops\n  # straight into the shared `fixing` loop (-> checking -> review + squash\n  # tail); a green run is a no-op back to `idle` (nothing to fix).\n  fix-precheck:\n    actor: check\n    fixEntry: true\n    label: Checking the baseline\n    script: *suiteCheck\n    on:\n      \"A <%= it.vars.feedbackFile %>\": fixing\n      \"M <%= it.vars.feedbackFile %>\": fixing\n      \"D <%= it.vars.feedbackFile %>\": idle\n      \"C\": idle\n\n  # ── Shared tail: squash finale (review loop is the `humanReview` sub-machine) ─\n  squashing:\n    actor: agent\n    label: Squashing\n    file: <%= it.vars.commitMsgFile %>\n    model: <%= it.vars.coderModel %>\n    memory: build\n    prompt: |\n      You are an autonomous coding agent. The cycle is approved and done. This\n      workflow steers itself through its own state files — treat them as its\n      private scratchpad, never as project code or documentation. The only\n      state file this turn touches is `<%= it.vars.commitMsgFile %>`; write\n      it. Do not create other files to hold notes or output.\n\n      Leave `<%= it.vars.commitMsgFile %>` uncommitted and finish your turn —\n      entering this file squashes everything this process retains into one\n      commit using its content as the message. This prompt carries no diff —\n      read the range yourself; it runs from `<%= it.retainedBase %>` to the\n      working tree, and is exactly what that commit will contain, the changes\n      THIS process made (its trace/retry boundary onward). For a normal build\n      cycle that is the whole feature; for a `gtd review` process it is only\n      the fixes made during the review — NOT the changeset that was under\n      review.\n\n      If that range is non-empty, write `<%= it.vars.commitMsgFile %>` with ONE\n      conventional-commits message for the changes (subject line\n      `type(scope): subject`, imperative mood, <= 72 characters; a body\n      explaining the why, trade-offs, and key decisions). Plain text, no\n      markdown wrapper.\n\n      If that range is empty (a clean review sign-off with no fixes), write\n      `<%= it.vars.commitMsgFile %>` with exactly this one line and nothing\n      else:\n\n      chore: human review\n    on:\n      \"A <%= it.vars.commitMsgFile %>\": done\n      \"M <%= it.vars.commitMsgFile %>\": done\n\n  done:\n    commit: |\n      <%~ it.read(it.vars.commitMsgFile) %>\n\n      Token cost: <%= it.processCost %>\n      <% it.processCostByModel.forEach(function(m){ %>\n      - <%= m.model %>: <%= m.cost %>\n      <% }) %>\n";
+var unified_default = "# The unified gtd workflow template — gtd's BUILT-IN DEFAULT workflow. When no\n# `workflow:` key is configured anywhere in the cwd→home config chain,\n# src/Config.ts runs this template directly, so a state command works with no\n# configuration at all. `gtd init` seeds only the settings a project tunes\n# (vars.testCommand + a modes: formatting suggestion), never the workflow\n# itself. See the README's \"How it works\" and \"Driving the loop\" sections for\n# the full walkthrough.\n#\n# Compiled through the exact same `compileWorkflowConfig` a user's `.gtdrc`\n# `workflow:` key goes through — no privileged code path\n# (src/workflows/templates.ts does the compiling). Every content string below\n# is INLINE (no `./`-relative file references): the bundled template ships\n# inside a single-file build (`dist/gtd.bundle.mjs`), so its content must\n# already be resolved at BUILD time. `renderInitConfig` (src/workflows/\n# templates.ts) can MATERIALIZE this raw source into a `.gtdrc.json`\n# `workflow:` value — the way to eject/customize the machine, and the hermetic\n# test fixture — but `gtd init` itself no longer writes the workflow.\n#\n# ── Authored with MACHINES (entry:/machines:) ───────────────────────────────\n#\n# This template is written as a tree of reusable, parameterized MACHINES (see\n# src/Machines.ts) — a gate/loop written once and instantiated several times\n# with different `with:` bindings (dedup), or a complex cluster grouped under\n# one name for source comprehension (encapsulation). Every reference below is\n# an ordinary `{ machine: <name>, with: { ... } }` local, expanded at\n# compile-time into concrete, qualified states before the pure engine ever\n# sees the definition — no runtime footprint.\n#\n# MACHINE BOUNDARIES LINE UP WITH CONVERSATIONAL IDENTITY: a machine that holds\n# an identity (a planner or a coder persona) declares its own `model:` ONCE, at\n# the machine level (stamped onto every one of its own `prompt` states — see\n# src/Machines.ts's `resolveInstanceModel`), instead of repeating `model:` on\n# every state; no state anywhere declares `model:` or `memory:` directly any\n# more (the memory key is computed from the machine tree — see\n# src/PatternMachine.ts's `memoryScopeAt` / src/Edge.ts's `memoryKeyFor`). Two\n# gate/queue machines below are deliberately IDENTITY-FREE (no `model:`):\n# `entryGate`/`healthGate` are infrastructure, not a persona, and `packageLoop`\n# is a bookkeeping queue, not a builder.\n#\n#   * entryGate (dedup ×3)    — the green-baseline gate (check + human blocked)\n#                               guarding the simple (`plan-gate`), advanced\n#                               (`spec-gate`) and review (`review-gate`)\n#                               entries. Identity-free.\n#   * healthGate (dedup ×2)   — the check/escalate health pair shared by the\n#                               simple build's own tail (`build.health.*`) and\n#                               the per-package build's own tail\n#                               (`packages.item.health.*`) — each caller's OWN\n#                               `fix` state (a coder-identity action) lives\n#                               beside this machine, not inside it, since\n#                               fixing IS a coder action and this machine has\n#                               no identity of its own. Identity-free.\n#   * advancedPlan (encap)    — the advanced flow's one design conversation:\n#                               product Q&A, technical Q&A, and decomposition\n#                               (`design.*`: product-author/-answer,\n#                               technical-author/-answer, decompose) all share\n#                               ONE machine identity, so the agent explores the\n#                               codebase once, not three times, and the human's\n#                               answer rationale survives into decomposition.\n#                               ▸ planner.\n#   * planLoop (encap)        — the simple flow's plan-iteration loop (`plan.*`).\n#                               ▸ planner.\n#   * humanReview (encap)     — the shared review tail, nested INSIDE\n#                               `simpleBuild` (`build.review.*`: reviewing →\n#                               await-review → deciding → collecting) — see\n#                               \"Why humanReview is nested, not a root sibling\"\n#                               below. ▸ planner — the implementer's OWN\n#                               follow-through on feedback is a coder action,\n#                               not a reviewer one, so it lives in\n#                               `build.addressing` instead.\n#   * specReview (encap)      — the advanced flow's per-package agentic review,\n#                               now a SINGLE state (`packages.item.spec.review`)\n#                               — a machine whose entire job is to be a\n#                               separate mind from the implementer. ▸ planner\n#                               — fixing the reviewer's own findings is a coder\n#                               action, so it lives in `packages.item.fix-spec`\n#                               instead.\n#   * packageLoop (encap)     — the advanced flow's per-package build queue\n#                               (`packages.picking`). Identity-free — the\n#                               actual per-package build identity lives in its\n#                               own `item` child (packageItem, below).\n#   * packageItem (encap)     — the advanced flow's per-package build identity\n#                               (`packages.item.*`: building, fix-suite,\n#                               fix-spec, closing), plus its own `health` and\n#                               `spec` children. ▸ coder.\n#   * simpleBuild (encap)     — the simple flow's build identity (`build.*`:\n#                               building, squashing, addressing, fix), plus its\n#                               own `health` child AND its own `review` child\n#                               (humanReview, above). ▸ coder.\n#\n# ── Why humanReview is nested, not a root sibling ───────────────────────────\n#\n# `humanReview` sits UNDER `simpleBuild` (`build.review`) rather than beside it\n# at the root, because a machine's memory scope is its dotted instance path\n# (see src/PatternMachine.ts's `memoryScopeAt`): entering a DESCENDANT scope\n# never breaks the parent's unbroken run, but entering a sibling does. The\n# review tail sits between the two coder turns that most need continuity —\n# `build.addressing` (follows through on review feedback) and `build.squashing`\n# (drafts the finale from the range this process built) — so hoisting it back\n# to a root sibling would force both of those turns to re-derive the feature\n# from scratch on every pass through the tail, instead of resuming the session\n# that built it. The reviewer itself is unaffected either way: `build.review.*`\n# is its own scope regardless of where it's nested, so it never resumes the\n# builder's session.\n#\n# ── Four entry points behind a green-baseline gate, one shared tail ─────────\n#\n# EVERY entry first runs the test suite and only proceeds when it is GREEN — you\n# never start new work (or a review) on top of a red baseline. A red run halts\n# at a human blocked gate (fix the failures and re-run, exactly like the\n# escalate states), or is what `gtd --entry fix-precheck` exists to repair.\n#\n# The initial `idle` state FORKS on which steering file the human creates,\n# routing into that flow's OWN start gate:\n#\n#   * the configured requirementsFile (default .gtd/REQUIREMENTS.md) ->\n#     `spec-gate.check` -> the ADVANCED flow (one design conversation across\n#     product + technical Q&A and decomposition, per-package parallel build +\n#     agentic spec-review).\n#   * anything else (e.g. the configured todoFile, default .gtd/TODO.md) ->\n#     `plan-gate.check` -> the SIMPLE flow (one grilling Q&A loop, a monolithic\n#     build, no decomposition, no agentic review).\n#\n# A third entry, `gtd --entry review-gate.check`, jumps there directly and,\n# once green, to `build.review.reviewing` to review a foreign branch through\n# the same shared tail. A fourth, `gtd --entry fix-precheck`, jumps there: a\n# red suite drops straight into the shared `build.fix` loop and out through the\n# review + squash tail; a green suite is a no-op back to `idle`. Both states\n# declare `entry: true` — otherwise unreachable from `entries.default`.\n#\n# All three converge at `build.review.reviewing` -> `build.review.await-review`.\n# Ticking a REVIEW.md box means only \"I reviewed this hunk\"; a COMMENT (not an\n# unticked box) is what asks for changes. Every human step at\n# `build.review.await-review` goes to `build.review.deciding`, which inspects\n# the step and routes:\n#   * no comment (every box ticked, no REVIEW.md note, no code edit) -> the diff\n#     is a bare REVIEW.md deletion -> build.squashing -> done (the ONLY path\n#     to the finale — the whole cycle collapses into one commit).\n#   * any comment — a note in REVIEW.md OR a hand-edit to code — ->\n#     build.review.deciding writes REVIEW_FEEDBACK.md -> build.review.collecting\n#     implements it (completing any code the human hand-edited, never\n#     reverting their lines) -> build.addressing (a coder action, not a\n#     reviewer one — see \"Why humanReview is nested\" above) -> back through\n#     `build.health.check` (the shared health pair, bound via the\n#     `$onFeedback`/local `review` reference) -> build.review.reviewing\n#     regenerates an INCREMENTAL REVIEW.md (build.review.deciding carries\n#     `reviewBase: true`, so each feedback round's review + checkout window\n#     covers only `last-review..HEAD`, i.e. the agent's follow-through, not the\n#     human's own edit) -> await-review, looping until sign-off.\n# Two dead ends never commit: the sign-off gate (src/program.ts) REFUSES a step\n# that leaves a box unticked with no comment (finish reviewing first) and a\n# deleted REVIEW.md (restore it and tick the boxes).\n#\n# The shared health pair (`build.health.check`/`.escalate`, plus the caller's\n# own `build.fix`) serves the simple build and the feedback loop — its green\n# edge targets `build.review.reviewing`. The advanced per-package loop keeps\n# its OWN health pair (`packages.item.health.check`/`.escalate`, plus\n# `packages.item.fix-suite`) because its green edge targets the per-package\n# `packages.item.spec.review` gate instead.\n#\n# Every `on` pattern's path below is written as the matching var's Eta\n# template (e.g. `\"A <%= it.vars.feedbackFile %>\"`), not a literal `.gtd/...`\n# path — repointing a var reroutes the machine along with every template that\n# reads/writes it (see the README's \"Variables\" section).\n\nvars:\n  testCommand: npm test\n  # Where gtd keeps its own scratch/bookkeeping (the check scripts' temp output\n  # file, review-deciding's state-file exclusion). Independent of the per-file\n  # vars below — relocating a file wholesale means setting both.\n  stateDir: .gtd\n  todoFile: .gtd/TODO.md\n  requirementsFile: .gtd/REQUIREMENTS.md\n  architectureFile: .gtd/ARCHITECTURE.md\n  packagesDir: .gtd/packages\n  nextFile: .gtd/NEXT.md\n  reviewFile: .gtd/REVIEW.md\n  reviewRawFile: .gtd/REVIEW_RAW.md\n  reviewFeedbackFile: .gtd/REVIEW_FEEDBACK.md\n  feedbackFile: .gtd/FEEDBACK.md\n  specFeedbackFile: .gtd/SPEC_FEEDBACK.md\n  commitMsgFile: .gtd/COMMIT_MSG.md\n  # The two opaque model tiers every agent state draws from — repoint them here\n  # (or via a top-level `.gtdrc` `vars:` key / a `GTD_PLANNERMODEL` env var)\n  # to change every state on that tier at once. `plannerModel` (default \"smart\")\n  # is the heavier tier for the one-shot planning/technical-qa/review turns;\n  # `coderModel` (default \"base\") is the tier for the build/fix turns.\n  plannerModel: smart\n  coderModel: base\n  # The fixed diff base for `gtd --entry review-gate.check --var\n  # reviewBase=<commitish>` — a plain non-gtd branch reviewed against that\n  # commitish rather than the process start. Declared here (rather than left\n  # undeclared) so `--var reviewBase=...` passes the CLI's declared-name\n  # check; the default empty string renders blank, which the entry command\n  # refuses (a review entry always requires an explicit base).\n  reviewBase: \"\"\n\nentry:\n  default: unified\n\nmachines:\n  # ── DEDUP: the green-baseline entry gate (identity-free) ──────────────────\n  # Runs the suite before any work starts (its script is the shared suite-check\n  # wrapper — red -> the configured feedbackFile, green -> remove it); the `on`\n  # rules turn that into \"halt at blocked\" vs \"proceed to $onGreen\". The script\n  # and blocked message/describe differ per entry, so they ride in as `with:`\n  # params. Kept SEPARATE from `healthGate` (below) even though both are a\n  # check+something-else shape: this gate runs BEFORE planning, so it must NOT\n  # sweep the plan/review steering files healthGate does — a human's fresh\n  # sketch legitimately still exists here.\n  entryGate:\n    params: [onGreen, blockedMessage, blockedDescribe, checkLabel, blockedLabel, reviewBase]\n    entry: check\n    states:\n      check:\n        actor: check\n        label: $checkLabel\n        # Anchored here and aliased by `fix-precheck` (`gtd --entry\n        # fix-precheck` entry): one suite-check script shared by all four\n        # call sites (this machine's ×3 instances plus `fix-precheck`)\n        # instead of four source copies. These gates run BEFORE planning, so\n        # — unlike `healthGate.check` — they must NOT sweep\n        # `todoFile`/`requirementsFile`: the human's fresh sketch still\n        # legitimately exists here.\n        # `entry: true` on the shared local marks all three `entryGate`\n        # instances (plan-gate/spec-gate/review-gate) as manual entries —\n        # only `review-gate.check` actually needs the reachability root (it\n        # is otherwise unreachable from `entries.default`), but the shared\n        # dedup makes marking one mark all three. Accepted as correct: all\n        # three ARE the workflow's entry gates.\n        entry: true\n        # `reviewBase: $reviewBase` — only `review-gate` binds a real\n        # template (`<%= it.vars.reviewBase %>`), fixing the whole process's\n        # diff base to whatever `gtd --entry review-gate.check --var\n        # reviewBase=<commitish>` supplies. `plan-gate`/`spec-gate` bind the\n        # literal empty string, which compiles away to \"no base\" here — they\n        # are reached from `idle`, never manually entered with a base.\n        reviewBase: $reviewBase\n        script: &suiteCheck |\n          #!/usr/bin/env bash\n          # gtd check turn — run the suite; a red run records .gtd/FEEDBACK.md, a\n          # green run cleans it up. The `on` rules decide what that means.\n          set +e\n          mkdir -p \"<%~ it.vars.stateDir %>\"\n          # Hoist the feedback path once, at the TOP: Eta's autoTrim eats the\n          # newline after an interpolation tag, so no tag may be the last token on\n          # a line — it would glue the next line's `else`/`fi` onto it and break\n          # the script. Below this point everything is plain bash.\n          feedback=\"<%~ it.vars.feedbackFile %>\"\n          mkdir -p \"$(dirname \"$feedback\")\"\n          <%~ it.vars.testCommand %> > <%~ it.vars.stateDir %>/.check-output 2>&1\n          code=$?\n          if [ \"$code\" -ne 0 ]; then\n            if [ -s <%~ it.vars.stateDir %>/.check-output ]; then\n              mv <%~ it.vars.stateDir %>/.check-output \"$feedback\"\n            else\n              rm -f <%~ it.vars.stateDir %>/.check-output\n              printf 'the test command failed with exit code %s and produced no output.' \"$code\" > \"$feedback\"\n            fi\n            # A repeat identical failure would otherwise leave FEEDBACK.md\n            # byte-identical to its committed copy — no diff, so the check would\n            # look GREEN. Stamp each red run with the current HEAD (which always\n            # advances between checks) so a still-red re-run always re-registers\n            # as an M/A edit and takes the red edge.\n            printf '\\n<!-- gtd check %s -->\\n' \"$(git rev-parse --short HEAD 2>/dev/null || echo pending)\" >> \"$feedback\"\n          else\n            rm -f <%~ it.vars.stateDir %>/.check-output\n            rm -f \"$feedback\"\n          fi\n        on:\n          \"A <%= it.vars.feedbackFile %>\": blocked\n          \"M <%= it.vars.feedbackFile %>\": blocked\n          \"D <%= it.vars.feedbackFile %>\": $onGreen\n          \"C\": $onGreen\n      blocked:\n        actor: human\n        label: $blockedLabel\n        file: <%= it.vars.feedbackFile %>\n        message: $blockedMessage\n        on:\n          \"* **\":\n            to: check\n            action: Retry check\n            describe: $blockedDescribe\n\n  # ── DEDUP: the check/escalate health pair (identity-free) ─────────────────\n  # Runs the suite; a red run records the configured feedbackFile and routes to\n  # the caller's OWN fixer (`$onRed` — a coder-identity action that lives\n  # beside this machine, not inside it, since fixing IS a coder action and this\n  # machine has no identity); a green run cleans it up and routes to\n  # `$onGreen`. Escalation redirects here after the caller's fixer has retried\n  # `max` times without success. Instantiated for the simple build's own tail\n  # (`build.health.*`, caller's fixer is `build.fix`) and the per-package\n  # build's own tail (`packages.item.health.*`, caller's fixer is\n  # `packages.item.fix-suite`).\n  healthGate:\n    params: [onGreen, onRed, escalateDescribe, checkLabel, escalateLabel]\n    entry: check\n    states:\n      check:\n        actor: check\n        label: $checkLabel\n        # This script ALSO sweeps spent steering files (`todoFile`,\n        # `reviewRawFile`, `reviewFeedbackFile`) — a mechanic `entryGate.check`\n        # must NOT run, since it executes before planning, while a fresh\n        # sketch legitimately still exists.\n        script: |\n          #!/usr/bin/env bash\n          # gtd check turn — run the suite; a red run records .gtd/FEEDBACK.md, a\n          # green run cleans it up. The `on` rules decide what that means.\n          set +e\n          mkdir -p \"<%~ it.vars.stateDir %>\"\n          # Hoist every path once, at the TOP: Eta's autoTrim eats the newline\n          # after an interpolation tag, so no tag may be the last token on a\n          # line — it would glue the next line's `else`/`fi` onto it and break\n          # the script. Below this point everything is plain bash.\n          feedback=\"<%~ it.vars.feedbackFile %>\"\n          mkdir -p \"$(dirname \"$feedback\")\"\n          # Sweep steering files spent by the states that led here: the plan\n          # (building), the raw review capture (review.collecting), and the\n          # feedback instructions (build.addressing) — each `rm -f` is a\n          # no-op when the file is already gone or never existed on this path.\n          todo=\"<%~ it.vars.todoFile %>\"\n          reviewRaw=\"<%~ it.vars.reviewRawFile %>\"\n          reviewFeedback=\"<%~ it.vars.reviewFeedbackFile %>\"\n          rm -f \"$todo\" \"$reviewRaw\" \"$reviewFeedback\"\n          <%~ it.vars.testCommand %> > <%~ it.vars.stateDir %>/.check-output 2>&1\n          code=$?\n          if [ \"$code\" -ne 0 ]; then\n            if [ -s <%~ it.vars.stateDir %>/.check-output ]; then\n              mv <%~ it.vars.stateDir %>/.check-output \"$feedback\"\n            else\n              rm -f <%~ it.vars.stateDir %>/.check-output\n              printf 'the test command failed with exit code %s and produced no output.' \"$code\" > \"$feedback\"\n            fi\n            # A repeat identical failure would otherwise leave FEEDBACK.md\n            # byte-identical to its committed copy — no diff, so the check would\n            # look GREEN. Stamp each red run with the current HEAD (which always\n            # advances between checks) so a still-red re-run always re-registers\n            # as an M/A edit and takes the red edge.\n            printf '\\n<!-- gtd check %s -->\\n' \"$(git rev-parse --short HEAD 2>/dev/null || echo pending)\" >> \"$feedback\"\n          else\n            rm -f <%~ it.vars.stateDir %>/.check-output\n            rm -f \"$feedback\"\n          fi\n        on:\n          \"A <%= it.vars.feedbackFile %>\": $onRed\n          \"M <%= it.vars.feedbackFile %>\": $onRed\n          \"* **\": $onGreen\n          \"C\": $onGreen\n      escalate:\n        actor: human\n        label: $escalateLabel\n        file: <%= it.vars.feedbackFile %>\n        message: |\n          The agent could not get the check to pass after repeated attempts.\n          `<%= it.vars.feedbackFile %>` holds the last failing output.\n\n          What each change does next (then run `gtd step human`):\n          <% it.edges.forEach(function (e) { if (e.describe) { %>\n          <%~ \"- \" + (e.action ? \"**\" + e.action + \"** — \" : \"\") + e.describe + \"\\n\" %>\n          <% } }) %>\n        on:\n          \"* **\":\n            to: check\n            action: Retry check\n            describe: $escalateDescribe\n\n  # ── ENCAPSULATION: the advanced flow's design conversation ─────────────────\n  # One planner identity across product Q&A -> technical Q&A -> decomposition:\n  # a single codebase exploration instead of three, and the human's answer\n  # rationale survives from product into technical and into decomposition (all\n  # five states share one memory scope, `design`). Replaces the former\n  # `qaLoop ×2` (which split one design conversation into two minds that each\n  # re-explored the codebase) plus `simpleBuild`'s own `decompose` (which\n  # landed on the coder tier only because it happened to live in the build\n  # machine — decomposition is judgement-heavy planning work, not building).\n  # ▸ planner identity — `model:` declared once here, stamped onto\n  # `product-author`, `technical-author`, and `decompose` (its own prompt\n  # states; the `*-answer` states are human turns and carry no prompt).\n  advancedPlan:\n    model: <%= it.vars.plannerModel %>\n    params: [onPackages]\n    entry: product-author\n    states:\n      product-author:\n        actor: agent\n        label: Refining the product plan\n        file: <%= it.vars.requirementsFile %>\n        mode: qa\n        prompt: |\n          You are an autonomous coding agent. This workflow steers itself\n          through its own state files — treat them as its private scratchpad,\n          never as project code or documentation. The only state file this turn\n          touches is `<%= it.vars.requirementsFile %>`; develop it. Do not\n          create other files to hold notes or output.\n\n          `<%= it.vars.requirementsFile %>` holds the product requirements (or the\n          plan you already wrote plus the human's answers on a return lap). Read it,\n          explore the codebase, and develop it into a concrete, PRODUCT-level plan\n          in this one turn.\n\n          Scope: product and user-facing decisions only. Leave implementation\n          details (file/module structure, data models, tech-stack choices) for the\n          next phase (`<%= it.vars.architectureFile %>`).\n\n          For every open point you cannot settle yourself, add a question under a\n          `## Open Questions` heading near the top: one `### <question>` sub-heading\n          each, followed by a checkbox list of candidate answers — aim for TWO\n          concrete options plus a final free-text slot, ALL left UNTICKED:\n\n              ### <the question>\n\n              - [ ] <first option — a concrete answer, a few words of rationale>\n              - [ ] <second option>\n              - [ ] _your answer_\n\n          Never tick a box yourself — the human ticks exactly one per question. The\n          last `- [ ] _your answer_` line is the human's own-answer slot; write it\n          with the literal `_your answer_` placeholder and leave it for them.\n\n          On a RETURN lap the human has ticked one option per question (or replaced\n          `_your answer_` with their own text). For each answered question: fold the\n          chosen answer into the plan prose, then MOVE the question down into a\n          `## Answered Questions` section as `### <question>` followed by the\n          resolved answer in plain PROSE (drop the checkboxes). Never re-raise a\n          question the human deleted; if the human deleted the whole\n          `## Open Questions` section, treat the plan as accepted and surface no new\n          questions unless something is genuinely still blocking. Omit\n          `## Open Questions` entirely once there are none left.\n\n          Leave `<%= it.vars.requirementsFile %>` uncommitted and finish your turn.\n        on:\n          \"* **\": product-answer\n\n      product-answer:\n        actor: human\n        label: Awaiting your answers\n        file: <%= it.vars.requirementsFile %>\n        mode: qa\n        answerGate: true\n        message: |\n          `<%= it.vars.requirementsFile %>` holds the product plan under\n          development. Each question under `## Open Questions` offers a few options\n          plus a `- [ ] _your answer_` slot. Answer EVERY question by ticking\n          exactly one box (`- [x]`); for your own answer, replace `_your answer_`\n          with your text and tick that line. Stepping is refused while any question\n          is unanswered.\n\n          What each change does next (then run `gtd step human`):\n          <% it.edges.forEach(function (e) { if (e.describe) { %>\n          <%~ \"- \" + (e.action ? \"**\" + e.action + \"** — \" : \"\") + e.describe + \"\\n\" %>\n          <% } }) %>\n        on:\n          \"C\":\n            to: technical-author\n            action: Accept answers\n            describe: >-\n              with no open questions left (the agent surfaced none, or you deleted\n              the section and it finalized the plan), change nothing to move on to\n              technical Q&A (**design.technical-author**).\n          \"* **\":\n            to: product-author\n            action: Revise answers\n            describe: >-\n              tick exactly one option per open question (replace `_your answer_` for\n              your own) to send the plan back for the agent to fold your answers in\n              (**design.product-author**). Delete a question to skip it, or delete the whole\n              `## Open Questions` section to accept the plan as-is.\n\n      technical-author:\n        actor: agent\n        label: Refining the technical plan\n        file: <%= it.vars.architectureFile %>\n        mode: qa\n        prompt: |\n          You are an autonomous coding agent. This workflow steers itself\n          through its own state files — treat them as its private scratchpad,\n          never as project code or documentation. The only state files this\n          turn touches are `<%= it.vars.architectureFile %>` (write it) and\n          `<%= it.vars.requirementsFile %>` (delete it once its content is\n          folded in). Do not create other files to hold notes or output.\n\n          If you developed those requirements earlier in this conversation, work\n          from what you already settled; otherwise read\n          `<%= it.vars.requirementsFile %>` (the converged product plan) yourself.\n          Develop `<%= it.vars.architectureFile %>` from it in this one turn:\n          file/module structure, data models, library/tech-stack choices,\n          error-handling strategy — the *how*, building on the *what* already\n          settled. Do not re-open product-level decisions; treat them as settled.\n\n          For every open point you cannot settle yourself, add a question under a\n          `## Open Questions` heading exactly as the grilling phase does: one\n          `### <question>` each, followed by a checkbox list — TWO concrete options\n          plus a final free-text slot, ALL left UNTICKED:\n\n              ### <the question>\n\n              - [ ] <first option>\n              - [ ] <second option>\n              - [ ] _your answer_\n\n          Never tick a box yourself. On a RETURN lap the human has ticked one option\n          per question (or replaced `_your answer_` with their own text): fold each\n          chosen answer into the plan prose, then MOVE the question into a\n          `## Answered Questions` section as `### <question>` + the resolved answer\n          in plain PROSE (drop the checkboxes). Never re-raise a deleted question;\n          treat a deleted `## Open Questions` section as acceptance. Omit\n          `## Open Questions` once there are none left.\n\n          Once `<%= it.vars.architectureFile %>` is written, delete\n          `<%= it.vars.requirementsFile %>` — its content has been folded in and it\n          must not linger. Leave everything uncommitted and finish your turn.\n        on:\n          \"* **\": technical-answer\n\n      technical-answer:\n        actor: human\n        label: Awaiting your answers\n        file: <%= it.vars.architectureFile %>\n        mode: qa\n        answerGate: true\n        message: |\n          `<%= it.vars.architectureFile %>` holds the technical plan under\n          development. Each question under `## Open Questions` offers a few options\n          plus a `- [ ] _your answer_` slot. Answer EVERY question by ticking\n          exactly one box (`- [x]`); for your own answer, replace `_your answer_`\n          with your text and tick that line. Stepping is refused while any question\n          is unanswered.\n\n          What each change does next (then run `gtd step human`):\n          <% it.edges.forEach(function (e) { if (e.describe) { %>\n          <%~ \"- \" + (e.action ? \"**\" + e.action + \"** — \" : \"\") + e.describe + \"\\n\" %>\n          <% } }) %>\n        on:\n          \"C\":\n            to: decompose\n            action: Accept answers\n            describe: >-\n              with no open questions left (the agent surfaced none, or you deleted\n              the section and it finalized the plan), change nothing to move on to\n              decomposing the work into packages (**design.decompose**).\n          \"* **\":\n            to: technical-author\n            action: Revise answers\n            describe: >-\n              tick exactly one option per open question (replace `_your answer_` for\n              your own) to send the plan back for the agent to fold your answers in\n              (**design.technical-author**). Delete a question to skip it, or delete the whole\n              `## Open Questions` section to accept the plan as-is.\n\n      decompose:\n        actor: agent\n        label: Decomposing into packages\n        prompt: |\n          You are an autonomous coding agent. This workflow steers itself through\n          its own state files — treat them as its private scratchpad, never as\n          project code or documentation. The only state files this turn touches\n          are the package files it writes under `<%= it.vars.packagesDir %>/` and\n          `<%= it.vars.architectureFile %>`, which it deletes. Do not create other\n          files to hold notes or output.\n\n          If you wrote `<%= it.vars.architectureFile %>` earlier in this\n          conversation, work from what you already settled; otherwise read it\n          (the converged technical plan) yourself. Decompose it into an ordered\n          set of WORK PACKAGES, one file each under\n          `<%= it.vars.packagesDir %>/` (e.g. `<%= it.vars.packagesDir %>/01-name.md`,\n          `<%= it.vars.packagesDir %>/02-name.md`, ...). Order the packages so the\n          test suite can pass again after each one lands.\n\n          Each package file describes a set of INDEPENDENT tasks that can be\n          implemented concurrently without ordering constraints between them — a\n          single build turn will fan them out to parallel subagents. Give each task\n          a clear description, acceptance criteria as `- [ ]` checkboxes, and the\n          relevant paths. Also state the package's overall requirement so it can be\n          reviewed against its spec. Do NOT put ordering-dependent tasks in the same\n          package — split them across ordered packages instead.\n\n          No package file may reference any other `.gtd/` file. Once the package\n          files are written, delete `<%= it.vars.architectureFile %>`. Leave\n          everything uncommitted and finish your turn.\n        on:\n          \"* <%= it.vars.packagesDir %>/**\": $onPackages\n\n  # ── ENCAPSULATION: the simple flow's plan-iteration loop ───────────────────\n  # ▸ planner identity — `model:` declared once here, stamped onto `planning`\n  # (its only prompt state).\n  planLoop:\n    model: <%= it.vars.plannerModel %>\n    params: [onAccept]\n    entry: planning\n    states:\n      planning:\n        actor: agent\n        label: Refining the plan\n        file: <%= it.vars.todoFile %>\n        mode: prose\n        prompt: |\n          You are an autonomous coding agent. This workflow steers itself\n          through its own state files — treat them as its private scratchpad,\n          never as project code or documentation. The only state file this\n          turn touches is `<%= it.vars.todoFile %>`; develop it into the plan.\n          Do not create other files to hold notes or output.\n\n          `<%= it.vars.todoFile %>` holds a short sketch of what to build — or, on a\n          return lap, the plan you already wrote plus the human's edits and comments\n          on it. Read it, explore the codebase, and develop it into a concrete\n          implementation plan: the files to change, the approach, and the steps to\n          take.\n\n          Do NOT ask questions and do NOT add an \"Open Questions\" section — decide\n          every open point yourself and write the plan as a set of concrete\n          decisions. Where a decision is genuinely a judgement call, state the\n          choice you made and, in one line, why. The human iterates on the plan by\n          editing it directly, not by answering questions.\n\n          On a return lap, `<%= it.vars.todoFile %>` carries the human's edits and\n          inline comments on your previous plan. If you wrote that plan earlier in\n          this conversation, work from what you already know plus these edits;\n          otherwise read the file fresh. Fold every edit and comment into a\n          revised, self-contained plan and remove the addressed comments — the plan\n          is always the current, clean proposal, never a diff.\n\n          Leave `<%= it.vars.todoFile %>` uncommitted and finish your turn — do\n          not commit, and do not run `gtd step agent` yourself; the harness does\n          that.\n        on:\n          \"* **\": await-plan\n\n      await-plan:\n        actor: human\n        label: Awaiting your review\n        file: <%= it.vars.todoFile %>\n        mode: prose\n        message: |\n          `<%= it.vars.todoFile %>` holds the proposed implementation plan. Read it,\n          then either accept it as-is or edit it — rewrite a step, add a\n          constraint, or drop an inline comment — to send it back for another round.\n\n          What each change does next (then run `gtd step human`):\n          <% it.edges.forEach(function (e) { if (e.describe) { %>\n          <%~ \"- \" + (e.action ? \"**\" + e.action + \"** — \" : \"\") + e.describe + \"\\n\" %>\n          <% } }) %>\n        on:\n          \"C\":\n            to: $onAccept\n            action: Accept plan\n            describe: >-\n              change nothing to move on to implementation (**build.building**).\n          \"* **\":\n            to: planning\n            action: Revise plan\n            describe: >-\n              rewrite a step, add a constraint, or leave an inline comment to\n              send it back for another round (**plan.planning**).\n\n  # ── ENCAPSULATION: the shared review tail ──────────────────────────────────\n  # ▸ planner identity — `model:` declared once here, stamped onto `reviewing`\n  # and `collecting` (its only prompt states). The implementer's OWN\n  # follow-through on feedback is a coder action, not a reviewer one — it\n  # lives in `build.addressing` (`$onFeedback`), not inside this machine.\n  humanReview:\n    model: <%= it.vars.plannerModel %>\n    entry: reviewing\n    states:\n      reviewing:\n        actor: agent\n        label: Reviewing\n        file: <%= it.vars.reviewFile %>\n        mode: review\n        # `gtd --entry review-gate.check` (a plain non-gtd branch, e.g. a\n        # colleague's PR) does NOT enter here directly — it enters\n        # `review-gate.check` first, which runs the green-baseline gate and,\n        # once green, transitions here. The `Gtd-Review-Base:` trailer rides on that\n        # entry commit (the process's oldest), so everything below still reuses\n        # the same reviewing/await-review/feedback machinery over <commitish>..HEAD.\n        prompt: |\n          You are an autonomous coding agent. This workflow steers itself\n          through its own state files — treat them as its private scratchpad,\n          never as project code or documentation. The only state file this\n          turn touches is `<%= it.vars.reviewFile %>`; write it at exactly\n          that path. Do not create other files to hold notes or output.\n\n          Write `<%= it.vars.reviewFile %>` to help a human review the changes in\n          this EXACT format:\n\n          - First non-blank line: `# Review: <%= it.currentCommit.slice(0, 7) %>`\n          - Somewhere in the document: `<!-- base: <%= it.reviewBase %> -->`\n          - At least one `## <Chunk Title>` heading, grouping hunks semantically\n            (same feature/refactor/fix, even across files) — a short explanation of\n            what changed and why, then one `- [ ] ./path/to/file.ts#42 — note` file\n            pointer per hunk (checkboxes are for the human to tick, not you; every\n            path is `./`-relative, with an optional `#line` and an optional\n            ` — note`).\n\n          This prompt carries no diff — read the changes yourself. The range runs\n          from `<%= it.reviewBase %>` to the working tree (committed turns plus\n          anything still pending); on a feedback round that base is the previous\n          review's boundary, so it covers only what changed since then, not items\n          already signed off.\n\n          Leave `<%= it.vars.reviewFile %>` uncommitted and finish your turn.\n        on:\n          \"* **\": await-review\n\n      await-review:\n        actor: human\n        label: Awaiting your review\n        file: <%= it.vars.reviewFile %>\n        mode: review\n        # While the cycle rests here, gtd opens a \"review checkout window\": raw HEAD\n        # is rewound to the review base (the most-recent `deciding` commit — so a\n        # feedback round shows only `last-review..HEAD` — or the process start on\n        # the first review) with the working tree untouched, surfacing the diff\n        # as ordinary uncommitted changes. It closes on the next invocation.\n        #\n        # Every human step here routes to `deciding`, which decides sign-off vs.\n        # feedback from the step's CONTENT (a comment, not a tick). Ticking a box\n        # only records \"I reviewed this hunk\". Two dead ends can't be told apart by a\n        # file-pattern edge, so the sign-off gate (`enforceReviewSignoffGate` in\n        # src/program.ts) catches them BEFORE the step commits and refuses: an\n        # unfinished review (a box still `- [ ]` with no comment) and a deleted\n        # REVIEW.md.\n        reviewWindow: true\n        message: |\n          `<%= it.vars.reviewFile %>` holds the review record for the cycle — one\n          `- [ ]` checkbox per reviewable item, grouped into chunks. Tick a box\n          (`- [x]`) as you review each hunk; ticking only records that you've read\n          it, it is not sign-off.\n\n          When you've been through the whole diff, run `gtd step human`:\n\n          - **Sign off** — tick EVERY box and leave no comment — no note in\n            `<%= it.vars.reviewFile %>`, no code edit — to collapse the cycle into\n            one commit (**build.squashing**).\n          - **Request changes** — leave a comment: a note on a\n            `<%= it.vars.reviewFile %>` line, or a direct code edit — to send it to a\n            build + re-review round (**review.deciding** → **build.addressing**). A\n            code edit counts as your own fix: the agent completes the follow-through\n            it implies and never reverts your lines.\n\n          Stepping with a box still unticked and no comment is refused (finish\n          reviewing first); so is deleting `<%= it.vars.reviewFile %>`.\n        on:\n          \"* **\": deciding\n\n      deciding:\n        actor: check\n        label: Reviewing\n        file: <%= it.vars.reviewFile %>\n        mode: review\n        # Anchors the INCREMENTAL review base: its most-recent in-process commit is\n        # the point the previous review round ended, so the next `reviewing` turn\n        # (and the review checkout window) covers only the changes since then. On\n        # the first review there is no such commit, so the base is the cycle start.\n        reviewBase: true\n        script: |\n          #!/usr/bin/env bash\n          # gtd check turn — decide the human's review step from its CONTENT. HEAD is\n          # the human's `await-review -> deciding` commit; HEAD^ is the `reviewing`\n          # commit that wrote the agent's original REVIEW.md (the sign-off gate\n          # refuses an incomplete step, so `deciding` is entered exactly once per\n          # round — nothing commits in between). It is FEEDBACK when the human left\n          # a comment: a note in REVIEW.md (any edit beyond a \"[ ]\"->\"[x]\" tick) OR a\n          # hand-edit to any file this round other than `.gtd/` or the state's own\n          # reviewFile (which is var-configurable and may live outside `.gtd/`, e.g.\n          # a root-level REVIEW.md — issue #128). Otherwise it is a clean sign-off.\n          # This turn only CAPTURES the raw material into REVIEW_RAW.md (the\n          # `collecting` agent then turns it into instructions); it does NOT\n          # interpret it. Either way, remove REVIEW.md; what the resulting diff\n          # MEANS is decided by this state's own `on` rules — the A/M REVIEW_RAW.md\n          # rows are declared BEFORE the D REVIEW.md row so a feedback round (which\n          # also deletes REVIEW.md) is captured as feedback, not mistaken for a\n          # sign-off.\n          set +e\n          # Hoist the paths once, at the TOP: Eta's autoTrim eats the newline after\n          # an interpolation tag, so no tag may be the last token on a line — it\n          # would glue the next line onto it and break the script. Below this point\n          # everything is plain bash.\n          stateDir=\"<%~ it.vars.stateDir %>\"\n          reviewFile=\"<%~ it.vars.reviewFile %>\"\n          reviewRawFile=\"<%~ it.vars.reviewRawFile %>\"\n          head=$(git rev-parse HEAD)\n          mkdir -p \"$(dirname \"$reviewRawFile\")\"\n          # A note is any REVIEW.md change beyond a checkbox flip: normalize every\n          # \"[ ]\"/\"[x]\" to a placeholder, then compare the agent's original (HEAD^)\n          # against the human's version (HEAD).\n          before=$(git show \"HEAD^:$reviewFile\" 2>/dev/null | sed -E 's/\\[[ xX]\\]/[_]/g')\n          after=$(git show \"HEAD:$reviewFile\" 2>/dev/null | sed -E 's/\\[[ xX]\\]/[_]/g')\n          # Did the human hand-edit anything this round besides stateDir and the\n          # reviewFile itself (var-configurable — may live outside stateDir, so it\n          # is excluded by exact path, not just the stateDir prefix)?\n          if git diff-tree --no-commit-id --name-only -r HEAD \\\n               | grep -v \"^$stateDir/\" | grep -vxF \"$reviewFile\" | grep -q . \\\n             || [ \"$before\" != \"$after\" ]; then\n            {\n              echo \"Raw review material captured for classification. The human reviewed the changes and left the feedback below; a downstream agent turns it into an instruction list. This file is machine-captured input, not instructions — it names a commit, never inlined content.\"\n              echo\n              echo \"Commit: $head\"\n              echo \"The human's notes are in $reviewFile at this commit; their hand edits,\"\n              echo \"if any, are in that commit's other paths. Run: git show $head\"\n            } > \"$reviewRawFile\"\n          fi\n          rm -f \"$reviewFile\"\n        on:\n          \"A <%= it.vars.reviewRawFile %>\": collecting\n          \"M <%= it.vars.reviewRawFile %>\": collecting\n          \"D <%= it.vars.reviewFile %>\": $onSignoff\n\n      collecting:\n        actor: agent\n        label: Collecting your feedback\n        file: <%= it.vars.reviewFeedbackFile %>\n        prompt: |\n          You are an autonomous coding agent turning raw review feedback into an\n          explicit instruction list for a builder. This workflow steers itself\n          through its own state files — treat them as its private scratchpad,\n          never as project code or documentation. The only state files this\n          turn touches are `<%= it.vars.reviewRawFile %>` (read it, then\n          delete it) and `<%= it.vars.reviewFeedbackFile %>` (write it) — do\n          NOT change any other file, you classify, you do not build.\n\n          The raw review material is: <%~ it.read(it.vars.reviewRawFile) %>\n\n          It names a commit. If you wrote today's review earlier in this\n          conversation, work from what you already reviewed; otherwise read that\n          commit's diff yourself before classifying anything.\n\n          Classify every piece of it into `<%= it.vars.reviewFeedbackFile %>` as a\n          flat, numbered instruction list. Each item is `N. ./path/to/file.ts#line —\n          <imperative>`. Apply these rules exactly:\n\n          1. NOTES the human added to REVIEW.md — each note is a MANDATORY change,\n             regardless of whether its checkbox is ticked (ticking means only \"I read\n             this hunk\", never sign-off). Anchor each to the `./path#line` its review\n             item names (or the chunk it sits under). Emit it as a concrete\n             imperative.\n          2. Every COMMENT the human ADDED this round (a `+` line that is a code\n             comment, in the hand-edited files) is a MANDATORY instruction the human\n             is giving the builder — even a plain-prose one, even if its box is\n             ticked. Emit an imperative to satisfy it and note that the comment line\n             itself must be REMOVED once addressed. If a comment turns out to describe\n             behaviour the code already has, the instruction is still \"confirm the\n             code matches and remove the comment line\".\n          3. Every NON-comment code line the human hand-edited is an already-committed\n             INTENT, NOT a do-then-delete item. Emit an instruction that names those\n             files and says: their lines are final — complete ONLY the follow-through\n             they imply (callers, tests, types, docs) and NEVER revert or rewrite\n             them. Do not turn their own edit into a task.\n\n          Split each hand-edited hunk per line: comment `+` lines follow rule 2, the\n          surrounding real code follows rule 3.\n\n          If — and only if — nothing in the raw material is actionable (e.g. the human\n          left only an approving remark), write `<%= it.vars.reviewFeedbackFile %>`\n          containing exactly one line: `NOTHING ACTIONABLE — <one-sentence reason>`.\n          Never invent work to satisfy a non-actionable remark.\n\n          Delete `<%= it.vars.reviewRawFile %>`, leave everything else uncommitted,\n          and finish your turn.\n        on:\n          \"A <%= it.vars.reviewFeedbackFile %>\": $onFeedback\n          \"M <%= it.vars.reviewFeedbackFile %>\": $onFeedback\n\n  # ── ENCAPSULATION: the advanced flow's per-package agentic review ──────────\n  # A single state: a machine whose entire job is to be a separate MIND from\n  # the implementer, distinct from the coder identity that builds/fixes the\n  # package (`packages.item.*`). ▸ planner identity — `model:` declared once\n  # here, stamped onto `review` (its only prompt state). Fixing the reviewer's\n  # own findings is a coder action, not a reviewer one — it lives in\n  # `packages.item.fix-spec` (`$onFix`), not inside this machine.\n  specReview:\n    model: <%= it.vars.plannerModel %>\n    params: [onApproved, onFix]\n    entry: review\n    states:\n      review:\n        actor: agent\n        label: Reviewing the package\n        # Bounded per cycle: once entered `max` times, a transition into it is\n        # redirected to `$onApproved` (force-close the package and move on — the\n        # unresolved concern is deferred to the shared human review at the tail,\n        # which sees the whole diff anyway). NOTE the cap is PROCESS-scoped, so it\n        # pools across packages — the same documented limitation the shared\n        # `build.fix` cap has (see the README's \"Why\" section, \"Bounded, not\n        # runaway\").\n        retry:\n          max: 3\n          otherwise: $onApproved\n        prompt: |\n          You are an autonomous coding agent reviewing a freshly-built work package\n          against its own spec. This workflow steers itself through its own\n          state files — treat them as its private scratchpad, never as project\n          code or documentation. The only state file this turn touches is\n          `<%= it.vars.specFeedbackFile %>`; write it only when — and only\n          when — you find problems. Do not create other files to hold notes or\n          output.\n\n          The package spec is: <%~ it.read(it.vars.nextFile) %>\n\n          Read that spec, then verify the package's implementation against it: are\n          all its tasks done, acceptance criteria met, and the code sound and\n          consistent with the codebase? This prompt carries no diff — read it\n          yourself: the range runs from `<%= it.startCommit %>` to the working\n          tree.\n\n          Note the range is process-wide (from the start of the whole build, not\n          just this package), so it can span earlier packages too.\n\n          - If it fully satisfies the spec, write NOTHING and finish your turn — a\n            clean turn is your approval.\n          - If it does not, write `<%= it.vars.specFeedbackFile %>` listing the\n            concrete problems for a fix turn to address. Be specific.\n\n          Do not fix anything yourself and do not delete the package file — a later\n          step owns that. Finish your turn.\n        on:\n          \"A <%= it.vars.specFeedbackFile %>\": $onFix\n          \"M <%= it.vars.specFeedbackFile %>\": $onFix\n          \"D <%= it.vars.specFeedbackFile %>\": $onApproved\n          \"C\": $onApproved\n\n  # ── ENCAPSULATION: the advanced flow's per-package build queue ─────────────\n  # Identity-free (a bookkeeping queue, not a builder) — the actual per-package\n  # build identity lives in its own `item` child (packageItem, below).\n  packageLoop:\n    params: [onDrained]\n    entry: picking\n    states:\n      picking:\n        actor: check\n        label: Picking the next package\n        script: |\n          #!/usr/bin/env bash\n          # gtd check turn (the package queue arbiter) — the loop driver executes\n          # this verbatim, then steps the check actor. Mechanics only: take the\n          # first package file (by name) under the packages dir into NEXT.md, or\n          # remove NEXT.md when the queue is empty. What NEXT.md's presence/absence\n          # MEANS (another package to build vs. the queue closing out to review) is\n          # decided by this state's own `on` rules at capture time — never here.\n          set +e\n          # Hoist the NEXT path once, at the TOP: Eta's autoTrim eats the newline\n          # after an interpolation tag, so no tag may be the last token on a line —\n          # it would glue the next line's `else`/`fi` onto it and break the script.\n          # Below this point everything is plain bash.\n          nextFile=\"<%~ it.vars.nextFile %>\"\n          # Sweep the advanced flow's spent Q&A steering files: requirementsFile\n          # is consumed by technical-qa, architectureFile by decompose — both are\n          # gone by the time the package queue starts. No-op if already removed.\n          requirements=\"<%~ it.vars.requirementsFile %>\"\n          architecture=\"<%~ it.vars.architectureFile %>\"\n          rm -f \"$requirements\" \"$architecture\"\n          next=$(ls <%~ it.vars.packagesDir %>/*.md 2>/dev/null | head -n 1)\n          if [ -n \"$next\" ]; then\n            mkdir -p \"$(dirname \"$nextFile\")\"\n            printf '%s' \"$next\" > \"$nextFile\"\n          else\n            rm -f \"$nextFile\"\n          fi\n        on:\n          \"D <%= it.vars.nextFile %>\": $onDrained\n          \"* <%= it.vars.nextFile %>\": item.building\n          \"C\": $onDrained\n\n      # The per-package build identity — its own coder machine (below), so\n      # deleting a package file's own lifecycle stays inside `item` while the\n      # queue itself (`packages`) stays a single state.\n      item:\n        machine: packageItem\n        with:\n          onNext: picking\n\n  # ── ENCAPSULATION: the advanced flow's per-package build identity ──────────\n  # ▸ coder identity — `model:` declared once here, stamped onto `building`,\n  # `fix-suite`, and `fix-spec` (its own prompt states). `closing` ends that\n  # package file's own lifecycle; keeping it here (not in the queue) keeps\n  # `packages` itself to a single state. `packages.item.closing` -> `picking`\n  # is the ONE upward-resolving target in the whole file, so it MUST be a\n  # param (`$onNext`, bound by `packages` — see the machine's own reference).\n  packageItem:\n    model: <%= it.vars.coderModel %>\n    params: [onNext]\n    entry: building\n    states:\n      building:\n        actor: agent\n        label: Building\n        prompt: |\n          You are an autonomous coding agent. This workflow steers itself\n          through its own state files — treat them as its private scratchpad,\n          never as project code or documentation. This turn writes no state\n          file: do NOT delete the package file (the spec-review gate reads\n          it after you) and never touch `<%= it.vars.nextFile %>` — the\n          `picking` state owns it.\n\n          The package to implement is: <%~ it.read(it.vars.nextFile) %>\n\n          That file describes a set of INDEPENDENT tasks. Implement ALL of them in\n          this one turn, fanning the independent tasks out to parallel subagents\n          where your harness supports it — each task is self-contained and can be\n          built concurrently. Implement EXACTLY the tasks this package describes — no\n          more, no less; leave every other package file untouched. Use TDD\n          discipline within each task.\n\n          Leave the package file in place and everything else uncommitted, then\n          finish your turn.\n        on:\n          \"* **\": health.check\n\n      fix-suite:\n        actor: agent\n        label: Fixing the check\n        file: <%= it.vars.feedbackFile %>\n        prompt: &suiteFixPrompt |\n          You are an autonomous coding agent. This workflow steers itself\n          through its own state files — treat them as its private scratchpad,\n          never as project code or documentation. The only state file this\n          turn touches is `<%= it.vars.feedbackFile %>`; fix it per its\n          contents, or delete it if the feedback turns out to be wrong. Do not\n          create other files to hold notes or output.\n\n          Read `<%= it.vars.feedbackFile %>` (the failing test output) and fix the\n          code so the suite passes. Keep the change focused — do not refactor\n          unrelated code. If the feedback is wrong, empty or delete\n          `<%= it.vars.feedbackFile %>` instead of \"fixing\" a non-issue.\n\n          Leave everything uncommitted and finish your turn — do not commit.\n        retry:\n          max: 3\n          otherwise: health.escalate\n        on:\n          \"* **\": health.check\n\n      fix-spec:\n        actor: agent\n        label: Fixing review feedback\n        file: <%= it.vars.specFeedbackFile %>\n        prompt: |\n          You are an autonomous coding agent. This workflow steers itself\n          through its own state files — treat them as its private scratchpad,\n          never as project code or documentation. The only state file this\n          turn touches is `<%= it.vars.specFeedbackFile %>`; address it, then\n          delete it. Do not create other files to hold notes or output.\n\n          Read `<%= it.vars.specFeedbackFile %>` (the reviewer's concerns about the\n          current package) and the package spec (`<%= it.read(it.vars.nextFile) %>`),\n          then fix the code to resolve every concern. Keep the change focused.\n\n          Delete `<%= it.vars.specFeedbackFile %>` once every concern is addressed.\n          Leave everything else uncommitted and finish your turn.\n        on:\n          \"* **\": health.check\n\n      closing:\n        actor: check\n        label: Closing out the package\n        script: |\n          #!/usr/bin/env bash\n          # gtd check turn (the package closer) — remove the just-reviewed package\n          # file (its path is in NEXT.md) plus any leftover spec feedback, so\n          # `picking` selects the NEXT package (or falls through to review when the\n          # queue is empty). Reached on approval (spec review clean) and on the\n          # spec review retry cap (force-close, deferring the concern to the tail).\n          set +e\n          pkg=$(cat <%~ it.vars.nextFile %> 2>/dev/null)\n          [ -n \"$pkg\" ] && rm -f \"$pkg\"\n          rm -f <%~ it.vars.specFeedbackFile %> <%~ it.vars.nextFile %>\n        on:\n          \"* **\": $onNext\n\n      # Per-package health pair: packages.item.health.check/.escalate ->\n      # packages.item.spec.review (green) or packages.item.fix-suite (red).\n      health:\n        machine: healthGate\n        with:\n          onGreen: spec\n          onRed: fix-suite\n          escalateDescribe: >-\n            edit the code and/or `.gtd/FEEDBACK.md` yourself\n            (**packages.item.health.check**).\n          checkLabel: Running checks\n          escalateLabel: Escalating to a human\n\n      # Per-package agentic review: packages.item.spec.review -> closing\n      # (approved), or packages.item.fix-spec (findings — re-verify via the\n      # full health check before re-reviewing).\n      spec:\n        machine: specReview\n        with:\n          onApproved: closing\n          onFix: fix-spec\n\n  # ── ENCAPSULATION: the simple flow's build identity ────────────────────────\n  # ▸ coder identity — `model:` declared once here, stamped onto `building`,\n  # `squashing`, `addressing`, and `fix` (its own prompt states). Decomposition\n  # (`design.decompose`) belongs to the planner tier now, not here — see\n  # `advancedPlan` below. `addressing` is the implementer's OWN follow-through\n  # on review feedback (a coder action) — reached via `$onFeedback`, bound at\n  # its own `review:` reference below, not nested inside the (planner-only)\n  # `humanReview` machine. `humanReview` is nested HERE (not at the root) so\n  # the review tail's run stays inside the builder's own scope — see the\n  # header comment.\n  simpleBuild:\n    model: <%= it.vars.coderModel %>\n    params: [onDone]\n    entry: building\n    states:\n      building:\n        actor: agent\n        label: Building\n        file: <%= it.vars.todoFile %>\n        prompt: |\n          You are an autonomous coding agent. This workflow steers itself through\n          its own state files — treat them as its private scratchpad, never as\n          project code or documentation. The only state file this turn touches is\n          `<%= it.vars.todoFile %>`; delete it once its work is complete. Do not\n          create other files to hold notes or output.\n\n          The plan to implement is: <%~ it.read(it.vars.todoFile) %>\n\n          Read that plan and implement it in full. Use TDD discipline: one test,\n          then the implementation that passes it, then the next — never write all\n          the tests first.\n\n          Delete `<%= it.vars.todoFile %>` once the work it describes is complete\n          and verified. Leave everything else uncommitted and finish your turn.\n        on:\n          \"* **\": health.check\n\n      squashing:\n        actor: agent\n        label: Squashing\n        file: <%= it.vars.commitMsgFile %>\n        prompt: |\n          You are an autonomous coding agent. The cycle is approved and done. This\n          workflow steers itself through its own state files — treat them as its\n          private scratchpad, never as project code or documentation. The only\n          state file this turn touches is `<%= it.vars.commitMsgFile %>`; write\n          it. Do not create other files to hold notes or output.\n\n          Leave `<%= it.vars.commitMsgFile %>` uncommitted and finish your turn —\n          entering this file squashes everything this process retains into one\n          commit using its content as the message. This prompt carries no diff —\n          if you built that range yourself earlier in this conversation, work from\n          what you already know; otherwise read the range yourself. It runs from\n          `<%= it.retainedBase %>` to the working tree, and is exactly what that\n          commit will contain, the changes THIS process made (its trace/retry\n          boundary onward). For a normal build\n          cycle that is the whole feature; for a `gtd --entry review-gate.check`\n          process it is only the fixes made during the review — NOT the changeset\n          that was under review.\n\n          If that range is non-empty, write `<%= it.vars.commitMsgFile %>` with ONE\n          conventional-commits message for the changes (subject line\n          `type(scope): subject`, imperative mood, <= 72 characters; a body\n          explaining the why, trade-offs, and key decisions). Plain text, no\n          markdown wrapper.\n\n          If that range is empty (a clean review sign-off with no fixes), write\n          `<%= it.vars.commitMsgFile %>` with exactly this one line and nothing\n          else:\n\n          chore: human review\n        on:\n          \"A <%= it.vars.commitMsgFile %>\": $onDone\n          \"M <%= it.vars.commitMsgFile %>\": $onDone\n\n      addressing:\n        actor: agent\n        label: Addressing your feedback\n        file: <%= it.vars.reviewFeedbackFile %>\n        # Refuse a work-free turn: a step whose only pending change is deleting the\n        # instructions file (the original \"captured then discarded\" bug). The edge\n        # gate (`enforceFeedbackProgressGate` in src/program.ts) reads this flag and\n        # exempts a `NOTHING ACTIONABLE` sentinel (a non-actionable review round,\n        # which legitimately makes no code change). The pure engine carries it inert.\n        requireProgress: true\n        prompt: |\n          You are an autonomous coding agent addressing review feedback. This\n          workflow steers itself through its own state files — treat them as\n          its private scratchpad, never as project code or documentation. The\n          only state file this turn touches is\n          `<%= it.vars.reviewFeedbackFile %>`; address it, then delete it. Do\n          not create other files to hold notes or output.\n\n          The instructions to implement are: <%~ it.read(it.vars.reviewFeedbackFile) %>\n\n          This is a flat instruction list, not a diff — execute every item exactly as\n          written, no Q&A, no re-planning, using TDD discipline:\n\n          - An item that says the human's own lines are final: build ON TOP of them to\n            complete only the follow-through it names (callers, tests, types, docs).\n            NEVER revert or rewrite the lines they already committed.\n          - An item derived from a human comment: satisfy it AND delete that comment\n            line from the code (the human's review comments are transient — none of\n            them survive this round).\n\n          If the file's sole content is a `NOTHING ACTIONABLE` line, make no code\n          change; just delete the instructions file.\n\n          Delete `<%= it.vars.reviewFeedbackFile %>` once every item is addressed.\n          Leave everything else uncommitted and finish your turn. Deleting the\n          instructions file WITHOUT making the changes it asks for is refused — the\n          feedback must actually be addressed.\n        on:\n          \"* **\": health.check\n\n      fix:\n        actor: agent\n        label: Fixing the check\n        file: <%= it.vars.feedbackFile %>\n        prompt: *suiteFixPrompt\n        retry:\n          max: 3\n          otherwise: health.escalate\n        on:\n          \"* **\": health.check\n\n      # Shared health pair: build.health.check/.escalate -> build.review.reviewing\n      # (green) or build.fix (red).\n      health:\n        machine: healthGate\n        with:\n          onGreen: review\n          onRed: fix\n          escalateDescribe: >-\n            edit the code and/or `.gtd/FEEDBACK.md` yourself\n            (**build.health.check**).\n          checkLabel: Running checks\n          escalateLabel: Escalating to a human\n\n      # The shared review tail, nested HERE (not at the root) so its run stays\n      # inside the builder's own scope across the feedback round-trip — see\n      # the header comment. Sign-off -> squashing; feedback -> addressing (the\n      # implementer's own coder-identity follow-through, not a reviewer action).\n      review:\n        machine: humanReview\n        with:\n          onSignoff: squashing\n          onFeedback: addressing\n\n  # The root machine — the whole \"advanced/simple\" flow tree described in\n  # this file's header comment. WIRING ONLY: no identity of its own, just the\n  # shared entry/exit states and the top-level machine tree.\n  unified:\n    entry: idle\n    states:\n      # ── Shared entry ────────────────────────────────────────────────────────\n      idle:\n        actor: human\n        label: Idle\n        # Every human-gate `message:` below closes with the same rendered \"What\n        # each change does next\" list, built from `it.edges` (the resting state's\n        # own `on` edges — each edge's `describe:` is the single source of truth).\n        message: |\n          No active gtd cycle.\n\n          To start one, create a steering file describing what you want built:\n\n          - `<%= it.vars.todoFile %>` — a short sketch — starts the SIMPLE flow\n            (plan, build, review).\n          - `<%= it.vars.requirementsFile %>` — the product requirements — starts\n            the ADVANCED flow (product + technical Q&A, package decomposition,\n            parallel build, per-package agentic review).\n\n          What each change does next (then run `gtd step human`):\n          <% it.edges.forEach(function (e) { if (e.describe) { %>\n          <%~ \"- \" + (e.action ? \"**\" + e.action + \"** — \" : \"\") + e.describe + \"\\n\" %>\n          <% } }) %>\n        on:\n          \"* <%= it.vars.requirementsFile %>\":\n            to: spec-gate\n            action: Start advanced flow\n            describe: >-\n              save the product requirements to `.gtd/REQUIREMENTS.md` — gtd first\n              checks the test baseline is green, then the agent develops them\n              through product then technical Q&A, decomposes the work into\n              packages, and builds each in parallel (**spec-gate.check**).\n          \"* **\":\n            to: plan-gate\n            action: Start simple flow\n            describe: >-\n              save a short sketch to `.gtd/TODO.md` (or any other change) — gtd\n              first checks the test baseline is green, then the agent reads it,\n              explores the codebase, and develops it into a concrete\n              implementation plan (**plan-gate.check**).\n\n      # ── Green-baseline gate: `gtd --entry fix-precheck` entry ─────────────────\n      # `gtd --entry fix-precheck` enters HERE: run the suite, then a red run\n      # drops straight into the shared `build.fix` loop (-> build.health.check ->\n      # review + squash tail); a green run is a no-op back to `idle` (nothing\n      # to fix).\n      fix-precheck:\n        actor: check\n        label: Checking the baseline\n        entry: true\n        script: *suiteCheck\n        on:\n          \"A <%= it.vars.feedbackFile %>\": build.fix\n          \"M <%= it.vars.feedbackFile %>\": build.fix\n          \"D <%= it.vars.feedbackFile %>\": idle\n          \"C\": idle\n\n      # ── Shared tail: the finale ─────────────────────────────────────────────\n      done:\n        commit: |\n          <%~ it.read(it.vars.commitMsgFile) %>\n\n          Token cost: <%= it.processCost %>\n          <% it.processCostByModel.forEach(function(m){ %>\n          - <%= m.model %>: <%= m.cost %>\n          <% }) %>\n\n      # ── Green-baseline gate: simple flow entry. ────────────────────────────────\n      plan-gate:\n        machine: entryGate\n        with:\n          onGreen: plan\n          reviewBase: \"\"\n          blockedMessage: |\n            The test baseline is red — gtd will not start new work on a broken suite.\n            `<%= it.vars.feedbackFile %>` holds the failing output.\n\n            What each change does next (then run `gtd step human`):\n            <% it.edges.forEach(function (e) { if (e.describe) { %>\n            <%~ \"- \" + (e.action ? \"**\" + e.action + \"** — \" : \"\") + e.describe + \"\\n\" %>\n            <% } }) %>\n          blockedDescribe: >-\n            edit the code and/or `.gtd/FEEDBACK.md` to fix the failing tests\n            (**plan-gate.check**). To repair the baseline as its own separate\n            reviewed commit instead, abandon this start and run\n            `gtd --entry fix-precheck` from a clean `idle`.\n          checkLabel: Checking the baseline\n          blockedLabel: Baseline is red\n\n      # ── Green-baseline gate: advanced flow entry. ──────────────────────────────\n      spec-gate:\n        machine: entryGate\n        with:\n          onGreen: design\n          reviewBase: \"\"\n          blockedMessage: |\n            The test baseline is red — gtd will not start new work on a broken suite.\n            `<%= it.vars.feedbackFile %>` holds the failing output.\n\n            What each change does next (then run `gtd step human`):\n            <% it.edges.forEach(function (e) { if (e.describe) { %>\n            <%~ \"- \" + (e.action ? \"**\" + e.action + \"** — \" : \"\") + e.describe + \"\\n\" %>\n            <% } }) %>\n          blockedDescribe: >-\n            edit the code and/or `.gtd/FEEDBACK.md` to fix the failing tests\n            (**spec-gate.check**). To repair the baseline as its own separate\n            reviewed commit instead, abandon this start and run\n            `gtd --entry fix-precheck` from a clean `idle`.\n          checkLabel: Checking the baseline\n          blockedLabel: Baseline is red\n\n      # ── Green-baseline gate: `gtd --entry review-gate.check` entry -> build.review.reviewing. ─\n      review-gate:\n        machine: entryGate\n        with:\n          onGreen: build.review\n          reviewBase: <%= it.vars.reviewBase %>\n          blockedMessage: |\n            The test baseline is red — gtd will not start a review on a broken suite.\n            `<%= it.vars.feedbackFile %>` holds the failing output.\n\n            What each change does next (then run `gtd step human`):\n            <% it.edges.forEach(function (e) { if (e.describe) { %>\n            <%~ \"- \" + (e.action ? \"**\" + e.action + \"** — \" : \"\") + e.describe + \"\\n\" %>\n            <% } }) %>\n          blockedDescribe: >-\n            edit the code and/or `.gtd/FEEDBACK.md` to fix the failing tests\n            (**review-gate.check**).\n          checkLabel: Checking the baseline\n          blockedLabel: Baseline is red\n\n      # ── Advanced flow: the design conversation (design.product-author/.product-answer ─\n      # -> design.technical-author/.technical-answer -> design.decompose -> packages). ──\n      design:\n        machine: advancedPlan\n        with:\n          onPackages: packages\n\n      # ── Simple flow plan-iteration loop (plan.planning/.await-plan -> build.building). ──\n      plan:\n        machine: planLoop\n        with:\n          onAccept: build.building\n\n      # ── Advanced per-package build queue (packages.* -> build.review). ────────\n      packages:\n        machine: packageLoop\n        with:\n          onDrained: build.review\n\n      # ── Simple flow's build identity (build.* -> build.review -> done). ───────\n      build:\n        machine: simpleBuild\n        with:\n          onPackages: packages\n          onDone: done\n";
 //#endregion
 //#region src/workflows/templates.ts
 /**
@@ -190699,13 +191074,21 @@ const DEFAULT_WORKFLOW = compileWorkflowConfig((0, import_dist$1.parse)(UNIFIED_
 /** The compiled built-in default workflow definition — the fallback when no `workflow:` is configured. */
 const defaultWorkflowDefinition = DEFAULT_WORKFLOW.definition;
 /**
-* The built-in default's RAW workflow value — `unified.yaml` parsed but NOT
-* expanded, so it still carries `submachines:`/`use:`. `src/Config.ts` exposes
-* it as `ConfigOperations.rawWorkflow` for the built-in default; tooling that
-* needs the sub-machine grouping the compiled definition flattens away (e.g.
-* `gtd visualize`'s `collectGroups`) reads it. Parsed once at module load.
+* The built-in default's machine-instance tree — the same `MachineNode` tree
+* `flattenMachines` (`src/Machines.ts`) built while compiling `DEFAULT_WORKFLOW`
+* above, exposed for tooling that needs the machine grouping the compiled
+* `WorkflowDefinition` flattens away (e.g. `gtd visualize`). `src/Config.ts`
+* exposes it as `ConfigOperations.machineTree` for the built-in default.
+*/
+const defaultMachineTree = DEFAULT_WORKFLOW.tree;
+/**
+* The built-in default's memory-scope map — qualified state name -> the
+* machine-instance path that owns it, the same `scopes` map
+* `flattenMachines` (`src/Machines.ts`) built while compiling
+* `DEFAULT_WORKFLOW` above. `src/Config.ts` exposes it as
+* `ConfigOperations.stateScopes` for the built-in default.
 */
-const defaultWorkflowRaw = (0, import_dist$1.parse)(UNIFIED_WORKFLOW);
+const defaultStateScopes = DEFAULT_WORKFLOW.scopes;
 /** The built-in default workflow's own declared `vars:` defaults (layer 1 of the merged `it.vars`). */
 const defaultWorkflowVars = DEFAULT_WORKFLOW.vars;
 /**
@@ -190799,187 +191182,172 @@ const modesJsonSchema = {
 		}
 	}
 };
-/** One state's shape — mirrors `PatternConfig.ts`'s `KNOWN_STATE_KEYS` and per-field compilers. */
-const stateJsonSchema = {
-	type: "object",
-	description: "One workflow state. Declare exactly one content kind (script/prompt/message/commit). A commit state is final: no actor, no on.",
-	additionalProperties: false,
-	properties: {
-		actor: {
-			type: "string",
-			description: "Who acts at this state. Required on every non-commit state; forbidden on a commit state."
-		},
-		script: {
-			type: "string",
-			description: "Content kind: a shell script (Eta template). The loop driver executes it verbatim via bash, then steps this state's actor."
-		},
-		prompt: {
-			type: "string",
-			description: "Content kind: an agent prompt (Eta template), emitted by `gtd next`."
-		},
-		message: {
-			type: "string",
-			description: "Content kind: a human-facing message (Eta template), emitted by `gtd next`."
-		},
-		commit: {
-			type: "string",
-			description: "Content kind: entering this state ends the process by squashing it into one commit with this message (Eta template). Final — no actor, no on."
-		},
-		on: {
-			type: "object",
-			description: "Ordered map of change pattern -> target state. Patterns: \"C\" (clean tree) or \"<A|M|D|*> <glob>\" over the pending diff; first declared match wins. Every target must name a defined state, and every non-initial state must be reachable through these edges (or a retry.otherwise). A value is either the target state name (string) or a { to, describe } object whose describe is a human-readable sentence templates can surface as it.edges (e.g. in a human gate's message).",
-			additionalProperties: { oneOf: [{
-				type: "string",
-				description: "The target state name."
-			}, {
-				type: "object",
-				additionalProperties: false,
-				required: ["to"],
-				properties: {
-					to: {
-						type: "string",
-						description: "The target state name."
-					},
-					describe: {
-						type: "string",
-						description: "Human-readable sentence describing where this change routes; surfaced verbatim (never Eta-rendered) to templates as it.edges[].describe."
-					}
-				}
-			}] }
-		},
-		initial: {
-			type: "boolean",
-			description: "Exactly one state in the workflow must declare initial: true (and it must not be a commit state)."
-		},
-		retry: {
-			type: "object",
-			description: "Redirect transitions INTO this state once it has been entered `max` times in the current process.",
-			additionalProperties: false,
-			required: ["max", "otherwise"],
-			properties: {
-				max: {
-					type: "integer",
-					minimum: 0,
-					description: "Entries allowed this process before redirecting."
-				},
-				otherwise: {
-					type: "string",
-					description: "Defined state to redirect to once over the cap."
-				}
-			}
-		},
-		model: {
-			type: "string",
-			description: "Opaque harness hint passed through `gtd next --json`/`gtd status --json` (e.g. \"smart\"). Never interpreted by gtd. Forbidden on a commit state."
-		},
-		memory: {
-			type: "string",
-			description: "Opaque memory-scope label passed through `gtd next --json`/`gtd status --json` (e.g. \"plan\"). A memory-aware driver retains an agent's memory across consecutive agent turns sharing this label and starts fresh when it changes. Never interpreted by gtd. Forbidden on a commit state."
-		},
-		file: {
-			type: "string",
-			description: "The state's steering file: an Eta template naming the file a human/editor should look at while the machine rests here. Forbidden on a commit state."
-		},
-		mode: {
-			type: "string",
-			description: "The steering file's format: the name of a built-in mode (qa/review, validated in-process by gtd) or of a `modes:` entry. gtd formats and validates the file with that mode before capturing a turn out of this state, and the LSP dispatches live diagnostics on the built-in names. Requires a sibling `file:`. Forbidden on a commit state."
-		},
-		reviewWindow: {
-			type: "boolean",
-			description: "When true, gtd opens a review checkout window while the machine rests here — HEAD/index are rewound to the review base so the whole base..HEAD diff surfaces as uncommitted changes in the editor. Forbidden on a commit state."
-		},
-		reviewBase: {
-			type: "boolean",
-			description: "Marks the state whose most-recent in-process commit anchors the review window's diff base; absent any, the base is the process start. Forbidden on a commit state."
-		},
-		reviewEntry: {
-			type: "boolean",
-			description: "Marks the (at most one) state `gtd review <commitish>` enters to start a brand new process reviewing <commitish>..HEAD. Forbidden on a commit state and on the initial state."
-		},
-		fixEntry: {
-			type: "boolean",
-			description: "Marks the (at most one) state `gtd fix` enters to start a brand new process that goes straight into repairing the current failing tests. Forbidden on a commit state and on the initial state."
-		},
-		requireProgress: {
-			type: "boolean",
-			description: "When true, a step at this state is refused if its only pending change is deleting the state's own `file:` — a work-free turn that discards its input without addressing it. A `NOTHING ACTIONABLE` sentinel file is exempt (a legitimately non-actionable round makes no code change). Requires a `file:`. Forbidden on a commit state."
-		},
-		answerGate: {
-			type: "boolean",
-			description: "When true, a step at this state is refused unless every open question in its qa-mode `file:` is answered — exactly one checkbox ticked per question. Requires a `file:` and `mode: qa`. Forbidden on a commit state."
-		}
-	}
-};
 /** The whole `workflow:` value — see `PatternConfig.ts`'s module docstring for the authoritative schema. */
 const workflowJsonSchema = {
 	type: "object",
-	description: "The whole machine definition: named states (plus the workflow's own vars: defaults and modes: steering-file modes). Compiled and validated by gtd at load time; content strings starting with ./ or ../ are file references inlined from the config file's directory (a modes: command never is — it is a shell command).",
+	description: "The whole machine definition: a tree of named machines rooted at entry.default (plus the workflow's own vars: defaults and modes: steering-file modes). Compiled and validated by gtd at load time; content strings starting with ./ or ../ are file references inlined from the config file's directory (a modes: command never is — it is a shell command).",
 	additionalProperties: false,
-	required: ["states"],
+	required: ["entry", "machines"],
 	properties: {
 		vars: varsJsonSchema,
 		modes: modesJsonSchema,
-		submachines: {
+		entry: {
 			type: "object",
-			description: "Optional reusable sub-machines, invoked by `use:` and expanded into concrete states at load time (see src/Submachines.ts).",
+			description: "The workflow's root machine, resolved through the same resolver an `on`/`retry.otherwise` target uses (see src/Machines.ts) — accepts either a bare state path or an instance/reference-key path. Extra manual entry points are declared per-state instead, via a state's own `entry: true` (see `stateJsonSchema`'s `entry` property) — not here.",
+			additionalProperties: false,
+			required: ["default"],
+			properties: { default: {
+				type: "string",
+				description: "Which declared `machines:` entry is the ROOT instance."
+			} }
+		},
+		machines: {
+			type: "object",
+			description: "Named, reusable machines — at least the one entry.default names.",
+			minProperties: 1,
 			additionalProperties: {
 				type: "object",
-				description: "A reusable, parameterized cluster of states, expanded at load time by each `use:` invocation into concrete states (see src/Submachines.ts). Purely a source-authoring convenience — the engine only ever sees the expanded states.",
+				description: "A named, reusable machine: an entry local plus a set of states, each either an ordinary state or a reference instantiating another machine as a child (see src/Machines.ts).",
 				additionalProperties: false,
-				required: ["states"],
+				required: ["entry", "states"],
 				properties: {
 					params: {
 						type: "array",
 						items: { type: "string" },
-						description: "Parameter names. A `$name` token used as a whole field value or `on`/`retry.otherwise` target is replaced by the invocation's `with:` binding."
+						description: "Advisory only — documents which $params a caller may bind via a reference's `with:`. A `$name` token used as a whole field value or `on`/`retry.otherwise` target is resolved against the binding."
 					},
-					states: {
-						type: "object",
-						description: "The sub-machine's local states. `on`/`retry.otherwise` targets naming another local are rewritten via `as:`; a `$name` value is bound from `with:`.",
-						minProperties: 1,
-						additionalProperties: stateJsonSchema
-					}
-				}
-			}
-		},
-		use: {
-			type: "array",
-			description: "Sub-machine invocations. Each clones a `submachines:` entry into concrete states: `as:` renames its locals (identity when omitted), `with:` binds its `$param`s, `set:` adds extra per-instance state fields.",
-			items: {
-				type: "object",
-				additionalProperties: false,
-				required: ["submachine"],
-				properties: {
-					submachine: {
+					entry: {
 						type: "string",
-						description: "Name of a declared sub-machine."
+						description: "This machine's own default local (a local state name, or a reference key), resolved recursively."
 					},
-					name: {
+					model: {
 						type: "string",
-						description: "Optional label for this instance (inert to expansion; used by tooling like `gtd visualize` to name the group). Defaults to the sub-machine name."
-					},
-					as: {
-						type: "object",
-						description: "Rename map: local state name -> concrete state name (identity when omitted).",
-						additionalProperties: { type: "string" }
-					},
-					with: {
-						type: "object",
-						description: "Bindings for the sub-machine's `$param`s."
+						description: "Opaque harness hint stamped onto every one of this machine's own `prompt` states (e.g. \"smart\"), passed through `gtd next --json`/`gtd status --json`. The ONLY place a model may be declared — a state carrying its own `model:` is a config error. Never interpreted by gtd. A machine declaring this with no `prompt` state is a config error."
 					},
-					set: {
+					states: {
 						type: "object",
-						description: "Extra fields merged onto a renamed local state, keyed by local name.",
-						additionalProperties: { type: "object" }
+						description: "This machine's local states, each either an ordinary state or a `{ machine, with }` reference.",
+						minProperties: 1,
+						additionalProperties: { oneOf: [{
+							type: "object",
+							description: "One workflow state. Declare exactly one content kind (script/prompt/message/commit). A commit state is final: no actor, no on.",
+							additionalProperties: false,
+							properties: {
+								actor: {
+									type: "string",
+									description: "Who acts at this state. Required on every non-commit state; forbidden on a commit state."
+								},
+								script: {
+									type: "string",
+									description: "Content kind: a shell script (Eta template). The loop driver executes it verbatim via bash, then steps this state's actor."
+								},
+								prompt: {
+									type: "string",
+									description: "Content kind: an agent prompt (Eta template), emitted by `gtd next`."
+								},
+								message: {
+									type: "string",
+									description: "Content kind: a human-facing message (Eta template), emitted by `gtd next`."
+								},
+								commit: {
+									type: "string",
+									description: "Content kind: entering this state ends the process by squashing it into one commit with this message (Eta template). Final — no actor, no on."
+								},
+								on: {
+									type: "object",
+									description: "Ordered map of change pattern -> target state. Patterns: \"C\" (clean tree) or \"<A|M|D|*> <glob>\" over the pending diff; first declared match wins. Every target must name a defined state, and every non-initial state must be reachable through these edges (or a retry.otherwise). A value is either the target state name (string) or a { to, describe, action } object whose describe/action are human-readable strings templates can surface as it.edges (e.g. in a human gate's message).",
+									additionalProperties: { oneOf: [{
+										type: "string",
+										description: "The target state name."
+									}, {
+										type: "object",
+										additionalProperties: false,
+										required: ["to"],
+										properties: {
+											to: {
+												type: "string",
+												description: "The target state name."
+											},
+											describe: {
+												type: "string",
+												description: "Human-readable sentence describing where this change routes; surfaced verbatim (never Eta-rendered) to templates as it.edges[].describe."
+											},
+											action: {
+												type: "string",
+												description: "Imperative label for this edge (e.g. \"Accept plan\"); surfaced verbatim (never Eta-rendered) to templates/tooling as it.edges[].action."
+											}
+										}
+									}] }
+								},
+								retry: {
+									type: "object",
+									description: "Redirect transitions INTO this state once it has been entered `max` times in the current process.",
+									additionalProperties: false,
+									required: ["max", "otherwise"],
+									properties: {
+										max: {
+											type: "integer",
+											minimum: 0,
+											description: "Entries allowed this process before redirecting."
+										},
+										otherwise: {
+											type: "string",
+											description: "Defined state to redirect to once over the cap."
+										}
+									}
+								},
+								label: {
+									type: "string",
+									description: "Opaque display name passed through `gtd next --json`/`gtd status --json` so a driver/viewer can show something nicer than the raw state name (e.g. \"Running checks\"). Never interpreted by gtd. Forbidden on a commit state."
+								},
+								file: {
+									type: "string",
+									description: "The state's steering file: an Eta template naming the file a human/editor should look at while the machine rests here. Forbidden on a commit state."
+								},
+								mode: {
+									type: "string",
+									description: "The steering file's format: the name of a built-in mode (qa/review, validated in-process by gtd) or of a `modes:` entry. gtd formats and validates the file with that mode before capturing a turn out of this state, and the LSP dispatches live diagnostics on the built-in names. Requires a sibling `file:`. Forbidden on a commit state."
+								},
+								reviewWindow: {
+									type: "boolean",
+									description: "When true, gtd opens a review checkout window while the machine rests here — HEAD/index are rewound to the review base so the whole base..HEAD diff surfaces as uncommitted changes in the editor. Forbidden on a commit state."
+								},
+								reviewBase: {
+									oneOf: [{ const: true }, { type: "string" }],
+									description: "true marks the state whose most-recent in-process commit anchors the review window's diff base; absent any, the base is the process start. A string is a different shape: an Eta template rendering a commitish that becomes the WHOLE PROCESS's fixed diff base when this state is entered manually via `gtd --entry <state> --base <commitish>` (see the `entry` property below). Forbidden on a commit state."
+								},
+								requireProgress: {
+									type: "boolean",
+									description: "When true, a step at this state is refused if its only pending change is deleting the state's own `file:` — a work-free turn that discards its input without addressing it. A `NOTHING ACTIONABLE` sentinel file is exempt (a legitimately non-actionable round makes no code change). Requires a `file:`. Forbidden on a commit state."
+								},
+								answerGate: {
+									type: "boolean",
+									description: "When true, a step at this state is refused unless every open question in its qa-mode `file:` is answered — exactly one checkbox ticked per question. Requires a `file:` and `mode: qa`. Forbidden on a commit state."
+								},
+								entry: {
+									const: true,
+									description: "Marks this state as an extra manual entry point (WorkflowEntries.manual), enterable via `gtd --entry <state>`. Not to be confused with the top-level `entry:` key naming the root machine (entry.default) — same name, different level, by design."
+								}
+							}
+						}, {
+							type: "object",
+							description: "A reference: instantiates the named machine as a child, at this local's path (see src/Machines.ts). Expanded at load time into concrete, qualified states — the engine only ever sees the flattened result.",
+							additionalProperties: false,
+							required: ["machine"],
+							properties: {
+								machine: {
+									type: "string",
+									description: "Name of a declared entry in `machines:`."
+								},
+								with: {
+									type: "object",
+									description: "Bindings for the referenced machine's `params:`. A bound value naming another of the CALLER's own bindings (a whole-value `$name`) passes it down verbatim, scope intact."
+								}
+							}
+						}] }
 					}
 				}
 			}
-		},
-		states: {
-			type: "object",
-			description: "The workflow's named states. At least one; exactly one with initial: true.",
-			minProperties: 1,
-			additionalProperties: stateJsonSchema
 		}
 	}
 };
@@ -191186,15 +191554,17 @@ const toOperations = (decoded, root) => {
 			} : defaultWorkflowDefinition,
 			workflowVars: defaultWorkflowVars,
 			rcVars,
-			rawWorkflow: defaultWorkflowRaw
+			machineTree: defaultMachineTree,
+			stateScopes: defaultStateScopes
 		};
 	}
-	const { definition, vars: workflowVars } = compileWorkflowConfig(decoded.workflow, root, rcModes, false);
+	const { definition, vars: workflowVars, tree, scopes } = compileWorkflowConfig(decoded.workflow, root, rcModes, false);
 	return {
 		workflow: definition,
 		workflowVars,
 		rcVars,
-		rawWorkflow: decoded.workflow
+		machineTree: tree,
+		stateScopes: scopes
 	};
 };
 const formatSchemaError = (e) => {
@@ -191264,15 +191634,40 @@ const parseNameStatus = (out) => {
 	return result;
 };
 /**
+* True when `error` is git's `index.lock` contention failure — another process
+* held the index lock when git tried to take it. gtd shares one worktree index
+* with every git-aware tool the reviewer runs (editor SCM, `gtd lsp`,
+* git-aware shell prompts): each refreshes its stat cache by WRITING the index
+* whenever a `git reset --mixed` in the review window wakes it, so gtd's own
+* index writes lose the `index.lock` race often on a large repo (where each
+* write takes long enough for the windows to overlap). The lock failure is a
+* pure "couldn't start" — git did nothing — so the losing command is safe to
+* retry verbatim (see `withIndexLockRetry`).
+*/
+const isIndexLockError = (error) => /index\.lock[\s\S]*File exists|Another git process seems to be running/i.test(error.message);
+/**
+* Retry an index-writing git command through transient `index.lock` contention
+* with jittered exponential backoff (~10ms → ~640ms, capped at 6 retries), and
+* ONLY on that error — any other failure propagates on the first attempt. This
+* is the general defense for the concurrent reality `isIndexLockError`
+* describes; it covers every index writer (`git add -A`, `reset`, `restore`),
+* not just the review window's own steps.
+*/
+const withIndexLockRetry = (eff) => retry(eff, {
+	schedule: intersect(recurs(6), exponential(millis(10), 2)).pipe(jittered),
+	while: (error) => isIndexLockError(error)
+});
+/**
 * 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
 * only collects stdout and silently ignores exit codes, which used to make
 * gtd report success on rejected commits (hooks, gpg), resolve Idle outside a
 * repository, and lose files whose quoted paths broke a swallowed `git add`.
 * Callers that expect a probe to fail (missing refs, empty repos) handle it
-* with an explicit `catchAll`.
+* with an explicit `catchAll`. `index.lock` contention is retried transparently
+* (`withIndexLockRetry`) before any caller's `catchAll` sees it.
 */
-const run = (root, ...args) => scoped$3(gen(function* () {
+const run = (root, ...args) => withIndexLockRetry(scoped$3(gen(function* () {
 	const process = yield* (yield* CommandExecutor).start(make$1(...args).pipe(workingDirectory(root), stdout("pipe"), stderr("pipe")));
 	const collect = (stream) => stream.pipe(decodeText(), mkString);
 	const [stdout$2, stderr$2, exitCode] = yield* all([
@@ -191282,7 +191677,7 @@ const run = (root, ...args) => scoped$3(gen(function* () {
 	], { concurrency: "unbounded" });
 	if (exitCode !== 0) return yield* fail$2(/* @__PURE__ */ new Error(`${args.join(" ")} failed (exit ${exitCode}): ${stderr$2.trim()}`));
 	return stdout$2;
-})).pipe(mapError$1((e) => e instanceof Error ? e : new Error(String(e))));
+})).pipe(mapError$1((e) => e instanceof Error ? e : new Error(String(e)))));
 const makeGitImpl = (executor, root) => {
 	const exec = (...args) => run(root, ...args).pipe(provide$1(succeed$2(CommandExecutor, executor)));
 	return {
@@ -191348,8 +191743,7 @@ const makeGitImpl = (executor, root) => {
 		deleteRef: (ref) => exec("git", "update-ref", "-d", ref).pipe(asVoid),
 		mixedResetTo: (ref) => exec("git", "reset", "--mixed", ref).pipe(asVoid),
 		hardResetTo: (ref) => exec("git", "reset", "--hard", ref).pipe(asVoid),
-		restoreStagedFrom: (source, paths) => paths.length === 0 ? _void : exec("git", "restore", "--staged", `--source=${source}`, "--", ...paths).pipe(catchAll(() => _void)),
-		addIntentToAdd: () => exec("git", "add", "--intent-to-add", ".").pipe(asVoid)
+		restoreStagedFrom: (source, paths) => paths.length === 0 ? _void : exec("git", "restore", "--staged", `--source=${source}`, "--", ...paths).pipe(catchAll(() => _void))
 	};
 };
 const makeLiveEffect = gen(function* () {
@@ -191935,7 +192329,7 @@ const HISTORY_TRAILER_RE = /^Gtd-History:[ \t]*(\S+)[ \t]*$/m;
 /**
 * Append a `Gtd-History: <hash>` trailer (after a blank line) to a commit
 * `subject` — records the pre-squash tip commit hash so a later `gtd restore`
-* command can read it back. Mirrors `Edge.ts`'s `withReviewBaseTrailer`
+* command can read it back. Mirrors `Edge.ts`'s `withEntryTrailers`
 * placement: the subject (first line) is untouched.
 */
 const withHistoryTrailer = (subject, hash) => `${subject}\n\n${HISTORY_TRAILER_PREFIX}${hash}`;
@@ -192025,20 +192419,40 @@ const parseCostTrailers = (messages) => {
 const REVIEW_BASE_TRAILER_PREFIX = "Gtd-Review-Base: ";
 const REVIEW_BASE_TRAILER_RE = /^Gtd-Review-Base:[ \t]*(\S+)[ \t]*$/m;
 /**
-* Append a `Gtd-Review-Base: <base>` trailer (after a blank line) to a commit
-* `subject` — the entry commit `gtd review <commitish>` writes to start a new
-* review process. Mirrors `withCostTrailer`'s placement: the subject (first
-* line) is untouched, so `parseStateSubject`/`resolveState` read it back
-* exactly like any other turn commit.
-*/
-const withReviewBaseTrailer = (subject, base) => `${subject}\n\n${REVIEW_BASE_TRAILER_PREFIX}${base}`;
-/**
-* The `Gtd-Review-Base: <hash>` trailer recorded on a `gtd review <commitish>`
-* entry commit (see `withReviewBaseTrailer`), or `undefined` when `message`
-* carries none. Read back by `computeProcessRun` — ONLY off the process's
-* first (oldest) commit — to override the run's diff base.
+* The `Gtd-Review-Base: <hash>` trailer recorded on a `gtd step <actor>
+* --entry <state>` entry commit (see `withEntryTrailers`), or `undefined`
+* when `message` carries none. Read back by `computeProcessRun` — ONLY off
+* the process's first (oldest) commit — to override the run's diff base.
 */
 const parseReviewBaseTrailer = (message) => REVIEW_BASE_TRAILER_RE.exec(message)?.[1];
+const ENTRY_VAR_TRAILER_PREFIX = "Gtd-Var: ";
+const ENTRY_VAR_TRAILER_RE = /^Gtd-Var:[ \t]*([^=\s]+)=(.*)$/gm;
+/**
+* Compose, after a blank line, a `Gtd-Review-Base: <base>` line (when
+* `opts.base !== undefined`, readable back by `parseReviewBaseTrailer`),
+* followed by one `Gtd-Var: <name>=<value>` line per `opts.vars` entry (in
+* `Object.entries` order) — the single place that formats either trailer, for
+* every caller including `gtd review <commitish>`'s entry commit. Mirrors
+* `withCostTrailer`'s "nothing to add → unchanged" shape: with no base and an
+* empty `opts.vars`, `subject` is returned untouched.
+*/
+const withEntryTrailers = (subject, opts) => {
+	const lines = [];
+	if (opts.base !== void 0) lines.push(`${REVIEW_BASE_TRAILER_PREFIX}${opts.base}`);
+	for (const [name, value] of Object.entries(opts.vars)) lines.push(`${ENTRY_VAR_TRAILER_PREFIX}${name}=${value}`);
+	return lines.length === 0 ? subject : `${subject}\n\n${lines.join("\n")}`;
+};
+/**
+* Every `Gtd-Var: <name>=<value>` trailer found in `message` (each value
+* split on the FIRST `=` only, so a value containing `=` round-trips), or
+* `{}` when `message` carries none. Read back by `computeProcessRun` — ONLY
+* off the process's first (oldest) commit — into `ProcessRun.entryVars`.
+*/
+const parseEntryVarTrailers = (message) => {
+	const vars = {};
+	for (const match of message.matchAll(ENTRY_VAR_TRAILER_RE)) vars[match[1]] = match[2];
+	return vars;
+};
 /** The total token cost across the given entries (`0` when none). */
 const totalCostOf = (entries) => entries.reduce((sum, entry) => sum + entry.cost, 0);
 /** Per-model token totals, highest-cost first (ties broken by model name for a stable order). */
@@ -192059,11 +192473,31 @@ const normalizeStatus = (raw) => raw === "A" ? "A" : raw === "D" ? "D" : "M";
 * visualize`'s best-effort current-state read, which prefers the review
 * checkout window's saved head over a HEAD that may be mid-window-rewind (see
 * `src/ReviewWindow.ts`'s `REVIEW_HEAD_REF`).
+*
+* A HEAD subject that DOES parse as a `gtd(actor): state` commit, but whose
+* named state the CURRENT workflow definition doesn't declare AT ALL, is
+* refused loudly here rather than silently falling through `resolveState`'s
+* own initial-state fallback: an in-flight process left resting at a state a
+* workflow upgrade then renamed/removed out from under it would otherwise
+* look like a perfectly fresh, idle repo — the same courtesy the earlier
+* `entry.review`/`entry.fix` removal got, pointing at the command that
+* actually resolves it rather than a generic failure. Distinct from
+* `memoryScopeAt`'s graceful "unmapped state reads as fresh entry" behavior
+* (`src/PatternMachine.ts`, package 04), which handles a state that IS
+* declared but merely missing from `scopes` (a compiler bug, not a rename) —
+* this is about a state that no longer exists in the definition at all. Every
+* OTHER case `resolveState` already folds into "rest at the initial state"
+* (an unparseable subject, an actor mismatch, a commit-state target) is left
+* exactly as it was — those are legitimately "no active process" readings,
+* not a renamed-out-from-under-us one.
 */
 const resolveRest = (atRef) => gen(function* () {
 	const git = yield* GitService;
 	const def = (yield* (yield* ConfigService).load).workflow;
-	const state = resolveState(def, (yield* git.hasCommits()) ? yield* git.lastCommitSubject(atRef) : "");
+	const headSubject = (yield* git.hasCommits()) ? yield* git.lastCommitSubject(atRef) : "";
+	const parsedHead = parseStateSubject(headSubject);
+	if (parsedHead !== void 0 && def.states[parsedHead.state] === void 0) return yield* fail$2(/* @__PURE__ */ new Error(`gtd: HEAD rests at "${parsedHead.state}", which the active workflow no longer declares — this looks like a process left in-flight from before a workflow change. Run \`gtd abandon\` to discard it and start over (or check out the workflow version it started under).`));
+	const state = resolveState(def, headSubject);
 	const stateDef = def.states[state];
 	if (stateDef.actor === void 0) return yield* fail$2(/* @__PURE__ */ new Error(`gtd: resolved at commit state "${state}" — a process never rests there`));
 	return {
@@ -192079,6 +192513,23 @@ const pendingChanges = (git) => git.changedPaths().pipe(map$4((entries) => entri
 	path: e.path
 }))));
 /**
+* The `Gtd-Review-Base:`/`Gtd-Var:` overrides carried by the process's OLDEST
+* commit (its entry commit, when `gtd review <commitish>` or a future generic
+* entry started this process) — a later turn's message is never mistaken for
+* it. `{reviewBase: undefined, vars: {}}` when the process has no commits yet.
+*/
+const parseEntryCommitOverrides = (processCommits) => {
+	if (processCommits.length === 0) return {
+		reviewBase: void 0,
+		vars: {}
+	};
+	const message = processCommits[0].message;
+	return {
+		reviewBase: parseReviewBaseTrailer(message),
+		vars: parseEntryVarTrailers(message)
+	};
+};
+/**
 * Walk first-parent history backward from HEAD while each commit's subject
 * parses as `gtd(actor): state` (a v3 workflow commit) AND that state isn't
 * the workflow's initial state; the walk stops — EXCLUDING that boundary
@@ -192103,7 +192554,8 @@ const computeProcessRun = (git, def) => gen(function* () {
 		startParentHash: EMPTY_TREE$2,
 		diffBase: EMPTY_TREE$2,
 		trace: [],
-		costEntries: []
+		costEntries: [],
+		entryVars: {}
 	};
 	const initialState = initialStateOf(def);
 	const history = yield* git.commitHistory();
@@ -192115,37 +192567,81 @@ const computeProcessRun = (git, def) => gen(function* () {
 	}
 	const startIdx = i + 1;
 	const processCommits = history.slice(startIdx);
-	const trace = processCommits.map((h) => parseStateSubject(subjectOf$1(h.message)).state);
+	const trace = processCommits.map((h) => ({
+		state: parseStateSubject(subjectOf$1(h.message)).state,
+		hash: h.hash
+	}));
 	const costEntries = parseCostTrailers(processCommits.map((h) => h.message));
 	const startParentHash = i >= 0 ? history[i].hash : EMPTY_TREE$2;
+	const startHash = startIdx < history.length ? history[startIdx].hash : history[history.length - 1].hash;
+	const { reviewBase: reviewBaseOverride, vars: entryVars } = parseEntryCommitOverrides(processCommits);
 	return {
-		startHash: startIdx < history.length ? history[startIdx].hash : history[history.length - 1].hash,
+		startHash,
 		startParentHash,
-		diffBase: (processCommits.length > 0 ? parseReviewBaseTrailer(processCommits[0].message) : void 0) ?? startParentHash,
+		diffBase: reviewBaseOverride ?? startParentHash,
 		trace,
-		costEntries
+		costEntries,
+		entryVars
 	};
 });
+const ROOT_MEMORY_SCOPE_NAME = "root";
+/**
+* Compute the commit-anchored memory key for the currently-rested state, or
+* `undefined` when none applies — the pure `memoryScopeAt` (package 04)
+* result turned into an actual key string a memory-aware driver can group
+* consecutive agent turns by (see `TraceEntry`/`ProcessRun.trace`).
+*
+* Only a `prompt`-content rest carries a memory key — mirrors the rule that
+* only a prompt state carries `model` (kept here, not inside `memoryScopeAt`,
+* so that stays a clean, reusable primitive with no content-kind opinion).
+* `undefined` also propagates when `memoryScopeAt` itself can't resolve a
+* scope (`rest.state` absent from `scopes` — see its own doc comment).
+*
+* The key is `${scope || ROOT_MEMORY_SCOPE_NAME}#${token.slice(0, 7)}`, where
+* `token` anchors to the commit the CURRENT unbroken scope entry started
+* FROM, not the entry's own commit: `run.startParentHash` at `entryIndex <=
+* 0` (an empty trace, or the entry sitting at trace position 0 — no earlier
+* commit exists yet), else `run.trace[entryIndex - 1].hash`. Anchoring to the
+* entry's own commit would give a workflow whose initial state is a prompt
+* state two different tokens across its first two turns (nothing committed
+* yet before the very first turn) — anchoring to the commit the entry
+* started FROM makes the empty-trace and position-0 cases coincide by
+* construction.
+*/
+const memoryKeyFor = (scopes, rest, run) => {
+	if (contentKindOf(rest.stateDef) !== "prompt") return void 0;
+	const resolved = memoryScopeAt(scopes, rest.state, run.trace.map((entry) => entry.state));
+	if (resolved === void 0) return void 0;
+	const { scope, entryIndex } = resolved;
+	const token = entryIndex <= 0 ? run.startParentHash : run.trace[entryIndex - 1].hash;
+	return `${scope || ROOT_MEMORY_SCOPE_NAME}#${token.slice(0, 7)}`;
+};
 const PREFIX = "GTD_";
 /**
-* Assemble the merged `it.vars` map every template sees, from three layers
+* Assemble the merged `it.vars` map every template sees, from four layers
 * (later wins): the active workflow's own declared `vars:` defaults
 * (`ConfigOperations.workflowVars`), the top-level `.gtdrc` `vars:` key
-* (`ConfigOperations.rcVars`), and — for each name declared by either of
-* those two layers — a `GTD_<UPPERCASE-name>` environment variable, if
-* defined. Unlike the first two layers, the environment can only OVERRIDE a
-* name some config layer already declared; it can never introduce a new one
-* (an uppercased env key can't round-trip back to an arbitrary camelCase
-* name), so a `GTD_*` var matching no declared name is silently ignored. A
-* `value === undefined` entry (a name declared-but-unset in the environment)
-* is skipped, never coerced to the string `"undefined"`. Pure: `env` is
-* whatever the caller's `EnvVars` service handed it, never `process.env`
-* read directly here.
-*/
-const resolveVars = (workflowVars, rcVars, env) => {
+* (`ConfigOperations.rcVars`), the current process's entry commit's
+* `Gtd-Var:` trailers (`ProcessRun.entryVars` — fixed overrides recorded at
+* the moment a process like `gtd review <commitish>` started it), and — for
+* each name declared by any of those three layers — a `GTD_<UPPERCASE-name>`
+* environment variable, if defined. Unlike the first three layers, the
+* environment can only OVERRIDE a name some earlier layer already declared;
+* it can never introduce a new one (an uppercased env key can't round-trip
+* back to an arbitrary camelCase name), so a `GTD_*` var matching no declared
+* name is silently ignored. A `value === undefined` entry (a name
+* declared-but-unset in the environment) is skipped, never coerced to the
+* string `"undefined"`. `entryVars`, by contrast, needs no such filtering —
+* it's a plain unconditional spread, so a name from an old commit that
+* matches neither the workflow nor the rc layer still lands in the merged
+* map (pure and total; never throws). Pure: `env` is whatever the caller's
+* `EnvVars` service handed it, never `process.env` read directly here.
+*/
+const resolveVars = (workflowVars, rcVars, entryVars, env) => {
 	const merged = {
 		...workflowVars,
-		...rcVars
+		...rcVars,
+		...entryVars
 	};
 	for (const name of Object.keys(merged)) {
 		const value = env[PREFIX + name.toUpperCase()];
@@ -192271,18 +192767,6 @@ const renderModel = (stateDef, context) => try_({
 	catch: (e) => e instanceof Error ? e : new Error(String(e))
 });
 /**
-* Render a state's declared `memory:` scope label (if any) through the SAME
-* template context as its content/`model` — see `renderModel`'s doc comment;
-* a plain label (e.g. `"plan"`) passes through unchanged, while
-* `memory: "<%= it.vars.planScope %>"` resolves against the merged `it.vars`.
-* The render-failure semantics are identical (propagates as a thrown/rejected
-* error, same call site as `gtd next`/`gtd status`).
-*/
-const renderMemory = (stateDef, context) => try_({
-	try: () => stateDef.memory !== void 0 ? renderStateTemplate(stateDef.memory, context) : void 0,
-	catch: (e) => e instanceof Error ? e : new Error(String(e))
-});
-/**
 * Render a state's declared `label:` (if any) through the SAME template
 * context as its content/`model` — see `renderModel`'s doc comment; a plain
 * label (e.g. `"planning"`) passes through unchanged, while
@@ -192305,8 +192789,16 @@ const renderFile = (stateDef, context) => try_({
 	catch: (e) => e instanceof Error ? e : new Error(String(e))
 });
 const omitUndefined = (obj) => Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== void 0));
-/** Render the resolved rest's declared content (script/prompt/message — never `commit`, since `resolveRest` never rests at a commit state) plus its `model:`/`memory:`/`label:`/`file:` hints, if declared (see `renderModel`/`renderMemory`/`renderLabel`/`renderFile`). `mode:` is a closed literal, never Eta-rendered — passed through verbatim. */
-const renderRest = (rest, context) => gen(function* () {
+/**
+* Render the resolved rest's declared content (script/prompt/message — never
+* `commit`, since `resolveRest` never rests at a commit state) plus its
+* `model:`/`label:`/`file:` hints, if declared (see
+* `renderModel`/`renderLabel`/`renderFile`), and the COMPUTED memory key the
+* caller passes in (`memory`, from `memoryKeyFor` — package 05/06; this
+* module no longer derives it from `rest.stateDef.memory` itself). `mode:` is
+* a closed literal, never Eta-rendered — passed through verbatim.
+*/
+const renderRest = (rest, context, memory) => gen(function* () {
 	const kind = contentKindOf(rest.stateDef);
 	if (kind === void 0) return yield* fail$2(/* @__PURE__ */ new Error(`state "${rest.state}" declares no content — invalid definition`));
 	const template = rest.stateDef.script ?? rest.stateDef.prompt ?? rest.stateDef.message ?? rest.stateDef.commit;
@@ -192316,7 +192808,7 @@ const renderRest = (rest, context) => gen(function* () {
 	});
 	const hints = {
 		model: yield* renderModel(rest.stateDef, context),
-		memory: yield* renderMemory(rest.stateDef, context),
+		memory,
 		label: yield* renderLabel(rest.stateDef, context),
 		file: yield* renderFile(rest.stateDef, context),
 		mode: rest.stateDef.mode
@@ -192525,8 +193017,8 @@ const closeReviewWindow = gen(function* () {
 * is nothing to surface and the window stays closed.
 *
 * Ordering is crash-safe: base ref → head ref → mixed reset → `.gtd/` index
-* pin → intent-to-add. A crash before the head-ref write leaves only a stale
-* base ref (overwritten on the next open); a crash after it leaves HEAD ==
+* pin. A crash before the head-ref write leaves only a stale base ref
+* (overwritten on the next open); a crash after it leaves HEAD ==
 * review-head, which the next invocation's close restores as a no-op.
 */
 const openReviewWindow = gen(function* () {
@@ -192542,7 +193034,6 @@ const openReviewWindow = gen(function* () {
 	yield* git.updateRef(REVIEW_HEAD_REF, headHash);
 	yield* git.mixedResetTo(base);
 	yield* git.restoreStagedFrom(REVIEW_HEAD_REF, [".gtd"]);
-	yield* git.addIntentToAdd();
 	return { opened: true };
 });
 //#endregion
@@ -204247,7 +204738,7 @@ const worktreeLayerForRoot = (root) => WorktreeReader.Live.pipe(provide(Cwd.laye
 const loadModeMap = async (root, onWarn) => {
 	try {
 		const config = await runPromise$1(ConfigService.pipe(flatMap$4((c) => c.load), provide$1(configLayerForRoot(root))));
-		const vars = resolveVars(config.workflowVars, config.rcVars, process.env);
+		const vars = resolveVars(config.workflowVars, config.rcVars, {}, process.env);
 		const { map, warnings } = buildFileModeMap(config.workflow, vars, root);
 		for (const warning of warnings) onWarn(warning);
 		return map;
@@ -204285,7 +204776,7 @@ const resolveSteeringFile = (root) => gen(function* () {
 	const envVars = yield* EnvVars;
 	const rest = yield* resolveRest();
 	const run = yield* computeProcessRun(git, rest.def);
-	const vars = resolveVars(config.workflowVars, config.rcVars, envVars.all);
+	const vars = resolveVars(config.workflowVars, config.rcVars, {}, envVars.all);
 	const context = yield* buildTemplateContext(git, worktree.read, rest.state, rest.actor, run, vars, rest.stateDef.on);
 	const file = yield* renderFile(rest.stateDef, context);
 	return {
@@ -204380,14 +204871,12 @@ const startLspServer = () => gen(function* () {
 });
 //#endregion
 //#region src/visualize.html
-var visualize_default = "<!doctype html>\n<html lang=\"en\">\n  <head>\n    <meta charset=\"utf-8\" />\n    <meta name=\"viewport\" content=\"width=device-width, initial-scale=1\" />\n    <title>gtd · workflow visualizer</title>\n    <style>\n      :root {\n        --bg: #f4f6fa;\n        --surface: #ffffff;\n        --surface-2: #eef1f7;\n        --surface-3: #e6ebf3;\n        --border: #d9dee8;\n        --border-strong: #c2ccdb;\n        --text: #1a2233;\n        --text-dim: #55607a;\n        --text-faint: #8a93a6;\n        --accent: #2d6cdf;\n        --accent-soft: #e4edfd;\n        --human-bg: #fbeccd;\n        --human-fg: #7a5310;\n        --human-dot: #d99413;\n        --agent-bg: #e5e2fb;\n        --agent-fg: #463693;\n        --agent-dot: #6d5ce0;\n        --check-bg: #d3f0ef;\n        --check-fg: #0c524f;\n        --check-dot: #16a39d;\n        --engine-bg: #fbdfe4;\n        --engine-fg: #8a1f38;\n        --engine-dot: #d84a68;\n        --unknown-bg: #eef1f7;\n        --unknown-fg: #55607a;\n        --unknown-dot: #8a93a6;\n        --shadow: 0 1px 2px rgba(20, 30, 50, 0.06), 0 8px 28px rgba(20, 30, 50, 0.1);\n        --shadow-sm: 0 1px 2px rgba(20, 30, 50, 0.08);\n        --radius: 12px;\n        --mono:\n          ui-monospace, \"SF Mono\", \"SFMono-Regular\", Menlo, Consolas, \"Liberation Mono\", monospace;\n        --sans:\n          ui-sans-serif, system-ui, -apple-system, \"Segoe UI\", Roboto, Helvetica, Arial, sans-serif;\n        --dia-bg: #f7f9fc;\n      }\n      @media (prefers-color-scheme: dark) {\n        :root {\n          --bg: #0e1420;\n          --surface: #161d2b;\n          --surface-2: #1c2434;\n          --surface-3: #232c3e;\n          --border: #2b3547;\n          --border-strong: #3a465c;\n          --text: #e6ebf4;\n          --text-dim: #9aa6bd;\n          --text-faint: #6b7690;\n          --accent: #5b8def;\n          --accent-soft: #1b2740;\n          --human-bg: #3a2e12;\n          --human-fg: #f0c674;\n          --human-dot: #e0a83e;\n          --agent-bg: #26224a;\n          --agent-fg: #b6abf7;\n          --agent-dot: #8b7cf0;\n          --check-bg: #123433;\n          --check-fg: #68dcd4;\n          --check-dot: #2dc4bc;\n          --engine-bg: #3a1b24;\n          --engine-fg: #f2a3b3;\n          --engine-dot: #e05f7c;\n          --unknown-bg: #1c2434;\n          --unknown-fg: #9aa6bd;\n          --unknown-dot: #6b7690;\n          --shadow: 0 1px 2px rgba(0, 0, 0, 0.3), 0 12px 34px rgba(0, 0, 0, 0.45);\n          --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.35);\n          --dia-bg: #0b1018;\n        }\n      }\n      :root[data-theme=\"light\"] {\n        --bg: #f4f6fa;\n        --surface: #ffffff;\n        --surface-2: #eef1f7;\n        --surface-3: #e6ebf3;\n        --border: #d9dee8;\n        --border-strong: #c2ccdb;\n        --text: #1a2233;\n        --text-dim: #55607a;\n        --text-faint: #8a93a6;\n        --accent: #2d6cdf;\n        --accent-soft: #e4edfd;\n        --human-bg: #fbeccd;\n        --human-fg: #7a5310;\n        --human-dot: #d99413;\n        --agent-bg: #e5e2fb;\n        --agent-fg: #463693;\n        --agent-dot: #6d5ce0;\n        --check-bg: #d3f0ef;\n        --check-fg: #0c524f;\n        --check-dot: #16a39d;\n        --engine-bg: #fbdfe4;\n        --engine-fg: #8a1f38;\n        --engine-dot: #d84a68;\n        --unknown-bg: #eef1f7;\n        --unknown-fg: #55607a;\n        --unknown-dot: #8a93a6;\n        --shadow: 0 1px 2px rgba(20, 30, 50, 0.06), 0 8px 28px rgba(20, 30, 50, 0.1);\n        --shadow-sm: 0 1px 2px rgba(20, 30, 50, 0.08);\n        --dia-bg: #f7f9fc;\n      }\n      :root[data-theme=\"dark\"] {\n        --bg: #0e1420;\n        --surface: #161d2b;\n        --surface-2: #1c2434;\n        --surface-3: #232c3e;\n        --border: #2b3547;\n        --border-strong: #3a465c;\n        --text: #e6ebf4;\n        --text-dim: #9aa6bd;\n        --text-faint: #6b7690;\n        --accent: #5b8def;\n        --accent-soft: #1b2740;\n        --human-bg: #3a2e12;\n        --human-fg: #f0c674;\n        --human-dot: #e0a83e;\n        --agent-bg: #26224a;\n        --agent-fg: #b6abf7;\n        --agent-dot: #8b7cf0;\n        --check-bg: #123433;\n        --check-fg: #68dcd4;\n        --check-dot: #2dc4bc;\n        --engine-bg: #3a1b24;\n        --engine-fg: #f2a3b3;\n        --engine-dot: #e05f7c;\n        --unknown-bg: #1c2434;\n        --unknown-fg: #9aa6bd;\n        --unknown-dot: #6b7690;\n        --shadow: 0 1px 2px rgba(0, 0, 0, 0.3), 0 12px 34px rgba(0, 0, 0, 0.45);\n        --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.35);\n        --dia-bg: #0b1018;\n      }\n\n      * {\n        box-sizing: border-box;\n      }\n      html,\n      body {\n        max-width: 100%;\n        overflow-x: hidden;\n      }\n      body {\n        margin: 0;\n        background: var(--bg);\n        color: var(--text);\n        font-family: var(--sans);\n        font-size: 15px;\n        line-height: 1.55;\n        -webkit-font-smoothing: antialiased;\n      }\n      ::selection {\n        background: var(--accent);\n        color: #fff;\n      }\n      .wrap {\n        max-width: 1180px;\n        margin: 0 auto;\n        padding: 0 20px;\n      }\n\n      /* header */\n      header.top {\n        position: sticky;\n        top: 0;\n        z-index: 40;\n        background: color-mix(in srgb, var(--bg) 88%, transparent);\n        backdrop-filter: blur(10px);\n        border-bottom: 1px solid var(--border);\n      }\n      .top-inner {\n        display: flex;\n        align-items: center;\n        gap: 18px;\n        padding: 12px 20px;\n        max-width: 1180px;\n        margin: 0 auto;\n        flex-wrap: wrap;\n      }\n      .brand {\n        display: flex;\n        align-items: baseline;\n        gap: 10px;\n        margin-right: auto;\n      }\n      .brand .cmd {\n        font-family: var(--mono);\n        font-weight: 700;\n        font-size: 17px;\n        letter-spacing: -0.02em;\n      }\n      .brand .cmd b {\n        color: var(--accent);\n      }\n      .brand .sub {\n        font-size: 12px;\n        color: var(--text-faint);\n        letter-spacing: 0.04em;\n        text-transform: uppercase;\n      }\n      .summary {\n        font-size: 12.5px;\n        color: var(--text-dim);\n        display: flex;\n        gap: 10px;\n        flex-wrap: wrap;\n        align-items: center;\n      }\n      .summary .s-num {\n        font-family: var(--mono);\n        font-weight: 700;\n        color: var(--text);\n      }\n      .summary .sep {\n        color: var(--border-strong);\n      }\n      .theme-btn {\n        border: 1px solid var(--border);\n        background: var(--surface);\n        color: var(--text-dim);\n        border-radius: 8px;\n        width: 32px;\n        height: 32px;\n        cursor: pointer;\n        font-size: 14px;\n        display: grid;\n        place-items: center;\n      }\n      .theme-btn:hover {\n        color: var(--text);\n        border-color: var(--border-strong);\n      }\n      .theme-btn:focus-visible {\n        outline: 2px solid var(--accent);\n        outline-offset: 2px;\n      }\n\n      /* hero */\n      .hero {\n        padding: 40px 0 4px;\n      }\n      h1 {\n        font-size: clamp(26px, 4vw, 36px);\n        line-height: 1.08;\n        letter-spacing: -0.025em;\n        margin: 0 0 12px;\n        font-weight: 780;\n      }\n      h1 .mono {\n        font-family: var(--mono);\n        font-weight: 700;\n      }\n      .lede {\n        font-size: 16px;\n        color: var(--text-dim);\n        max-width: 70ch;\n        margin: 0;\n      }\n      .lede code {\n        font-family: var(--mono);\n        font-size: 0.88em;\n        background: var(--surface-2);\n        padding: 1px 6px;\n        border-radius: 5px;\n        color: var(--text);\n      }\n\n      /* section headers */\n      .sec-head {\n        display: flex;\n        align-items: baseline;\n        gap: 12px;\n        margin: 46px 0 4px;\n      }\n      .sec-head h2 {\n        font-size: 13px;\n        text-transform: uppercase;\n        letter-spacing: 0.12em;\n        color: var(--text-faint);\n        margin: 0;\n        font-weight: 700;\n      }\n      .sec-head .rule {\n        flex: 1;\n        height: 1px;\n        background: var(--border);\n      }\n\n      /* diagram */\n      .diagram-note {\n        font-size: 13px;\n        color: var(--text-dim);\n        margin: 16px 0 14px;\n        max-width: 78ch;\n      }\n      .diagram-note .mono {\n        font-family: var(--mono);\n      }\n      .dia-card {\n        background: var(--surface);\n        border: 1px solid var(--border);\n        border-radius: var(--radius);\n        box-shadow: var(--shadow-sm);\n        overflow: hidden;\n      }\n      .sm-card summary.h {\n        display: flex;\n        align-items: baseline;\n        justify-content: space-between;\n        cursor: pointer;\n        list-style: none;\n        padding: 14px 18px;\n        transition: background 0.12s ease;\n      }\n      .sm-card summary.h:hover {\n        background: var(--surface-2);\n      }\n      .sm-card[open] summary.h {\n        border-bottom: 1px solid var(--border);\n      }\n      .sm-card summary::-webkit-details-marker {\n        display: none;\n      }\n      .sm-card summary::after {\n        content: \"+\";\n        align-self: center;\n        color: var(--text-dim);\n        font-size: 18px;\n        font-weight: 700;\n        line-height: 1;\n        transform: translateY(-0.08em);\n        transition: color 0.15s ease;\n      }\n      .sm-card summary:hover::after {\n        color: var(--text);\n      }\n      .sm-card[open] summary::after {\n        content: \"\\2212\";\n      }\n      .dia-scroll {\n        position: relative;\n        overflow: hidden;\n        background: var(--dia-bg);\n        height: 460px;\n        cursor: grab;\n        touch-action: none;\n      }\n      .dia-scroll.pz-dragging {\n        cursor: grabbing;\n      }\n      .dia-scroll .mflow {\n        position: absolute;\n        top: 0;\n        left: 0;\n        padding: 18px 16px;\n        transform-origin: 0 0;\n      }\n      .dia-scroll .mflow svg {\n        max-width: none;\n        height: auto;\n        display: block;\n      }\n      .pz-controls {\n        position: absolute;\n        right: 12px;\n        bottom: 12px;\n        display: flex;\n        gap: 6px;\n        z-index: 5;\n      }\n      .pz-btn {\n        width: 30px;\n        height: 30px;\n        border-radius: 8px;\n        border: 1px solid var(--border);\n        background: var(--surface);\n        color: var(--text-dim);\n        cursor: pointer;\n        font-size: 15px;\n        font-family: var(--mono);\n        display: grid;\n        place-items: center;\n        box-shadow: var(--shadow-sm);\n        padding: 0;\n      }\n      .pz-btn:hover {\n        color: var(--text);\n        border-color: var(--border-strong);\n      }\n      .pz-btn:focus-visible {\n        outline: 2px solid var(--accent);\n        outline-offset: 2px;\n      }\n      .dia-msg {\n        padding: 22px 18px;\n        font-size: 13.5px;\n        color: var(--text-dim);\n      }\n      .dia-msg code {\n        font-family: var(--mono);\n        font-size: 12px;\n        background: var(--surface-2);\n        padding: 1px 6px;\n        border-radius: 5px;\n      }\n      .dia-src {\n        margin: 10px 0 0;\n        padding: 12px 14px;\n        background: var(--surface-2);\n        border-radius: 9px;\n        font-family: var(--mono);\n        font-size: 11.5px;\n        white-space: pre;\n        overflow-x: auto;\n        color: var(--text-dim);\n        max-height: 260px;\n      }\n      .state-content {\n        max-height: 340px;\n        white-space: pre-wrap;\n        word-break: break-word;\n      }\n\n      /* sub-machines */\n      .sm-grid {\n        display: grid;\n        grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));\n        gap: 14px;\n        margin-top: 18px;\n      }\n      .sm-def {\n        border: 1.5px dashed var(--border-strong);\n        border-radius: var(--radius);\n        background: var(--surface);\n        box-shadow: var(--shadow-sm);\n        overflow: hidden;\n      }\n      .sm-def .h {\n        padding: 13px 16px;\n        border-bottom: 1px solid var(--border);\n        background: var(--surface-2);\n      }\n      .sm-def .h .nm {\n        font-family: var(--mono);\n        font-weight: 700;\n        font-size: 15px;\n      }\n      .sm-def .h .pm {\n        font-family: var(--mono);\n        font-size: 12px;\n        color: var(--text-dim);\n        display: block;\n        margin-top: 3px;\n      }\n      .sm-def .h .pm b {\n        color: var(--accent);\n      }\n      .sm-def .body {\n        padding: 12px 16px 16px;\n        display: flex;\n        flex-wrap: wrap;\n        gap: 6px;\n      }\n      .muted-note {\n        color: var(--text-faint);\n        font-style: italic;\n        margin-top: 16px;\n      }\n      .sm-def .h {\n        display: flex;\n        align-items: baseline;\n        justify-content: space-between;\n        gap: 8px;\n      }\n      .sm-def .h .goto-sm {\n        font: inherit;\n        font-family: var(--mono);\n        font-size: 11px;\n        color: var(--accent);\n        background: none;\n        border: none;\n        cursor: pointer;\n        text-decoration: underline;\n        padding: 0;\n      }\n\n      /* current-state panel */\n      .current-panel {\n        background: var(--surface);\n        border: 1px solid var(--border);\n        border-radius: var(--radius);\n        box-shadow: var(--shadow-sm);\n        padding: 18px 20px 20px;\n        margin: 16px 0 34px;\n      }\n      .cur-head {\n        display: flex;\n        align-items: center;\n        gap: 10px;\n        flex-wrap: wrap;\n        cursor: pointer;\n      }\n      .cur-name {\n        font-family: var(--mono);\n        font-weight: 700;\n        font-size: 18px;\n        letter-spacing: -0.01em;\n      }\n      .cur-none {\n        color: var(--text-faint);\n        font-style: italic;\n      }\n      .edge.cur-matched {\n        border-color: var(--accent);\n        background: var(--accent-soft);\n      }\n      .cur-tag {\n        font-family: var(--mono);\n        font-size: 10.5px;\n        font-weight: 700;\n        color: var(--accent);\n        background: var(--surface);\n        border: 1px solid var(--accent);\n        padding: 1px 7px;\n        border-radius: 999px;\n        margin-left: auto;\n      }\n\n      /* pending-changes readout in the current-state panel */\n      .pending-list {\n        display: flex;\n        flex-direction: column;\n        gap: 3px;\n        font-family: var(--mono);\n        font-size: 12.5px;\n        margin-bottom: 14px;\n      }\n      .pending-list .pc {\n        display: flex;\n        gap: 9px;\n      }\n      .pending-list .st {\n        font-weight: 700;\n        width: 1ch;\n        flex: none;\n      }\n      .pending-list .path {\n        color: var(--text-dim);\n        word-break: break-all;\n      }\n      .pending-clean {\n        color: var(--text-faint);\n        font-style: italic;\n        font-size: 12.5px;\n        margin-bottom: 14px;\n      }\n\n      /* mermaid black-box / ghost node labels (rendered inside the SVG via htmlLabels) */\n      .sm-hint {\n        display: block;\n        margin-top: 2px;\n        font-size: 10.5px;\n        opacity: 0.72;\n        font-weight: 500;\n      }\n\n      /* the current-state highlight ring on a rendered SVG node/group box */\n      g.node.gtd-current {\n        filter: drop-shadow(0 0 6px var(--accent));\n      }\n      g.node.gtd-current > rect,\n      g.node.gtd-current > polygon,\n      g.node.gtd-current > circle,\n      g.node.gtd-current > ellipse,\n      g.node.gtd-current > path.basic {\n        stroke: var(--accent) !important;\n        stroke-width: 3px !important;\n      }\n\n      /* toolbar */\n      .toolbar {\n        display: flex;\n        gap: 12px;\n        align-items: center;\n        margin: 18px 0 22px;\n        flex-wrap: wrap;\n      }\n      .search {\n        flex: 1;\n        min-width: 200px;\n        position: relative;\n      }\n      .search input {\n        width: 100%;\n        font-family: var(--mono);\n        font-size: 14px;\n        padding: 10px 12px 10px 34px;\n        border-radius: 10px;\n        border: 1px solid var(--border);\n        background: var(--surface);\n        color: var(--text);\n      }\n      .search input:focus {\n        outline: none;\n        border-color: var(--accent);\n        box-shadow: 0 0 0 3px var(--accent-soft);\n      }\n      .search svg {\n        position: absolute;\n        left: 11px;\n        top: 50%;\n        transform: translateY(-50%);\n        color: var(--text-faint);\n      }\n      .chips {\n        display: flex;\n        gap: 6px;\n        flex-wrap: wrap;\n      }\n      .chip-btn {\n        font: inherit;\n        font-size: 12.5px;\n        padding: 7px 12px;\n        border-radius: 999px;\n        border: 1px solid var(--border);\n        background: var(--surface);\n        color: var(--text-dim);\n        cursor: pointer;\n      }\n      .chip-btn:hover {\n        border-color: var(--border-strong);\n        color: var(--text);\n      }\n      .chip-btn.on {\n        background: var(--accent);\n        border-color: var(--accent);\n        color: #fff;\n      }\n      .chip-btn:focus-visible {\n        outline: 2px solid var(--accent);\n        outline-offset: 2px;\n      }\n      .legend {\n        display: flex;\n        gap: 8px;\n        flex-wrap: wrap;\n      }\n      .legend .li {\n        display: inline-flex;\n        align-items: center;\n        gap: 6px;\n        font-size: 12.5px;\n        color: var(--text-dim);\n        cursor: pointer;\n        user-select: none;\n        padding: 5px 9px;\n        border-radius: 999px;\n        border: 1px solid var(--border);\n        background: var(--surface);\n      }\n      .legend .li:hover {\n        border-color: var(--border-strong);\n      }\n      .legend .li.off {\n        opacity: 0.4;\n      }\n      .legend .li:focus-visible {\n        outline: 2px solid var(--accent);\n        outline-offset: 2px;\n      }\n      .legend .li .dot {\n        width: 10px;\n        height: 10px;\n        border-radius: 3px;\n      }\n\n      /* groups + cards */\n      .group {\n        margin-bottom: 30px;\n      }\n      .group-head {\n        display: flex;\n        align-items: baseline;\n        gap: 10px;\n        margin: 0 0 12px;\n      }\n      .group-head h3 {\n        font-family: var(--mono);\n        font-size: 15px;\n        margin: 0;\n        letter-spacing: -0.01em;\n      }\n      .group-head .flow-tag {\n        font-family: var(--mono);\n        font-size: 11px;\n        padding: 2px 8px;\n        border-radius: 6px;\n        background: var(--surface-2);\n        color: var(--text-dim);\n        border: 1px solid var(--border);\n      }\n      .grid {\n        display: grid;\n        grid-template-columns: repeat(auto-fill, minmax(250px, 1fr));\n        gap: 12px;\n      }\n      .card {\n        text-align: left;\n        font: inherit;\n        color: var(--text);\n        cursor: pointer;\n        background: var(--surface);\n        border: 1px solid var(--border);\n        border-left: 4px solid var(--card-accent, var(--border));\n        border-radius: 10px;\n        padding: 13px 15px;\n        box-shadow: var(--shadow-sm);\n        transition:\n          transform 0.12s ease,\n          box-shadow 0.12s ease,\n          border-color 0.12s ease;\n        position: relative;\n        display: flex;\n        flex-direction: column;\n        gap: 8px;\n      }\n      .card:hover {\n        transform: translateY(-2px);\n        box-shadow: var(--shadow);\n      }\n      .card:focus-visible {\n        outline: 2px solid var(--accent);\n        outline-offset: 2px;\n      }\n      .card[data-actor=\"human\"] {\n        --card-accent: var(--human-dot);\n      }\n      .card[data-actor=\"agent\"] {\n        --card-accent: var(--agent-dot);\n      }\n      .card[data-actor=\"check\"] {\n        --card-accent: var(--check-dot);\n      }\n      .card[data-actor=\"commit\"] {\n        --card-accent: var(--engine-dot);\n      }\n      .card[data-actor=\"unknown\"] {\n        --card-accent: var(--unknown-dot);\n      }\n      .card .name {\n        font-family: var(--mono);\n        font-weight: 700;\n        font-size: 14.5px;\n        letter-spacing: -0.01em;\n        word-break: break-word;\n      }\n      .card .row {\n        display: flex;\n        align-items: center;\n        gap: 6px;\n        flex-wrap: wrap;\n      }\n      .card .init-tick {\n        position: absolute;\n        top: 11px;\n        right: 12px;\n        font-size: 10px;\n        font-family: var(--mono);\n        color: var(--accent);\n        background: var(--accent-soft);\n        padding: 1px 6px;\n        border-radius: 5px;\n        font-weight: 700;\n      }\n\n      .pill {\n        display: inline-flex;\n        align-items: center;\n        gap: 5px;\n        font-family: var(--mono);\n        font-size: 11px;\n        font-weight: 600;\n        padding: 2px 8px;\n        border-radius: 999px;\n      }\n      .pill.actor-human {\n        background: var(--human-bg);\n        color: var(--human-fg);\n      }\n      .pill.actor-agent {\n        background: var(--agent-bg);\n        color: var(--agent-fg);\n      }\n      .pill.actor-check {\n        background: var(--check-bg);\n        color: var(--check-fg);\n      }\n      .pill.actor-engine {\n        background: var(--engine-bg);\n        color: var(--engine-fg);\n      }\n      .pill.actor-unknown {\n        background: var(--unknown-bg);\n        color: var(--unknown-fg);\n      }\n      .pill .dot {\n        width: 7px;\n        height: 7px;\n        border-radius: 2px;\n      }\n      .pill.actor-human .dot {\n        background: var(--human-dot);\n      }\n      .pill.actor-agent .dot {\n        background: var(--agent-dot);\n      }\n      .pill.actor-check .dot {\n        background: var(--check-dot);\n      }\n      .pill.actor-engine .dot {\n        background: var(--engine-dot);\n      }\n      .pill.actor-unknown .dot {\n        background: var(--unknown-dot);\n      }\n      .kind {\n        font-family: var(--mono);\n        font-size: 11px;\n        padding: 2px 7px;\n        border-radius: 6px;\n        border: 1px solid var(--border-strong);\n        color: var(--text-dim);\n        background: var(--surface-2);\n      }\n      .flag {\n        font-family: var(--mono);\n        font-size: 10.5px;\n        padding: 1px 6px;\n        border-radius: 5px;\n        background: var(--accent-soft);\n        color: var(--accent);\n        font-weight: 600;\n        border: 1px solid color-mix(in srgb, var(--accent) 25%, transparent);\n      }\n\n      /* drawer */\n      .backdrop {\n        position: fixed;\n        inset: 0;\n        background: rgba(10, 16, 28, 0.5);\n        backdrop-filter: blur(2px);\n        opacity: 0;\n        pointer-events: none;\n        transition: opacity 0.22s ease;\n        z-index: 90;\n      }\n      .backdrop.open {\n        opacity: 1;\n        pointer-events: auto;\n      }\n      .drawer {\n        position: fixed;\n        top: 0;\n        right: 0;\n        height: 100%;\n        width: min(560px, 100%);\n        background: var(--surface);\n        border-left: 1px solid var(--border);\n        box-shadow: var(--shadow);\n        transform: translateX(100%);\n        transition: transform 0.26s cubic-bezier(0.22, 0.61, 0.36, 1);\n        z-index: 100;\n        display: flex;\n        flex-direction: column;\n      }\n      .drawer.open {\n        transform: translateX(0);\n      }\n      .drawer-head {\n        padding: 18px 22px 14px;\n        border-bottom: 1px solid var(--border);\n        border-top: 4px solid var(--card-accent, var(--accent));\n      }\n      .drawer-head .top {\n        display: flex;\n        align-items: flex-start;\n        gap: 12px;\n      }\n      .drawer-head h3 {\n        font-family: var(--mono);\n        font-size: 20px;\n        font-weight: 700;\n        margin: 0;\n        letter-spacing: -0.02em;\n        word-break: break-word;\n      }\n      .drawer-head .meta-row {\n        display: flex;\n        gap: 6px;\n        flex-wrap: wrap;\n        margin-top: 10px;\n      }\n      .close-x {\n        margin-left: auto;\n        border: 1px solid var(--border);\n        background: var(--surface-2);\n        color: var(--text-dim);\n        border-radius: 8px;\n        width: 30px;\n        height: 30px;\n        cursor: pointer;\n        flex: none;\n        font-size: 15px;\n      }\n      .close-x:hover {\n        color: var(--text);\n      }\n      .close-x:focus-visible {\n        outline: 2px solid var(--accent);\n        outline-offset: 2px;\n      }\n      .drawer-body {\n        overflow-y: auto;\n        padding: 20px 22px 40px;\n        flex: 1;\n      }\n      .field {\n        margin-bottom: 18px;\n      }\n      .field > .k {\n        font-size: 11px;\n        text-transform: uppercase;\n        letter-spacing: 0.09em;\n        color: var(--text-faint);\n        font-weight: 700;\n        margin-bottom: 7px;\n      }\n      .kv {\n        display: grid;\n        grid-template-columns: 88px 1fr;\n        gap: 4px 14px;\n        font-size: 13.5px;\n      }\n      .kv dt {\n        color: var(--text-faint);\n        font-size: 12px;\n      }\n      .kv dd {\n        margin: 0;\n        font-family: var(--mono);\n        font-size: 12.5px;\n        word-break: break-word;\n      }\n      .none {\n        color: var(--text-faint);\n        font-style: italic;\n        font-family: var(--sans);\n      }\n\n      .edges {\n        display: flex;\n        flex-direction: column;\n        gap: 8px;\n      }\n      .edge {\n        border: 1px solid var(--border);\n        border-radius: 9px;\n        padding: 10px 12px;\n        background: var(--surface-2);\n      }\n      .edge .er {\n        display: flex;\n        align-items: center;\n        gap: 8px;\n        flex-wrap: wrap;\n      }\n      .edge .pat {\n        font-family: var(--mono);\n        font-size: 12px;\n        font-weight: 700;\n        background: var(--surface);\n        border: 1px solid var(--border-strong);\n        padding: 2px 8px;\n        border-radius: 6px;\n        white-space: nowrap;\n      }\n      .edge .act {\n        font-size: 12.5px;\n        font-weight: 700;\n        color: var(--accent);\n      }\n      .edge .arr {\n        color: var(--text-faint);\n      }\n      .goto {\n        font: inherit;\n        font-family: var(--mono);\n        font-size: 12.5px;\n        font-weight: 700;\n        cursor: pointer;\n        border: 1px solid var(--card-accent, var(--accent));\n        background: transparent;\n        color: var(--card-accent, var(--accent));\n        padding: 2px 9px;\n        border-radius: 6px;\n      }\n      .goto:hover {\n        background: var(--card-accent, var(--accent));\n        color: #fff;\n      }\n      .goto:focus-visible {\n        outline: 2px solid var(--accent);\n        outline-offset: 2px;\n      }\n      .goto[data-actor=\"human\"] {\n        --card-accent: var(--human-dot);\n      }\n      .goto[data-actor=\"agent\"] {\n        --card-accent: var(--agent-dot);\n      }\n      .goto[data-actor=\"check\"] {\n        --card-accent: var(--check-dot);\n      }\n      .goto[data-actor=\"commit\"] {\n        --card-accent: var(--engine-dot);\n      }\n      .goto[data-actor=\"unknown\"] {\n        --card-accent: var(--unknown-dot);\n      }\n      .edge .em {\n        font-size: 12.5px;\n        color: var(--text-dim);\n        margin-top: 6px;\n        line-height: 1.45;\n      }\n      .incoming {\n        display: flex;\n        flex-wrap: wrap;\n        gap: 6px;\n      }\n\n      .flag-list {\n        display: flex;\n        flex-direction: column;\n        gap: 8px;\n      }\n      .flag-item {\n        display: flex;\n        gap: 9px;\n        font-size: 13px;\n        align-items: baseline;\n      }\n      .flag-item .fn {\n        font-family: var(--mono);\n        font-size: 11.5px;\n        font-weight: 700;\n        color: var(--accent);\n        flex: none;\n        padding: 1px 6px;\n        border-radius: 5px;\n        background: var(--accent-soft);\n      }\n      .flag-item .fd {\n        color: var(--text-dim);\n      }\n\n      /* vars */\n      .vars-grid {\n        display: flex;\n        flex-wrap: wrap;\n        gap: 8px;\n        margin-top: 16px;\n      }\n      .var-chip {\n        font-family: var(--mono);\n        font-size: 12px;\n        padding: 6px 10px;\n        border-radius: 8px;\n        border: 1px solid var(--border);\n        background: var(--surface);\n        box-shadow: var(--shadow-sm);\n      }\n      .var-chip b {\n        color: var(--accent);\n      }\n\n      footer {\n        border-top: 1px solid var(--border);\n        margin-top: 56px;\n        padding: 40px 0 72px;\n        color: var(--text-faint);\n        font-size: 13px;\n      }\n      footer code {\n        font-family: var(--mono);\n        background: var(--surface-2);\n        padding: 1px 6px;\n        border-radius: 5px;\n      }\n      footer .foot-lead {\n        margin: 0 0 14px;\n        padding-top: 16px;\n        color: var(--text-dim);\n      }\n      footer .foot-legend {\n        display: flex;\n        align-items: center;\n        gap: 8px;\n        flex-wrap: wrap;\n        padding-bottom: 16px;\n      }\n      footer .foot-chip {\n        font-family: var(--mono);\n        font-size: 12px;\n        padding: 3px 9px;\n        border-radius: 7px;\n        border: 1px solid var(--border);\n        background: var(--surface);\n        color: var(--text-dim);\n      }\n\n      .hidden {\n        display: none !important;\n      }\n      @media (prefers-reduced-motion: reduce) {\n        *,\n        *::before,\n        *::after {\n          transition: none !important;\n          animation: none !important;\n        }\n      }\n      @media (max-width: 640px) {\n        .brand .sub {\n          display: none;\n        }\n        .kv {\n          grid-template-columns: 74px 1fr;\n        }\n      }\n    </style>\n  </head>\n  <body>\n    <header class=\"top\">\n      <div class=\"top-inner\">\n        <div class=\"brand\">\n          <span class=\"cmd\"><b>gtd</b> · workflow visualizer</span>\n          <span class=\"sub\" id=\"brandSub\">read-only view</span>\n        </div>\n        <div class=\"summary\" id=\"summary\"></div>\n        <button\n          class=\"theme-btn\"\n          id=\"themeBtn\"\n          title=\"Toggle light/dark theme\"\n          aria-label=\"Toggle light/dark theme\"\n        >\n          ◐\n        </button>\n      </div>\n    </header>\n\n    <main class=\"wrap\" id=\"app\">\n      <section class=\"hero\">\n        <h1 id=\"heroTitle\">Loading workflow…</h1>\n        <p class=\"lede\" id=\"heroLede\">\n          Fetching <code>/workflow.json</code> from the local\n          <span class=\"mono\">gtd visualize</span> server.\n        </p>\n      </section>\n\n      <div id=\"content\" class=\"hidden\">\n        <div class=\"sec-head\">\n          <h2>Current state</h2>\n          <span class=\"rule\"></span>\n        </div>\n        <div class=\"current-panel hidden\" id=\"currentPanel\"></div>\n        <div id=\"varsSection\"></div>\n\n        <div class=\"sec-head\">\n          <h2>Main flow</h2>\n          <span class=\"rule\"></span>\n        </div>\n        <p class=\"diagram-note\" id=\"diaNote\"></p>\n        <div class=\"dia-card\">\n          <div class=\"dia-scroll\" id=\"diaScroll\"><div class=\"dia-msg\">Rendering diagram…</div></div>\n        </div>\n\n        <div class=\"sec-head\">\n          <h2>Sub-machines</h2>\n          <span class=\"rule\"></span>\n        </div>\n        <div id=\"smSection\"></div>\n\n        <div class=\"sec-head\">\n          <h2>State catalogue</h2>\n          <span class=\"rule\"></span>\n        </div>\n        <div class=\"toolbar\">\n          <div class=\"search\">\n            <svg\n              width=\"15\"\n              height=\"15\"\n              viewBox=\"0 0 24 24\"\n              fill=\"none\"\n              stroke=\"currentColor\"\n              stroke-width=\"2.4\"\n            >\n              <circle cx=\"11\" cy=\"11\" r=\"7\" />\n              <path d=\"m21 21-4.3-4.3\" />\n            </svg>\n            <input\n              id=\"search\"\n              type=\"search\"\n              placeholder=\"filter by name, actor, kind, file, mode, flag…\"\n              autocomplete=\"off\"\n              spellcheck=\"false\"\n              aria-label=\"Filter states\"\n            />\n          </div>\n          <div class=\"chips\" id=\"kindChips\"></div>\n          <div class=\"legend\" id=\"legend\"></div>\n        </div>\n        <div id=\"groups\"></div>\n      </div>\n    </main>\n\n    <div class=\"backdrop\" id=\"backdrop\"></div>\n    <aside\n      class=\"drawer\"\n      id=\"drawer\"\n      role=\"dialog\"\n      aria-modal=\"true\"\n      aria-label=\"State detail\"\n      tabindex=\"-1\"\n    ></aside>\n\n    <footer class=\"wrap\" id=\"footer\"></footer>\n\n    <script type=\"module\">\n      // ── theme ──────────────────────────────────────────────────────────────\n      const root = document.documentElement\n      const prefersDark = () => matchMedia(\"(prefers-color-scheme: dark)\").matches\n      const isDark = () => {\n        const t = root.getAttribute(\"data-theme\")\n        return t ? t === \"dark\" : prefersDark()\n      }\n      document.getElementById(\"themeBtn\").onclick = () => {\n        const next = isDark() ? \"light\" : \"dark\"\n        root.setAttribute(\"data-theme\", next)\n        reinitializeAndRenderAll()\n      }\n      // Follow the OS when the user hasn't made an explicit choice — an\n      // explicit `data-theme` override always wins over an OS flip.\n      matchMedia(\"(prefers-color-scheme: dark)\").addEventListener(\"change\", () => {\n        if (!root.getAttribute(\"data-theme\")) reinitializeAndRenderAll()\n      })\n\n      const esc = (s) =>\n        String(s).replace(\n          /[&<>\"']/g,\n          (c) => ({ \"&\": \"&amp;\", \"<\": \"&lt;\", \">\": \"&gt;\", '\"': \"&quot;\", \"'\": \"&#39;\" })[c],\n        )\n\n      // Actor metadata: color class, css-var prefix, mermaid classDef name, label.\n      const ACTOR = {\n        human: { cls: \"actor-human\", dot: \"human\", label: \"human\" },\n        agent: { cls: \"actor-agent\", dot: \"agent\", label: \"agent\" },\n        check: { cls: \"actor-check\", dot: \"check\", label: \"check\" },\n        commit: { cls: \"actor-engine\", dot: \"engine\", label: \"commit\" },\n        unknown: { cls: \"actor-unknown\", dot: \"unknown\", label: \"?\" },\n      }\n      // A commit state has no actor — treat it as the engine/commit colour.\n      const actorOf = (s) => s.actor || (s.kind === \"commit\" ? \"commit\" : \"unknown\")\n      const meta = (a) => ACTOR[a] || ACTOR.unknown\n\n      const FLAGS = {\n        initial:\n          \"The one initial state — an unrecognized HEAD (any non-gtd history) resolves here.\",\n        reviewEntry:\n          \"This state is a dedicated CLI entry point (e.g. `gtd review <ref>`) that starts a brand-new process.\",\n        fixEntry:\n          \"This state is the `gtd fix` entry point — a red suite drops into the fixing loop, a green suite is a no-op.\",\n        reviewWindow:\n          \"While resting here, gtd opens the review checkout window: HEAD is rewound to the review base so the whole diff surfaces as ordinary uncommitted changes.\",\n        reviewBase:\n          \"Anchors the incremental review diff base — its most-recent in-process commit is where the next reviewing turn and checkout window start.\",\n        answerGate:\n          \"Edge gate: a step is refused while any open question in the steering file is not answered with exactly one tick.\",\n        requireProgress:\n          \"Edge gate: refuses a work-free turn that only deletes the instructions file (unless it held a NOTHING ACTIONABLE sentinel).\",\n      }\n\n      // ── state ──────────────────────────────────────────────────────────────\n      let MODEL = null\n      let STATES = []\n      let byName = {}\n      let CURRENT = null\n      let lastCurrentSig = undefined\n      let mermaidMod = null\n\n      // Fetches `/state.json`, updates `CURRENT`, and reports whether the\n      // resolved body actually changed since the last call (compared on the\n      // full JSON so an edge's `matched` flag flipping counts as a change too).\n      async function refreshCurrent() {\n        let next = null\n        try {\n          const res = await fetch(\"/state.json\")\n          const body = res.ok ? await res.json() : {}\n          next = body && body.state ? body : null\n        } catch (e) {\n          next = null\n        }\n        const sig = JSON.stringify(next)\n        if (sig === lastCurrentSig) return false\n        lastCurrentSig = sig\n        CURRENT = next\n        return true\n      }\n\n      const actorFilter = new Set([\"human\", \"agent\", \"check\", \"commit\", \"unknown\"])\n      let kindFilter = \"all\"\n\n      // ── boot ─────────────────────────────────────────────────────────────\n      try {\n        const res = await fetch(\"/workflow.json\")\n        if (!res.ok) throw new Error(\"HTTP \" + res.status)\n        MODEL = await res.json()\n      } catch (e) {\n        document.getElementById(\"heroTitle\").textContent = \"Could not load workflow\"\n        document.getElementById(\"heroLede\").innerHTML =\n          \"Fetching <code>/workflow.json</code> failed: \" +\n          esc(e.message) +\n          '. This page must be served by <span class=\"mono\">gtd visualize</span>.'\n        throw e\n      }\n\n      // Resolved at page load, then re-polled every 3s (see `poll()` below) so\n      // advancing the process shows up without a manual refresh. Tolerates a\n      // 404/error (an older server) or an empty `{}` (no active process/not a repo).\n      await refreshCurrent()\n\n      STATES = MODEL.states || []\n      byName = Object.fromEntries(STATES.map((s) => [s.name, s]))\n\n      // ── header summary + hero ───────────────────────────────────────────\n      const counts = { human: 0, agent: 0, check: 0, commit: 0, unknown: 0 }\n      STATES.forEach((s) => {\n        counts[actorOf(s)]++\n      })\n      const nGroups = (MODEL.groups || []).length\n      const cnt = (a) =>\n        counts[a] ? `<span><span class=\"s-num\">${counts[a]}</span> ${meta(a).label}</span>` : \"\"\n      document.getElementById(\"summary\").innerHTML = [\n        `<span><span class=\"s-num\">${STATES.length}</span> states</span>`,\n        `<span><span class=\"s-num\">${nGroups}</span> sub-machine${nGroups === 1 ? \"\" : \"s\"}</span>`,\n        `<span class=\"sep\">·</span>`,\n        cnt(\"human\"),\n        cnt(\"agent\"),\n        cnt(\"check\"),\n        cnt(\"commit\"),\n        cnt(\"unknown\"),\n      ]\n        .filter(Boolean)\n        .join(\" \")\n\n      document.getElementById(\"heroTitle\").innerHTML = `GTD workflow visualization`\n      document.getElementById(\"heroLede\").innerHTML =\n        `Rendered live from your workflow. The initial state is ` +\n        `<code>${esc(MODEL.initial)}</code>. Click any state — in the diagram, a sub-machine chip, ` +\n        `or the catalogue — to open its full definition, walk its outgoing edges, and see what routes into it.`\n      document.getElementById(\"content\").classList.remove(\"hidden\")\n\n      document.getElementById(\"footer\").innerHTML =\n        `<p class=\"foot-lead\">Read-only view served by <code>gtd visualize</code>.</p>` +\n        `<div class=\"foot-legend\">` +\n        `<span class=\"foot-chip\">([message])</span>` +\n        `<span class=\"foot-chip\">[prompt]</span>` +\n        `<span class=\"foot-chip\">{{script}}</span>` +\n        `<span class=\"foot-chip\">[[commit]]</span>` +\n        `<span>— node shape = content kind; colour = actor.</span>` +\n        `</div>`\n\n      // ── pill helper ────────────────────────────────────────────────────\n      const pill = (a) =>\n        `<span class=\"pill ${meta(a).cls}\"><span class=\"dot\"></span>${meta(a).label}</span>`\n\n      // ── mermaid source generation ──────────────────────────────────────\n      // Safe, stable node ids (state names can contain hyphens etc.), with a\n      // reverse lookup — needed to map a rendered SVG node's id back to its\n      // state name when wiring clicks (see `nodeIdOf`/`wire*Clicks` below).\n      const idFor = (() => {\n        const map = new Map()\n        const rev = new Map()\n        const fn = (name) => {\n          if (!map.has(name)) {\n            const id = \"n\" + map.size\n            map.set(name, id)\n            rev.set(id, name)\n          }\n          return map.get(name)\n        }\n        fn.nameOf = (id) => rev.get(id)\n        return fn\n      })()\n      const groupBoxId = (i) => \"g\" + i\n      const groupIndexOf = (name) => (MODEL.groups || []).findIndex((g) => g.name === name)\n      const shapeFor = (kind, label) => {\n        const l = `\"${label.replace(/\"/g, \"&quot;\")}\"`\n        switch (kind) {\n          case \"message\":\n            return `([\"${label.replace(/\"/g, \"&quot;\")}\"])`\n          case \"prompt\":\n            return `[${l}]`\n          case \"script\":\n            return `{{${l}}}`\n          case \"commit\":\n            return `[[${l}]]`\n          default:\n            return `[${l}]`\n        }\n      }\n      const mlabel = (s) => `\"${String(s).replace(/\"/g, \"&quot;\").replace(/\\|/g, \"&#124;\")}\"`\n      /**\n       * The mermaid `classDef` lines for actor/ghost node fills, chosen per\n       * theme so dark mode doesn't render washed-out light pastels.\n       */\n      function classDefs(dark) {\n        return [\n          dark\n            ? \"classDef human fill:#3a2e12,stroke:#e0a83e,color:#f0c674;\"\n            : \"classDef human fill:#fbeccd,stroke:#d99413,color:#5a3d0a;\",\n          dark\n            ? \"classDef agent fill:#26224a,stroke:#8b7cf0,color:#b6abf7;\"\n            : \"classDef agent fill:#e5e2fb,stroke:#6d5ce0,color:#3a2c85;\",\n          dark\n            ? \"classDef check fill:#123433,stroke:#2dc4bc,color:#68dcd4;\"\n            : \"classDef check fill:#d3f0ef,stroke:#16a39d,color:#0c524f;\",\n          dark\n            ? \"classDef commit fill:#3a1b24,stroke:#e05f7c,color:#f2a3b3;\"\n            : \"classDef commit fill:#fbdfe4,stroke:#d84a68,color:#8a1f38;\",\n          dark\n            ? \"classDef unknown fill:#1c2434,stroke:#3a465c,color:#9aa6bd,stroke-dasharray:4 3;\"\n            : \"classDef unknown fill:#eef1f7,stroke:#c2ccdb,color:#55607a,stroke-dasharray:4 3;\",\n          // Sub-machine invocation: a muted slate box (not one of the actor\n          // colours) so it still reads as its own distinct \"black-box\" kind,\n          // without the harsh opaque-black fill clashing with a light theme.\n          dark\n            ? \"classDef submachine fill:#2a3142,stroke:#5a6b8c,color:#dbe4f5,font-weight:700;\"\n            : \"classDef submachine fill:#e4e9f2,stroke:#8695b3,color:#2a3142,font-weight:700;\",\n          // A muted, dashed ghost node standing in for a target OUTSIDE the\n          // current diagram (a sub-machine diagram's external edge).\n          dark\n            ? \"classDef external fill:#1c2434,stroke:#3a465c,color:#9aa6bd,stroke-dasharray:5 4;\"\n            : \"classDef external fill:#eef1f7,stroke:#c2ccdb,color:#55607a,stroke-dasharray:5 4;\",\n        ]\n      }\n\n      /**\n       * Build one flowchart's mermaid source over `states` (a diagram scope):\n       * the whole machine for the main flow (`opts.scope` unset), or one\n       * sub-machine's own member states (`opts.scope` = that group's name).\n       * A member state whose innermost group differs from `opts.scope`\n       * collapses into a black box for ITS group (handles a sub-machine\n       * nested inside another); a target outside `states` entirely renders as\n       * a muted, dashed ghost node instead (only possible in a sub-machine\n       * diagram — the main flow's `states` is every state, so nothing is ever\n       * \"outside\" it).\n       */\n      function buildFlowSrc(states, opts) {\n        const scope = opts && opts.scope\n        const inSet = new Set(states.map((s) => s.name))\n        const lines = [\"flowchart TD\"]\n\n        const unitOf = (name) => {\n          const s = byName[name]\n          if (s && s.group && s.group !== scope) return { kind: \"box\", group: s.group }\n          return { kind: \"node\", name }\n        }\n        const unitId = (name) => {\n          const u = unitOf(name)\n          return u.kind === \"box\" ? groupBoxId(groupIndexOf(u.group)) : idFor(name)\n        }\n\n        const emittedNodes = new Set()\n        const emittedBoxes = new Set()\n        const emittedGhosts = new Set()\n        const nodeLine = (s) => `  ${idFor(s.name)}${shapeFor(s.kind, s.name)}:::${actorOf(s)}`\n        const boxLine = (g, i) =>\n          `  ${groupBoxId(i)}[\"${esc(g.name)}<br/><span class='sm-hint'>▸ ${g.states.length} state${\n            g.states.length === 1 ? \"\" : \"s\"\n          }</span>\"]:::submachine`\n        const ghostLine = (s) => `  e${idFor(s.name)}${shapeFor(s.kind, s.name)}:::external`\n\n        states.forEach((s) => {\n          const u = unitOf(s.name)\n          if (u.kind === \"node\") {\n            if (emittedNodes.has(s.name)) return\n            emittedNodes.add(s.name)\n            lines.push(nodeLine(s))\n          } else if (!emittedBoxes.has(u.group)) {\n            emittedBoxes.add(u.group)\n            const i = groupIndexOf(u.group)\n            if (i >= 0) lines.push(boxLine(MODEL.groups[i], i))\n          }\n        })\n\n        // Edges within this diagram's own state set, collapsed through box\n        // units, deduped, and label-dropped when several patterns land on the\n        // same box-level edge (a black box hides which one specifically).\n        const solid = new Map()\n        const dashed = new Map()\n        const addEdge = (map, from, to, label) => {\n          if (from === to) return\n          const key = from + \" \" + to\n          if (!map.has(key)) map.set(key, [])\n          map.get(key).push(label)\n        }\n        states.forEach((s) => {\n          ;(s.on || []).forEach((e) => {\n            if (!inSet.has(e.to) || !byName[e.to]) return\n            addEdge(solid, unitId(s.name), unitId(e.to), e.action || e.pattern)\n          })\n          if (s.retry && inSet.has(s.retry.otherwise)) {\n            addEdge(dashed, unitId(s.name), unitId(s.retry.otherwise), \"retry ×\" + s.retry.max)\n          }\n        })\n        // Ghost edges to a target entirely outside this diagram's state set\n        // (only fires for a sub-machine diagram — the main flow's set is\n        // every state, so nothing is ever \"outside\" it).\n        states.forEach((s) => {\n          ;(s.on || []).forEach((e) => {\n            if (inSet.has(e.to) || !byName[e.to]) return\n            const target = byName[e.to]\n            if (!emittedGhosts.has(e.to)) {\n              emittedGhosts.add(e.to)\n              lines.push(ghostLine(target))\n            }\n            lines.push(`  ${idFor(s.name)} -->|${mlabel(e.action || e.pattern)}| e${idFor(e.to)}`)\n          })\n          if (s.retry && byName[s.retry.otherwise] && !inSet.has(s.retry.otherwise)) {\n            const target = byName[s.retry.otherwise]\n            if (!emittedGhosts.has(s.retry.otherwise)) {\n              emittedGhosts.add(s.retry.otherwise)\n              lines.push(ghostLine(target))\n            }\n            lines.push(\n              `  ${idFor(s.name)} -.->|${mlabel(\"retry ×\" + s.retry.max)}| e${idFor(s.retry.otherwise)}`,\n            )\n          }\n        })\n\n        solid.forEach((labels, key) => {\n          const [from, to] = key.split(\" \")\n          const label = labels.length === 1 ? mlabel(labels[0]) : null\n          lines.push(`  ${from} -->${label ? \"|\" + label + \"|\" : \"\"} ${to}`)\n        })\n        dashed.forEach((labels, key) => {\n          const [from, to] = key.split(\" \")\n          const label = labels.length === 1 ? mlabel(labels[0]) : null\n          lines.push(`  ${from} -.->${label ? \"|\" + label + \"|\" : \"\"} ${to}`)\n        })\n\n        lines.push(...classDefs(isDark()))\n        return lines.join(\"\\n\")\n      }\n\n      document.getElementById(\"diaNote\").innerHTML =\n        `Every state as a node — shape is the content kind, colour is the actor. Each edge is an ` +\n        `<span class=\"mono\">on</span> pattern (first match wins); dashed edges are ` +\n        `<span class=\"mono\">retry</span> redirects. A sub-machine invocation collapses into a single ` +\n        `dark box (click it to jump to its own diagram below); an edge label is dropped when several ` +\n        `patterns collapse onto the same box-to-box edge. Scroll/pinch or drag to pan and zoom; use the ` +\n        `<span class=\"mono\">+</span>/<span class=\"mono\">−</span>/<span class=\"mono\">⤢</span> controls in the corner.`\n\n      // ── diagram render (theme-aware, offline-tolerant) ─────────────────\n      async function loadMermaid() {\n        if (mermaidMod) return mermaidMod\n        const m = await import(\"https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs\")\n        mermaidMod = m.default\n        return mermaidMod\n      }\n\n      const renderSeqByBase = new Map()\n      const nextSeq = (base) => {\n        const n = (renderSeqByBase.get(base) || 0) + 1\n        renderSeqByBase.set(base, n)\n        return n\n      }\n\n      /** Render `src` into `host` via mermaid, guarding against a stale (superseded) render; falls back to a readable error + raw source on failure. Returns the mermaid render id used (so the caller can wire clicks/highlight against ITS OWN node ids), or `null` if nothing rendered. */\n      async function renderInto(host, src, renderIdBase) {\n        const seq = nextSeq(renderIdBase)\n        let mermaid\n        try {\n          mermaid = await loadMermaid()\n        } catch (e) {\n          host.innerHTML =\n            `<div class=\"dia-msg\">Could not load the Mermaid renderer (offline?). ` +\n            `The workflow is still fully browsable below. Diagram source:` +\n            `<pre class=\"dia-src\">${esc(src)}</pre></div>`\n          return null\n        }\n        if (seq !== renderSeqByBase.get(renderIdBase)) return null\n        const renderId = renderIdBase + seq\n        try {\n          const { svg } = await mermaid.render(renderId, src)\n          if (seq !== renderSeqByBase.get(renderIdBase)) return null\n          host.innerHTML = `<div class=\"mflow\">${svg}</div>`\n          return renderId\n        } catch (e) {\n          host.innerHTML =\n            `<div class=\"dia-msg\">Diagram render failed: ${esc(e.message)}. ` +\n            `Diagram source:<pre class=\"dia-src\">${esc(src)}</pre></div>`\n          return null\n        }\n      }\n\n      // Every live diagram (main + one per sub-machine) — re-rendered as a\n      // group on every theme toggle (replaces the old single DIAGRAM_SRC).\n      // `build` is a thunk (not a fixed string) because the diagram source\n      // embeds theme-dependent classDefs — it must be re-emitted fresh on\n      // every re-render, not cached from first render.\n      const diagrams = []\n      function registerDiagram(host, build, renderIdBase, onRendered, highlight) {\n        diagrams.push({ host, build, renderIdBase, onRendered, highlight, lastRenderId: null })\n      }\n      async function renderAllDiagrams() {\n        for (const d of diagrams) {\n          const renderId = await renderInto(d.host, d.build(), d.renderIdBase)\n          if (renderId) d.lastRenderId = renderId\n          if (renderId && d.onRendered) d.onRendered(renderId, d.host)\n        }\n      }\n      async function reinitializeAndRenderAll() {\n        const mermaid = await loadMermaid().catch(() => null)\n        if (mermaid) {\n          const dark = isDark()\n          mermaid.initialize({\n            startOnLoad: false,\n            theme: \"base\",\n            securityLevel: \"strict\",\n            flowchart: { useMaxWidth: false, htmlLabels: true },\n            themeVariables: {\n              fontFamily: \"ui-monospace, Menlo, monospace\",\n              fontSize: \"12.5px\",\n              lineColor: dark ? \"#6b7690\" : \"#8a93a6\",\n              primaryBorderColor: dark ? \"#3a465c\" : \"#c2ccdb\",\n              tertiaryColor: dark ? \"#1c2434\" : \"#f0f3f8\",\n              mainBkg: dark ? \"#232c3e\" : \"#ffffff\",\n              clusterBkg: dark ? \"#1c2434\" : \"#f0f3f8\",\n              clusterBorder: dark ? \"#3a465c\" : \"#c2ccdb\",\n              titleColor: dark ? \"#e6ebf4\" : \"#1a2233\",\n              nodeTextColor: dark ? \"#e6ebf4\" : \"#1a2233\",\n              textColor: dark ? \"#e6ebf4\" : \"#1a2233\",\n              edgeLabelBackground: dark ? \"#161d2b\" : \"#f4f6fa\",\n            },\n          })\n        }\n        await renderAllDiagrams()\n      }\n\n      // ── click wiring + current-state highlight (post-render — mermaid's own\n      // `click` callbacks are disabled by securityLevel:\"strict\") ──────────\n      // A rendered node group's `id` is `${renderId}-flowchart-${ourNodeId}-<n>`\n      // (verified against mermaid@11's actual output) — strip that wrapper to\n      // recover the id we generated the diagram with.\n      function nodeIdOf(el, renderId) {\n        const prefix = renderId + \"-flowchart-\"\n        if (!el.id || !el.id.startsWith(prefix)) return null\n        const m = /^(.+)-\\d+$/.exec(el.id.slice(prefix.length))\n        return m ? m[1] : null\n      }\n      const nodeGroupsOf = (host) => [...host.querySelectorAll(\"g.node\")]\n\n      function scrollToSubmachine(i) {\n        const el = document.getElementById(\"sm-\" + i)\n        if (!el) return\n        el.open = true\n        el.scrollIntoView({ behavior: \"smooth\", block: \"start\" })\n      }\n      function navigateTo(name) {\n        const s = byName[name]\n        if (s && s.group) {\n          const gi = groupIndexOf(s.group)\n          if (gi >= 0) return scrollToSubmachine(gi)\n        }\n        openDrawer(name)\n      }\n\n      function applyCurrentHighlight(renderId, host, mode, gi) {\n        if (!CURRENT || !CURRENT.state) return\n        const wantId =\n          mode === \"main\"\n            ? CURRENT.group\n              ? groupBoxId(groupIndexOf(CURRENT.group))\n              : idFor(CURRENT.state)\n            : CURRENT.group === MODEL.groups[gi].name\n              ? idFor(CURRENT.state)\n              : null\n        if (wantId === null) return\n        nodeGroupsOf(host).forEach((el) => {\n          if (nodeIdOf(el, renderId) === wantId) el.classList.add(\"gtd-current\")\n        })\n      }\n\n      // Re-applies the current-state highlight to every already-rendered\n      // diagram, without re-running mermaid — used by the poll loop below.\n      function repaintHighlights() {\n        for (const d of diagrams) {\n          nodeGroupsOf(d.host).forEach((el) => el.classList.remove(\"gtd-current\"))\n          if (d.lastRenderId && d.highlight) {\n            applyCurrentHighlight(d.lastRenderId, d.host, d.highlight.mode, d.highlight.gi)\n          }\n        }\n      }\n\n      function wireMainDiagramClicks(renderId, host) {\n        nodeGroupsOf(host).forEach((el) => {\n          const rawId = nodeIdOf(el, renderId)\n          if (!rawId) return\n          el.classList.add(\"clickable\")\n          el.style.cursor = \"pointer\"\n          if (rawId[0] === \"g\") {\n            el.onclick = () => scrollToSubmachine(Number(rawId.slice(1)))\n          } else {\n            const name = idFor.nameOf(rawId)\n            if (name) el.onclick = () => openDrawer(name)\n          }\n        })\n        applyCurrentHighlight(renderId, host, \"main\")\n        attachPanZoom(host)\n      }\n\n      function wireSubmachineDiagramClicks(renderId, host, gi) {\n        nodeGroupsOf(host).forEach((el) => {\n          const rawId = nodeIdOf(el, renderId)\n          if (!rawId) return\n          el.classList.add(\"clickable\")\n          el.style.cursor = \"pointer\"\n          if (rawId[0] === \"g\") {\n            el.onclick = () => scrollToSubmachine(Number(rawId.slice(1)))\n          } else if (rawId[0] === \"e\") {\n            const name = idFor.nameOf(rawId.slice(1))\n            if (name) el.onclick = () => navigateTo(name)\n          } else {\n            const name = idFor.nameOf(rawId)\n            if (name) el.onclick = () => openDrawer(name)\n          }\n        })\n        applyCurrentHighlight(renderId, host, \"submachine\", gi)\n        attachPanZoom(host)\n      }\n\n      // ── diagram pan & zoom (hand-rolled — no pan-zoom dependency, see plan) ──\n      // `host` is a `.dia-scroll` element whose content mermaid just replaced\n      // wholesale (`renderInto`'s `host.innerHTML = ...`), so old listeners on\n      // its previous children are already gone — this re-creates the control\n      // cluster and re-attaches fresh listeners on every render, never\n      // accumulating stale ones.\n      const REDUCED_MOTION = matchMedia(\"(prefers-reduced-motion: reduce)\").matches\n      const clampScale = (s) => Math.min(3, Math.max(0.4, s))\n\n      function attachPanZoom(host) {\n        const flow = host.querySelector(\".mflow\")\n        const svg = flow && flow.querySelector(\"svg\")\n        if (!flow || !svg) return\n\n        const controls = document.createElement(\"div\")\n        controls.className = \"pz-controls\"\n        controls.innerHTML =\n          `<button class=\"pz-btn\" data-act=\"in\" title=\"Zoom in\" aria-label=\"Zoom in\">+</button>` +\n          `<button class=\"pz-btn\" data-act=\"out\" title=\"Zoom out\" aria-label=\"Zoom out\">−</button>` +\n          `<button class=\"pz-btn\" data-act=\"fit\" title=\"Fit to width\" aria-label=\"Fit to width\">⤢</button>`\n        host.appendChild(controls)\n\n        const box = svg.getBBox ? svg.getBBox() : { width: 0, height: 0 }\n        const naturalWidth = box.width || svg.clientWidth || 1\n        const naturalHeight = box.height || svg.clientHeight || 1\n\n        const state = { scale: 1, tx: 0, ty: 0 }\n        const apply = () => {\n          flow.style.transform = `translate(${state.tx}px, ${state.ty}px) scale(${state.scale})`\n        }\n        // Fit-to-width, capped at 1× so a small workflow renders at its\n        // natural size (the pre-pan/zoom default) instead of being blown up.\n        const fit = () => {\n          const r = host.getBoundingClientRect()\n          state.scale = clampScale(Math.min(1, Math.max(r.width - 32, 40) / naturalWidth))\n          state.tx = (r.width - naturalWidth * state.scale) / 2\n          state.ty = (r.height - naturalHeight * state.scale) / 2\n          apply()\n        }\n        const zoomBy = (factor, cx, cy) => {\n          const r = host.getBoundingClientRect()\n          const px = cx == null ? r.width / 2 : cx\n          const py = cy == null ? r.height / 2 : cy\n          const next = clampScale(state.scale * factor)\n          const ratio = next / state.scale\n          state.tx = px - (px - state.tx) * ratio\n          state.ty = py - (py - state.ty) * ratio\n          state.scale = next\n          apply()\n        }\n        // Animate only a button-triggered zoom/fit (an explicit, discrete\n        // action) — wheel/drag stay instant so the transform tracks the\n        // cursor/finger with no lag. Skipped entirely under\n        // prefers-reduced-motion.\n        const animated = (fn) => {\n          if (REDUCED_MOTION) return fn()\n          flow.style.transition = \"transform 0.18s ease\"\n          fn()\n          flow.addEventListener(\"transitionend\", () => (flow.style.transition = \"\"), {\n            once: true,\n          })\n        }\n        fit()\n\n        host.addEventListener(\n          \"wheel\",\n          (e) => {\n            e.preventDefault()\n            flow.style.transition = \"none\"\n            const r = host.getBoundingClientRect()\n            zoomBy(e.deltaY < 0 ? 1.12 : 1 / 1.12, e.clientX - r.left, e.clientY - r.top)\n          },\n          { passive: false },\n        )\n\n        // Drag-to-pan: a small movement threshold before a pointerdown counts\n        // as a drag (rather than a click), and — once it does — the resulting\n        // synthetic `click` is swallowed so dragging over a node never opens\n        // its drawer. Pointer capture is deferred until that threshold is\n        // actually crossed: a captured pointer retargets its WHOLE mouse-event\n        // sequence (including the eventual `click`) to `host`, so capturing\n        // eagerly on every pointerdown would silently break a plain click on\n        // any node (or the zoom/fit buttons) — not just an actual drag.\n        let drag = null\n        host.addEventListener(\"pointerdown\", (e) => {\n          if (e.button !== 0 || e.target.closest(\".pz-controls\")) return\n          drag = { x: e.clientX, y: e.clientY, tx: state.tx, ty: state.ty, moved: false }\n          flow.style.transition = \"none\"\n        })\n        host.addEventListener(\"pointermove\", (e) => {\n          if (!drag) return\n          const dx = e.clientX - drag.x\n          const dy = e.clientY - drag.y\n          if (!drag.moved && Math.hypot(dx, dy) > 4) {\n            drag.moved = true\n            host.classList.add(\"pz-dragging\")\n            host.setPointerCapture(e.pointerId)\n          }\n          if (drag.moved) {\n            state.tx = drag.tx + dx\n            state.ty = drag.ty + dy\n            apply()\n          }\n        })\n        const endDrag = () => {\n          if (!drag) return\n          if (drag.moved) {\n            host.classList.remove(\"pz-dragging\")\n            host.addEventListener(\n              \"click\",\n              (ev) => {\n                ev.stopPropagation()\n                ev.preventDefault()\n              },\n              { capture: true, once: true },\n            )\n          }\n          drag = null\n        }\n        host.addEventListener(\"pointerup\", endDrag)\n        host.addEventListener(\"pointercancel\", endDrag)\n\n        controls.querySelector('[data-act=\"in\"]').onclick = (e) => {\n          e.stopPropagation()\n          animated(() => zoomBy(1.25))\n        }\n        controls.querySelector('[data-act=\"out\"]').onclick = (e) => {\n          e.stopPropagation()\n          animated(() => zoomBy(1 / 1.25))\n        }\n        controls.querySelector('[data-act=\"fit\"]').onclick = (e) => {\n          e.stopPropagation()\n          animated(fit)\n        }\n\n        // Exposed so a collapsed sub-machine `<details>` panel can re-fit once\n        // it's actually opened (its content renders at zero width while hidden).\n        host.__pz = { fit, zoomBy }\n      }\n\n      // ── main flow ────────────────────────────────────────────────────────\n      registerDiagram(\n        document.getElementById(\"diaScroll\"),\n        () => buildFlowSrc(STATES, {}),\n        \"gtdmain\",\n        wireMainDiagramClicks,\n        { mode: \"main\" },\n      )\n\n      // ── sub-machines panel — one real mermaid diagram per invocation ─────\n      ;(function renderSubmachines() {\n        const el = document.getElementById(\"smSection\")\n        const groups = MODEL.groups || []\n        if (!groups.length) {\n          el.innerHTML = `<p class=\"muted-note\">This workflow declares no sub-machines.</p>`\n          return\n        }\n        el.innerHTML = \"\"\n        groups.forEach((g, i) => {\n          const card = document.createElement(\"details\")\n          card.className = \"dia-card sm-card\"\n          card.id = \"sm-\" + i\n          card.style.marginBottom = \"16px\"\n          if (CURRENT && CURRENT.group === g.name) card.open = true\n          card.innerHTML =\n            `<summary class=\"h\"><span class=\"nm\">${esc(g.name)} · instantiates <b>${esc(g.submachine)}</b></span></summary>` +\n            `<div class=\"dia-scroll\" id=\"smDia${i}\"><div class=\"dia-msg\">Rendering diagram…</div></div>`\n          el.appendChild(card)\n\n          const members = (g.states || []).map((n) => byName[n]).filter(Boolean)\n          registerDiagram(\n            card.querySelector(`#smDia${i}`),\n            () => buildFlowSrc(members, { scope: g.name }),\n            \"gtdsm\" + i + \"-\",\n            (renderId, host) => wireSubmachineDiagramClicks(renderId, host, i),\n            { mode: \"submachine\", gi: i },\n          )\n          // A collapsed <details> renders its content at zero width, so the\n          // pan/zoom \"fit\" computed while hidden is wrong — recompute it once\n          // the panel is actually opened.\n          card.addEventListener(\"toggle\", () => {\n            if (!card.open) return\n            const host = card.querySelector(`#smDia${i}`)\n            if (host && host.__pz) host.__pz.fit()\n          })\n        })\n      })()\n\n      // ── vars ─────────────────────────────────────────────────────────────\n      ;(function renderVars() {\n        const vars = MODEL.vars || {}\n        const keys = Object.keys(vars)\n        if (!keys.length) return\n        const el = document.getElementById(\"varsSection\")\n        el.innerHTML =\n          `<div class=\"sec-head\"><h2>Workflow variables</h2><span class=\"rule\"></span></div>` +\n          `<div class=\"vars-grid\">${keys\n            .map((k) => `<span class=\"var-chip\"><b>${esc(k)}</b> = ${esc(vars[k])}</span>`)\n            .join(\"\")}</div>`\n      })()\n\n      // ── current-state panel ─────────────────────────────────────────────\n      // Status-letter colour reuses existing actor tokens rather than adding new\n      // theme variables: A (added) reads as the check colour, M (modified) as\n      // the accent, D (deleted) as the engine/commit colour.\n      const PENDING_STATUS_COLOR = {\n        A: \"var(--check-fg)\",\n        M: \"var(--accent)\",\n        D: \"var(--engine-fg)\",\n      }\n      function pendingListHtml(pending) {\n        if (!pending || !pending.length) {\n          return `<p class=\"pending-clean\">working tree clean</p>`\n        }\n        return (\n          `<div class=\"pending-list\">` +\n          pending\n            .map(\n              (c) =>\n                `<div class=\"pc\"><span class=\"st\" style=\"color:${PENDING_STATUS_COLOR[c.status] || \"var(--text-dim)\"}\">${esc(c.status)}</span><span class=\"path\">${esc(c.path)}</span></div>`,\n            )\n            .join(\"\") +\n          `</div>`\n        )\n      }\n      function renderCurrentPanel() {\n        const panel = document.getElementById(\"currentPanel\")\n        if (!CURRENT || !CURRENT.state) {\n          panel.classList.add(\"hidden\")\n          return\n        }\n        panel.classList.remove(\"hidden\")\n        const a = CURRENT.actor\n        const edgeRow = (pattern, to, matched, retryOf, action) => {\n          const t = byName[to]\n          return (\n            `<div class=\"edge${matched ? \" cur-matched\" : \"\"}\"><div class=\"er\">` +\n            `${action ? `<span class=\"act\">${esc(action)}</span>` : \"\"}` +\n            `<span class=\"pat\">${retryOf ? \"after \" + esc(retryOf) + \" tries\" : \"if \" + esc(pattern)}</span>` +\n            `<span class=\"arr\">→</span>` +\n            `<button class=\"goto\" data-actor=\"${t ? actorOf(t) : \"unknown\"}\" data-to=\"${esc(to)}\">${esc(to)}</button>` +\n            `${matched ? '<span class=\"cur-tag\">current match</span>' : \"\"}</div></div>`\n          )\n        }\n        const rows = (CURRENT.edges || [])\n          .map((e) => edgeRow(e.pattern, e.to, e.matched, undefined, e.action))\n          .join(\"\")\n        const retryRow = CURRENT.retry\n          ? edgeRow(null, CURRENT.retry.otherwise, false, CURRENT.retry.max, undefined)\n          : \"\"\n        panel.innerHTML =\n          `<div class=\"cur-head\"><span class=\"cur-name\">${esc(CURRENT.state)}</span>` +\n          `${pill(a)}<span class=\"kind\">${esc(CURRENT.kind)}</span>` +\n          `${CURRENT.group ? `<span class=\"flow-tag\">${esc(CURRENT.group)}</span>` : \"\"}</div>` +\n          `<div style=\"margin-top:14px\">${pendingListHtml(CURRENT.pending)}</div>` +\n          `<div class=\"edges\">${\n            rows || retryRow ? rows + retryRow : '<p class=\"none\">No outgoing edges declared.</p>'\n          }</div>`\n        panel.querySelector(\".cur-head\").onclick = () => navigateTo(CURRENT.state)\n        panel.querySelectorAll(\".goto\").forEach((b) => (b.onclick = () => navigateTo(b.dataset.to)))\n      }\n      renderCurrentPanel()\n\n      reinitializeAndRenderAll()\n\n      // ── live current-state polling ──────────────────────────────────────\n      // Keeps the panel + diagram highlight in sync with an in-progress\n      // process without a manual page refresh. Skipped while the tab is\n      // hidden; becoming visible again triggers an immediate refresh. No\n      // in-flight guard — a slow tick just means the next one also awaits.\n      async function poll() {\n        if (document.hidden) return\n        const changed = await refreshCurrent()\n        if (changed) {\n          renderCurrentPanel()\n          repaintHighlights()\n        }\n      }\n      setInterval(poll, 3000)\n      document.addEventListener(\"visibilitychange\", () => {\n        if (!document.hidden) poll()\n      })\n\n      // ── kind chips + actor legend ──────────────────────────────────────\n      const kindChipsEl = document.getElementById(\"kindChips\")\n      const presentKinds = [\"all\", ...Array.from(new Set(STATES.map((s) => s.kind)))]\n      presentKinds.forEach((k) => {\n        const b = document.createElement(\"button\")\n        b.className = \"chip-btn\" + (k === \"all\" ? \" on\" : \"\")\n        b.textContent = k\n        b.dataset.kind = k\n        b.onclick = () => {\n          kindFilter = k\n          ;[...kindChipsEl.children].forEach((c) =>\n            c.classList.toggle(\"on\", c.dataset.kind === kindFilter),\n          )\n          renderCatalogue()\n        }\n        kindChipsEl.appendChild(b)\n      })\n\n      const legendEl = document.getElementById(\"legend\")\n      ;[\"human\", \"agent\", \"check\", \"commit\", \"unknown\"].forEach((a) => {\n        if (!counts[a]) return\n        const el = document.createElement(\"button\")\n        el.className = \"li\"\n        el.dataset.actor = a\n        el.setAttribute(\"aria-pressed\", \"true\")\n        el.innerHTML = `<span class=\"dot\" style=\"background:var(--${meta(a).dot}-dot)\"></span>${meta(a).label}`\n        el.onclick = () => {\n          const on = actorFilter.has(a)\n          on ? actorFilter.delete(a) : actorFilter.add(a)\n          el.classList.toggle(\"off\", on)\n          el.setAttribute(\"aria-pressed\", String(!on))\n          renderCatalogue()\n        }\n        legendEl.appendChild(el)\n      })\n\n      // ── catalogue ──────────────────────────────────────────────────────\n      const groupsEl = document.getElementById(\"groups\")\n      function stateMatches(s, q) {\n        if (!actorFilter.has(actorOf(s))) return false\n        if (kindFilter !== \"all\" && s.kind !== kindFilter) return false\n        if (!q) return true\n        const hay = [\n          s.name,\n          s.actor,\n          s.kind,\n          s.file,\n          s.mode,\n          s.model,\n          s.memory,\n          (s.flags || []).join(\" \"),\n        ]\n          .filter(Boolean)\n          .join(\" \")\n          .toLowerCase()\n        return hay.includes(q)\n      }\n      function cardFor(s) {\n        const a = actorOf(s)\n        const card = document.createElement(\"button\")\n        card.className = \"card\"\n        card.dataset.actor = a\n        const flags = (s.flags || [])\n          .filter((f) => f !== \"initial\")\n          .map((f) => `<span class=\"flag\">${esc(f)}</span>`)\n          .join(\"\")\n        const retry = s.retry ? `<span class=\"flag\">retry ${s.retry.max}</span>` : \"\"\n        const initTick = s.initial ? `<div class=\"init-tick\">initial</div>` : \"\"\n        card.innerHTML =\n          `${initTick}<div class=\"name\">${esc(s.name)}</div>` +\n          `<div class=\"row\">${pill(a)}<span class=\"kind\">${esc(s.kind)}</span>${retry}${flags}</div>`\n        card.onclick = () => openDrawer(s.name)\n        return card\n      }\n      function renderCatalogue() {\n        const q = document.getElementById(\"search\").value.trim().toLowerCase()\n        groupsEl.innerHTML = \"\"\n        const sections = []\n        ;(MODEL.groups || []).forEach((g) => {\n          sections.push({\n            label: g.name,\n            flow: g.submachine,\n            items: STATES.filter((s) => s.group === g.name),\n          })\n        })\n        const ungrouped = STATES.filter((s) => !s.group)\n        if (ungrouped.length) sections.push({ label: \"Ungrouped\", flow: \"\", items: ungrouped })\n\n        let shown = 0\n        sections.forEach((sec) => {\n          const items = sec.items.filter((s) => stateMatches(s, q))\n          if (!items.length) return\n          shown += items.length\n          const wrap = document.createElement(\"div\")\n          wrap.className = \"group\"\n          wrap.innerHTML =\n            `<div class=\"group-head\">${sec.flow ? `<span class=\"flow-tag\">${esc(sec.flow)}</span>` : \"\"}` +\n            `<h3>${esc(sec.label)}</h3></div>`\n          const grid = document.createElement(\"div\")\n          grid.className = \"grid\"\n          items.forEach((s) => grid.appendChild(cardFor(s)))\n          wrap.appendChild(grid)\n          groupsEl.appendChild(wrap)\n        })\n        if (!shown)\n          groupsEl.innerHTML = `<p class=\"none\" style=\"padding:20px 0\">No states match this filter.</p>`\n      }\n      document.getElementById(\"search\").addEventListener(\"input\", renderCatalogue)\n      renderCatalogue()\n\n      // ── drawer ─────────────────────────────────────────────────────────\n      const drawer = document.getElementById(\"drawer\")\n      const backdrop = document.getElementById(\"backdrop\")\n      let lastFocus = null\n\n      function openDrawer(name) {\n        const s = byName[name]\n        if (!s) return\n        const a = actorOf(s)\n        if (!drawer.classList.contains(\"open\")) lastFocus = document.activeElement\n\n        const kv = []\n        kv.push([\"actor\", pill(a)])\n        kv.push([\"kind\", `<span class=\"kind\">${esc(s.kind)}</span>`])\n        kv.push([\"model\", s.model ? esc(s.model) : '<span class=\"none\">—</span>'])\n        kv.push([\"memory\", s.memory ? esc(s.memory) : '<span class=\"none\">—</span>'])\n        kv.push([\"file\", s.file ? esc(s.file) : '<span class=\"none\">—</span>'])\n        kv.push([\"mode\", s.mode ? esc(s.mode) : '<span class=\"none\">—</span>'])\n        if (s.retry)\n          kv.push([\n            \"retry\",\n            `max ${s.retry.max} → <span style=\"color:var(--accent)\">${esc(s.retry.otherwise)}</span>`,\n          ])\n        if (s.group) kv.push([\"group\", esc(s.group)])\n\n        const contentBlock = s.content\n          ? `<div class=\"field\"><div class=\"k\">content — ${esc(s.kind)}</div><pre class=\"dia-src state-content\">${esc(s.content)}</pre></div>`\n          : \"\"\n\n        const flags = s.flags || []\n        const flagBlock = flags.length\n          ? `<div class=\"field\"><div class=\"k\">flags & gates</div><div class=\"flag-list\">${flags\n              .map(\n                (f) =>\n                  `<div class=\"flag-item\"><span class=\"fn\">${esc(f)}</span><span class=\"fd\">${esc(FLAGS[f] || \"\")}</span></div>`,\n              )\n              .join(\"\")}</div></div>`\n          : \"\"\n\n        const edges = s.on || []\n        const edgesBlock = edges.length\n          ? `<div class=\"field\"><div class=\"k\">outgoing edges — on (first match wins)</div><div class=\"edges\">${edges\n              .map((e) => {\n                const t = byName[e.to]\n                const ta = t ? actorOf(t) : \"unknown\"\n                return (\n                  `<div class=\"edge\"><div class=\"er\">${\n                    e.action ? `<span class=\"act\">${esc(e.action)}</span>` : \"\"\n                  }<span class=\"pat\">${esc(e.pattern)}</span><span class=\"arr\">→</span>` +\n                  `<button class=\"goto\" data-actor=\"${ta}\" data-to=\"${esc(e.to)}\">${esc(e.to)}</button></div>` +\n                  `${e.describe ? `<div class=\"em\">${esc(e.describe)}</div>` : \"\"}</div>`\n                )\n              })\n              .join(\"\")}</div></div>`\n          : `<div class=\"field\"><div class=\"k\">outgoing edges</div><p class=\"none\">${\n              s.kind === \"commit\"\n                ? \"Commit state — no outgoing edges. Entering it ends the process in one squash.\"\n                : \"No outgoing edges declared.\"\n            }</p></div>`\n\n        const retryOut =\n          s.retry && byName[s.retry.otherwise]\n            ? `<div class=\"field\"><div class=\"k\">retry redirect</div><div class=\"edge\"><div class=\"er\">` +\n              `<span class=\"pat\">after ${esc(s.retry.max)} tries</span><span class=\"arr\">→</span>` +\n              `<button class=\"goto\" data-actor=\"${actorOf(byName[s.retry.otherwise])}\" data-to=\"${esc(s.retry.otherwise)}\">${esc(s.retry.otherwise)}</button>` +\n              `</div></div></div>`\n            : \"\"\n\n        const inc = s.incoming || []\n        const incBlock =\n          `<div class=\"field\"><div class=\"k\">routes in from (${inc.length})</div>` +\n          (inc.length\n            ? `<div class=\"incoming\">${inc\n                .map((i) => {\n                  const f = byName[i.from]\n                  return `<button class=\"goto\" data-actor=\"${f ? actorOf(f) : \"unknown\"}\" data-to=\"${esc(i.from)}\" title=\"${esc(i.pattern)}\">${esc(i.from)}</button>`\n                })\n                .join(\"\")}</div>`\n            : `<p class=\"none\">Reached only as an entry point (a CLI command enters it directly).</p>`) +\n          `</div>`\n\n        drawer.style.setProperty(\"--card-accent\", `var(--${meta(a).dot}-dot)`)\n        drawer.innerHTML =\n          `<div class=\"drawer-head\" style=\"--card-accent:var(--${meta(a).dot}-dot)\">` +\n          `<div class=\"top\"><h3>${esc(s.name)}</h3>` +\n          `<button class=\"close-x\" id=\"closeX\" aria-label=\"Close detail\">✕</button></div>` +\n          `<div class=\"meta-row\">${pill(a)}<span class=\"kind\">${esc(s.kind)}</span>` +\n          `${s.initial ? '<span class=\"flag\">initial</span>' : \"\"}` +\n          `${s.retry ? `<span class=\"flag\">retry ${s.retry.max}</span>` : \"\"}` +\n          `${flags\n            .filter((f) => f !== \"initial\")\n            .map((f) => `<span class=\"flag\">${esc(f)}</span>`)\n            .join(\"\")}</div></div>` +\n          `<div class=\"drawer-body\">` +\n          `<div class=\"field\"><div class=\"k\">definition</div><dl class=\"kv\">${kv\n            .map(([k, v]) => `<dt>${esc(k)}</dt><dd>${v}</dd>`)\n            .join(\"\")}</dl></div>` +\n          contentBlock +\n          flagBlock +\n          edgesBlock +\n          retryOut +\n          incBlock +\n          `</div>`\n\n        drawer\n          .querySelectorAll(\".goto\")\n          .forEach((b) => (b.onclick = () => openDrawer(b.dataset.to)))\n        drawer.querySelector(\"#closeX\").onclick = closeDrawer\n\n        backdrop.classList.add(\"open\")\n        drawer.classList.add(\"open\")\n        drawer.querySelector(\".drawer-body\").scrollTop = 0\n        drawer.querySelector(\"#closeX\").focus()\n      }\n      function closeDrawer() {\n        backdrop.classList.remove(\"open\")\n        drawer.classList.remove(\"open\")\n        if (lastFocus && lastFocus.focus) lastFocus.focus()\n      }\n      backdrop.onclick = closeDrawer\n      document.addEventListener(\"keydown\", (e) => {\n        if (e.key === \"Escape\" && drawer.classList.contains(\"open\")) closeDrawer()\n      })\n\n      // expose for interactions\n      window.__openState = openDrawer\n    <\/script>\n  </body>\n</html>\n";
+var visualize_default = "<!doctype html>\n<html lang=\"en\">\n  <head>\n    <meta charset=\"utf-8\" />\n    <meta name=\"viewport\" content=\"width=device-width, initial-scale=1\" />\n    <title>gtd · workflow visualizer</title>\n    <style>\n      :root {\n        --bg: #f4f6fa;\n        --surface: #ffffff;\n        --surface-2: #eef1f7;\n        --surface-3: #e6ebf3;\n        --border: #d9dee8;\n        --border-strong: #c2ccdb;\n        --text: #1a2233;\n        --text-dim: #55607a;\n        --text-faint: #8a93a6;\n        --accent: #2d6cdf;\n        --accent-soft: #e4edfd;\n        --human-bg: #fbeccd;\n        --human-fg: #7a5310;\n        --human-dot: #d99413;\n        --agent-bg: #e5e2fb;\n        --agent-fg: #463693;\n        --agent-dot: #6d5ce0;\n        --check-bg: #d3f0ef;\n        --check-fg: #0c524f;\n        --check-dot: #16a39d;\n        --engine-bg: #fbdfe4;\n        --engine-fg: #8a1f38;\n        --engine-dot: #d84a68;\n        --unknown-bg: #eef1f7;\n        --unknown-fg: #55607a;\n        --unknown-dot: #8a93a6;\n        --shadow: 0 1px 2px rgba(20, 30, 50, 0.06), 0 8px 28px rgba(20, 30, 50, 0.1);\n        --shadow-sm: 0 1px 2px rgba(20, 30, 50, 0.08);\n        --radius: 12px;\n        --mono:\n          ui-monospace, \"SF Mono\", \"SFMono-Regular\", Menlo, Consolas, \"Liberation Mono\", monospace;\n        --sans:\n          ui-sans-serif, system-ui, -apple-system, \"Segoe UI\", Roboto, Helvetica, Arial, sans-serif;\n        --dia-bg: #f7f9fc;\n      }\n      @media (prefers-color-scheme: dark) {\n        :root {\n          --bg: #0e1420;\n          --surface: #161d2b;\n          --surface-2: #1c2434;\n          --surface-3: #232c3e;\n          --border: #2b3547;\n          --border-strong: #3a465c;\n          --text: #e6ebf4;\n          --text-dim: #9aa6bd;\n          --text-faint: #6b7690;\n          --accent: #5b8def;\n          --accent-soft: #1b2740;\n          --human-bg: #3a2e12;\n          --human-fg: #f0c674;\n          --human-dot: #e0a83e;\n          --agent-bg: #26224a;\n          --agent-fg: #b6abf7;\n          --agent-dot: #8b7cf0;\n          --check-bg: #123433;\n          --check-fg: #68dcd4;\n          --check-dot: #2dc4bc;\n          --engine-bg: #3a1b24;\n          --engine-fg: #f2a3b3;\n          --engine-dot: #e05f7c;\n          --unknown-bg: #1c2434;\n          --unknown-fg: #9aa6bd;\n          --unknown-dot: #6b7690;\n          --shadow: 0 1px 2px rgba(0, 0, 0, 0.3), 0 12px 34px rgba(0, 0, 0, 0.45);\n          --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.35);\n          --dia-bg: #0b1018;\n        }\n      }\n      :root[data-theme=\"light\"] {\n        --bg: #f4f6fa;\n        --surface: #ffffff;\n        --surface-2: #eef1f7;\n        --surface-3: #e6ebf3;\n        --border: #d9dee8;\n        --border-strong: #c2ccdb;\n        --text: #1a2233;\n        --text-dim: #55607a;\n        --text-faint: #8a93a6;\n        --accent: #2d6cdf;\n        --accent-soft: #e4edfd;\n        --human-bg: #fbeccd;\n        --human-fg: #7a5310;\n        --human-dot: #d99413;\n        --agent-bg: #e5e2fb;\n        --agent-fg: #463693;\n        --agent-dot: #6d5ce0;\n        --check-bg: #d3f0ef;\n        --check-fg: #0c524f;\n        --check-dot: #16a39d;\n        --engine-bg: #fbdfe4;\n        --engine-fg: #8a1f38;\n        --engine-dot: #d84a68;\n        --unknown-bg: #eef1f7;\n        --unknown-fg: #55607a;\n        --unknown-dot: #8a93a6;\n        --shadow: 0 1px 2px rgba(20, 30, 50, 0.06), 0 8px 28px rgba(20, 30, 50, 0.1);\n        --shadow-sm: 0 1px 2px rgba(20, 30, 50, 0.08);\n        --dia-bg: #f7f9fc;\n      }\n      :root[data-theme=\"dark\"] {\n        --bg: #0e1420;\n        --surface: #161d2b;\n        --surface-2: #1c2434;\n        --surface-3: #232c3e;\n        --border: #2b3547;\n        --border-strong: #3a465c;\n        --text: #e6ebf4;\n        --text-dim: #9aa6bd;\n        --text-faint: #6b7690;\n        --accent: #5b8def;\n        --accent-soft: #1b2740;\n        --human-bg: #3a2e12;\n        --human-fg: #f0c674;\n        --human-dot: #e0a83e;\n        --agent-bg: #26224a;\n        --agent-fg: #b6abf7;\n        --agent-dot: #8b7cf0;\n        --check-bg: #123433;\n        --check-fg: #68dcd4;\n        --check-dot: #2dc4bc;\n        --engine-bg: #3a1b24;\n        --engine-fg: #f2a3b3;\n        --engine-dot: #e05f7c;\n        --unknown-bg: #1c2434;\n        --unknown-fg: #9aa6bd;\n        --unknown-dot: #6b7690;\n        --shadow: 0 1px 2px rgba(0, 0, 0, 0.3), 0 12px 34px rgba(0, 0, 0, 0.45);\n        --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.35);\n        --dia-bg: #0b1018;\n      }\n\n      * {\n        box-sizing: border-box;\n      }\n      html,\n      body {\n        max-width: 100%;\n        overflow-x: hidden;\n      }\n      body {\n        margin: 0;\n        background: var(--bg);\n        color: var(--text);\n        font-family: var(--sans);\n        font-size: 15px;\n        line-height: 1.55;\n        -webkit-font-smoothing: antialiased;\n      }\n      ::selection {\n        background: var(--accent);\n        color: #fff;\n      }\n      .wrap {\n        max-width: 1180px;\n        margin: 0 auto;\n        padding: 0 20px;\n      }\n\n      /* header */\n      header.top {\n        position: sticky;\n        top: 0;\n        z-index: 40;\n        background: color-mix(in srgb, var(--bg) 88%, transparent);\n        backdrop-filter: blur(10px);\n        border-bottom: 1px solid var(--border);\n      }\n      .top-inner {\n        display: flex;\n        align-items: center;\n        gap: 18px;\n        padding: 12px 20px;\n        max-width: 1180px;\n        margin: 0 auto;\n        flex-wrap: wrap;\n      }\n      .brand {\n        display: flex;\n        align-items: baseline;\n        gap: 10px;\n        margin-right: auto;\n      }\n      .brand .cmd {\n        font-family: var(--mono);\n        font-weight: 700;\n        font-size: 17px;\n        letter-spacing: -0.02em;\n      }\n      .brand .cmd b {\n        color: var(--accent);\n      }\n      .brand .sub {\n        font-size: 12px;\n        color: var(--text-faint);\n        letter-spacing: 0.04em;\n        text-transform: uppercase;\n      }\n      .summary {\n        font-size: 12.5px;\n        color: var(--text-dim);\n        display: flex;\n        gap: 10px;\n        flex-wrap: wrap;\n        align-items: center;\n      }\n      .summary .s-num {\n        font-family: var(--mono);\n        font-weight: 700;\n        color: var(--text);\n      }\n      .summary .sep {\n        color: var(--border-strong);\n      }\n      .theme-btn {\n        border: 1px solid var(--border);\n        background: var(--surface);\n        color: var(--text-dim);\n        border-radius: 8px;\n        width: 32px;\n        height: 32px;\n        cursor: pointer;\n        font-size: 14px;\n        display: grid;\n        place-items: center;\n      }\n      .theme-btn:hover {\n        color: var(--text);\n        border-color: var(--border-strong);\n      }\n      .theme-btn:focus-visible {\n        outline: 2px solid var(--accent);\n        outline-offset: 2px;\n      }\n\n      /* hero */\n      .hero {\n        padding: 40px 0 4px;\n      }\n      h1 {\n        font-size: clamp(26px, 4vw, 36px);\n        line-height: 1.08;\n        letter-spacing: -0.025em;\n        margin: 0 0 12px;\n        font-weight: 780;\n      }\n      h1 .mono {\n        font-family: var(--mono);\n        font-weight: 700;\n      }\n      .lede {\n        font-size: 16px;\n        color: var(--text-dim);\n        max-width: 70ch;\n        margin: 0;\n      }\n      .lede code {\n        font-family: var(--mono);\n        font-size: 0.88em;\n        background: var(--surface-2);\n        padding: 1px 6px;\n        border-radius: 5px;\n        color: var(--text);\n      }\n\n      /* section headers */\n      .sec-head {\n        display: flex;\n        align-items: baseline;\n        gap: 12px;\n        margin: 46px 0 4px;\n      }\n      .sec-head h2 {\n        font-size: 13px;\n        text-transform: uppercase;\n        letter-spacing: 0.12em;\n        color: var(--text-faint);\n        margin: 0;\n        font-weight: 700;\n      }\n      .sec-head .rule {\n        flex: 1;\n        height: 1px;\n        background: var(--border);\n      }\n\n      /* diagram */\n      .diagram-note {\n        font-size: 13px;\n        color: var(--text-dim);\n        margin: 16px 0 14px;\n        max-width: 78ch;\n      }\n      .diagram-note .mono {\n        font-family: var(--mono);\n      }\n      .dia-card {\n        background: var(--surface);\n        border: 1px solid var(--border);\n        border-radius: var(--radius);\n        box-shadow: var(--shadow-sm);\n        overflow: hidden;\n      }\n      .sm-card summary.h {\n        display: flex;\n        align-items: baseline;\n        justify-content: space-between;\n        cursor: pointer;\n        list-style: none;\n        padding: 14px 18px;\n        transition: background 0.12s ease;\n      }\n      .sm-card summary.h:hover {\n        background: var(--surface-2);\n      }\n      .sm-card[open] summary.h {\n        border-bottom: 1px solid var(--border);\n      }\n      .sm-card summary::-webkit-details-marker {\n        display: none;\n      }\n      .sm-card summary::after {\n        content: \"+\";\n        align-self: center;\n        color: var(--text-dim);\n        font-size: 18px;\n        font-weight: 700;\n        line-height: 1;\n        transform: translateY(-0.08em);\n        transition: color 0.15s ease;\n      }\n      .sm-card summary:hover::after {\n        color: var(--text);\n      }\n      .sm-card[open] summary::after {\n        content: \"\\2212\";\n      }\n      .dia-scroll {\n        position: relative;\n        overflow: hidden;\n        background: var(--dia-bg);\n        height: 460px;\n        cursor: grab;\n        touch-action: none;\n      }\n      .dia-scroll.pz-dragging {\n        cursor: grabbing;\n      }\n      .dia-scroll .mflow {\n        position: absolute;\n        top: 0;\n        left: 0;\n        padding: 18px 16px;\n        transform-origin: 0 0;\n      }\n      .dia-scroll .mflow svg {\n        max-width: none;\n        height: auto;\n        display: block;\n      }\n      .pz-controls {\n        position: absolute;\n        right: 12px;\n        bottom: 12px;\n        display: flex;\n        gap: 6px;\n        z-index: 5;\n      }\n      .pz-btn {\n        width: 30px;\n        height: 30px;\n        border-radius: 8px;\n        border: 1px solid var(--border);\n        background: var(--surface);\n        color: var(--text-dim);\n        cursor: pointer;\n        font-size: 15px;\n        font-family: var(--mono);\n        display: grid;\n        place-items: center;\n        box-shadow: var(--shadow-sm);\n        padding: 0;\n      }\n      .pz-btn:hover {\n        color: var(--text);\n        border-color: var(--border-strong);\n      }\n      .pz-btn:focus-visible {\n        outline: 2px solid var(--accent);\n        outline-offset: 2px;\n      }\n      .dia-msg {\n        padding: 22px 18px;\n        font-size: 13.5px;\n        color: var(--text-dim);\n      }\n      .dia-msg code {\n        font-family: var(--mono);\n        font-size: 12px;\n        background: var(--surface-2);\n        padding: 1px 6px;\n        border-radius: 5px;\n      }\n      .dia-src {\n        margin: 10px 0 0;\n        padding: 12px 14px;\n        background: var(--surface-2);\n        border-radius: 9px;\n        font-family: var(--mono);\n        font-size: 11.5px;\n        white-space: pre;\n        overflow-x: auto;\n        color: var(--text-dim);\n        max-height: 260px;\n      }\n      .state-content {\n        max-height: 340px;\n        white-space: pre-wrap;\n        word-break: break-word;\n      }\n\n      /* sub-machines */\n      .sm-grid {\n        display: grid;\n        grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));\n        gap: 14px;\n        margin-top: 18px;\n      }\n      .sm-def {\n        border: 1.5px dashed var(--border-strong);\n        border-radius: var(--radius);\n        background: var(--surface);\n        box-shadow: var(--shadow-sm);\n        overflow: hidden;\n      }\n      .sm-def .h {\n        padding: 13px 16px;\n        border-bottom: 1px solid var(--border);\n        background: var(--surface-2);\n      }\n      .sm-def .h .nm {\n        font-family: var(--mono);\n        font-weight: 700;\n        font-size: 15px;\n      }\n      .sm-def .h .pm {\n        font-family: var(--mono);\n        font-size: 12px;\n        color: var(--text-dim);\n        display: block;\n        margin-top: 3px;\n      }\n      .sm-def .h .pm b {\n        color: var(--accent);\n      }\n      .sm-def .body {\n        padding: 12px 16px 16px;\n        display: flex;\n        flex-wrap: wrap;\n        gap: 6px;\n      }\n      .muted-note {\n        color: var(--text-faint);\n        font-style: italic;\n        margin-top: 16px;\n      }\n      .sm-def .h {\n        display: flex;\n        align-items: baseline;\n        justify-content: space-between;\n        gap: 8px;\n      }\n      .sm-def .h .goto-sm {\n        font: inherit;\n        font-family: var(--mono);\n        font-size: 11px;\n        color: var(--accent);\n        background: none;\n        border: none;\n        cursor: pointer;\n        text-decoration: underline;\n        padding: 0;\n      }\n\n      /* current-state panel */\n      .current-panel {\n        background: var(--surface);\n        border: 1px solid var(--border);\n        border-radius: var(--radius);\n        box-shadow: var(--shadow-sm);\n        padding: 18px 20px 20px;\n        margin: 16px 0 34px;\n      }\n      .cur-head {\n        display: flex;\n        align-items: center;\n        gap: 10px;\n        flex-wrap: wrap;\n        cursor: pointer;\n      }\n      .cur-name {\n        font-family: var(--mono);\n        font-weight: 700;\n        font-size: 18px;\n        letter-spacing: -0.01em;\n      }\n      .cur-none {\n        color: var(--text-faint);\n        font-style: italic;\n      }\n      .edge.cur-matched {\n        border-color: var(--accent);\n        background: var(--accent-soft);\n      }\n      .cur-tag {\n        font-family: var(--mono);\n        font-size: 10.5px;\n        font-weight: 700;\n        color: var(--accent);\n        background: var(--surface);\n        border: 1px solid var(--accent);\n        padding: 1px 7px;\n        border-radius: 999px;\n        margin-left: auto;\n      }\n\n      /* pending-changes readout in the current-state panel */\n      .pending-list {\n        display: flex;\n        flex-direction: column;\n        gap: 3px;\n        font-family: var(--mono);\n        font-size: 12.5px;\n        margin-bottom: 14px;\n      }\n      .pending-list .pc {\n        display: flex;\n        gap: 9px;\n      }\n      .pending-list .st {\n        font-weight: 700;\n        width: 1ch;\n        flex: none;\n      }\n      .pending-list .path {\n        color: var(--text-dim);\n        word-break: break-all;\n      }\n      .pending-clean {\n        color: var(--text-faint);\n        font-style: italic;\n        font-size: 12.5px;\n        margin-bottom: 14px;\n      }\n\n      /* mermaid black-box / ghost node labels (rendered inside the SVG via htmlLabels) */\n      .sm-hint {\n        display: block;\n        margin-top: 2px;\n        font-size: 10.5px;\n        opacity: 0.72;\n        font-weight: 500;\n      }\n\n      /* the current-state highlight ring on a rendered SVG node/group box */\n      g.node.gtd-current {\n        filter: drop-shadow(0 0 6px var(--accent));\n      }\n      g.node.gtd-current > rect,\n      g.node.gtd-current > polygon,\n      g.node.gtd-current > circle,\n      g.node.gtd-current > ellipse,\n      g.node.gtd-current > path.basic {\n        stroke: var(--accent) !important;\n        stroke-width: 3px !important;\n      }\n\n      /* toolbar */\n      .toolbar {\n        display: flex;\n        gap: 12px;\n        align-items: center;\n        margin: 18px 0 22px;\n        flex-wrap: wrap;\n      }\n      .search {\n        flex: 1;\n        min-width: 200px;\n        position: relative;\n      }\n      .search input {\n        width: 100%;\n        font-family: var(--mono);\n        font-size: 14px;\n        padding: 10px 12px 10px 34px;\n        border-radius: 10px;\n        border: 1px solid var(--border);\n        background: var(--surface);\n        color: var(--text);\n      }\n      .search input:focus {\n        outline: none;\n        border-color: var(--accent);\n        box-shadow: 0 0 0 3px var(--accent-soft);\n      }\n      .search svg {\n        position: absolute;\n        left: 11px;\n        top: 50%;\n        transform: translateY(-50%);\n        color: var(--text-faint);\n      }\n      .chips {\n        display: flex;\n        gap: 6px;\n        flex-wrap: wrap;\n      }\n      .chip-btn {\n        font: inherit;\n        font-size: 12.5px;\n        padding: 7px 12px;\n        border-radius: 999px;\n        border: 1px solid var(--border);\n        background: var(--surface);\n        color: var(--text-dim);\n        cursor: pointer;\n      }\n      .chip-btn:hover {\n        border-color: var(--border-strong);\n        color: var(--text);\n      }\n      .chip-btn.on {\n        background: var(--accent);\n        border-color: var(--accent);\n        color: #fff;\n      }\n      .chip-btn:focus-visible {\n        outline: 2px solid var(--accent);\n        outline-offset: 2px;\n      }\n      .legend {\n        display: flex;\n        gap: 8px;\n        flex-wrap: wrap;\n      }\n      .legend .li {\n        display: inline-flex;\n        align-items: center;\n        gap: 6px;\n        font-size: 12.5px;\n        color: var(--text-dim);\n        cursor: pointer;\n        user-select: none;\n        padding: 5px 9px;\n        border-radius: 999px;\n        border: 1px solid var(--border);\n        background: var(--surface);\n      }\n      .legend .li:hover {\n        border-color: var(--border-strong);\n      }\n      .legend .li.off {\n        opacity: 0.4;\n      }\n      .legend .li:focus-visible {\n        outline: 2px solid var(--accent);\n        outline-offset: 2px;\n      }\n      .legend .li .dot {\n        width: 10px;\n        height: 10px;\n        border-radius: 3px;\n      }\n\n      /* groups + cards */\n      .group {\n        margin-bottom: 30px;\n      }\n      .group-head {\n        display: flex;\n        align-items: baseline;\n        gap: 10px;\n        margin: 0 0 12px;\n      }\n      .group-head h3 {\n        font-family: var(--mono);\n        font-size: 15px;\n        margin: 0;\n        letter-spacing: -0.01em;\n      }\n      .group-head .flow-tag {\n        font-family: var(--mono);\n        font-size: 11px;\n        padding: 2px 8px;\n        border-radius: 6px;\n        background: var(--surface-2);\n        color: var(--text-dim);\n        border: 1px solid var(--border);\n      }\n      .grid {\n        display: grid;\n        grid-template-columns: repeat(auto-fill, minmax(250px, 1fr));\n        gap: 12px;\n      }\n      .card {\n        text-align: left;\n        font: inherit;\n        color: var(--text);\n        cursor: pointer;\n        background: var(--surface);\n        border: 1px solid var(--border);\n        border-left: 4px solid var(--card-accent, var(--border));\n        border-radius: 10px;\n        padding: 13px 15px;\n        box-shadow: var(--shadow-sm);\n        transition:\n          transform 0.12s ease,\n          box-shadow 0.12s ease,\n          border-color 0.12s ease;\n        position: relative;\n        display: flex;\n        flex-direction: column;\n        gap: 8px;\n      }\n      .card:hover {\n        transform: translateY(-2px);\n        box-shadow: var(--shadow);\n      }\n      .card:focus-visible {\n        outline: 2px solid var(--accent);\n        outline-offset: 2px;\n      }\n      .card[data-actor=\"human\"] {\n        --card-accent: var(--human-dot);\n      }\n      .card[data-actor=\"agent\"] {\n        --card-accent: var(--agent-dot);\n      }\n      .card[data-actor=\"check\"] {\n        --card-accent: var(--check-dot);\n      }\n      .card[data-actor=\"commit\"] {\n        --card-accent: var(--engine-dot);\n      }\n      .card[data-actor=\"unknown\"] {\n        --card-accent: var(--unknown-dot);\n      }\n      .card .name {\n        font-family: var(--mono);\n        font-weight: 700;\n        font-size: 14.5px;\n        letter-spacing: -0.01em;\n        word-break: break-word;\n      }\n      .card .row {\n        display: flex;\n        align-items: center;\n        gap: 6px;\n        flex-wrap: wrap;\n      }\n      .card .init-tick {\n        position: absolute;\n        top: 11px;\n        right: 12px;\n        font-size: 10px;\n        font-family: var(--mono);\n        color: var(--accent);\n        background: var(--accent-soft);\n        padding: 1px 6px;\n        border-radius: 5px;\n        font-weight: 700;\n      }\n\n      .pill {\n        display: inline-flex;\n        align-items: center;\n        gap: 5px;\n        font-family: var(--mono);\n        font-size: 11px;\n        font-weight: 600;\n        padding: 2px 8px;\n        border-radius: 999px;\n      }\n      .pill.actor-human {\n        background: var(--human-bg);\n        color: var(--human-fg);\n      }\n      .pill.actor-agent {\n        background: var(--agent-bg);\n        color: var(--agent-fg);\n      }\n      .pill.actor-check {\n        background: var(--check-bg);\n        color: var(--check-fg);\n      }\n      .pill.actor-engine {\n        background: var(--engine-bg);\n        color: var(--engine-fg);\n      }\n      .pill.actor-unknown {\n        background: var(--unknown-bg);\n        color: var(--unknown-fg);\n      }\n      .pill .dot {\n        width: 7px;\n        height: 7px;\n        border-radius: 2px;\n      }\n      .pill.actor-human .dot {\n        background: var(--human-dot);\n      }\n      .pill.actor-agent .dot {\n        background: var(--agent-dot);\n      }\n      .pill.actor-check .dot {\n        background: var(--check-dot);\n      }\n      .pill.actor-engine .dot {\n        background: var(--engine-dot);\n      }\n      .pill.actor-unknown .dot {\n        background: var(--unknown-dot);\n      }\n      .kind {\n        font-family: var(--mono);\n        font-size: 11px;\n        padding: 2px 7px;\n        border-radius: 6px;\n        border: 1px solid var(--border-strong);\n        color: var(--text-dim);\n        background: var(--surface-2);\n      }\n      .flag {\n        font-family: var(--mono);\n        font-size: 10.5px;\n        padding: 1px 6px;\n        border-radius: 5px;\n        background: var(--accent-soft);\n        color: var(--accent);\n        font-weight: 600;\n        border: 1px solid color-mix(in srgb, var(--accent) 25%, transparent);\n      }\n\n      /* drawer */\n      .backdrop {\n        position: fixed;\n        inset: 0;\n        background: rgba(10, 16, 28, 0.5);\n        backdrop-filter: blur(2px);\n        opacity: 0;\n        pointer-events: none;\n        transition: opacity 0.22s ease;\n        z-index: 90;\n      }\n      .backdrop.open {\n        opacity: 1;\n        pointer-events: auto;\n      }\n      .drawer {\n        position: fixed;\n        top: 0;\n        right: 0;\n        height: 100%;\n        width: min(560px, 100%);\n        background: var(--surface);\n        border-left: 1px solid var(--border);\n        box-shadow: var(--shadow);\n        transform: translateX(100%);\n        transition: transform 0.26s cubic-bezier(0.22, 0.61, 0.36, 1);\n        z-index: 100;\n        display: flex;\n        flex-direction: column;\n      }\n      .drawer.open {\n        transform: translateX(0);\n      }\n      .drawer-head {\n        padding: 18px 22px 14px;\n        border-bottom: 1px solid var(--border);\n        border-top: 4px solid var(--card-accent, var(--accent));\n      }\n      .drawer-head .top {\n        display: flex;\n        align-items: flex-start;\n        gap: 12px;\n      }\n      .drawer-head h3 {\n        font-family: var(--mono);\n        font-size: 20px;\n        font-weight: 700;\n        margin: 0;\n        letter-spacing: -0.02em;\n        word-break: break-word;\n      }\n      .drawer-head .meta-row {\n        display: flex;\n        gap: 6px;\n        flex-wrap: wrap;\n        margin-top: 10px;\n      }\n      .close-x {\n        margin-left: auto;\n        border: 1px solid var(--border);\n        background: var(--surface-2);\n        color: var(--text-dim);\n        border-radius: 8px;\n        width: 30px;\n        height: 30px;\n        cursor: pointer;\n        flex: none;\n        font-size: 15px;\n      }\n      .close-x:hover {\n        color: var(--text);\n      }\n      .close-x:focus-visible {\n        outline: 2px solid var(--accent);\n        outline-offset: 2px;\n      }\n      .drawer-body {\n        overflow-y: auto;\n        padding: 20px 22px 40px;\n        flex: 1;\n      }\n      .field {\n        margin-bottom: 18px;\n      }\n      .field > .k {\n        font-size: 11px;\n        text-transform: uppercase;\n        letter-spacing: 0.09em;\n        color: var(--text-faint);\n        font-weight: 700;\n        margin-bottom: 7px;\n      }\n      .kv {\n        display: grid;\n        grid-template-columns: 88px 1fr;\n        gap: 4px 14px;\n        font-size: 13.5px;\n      }\n      .kv dt {\n        color: var(--text-faint);\n        font-size: 12px;\n      }\n      .kv dd {\n        margin: 0;\n        font-family: var(--mono);\n        font-size: 12.5px;\n        word-break: break-word;\n      }\n      .none {\n        color: var(--text-faint);\n        font-style: italic;\n        font-family: var(--sans);\n      }\n\n      .edges {\n        display: flex;\n        flex-direction: column;\n        gap: 8px;\n      }\n      .edge {\n        border: 1px solid var(--border);\n        border-radius: 9px;\n        padding: 10px 12px;\n        background: var(--surface-2);\n      }\n      .edge .er {\n        display: flex;\n        align-items: center;\n        gap: 8px;\n        flex-wrap: wrap;\n      }\n      .edge .pat {\n        font-family: var(--mono);\n        font-size: 12px;\n        font-weight: 700;\n        background: var(--surface);\n        border: 1px solid var(--border-strong);\n        padding: 2px 8px;\n        border-radius: 6px;\n        white-space: nowrap;\n      }\n      .edge .act {\n        font-size: 12.5px;\n        font-weight: 700;\n        color: var(--accent);\n      }\n      .edge .arr {\n        color: var(--text-faint);\n      }\n      .goto {\n        font: inherit;\n        font-family: var(--mono);\n        font-size: 12.5px;\n        font-weight: 700;\n        cursor: pointer;\n        border: 1px solid var(--card-accent, var(--accent));\n        background: transparent;\n        color: var(--card-accent, var(--accent));\n        padding: 2px 9px;\n        border-radius: 6px;\n      }\n      .goto:hover {\n        background: var(--card-accent, var(--accent));\n        color: #fff;\n      }\n      .goto:focus-visible {\n        outline: 2px solid var(--accent);\n        outline-offset: 2px;\n      }\n      .goto[data-actor=\"human\"] {\n        --card-accent: var(--human-dot);\n      }\n      .goto[data-actor=\"agent\"] {\n        --card-accent: var(--agent-dot);\n      }\n      .goto[data-actor=\"check\"] {\n        --card-accent: var(--check-dot);\n      }\n      .goto[data-actor=\"commit\"] {\n        --card-accent: var(--engine-dot);\n      }\n      .goto[data-actor=\"unknown\"] {\n        --card-accent: var(--unknown-dot);\n      }\n      .edge .em {\n        font-size: 12.5px;\n        color: var(--text-dim);\n        margin-top: 6px;\n        line-height: 1.45;\n      }\n      .incoming {\n        display: flex;\n        flex-wrap: wrap;\n        gap: 6px;\n      }\n\n      .flag-list {\n        display: flex;\n        flex-direction: column;\n        gap: 8px;\n      }\n      .flag-item {\n        display: flex;\n        gap: 9px;\n        font-size: 13px;\n        align-items: baseline;\n      }\n      .flag-item .fn {\n        font-family: var(--mono);\n        font-size: 11.5px;\n        font-weight: 700;\n        color: var(--accent);\n        flex: none;\n        padding: 1px 6px;\n        border-radius: 5px;\n        background: var(--accent-soft);\n      }\n      .flag-item .fd {\n        color: var(--text-dim);\n      }\n\n      /* vars */\n      .vars-grid {\n        display: flex;\n        flex-wrap: wrap;\n        gap: 8px;\n        margin-top: 16px;\n      }\n      .var-chip {\n        font-family: var(--mono);\n        font-size: 12px;\n        padding: 6px 10px;\n        border-radius: 8px;\n        border: 1px solid var(--border);\n        background: var(--surface);\n        box-shadow: var(--shadow-sm);\n      }\n      .var-chip b {\n        color: var(--accent);\n      }\n\n      footer {\n        border-top: 1px solid var(--border);\n        margin-top: 56px;\n        padding: 40px 0 72px;\n        color: var(--text-faint);\n        font-size: 13px;\n      }\n      footer code {\n        font-family: var(--mono);\n        background: var(--surface-2);\n        padding: 1px 6px;\n        border-radius: 5px;\n      }\n      footer .foot-lead {\n        margin: 0 0 14px;\n        padding-top: 16px;\n        color: var(--text-dim);\n      }\n      footer .foot-legend {\n        display: flex;\n        align-items: center;\n        gap: 8px;\n        flex-wrap: wrap;\n        padding-bottom: 16px;\n      }\n      footer .foot-chip {\n        font-family: var(--mono);\n        font-size: 12px;\n        padding: 3px 9px;\n        border-radius: 7px;\n        border: 1px solid var(--border);\n        background: var(--surface);\n        color: var(--text-dim);\n      }\n\n      .hidden {\n        display: none !important;\n      }\n      @media (prefers-reduced-motion: reduce) {\n        *,\n        *::before,\n        *::after {\n          transition: none !important;\n          animation: none !important;\n        }\n      }\n      @media (max-width: 640px) {\n        .brand .sub {\n          display: none;\n        }\n        .kv {\n          grid-template-columns: 74px 1fr;\n        }\n      }\n    </style>\n  </head>\n  <body>\n    <header class=\"top\">\n      <div class=\"top-inner\">\n        <div class=\"brand\">\n          <span class=\"cmd\"><b>gtd</b> · workflow visualizer</span>\n          <span class=\"sub\" id=\"brandSub\">read-only view</span>\n        </div>\n        <div class=\"summary\" id=\"summary\"></div>\n        <button\n          class=\"theme-btn\"\n          id=\"themeBtn\"\n          title=\"Toggle light/dark theme\"\n          aria-label=\"Toggle light/dark theme\"\n        >\n          ◐\n        </button>\n      </div>\n    </header>\n\n    <main class=\"wrap\" id=\"app\">\n      <section class=\"hero\">\n        <h1 id=\"heroTitle\">Loading workflow…</h1>\n        <p class=\"lede\" id=\"heroLede\">\n          Fetching <code>/workflow.json</code> from the local\n          <span class=\"mono\">gtd visualize</span> server.\n        </p>\n      </section>\n\n      <div id=\"content\" class=\"hidden\">\n        <div class=\"sec-head\">\n          <h2>Current state</h2>\n          <span class=\"rule\"></span>\n        </div>\n        <div class=\"current-panel hidden\" id=\"currentPanel\"></div>\n        <div id=\"varsSection\"></div>\n\n        <div class=\"sec-head\">\n          <h2>Main flow</h2>\n          <span class=\"rule\"></span>\n        </div>\n        <p class=\"diagram-note\" id=\"diaNote\"></p>\n        <div class=\"dia-card\">\n          <div class=\"dia-scroll\" id=\"diaScroll\"><div class=\"dia-msg\">Rendering diagram…</div></div>\n        </div>\n\n        <div class=\"sec-head\">\n          <h2>Sub-machines</h2>\n          <span class=\"rule\"></span>\n        </div>\n        <div id=\"smSection\"></div>\n\n        <div class=\"sec-head\">\n          <h2>State catalogue</h2>\n          <span class=\"rule\"></span>\n        </div>\n        <div class=\"toolbar\">\n          <div class=\"search\">\n            <svg\n              width=\"15\"\n              height=\"15\"\n              viewBox=\"0 0 24 24\"\n              fill=\"none\"\n              stroke=\"currentColor\"\n              stroke-width=\"2.4\"\n            >\n              <circle cx=\"11\" cy=\"11\" r=\"7\" />\n              <path d=\"m21 21-4.3-4.3\" />\n            </svg>\n            <input\n              id=\"search\"\n              type=\"search\"\n              placeholder=\"filter by name, actor, kind, file, mode, flag…\"\n              autocomplete=\"off\"\n              spellcheck=\"false\"\n              aria-label=\"Filter states\"\n            />\n          </div>\n          <div class=\"chips\" id=\"kindChips\"></div>\n          <div class=\"legend\" id=\"legend\"></div>\n        </div>\n        <div id=\"groups\"></div>\n      </div>\n    </main>\n\n    <div class=\"backdrop\" id=\"backdrop\"></div>\n    <aside\n      class=\"drawer\"\n      id=\"drawer\"\n      role=\"dialog\"\n      aria-modal=\"true\"\n      aria-label=\"State detail\"\n      tabindex=\"-1\"\n    ></aside>\n\n    <footer class=\"wrap\" id=\"footer\"></footer>\n\n    <script type=\"module\">\n      // ── theme ──────────────────────────────────────────────────────────────\n      const root = document.documentElement\n      const prefersDark = () => matchMedia(\"(prefers-color-scheme: dark)\").matches\n      const isDark = () => {\n        const t = root.getAttribute(\"data-theme\")\n        return t ? t === \"dark\" : prefersDark()\n      }\n      document.getElementById(\"themeBtn\").onclick = () => {\n        const next = isDark() ? \"light\" : \"dark\"\n        root.setAttribute(\"data-theme\", next)\n        reinitializeAndRenderAll()\n      }\n      // Follow the OS when the user hasn't made an explicit choice — an\n      // explicit `data-theme` override always wins over an OS flip.\n      matchMedia(\"(prefers-color-scheme: dark)\").addEventListener(\"change\", () => {\n        if (!root.getAttribute(\"data-theme\")) reinitializeAndRenderAll()\n      })\n\n      const esc = (s) =>\n        String(s).replace(\n          /[&<>\"']/g,\n          (c) => ({ \"&\": \"&amp;\", \"<\": \"&lt;\", \">\": \"&gt;\", '\"': \"&quot;\", \"'\": \"&#39;\" })[c],\n        )\n\n      // Actor metadata: color class, css-var prefix, mermaid classDef name, label.\n      const ACTOR = {\n        human: { cls: \"actor-human\", dot: \"human\", label: \"human\" },\n        agent: { cls: \"actor-agent\", dot: \"agent\", label: \"agent\" },\n        check: { cls: \"actor-check\", dot: \"check\", label: \"check\" },\n        commit: { cls: \"actor-engine\", dot: \"engine\", label: \"commit\" },\n        unknown: { cls: \"actor-unknown\", dot: \"unknown\", label: \"?\" },\n      }\n      // A commit state has no actor — treat it as the engine/commit colour.\n      const actorOf = (s) => s.actor || (s.kind === \"commit\" ? \"commit\" : \"unknown\")\n      const meta = (a) => ACTOR[a] || ACTOR.unknown\n\n      const FLAGS = {\n        initial:\n          \"The one initial state — an unrecognized HEAD (any non-gtd history) resolves here.\",\n        entry:\n          \"This state is a manual entry point (`entry: true`) — a brand-new process may start here via `gtd step <actor> --entry <state>` (or the subcommand-less `gtd --entry <state>`), in addition to the workflow's ordinary `initial` state.\",\n        reviewWindow:\n          \"While resting here, gtd opens the review checkout window: HEAD is rewound to the review base so the whole diff surfaces as ordinary uncommitted changes.\",\n        reviewBase:\n          \"Anchors the incremental review diff base — its most-recent in-process commit is where the next reviewing turn and checkout window start.\",\n        answerGate:\n          \"Edge gate: a step is refused while any open question in the steering file is not answered with exactly one tick.\",\n        requireProgress:\n          \"Edge gate: refuses a work-free turn that only deletes the instructions file (unless it held a NOTHING ACTIONABLE sentinel).\",\n      }\n\n      // ── state ──────────────────────────────────────────────────────────────\n      let MODEL = null\n      let STATES = []\n      let byName = {}\n      let CURRENT = null\n      let lastCurrentSig = undefined\n      let mermaidMod = null\n\n      // Fetches `/state.json`, updates `CURRENT`, and reports whether the\n      // resolved body actually changed since the last call (compared on the\n      // full JSON so an edge's `matched` flag flipping counts as a change too).\n      async function refreshCurrent() {\n        let next = null\n        try {\n          const res = await fetch(\"/state.json\")\n          const body = res.ok ? await res.json() : {}\n          next = body && body.state ? body : null\n        } catch (e) {\n          next = null\n        }\n        const sig = JSON.stringify(next)\n        if (sig === lastCurrentSig) return false\n        lastCurrentSig = sig\n        CURRENT = next\n        return true\n      }\n\n      const actorFilter = new Set([\"human\", \"agent\", \"check\", \"commit\", \"unknown\"])\n      let kindFilter = \"all\"\n\n      // ── boot ─────────────────────────────────────────────────────────────\n      try {\n        const res = await fetch(\"/workflow.json\")\n        if (!res.ok) throw new Error(\"HTTP \" + res.status)\n        MODEL = await res.json()\n      } catch (e) {\n        document.getElementById(\"heroTitle\").textContent = \"Could not load workflow\"\n        document.getElementById(\"heroLede\").innerHTML =\n          \"Fetching <code>/workflow.json</code> failed: \" +\n          esc(e.message) +\n          '. This page must be served by <span class=\"mono\">gtd visualize</span>.'\n        throw e\n      }\n\n      // Resolved at page load, then re-polled every 3s (see `poll()` below) so\n      // advancing the process shows up without a manual refresh. Tolerates a\n      // 404/error (an older server) or an empty `{}` (no active process/not a repo).\n      await refreshCurrent()\n\n      STATES = MODEL.states || []\n      byName = Object.fromEntries(STATES.map((s) => [s.name, s]))\n\n      // ── header summary + hero ───────────────────────────────────────────\n      const counts = { human: 0, agent: 0, check: 0, commit: 0, unknown: 0 }\n      STATES.forEach((s) => {\n        counts[actorOf(s)]++\n      })\n      const nGroups = (MODEL.groups || []).length\n      const cnt = (a) =>\n        counts[a] ? `<span><span class=\"s-num\">${counts[a]}</span> ${meta(a).label}</span>` : \"\"\n      document.getElementById(\"summary\").innerHTML = [\n        `<span><span class=\"s-num\">${STATES.length}</span> states</span>`,\n        `<span><span class=\"s-num\">${nGroups}</span> sub-machine${nGroups === 1 ? \"\" : \"s\"}</span>`,\n        `<span class=\"sep\">·</span>`,\n        cnt(\"human\"),\n        cnt(\"agent\"),\n        cnt(\"check\"),\n        cnt(\"commit\"),\n        cnt(\"unknown\"),\n      ]\n        .filter(Boolean)\n        .join(\" \")\n\n      document.getElementById(\"heroTitle\").innerHTML = `GTD workflow visualization`\n      document.getElementById(\"heroLede\").innerHTML =\n        `Rendered live from your workflow. The initial state is ` +\n        `<code>${esc(MODEL.initial)}</code>. Click any state — in the diagram, a sub-machine chip, ` +\n        `or the catalogue — to open its full definition, walk its outgoing edges, and see what routes into it.`\n      document.getElementById(\"content\").classList.remove(\"hidden\")\n\n      document.getElementById(\"footer\").innerHTML =\n        `<p class=\"foot-lead\">Read-only view served by <code>gtd visualize</code>.</p>` +\n        `<div class=\"foot-legend\">` +\n        `<span class=\"foot-chip\">([message])</span>` +\n        `<span class=\"foot-chip\">[prompt]</span>` +\n        `<span class=\"foot-chip\">{{script}}</span>` +\n        `<span class=\"foot-chip\">[[commit]]</span>` +\n        `<span>— node shape = content kind; colour = actor.</span>` +\n        `</div>`\n\n      // ── pill helper ────────────────────────────────────────────────────\n      const pill = (a) =>\n        `<span class=\"pill ${meta(a).cls}\"><span class=\"dot\"></span>${meta(a).label}</span>`\n\n      // ── mermaid source generation ──────────────────────────────────────\n      // Safe, stable node ids (state names can contain hyphens etc.), with a\n      // reverse lookup — needed to map a rendered SVG node's id back to its\n      // state name when wiring clicks (see `nodeIdOf`/`wire*Clicks` below).\n      const idFor = (() => {\n        const map = new Map()\n        const rev = new Map()\n        const fn = (name) => {\n          if (!map.has(name)) {\n            const id = \"n\" + map.size\n            map.set(name, id)\n            rev.set(id, name)\n          }\n          return map.get(name)\n        }\n        fn.nameOf = (id) => rev.get(id)\n        return fn\n      })()\n      const groupBoxId = (i) => \"g\" + i\n      const groupIndexOf = (name) => (MODEL.groups || []).findIndex((g) => g.name === name)\n      // `g.states` is that instance's DIRECT states only (`MODEL.groups` is a\n      // flat, depth-first projection of the machine tree) — a diagram scoped to\n      // `g` (the main flow collapsing `g`, or `g`'s own sub-machine panel) needs\n      // its whole subtree: direct states unioned with every descendant's.\n      const allStatesOf = (g) => {\n        const prefix = g.name + \".\"\n        const states = [...(g.states || [])]\n        ;(MODEL.groups || []).forEach((other) => {\n          if (other.name.startsWith(prefix)) states.push(...(other.states || []))\n        })\n        return states\n      }\n      const shapeFor = (kind, label) => {\n        const l = `\"${label.replace(/\"/g, \"&quot;\")}\"`\n        switch (kind) {\n          case \"message\":\n            return `([\"${label.replace(/\"/g, \"&quot;\")}\"])`\n          case \"prompt\":\n            return `[${l}]`\n          case \"script\":\n            return `{{${l}}}`\n          case \"commit\":\n            return `[[${l}]]`\n          default:\n            return `[${l}]`\n        }\n      }\n      const mlabel = (s) => `\"${String(s).replace(/\"/g, \"&quot;\").replace(/\\|/g, \"&#124;\")}\"`\n      /**\n       * The mermaid `classDef` lines for actor/ghost node fills, chosen per\n       * theme so dark mode doesn't render washed-out light pastels.\n       */\n      function classDefs(dark) {\n        return [\n          dark\n            ? \"classDef human fill:#3a2e12,stroke:#e0a83e,color:#f0c674;\"\n            : \"classDef human fill:#fbeccd,stroke:#d99413,color:#5a3d0a;\",\n          dark\n            ? \"classDef agent fill:#26224a,stroke:#8b7cf0,color:#b6abf7;\"\n            : \"classDef agent fill:#e5e2fb,stroke:#6d5ce0,color:#3a2c85;\",\n          dark\n            ? \"classDef check fill:#123433,stroke:#2dc4bc,color:#68dcd4;\"\n            : \"classDef check fill:#d3f0ef,stroke:#16a39d,color:#0c524f;\",\n          dark\n            ? \"classDef commit fill:#3a1b24,stroke:#e05f7c,color:#f2a3b3;\"\n            : \"classDef commit fill:#fbdfe4,stroke:#d84a68,color:#8a1f38;\",\n          dark\n            ? \"classDef unknown fill:#1c2434,stroke:#3a465c,color:#9aa6bd,stroke-dasharray:4 3;\"\n            : \"classDef unknown fill:#eef1f7,stroke:#c2ccdb,color:#55607a,stroke-dasharray:4 3;\",\n          // Sub-machine invocation: a muted slate box (not one of the actor\n          // colours) so it still reads as its own distinct \"black-box\" kind,\n          // without the harsh opaque-black fill clashing with a light theme.\n          dark\n            ? \"classDef submachine fill:#2a3142,stroke:#5a6b8c,color:#dbe4f5,font-weight:700;\"\n            : \"classDef submachine fill:#e4e9f2,stroke:#8695b3,color:#2a3142,font-weight:700;\",\n          // A muted, dashed ghost node standing in for a target OUTSIDE the\n          // current diagram (a sub-machine diagram's external edge).\n          dark\n            ? \"classDef external fill:#1c2434,stroke:#3a465c,color:#9aa6bd,stroke-dasharray:5 4;\"\n            : \"classDef external fill:#eef1f7,stroke:#c2ccdb,color:#55607a,stroke-dasharray:5 4;\",\n        ]\n      }\n\n      /**\n       * Build one flowchart's mermaid source over `states` (a diagram scope):\n       * the whole machine for the main flow (`opts.scope` unset), or one\n       * sub-machine's own member states (`opts.scope` = that group's name).\n       * A member state whose innermost group differs from `opts.scope`\n       * collapses into a black box for ITS group (handles a sub-machine\n       * nested inside another); a target outside `states` entirely renders as\n       * a muted, dashed ghost node instead (only possible in a sub-machine\n       * diagram — the main flow's `states` is every state, so nothing is ever\n       * \"outside\" it).\n       */\n      function buildFlowSrc(states, opts) {\n        const scope = opts && opts.scope\n        const inSet = new Set(states.map((s) => s.name))\n        const lines = [\"flowchart TD\"]\n\n        // Collapse a state to the outermost instance strictly below `scope`\n        // (the child of `scope` that is an ancestor of the state), not the\n        // state's own innermost group — walk from `scope` toward the state one\n        // path segment at a time and stop at the first instance boundary. A\n        // state whose group IS `scope` (a direct member) stays a real node.\n        const unitOf = (name) => {\n          const s = byName[name]\n          const group = s ? s.group : undefined\n          if (group === scope) return { kind: \"node\", name }\n          const scopePrefix = scope ? scope + \".\" : \"\"\n          const rest = name.startsWith(scopePrefix) ? name.slice(scopePrefix.length) : name\n          const firstSeg = rest.split(\".\")[0]\n          const boundary = scope ? scope + \".\" + firstSeg : firstSeg\n          return { kind: \"box\", group: boundary }\n        }\n        const unitId = (name) => {\n          const u = unitOf(name)\n          return u.kind === \"box\" ? groupBoxId(groupIndexOf(u.group)) : idFor(name)\n        }\n\n        const emittedNodes = new Set()\n        const emittedBoxes = new Set()\n        const emittedGhosts = new Set()\n        const nodeLine = (s) => `  ${idFor(s.name)}${shapeFor(s.kind, s.name)}:::${actorOf(s)}`\n        const boxLine = (g, i) => {\n          const n = allStatesOf(g).length\n          const modelSuffix = g.model ? ` · model: ${esc(g.model)}` : \"\"\n          return `  ${groupBoxId(i)}[\"${esc(g.name)}<br/><span class='sm-hint'>▸ ${n} state${\n            n === 1 ? \"\" : \"s\"\n          }${modelSuffix}</span>\"]:::submachine`\n        }\n        const ghostLine = (s) => `  e${idFor(s.name)}${shapeFor(s.kind, s.name)}:::external`\n\n        states.forEach((s) => {\n          const u = unitOf(s.name)\n          if (u.kind === \"node\") {\n            if (emittedNodes.has(s.name)) return\n            emittedNodes.add(s.name)\n            lines.push(nodeLine(s))\n          } else if (!emittedBoxes.has(u.group)) {\n            emittedBoxes.add(u.group)\n            const i = groupIndexOf(u.group)\n            if (i >= 0) lines.push(boxLine(MODEL.groups[i], i))\n          }\n        })\n\n        // Edges within this diagram's own state set, collapsed through box\n        // units, deduped, and label-dropped when several patterns land on the\n        // same box-level edge (a black box hides which one specifically).\n        const solid = new Map()\n        const dashed = new Map()\n        const addEdge = (map, from, to, label) => {\n          if (from === to) return\n          const key = from + \" \" + to\n          if (!map.has(key)) map.set(key, [])\n          map.get(key).push(label)\n        }\n        states.forEach((s) => {\n          ;(s.on || []).forEach((e) => {\n            if (!inSet.has(e.to) || !byName[e.to]) return\n            addEdge(solid, unitId(s.name), unitId(e.to), e.action || e.pattern)\n          })\n          if (s.retry && inSet.has(s.retry.otherwise)) {\n            addEdge(dashed, unitId(s.name), unitId(s.retry.otherwise), \"retry ×\" + s.retry.max)\n          }\n        })\n        // Ghost edges to a target entirely outside this diagram's state set\n        // (only fires for a sub-machine diagram — the main flow's set is\n        // every state, so nothing is ever \"outside\" it).\n        states.forEach((s) => {\n          ;(s.on || []).forEach((e) => {\n            if (inSet.has(e.to) || !byName[e.to]) return\n            const target = byName[e.to]\n            if (!emittedGhosts.has(e.to)) {\n              emittedGhosts.add(e.to)\n              lines.push(ghostLine(target))\n            }\n            lines.push(`  ${idFor(s.name)} -->|${mlabel(e.action || e.pattern)}| e${idFor(e.to)}`)\n          })\n          if (s.retry && byName[s.retry.otherwise] && !inSet.has(s.retry.otherwise)) {\n            const target = byName[s.retry.otherwise]\n            if (!emittedGhosts.has(s.retry.otherwise)) {\n              emittedGhosts.add(s.retry.otherwise)\n              lines.push(ghostLine(target))\n            }\n            lines.push(\n              `  ${idFor(s.name)} -.->|${mlabel(\"retry ×\" + s.retry.max)}| e${idFor(s.retry.otherwise)}`,\n            )\n          }\n        })\n\n        solid.forEach((labels, key) => {\n          const [from, to] = key.split(\" \")\n          const label = labels.length === 1 ? mlabel(labels[0]) : null\n          lines.push(`  ${from} -->${label ? \"|\" + label + \"|\" : \"\"} ${to}`)\n        })\n        dashed.forEach((labels, key) => {\n          const [from, to] = key.split(\" \")\n          const label = labels.length === 1 ? mlabel(labels[0]) : null\n          lines.push(`  ${from} -.->${label ? \"|\" + label + \"|\" : \"\"} ${to}`)\n        })\n\n        lines.push(...classDefs(isDark()))\n        return lines.join(\"\\n\")\n      }\n\n      document.getElementById(\"diaNote\").innerHTML =\n        `Every state as a node — shape is the content kind, colour is the actor. Each edge is an ` +\n        `<span class=\"mono\">on</span> pattern (first match wins); dashed edges are ` +\n        `<span class=\"mono\">retry</span> redirects. A sub-machine invocation collapses into a single ` +\n        `dark box (click it to jump to its own diagram below); an edge label is dropped when several ` +\n        `patterns collapse onto the same box-to-box edge. Scroll/pinch or drag to pan and zoom; use the ` +\n        `<span class=\"mono\">+</span>/<span class=\"mono\">−</span>/<span class=\"mono\">⤢</span> controls in the corner.`\n\n      // ── diagram render (theme-aware, offline-tolerant) ─────────────────\n      async function loadMermaid() {\n        if (mermaidMod) return mermaidMod\n        const m = await import(\"https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs\")\n        mermaidMod = m.default\n        return mermaidMod\n      }\n\n      const renderSeqByBase = new Map()\n      const nextSeq = (base) => {\n        const n = (renderSeqByBase.get(base) || 0) + 1\n        renderSeqByBase.set(base, n)\n        return n\n      }\n\n      /** Render `src` into `host` via mermaid, guarding against a stale (superseded) render; falls back to a readable error + raw source on failure. Returns the mermaid render id used (so the caller can wire clicks/highlight against ITS OWN node ids), or `null` if nothing rendered. */\n      async function renderInto(host, src, renderIdBase) {\n        const seq = nextSeq(renderIdBase)\n        let mermaid\n        try {\n          mermaid = await loadMermaid()\n        } catch (e) {\n          host.innerHTML =\n            `<div class=\"dia-msg\">Could not load the Mermaid renderer (offline?). ` +\n            `The workflow is still fully browsable below. Diagram source:` +\n            `<pre class=\"dia-src\">${esc(src)}</pre></div>`\n          return null\n        }\n        if (seq !== renderSeqByBase.get(renderIdBase)) return null\n        const renderId = renderIdBase + seq\n        try {\n          const { svg } = await mermaid.render(renderId, src)\n          if (seq !== renderSeqByBase.get(renderIdBase)) return null\n          host.innerHTML = `<div class=\"mflow\">${svg}</div>`\n          return renderId\n        } catch (e) {\n          host.innerHTML =\n            `<div class=\"dia-msg\">Diagram render failed: ${esc(e.message)}. ` +\n            `Diagram source:<pre class=\"dia-src\">${esc(src)}</pre></div>`\n          return null\n        }\n      }\n\n      // Every live diagram (main + one per sub-machine) — re-rendered as a\n      // group on every theme toggle (replaces the old single DIAGRAM_SRC).\n      // `build` is a thunk (not a fixed string) because the diagram source\n      // embeds theme-dependent classDefs — it must be re-emitted fresh on\n      // every re-render, not cached from first render.\n      const diagrams = []\n      function registerDiagram(host, build, renderIdBase, onRendered, highlight) {\n        diagrams.push({ host, build, renderIdBase, onRendered, highlight, lastRenderId: null })\n      }\n      async function renderAllDiagrams() {\n        for (const d of diagrams) {\n          const renderId = await renderInto(d.host, d.build(), d.renderIdBase)\n          if (renderId) d.lastRenderId = renderId\n          if (renderId && d.onRendered) d.onRendered(renderId, d.host)\n        }\n      }\n      async function reinitializeAndRenderAll() {\n        const mermaid = await loadMermaid().catch(() => null)\n        if (mermaid) {\n          const dark = isDark()\n          mermaid.initialize({\n            startOnLoad: false,\n            theme: \"base\",\n            securityLevel: \"strict\",\n            flowchart: { useMaxWidth: false, htmlLabels: true },\n            themeVariables: {\n              fontFamily: \"ui-monospace, Menlo, monospace\",\n              fontSize: \"12.5px\",\n              lineColor: dark ? \"#6b7690\" : \"#8a93a6\",\n              primaryBorderColor: dark ? \"#3a465c\" : \"#c2ccdb\",\n              tertiaryColor: dark ? \"#1c2434\" : \"#f0f3f8\",\n              mainBkg: dark ? \"#232c3e\" : \"#ffffff\",\n              clusterBkg: dark ? \"#1c2434\" : \"#f0f3f8\",\n              clusterBorder: dark ? \"#3a465c\" : \"#c2ccdb\",\n              titleColor: dark ? \"#e6ebf4\" : \"#1a2233\",\n              nodeTextColor: dark ? \"#e6ebf4\" : \"#1a2233\",\n              textColor: dark ? \"#e6ebf4\" : \"#1a2233\",\n              edgeLabelBackground: dark ? \"#161d2b\" : \"#f4f6fa\",\n            },\n          })\n        }\n        await renderAllDiagrams()\n      }\n\n      // ── click wiring + current-state highlight (post-render — mermaid's own\n      // `click` callbacks are disabled by securityLevel:\"strict\") ──────────\n      // A rendered node group's `id` is `${renderId}-flowchart-${ourNodeId}-<n>`\n      // (verified against mermaid@11's actual output) — strip that wrapper to\n      // recover the id we generated the diagram with.\n      function nodeIdOf(el, renderId) {\n        const prefix = renderId + \"-flowchart-\"\n        if (!el.id || !el.id.startsWith(prefix)) return null\n        const m = /^(.+)-\\d+$/.exec(el.id.slice(prefix.length))\n        return m ? m[1] : null\n      }\n      const nodeGroupsOf = (host) => [...host.querySelectorAll(\"g.node\")]\n\n      function scrollToSubmachine(i) {\n        const el = document.getElementById(\"sm-\" + i)\n        if (!el) return\n        el.open = true\n        el.scrollIntoView({ behavior: \"smooth\", block: \"start\" })\n      }\n      function navigateTo(name) {\n        const s = byName[name]\n        if (s && s.group) {\n          const gi = groupIndexOf(s.group)\n          if (gi >= 0) return scrollToSubmachine(gi)\n        }\n        openDrawer(name)\n      }\n\n      function applyCurrentHighlight(renderId, host, mode, gi) {\n        if (!CURRENT || !CURRENT.state) return\n        const wantId =\n          mode === \"main\"\n            ? CURRENT.group\n              ? groupBoxId(groupIndexOf(CURRENT.group))\n              : idFor(CURRENT.state)\n            : CURRENT.group === MODEL.groups[gi].name\n              ? idFor(CURRENT.state)\n              : null\n        if (wantId === null) return\n        nodeGroupsOf(host).forEach((el) => {\n          if (nodeIdOf(el, renderId) === wantId) el.classList.add(\"gtd-current\")\n        })\n      }\n\n      // Re-applies the current-state highlight to every already-rendered\n      // diagram, without re-running mermaid — used by the poll loop below.\n      function repaintHighlights() {\n        for (const d of diagrams) {\n          nodeGroupsOf(d.host).forEach((el) => el.classList.remove(\"gtd-current\"))\n          if (d.lastRenderId && d.highlight) {\n            applyCurrentHighlight(d.lastRenderId, d.host, d.highlight.mode, d.highlight.gi)\n          }\n        }\n      }\n\n      function wireMainDiagramClicks(renderId, host) {\n        nodeGroupsOf(host).forEach((el) => {\n          const rawId = nodeIdOf(el, renderId)\n          if (!rawId) return\n          el.classList.add(\"clickable\")\n          el.style.cursor = \"pointer\"\n          if (rawId[0] === \"g\") {\n            el.onclick = () => scrollToSubmachine(Number(rawId.slice(1)))\n          } else {\n            const name = idFor.nameOf(rawId)\n            if (name) el.onclick = () => openDrawer(name)\n          }\n        })\n        applyCurrentHighlight(renderId, host, \"main\")\n        attachPanZoom(host)\n      }\n\n      function wireSubmachineDiagramClicks(renderId, host, gi) {\n        nodeGroupsOf(host).forEach((el) => {\n          const rawId = nodeIdOf(el, renderId)\n          if (!rawId) return\n          el.classList.add(\"clickable\")\n          el.style.cursor = \"pointer\"\n          if (rawId[0] === \"g\") {\n            el.onclick = () => scrollToSubmachine(Number(rawId.slice(1)))\n          } else if (rawId[0] === \"e\") {\n            const name = idFor.nameOf(rawId.slice(1))\n            if (name) el.onclick = () => navigateTo(name)\n          } else {\n            const name = idFor.nameOf(rawId)\n            if (name) el.onclick = () => openDrawer(name)\n          }\n        })\n        applyCurrentHighlight(renderId, host, \"submachine\", gi)\n        attachPanZoom(host)\n      }\n\n      // ── diagram pan & zoom (hand-rolled — no pan-zoom dependency, see plan) ──\n      // `host` is a `.dia-scroll` element whose content mermaid just replaced\n      // wholesale (`renderInto`'s `host.innerHTML = ...`), so old listeners on\n      // its previous children are already gone — this re-creates the control\n      // cluster and re-attaches fresh listeners on every render, never\n      // accumulating stale ones.\n      const REDUCED_MOTION = matchMedia(\"(prefers-reduced-motion: reduce)\").matches\n      const clampScale = (s) => Math.min(3, Math.max(0.4, s))\n\n      function attachPanZoom(host) {\n        const flow = host.querySelector(\".mflow\")\n        const svg = flow && flow.querySelector(\"svg\")\n        if (!flow || !svg) return\n\n        const controls = document.createElement(\"div\")\n        controls.className = \"pz-controls\"\n        controls.innerHTML =\n          `<button class=\"pz-btn\" data-act=\"in\" title=\"Zoom in\" aria-label=\"Zoom in\">+</button>` +\n          `<button class=\"pz-btn\" data-act=\"out\" title=\"Zoom out\" aria-label=\"Zoom out\">−</button>` +\n          `<button class=\"pz-btn\" data-act=\"fit\" title=\"Fit to width\" aria-label=\"Fit to width\">⤢</button>`\n        host.appendChild(controls)\n\n        const box = svg.getBBox ? svg.getBBox() : { width: 0, height: 0 }\n        const naturalWidth = box.width || svg.clientWidth || 1\n        const naturalHeight = box.height || svg.clientHeight || 1\n\n        const state = { scale: 1, tx: 0, ty: 0 }\n        const apply = () => {\n          flow.style.transform = `translate(${state.tx}px, ${state.ty}px) scale(${state.scale})`\n        }\n        // Fit-to-width, capped at 1× so a small workflow renders at its\n        // natural size (the pre-pan/zoom default) instead of being blown up.\n        const fit = () => {\n          const r = host.getBoundingClientRect()\n          state.scale = clampScale(Math.min(1, Math.max(r.width - 32, 40) / naturalWidth))\n          state.tx = (r.width - naturalWidth * state.scale) / 2\n          state.ty = (r.height - naturalHeight * state.scale) / 2\n          apply()\n        }\n        const zoomBy = (factor, cx, cy) => {\n          const r = host.getBoundingClientRect()\n          const px = cx == null ? r.width / 2 : cx\n          const py = cy == null ? r.height / 2 : cy\n          const next = clampScale(state.scale * factor)\n          const ratio = next / state.scale\n          state.tx = px - (px - state.tx) * ratio\n          state.ty = py - (py - state.ty) * ratio\n          state.scale = next\n          apply()\n        }\n        // Animate only a button-triggered zoom/fit (an explicit, discrete\n        // action) — wheel/drag stay instant so the transform tracks the\n        // cursor/finger with no lag. Skipped entirely under\n        // prefers-reduced-motion.\n        const animated = (fn) => {\n          if (REDUCED_MOTION) return fn()\n          flow.style.transition = \"transform 0.18s ease\"\n          fn()\n          flow.addEventListener(\"transitionend\", () => (flow.style.transition = \"\"), {\n            once: true,\n          })\n        }\n        fit()\n\n        host.addEventListener(\n          \"wheel\",\n          (e) => {\n            e.preventDefault()\n            flow.style.transition = \"none\"\n            const r = host.getBoundingClientRect()\n            zoomBy(e.deltaY < 0 ? 1.12 : 1 / 1.12, e.clientX - r.left, e.clientY - r.top)\n          },\n          { passive: false },\n        )\n\n        // Drag-to-pan: a small movement threshold before a pointerdown counts\n        // as a drag (rather than a click), and — once it does — the resulting\n        // synthetic `click` is swallowed so dragging over a node never opens\n        // its drawer. Pointer capture is deferred until that threshold is\n        // actually crossed: a captured pointer retargets its WHOLE mouse-event\n        // sequence (including the eventual `click`) to `host`, so capturing\n        // eagerly on every pointerdown would silently break a plain click on\n        // any node (or the zoom/fit buttons) — not just an actual drag.\n        let drag = null\n        host.addEventListener(\"pointerdown\", (e) => {\n          if (e.button !== 0 || e.target.closest(\".pz-controls\")) return\n          drag = { x: e.clientX, y: e.clientY, tx: state.tx, ty: state.ty, moved: false }\n          flow.style.transition = \"none\"\n        })\n        host.addEventListener(\"pointermove\", (e) => {\n          if (!drag) return\n          const dx = e.clientX - drag.x\n          const dy = e.clientY - drag.y\n          if (!drag.moved && Math.hypot(dx, dy) > 4) {\n            drag.moved = true\n            host.classList.add(\"pz-dragging\")\n            host.setPointerCapture(e.pointerId)\n          }\n          if (drag.moved) {\n            state.tx = drag.tx + dx\n            state.ty = drag.ty + dy\n            apply()\n          }\n        })\n        const endDrag = () => {\n          if (!drag) return\n          if (drag.moved) {\n            host.classList.remove(\"pz-dragging\")\n            host.addEventListener(\n              \"click\",\n              (ev) => {\n                ev.stopPropagation()\n                ev.preventDefault()\n              },\n              { capture: true, once: true },\n            )\n          }\n          drag = null\n        }\n        host.addEventListener(\"pointerup\", endDrag)\n        host.addEventListener(\"pointercancel\", endDrag)\n\n        controls.querySelector('[data-act=\"in\"]').onclick = (e) => {\n          e.stopPropagation()\n          animated(() => zoomBy(1.25))\n        }\n        controls.querySelector('[data-act=\"out\"]').onclick = (e) => {\n          e.stopPropagation()\n          animated(() => zoomBy(1 / 1.25))\n        }\n        controls.querySelector('[data-act=\"fit\"]').onclick = (e) => {\n          e.stopPropagation()\n          animated(fit)\n        }\n\n        // Exposed so a collapsed sub-machine `<details>` panel can re-fit once\n        // it's actually opened (its content renders at zero width while hidden).\n        host.__pz = { fit, zoomBy }\n      }\n\n      // ── main flow ────────────────────────────────────────────────────────\n      registerDiagram(\n        document.getElementById(\"diaScroll\"),\n        () => buildFlowSrc(STATES, {}),\n        \"gtdmain\",\n        wireMainDiagramClicks,\n        { mode: \"main\" },\n      )\n\n      // ── sub-machines panel — one real mermaid diagram per invocation ─────\n      ;(function renderSubmachines() {\n        const el = document.getElementById(\"smSection\")\n        const groups = MODEL.groups || []\n        if (!groups.length) {\n          el.innerHTML = `<p class=\"muted-note\">This workflow declares no sub-machines.</p>`\n          return\n        }\n        el.innerHTML = \"\"\n        groups.forEach((g, i) => {\n          const card = document.createElement(\"details\")\n          card.className = \"dia-card sm-card\"\n          card.id = \"sm-\" + i\n          card.style.marginBottom = \"16px\"\n          card.style.marginLeft = (g.depth || 0) * 24 + \"px\"\n          if (CURRENT && CURRENT.group === g.name) card.open = true\n          card.innerHTML =\n            `<summary class=\"h\"><span class=\"nm\">${esc(g.name)} · instantiates <b>${esc(g.machine)}</b>${\n              g.model ? ` · model: ${esc(g.model)}` : \"\"\n            }</span></summary>` +\n            `<div class=\"dia-scroll\" id=\"smDia${i}\"><div class=\"dia-msg\">Rendering diagram…</div></div>`\n          el.appendChild(card)\n\n          const members = allStatesOf(g)\n            .map((n) => byName[n])\n            .filter(Boolean)\n          registerDiagram(\n            card.querySelector(`#smDia${i}`),\n            () => buildFlowSrc(members, { scope: g.name }),\n            \"gtdsm\" + i + \"-\",\n            (renderId, host) => wireSubmachineDiagramClicks(renderId, host, i),\n            { mode: \"submachine\", gi: i },\n          )\n          // A collapsed <details> renders its content at zero width, so the\n          // pan/zoom \"fit\" computed while hidden is wrong — recompute it once\n          // the panel is actually opened.\n          card.addEventListener(\"toggle\", () => {\n            if (!card.open) return\n            const host = card.querySelector(`#smDia${i}`)\n            if (host && host.__pz) host.__pz.fit()\n          })\n        })\n      })()\n\n      // ── vars ─────────────────────────────────────────────────────────────\n      ;(function renderVars() {\n        const vars = MODEL.vars || {}\n        const keys = Object.keys(vars)\n        if (!keys.length) return\n        const el = document.getElementById(\"varsSection\")\n        el.innerHTML =\n          `<div class=\"sec-head\"><h2>Workflow variables</h2><span class=\"rule\"></span></div>` +\n          `<div class=\"vars-grid\">${keys\n            .map((k) => `<span class=\"var-chip\"><b>${esc(k)}</b> = ${esc(vars[k])}</span>`)\n            .join(\"\")}</div>`\n      })()\n\n      // ── current-state panel ─────────────────────────────────────────────\n      // Status-letter colour reuses existing actor tokens rather than adding new\n      // theme variables: A (added) reads as the check colour, M (modified) as\n      // the accent, D (deleted) as the engine/commit colour.\n      const PENDING_STATUS_COLOR = {\n        A: \"var(--check-fg)\",\n        M: \"var(--accent)\",\n        D: \"var(--engine-fg)\",\n      }\n      function pendingListHtml(pending) {\n        if (!pending || !pending.length) {\n          return `<p class=\"pending-clean\">working tree clean</p>`\n        }\n        return (\n          `<div class=\"pending-list\">` +\n          pending\n            .map(\n              (c) =>\n                `<div class=\"pc\"><span class=\"st\" style=\"color:${PENDING_STATUS_COLOR[c.status] || \"var(--text-dim)\"}\">${esc(c.status)}</span><span class=\"path\">${esc(c.path)}</span></div>`,\n            )\n            .join(\"\") +\n          `</div>`\n        )\n      }\n      function renderCurrentPanel() {\n        const panel = document.getElementById(\"currentPanel\")\n        if (!CURRENT || !CURRENT.state) {\n          panel.classList.add(\"hidden\")\n          return\n        }\n        panel.classList.remove(\"hidden\")\n        const a = CURRENT.actor\n        const edgeRow = (pattern, to, matched, retryOf, action) => {\n          const t = byName[to]\n          return (\n            `<div class=\"edge${matched ? \" cur-matched\" : \"\"}\"><div class=\"er\">` +\n            `${action ? `<span class=\"act\">${esc(action)}</span>` : \"\"}` +\n            `<span class=\"pat\">${retryOf ? \"after \" + esc(retryOf) + \" tries\" : \"if \" + esc(pattern)}</span>` +\n            `<span class=\"arr\">→</span>` +\n            `<button class=\"goto\" data-actor=\"${t ? actorOf(t) : \"unknown\"}\" data-to=\"${esc(to)}\">${esc(to)}</button>` +\n            `${matched ? '<span class=\"cur-tag\">current match</span>' : \"\"}</div></div>`\n          )\n        }\n        const rows = (CURRENT.edges || [])\n          .map((e) => edgeRow(e.pattern, e.to, e.matched, undefined, e.action))\n          .join(\"\")\n        const retryRow = CURRENT.retry\n          ? edgeRow(null, CURRENT.retry.otherwise, false, CURRENT.retry.max, undefined)\n          : \"\"\n        panel.innerHTML =\n          `<div class=\"cur-head\"><span class=\"cur-name\">${esc(CURRENT.state)}</span>` +\n          `${pill(a)}<span class=\"kind\">${esc(CURRENT.kind)}</span>` +\n          `${CURRENT.group ? `<span class=\"flow-tag\">${esc(CURRENT.group)}</span>` : \"\"}</div>` +\n          `<div style=\"margin-top:14px\">${pendingListHtml(CURRENT.pending)}</div>` +\n          `<div class=\"edges\">${\n            rows || retryRow ? rows + retryRow : '<p class=\"none\">No outgoing edges declared.</p>'\n          }</div>`\n        panel.querySelector(\".cur-head\").onclick = () => navigateTo(CURRENT.state)\n        panel.querySelectorAll(\".goto\").forEach((b) => (b.onclick = () => navigateTo(b.dataset.to)))\n      }\n      renderCurrentPanel()\n\n      reinitializeAndRenderAll()\n\n      // ── live current-state polling ──────────────────────────────────────\n      // Keeps the panel + diagram highlight in sync with an in-progress\n      // process without a manual page refresh. Skipped while the tab is\n      // hidden; becoming visible again triggers an immediate refresh. No\n      // in-flight guard — a slow tick just means the next one also awaits.\n      async function poll() {\n        if (document.hidden) return\n        const changed = await refreshCurrent()\n        if (changed) {\n          renderCurrentPanel()\n          repaintHighlights()\n        }\n      }\n      setInterval(poll, 3000)\n      document.addEventListener(\"visibilitychange\", () => {\n        if (!document.hidden) poll()\n      })\n\n      // ── kind chips + actor legend ──────────────────────────────────────\n      const kindChipsEl = document.getElementById(\"kindChips\")\n      const presentKinds = [\"all\", ...Array.from(new Set(STATES.map((s) => s.kind)))]\n      presentKinds.forEach((k) => {\n        const b = document.createElement(\"button\")\n        b.className = \"chip-btn\" + (k === \"all\" ? \" on\" : \"\")\n        b.textContent = k\n        b.dataset.kind = k\n        b.onclick = () => {\n          kindFilter = k\n          ;[...kindChipsEl.children].forEach((c) =>\n            c.classList.toggle(\"on\", c.dataset.kind === kindFilter),\n          )\n          renderCatalogue()\n        }\n        kindChipsEl.appendChild(b)\n      })\n\n      const legendEl = document.getElementById(\"legend\")\n      ;[\"human\", \"agent\", \"check\", \"commit\", \"unknown\"].forEach((a) => {\n        if (!counts[a]) return\n        const el = document.createElement(\"button\")\n        el.className = \"li\"\n        el.dataset.actor = a\n        el.setAttribute(\"aria-pressed\", \"true\")\n        el.innerHTML = `<span class=\"dot\" style=\"background:var(--${meta(a).dot}-dot)\"></span>${meta(a).label}`\n        el.onclick = () => {\n          const on = actorFilter.has(a)\n          on ? actorFilter.delete(a) : actorFilter.add(a)\n          el.classList.toggle(\"off\", on)\n          el.setAttribute(\"aria-pressed\", String(!on))\n          renderCatalogue()\n        }\n        legendEl.appendChild(el)\n      })\n\n      // ── catalogue ──────────────────────────────────────────────────────\n      const groupsEl = document.getElementById(\"groups\")\n      function stateMatches(s, q) {\n        if (!actorFilter.has(actorOf(s))) return false\n        if (kindFilter !== \"all\" && s.kind !== kindFilter) return false\n        if (!q) return true\n        const hay = [s.name, s.actor, s.kind, s.file, s.mode, s.model, (s.flags || []).join(\" \")]\n          .filter(Boolean)\n          .join(\" \")\n          .toLowerCase()\n        return hay.includes(q)\n      }\n      function cardFor(s) {\n        const a = actorOf(s)\n        const card = document.createElement(\"button\")\n        card.className = \"card\"\n        card.dataset.actor = a\n        const flags = (s.flags || [])\n          .filter((f) => f !== \"initial\")\n          .map((f) => `<span class=\"flag\">${esc(f)}</span>`)\n          .join(\"\")\n        const retry = s.retry ? `<span class=\"flag\">retry ${s.retry.max}</span>` : \"\"\n        const initTick = s.initial ? `<div class=\"init-tick\">initial</div>` : \"\"\n        card.innerHTML =\n          `${initTick}<div class=\"name\">${esc(s.name)}</div>` +\n          `<div class=\"row\">${pill(a)}<span class=\"kind\">${esc(s.kind)}</span>${retry}${flags}</div>`\n        card.onclick = () => openDrawer(s.name)\n        return card\n      }\n      function renderCatalogue() {\n        const q = document.getElementById(\"search\").value.trim().toLowerCase()\n        groupsEl.innerHTML = \"\"\n        const sections = []\n        ;(MODEL.groups || []).forEach((g) => {\n          sections.push({\n            label: g.name,\n            flow: g.machine,\n            items: STATES.filter((s) => s.group === g.name),\n          })\n        })\n        const ungrouped = STATES.filter((s) => !s.group)\n        if (ungrouped.length) sections.push({ label: \"Ungrouped\", flow: \"\", items: ungrouped })\n\n        let shown = 0\n        sections.forEach((sec) => {\n          const items = sec.items.filter((s) => stateMatches(s, q))\n          if (!items.length) return\n          shown += items.length\n          const wrap = document.createElement(\"div\")\n          wrap.className = \"group\"\n          wrap.innerHTML =\n            `<div class=\"group-head\">${sec.flow ? `<span class=\"flow-tag\">${esc(sec.flow)}</span>` : \"\"}` +\n            `<h3>${esc(sec.label)}</h3></div>`\n          const grid = document.createElement(\"div\")\n          grid.className = \"grid\"\n          items.forEach((s) => grid.appendChild(cardFor(s)))\n          wrap.appendChild(grid)\n          groupsEl.appendChild(wrap)\n        })\n        if (!shown)\n          groupsEl.innerHTML = `<p class=\"none\" style=\"padding:20px 0\">No states match this filter.</p>`\n      }\n      document.getElementById(\"search\").addEventListener(\"input\", renderCatalogue)\n      renderCatalogue()\n\n      // ── drawer ─────────────────────────────────────────────────────────\n      const drawer = document.getElementById(\"drawer\")\n      const backdrop = document.getElementById(\"backdrop\")\n      let lastFocus = null\n\n      function openDrawer(name) {\n        const s = byName[name]\n        if (!s) return\n        const a = actorOf(s)\n        if (!drawer.classList.contains(\"open\")) lastFocus = document.activeElement\n\n        const kv = []\n        kv.push([\"actor\", pill(a)])\n        kv.push([\"kind\", `<span class=\"kind\">${esc(s.kind)}</span>`])\n        kv.push([\"model\", s.model ? esc(s.model) : '<span class=\"none\">—</span>'])\n        kv.push([\"file\", s.file ? esc(s.file) : '<span class=\"none\">—</span>'])\n        kv.push([\"mode\", s.mode ? esc(s.mode) : '<span class=\"none\">—</span>'])\n        if (s.retry)\n          kv.push([\n            \"retry\",\n            `max ${s.retry.max} → <span style=\"color:var(--accent)\">${esc(s.retry.otherwise)}</span>`,\n          ])\n        if (s.group) kv.push([\"group\", esc(s.group)])\n\n        const contentBlock = s.content\n          ? `<div class=\"field\"><div class=\"k\">content — ${esc(s.kind)}</div><pre class=\"dia-src state-content\">${esc(s.content)}</pre></div>`\n          : \"\"\n\n        const flags = s.flags || []\n        const flagBlock = flags.length\n          ? `<div class=\"field\"><div class=\"k\">flags & gates</div><div class=\"flag-list\">${flags\n              .map(\n                (f) =>\n                  `<div class=\"flag-item\"><span class=\"fn\">${esc(f)}</span><span class=\"fd\">${esc(FLAGS[f] || \"\")}</span></div>`,\n              )\n              .join(\"\")}</div></div>`\n          : \"\"\n\n        const edges = s.on || []\n        const edgesBlock = edges.length\n          ? `<div class=\"field\"><div class=\"k\">outgoing edges — on (first match wins)</div><div class=\"edges\">${edges\n              .map((e) => {\n                const t = byName[e.to]\n                const ta = t ? actorOf(t) : \"unknown\"\n                return (\n                  `<div class=\"edge\"><div class=\"er\">${\n                    e.action ? `<span class=\"act\">${esc(e.action)}</span>` : \"\"\n                  }<span class=\"pat\">${esc(e.pattern)}</span><span class=\"arr\">→</span>` +\n                  `<button class=\"goto\" data-actor=\"${ta}\" data-to=\"${esc(e.to)}\">${esc(e.to)}</button></div>` +\n                  `${e.describe ? `<div class=\"em\">${esc(e.describe)}</div>` : \"\"}</div>`\n                )\n              })\n              .join(\"\")}</div></div>`\n          : `<div class=\"field\"><div class=\"k\">outgoing edges</div><p class=\"none\">${\n              s.kind === \"commit\"\n                ? \"Commit state — no outgoing edges. Entering it ends the process in one squash.\"\n                : \"No outgoing edges declared.\"\n            }</p></div>`\n\n        const retryOut =\n          s.retry && byName[s.retry.otherwise]\n            ? `<div class=\"field\"><div class=\"k\">retry redirect</div><div class=\"edge\"><div class=\"er\">` +\n              `<span class=\"pat\">after ${esc(s.retry.max)} tries</span><span class=\"arr\">→</span>` +\n              `<button class=\"goto\" data-actor=\"${actorOf(byName[s.retry.otherwise])}\" data-to=\"${esc(s.retry.otherwise)}\">${esc(s.retry.otherwise)}</button>` +\n              `</div></div></div>`\n            : \"\"\n\n        const inc = s.incoming || []\n        const incBlock =\n          `<div class=\"field\"><div class=\"k\">routes in from (${inc.length})</div>` +\n          (inc.length\n            ? `<div class=\"incoming\">${inc\n                .map((i) => {\n                  const f = byName[i.from]\n                  return `<button class=\"goto\" data-actor=\"${f ? actorOf(f) : \"unknown\"}\" data-to=\"${esc(i.from)}\" title=\"${esc(i.pattern)}\">${esc(i.from)}</button>`\n                })\n                .join(\"\")}</div>`\n            : `<p class=\"none\">Reached only as an entry point (a CLI command enters it directly).</p>`) +\n          `</div>`\n\n        drawer.style.setProperty(\"--card-accent\", `var(--${meta(a).dot}-dot)`)\n        drawer.innerHTML =\n          `<div class=\"drawer-head\" style=\"--card-accent:var(--${meta(a).dot}-dot)\">` +\n          `<div class=\"top\"><h3>${esc(s.name)}</h3>` +\n          `<button class=\"close-x\" id=\"closeX\" aria-label=\"Close detail\">✕</button></div>` +\n          `<div class=\"meta-row\">${pill(a)}<span class=\"kind\">${esc(s.kind)}</span>` +\n          `${s.initial ? '<span class=\"flag\">initial</span>' : \"\"}` +\n          `${s.retry ? `<span class=\"flag\">retry ${s.retry.max}</span>` : \"\"}` +\n          `${flags\n            .filter((f) => f !== \"initial\")\n            .map((f) => `<span class=\"flag\">${esc(f)}</span>`)\n            .join(\"\")}</div></div>` +\n          `<div class=\"drawer-body\">` +\n          `<div class=\"field\"><div class=\"k\">definition</div><dl class=\"kv\">${kv\n            .map(([k, v]) => `<dt>${esc(k)}</dt><dd>${v}</dd>`)\n            .join(\"\")}</dl></div>` +\n          contentBlock +\n          flagBlock +\n          edgesBlock +\n          retryOut +\n          incBlock +\n          `</div>`\n\n        drawer\n          .querySelectorAll(\".goto\")\n          .forEach((b) => (b.onclick = () => openDrawer(b.dataset.to)))\n        drawer.querySelector(\"#closeX\").onclick = closeDrawer\n\n        backdrop.classList.add(\"open\")\n        drawer.classList.add(\"open\")\n        drawer.querySelector(\".drawer-body\").scrollTop = 0\n        drawer.querySelector(\"#closeX\").focus()\n      }\n      function closeDrawer() {\n        backdrop.classList.remove(\"open\")\n        drawer.classList.remove(\"open\")\n        if (lastFocus && lastFocus.focus) lastFocus.focus()\n      }\n      backdrop.onclick = closeDrawer\n      document.addEventListener(\"keydown\", (e) => {\n        if (e.key === \"Escape\" && drawer.classList.contains(\"open\")) closeDrawer()\n      })\n\n      // expose for interactions\n      window.__openState = openDrawer\n    <\/script>\n  </body>\n</html>\n";
 //#endregion
 //#region src/Visualize.ts
 const FLAG_KEYS = [
 	"reviewWindow",
 	"reviewBase",
-	"reviewEntry",
-	"fixEntry",
 	"requireProgress",
 	"answerGate"
 ];
@@ -204403,19 +204892,18 @@ const stripUndefined = (o) => {
 	for (const key of Object.keys(o)) if (o[key] === void 0) delete o[key];
 	return o;
 };
-/** Describe one compiled state for the viewer (optional fields omitted when unset). `onEdges` is that state's `on`, ALREADY RENDERED against `it.vars` (see `buildVizModel`) — never `def.on` directly, which would show the unrendered literal. */
-const toVizState = (name, def, onEdges, group, incoming) => stripUndefined({
+/** Describe one compiled state for the viewer (optional fields omitted when unset). `onEdges` is that state's `on`, ALREADY RENDERED against `it.vars` (see `buildVizModel`) — never `def.on` directly, which would show the unrendered literal. `entries` is the workflow's `entries` — `name`'s match against `.default`/`.manual` drives `initial`/the `entry` flag. */
+const toVizState = (name, def, onEdges, group, incoming, entries) => stripUndefined({
 	name,
 	actor: def.actor,
 	kind: contentKindOf(def) ?? "unknown",
 	content: contentOf(def),
-	initial: def.initial === true ? true : void 0,
+	initial: entries.default === name ? true : void 0,
 	model: def.model,
-	memory: def.memory,
 	file: def.file,
 	mode: def.mode,
 	retry: def.retry,
-	flags: flagsOf(def),
+	flags: [...flagsOf(def), ...entries.manual.includes(name) ? ["entry"] : []],
 	on: onEdges.map(edgeToViz),
 	incoming,
 	group
@@ -204443,22 +204931,64 @@ const renderedOnByState = (workflow, vars) => new Map(Object.entries(workflow.st
 		describe
 	] : [renderedPattern, target];
 })]));
-/**
-* Build the viewer's JSON description from the active COMPILED workflow plus its
-* RAW value (the pre-expansion `submachines:`/`use:` form — `rawWorkflow` from
-* `ConfigService`), which is the only place the sub-machine grouping survives
-* (`compileWorkflowConfig` flattens it away). `vars` is shown for reference, AND
-* used to render every state's `on` pattern (see `renderedOnByState`) so the
-* diagram shows real paths rather than a repointed var's stale literal.
-*/
-const buildVizModel = (workflow, rawWorkflow, vars) => {
-	const groups = collectGroups(rawWorkflow);
-	const sizeOf = new Map(groups.map((g) => [g.name, g.states.length]));
-	const groupOf = /* @__PURE__ */ new Map();
-	for (const g of groups) for (const s of g.states) {
-		const cur = groupOf.get(s);
-		if (cur === void 0 || sizeOf.get(g.name) < sizeOf.get(cur)) groupOf.set(s, g.name);
-	}
+/** A state's owning instance path, straight from `scopes` (`CompiledWorkflowConfig.scopes`/`ConfigOperations.stateScopes`) — a direct lookup, NOT a string chop off the qualified name (a state's group is not always "everything before the last dot"). `""` (the root instance's own path) means root-owned, reported as `undefined` here — same convention `VizState.group` has always had for a root-owned state. */
+const groupOf = (name, scopes) => {
+	const scope = scopes[name];
+	return scope === "" || scope === void 0 ? void 0 : scope;
+};
+/**
+* Flatten a `MachineNode` tree (`CompiledWorkflowConfig.tree`, from
+* `src/Machines.ts`'s `flattenMachines`) into `VizModel.groups` — a flat,
+* depth-first array of every instance STRICTLY BELOW the root (the root
+* machine itself is the canvas, never a box). Kept flat (rather than a
+* recursive payload) so every index-based front-end helper
+* (`groupBoxId`/`groupIndexOf`/`scrollToSubmachine`/etc — `src/visualize.html`)
+* keeps working unchanged.
+*/
+const flattenTree = (node, parent, depth, out) => {
+	for (const child of node.children) {
+		out.push({
+			name: child.key,
+			machine: child.machine,
+			states: [...child.states],
+			...parent !== void 0 ? { parent } : {},
+			depth
+		});
+		flattenTree(child, child.key, depth + 1, out);
+	}
+};
+/**
+* The `model` of one group — a machine instance's own `model:`, read off any
+* ONE of that group's own prompt-content states (by construction every prompt
+* state one machine instance owns carries the identical `def.model` — see
+* `Machines.ts`'s `resolveInstanceModel`/`emitTree`). `undefined` when the
+* group owns no prompt state (e.g. a queue/gate machine of only
+* script/message/commit states) or its machine declares no `model:` — never
+* guessed.
+*/
+const modelOfGroup = (groupName, workflow, scopes) => {
+	for (const [name, def] of Object.entries(workflow.states)) if (scopes[name] === groupName && contentKindOf(def) === "prompt") return def.model;
+};
+/**
+* Build the viewer's JSON description from the active COMPILED workflow plus
+* the machine tree its flattening produced (`CompiledWorkflowConfig.tree`)
+* and the memory-scope map its flattening produced alongside it
+* (`CompiledWorkflowConfig.scopes`/`ConfigOperations.stateScopes`) — qualified
+* state name -> the machine-instance path that owns it. `vars` is shown for
+* reference, AND used to render every state's `on` pattern (see
+* `renderedOnByState`) so the diagram shows real paths rather than a
+* repointed var's stale literal.
+*/
+const buildVizModel = (workflow, tree, vars, scopes) => {
+	const flatGroups = [];
+	flattenTree(tree, void 0, 0, flatGroups);
+	const groups = flatGroups.map((group) => {
+		const model = modelOfGroup(group.name, workflow, scopes);
+		return model !== void 0 ? {
+			...group,
+			model
+		} : group;
+	});
 	const renderedOn = renderedOnByState(workflow, vars);
 	const incoming = /* @__PURE__ */ new Map();
 	const addIncoming = (target, from, pattern) => {
@@ -204474,13 +205004,9 @@ const buildVizModel = (workflow, rawWorkflow, vars) => {
 		if (def.retry) addIncoming(def.retry.otherwise, name, `retry ×${def.retry.max}`);
 	}
 	return {
-		states: Object.entries(workflow.states).map(([name, def]) => toVizState(name, def, renderedOn.get(name) ?? [], groupOf.get(name), incoming.get(name) ?? [])),
+		states: Object.entries(workflow.states).map(([name, def]) => toVizState(name, def, renderedOn.get(name) ?? [], groupOf(name, scopes), incoming.get(name) ?? [], workflow.entries)),
 		initial: initialStateOf(workflow),
-		groups: groups.map((g) => ({
-			name: g.name,
-			submachine: g.submachine,
-			states: [...g.states]
-		})),
+		groups,
 		vars
 	};
 };
@@ -204731,16 +205257,16 @@ Commands:
                    (or squash) the one resulting transition. Pass
                    --cost=<n> (optionally --model=<name>) to record the
                    just-finished invocation's token cost and model on the
-                   turn commit (summed into it.processCost/processCostByModel)
-  review <commitish>
-                   Start a NEW review process at the workflow's declared
-                   review-entry state (reviewEntry: true), reviewing
-                   <commitish>..HEAD — e.g. a colleague's PR branch. Requires
-                   a clean tree resting at the workflow's initial state
-  fix              Start a NEW process at the workflow's declared fix-entry
-                   state (fixEntry: true) that goes straight into repairing the
-                   current failing tests. Requires a clean tree resting at the
-                   workflow's initial state
+                   turn commit (summed into it.processCost/processCostByModel).
+                   Pass --entry <state> to start a brand NEW process at
+                   <state> instead — any declared, non-commit state (e.g.
+                   review-gate.check or fix-precheck on the bundled unified
+                   template) — with repeatable --var <name>=<value> supplying
+                   that new process's fixed it.vars overrides
+  (no command) --entry <state>
+                   Short form of 'step human --entry <state>' — starts a new
+                   process authenticated as human, e.g.
+                   'gtd --entry review-gate.check'
   abandon          End the process currently underway without completing it:
                    close any open review checkout window, then rewind HEAD to
                    the commit the process started from, keeping everything it
@@ -204772,6 +205298,15 @@ Options:
   --no-open        (gtd visualize only) do not open the browser
   --cost=<n>       (gtd step only) record the invocation's token cost
   --model=<name>   (gtd step only, with --cost) tag that cost's model
+  --entry <state>  (gtd step, or with no command at all) start a brand new
+                   process at <state> — any declared, non-commit state —
+                   instead of stepping the one currently resting. Not
+                   combinable with --cost/--model (an entry is not a metered
+                   agent turn)
+  --var <name>=<value>
+                   (with --entry; repeatable) supply a fixed it.vars
+                   override for the new process; the name must already be
+                   declared by the workflow's own vars: or the .gtdrc vars:
   --version, -v    Print version and exit
   --help, -h       Print this help and exit
 `;
@@ -204796,8 +205331,66 @@ const cliErrorLine = (error) => {
 	const message = error instanceof Error ? error.message : String(error);
 	return /^gtd[: ]/.test(message) ? message : `gtd: ${message}`;
 };
-/** Non-flag positional arguments past the subcommand name (argv[3..]). */
-const commandArgs = (argv) => argv.slice(3).filter((a) => a.length > 0 && !a.startsWith("--"));
+/**
+* Every value `flag` carries in `argv`, in BOTH `--flag=value` and `--flag
+* value` (space-separated) forms, plus every argv INDEX consumed producing
+* them — the flag token itself, and (for the space-separated form) the next
+* token too. A trailing bare occurrence (`flag` as the very last argv token,
+* with no following value) still consumes its own index but contributes an
+* EMPTY STRING to `values` — indistinguishable from an explicit `flag=`, and
+* deliberately so: both are "no value given" and a caller that cares (see
+* `parseEntryFlags`) rejects an empty value with its own message. Repeatable
+* flags (`--var`) collect one entry per occurrence, in argv order. Shared by
+* the positional-extraction fix below (`commandArgs`, and the top-level
+* `positional` lookup in `makeProgram`) and by `parseEntryFlags`'s own
+* `--entry`/`--var` parsing, so both agree on exactly which indices a flag's
+* value occupies.
+*/
+const takeFlagValues = (argv, flag) => {
+	const values = [];
+	const consumed = /* @__PURE__ */ new Set();
+	const eqPrefix = `${flag}=`;
+	for (let i = 0; i < argv.length; i++) {
+		const arg = argv[i];
+		if (arg === flag) {
+			consumed.add(i);
+			if (i + 1 < argv.length) {
+				values.push(argv[i + 1]);
+				consumed.add(i + 1);
+			} else values.push("");
+		} else if (arg.startsWith(eqPrefix)) {
+			consumed.add(i);
+			values.push(arg.slice(eqPrefix.length));
+		}
+	}
+	return {
+		values,
+		consumed
+	};
+};
+const ENTRY_FLAG = "--entry";
+const VAR_FLAG = "--var";
+/**
+* The absolute argv indices `takeFlagValues` reports as consumed for
+* `--entry`/`--var`, merged — the set both `commandArgs` and the top-level
+* `positional` lookup in `makeProgram` must SKIP so a flag's value (e.g.
+* `--entry review-gate.check`, which carries no `--` prefix of its own) is
+* never mistaken for a stray extra positional argument.
+*/
+const flagConsumedIndices = (argv) => {
+	const consumed = /* @__PURE__ */ new Set();
+	for (const i of takeFlagValues(argv, ENTRY_FLAG).consumed) consumed.add(i);
+	for (const i of takeFlagValues(argv, VAR_FLAG).consumed) consumed.add(i);
+	return consumed;
+};
+/** Non-flag positional arguments past the subcommand name (argv[3..]), skipping any index `flagConsumedIndices` reports as an `--entry`/`--var` value (which carries no `--` prefix of its own and would otherwise read as a stray extra positional — see `takeFlagValues`). */
+const commandArgs = (argv) => {
+	const consumed = flagConsumedIndices(argv);
+	return argv.map((a, i) => ({
+		a,
+		i
+	})).slice(3).filter(({ a, i }) => a.length > 0 && !a.startsWith("--") && !consumed.has(i)).map(({ a }) => a);
+};
 const COST_FLAG = "--cost=";
 /**
 * Parse the optional `--cost=<n>` flag (only `gtd step` accepts it — see
@@ -204850,6 +205443,55 @@ const parseStepFlags = (argv, positional) => gen(function* () {
 		model
 	};
 });
+/**
+* Parse the `--entry <state>`/`--entry=<state>` flag and the repeatable
+* `--var <name>=<value>`/`--var=<name>=<value>` flag together (see
+* `takeFlagValues`) — mirrors `parseStepFlags`'s shape/Effect style. `--entry`
+* names the state a brand-new process should START at (see
+* `runEntryCommand`), reached via `gtd step <actor> --entry <state>` or the
+* subcommand-less short form `gtd --entry <state>` — so, like `--cost`/
+* `--model`, it is rejected outright on any OTHER command rather than
+* silently ignored. `--var` supplies that new process's fixed `it.vars`
+* overrides, and only means anything alongside `--entry`.
+*
+* - At most one `--entry` occurrence — a second is a usage error (not
+*   last-wins).
+* - A bare `--entry` with no following value is a usage error (mirrors
+*   `parseCostFlag`'s bare-`--cost` handling).
+* - Each `--var` value must be `<name>=<value>` with a non-empty name and a
+*   single-line value (mirrors `parseModelFlag`'s multiline-rejection idiom);
+*   a duplicate `--var` NAME is a usage error (no silent last-wins).
+* - `--var` present with no `--entry` is a usage error.
+*
+* Deliberately does NOT reject `--cost`/`--model` alongside `--entry` — that
+* combination check lives where `--cost`/`--model` are already validated
+* (see `makeProgram`).
+*/
+const parseEntryFlags = (argv, positional) => gen(function* () {
+	const entryValues = takeFlagValues(argv, ENTRY_FLAG).values;
+	if (entryValues.length > 1) return yield* fail$2(/* @__PURE__ */ new Error("gtd: --entry may be given at most once"));
+	const entryRaw = entryValues[0];
+	if (entryRaw === "") return yield* fail$2(/* @__PURE__ */ new Error("gtd: --entry requires a value — use --entry=<state> or --entry <state>"));
+	const entry = entryRaw;
+	if (entry !== void 0 && positional !== "step" && positional !== void 0) return yield* fail$2(/* @__PURE__ */ new Error("gtd: --entry is only valid for `gtd step` or the bare `gtd --entry <state>` form"));
+	const vars = {};
+	const seenNames = /* @__PURE__ */ new Set();
+	for (const raw of takeFlagValues(argv, VAR_FLAG).values) {
+		const eq = raw.indexOf("=");
+		if (eq <= 0) return yield* fail$2(/* @__PURE__ */ new Error(`gtd: --var must be <name>=<value> with a non-empty name — got "${raw}"`));
+		const name = raw.slice(0, eq);
+		const value = raw.slice(eq + 1);
+		if (/[\r\n]/.test(value)) return yield* fail$2(/* @__PURE__ */ new Error(`gtd: --var ${name} must be a single-line value`));
+		if (seenNames.has(name)) return yield* fail$2(/* @__PURE__ */ new Error(`gtd: --var ${name} specified more than once`));
+		seenNames.add(name);
+		vars[name] = value;
+	}
+	if (entry === void 0 && Object.keys(vars).length > 0) return yield* fail$2(/* @__PURE__ */ new Error("gtd: --var requires --entry"));
+	return {
+		entry,
+		vars
+	};
+});
 /** Rejects extra positional arguments for a subcommand that takes none (`status`, `run`). */
 const rejectExtraArgs = (command, argv) => {
 	const args = commandArgs(argv);
@@ -204913,7 +205555,11 @@ const renderOnEdgesOrFail = (onEdges, vars) => try_({
 * path renders a DIFFERENT state, so it builds its own context inline
 * instead of sharing this helper). `renderedOn` is the resting state's `on`
 * edges already rendered against `it.vars` (`renderOnEdges`) — `next`/`status`
-* reuse it instead of re-rendering the same patterns themselves.
+* reuse it instead of re-rendering the same patterns themselves. `memory` is
+* the COMPUTED memory key (`memoryKeyFor`, package 05/06) for this rest —
+* `undefined` for a non-`prompt` rest or when no scope resolves — computed
+* once here (against the loaded config's `stateScopes`) rather than by each
+* caller separately.
 */
 const resolveRestContext = (git) => gen(function* () {
 	const config = yield* (yield* ConfigService).load;
@@ -204921,14 +205567,15 @@ const resolveRestContext = (git) => gen(function* () {
 	const envVars = yield* EnvVars;
 	const rest = yield* resolveRest();
 	const run = yield* computeProcessRun(git, rest.def);
-	const vars = resolveVars(config.workflowVars, config.rcVars, envVars.all);
+	const vars = resolveVars(config.workflowVars, config.rcVars, run.entryVars, envVars.all);
 	const renderedOn = yield* renderOnEdgesOrFail(rest.stateDef.on, vars);
 	const reviewBase = yield* reviewBaseHash(git, rest.def, run);
 	return {
 		rest,
 		run,
 		context: yield* buildTemplateContext(git, worktree.read, rest.state, rest.actor, run, vars, renderedOn, 0, void 0, reviewBase),
-		renderedOn
+		renderedOn,
+		memory: memoryKeyFor(config.stateScopes, rest, run)
 	};
 });
 /** The user-facing message for a `step` refusal — out-of-turn names the awaited actor, no-match names every declared pattern. */
@@ -204948,11 +205595,11 @@ const stepAsActor = (invoker, cost, model) => gen(function* () {
 	const rest = yield* resolveRest();
 	const run = yield* computeProcessRun(git, rest.def);
 	const changes = yield* pendingChanges(git);
-	const vars = resolveVars(config.workflowVars, config.rcVars, envVars.all);
+	const vars = resolveVars(config.workflowVars, config.rcVars, run.entryVars, envVars.all);
 	const renderedOn = yield* renderOnEdgesOrFail(rest.stateDef.on, vars);
 	const decision = step(withRenderedOn(rest.def, rest.state, renderedOn), rest.state, invoker, {
 		changes,
-		processTrace: run.trace
+		processTrace: run.trace.map((entry) => entry.state)
 	});
 	if (decision.kind === "refusal") return yield* fail$2(new Error(formatStepRefusal(invoker, decision)));
 	if (decision.kind === "noop") return {
@@ -205001,88 +205648,94 @@ const reportStepResult = (result, json, write) => {
 	}) + "\n");
 	else write(result.subject !== null ? `committed: ${result.subject}\n` : `nothing to do at "${result.state}"\n`);
 };
-/** `gtd step <actor> [--cost=<n>] [--model=<name>]`: authenticate as `<actor>` and perform the one resulting transition, recording `--cost`/`--model` as a `Gtd-Cost:` trailer. */
-const runStepCommand = (argv, json, write, cost, model) => gen(function* () {
+/**
+* `gtd step <actor> [--cost=<n>] [--model=<name>]`: authenticate as `<actor>`
+* and perform the one resulting transition, recording `--cost`/`--model` as a
+* `Gtd-Cost:` trailer. When `--entry <state>` is present, the actor argument
+* is still required (it names who authors the entry commit) but the ordinary
+* pattern-matched step never runs — dispatches to `runEntryCommand` instead
+* (see `makeProgram`'s parsing of `--entry`/`--var`, and its sibling
+* subcommand-less short form).
+*/
+const runStepCommand = (argv, json, write, cost, model, entryFlags) => gen(function* () {
 	const args = commandArgs(argv);
 	if (args.length === 0) return yield* fail$2(/* @__PURE__ */ new Error("gtd step: missing actor argument"));
 	if (args.length > 1) return yield* fail$2(/* @__PURE__ */ new Error(`gtd step: too many arguments — expected one actor, got: ${args.join(", ")}`));
-	const result = yield* stepAsActor(args[0], cost, model);
+	const actor = args[0];
+	if (entryFlags.entry !== void 0) return yield* runEntryCommand(actor, entryFlags.entry, entryFlags.vars, json, write, `gtd step ${actor} --entry ${entryFlags.entry}`);
+	const result = yield* stepAsActor(actor, cost, model);
 	reportStepResult(result, json, write);
 });
 /**
-* `gtd review <commitish>`: start a brand NEW review process at the active
-* workflow's declared `reviewEntry: true` state (see
-* `PatternMachine.reviewEntryStateOf`), reviewing `<commitish>..HEAD` — e.g. a
-* colleague's PR branch pushed on top of a shared base, with no gtd process of
-* its own. Writes an ordinary EMPTY turn commit
-* (`gtd(human): <review-entry-state>`) carrying the resolved `<commitish>`'s
-* full hash as a `Gtd-Review-Base:` trailer (`withReviewBaseTrailer`) —
-* `computeProcessRun` reads that trailer back off this same commit (its
-* process's own oldest) to override the new process's diff base, so the
-* ENTIRE existing review flow (reviewing → await-review → feedback laps, the
-* `await-review` review checkout window) operates over `<commitish>..HEAD`
-* with zero duplicated logic — see `src/Edge.ts`/`src/ReviewWindow.ts`.
-*
-* Any failure below is a plain refusal: nothing is written.
-*
-* a. The machine must currently rest at the workflow's INITIAL state — a
+* `gtd step <actor> --entry <state> [--var <name>=<value> ...]` (or its
+* subcommand-less short form `gtd --entry <state> ...`, `actor` defaulting to
+* `human` there — see `makeProgram`): start a brand NEW process at `<state>`
+* — any declared, non-commit state (see `PatternMachine.enterableStates`) —
+* replacing the two former named commands `gtd review <commitish>`/`gtd fix`
+* with one generic mechanism. Writes an ordinary turn commit
+* (`gtd(<actor>): <state>`) carrying zero or more `Gtd-Var: <name>=<value>`
+* trailers (`withEntryTrailers`) for each `--var` override, plus — when
+* `<state>` declares a string `reviewBase:` — a `Gtd-Review-Base:` trailer
+* pinning the new process's diff base (rendered from that template against
+* the merged `it.vars`, resolved to a commit, and checked sane). Unlike the
+* old commands (which required a clean tree and used `commitAsIs`), this
+* commits via `commitAllWithPrefix` — capturing whatever the working tree
+* carries at the moment of entry, exactly like an ordinary `gtd step`
+* capture, rather than demanding a clean tree first.
+*
+* Any failure below is a plain refusal: nothing is written. Checked in order:
+*
+* 1. The machine must currently rest at the workflow's INITIAL state — a
 *    plain non-gtd branch (the normal case) resolves there via the
-*    inert-subject rule (see `resolveState`); a process already underway refuses.
-* b. The working tree must be clean.
-* c. The active workflow must declare a `reviewEntry: true` state.
-* d. `<commitish>` must resolve to a commit, be an ancestor of HEAD, and
-*    differ from HEAD (nothing to review otherwise).
-*/
-const runReviewCommand = (argv, json, write) => gen(function* () {
-	const args = commandArgs(argv);
-	if (args.length === 0) return yield* fail$2(/* @__PURE__ */ new Error("gtd review: missing <commitish> argument"));
-	if (args.length > 1) return yield* fail$2(/* @__PURE__ */ new Error(`gtd review: too many arguments — expected one <commitish>, got: ${args.join(", ")}`));
-	const commitish = args[0];
-	const git = yield* GitService;
-	const rest = yield* resolveRest();
-	if (rest.state !== initialStateOf(rest.def)) return yield* fail$2(/* @__PURE__ */ new Error(`gtd review: a process is already underway (resting at "${rest.state}") — finish it, or run \`gtd abandon\`, before starting a review`));
-	if ((yield* pendingChanges(git)).length > 0) return yield* fail$2(/* @__PURE__ */ new Error("gtd review: the working tree must be clean before starting a review"));
-	const entryState = reviewEntryStateOf(rest.def);
-	if (entryState === void 0) return yield* fail$2(/* @__PURE__ */ new Error("gtd review: the active workflow declares no review entry state"));
-	const resolvedBase = yield* git.resolveRef(commitish).pipe(mapError$1(() => /* @__PURE__ */ new Error(`gtd review: "${commitish}" does not resolve to a commit`)));
-	if (resolvedBase === (yield* git.resolveRef("HEAD"))) return yield* fail$2(/* @__PURE__ */ new Error(`gtd review: "${commitish}" is HEAD — nothing to review`));
-	if (!(yield* git.isAncestor(resolvedBase, "HEAD"))) return yield* fail$2(/* @__PURE__ */ new Error(`gtd review: "${commitish}" is not an ancestor of HEAD`));
-	const subject = stateSubject("human", entryState);
-	yield* git.commitAsIs(withReviewBaseTrailer(subject, resolvedBase));
-	if (json) write(JSON.stringify({
-		state: entryState,
-		subject
-	}) + "\n");
-	else write(`committed: ${subject}\n`);
-});
-/**
-* `gtd fix`: start a brand NEW process at the active workflow's declared
-* `fixEntry: true` state (see `PatternMachine.fixEntryStateOf`), which goes
-* straight into repairing the current failing tests. Mirrors `runReviewCommand`
-* but simpler — it takes no argument and writes NO `Gtd-Review-Base:` trailer:
-* the fix process reviews its own fixes from the ordinary process start, so a
-* plain empty turn commit (`gtd(human): <fix-entry-state>`) is all it needs.
-* `computeProcessRun` then treats that commit as the process's first turn like
-* any other, and the shared health/review/squash tail runs unmodified.
-*
-* Any failure below is a plain refusal: nothing is written.
-*
-* a. The machine must currently rest at the workflow's INITIAL state — a
-*    dedicated `gtd fix` entry is distinct from the "no active cycle" rest, and
-*    a process already underway refuses (finish or abandon it first).
-* b. The working tree must be clean — the fixes belong to their own process.
-* c. The active workflow must declare a `fixEntry: true` state.
-*/
-const runFixCommand = (argv, json, write) => gen(function* () {
-	yield* rejectExtraArgs("fix", argv);
+*    inert-subject rule (see `resolveState`); a process already underway
+*    refuses.
+* 2. `<state>` must be one of `enterableStates(rest.def)` — every declared,
+*    non-commit state, NOT narrowed to whatever declared `entry: true` (that
+*    narrower set only seeds the workflow's own `entries.manual` reachability
+*    roots — this command lets an operator enter any of them).
+* 3. Every `--var` name must already be declared by the workflow's own
+*    `vars:` or the top-level `.gtdrc` `vars:` — an undeclared name is a
+*    usage error, not a silently-ignored override.
+* 4. When `<state>` declares a string `reviewBase:`, that template must
+*    render to a NON-BLANK commitish that resolves to a commit, is an
+*    ancestor of HEAD, and differs from HEAD.
+*/
+const runEntryCommand = (actor, entryState, varOverrides, json, write, commandLabel) => gen(function* () {
 	const git = yield* GitService;
+	const config = yield* (yield* ConfigService).load;
+	const envVars = yield* EnvVars;
 	const rest = yield* resolveRest();
-	if (rest.state !== initialStateOf(rest.def)) return yield* fail$2(/* @__PURE__ */ new Error(`gtd fix: a process is already underway (resting at "${rest.state}") — finish it, or run \`gtd abandon\`, before starting a fix`));
-	if ((yield* pendingChanges(git)).length > 0) return yield* fail$2(/* @__PURE__ */ new Error("gtd fix: the working tree must be clean before starting a fix"));
-	const entryState = fixEntryStateOf(rest.def);
-	if (entryState === void 0) return yield* fail$2(/* @__PURE__ */ new Error("gtd fix: the active workflow declares no fix entry state"));
-	const subject = stateSubject("human", entryState);
-	yield* git.commitAsIs(subject);
+	if (rest.state !== initialStateOf(rest.def)) return yield* fail$2(/* @__PURE__ */ new Error(`${commandLabel}: a process is already underway (resting at "${rest.state}") — finish it, or run \`gtd abandon\`, before entering`));
+	const enterable = enterableStates(rest.def);
+	if (!enterable.includes(entryState)) return yield* fail$2(/* @__PURE__ */ new Error(`${commandLabel}: "${entryState}" is not an enterable state — enterable states:\n${enterable.map((s) => `  ${s}`).join("\n")}`));
+	const declaredNames = Object.keys({
+		...config.workflowVars,
+		...config.rcVars
+	});
+	const undeclared = Object.keys(varOverrides).filter((name) => !declaredNames.includes(name));
+	if (undeclared.length > 0) return yield* fail$2(/* @__PURE__ */ new Error(`${commandLabel}: --var name(s) not declared by this workflow: ${undeclared.join(", ")} — declared: ${declaredNames.length > 0 ? declaredNames.join(", ") : "(none)"}`));
+	const vars = resolveVars(config.workflowVars, config.rcVars, varOverrides, envVars.all);
+	let base;
+	const baseTemplate = entryBaseTemplateOf(rest.def, entryState);
+	if (baseTemplate !== void 0) {
+		const rendered = yield* try_({
+			try: () => renderStateTemplate(baseTemplate, varsOnlyContext(vars, entryState)),
+			catch: (e) => /* @__PURE__ */ new Error(`${commandLabel}: ${e instanceof Error ? e.message : String(e)}`)
+		});
+		if (rendered.trim() === "") {
+			const refs = Array.from(new Set(Array.from(baseTemplate.matchAll(/it\.vars\.(\w+)/g)).map((m) => m[1])));
+			return yield* fail$2(/* @__PURE__ */ new Error(`${commandLabel}: "${entryState}"'s reviewBase template rendered blank — template: ${JSON.stringify(baseTemplate)}; it.vars references: ${refs.length > 0 ? refs.map((r) => `it.vars.${r}`).join(", ") : "(none found)"}`));
+		}
+		const resolvedBase = yield* git.resolveRef(rendered).pipe(mapError$1(() => /* @__PURE__ */ new Error(`${commandLabel}: "${rendered}" does not resolve to a commit`)));
+		if (!(yield* git.isAncestor(resolvedBase, "HEAD"))) return yield* fail$2(/* @__PURE__ */ new Error(`${commandLabel}: "${rendered}" is not an ancestor of HEAD`));
+		if (resolvedBase === (yield* git.resolveRef("HEAD"))) return yield* fail$2(/* @__PURE__ */ new Error(`${commandLabel}: "${rendered}" is HEAD — nothing to review`));
+		base = resolvedBase;
+	}
+	const subject = stateSubject(actor, entryState);
+	yield* git.commitAllWithPrefix(withEntryTrailers(subject, {
+		...base !== void 0 ? { base } : {},
+		vars: varOverrides
+	}));
 	if (json) write(JSON.stringify({
 		state: entryState,
 		subject
@@ -205093,8 +205746,10 @@ const EMPTY_TREE = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
 /**
 * `gtd abandon`: end the process currently underway WITHOUT completing it,
 * returning the machine to the workflow's initial state — the recovery path out
-* of a process nobody is going to finish (the refusals of `gtd review`/`gtd fix`
-* name it: "finish or abandon it before starting a review").
+* of a process nobody is going to finish (`runEntryCommand`'s "already
+* underway" refusal names it: "finish it, or run `gtd abandon`, before entering"
+* — and so does `resolveRest`'s refusal when HEAD names a state a workflow
+* change has since removed).
 *
 * NOTHING is discarded. The shared bracket in `makeProgram` has already closed
 * any open review checkout window (so HEAD is the real head), and abandon then
@@ -205105,6 +205760,15 @@ const EMPTY_TREE = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
 * uncommitted changes for the human to keep, re-commit, or discard with
 * ordinary git.
 *
+* Deliberately reads the current state off `computeProcessRun`'s OWN trace
+* (its last entry, oldest→newest) rather than `resolveRest` — `resolveRest`
+* refuses when HEAD names a state the CURRENT workflow no longer declares
+* (the escape hatch THIS command is), so routing through it here would make
+* the one command that must still work in that exact situation refuse right
+* alongside everything else. `computeProcessRun`'s boundary walk only ever
+* compares state NAMES (never a declaration lookup), so it resolves a
+* renamed-away trace exactly as well as an ordinary one.
+*
 * Idempotent: resting at the initial state (a plain non-gtd branch, or a
 * just-squashed cycle) is a no-op SUCCESS, not a refusal — a recovery command
 * that fails when there is nothing to recover is a worse tool. The one refusal
@@ -205114,9 +205778,10 @@ const EMPTY_TREE = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
 const runAbandonCommand = (argv, json, write) => gen(function* () {
 	yield* rejectExtraArgs("abandon", argv);
 	const git = yield* GitService;
-	const rest = yield* resolveRest();
-	const initial = initialStateOf(rest.def);
-	if (rest.state === initial) {
+	const def = (yield* (yield* ConfigService).load).workflow;
+	const initial = initialStateOf(def);
+	const run = yield* computeProcessRun(git, def);
+	if (run.trace.length === 0) {
 		if (json) write(JSON.stringify({
 			state: initial,
 			abandoned: false
@@ -205124,18 +205789,18 @@ const runAbandonCommand = (argv, json, write) => gen(function* () {
 		else write(`no gtd process is underway (resting at "${initial}") — nothing to abandon\n`);
 		return;
 	}
-	const run = yield* computeProcessRun(git, rest.def);
-	if (run.startParentHash === EMPTY_TREE) return yield* fail$2(/* @__PURE__ */ new Error(`gtd abandon: the process underway (resting at "${rest.state}") starts at the repository's first commit — there is no earlier commit to rewind to`));
+	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`));
 	yield* retainHistory(git, yield* git.resolveRef("HEAD"), run.startParentHash);
 	yield* git.mixedResetTo(run.startParentHash);
 	const subject = yield* git.lastCommitSubject();
 	if (json) write(JSON.stringify({
 		state: initial,
 		abandoned: true,
-		from: rest.state,
+		from: restState,
 		head: run.startParentHash
 	}) + "\n");
-	else write(`abandoned the process resting at "${rest.state}" — HEAD is back at ${run.startParentHash.slice(0, 7)} ("${subject}"), resting at "${initial}".\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`);
+	else write(`abandoned the process resting at "${restState}" — HEAD is back at ${run.startParentHash.slice(0, 7)} ("${subject}"), resting at "${initial}".\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`);
 });
 /**
 * `gtd restore`: hard-reset HEAD back to the pre-squash tip a squash or
@@ -205208,8 +205873,8 @@ const nextPlainOutput = (rendered) => {
 };
 const runNextCommand = (json, write) => gen(function* () {
 	const git = yield* GitService;
-	const { rest, context } = yield* resolveRestContext(git);
-	const rendered = yield* renderRest(rest, context);
+	const { rest, context, memory } = yield* resolveRestContext(git);
+	const rendered = yield* renderRest(rest, context, memory);
 	write(json ? nextJsonOutput(rendered) : nextPlainOutput(rendered));
 });
 /**
@@ -205559,10 +206224,9 @@ const writeStatusPlain = (write, rest, statusChanges, next, model, memory, label
 const runStatusCommand = (argv, json, write) => gen(function* () {
 	yield* rejectExtraArgs("status", argv);
 	const git = yield* GitService;
-	const { rest, context, renderedOn } = yield* resolveRestContext(git);
+	const { rest, context, renderedOn, memory } = yield* resolveRestContext(git);
 	const changes = yield* pendingChanges(git);
 	const model = yield* renderModel(rest.stateDef, context);
-	const memory = yield* renderMemory(rest.stateDef, context);
 	const label = yield* renderLabel(rest.stateDef, context);
 	const file = yield* renderFile(rest.stateDef, context);
 	const statusChanges = computeStatusChanges(renderedOn, changes);
@@ -205632,8 +206296,9 @@ const computeCurrentState = (model) => gen(function* () {
 	const envVars = yield* EnvVars;
 	const reviewHead = yield* git.readRefOption(REVIEW_HEAD_REF);
 	const currentRest = yield* resolveRest(getOrUndefined(reviewHead));
+	const run = yield* computeProcessRun(git, currentRest.def);
 	const changes = yield* pendingChanges(git);
-	const vars = resolveVars(config.workflowVars, config.rcVars, envVars.all);
+	const vars = resolveVars(config.workflowVars, config.rcVars, run.entryVars, envVars.all);
 	const renderedOn = yield* renderOnEdgesOrFail(currentRest.stateDef.on, vars);
 	const group = model.states.find((s) => s.name === currentRest.state)?.group;
 	return buildCurrentStateModel(currentRest, changes, renderedOn, group);
@@ -205656,10 +206321,10 @@ const runVisualizeCommand = (argv, json, write) => gen(function* () {
 	const opts = parseVisualizeOptions(rest);
 	if ("error" in opts) return yield* fail$2(new Error(opts.error));
 	const config = yield* (yield* ConfigService).load;
-	const model = buildVizModel(config.workflow, config.rawWorkflow, {
+	const model = buildVizModel(config.workflow, config.machineTree, {
 		...config.workflowVars,
 		...config.rcVars
-	});
+	}, config.stateScopes);
 	if (json) {
 		write(JSON.stringify(model, null, 2) + "\n");
 		return;
@@ -205676,8 +206341,6 @@ const runVisualizeCommand = (argv, json, write) => gen(function* () {
 });
 const KNOWN_SUBCOMMANDS = [
 	"step",
-	"review",
-	"fix",
 	"abandon",
 	"restore",
 	"next",
@@ -205685,6 +206348,19 @@ const KNOWN_SUBCOMMANDS = [
 	"validate"
 ];
 /**
+* The two named commands the generic `--entry` mechanism replaced (see
+* `runEntryCommand`) — no fallback, so `gtd review`/`gtd fix` must fail with a
+* message pointing at the replacement rather than the generic "unknown
+* command" (see `requireKnownSubcommand`). Illustrated with the bundled
+* unified template's own entry-flagged state names (`review-gate.check`/
+* `fix-precheck`) since gtd itself has no opinion on any workflow's state
+* names — a custom workflow names its own.
+*/
+const REMOVED_SUBCOMMANDS = {
+	review: "gtd: `gtd review <commitish>` is gone — this workflow's own state names aren't known to gtd; run `gtd step <actor> --entry <review-state> --var <name>=<value> ...` instead (e.g. `gtd step human --entry review-gate.check` for the bundled unified template)",
+	fix: "gtd: `gtd fix` is gone — this workflow's own state names aren't known to gtd; run `gtd step <actor> --entry <fix-state>` instead (e.g. `gtd step human --entry fix-precheck` for the bundled unified template)"
+};
+/**
 * `--version`/`-v`/`version` or `--help`/`-h`/`help`: short-circuits before any
 * git or state work, so it works outside a repo too. The bare `version`/`help`
 * subcommands are equivalent to their flag forms. Exported so main.ts can run
@@ -205712,6 +206388,8 @@ const requireKnownSubcommand = (sub, json, write) => {
 		if (!json) write(HELP_TEXT);
 		return fail$2(/* @__PURE__ */ new Error("gtd: missing command — see usage above (`gtd --help`)"));
 	}
+	const removedMessage = REMOVED_SUBCOMMANDS[sub];
+	if (removedMessage !== void 0) return fail$2(new Error(removedMessage));
 	if (!KNOWN_SUBCOMMANDS.includes(sub)) return fail$2(/* @__PURE__ */ new Error(`unknown command '${sub}'`));
 	return succeed$3(sub);
 };
@@ -205745,12 +206423,10 @@ const assertInitLocation = (git, fs) => gen(function* () {
 	if ((yield* fs.realPath(topLevel.right)) !== (yield* fs.realPath(process.cwd()))) return yield* fail$2(/* @__PURE__ */ new Error(`gtd init must be run from the repository root (${topLevel.right}) or from a directory outside any git repository; the current directory is a repository subdirectory: ${process.cwd()}`));
 	return true;
 });
-/** Dispatches to the named `run*Command` handler for every known subcommand. */
-const dispatchKnownSubcommand = (sub, argv, json, write, cost, model) => {
+/** Dispatches to the named `run*Command` handler for every known subcommand. `entryFlags` is only consulted by `step` (see `runStepCommand`) — every other subcommand ignores it, since `--entry`/`--var` are meaningless anywhere else (`parseEntryFlags` already rejects that combination before dispatch is reached). */
+const dispatchKnownSubcommand = (sub, argv, json, write, cost, model, entryFlags) => {
 	switch (sub) {
-		case "step": return runStepCommand(argv, json, write, cost, model);
-		case "review": return runReviewCommand(argv, json, write);
-		case "fix": return runFixCommand(argv, json, write);
+		case "step": return runStepCommand(argv, json, write, cost, model, entryFlags);
 		case "abandon": return runAbandonCommand(argv, json, write);
 		case "restore": return runRestoreCommand(argv, json, write);
 		case "next": return runNextCommand(json, write);
@@ -205759,6 +206435,22 @@ const dispatchKnownSubcommand = (sub, argv, json, write, cost, model) => {
 	}
 };
 /**
+* Runs `command` inside the bracket every state-touching subcommand shares:
+* the repo-root guard, then close-any-open-review-window before the command
+* sees HEAD, then re-arm it afterward whether `command` succeeded or refused
+* (see `closeReviewWindow`/`openReviewWindow`). Shared by the normal
+* known-subcommand dispatch and the subcommand-less `gtd --entry <state>`
+* short form in `makeProgram`, so both open/close the window identically.
+*/
+const runInReviewWindowBracket = (git, fs, command) => gen(function* () {
+	yield* assertRunningFromRepoRoot(git, fs);
+	yield* closeReviewWindow;
+	const outcome = yield* either(command);
+	const rearm = yield* either(openReviewWindow);
+	if (isLeft(outcome)) return yield* fail$2(outcome.left);
+	if (isLeft(rearm)) return yield* fail$2(rearm.left);
+});
+/**
 * Factory that returns the gtd driver Effect with the given I/O options.
 *
 * The returned Effect requires `GitService | FileSystem.FileSystem |
@@ -205766,36 +206458,46 @@ const dispatchKnownSubcommand = (sub, argv, json, write, cost, model) => {
 * this with no arguments; the test world supplies an in-memory layer set and
 * captures stdout via the `write` callback.
 *
-* v3 command surface: `step <actor>` / `review <commitish>` / `fix` / `next` /
-* `status` / `validate` (see `src/Edge.ts`),
-* plus `lsp` and `init` — both dispatched before the config-reading
-* path since neither needs to touch the config. Bare `gtd` or an
-* unknown subcommand is a usage error. Shared setup (argv parsing, the
-* repo-root guard) lives here; each subcommand's own logic is a named
-* `run*Command` function above.
+* v3 command surface: `step <actor>` / `next` / `status` / `validate` (see
+* `src/Edge.ts`), plus `lsp` and `init` — both dispatched before the
+* config-reading path since neither needs to touch the config. `step
+* <actor> --entry <state>` (and its subcommand-less short form `gtd --entry
+* <state>`, actor defaulting to `human`) starts a brand-new process at any
+* declared, non-commit state — the generic mechanism that replaced the old
+* named `review`/`fix` commands (see `runEntryCommand`; `gtd review`/`gtd
+* fix` now fail with a message pointing at the replacement, `REMOVED_SUBCOMMANDS`).
+* Bare `gtd` with no `--entry` present, or an unknown subcommand, is a usage
+* error. Shared setup (argv parsing, the repo-root guard) lives here; each
+* subcommand's own logic is a named `run*Command` function above.
 */
 function makeProgram(opts = {}) {
 	const argv = opts.argv ?? process.argv;
 	const write = opts.write ?? ((chunk) => process.stdout.write(chunk));
 	const json = argv.includes("--json");
-	const positional = argv.slice(2).find((a) => !a.startsWith("--"));
+	const consumedFlagIndices = flagConsumedIndices(argv);
+	const positional = argv.map((a, i) => ({
+		a,
+		i
+	})).slice(2).find(({ a, i }) => !a.startsWith("--") && !consumedFlagIndices.has(i))?.a;
 	return gen(function* () {
 		if (runVersionOrHelp(argv, write)) return;
 		if (positional === "visualize") return yield* runVisualizeCommand(argv, json, write);
-		const unknownOption = argv.slice(2).find((a) => a.startsWith("--") && a !== "--json" && a !== "--cost" && a !== "--model" && !a.startsWith(COST_FLAG) && !a.startsWith(MODEL_FLAG));
+		const unknownOption = argv.slice(2).find((a) => a.startsWith("--") && a !== "--json" && a !== "--cost" && a !== "--model" && a !== ENTRY_FLAG && a !== VAR_FLAG && !a.startsWith(COST_FLAG) && !a.startsWith(MODEL_FLAG) && !a.startsWith(`${ENTRY_FLAG}=`) && !a.startsWith(`${VAR_FLAG}=`));
 		if (unknownOption !== void 0) return yield* fail$2(/* @__PURE__ */ new Error(`gtd: unknown option '${unknownOption}' — see \`gtd --help\``));
 		const { cost, model } = yield* parseStepFlags(argv, positional);
+		const entryFlags = yield* parseEntryFlags(argv, positional);
+		if (entryFlags.entry !== void 0 && (cost !== void 0 || model !== void 0)) return yield* fail$2(/* @__PURE__ */ new Error("gtd: --cost/--model cannot be combined with --entry — an entry is not a metered agent turn"));
 		if (positional === "lsp") return yield* runLspCommand(argv, json);
 		if (positional === "init") return yield* runInitCommand(argv, json, write);
+		if (positional === void 0 && entryFlags.entry !== void 0) {
+			const git = yield* GitService;
+			const fs = yield* FileSystem;
+			return yield* runInReviewWindowBracket(git, fs, runEntryCommand("human", entryFlags.entry, entryFlags.vars, json, write, `gtd --entry ${entryFlags.entry}`));
+		}
 		const sub = yield* requireKnownSubcommand(positional, json, write);
 		const git = yield* GitService;
 		const fs = yield* FileSystem;
-		yield* assertRunningFromRepoRoot(git, fs);
-		yield* closeReviewWindow;
-		const outcome = yield* either(dispatchKnownSubcommand(sub, argv, json, write, cost, model));
-		const rearm = yield* either(openReviewWindow);
-		if (isLeft(outcome)) return yield* fail$2(outcome.left);
-		if (isLeft(rearm)) return yield* fail$2(rearm.left);
+		yield* runInReviewWindowBracket(git, fs, dispatchKnownSubcommand(sub, argv, json, write, cost, model, entryFlags));
 	}).pipe(json ? catchAll((error) => sync$1(() => write(JSON.stringify({
 		state: "error",
 		prompt: error.message