@pmelab/gtd 10.4.0 → 10.5.0

package/README.md

@@ -268,7 +268,10 @@ command opens the empty `.gtd/TODO.md`, and whatever you write there is the
 first sketch the whole process gets planned from. As a final step, if it finds
 an LSP-capable editor, the briefing also offers to wire up live diagnostics and
 review actions in it — asking first and naming the exact file, and merging
-rather than overwriting your editor's config.
+rather than overwriting your editor's config. That editor integration also adds
+a footnote where your cursor sits with one code action, and jumps between a
+footnote's marker and its definition both ways — so leaving a comment for the
+next agent turn never means hand-typing the `[^name]` syntax yourself.
 
 ### The workflow it ships with
 

package/dist/gtd.bundle.mjs

@@ -190484,16 +190484,336 @@ const flattenMachines = (raw, errors) => {
 		scopes
 	};
 };
-/** `QA_FORMAT`'s canonical sample: one open question with two options plus the unfilled free-text slot. Not authored to survive any particular formatter. */
+//#endregion
+//#region src/Footnotes.ts
+/** The seeded placeholder a hand-authored definition starts as — still present means the human never filled it in. `footnoteAdditionEdits` (below) seeds new definitions with this exact text, so `computeFindings`'s placeholder check fires until a human replaces it. */
+const PLACEHOLDER_BODY = "your comment";
+/** A definition's start line: `[^name]:` at COLUMN 0, nothing before it. */
+const DEFINITION_START_RE = /^\[\^([^\s\]]+)\]:\s?(.*)$/;
+/** A marker anywhere on a line: `[^name]`, name has no whitespace and no `]`. */
+const MARKER_RE = /\[\^([^\s\]]+)\]/g;
+/** A fenced-code-block delimiter line (any indent, ``` or more backticks). */
+const FENCE_RE = /^\s*```/;
+/** Blanks out inline-code spans (\`...\`) while preserving line length, so marker column offsets stay accurate. */
+const maskInlineCode = (line) => line.replace(/`[^`]*`/g, (m) => " ".repeat(m.length));
+/** A non-blank line that starts with leading whitespace — the shape of a definition's continuation line. */
+const isContinuationLine = (line) => line.trim().length > 0 && /^\s+\S/.test(line);
+/**
+* For each line in `lines`, whether it's inside (or is the delimiter of) a
+* fenced code block — content that "scanning skips code" excludes from both
+* marker and definition recognition. The one shared source of truth for
+* fence state: `parseFootnotes` and `isFootnoteDefinitionLine` both consult
+* this instead of tracking fences independently, so the two can never
+* disagree about what a definition is.
+*/
+const computeFenceSkip = (lines) => {
+	const skip = [];
+	let inFence = false;
+	for (const line of lines) if (FENCE_RE.test(line)) {
+		skip.push(true);
+		inFence = !inFence;
+	} else skip.push(inFence);
+	return skip;
+};
+/**
+* True when `lines[index]` is part of a footnote definition — either the
+* `[^name]:` start line itself, or one of its indented continuation lines —
+* and is not itself fenced-code content. Walks backward through the
+* contiguous run of indented non-blank lines above `index` to find the
+* start; a blank line, an unindented line, fenced-code content, or the top
+* of `lines` ends the search with `false`. Exported so `OpenQuestions.ts`
+* and `ReviewDoc.ts` can break their own item/pointer spans on a definition
+* without re-parsing the whole document.
+*/
+const isFootnoteDefinitionLine = (lines, index) => {
+	const line = lines[index];
+	if (line === void 0) return false;
+	const fenceSkip = computeFenceSkip(lines);
+	if (fenceSkip[index]) return false;
+	if (DEFINITION_START_RE.test(line)) return true;
+	if (!isContinuationLine(line)) return false;
+	let i = index - 1;
+	while (i >= 0) {
+		if (fenceSkip[i]) return false;
+		const prev = lines[i];
+		if (DEFINITION_START_RE.test(prev)) return true;
+		if (!isContinuationLine(prev)) return false;
+		i -= 1;
+	}
+	return false;
+};
+/** Strips every `[^name]` marker out of `text` — applied to every extracted text field so a marker never leaks into an option's or note's text. */
+const stripFootnoteMarkers = (text) => text.replace(MARKER_RE, "");
+const computeFindings = (markers, definitions) => {
+	const findings = [];
+	const definedNames = new Set(definitions.map((d) => d.name));
+	const referencedNames = new Set(markers.map((m) => m.name));
+	const seenDefinitionNames = /* @__PURE__ */ new Set();
+	for (const marker of markers) if (!definedNames.has(marker.name)) findings.push({
+		message: `Footnote marker "[^${marker.name}]" has no matching definition`,
+		line: marker.line
+	});
+	for (const def of definitions) {
+		if (seenDefinitionNames.has(def.name)) findings.push({
+			message: `Duplicate footnote definition "[^${def.name}]"`,
+			line: def.line
+		});
+		else seenDefinitionNames.add(def.name);
+		if (!referencedNames.has(def.name)) findings.push({
+			message: `Footnote definition "[^${def.name}]" has no marker referencing it`,
+			line: def.line
+		});
+		if (def.body.trim().toLowerCase() === PLACEHOLDER_BODY) findings.push({
+			message: `Footnote definition "[^${def.name}]" still has its seeded placeholder body`,
+			line: def.line
+		});
+	}
+	return findings.sort((a, b) => (a.line ?? 0) - (b.line ?? 0));
+};
+/** Parses the `[^name]:` definition starting at `lines[index]`, plus its indented continuation run. Returns the parsed definition and the index of the first line past it. */
+const parseDefinitionAt = (lines, index, defMatch) => {
+	const name = defMatch[1];
+	const sameLineBody = (defMatch[2] ?? "").trim();
+	const bodyParts = sameLineBody.length > 0 ? [sameLineBody] : [];
+	let endLine = index;
+	let j = index + 1;
+	while (j < lines.length && isContinuationLine(lines[j])) {
+		bodyParts.push(lines[j].trim());
+		endLine = j;
+		j += 1;
+	}
+	return {
+		definition: {
+			name,
+			line: index,
+			endLine,
+			body: bodyParts.join(" ")
+		},
+		nextIndex: j
+	};
+};
+/** Every marker on `line` (after masking inline-code spans), anchored at `lineIndex`. */
+const scanMarkers = (line, lineIndex) => {
+	const masked = maskInlineCode(line);
+	const re = new RegExp(MARKER_RE);
+	const found = [];
+	let match;
+	while ((match = re.exec(masked)) !== null) found.push({
+		name: match[1],
+		line: lineIndex,
+		character: match.index
+	});
+	return found;
+};
+/**
+* Parses every footnote marker and definition out of `content`. Total and
+* side-effect-free: always returns a result, never throws. Scanning skips
+* fenced code blocks entirely and blanks inline-code spans before looking for
+* markers, so `[^x]` inside either never counts. A definition's own body
+* (same-line plus indented continuation lines) is excluded from marker
+* scanning — a `[^y]` written there is ordinary text.
+*/
+const parseFootnotes = (content) => {
+	const lines = content.split(/\r?\n/);
+	const fenceSkip = computeFenceSkip(lines);
+	const markers = [];
+	const definitions = [];
+	let i = 0;
+	while (i < lines.length) {
+		const line = lines[i];
+		if (fenceSkip[i]) {
+			i += 1;
+			continue;
+		}
+		const defMatch = DEFINITION_START_RE.exec(line);
+		if (defMatch) {
+			const { definition, nextIndex } = parseDefinitionAt(lines, i, defMatch);
+			definitions.push(definition);
+			i = nextIndex;
+			continue;
+		}
+		markers.push(...scanMarkers(line, i));
+		i += 1;
+	}
+	return {
+		markers,
+		definitions,
+		findings: computeFindings(markers, definitions)
+	};
+};
+/** The first integer unused by any `fnN` marker or definition already in the document — deterministic (no clock, no randomness), so "add a footnote" is testable and idempotent under re-run: applying it twice yields `fn1` then `fn2`, never a collision. */
+const nextFootnoteName = (content) => {
+	const { markers, definitions } = parseFootnotes(content);
+	const NAME_RE = /^fn(\d+)$/;
+	const used = /* @__PURE__ */ new Set();
+	for (const name of [...markers.map((m) => m.name), ...definitions.map((d) => d.name)]) {
+		const match = NAME_RE.exec(name);
+		if (match) used.add(Number(match[1]));
+	}
+	let n = 1;
+	while (used.has(n)) n += 1;
+	return `fn${n}`;
+};
+/**
+* Where "add a footnote" plants the marker: scan right from `character` while
+* the character at that position is a word character, and stop there. One
+* rule, no branching — a cursor inside a word lands at the word's end, a
+* cursor already just past a word (or on whitespace/punctuation) doesn't
+* move at all, landing right at the cursor.
+*/
+const footnoteMarkerColumn = (line, character) => {
+	let i = character;
+	while (i < line.length && /\w/.test(line[i])) i += 1;
+	return i;
+};
+/** The first line index at or after `from` that is non-blank, or `lines.length` when none remain (EOF). */
+const firstNonBlankFrom = (lines, from) => {
+	let i = from;
+	while (i < lines.length && lines[i].trim().length === 0) i += 1;
+	return i;
+};
+/**
+* The last non-blank line of the current prose block starting at `index` —
+* the "otherwise" placement rule for "add a footnote": the next blank line,
+* or end of file. Shared by both formats' fallback case (a hunk's own span
+* and a question's option-list span are format-specific and computed by the
+* caller instead).
+*/
+const proseBlockEnd = (lines, index) => {
+	let end = index;
+	for (let i = index + 1; i < lines.length; i += 1) {
+		if (lines[i].trim().length === 0) break;
+		end = i;
+	}
+	return end;
+};
+/** The marker whose `[^name]` span (inclusive of both brackets) contains `position`, or `undefined`. Shared by `footnotePointerAt` and `isOnExistingFootnote` so the two can never disagree about what counts as "inside a marker". */
+const markerAt = (markers, position) => markers.find((m) => {
+	if (m.line !== position.line) return false;
+	const end = m.character + m.name.length + 3;
+	return position.character >= m.character && position.character <= end;
+});
+/**
+* True when `position` sits inside an EXISTING marker's `[^name]` span, or on
+* an existing definition's own line (its `[^name]:` label line or an indented
+* continuation) — the guard "gtd: add a footnote" uses to refuse itself
+* rather than plant a new marker/definition into already-written footnote
+* syntax (which would corrupt it: a marker inserted inside another marker's
+* name, or a definition inserted between an existing definition's label and
+* its own name).
+*/
+const isOnExistingFootnote = (content, position) => {
+	const { markers } = parseFootnotes(content);
+	if (markerAt(markers, position)) return true;
+	return isFootnoteDefinitionLine(content.split(/\r?\n/), position.line);
+};
+/**
+* The two edits behind "gtd: add a footnote": a marker inserted at the
+* cursor (via `footnoteMarkerColumn`) and a definition seeded with
+* `PLACEHOLDER_BODY`, planted right after `blockEndLine` — the caller's own
+* notion of "the current block's last line" (a hunk's span in `ReviewDoc.ts`,
+* an option-list's span in `OpenQuestions.ts`, or `proseBlockEnd` otherwise).
+* The definition edit REPLACES any existing blank-line run between
+* `blockEndLine` and the next non-blank content (or EOF) with exactly one
+* blank line, the definition, and — unless at EOF — one more blank line, so
+* the result is deterministic regardless of the surrounding whitespace.
+*
+* The definition edit's range starts at `(blockEndLine + 1, 0)` — the line
+* AFTER `blockEndLine` — never at the end of `blockEndLine` itself, even when
+* that line doesn't literally exist yet (a document with no trailing
+* newline): a `line` past the document's last index is a legal LSP position,
+* clamped to end-of-file, per the protocol. The marker edit's own position is
+* always on or before `blockEndLine` (callers only ever pass a `blockEndLine`
+* at or after the cursor's line), so anchoring one line later guarantees the
+* two edits' ranges never touch: two edits that share a start position have
+* no defined application order (LSP forbids overlapping — including
+* coincident-zero-length — ranges in one action), and a naive apply corrupts
+* whichever text sits at the shared offset.
+*/
+const footnoteAdditionEdits = (content, position, blockEndLine) => {
+	const lines = content.split(/\r?\n/);
+	const cursorLine = lines[position.line] ?? "";
+	const markerColumn = footnoteMarkerColumn(cursorLine, position.character);
+	const name = nextFootnoteName(content);
+	const markerEdit = {
+		range: {
+			start: {
+				line: position.line,
+				character: markerColumn
+			},
+			end: {
+				line: position.line,
+				character: markerColumn
+			}
+		},
+		newText: `[^${name}]`
+	};
+	const insertLine = blockEndLine + 1;
+	const start = {
+		line: insertLine,
+		character: 0
+	};
+	const nextContentLine = firstNonBlankFrom(lines, insertLine);
+	const atEof = nextContentLine >= lines.length;
+	return [markerEdit, {
+		range: {
+			start,
+			end: atEof ? start : {
+				line: nextContentLine,
+				character: 0
+			}
+		},
+		newText: atEof ? `\n[^${name}]: ${PLACEHOLDER_BODY}\n` : `\n[^${name}]: ${PLACEHOLDER_BODY}\n\n`
+	}];
+};
+/**
+* The footnote half of `pointerAt`, shared by `qa` (which serves footnote
+* jumps ONLY) and `review` (which tries this FIRST — footnotes are
+* column-scoped and the hunk jump is line-scoped, so a marker sitting in a
+* hunk's inline note would otherwise be shadowed by it). Returns `undefined`
+* when `position` isn't on a footnote at all (the caller should try its own
+* next resolver); returns `{ pointer: undefined }` for an orphan marker or
+* definition — resolved, but to nothing, so the caller must NOT fall through
+* to another resolver (an orphan marker inside a review hunk's note must not
+* jump to the hunk).
+*/
+const footnotePointerAt = (content, position) => {
+	const { markers, definitions } = parseFootnotes(content);
+	const marker = markerAt(markers, position);
+	if (marker) {
+		const definition = definitions.find((d) => d.name === marker.name);
+		return { pointer: definition ? { line: definition.line } : void 0 };
+	}
+	const lines = content.split(/\r?\n/);
+	if (isFootnoteDefinitionLine(lines, position.line)) {
+		const definition = definitions.find((d) => position.line >= d.line && position.line <= d.endLine);
+		const firstMarker = definition ? markers.find((m) => m.name === definition.name) : void 0;
+		return { pointer: firstMarker ? {
+			line: firstMarker.line,
+			character: firstMarker.character
+		} : void 0 };
+	}
+};
+/**
+* `QA_FORMAT`'s canonical sample: one open question with two options plus the
+* unfilled free-text slot, and one anchored footnote on an option with a body
+* over 80 characters — pinned already in oxfmt's own wrapped four-space form
+* (see `src/SteeringFormats.test.ts`'s formatter round-trip). Not authored to
+* survive any particular formatter.
+*/
 const QA_SAMPLE = `Sample plan. Add a thing.
 
 ## Open Questions
 
 ### Which option?
 
-- [ ] Option A
+- [ ] Option A[^fn1]
 - [ ] Option B
 - [ ] _your answer_
+
+[^fn1]:
+    This option keeps the current behavior exactly as it is today, which is the
+    safer default for most reviewers.
 `;
 const OPEN_QUESTIONS_HEADING = "## Open Questions";
 const ANSWERED_QUESTIONS_HEADING = "## Answered Questions";
@@ -190521,7 +190841,7 @@ const splitQuestionBlocks = (lines, start) => {
 			i += 1;
 			continue;
 		}
-		const question = heading.text;
+		const question = stripFootnoteMarkers(heading.text);
 		const headingLine = i;
 		i += 1;
 		const body = [];
@@ -190549,7 +190869,7 @@ const itemEndIndex = (body, index) => {
 	let end = index;
 	for (let i = index + 1; i < body.length; i += 1) {
 		const line = body[i];
-		if (line.trim().length === 0 || CHECKBOX_RE.test(line)) break;
+		if (line.trim().length === 0 || CHECKBOX_RE.test(line) || isFootnoteDefinitionLine(body, i)) break;
 		end = i;
 	}
 	return end;
@@ -190566,7 +190886,7 @@ const parseOptions = (body, bodyStart) => {
 		if (!match) return;
 		raw.push({
 			checked: match[1] !== " ",
-			text: match[2].trim(),
+			text: stripFootnoteMarkers(match[2]).trim(),
 			sourceLine: bodyStart + i,
 			bodyIndex: i
 		});
@@ -190598,7 +190918,8 @@ const isAnswered = (options) => {
 };
 const parseQuestionBlock = (block, status) => {
 	if (block.question.length === 0) return { error: "An '### ' question heading under '## Open Questions' or '## Answered Questions' has no question text" };
-	const firstNonBlank = block.body.map((line) => line.trim()).find((line) => line.length > 0) ?? "";
+	const firstNonBlankLine = block.body.find((line, i) => line.trim().length > 0 && !isFootnoteDefinitionLine(block.body, i));
+	const firstNonBlank = firstNonBlankLine ? stripFootnoteMarkers(firstNonBlankLine.trim()) : "";
 	const options = status === "open" ? parseOptions(block.body, block.headingLine + 1) : [];
 	return {
 		question: block.question,
@@ -190701,19 +191022,45 @@ const statusMarker = (question) => {
 	if (question.status === "answered") return "[answered]";
 	return question.answered ? "[answered]" : "[unanswered]";
 };
-/** The outline tree for a `qa`-mode file's open/answered questions, each option a `leaf: true` child of its open question. */
+/** One footnote marker rendered as an outline leaf: `[^name] <body>`. */
+const footnoteLeaf$1 = (lines, definitionByName, marker) => ({
+	name: `[^${marker.name}] ${definitionByName.get(marker.name) ?? ""}`.trim(),
+	range: lineRange$1(lines, marker.line),
+	selectionRange: lineRange$1(lines, marker.line),
+	leaf: true
+});
+/**
+* The outline tree for a `qa`-mode file's open/answered questions, each
+* option a `leaf: true` child of its open question — unless it carries a
+* footnote of its own, in which case it's a container instead (`leaf` and
+* `children` are never both set; see `SteeringFormat.ts`'s `leaf` doc). A
+* footnote is itself always a `leaf: true` child of whichever node's span
+* contains its marker — an option when the marker sits inside that option's
+* span, otherwise the question itself.
+*/
 const questionsOutline = (content) => {
 	const { questions } = parseOpenQuestions(content);
+	const { markers, definitions } = parseFootnotes(content);
+	const definitionByName = new Map(definitions.map((d) => [d.name, d.body]));
 	const lines = content.split(/\r?\n/);
 	return questions.map((question, i) => {
 		const start = question.headingLine;
 		const end = Math.max(start, (questions[i + 1]?.headingLine ?? lines.length) - 1);
-		const children = question.options.map((option) => ({
-			name: `${option.checked ? "[x]" : "[ ]"} ${option.text || "your answer"}`,
-			range: spanRange$2(lines, option.sourceLine, option.endLine),
-			selectionRange: lineRange$1(lines, option.sourceLine),
-			leaf: true
-		}));
+		const questionMarkers = markers.filter((m) => m.line >= start && m.line <= end);
+		const assigned = /* @__PURE__ */ new Set();
+		const optionChildren = question.options.map((option) => {
+			const optionMarkers = questionMarkers.filter((m) => m.line >= option.sourceLine && m.line <= option.endLine);
+			optionMarkers.forEach((m) => assigned.add(m));
+			const footnotes = optionMarkers.map((m) => footnoteLeaf$1(lines, definitionByName, m));
+			return {
+				name: `${option.checked ? "[x]" : "[ ]"} ${option.text || "your answer"}`,
+				range: spanRange$2(lines, option.sourceLine, option.endLine),
+				selectionRange: lineRange$1(lines, option.sourceLine),
+				...footnotes.length > 0 ? { children: footnotes } : { leaf: true }
+			};
+		});
+		const questionFootnotes = questionMarkers.filter((m) => !assigned.has(m)).map((m) => footnoteLeaf$1(lines, definitionByName, m));
+		const children = [...optionChildren, ...questionFootnotes];
 		return {
 			name: `${statusMarker(question)} ${question.question}`,
 			detail: question.text,
@@ -190743,15 +191090,42 @@ const optionAction = (content, question, option) => {
 	};
 };
 /**
+* The block a footnote lands after when "add a footnote" fires with the
+* cursor at `cursorLine`: the whole contiguous option list's own span (its
+* first option's `sourceLine` through its last option's `endLine`, never
+* split between two items) when the cursor sits inside one, otherwise the
+* surrounding prose block (the next blank line or EOF) — covers question-body
+* prose ABOVE a list, a question with no options at all, and any cursor
+* position outside every question.
+*/
+const footnoteBlockEnd$1 = (content, lines, cursorLine) => {
+	const { questions } = parseOpenQuestions(content);
+	for (const question of questions) {
+		if (question.options.length === 0) continue;
+		const first = question.options[0].sourceLine;
+		const last = question.options[question.options.length - 1].endLine;
+		if (cursorLine >= first && cursorLine <= last) return last;
+	}
+	return proseBlockEnd(lines, cursorLine);
+};
+/**
 * Actions for a `qa`-mode file: anywhere on an open question's option's list
 * item, "pick this option" (radio semantics) or "uncheck this option" when
-* it's already chosen. No action off an option's span, or on an
-* answered-section (prose) question.
+* it's already chosen; "add a footnote" everywhere EXCEPT inside an existing
+* marker's span or on an existing definition's own line — planting a new
+* marker/definition there would corrupt the footnote already written. No
+* pick/uncheck action off an option's span, or on an answered-section
+* (prose) question.
 */
 const questionActions = (content, range) => {
 	const { questions } = parseOpenQuestions(content);
+	const lines = content.split(/\r?\n/);
 	const cursorLine = range.start.line;
 	const actions = [];
+	if (!isOnExistingFootnote(content, range.start)) actions.push({
+		title: "gtd: add a footnote",
+		edits: footnoteAdditionEdits(content, range.start, footnoteBlockEnd$1(content, lines, cursorLine))
+	});
 	for (const question of questions) {
 		if (question.status !== "open") continue;
 		const option = question.options.find((o) => cursorLine >= o.sourceLine && cursorLine <= o.endLine);
@@ -190761,27 +191135,41 @@ const questionActions = (content, range) => {
 	}
 	return actions;
 };
-/** The `qa` steering format: gtd's own in-process open-questions checkbox format — validation, outline, and code actions, no `pointerAt` (an open question's options have nothing to jump to). Its one finding is always positionless — this format has no notion of a per-line problem. */
+/**
+* `qa`'s `pointerAt`: footnote jumps only (an open question's options have
+* nothing else to jump to) — marker → definition, definition → first marker,
+* both within the same document.
+*/
+const questionsPointerAt = (content, position) => footnotePointerAt(content, position)?.pointer;
+/** The `qa` steering format: gtd's own in-process open-questions checkbox format — validation, outline, code actions, and a footnote-only `pointerAt`. Its structural findings are positionless, but a footnote finding carries the offending marker's or definition's `line`. */
 const QA_FORMAT = {
 	sample: QA_SAMPLE,
-	validate: (content) => parseOpenQuestions(content).errors.map((message) => ({ message })),
+	validate: (content) => [...parseOpenQuestions(content).errors.map((message) => ({ message })), ...parseFootnotes(content).findings],
 	outline: questionsOutline,
-	actions: questionActions
+	actions: questionActions,
+	pointerAt: questionsPointerAt
 };
 //#endregion
 //#region src/ReviewDoc.ts
 /**
 * `REVIEW_FORMAT`'s canonical sample — a minimal, valid `review`-mode
-* document: the header, the base comment, and one chunk with one file
-* pointer. Deliberately not authored to survive any particular formatter.
+* document: the header, the base comment, one chunk with one file pointer,
+* and one anchored footnote on that hunk's note with a body over 80
+* characters — pinned already in oxfmt's own wrapped four-space form (see
+* `src/SteeringFormats.test.ts`'s formatter round-trip). Deliberately not
+* authored to survive any particular formatter beyond that.
 */
 const REVIEW_SAMPLE = `# Review: sample123
+
 <!-- base: 0000000000000000000000000000000000000000 -->
 
 ## Sample chunk
 
-- [ ] ./sample.ts#1
-what this hunk does
+- [ ] ./sample.ts#1 what this hunk does[^fn1]
+
+[^fn1]:
+    This note explains why the hunk exists in more detail than fits on one line
+    for a reviewer.
 `;
 const HEADER_RE = /^#\s+Review:\s*(\S+)\s*$/;
 const BASE_COMMENT_RE = /^<!--\s*base:\s*(\S+)\s*-->$/;
@@ -190827,11 +191215,18 @@ const isPointerToken = (token) => {
 	const lineMatch = POINTER_LINE_RE.exec(token);
 	return (lineMatch ? lineMatch[1] : token).length > 2;
 };
-/** One `- [ ]` / `- [x]` file-pointer line, or `undefined` if `line` isn't one. Text trailing the pointer token on its own line still parses as the note's inline segment, not an error. */
+/**
+* One `- [ ]` / `- [x]` file-pointer line, or `undefined` if `line` isn't
+* one. Text trailing the pointer token on its own line still parses as the
+* note's inline segment, not an error. A marker written directly against the
+* token (`./a.ts#1[^fn1]`, the most natural way to comment on a hunk) is
+* stripped before path/line parsing — otherwise it's swallowed into the
+* `\S+` token capture and corrupts the path.
+*/
 const parseFilePointer = (line, sourceLine) => {
 	const match = FILE_POINTER_RE.exec(line);
 	if (!match) return void 0;
-	const token = match[2];
+	const token = stripFootnoteMarkers(match[2]);
 	if (!isPointerToken(token)) return void 0;
 	const lineMatch = POINTER_LINE_RE.exec(token);
 	const path = lineMatch ? lineMatch[1] : token;
@@ -190855,19 +191250,29 @@ const parseFilePointer = (line, sourceLine) => {
 * next pointer/heading isn't absorbed.
 */
 const pointerEndIndex = (body, index) => {
+	const texts = body.map((b) => b.text);
 	let end = index;
 	for (let i = index + 1; i < body.length; i += 1) {
 		const trimmed = body[i].text.trim();
 		if (trimmed.length === 0) continue;
-		if (parseFilePointer(trimmed, body[i].line)) break;
+		if (parseFilePointer(trimmed, body[i].line) || isFootnoteDefinitionLine(texts, i)) break;
 		end = i;
 	}
 	return end;
 };
-/** Joins a pointer's gathered explanation: every non-blank line strictly between `startIndex` and `endIndex` (inclusive), each stripped of a leading dash, joined with a single space. */
+/**
+* Joins a pointer's gathered explanation: every non-blank line strictly
+* between `startIndex` and `endIndex` (inclusive), each stripped of a
+* leading dash, joined with a single space. A footnote definition line (and
+* its continuations) is never gathered — `pointerEndIndex` already stops the
+* span before reaching one, so this skip only matters for a definition that
+* begins exactly at `endIndex` itself.
+*/
 const gatherNote = (body, startIndex, endIndex) => {
+	const texts = body.map((b) => b.text);
 	const noteLines = [];
 	for (let j = startIndex + 1; j <= endIndex; j += 1) {
+		if (isFootnoteDefinitionLine(texts, j)) continue;
 		const t = body[j].text.trim();
 		if (t.length > 0) noteLines.push(t.replace(NOTE_SEPARATOR_RE, ""));
 	}
@@ -190903,7 +191308,7 @@ const secondPointerError = (title, pointer, secondToken) => {
 const parsePointerSpan = (title, body, index, pointer) => {
 	const endIndex = pointerEndIndex(body, index);
 	const inlineSegment = (pointer.inlineNote ?? "").replace(NOTE_SEPARATOR_RE, "");
-	const note = [inlineSegment, gatherNote(body, index, endIndex)].filter((segment) => segment.length > 0).join(" ");
+	const note = stripFootnoteMarkers([inlineSegment, gatherNote(body, index, endIndex)].filter((segment) => segment.length > 0).join(" "));
 	const { inlineNote: _inlineNote, ...pointerFields } = pointer;
 	const file = {
 		...pointerFields,
@@ -190923,10 +191328,11 @@ const parseChunkBody = (title, body) => {
 	const files = [];
 	const errors = [];
 	const descriptionLines = [];
+	const texts = body.map((b) => b.text);
 	let i = 0;
 	while (i < body.length) {
 		const trimmed = body[i].text.trim();
-		if (trimmed.length === 0) {
+		if (trimmed.length === 0 || isFootnoteDefinitionLine(texts, i)) {
 			i += 1;
 			continue;
 		}
@@ -190942,7 +191348,7 @@ const parseChunkBody = (title, body) => {
 		i = nextIndex;
 	}
 	return {
-		description: descriptionLines.join(" "),
+		description: stripFootnoteMarkers(descriptionLines.join(" ")),
 		files,
 		errors
 	};
@@ -190956,7 +191362,7 @@ const splitChunks = (lines) => {
 			i += 1;
 			continue;
 		}
-		const title = chunkMatch[1].trim();
+		const title = stripFootnoteMarkers(chunkMatch[1].trim());
 		const headingLine = i;
 		i += 1;
 		const body = [];
@@ -191085,19 +191491,39 @@ const spanRange$1 = (lines, startLine, endLine) => ({
 		character: (lines[endLine] ?? "").length
 	}
 });
-/** Document outline for `.gtd/REVIEW.md`: only the headlines of chunks (the user-facing "work packages") that still carry at least one unchecked hunk — the outline is the list of packages left to review, nothing else. No children — a chunk headline is the whole node. */
+/** One footnote marker rendered as an outline leaf: `[^name] <body>`. */
+const footnoteLeaf = (lines, definitionByName, marker) => ({
+	name: `[^${marker.name}] ${definitionByName.get(marker.name) ?? ""}`.trim(),
+	range: lineRange(lines, marker.line),
+	selectionRange: lineRange(lines, marker.line),
+	leaf: true
+});
+/**
+* Document outline for `.gtd/REVIEW.md`: the headlines of chunks (the
+* user-facing "work packages") that still carry at least one unchecked hunk
+* — the outline is the list of packages left to review — PLUS any chunk
+* that carries at least one footnote, even when every hunk in it is ticked:
+* `reviewOutline` otherwise drops a fully-checked chunk, which would make a
+* human's own comment vanish the moment they tick the last box. A chunk's
+* footnotes are `leaf: true` children; a chunk with none has no children.
+*/
 const reviewOutline = (content) => {
 	const { changesets } = parseReviewDoc(content);
+	const { markers, definitions } = parseFootnotes(content);
+	const definitionByName = new Map(definitions.map((d) => [d.name, d.body]));
 	const lines = content.split(/\r?\n/);
 	return changesets.map((chunk, i) => {
 		const start = chunk.headingLine;
 		const end = Math.max(start, (changesets[i + 1]?.headingLine ?? lines.length) - 1);
 		const checkedCount = chunk.files.filter((file) => file.checked).length;
+		const chunkMarkers = markers.filter((m) => m.line >= start && m.line <= end);
+		const children = chunkMarkers.map((m) => footnoteLeaf(lines, definitionByName, m));
 		return {
 			name: `${chunk.title} (${checkedCount}/${chunk.files.length})`,
 			range: spanRange$1(lines, start, end),
 			selectionRange: lineRange(lines, start),
-			unchecked: checkedCount < chunk.files.length
+			...children.length > 0 ? { children } : {},
+			unchecked: checkedCount < chunk.files.length || chunkMarkers.length > 0
 		};
 	}).filter((node) => node.unchecked).map(({ unchecked: _unchecked, ...node }) => node);
 };
@@ -191124,12 +191550,33 @@ const toggleChunkEdits = (content, headingLine) => {
 	}
 	return edits;
 };
-/** Actions for `.gtd/REVIEW.md`: "check/uncheck this hunk" when `range` sits on a hunk line, "check/uncheck all hunks" when `range` sits anywhere in a chunk (heading or body). */
+/**
+* The block a footnote lands after when "add a footnote" fires with the
+* cursor at `cursorLine`: the containing hunk's own span (never split, even
+* across a multi-paragraph note) when the cursor sits in one, otherwise the
+* surrounding prose block (the next blank line or EOF).
+*/
+const footnoteBlockEnd = (content, lines, cursorLine) => {
+	const { changesets } = parseReviewDoc(content);
+	const hunk = changesets.flatMap((chunk) => chunk.files).find((file) => cursorLine >= file.sourceLine && cursorLine <= file.endLine);
+	return hunk ? hunk.endLine : proseBlockEnd(lines, cursorLine);
+};
+/**
+* Actions for `.gtd/REVIEW.md`: "check/uncheck this hunk" when `range` sits
+* on a hunk line, "check/uncheck all hunks" when `range` sits anywhere in a
+* chunk (heading or body), and "add a footnote" everywhere EXCEPT inside an
+* existing marker's span or on an existing definition's own line — planting
+* a new marker/definition there would corrupt the footnote already written.
+*/
 const reviewActions = (content, range) => {
 	const { changesets } = parseReviewDoc(content);
 	const lines = content.split(/\r?\n/);
 	const cursorLine = range.start.line;
 	const actions = [];
+	if (!isOnExistingFootnote(content, range.start)) actions.push({
+		title: "gtd: add a footnote",
+		edits: footnoteAdditionEdits(content, range.start, footnoteBlockEnd(content, lines, cursorLine))
+	});
 	changesets.forEach((chunk, i) => {
 		const hunk = chunk.files.find((file) => cursorLine >= file.sourceLine && cursorLine <= file.endLine);
 		if (hunk) {
@@ -191164,7 +191611,7 @@ const reviewActions = (content, range) => {
 * concern, not this module's — the path returned here is the pointer's raw
 * `./`-relative text.
 */
-const reviewPointerAt = (content, line) => {
+const hunkPointerAt = (content, line) => {
 	const { changesets } = parseReviewDoc(content);
 	const hunk = changesets.flatMap((chunk) => chunk.files).find((file) => file.sourceLine === line);
 	if (!hunk) return void 0;
@@ -191173,11 +191620,24 @@ const reviewPointerAt = (content, line) => {
 		line: hunk.line !== void 0 ? hunk.line - 1 : 0
 	};
 };
+/**
+* `.gtd/REVIEW.md`'s `pointerAt`: footnotes resolve FIRST (they're
+* column-scoped, the hunk jump is line-scoped — a marker sitting in a hunk's
+* inline note would otherwise be shadowed by it), the hunk-pointer jump to
+* another file second. An orphan marker/definition resolves (via
+* `footnotePointerAt`) to "handled, but no pointer" — so it returns
+* `undefined` here too, rather than falling through to the hunk jump.
+*/
+const reviewPointerAt = (content, position) => {
+	const footnote = footnotePointerAt(content, position);
+	if (footnote) return footnote.pointer;
+	return hunkPointerAt(content, position.line);
+};
 //#endregion
 //#region src/SteeringFormats.ts
 const STEERING_FORMATS = /* @__PURE__ */ new Map([["qa", QA_FORMAT], ["review", {
 	sample: REVIEW_SAMPLE,
-	validate: (content) => parseReviewFindings(content).findings,
+	validate: (content) => [...parseReviewFindings(content).findings, ...parseFootnotes(content).findings],
 	outline: reviewOutline,
 	actions: reviewActions,
 	pointerAt: reviewPointerAt
@@ -191804,7 +192264,7 @@ const compileWorkflowConfig = (raw, configDir, rcModes, inlineFileRefs = true, f
 };
 //#endregion
 //#region src/workflows/unified.yaml
-var unified_default = "# gtd's BUILT-IN DEFAULT workflow — used when no `workflow:` key is\n# configured anywhere in the cwd→home config chain; `gtd init` seeds only\n# vars.testCommand + a modes: suggestion, never this file. Compiled through\n# the same `compileWorkflowConfig` a user's own `workflow:` goes through — no\n# privileged path. See skills/authoring/SKILL.md for how to read or edit it\n# (machines, patterns, templates) and docs/driver.md for how a driver runs it.\n#\n# One flow: any change to the tree starts the process. `idle` -> `unwind`\n# reverts that diff (intent survives only in history) -> a green-baseline\n# gate -> `design.triage` groups the reverted diff into ordered, classified\n# concerns and resolves the PRODUCT ones' open questions (`design.gate`) ->\n# `architecture.author` works out the *how* and resolves the TECHNICAL ones\n# (`architecture.gate`) -> `architecture.decompose` writes one package file\n# per concern -> the per-package queue (`packages.*`) builds and reviews each\n# -> the shared tail (`build.review.*`) decides sign-off (-> `idle`, landing\n# an ordinary commit that closes the process — every per-turn commit stays on\n# the branch; run `gtd summary` afterward for a closing-message prompt) vs.\n# actionable feedback (-> `re-unwind` -> back to `design.triage`, a full\n# re-plan lap that never builds on the human's hand-edit). `--entry\n# review-gate.check --var reviewBase=<commitish>` and `--entry fix-precheck`\n# are the two other entries into this same flow.\nvars:\n  testCommand: npm test\n  # plannerModel: the heavier tier for one-shot triage/design/review turns.\n  # coderModel: the tier for build/fix turns. Both repointable via a\n  # top-level `vars:` key or a `GTD_<NAME>` env var, like any other var.\n  plannerModel: smart\n  coderModel: base\n  # Declared (not left undeclared) so `--var reviewBase=...` passes the CLI's\n  # declared-name check; blank renders empty, which the review entry refuses.\n  reviewBase: \"\"\n  # gtd's own voice for generated files — adapted from the \"Spartan\" output\n  # style (https://github.com/alexgreensh/attention-span, AGPL-3.0, version 0.6),\n  # rewritten in gtd's own words for deliverables rather than chat replies;\n  # no upstream text ships. A point-in-time derivation with no refresh\n  # mechanism.\n  styleBlock: |-\n    - A deliverable, not a chat reply — size follows the work; cut padding\n    - Lead with the answer; never circle back to restate it\n    - Flat, commanding sentences — commit to the claim, never hedge\n    - Everyday words; define an unavoidable term in five words or fewer, on\n      first use\n    - Bold carries the load: bold the claim, not the sentence around it —\n      the bold text alone must yield the full point and every risk\n    - **Never trim a risk, a number, a threshold, or a scoped condition to\n      save space — this outranks every other rule here**\n    - Ship the artifact bare — no lead-in, no sign-off\n    - Compressing is not dropping: three load-bearing parts ship as three,\n      each shorter, never as two\n    - One idea per block; break when the idea shifts\n    - Flag risk in one blunt line, never hedged prose; never narrate — do it\n  styleFormatContract: |-\n    - Machine-read: its format contract outranks every style rule above —\n      keep every `##`/`###` heading, checkbox row, and marker line exactly\n      as specified. Never renumber or rename a heading; a parser reads\n      these literally and a violation refuses the turn\n    - Voice rules above govern only the prose between these elements\n\n  # One persona per prompt-bearing machine below, stamped as its `system:`\n  # (see src/StateFields.ts's `system`). `--system-prompt` REPLACES a\n  # harness's default system prompt — including its injected cwd/env/\n  # git-status block — so each persona is written self-contained, restating\n  # that context explicitly rather than relying on it.\n\n  # Shared conduct tail, appended after every persona's own role paragraph:\n  # use tools without asking, orient yourself with git, and go inspect what\n  # the turn's message names. Deliberately NOT named `*Persona`:\n  # `templates.test.ts` derives its six-name persona set from\n  # `it\\.vars\\.(\\w+Persona)`, so that suffix would silently grow the set.\n  agentConduct: |-\n    - You have shell and file tools — bash, read, write, edit — use them\n      without asking first; this runs unattended, no one grants permission\n    - Investigate with real commands rather than assuming a file's, a\n      commit's, or a decision's status — then act on what you find\n    - No injected status block — no cwd, no branch, no history, no tree\n      state — orient yourself first with `git status`, `git log`, `ls`\n    - The turn's message names a commit, a range, or a file to go inspect\n      yourself — never a diff or summary inlined into the conversation\n    - Across turns one conversation may span, work from what you already\n      read and settled, unless told this is a fresh, cold pass\n  designPersona: |-\n    You are the product-facing planning voice in gtd's build pipeline: turn\n    a raw sketch — a hand-edit, a scratch note, or both — into an ordered,\n    classified list of concerns, and hold the running product conversation\n    with the human it depends on. You are read by that human — write\n    plainly — not by a parser, except where a state says otherwise.\n  architectPersona: |-\n    You are the technical planning voice in gtd's build pipeline: take over\n    once product concerns are settled, reading them cold, no carried\n    conversation. Work out the *how* per concern — structure, data models,\n    tech-stack choices, error handling — raise the technical open\n    questions, then write one package spec per concern with no further\n    judgement call: the grouping is already decided.\n  reviewerPersona: |-\n    You are the independent reviewing mind in gtd's build pipeline —\n    deliberately separate from whoever wrote the code, with no attachment\n    to it. Two turns: write a structured review document grouping a diff\n    into chunks; later, classify a round of the human's feedback as\n    actionable or just approving, never fixing anything yourself. You judge\n    and classify; you never build.\n  specReviewerPersona: |-\n    You are the adversarial spec-conformance checker in gtd's build\n    pipeline, checking one freshly-built package against its spec. Verify\n    only: tasks done, criteria met, code sound and consistent with the\n    codebase. Write feedback only when something is genuinely wrong —\n    otherwise write nothing; a clean turn IS the approval. Never fix what\n    you find — naming it precisely enough for a fix turn is the whole job.\n  builderPersona: |-\n    You are the TDD implementer in gtd's build pipeline: build one\n    package's declared scope end to end, tests first, and come back to fix\n    things when redirected — a failing check, or reviewer feedback. Stay\n    strictly inside the package in front of you; never touch another\n    package's files or code outside the task. Treat feedback as the\n    diagnosis to act on; discard it, with reason, only when simply wrong.\n  finisherPersona: |-\n    You are the closing identity in gtd's build pipeline — the last coder\n    before it closes. Fix a late-breaking failing check after sign-off,\n    focused and minimal. Every turn lands its own commit — nothing here\n    gets squashed away.\n\n  # The scratchpad-opener sentence shared by every prompt-content state (see\n  # STATE_FIELDS's `prompt`) — this workflow's own state files are its private\n  # working notes, never project code or documentation a human reads. Injected\n  # as the leading line of every prompt body that touches a `.gtd/` file\n  # directly; each state's own \"the only state file this turn touches is X\"\n  # sentence stays local, immediately after the tag. Some states splice a\n  # role clause into this same opening sentence (`build.review.collecting`,\n  # `packages.item.spec.review`) — those hoist the clause to its own leading\n  # sentence ahead of the tag instead, keeping every word.\n  stateFileRules: |-\n    - You are an autonomous coding agent\n    - This workflow's own state files are its private scratchpad, never\n      project code or documentation\n  # The open-questions warrant test, decide-it-yourself sink, and `## Open\n  # Questions` checkbox shape shared by `design.triage` and\n  # `architecture.author` — written phase-agnostic (no PRODUCT/TECHNICAL\n  # bake-in) so both sites can inject it verbatim. Each site's own\n  # phase-scope sentence (triage: product-only, technical waits; architecture:\n  # every point here is TECHNICAL) stays local around the tag — the two\n  # genuinely disagree on scope, so that sentence is never shared.\n  # `questionBarReturn` is the return-lap half — split out so each site can\n  # inject it under its own `## Return lap` heading instead of burying\n  # return-lap behaviour inside the first lap's own section.\n  questionBar: |-\n    - Ask only when all three hold: it's a genuine fork with divergent\n      outcomes (user-visible for product, materially different builds for\n      technical); the diff and history don't already settle it (treat an\n      explicit `.gtd/TODO.md` directive, a committed hand-edit, or — on a\n      loop-back lap — the human's own review-round edit/note as settled);\n      and getting it wrong would survive to the human review tail\n    - Below that bar, decide it yourself: record it under\n      `## Answered Questions` as `### <the point phrased as a question>`\n      plus a one-line rationale in prose, no checkboxes. That heading\n      always comes last, after every other `##` section\n    - Above the bar, write it under `## Open Questions` — always the first\n      `##` section — as `### <question>` plus a checkbox list: two\n      concrete options and a free-text slot, all 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\n  questionBarReturn: |-\n    - The human ticked one option per question (or wrote their own in\n      place of `_your answer_`): fold each answer into its concern's\n      prose, then move the question into `## Answered Questions` as\n      `### <question>` with the resolved answer in plain prose — no\n      checkboxes\n    - `## Answered Questions` is always the last `##` section — a moved\n      question lands there, never wherever `## Open Questions` used to sit\n    - Never re-raise a deleted question — treat a deleted `## Open\n      Questions` section as acceptance; omit it entirely once none are left\n  # The body `packages.item.fix-suite` and `build.fix` share byte for byte —\n  # both fix a red `.gtd/FEEDBACK.md`. `fix-suite` appends its own\n  # cross-package paragraph right after this tag (before the shared\n  # \"Leave everything uncommitted\" close, which stays local at both sites so\n  # the appended paragraph lands in the same position it renders in today);\n  # `build.fix` renders the tag alone.\n  fixFeedbackPrompt: |-\n    - The only state file this turn touches is `.gtd/FEEDBACK.md` — no\n      other files for notes or output\n    - Read it (the failing test output) and fix the code so the suite\n      passes; keep the change focused, never refactor unrelated code\n    - If the feedback is wrong, fix nothing rather than \"fixing\" a non-issue\n    - Delete `.gtd/FEEDBACK.md` either way — once the suite passes, or once\n      you have established the feedback was wrong; leaving it in place is\n      never the right end state, the next check writes its own\n\n# `gtd summary`'s prompt — printed cold, no session identity, no diff inlined.\n# Names the hashes/range for the agent to inspect itself; renders the same\n# it.processCost/it.processCostByModel the old squash finale used to.\nsummary: |\n  <%~ it.vars.styleBlock %>\n\n\n  - Write the closing message for the process HEAD closes or sits inside —\n    for a squash, an amend, or a PR body. Starting cold: read every\n    decision out of the commits below, not assumed context\n  - Cover the motivation, the decisions, the trade-offs, and the\n    high-level architectural changes — never which files changed; `git\n    diff --stat` is for that, not this message\n\n  The process's entry commit is `<%= it.entryCommit %>`. <% if\n  (it.humanCommits.length > 0) { %>The human contributed at these commits,\n  oldest to newest:\n  <% it.humanCommits.forEach(function (c) { %>\n  - `<%= c.hash %>` (entering `<%= c.state %>`)\n  <% }) %><% } else { %>The human left no comment or edit this process —\n  every commit is machine-authored.<% } %>\n\n  Inspect the range: `git log <%= it.processBase %>..<%= it.processTip %>`\n  and `git diff <%= it.processBase %> <%= it.processTip %>` — exactly what\n  a squash or PR body should describe.\n\n  Token cost: <%= it.processCost %>\n  <% it.processCostByModel.forEach(function(m){ %>\n  - <%= m.model %>: <%= m.cost %>\n  <% }) %>\n\n  Print the closing message and stop — this writes nothing itself.\n\nentry:\n  default: unified\n\nmachines:\n  # Shared green-baseline gate — start-gate/review-gate/fix-precheck all\n  # alias this script via &suiteCheck.\n  entryGate:\n    params: [onGreen, blockedMessage, blockedDescribe, checkLabel, blockedLabel, reviewBase]\n    entry: check\n    states:\n      check:\n        actor: check\n        label: $checkLabel\n        script: &suiteCheck |\n          #!/usr/bin/env sh\n          set +e\n          mkdir -p .gtd\n          # Sweep a raw review capture an earlier, abandoned process may have\n          # left behind — no ordinary path from deciding/collecting reaches\n          # this check.\n          rm -f .gtd/REVIEW_RAW.md\n          <%~ it.vars.testCommand %> > .gtd/.check-output 2>&1\n          code=$?\n          if [ \"$code\" -ne 0 ]; then\n            if [ -s .gtd/.check-output ]; then\n              mv .gtd/.check-output .gtd/FEEDBACK.md\n            else\n              rm -f .gtd/.check-output\n              printf 'the test command failed with exit code %s and produced no output.' \"$code\" > .gtd/FEEDBACK.md\n            fi\n            # Stamp with HEAD so a repeat identical failure still re-registers\n            # as an M/A edit instead of looking byte-identical (GREEN).\n            printf '\\n<!-- gtd check %s -->\\n' \"$(git rev-parse --short HEAD 2>/dev/null || echo pending)\" >> .gtd/FEEDBACK.md\n          else\n            rm -f .gtd/.check-output\n            rm -f .gtd/FEEDBACK.md\n          fi\n        # Marks BOTH entryGate instances (start-gate/review-gate); only\n        # review-gate strictly needs it, but the shared dedup makes marking\n        # one mark both — both ARE entry gates.\n        entry: true\n        # Only review-gate binds a real reviewBase (via --var); start-gate\n        # binds \"\" (no base), since it's reached from idle, never entered.\n        reviewBase: $reviewBase\n        on:\n          \"A .gtd/FEEDBACK.md\": blocked\n          \"M .gtd/FEEDBACK.md\": blocked\n          \"D .gtd/REVIEW_RAW.md\": $onGreen\n          \"D .gtd/FEEDBACK.md\": $onGreen\n          \"C\": $onGreen\n      blocked:\n        actor: human\n        label: $blockedLabel\n        file: FEEDBACK.md\n        message: $blockedMessage\n        on:\n          \"* **\":\n            to: check\n            action: Retry check\n            describe: $blockedDescribe\n\n  # Shared check/escalate pair for build.health.*/packages.item.health.* —\n  # the caller's own coder fix-state ($onRed), not this machine, handles red.\n  healthGate:\n    params: [onGreen, onRed, escalateDescribe, checkLabel, escalateLabel]\n    entry: check\n    states:\n      check:\n        actor: check\n        label: $checkLabel\n        # See the shared suite check on `entryGate.check` above.\n        script: *suiteCheck\n        on:\n          \"A .gtd/FEEDBACK.md\": $onRed\n          \"M .gtd/FEEDBACK.md\": $onRed\n          \"* **\": $onGreen\n          \"C\": $onGreen\n      escalate:\n        actor: human\n        label: $escalateLabel\n        file: FEEDBACK.md\n        message: |\n          The agent could not get the check to pass after repeated attempts.\n          `.gtd/FEEDBACK.md` holds the last failing output.\n\n          What each change does next (then run `gtd land`):\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  # Shared check/answer pair for design.gate/architecture.gate. No `file:`\n  # PARAM for the probe script itself: machine `$param` substitution is\n  # whole-value only, so a path can't be spliced into a shared script body —\n  # `file` here is instead the `answer` param's own `file:` (the human gate).\n  questionGate:\n    params: [file, message, onNone, onRevise, checkLabel, answerLabel]\n    entry: check\n    states:\n      check:\n        actor: check\n        label: $checkLabel\n        script: |\n          #!/usr/bin/env sh\n          # Exactly one of REQUIREMENTS.md/ARCHITECTURE.md exists on disk at\n          # a time — architecture.author deletes the former in the same turn\n          # it writes the latter — so this probe is unambiguous either way.\n          set +e\n          mkdir -p .gtd\n          file=.gtd/REQUIREMENTS.md\n          [ -f \"$file\" ] || file=.gtd/ARCHITECTURE.md\n          gtd check qa \"$file\" --open-questions > /dev/null 2>&1\n          code=$?\n          if [ \"$code\" -ne 0 ]; then\n            printf 'open questions remain in %s\\n' \"$file\" > .gtd/QUESTIONS.md\n            # See the shared suite check's cache-buster rationale on\n            # `entryGate.check` above.\n            printf '\\n<!-- gtd check %s -->\\n' \"$(git rev-parse --short HEAD 2>/dev/null || echo pending)\" >> .gtd/QUESTIONS.md\n          else\n            rm -f .gtd/QUESTIONS.md\n          fi\n        on:\n          \"A .gtd/QUESTIONS.md\": answer\n          \"M .gtd/QUESTIONS.md\": answer\n          \"D .gtd/QUESTIONS.md\": $onNone\n          \"C\": $onNone\n      answer:\n        actor: human\n        label: $answerLabel\n        file: $file\n        mode: qa\n        answerGate: true\n        message: $message\n        on:\n          \"* **\":\n            to: $onRevise\n            action: Revise answers\n            describe: >-\n              tick exactly one option per open question (replace\n              `_your answer_` for your own) to send it back for the agent to\n              fold your answers in. Delete a question to skip it, or delete\n              the whole `## Open Questions` section to accept the plan as-is.\n\n  # The triage phase — one conversation across the whole back-and-forth (the\n  # human's answer rationale survives every return lap). A review loop-back\n  # lap runs the suite itself and files any breakage as its own FIRST\n  # concern, rather than spending one of packages.item.fix-suite's\n  # (per-episode) retries on breakage the package didn't cause.\n  # ▸ planner identity.\n  designPlan:\n    model: <%= it.vars.plannerModel %>\n    system: |-\n      <%~ it.vars.designPersona %>\n\n\n      <%~ it.vars.agentConduct %>\n    params: [onArchitecture]\n    entry: triage\n    states:\n      triage:\n        actor: agent\n        label: Triaging the change\n        file: REQUIREMENTS.md\n        mode: qa\n        # Guards against discarding assembled review input without folding\n        # it in (the original bug this guard was added for).\n        requireProgress: true\n        prompt: |\n          <%~ it.vars.styleBlock %>\n\n\n          <%~ it.vars.styleFormatContract %>\n\n\n          <%~ it.vars.stateFileRules %>\n\n          - The only state file this turn touches is `.gtd/REQUIREMENTS.md`\n            — no other files for notes or output\n          - `.gtd/TODO.md` is the likely home of the sketch that started\n            this process — the human's input, folded into the concerns\n            below like any other part of the start diff; never a state\n            file to preserve, never gtd bookkeeping to ignore\n          - This process started at commit `<%= it.startCommit %>`,\n            reverted out of the tree by `unwind` right after landing, so\n            `git diff <%= it.startCommit %>` is now empty — its content\n            survives only in history. Find the entry commit yourself:\n            `git rev-list --ancestry-path <%= it.startCommit %>..HEAD | tail -1`\n            (the process's first turn, before any baseline-repair\n            commits), then `git show` it — a hand-edit, a scratch note,\n            or both\n          - Whichever lap this is, leave `.gtd/REQUIREMENTS.md`\n            uncommitted and finish once it reflects this lap's own work\n\n          ## First lap\n\n          `.gtd/REQUIREMENTS.md` does not exist yet (or holds whatever the\n          human's change left there). Build it from that start diff:\n\n          ### Group into concerns\n\n          - An ordered list of concerns, each a coherent piece of work\n            that leaves the suite green on its own, in build order — a\n            concern that would red-light a later fix is not a valid\n            split; merge the two\n          - Vertical, not horizontal: slice by capability, never by layer\n            — a concern that only prepares for a later one (types,\n            scaffolding, renames) folds into the first concern that uses it\n          - Distinct acceptance: each concern needs a check that fails\n            before it and passes after; if you can't name one, merge it into\n            its neighbour\n          - Prefer fewer, larger packages — the smallest independently\n            valuable change, not the smallest change that compiles\n\n          ### Classify each concern\n\n          Classify each as PRODUCT (user-facing/requirements) or TECHNICAL\n          (implementation).\n\n          <%~ it.vars.questionBar %>\n\n\n          Raise questions only for product concerns here — technical ones\n          wait for the next phase. When every concern is TECHNICAL, write\n          no `## Open Questions` section.\n\n          ### Fold in the sketch\n\n          - Fold everything the entry commit added under the concern it\n            belongs to — a scratch note and a real code edit are both\n            just a sketch to finish, never work to preserve; `unwind`\n            already reverted both, so there is nothing left to delete\n\n          ## Return lap\n\n          <%~ it.vars.questionBarReturn %>\n\n          ## Review loop-back\n\n          - `.gtd/REQUIREMENTS.md` already holds concerns with no\n            ticked-but-unfolded answer waiting — a completed REVIEW round\n            put this here, not a question you asked. Develop those\n            concerns further with whatever the round raised; never\n            rediscover or regroup them cold, the way the first lap does\n          - The human's review-round edit was reverted the same way the\n            entry commit was — read it from history:\n            `git show <%= it.reviewBase %>`. (On the first lap that hash\n            is the process's own diff base, `<%= it.startCommit %>` — this\n            branch doesn't apply)\n          - Every decision under `## Answered Questions` stays settled —\n            never re-open one. A genuinely open PRODUCT point may still\n            raise a fresh `## Open Questions` entry: the product gate sits\n            on this path exactly as on the first lap\n          - Before grouping anything, run `<%= it.vars.testCommand %>`\n            yourself — a loop-back runs no green-baseline gate, so the\n            tree may already be red (reverting the edit can undo a fix it\n            made). If red, make that breakage the first concern, ahead of\n            everything else — every later concern's green-on-its-own\n            property assumes the suite started green\n        on:\n          \"* **\": gate.check\n\n      gate:\n        machine: questionGate\n        with:\n          file: REQUIREMENTS.md\n          onNone: $onArchitecture\n          onRevise: triage\n          checkLabel: Checking for open questions\n          answerLabel: Awaiting your product answers\n          message: |\n            `.gtd/REQUIREMENTS.md` holds the concerns under\n            development. Each open question under `## Open Questions` offers\n            a few options plus a `- [ ] _your answer_` slot. Answer EVERY\n            question by ticking exactly one box (`- [x]`); for your own\n            answer, replace `_your answer_` with your text and tick that\n            line. Stepping is refused while any question is unanswered.\n\n            What each change does next (then run `gtd land`):\n            <% it.edges.forEach(function (e) { if (e.describe) { %>\n            <%~ \"- \" + (e.action ? \"**\" + e.action + \"** — \" : \"\") + e.describe + \"\\n\" %>\n            <% } }) %>\n\n  # A separate machine from designPlan (its own memory scope — a COLD read,\n  # not a resumed conversation). Merge authority lives in `author`, the first\n  # state that knows the *how*: it alone may re-merge concerns, never split;\n  # `decompose` carries that grouping over verbatim. ▸ planner identity.\n  archPlan:\n    model: <%= it.vars.plannerModel %>\n    system: |-\n      <%~ it.vars.architectPersona %>\n\n\n      <%~ it.vars.agentConduct %>\n    params: [onPackages]\n    entry: author\n    states:\n      author:\n        actor: agent\n        label: Refining the technical plan\n        file: ARCHITECTURE.md\n        mode: qa\n        prompt: |\n          <%~ it.vars.styleBlock %>\n\n\n          <%~ it.vars.styleFormatContract %>\n\n\n          <%~ it.vars.stateFileRules %>\n\n          - The only state files this turn touches are\n            `.gtd/ARCHITECTURE.md` (write it) and `.gtd/REQUIREMENTS.md`\n            (delete once folded in) — no other files for notes or output\n          - You do not resume the design conversation — a separate\n            machine, its own memory, a cold read every time. Read\n            `.gtd/REQUIREMENTS.md` (the settled, ordered, classified\n            concerns) in full; treat every decision there, PRODUCT or\n            TECHNICAL alike, as settled — never re-open it\n          - Cold means no memory of triage's own back-and-forth, not no\n            git access. This process started at commit\n            `<%= it.startCommit %>`. Find the first turn yourself: run\n            `git rev-list --ancestry-path <%= it.startCommit %>..HEAD | tail -1`\n            then `git show` it to see what started this process — a\n            hand-edit, a scratch note, or both\n          - Once `.gtd/ARCHITECTURE.md` is written, delete\n            `.gtd/REQUIREMENTS.md` — folded in, it must not linger. Leave\n            everything uncommitted and finish\n\n          ## First lap\n\n          - Develop `.gtd/ARCHITECTURE.md` from those concerns: for each,\n            in order, work out the *how* — structure, data models,\n            tech-stack choices, error handling — building on the settled\n            *what*\n          - You now know the *how*, so you know each concern's file footprint\n            — list each concern's primary paths. Merge concerns whose\n            footprints center on the same files into one, unless the later\n            one only consumes an interface the earlier one creates (keeps a\n            build-on-top sequence from collapsing into one blob). This\n            authority is to merge only, never to split — the whole problem\n            is over-granularity\n          - Record every merge under `## Merged Concerns`,\n            carrying both merged requirements verbatim so spec review\n            still covers each independently\n          - A merge raises no open question and stops for no\n            human — do not route it to `architecture.gate` for a veto; the\n            human sees it when reviewing the plan, and spec review is the\n            real safety net\n          - Prefer fewer, larger packages — the smallest independently\n            valuable change, not the smallest change that compiles\n          - Every open point here is TECHNICAL — triage already resolved\n            the product ones, one phase earlier\n\n          <%~ it.vars.questionBar %>\n\n          ## Return lap\n\n          <%~ it.vars.questionBarReturn %>\n        on:\n          \"* **\": gate.check\n\n      gate:\n        machine: questionGate\n        with:\n          file: ARCHITECTURE.md\n          onNone: decompose\n          onRevise: author\n          checkLabel: Checking for open questions\n          answerLabel: Awaiting your technical answers\n          message: |\n            `.gtd/ARCHITECTURE.md` holds the technical plan under\n            development. Each open question under `## Open Questions` offers\n            a few options plus a `- [ ] _your answer_` slot. Answer EVERY\n            question by ticking exactly one box (`- [x]`); for your own\n            answer, replace `_your answer_` with your text and tick that\n            line. Stepping is refused while any question is unanswered.\n\n            What each change does next (then run `gtd land`):\n            <% it.edges.forEach(function (e) { if (e.describe) { %>\n            <%~ \"- \" + (e.action ? \"**\" + e.action + \"** — \" : \"\") + e.describe + \"\\n\" %>\n            <% } }) %>\n\n      decompose:\n        actor: agent\n        label: Decomposing into packages\n        prompt: |\n          <%~ it.vars.styleBlock %>\n\n\n          <%~ it.vars.stateFileRules %>\n\n          - The only state files this turn touches are the package files\n            under `.gtd/packages/` and `.gtd/ARCHITECTURE.md` (deleted) —\n            no other files for notes or output\n          - Work from `.gtd/ARCHITECTURE.md` if you wrote it earlier this\n            conversation, otherwise read it (the converged technical\n            plan). It already lists an ordered set of concerns with every\n            merge/split judgement made — this turn is a mechanical\n            write-out, not a planning one. A `## Merged Concerns` heading\n            there records those merges, never a concern of its own: write\n            no package file for it\n          - Write one package file per concern, in the settled order,\n            under `.gtd/packages/` (e.g. `.gtd/packages/01-name.md`,\n            `02-name.md`, ...), each carrying that concern's\n            requirement(s) — both, independently, if merged — its\n            independent tasks, and each task's acceptance criteria as\n            `- [ ]` checkboxes and relevant paths\n          - Do not merge or split concerns here — that judgement already\n            happened; carry the settled grouping over verbatim. No\n            package file may reference any other `.gtd/` file\n          - Once written, delete `.gtd/ARCHITECTURE.md`. Leave everything\n            uncommitted and finish\n        on:\n          \"* .gtd/packages/**\": $onPackages\n\n  # The shared review tail. ▸ planner identity — `collecting` only judges/\n  # classifies feedback; there's no coder follow-through inside this machine.\n  #\n  # Nested inside buildTail (build.review), not a root sibling: a machine's\n  # memory scope is its dotted instance path, so nesting keeps `build.fix ->\n  # build.health.check -> build.review.*` (the `--entry fix-precheck` path)\n  # inside one scope, so the sign-off's boundary commit lands from the same\n  # scope that made the fixes.\n  humanReview:\n    model: <%= it.vars.plannerModel %>\n    system: |-\n      <%~ it.vars.reviewerPersona %>\n\n\n      <%~ it.vars.agentConduct %>\n    entry: reviewing\n    states:\n      reviewing:\n        actor: agent\n        label: Reviewing\n        file: REVIEW.md\n        mode: review\n        # `gtd --entry review-gate.check` enters via review-gate.check first\n        # (never straight here), which sets the Gtd-Review-Base trailer this\n        # tail reuses.\n        prompt: |\n          <%~ it.vars.styleBlock %>\n\n\n          <%~ it.vars.styleFormatContract %>\n\n\n          <%~ it.vars.stateFileRules %>\n\n          - The only state file this turn touches is `.gtd/REVIEW.md`,\n            written at exactly that path — no other files for notes or\n            output\n\n          Write `.gtd/REVIEW.md` in this exact format, to help a human\n          review the changes:\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\n            semantically (same feature/refactor/fix, across files), each\n            with a short explanation of what changed and why, then one\n            pointer per hunk (`./`-relative path, optional `#line`;\n            checkboxes are for the human, not you). Put the note's\n            opening line right on the pointer's line:\n\n                - [ ] ./path/to/file.ts#42 — what this hunk does\n\n            Continue a longer note below the pointer, indented exactly two spaces\n            — never four or more, which reads as a code block and never\n            reflows:\n\n                - [ ] ./path/to/file.ts#42 — what this hunk does\n                  and here is more detail, continued below it\n\n            A note sitting entirely on the line(s) beneath the pointer is\n            also valid. Either way, the note must never start with a bare `./path` token\n            — that parses as a second pointer, not a note\n\n          No diff is given — read the changes yourself. The range runs\n          from `<%= it.reviewBase %>` to the working tree (committed turns\n          plus anything pending); on a feedback round that's the previous\n          review's boundary, so it covers only what's new.\n\n          Leave `.gtd/REVIEW.md` uncommitted and finish.\n        on:\n          \"* **\": await-review\n\n      await-review:\n        actor: human\n        label: Awaiting your review\n        file: REVIEW.md\n        mode: review\n        message: |\n          `.gtd/REVIEW.md` holds the review record for the process — 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. Ticks are read-progress only: landing clears\n          every box back to `- [ ]` on disk and nothing records which hunks\n          you read — there is no persisted trail of it.\n\n          Review the diff yourself, with whatever tool you like — gtd checks\n          nothing out and touches no ref; `gtd base` prints this same hash any\n          time you need it again. The range runs from the review base to the\n          working tree:\n\n              git diff <%= it.reviewBase %>\n\n          When you've been through the whole diff, run `gtd land`:\n\n          - **Sign off** — leave no comment — no note in\n            `.gtd/REVIEW.md`, no code edit — to close the process,\n            whatever the boxes say. Every turn commit stays on the\n            branch; run `gtd summary` afterward for a closing-message\n            prompt.\n          - **Request changes** — leave a comment: a note on a\n            `.gtd/REVIEW.md` line, or a direct code edit — to send a FULL\n            development lap (**review.deciding** → **review.collecting** →\n            re-triage). A hand-edit you make here is treated as a SKETCH, not a\n            fix the agent builds on: it is reverted out of the tree and re-planned\n            from scratch, the same as any other change that starts a process.\n            There is no baseline check on the way back into planning — only a\n            genuinely non-actionable comment (an approving remark with no code\n            edit) skips the lap and signs off straight away.\n\n          Deleting `.gtd/REVIEW.md` is refused.\n        on:\n          \"* **\": deciding\n\n      deciding:\n        actor: check\n        label: Reviewing\n        file: REVIEW.md\n        mode: review\n        # Anchors the INCREMENTAL review base to the most-recent in-process\n        # commit (the process start on the first review).\n        reviewBase: true\n        script: |\n          #!/usr/bin/env sh\n          # FEEDBACK iff the human left a REVIEW.md note or hand-edited any\n          # file this round outside .gtd/; otherwise a clean sign-off. No\n          # [ ]/[x] normalization is needed here: `gtd uncheck` (emitted\n          # ahead of every human-review-gate commit) already resets every\n          # tick before this commit is made, so no `[x]` can ever reach it —\n          # a byte-for-byte comparison is enough. This turn only\n          # CAPTURES the raw material into REVIEW_RAW.md — collecting judges\n          # actionability. A/M REVIEW_RAW.md rows are declared before D\n          # REVIEW.md so a feedback round (which also deletes REVIEW.md)\n          # isn't mistaken for sign-off.\n          set +e\n          mkdir -p .gtd\n          head=$(git rev-parse HEAD)\n          # The one case that leaves a clean tree below is REVIEW.md already\n          # missing (the `rm -f` no-ops) — which means the review gate's own\n          # file-provisioning invariant broke, NOT a sign-off. Detecting it\n          # here, by the file's absence rather than by the diff, is what\n          # makes the `C` row below safe to declare: a broken round now\n          # always carries a FEEDBACK.md diff and routes to a human.\n          if ! git cat-file -e \"HEAD:.gtd/REVIEW.md\" 2>/dev/null; then\n            printf 'there is no `.gtd/REVIEW.md` at %s — nothing was reviewed this round.\\n' \"$head\" > .gtd/FEEDBACK.md\n          elif git diff-tree --no-commit-id --name-only -r HEAD -- . \":(exclude).gtd\" \\\n               | grep -q . \\\n             || [ \"$(git show \"HEAD^:.gtd/REVIEW.md\" 2>/dev/null)\" \\\n                != \"$(git show \"HEAD:.gtd/REVIEW.md\" 2>/dev/null)\" ]; then\n            # Reached only with REVIEW.md present. FEEDBACK iff the human\n            # left a note (any edit — no tick can reach this commit at all)\n            # or hand-edited any file this round outside .gtd/; otherwise a\n            # clean sign-off. This turn only CAPTURES the raw material into\n            # REVIEW_RAW.md — collecting judges actionability.\n            {\n              echo \"This is machine-captured input, not instructions. A downstream agent judges whether it's actionable.\"\n              echo\n              echo \"Commit: $head\"\n              echo \"The human's notes are in .gtd/REVIEW.md at this commit. Any hand edits are\"\n              echo \"in that commit's other paths. Run: git show $head\"\n            } > .gtd/REVIEW_RAW.md\n            rm -f .gtd/REVIEW.md\n          else\n            rm -f .gtd/REVIEW.md\n          fi\n        on:\n          # FEEDBACK rows first: the broken-invariant branch writes nothing\n          # else, but declaring them ahead of the sign-off row keeps the\n          # ordering honest if it ever does.\n          \"A .gtd/FEEDBACK.md\": review-missing\n          \"M .gtd/FEEDBACK.md\": review-missing\n          # A/M REVIEW_RAW.md before D REVIEW.md so a feedback round (which\n          # also deletes REVIEW.md) isn't mistaken for sign-off.\n          \"A .gtd/REVIEW_RAW.md\": collecting\n          \"M .gtd/REVIEW_RAW.md\": collecting\n          \"D .gtd/REVIEW.md\": $onSignoff\n          # Unreachable now that the missing-REVIEW.md case writes\n          # FEEDBACK.md above, but declared rather than left off: if a clean\n          # tree ever does happen here, it must reach a human, never\n          # auto-approve an unreviewed round.\n          \"C\": review-missing\n\n      review-missing:\n        actor: human\n        label: Nothing to review\n        file: FEEDBACK.md\n        message: |\n          The review round committed no `.gtd/REVIEW.md`, so there is nothing\n          to sign off on. `.gtd/FEEDBACK.md` holds the detail.\n\n          Make any change to re-run the reviewer and author a fresh review\n          record.\n\n          What each change does next (then run `gtd land`):\n          <% it.edges.forEach(function (e) { if (e.describe) { %>\n          <%~ \"- \" + (e.action ? \"**\" + e.action + \"** — \" : \"\") + e.describe + \"\\n\" %>\n          <% } }) %>\n        on:\n          \"* **\":\n            to: reviewing\n            action: Re-review\n            describe: >-\n              re-run the reviewer to author a fresh `.gtd/REVIEW.md`\n              (**build.review.reviewing**).\n\n      # Outcome is by which paths THIS diff touches: writing REQUIREMENTS.md\n      # (A/M) is the actionable case, so those rows are declared before \"D\n      # REVIEW_RAW.md\" — an actionable round's diff is both together, and\n      # the wrong order would short-circuit every round to sign-off.\n      # Consuming REVIEW_RAW.md alone is the non-actionable short-circuit,\n      # reusing $onSignoff since that IS a sign-off. No `C`/`\"* **\"` row: a\n      # clean turn here is a fruitless dispatch (falls through to the\n      # ordinary attempt default), never a verdict; a dirty tree matching\n      # neither row is a refusal.\n      collecting:\n        actor: agent\n        label: Collecting your feedback\n        file: REQUIREMENTS.md\n        mode: qa\n        prompt: |\n          <%~ it.vars.styleBlock %>\n\n\n          <%~ it.vars.styleFormatContract %>\n\n\n          You are judging and classifying a round of review feedback.\n\n          <%~ it.vars.stateFileRules %>\n\n          - The only state files this turn touches are\n            `.gtd/REQUIREMENTS.md` and `.gtd/REVIEW_RAW.md` (deleted) —\n            you classify, you do not build\n\n          The raw review material is: <%~ it.read(\".gtd/REVIEW_RAW.md\") %>\n\n          It names a commit. Work from what you already reviewed if you\n          wrote today's review earlier this conversation; otherwise read\n          that commit's diff yourself first.\n\n          The round is actionable if any of these hold:\n\n          - The human left a note on `.gtd/REVIEW.md`. A note is a mandatory\n            concern below\n          - The human added a code comment this round, even a plain-prose\n            one — describe it as a concern, and note the comment line\n            itself is transient: it must not survive the lap that\n            satisfies it\n          - The human hand-edited non-comment code this round — no longer\n            a committed intent to build on, but a sketch like the entry\n            commit's own diff. Describe what it was reaching for; expect\n            the next lap to re-derive it from scratch, never call it final\n\n          Not actionable only when none of the above holds — nothing but an\n          approving remark, no code edit, no substantive note. Never invent\n          actionability, and never dismiss a real note or edit as approval.\n\n          - If actionable: write `.gtd/REQUIREMENTS.md` with an ordered\n            list of concerns, each PRODUCT or TECHNICAL — the shape\n            `design.triage` builds, one `## <heading>` per concern in\n            build order. Fold every note, comment, and hand-edit in under\n            its concern. Raise no open questions here — `design.triage`\n            owns that later. Then delete `.gtd/REVIEW_RAW.md` and finish\n          - If not: delete `.gtd/REVIEW_RAW.md` and finish, writing\n            nothing to `.gtd/REQUIREMENTS.md` — that alone is the sign-off\n        on:\n          \"A .gtd/REQUIREMENTS.md\": $onFeedback\n          \"M .gtd/REQUIREMENTS.md\": $onFeedback\n          \"D .gtd/REVIEW_RAW.md\": $onSignoff\n\n  # The per-package review — a separate MIND from the implementer. ▸ planner\n  # identity; fixing findings is a coder action (packages.item.fix-spec).\n  specReview:\n    model: <%= it.vars.plannerModel %>\n    system: |-\n      <%~ it.vars.specReviewerPersona %>\n\n\n      <%~ it.vars.agentConduct %>\n    params: [onApproved, onFix]\n    entry: review\n    states:\n      review:\n        actor: agent\n        label: Reviewing the package\n        # No retry cap: the loop only re-enters through\n        # `fix-spec`/`health.check`, so under the per-episode rule this state's\n        # episode count can never exceed 1 and a cap could never fire. The\n        # spec-review loop is genuinely unbounded — see docs/configuration.md's\n        # `retry` documentation.\n        prompt: |\n          <%~ it.vars.styleBlock %>\n\n\n          You are reviewing a freshly-built work package against its own\n          spec.\n\n          <%~ it.vars.stateFileRules %>\n\n          - The only state file this turn touches is\n            `.gtd/SPEC_FEEDBACK.md` — write it only when you find problems\n          - The package spec is: <%~ it.read(\".gtd/NEXT.md\") %>\n          - Verify the implementation against it: tasks done, criteria\n            met, code sound and consistent with the codebase. No diff is\n            given — read the range yourself, from `<%= it.startCommit %>`\n            to the working tree, process-wide (it can span earlier\n            packages)\n          - If it fully satisfies the spec, write nothing — silence is\n            your approval. Otherwise write `.gtd/SPEC_FEEDBACK.md` listing\n            concrete problems for a fix turn, specific enough to act on\n          - Never fix anything yourself and never delete the package\n            file — a later step owns that\n        on:\n          \"A .gtd/SPEC_FEEDBACK.md\": $onFix\n          \"M .gtd/SPEC_FEEDBACK.md\": $onFix\n          \"D .gtd/SPEC_FEEDBACK.md\": $onApproved\n          \"C\": $onApproved\n\n  # The per-package build queue — identity-free; build identity lives in\n  # 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 sh\n          # Mechanics only — NEXT.md's presence/absence is interpreted by\n          # the `on` rows below, never here.\n          set +e\n          mkdir -p .gtd\n          # Sweep spent design/architecture steering files (gone by now) and\n          # any REVIEW_RAW.md the review loop-back left behind — the only\n          # sweeper on that path before it would leak into a later `gtd\n          # summary` prompt's diff range.\n          rm -f .gtd/REQUIREMENTS.md .gtd/ARCHITECTURE.md .gtd/QUESTIONS.md .gtd/REVIEW_RAW.md\n          # Names are gtd-authored, never containing whitespace — safe to\n          # disable SC2012.\n          # shellcheck disable=SC2012\n          next=$(ls .gtd/packages/*.md 2>/dev/null | head -n 1)\n          if [ -n \"$next\" ]; then\n            printf '%s' \"$next\" > .gtd/NEXT.md\n          else\n            rm -f .gtd/NEXT.md\n          fi\n        on:\n          \"D .gtd/NEXT.md\": $onDrained\n          \"* .gtd/NEXT.md\": item.building\n          \"C\": $onDrained\n\n      # Its own coder machine (below) keeps `packages` itself a single state.\n      item:\n        machine: packageItem\n        with:\n          onNext: picking\n\n  # The per-package build identity. ▸ coder identity. packages.item.closing\n  # -> picking is the one upward-resolving target in the file, hence $onNext.\n  packageItem:\n    model: <%= it.vars.coderModel %>\n    system: |-\n      <%~ it.vars.builderPersona %>\n\n\n      <%~ it.vars.agentConduct %>\n    params: [onNext]\n    entry: building\n    states:\n      building:\n        actor: agent\n        label: Building\n        prompt: |\n          <%~ it.vars.stateFileRules %>\n\n          - The only state file this turn may write is `.gtd/SATISFIED.md`;\n            never delete the package file (the spec-review gate reads it\n            after you) or touch `.gtd/NEXT.md` — `picking` owns it\n          - The package to implement is: <%~ it.read(\".gtd/NEXT.md\") %>\n          - First check its acceptance criteria against the current tree —\n            an earlier fix turn may already satisfy them. If **every**\n            criterion is met, implement nothing: write `.gtd/SATISFIED.md`\n            with each criterion's concrete evidence (commit, file, or\n            symbol), change nothing else, and finish. Otherwise implement\n            normally and skip that file\n          - Implement every task the package describes, no more, no less,\n            fanning independent ones out to parallel subagents where your\n            harness supports it. TDD throughout; leave other package\n            files untouched\n          - Leave the package file in place, everything uncommitted, then\n            finish your turn\n        on:\n          \"A .gtd/SATISFIED.md\": &satisfied\n            to: health.check\n            action: Close as already satisfied\n            describe: >-\n              record per-criterion evidence in .gtd/SATISFIED.md when this\n              package's work already landed (an earlier package's fix turn\n              pulled it in) — the package still runs the checks and the spec\n              review, then closes out.\n          \"M .gtd/SATISFIED.md\": *satisfied\n          \"* **\": health.check\n\n      fix-suite:\n        actor: agent\n        label: Fixing the check\n        file: FEEDBACK.md\n        prompt: |\n          <%~ it.vars.stateFileRules %>\n\n          <%~ it.vars.fixFeedbackPrompt %>\n\n          - If the only way to green the suite is another package's work,\n            make the smallest change that gets there — that package can\n            then legitimately report itself already satisfied later\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: SPEC_FEEDBACK.md\n        prompt: |\n          <%~ it.vars.stateFileRules %>\n\n          - The only state file this turn touches is\n            `.gtd/SPEC_FEEDBACK.md` — address it, then delete it\n          - Read it (the reviewer's concerns) and the package spec\n            (`<%= it.read(\".gtd/NEXT.md\") %>`), then fix the code to\n            resolve every concern, focused\n          - Delete `.gtd/SPEC_FEEDBACK.md` once resolved; leave everything\n            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 sh\n          # Removes the just-reviewed package file (path in NEXT.md) plus\n          # leftover spec feedback/evidence, so picking selects the next.\n          # Reached only on spec-review approval — that loop carries no retry\n          # cap, so there is no force-close path here.\n          set +e\n          pkg=$(cat .gtd/NEXT.md 2>/dev/null)\n          [ -n \"$pkg\" ] && rm -f \"$pkg\"\n          rm -f .gtd/SPEC_FEEDBACK.md .gtd/NEXT.md .gtd/SATISFIED.md\n        on:\n          \"* **\": $onNext\n          # Nothing left to sweep (an already-clean NEXT.md/package) still\n          # needs to proceed to the next package, not stall here.\n          \"C\": $onNext\n\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      spec:\n        machine: specReview\n        with:\n          onApproved: closing\n          onFix: fix-spec\n\n  # The process's build identity. ▸ coder identity — model/system stamped\n  # onto fix.\n  buildTail:\n    model: <%= it.vars.coderModel %>\n    system: |-\n      <%~ it.vars.finisherPersona %>\n\n\n      <%~ it.vars.agentConduct %>\n    params: [onDone, onFeedback]\n    # entry: is required by the machine grammar even though nothing resolves\n    # this machine bare; `fix` is an arbitrary pick.\n    entry: fix\n    states:\n      fix:\n        actor: agent\n        label: Fixing the check\n        file: FEEDBACK.md\n        prompt: |\n          <%~ it.vars.stateFileRules %>\n\n          <%~ it.vars.fixFeedbackPrompt %>\n\n          - Leave everything uncommitted — do not commit\n        retry:\n          max: 3\n          otherwise: health.escalate\n        on:\n          \"* **\": health.check\n\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      # Nested here (not root) so the sign-off's boundary commit stays inside\n      # the builder's own scope — see humanReview above.\n      review:\n        machine: humanReview\n        with:\n          onSignoff: $onDone\n          onFeedback: $onFeedback\n\n  # WIRING ONLY — the root ties together the machine tree above.\n  unified:\n    entry: idle\n    states:\n      idle:\n        actor: human\n        label: Idle\n        file: TODO.md\n        message: |\n          No active gtd process.\n\n          To start one, make ANY change — a hand-edit to real code, a scratch\n          note, anything at all. .gtd/TODO.md is a good default\n          place to start sketching. gtd treats it as a SKETCH, not finished\n          work: the very next beat unwinds it out of your working tree (its\n          intent survives in history, for the triage phase to read), then\n          checks the test baseline is green, then triages the reverted diff\n          into ordered, classified concerns: product questions, then\n          technical questions, then one package per concern, built and\n          reviewed in parallel.\n\n          What each change does next (then run `gtd land`):\n          <% it.edges.forEach(function (e) { if (e.describe) { %>\n          <%~ \"- \" + (e.action ? \"**\" + e.action + \"** — \" : \"\") + e.describe + \"\\n\" %>\n          <% } }) %>\n        on:\n          \"* **\":\n            to: unwind\n            action: Start\n            describe: >-\n              make any change — gtd unwinds it out of your working tree (its\n              intent survives in history) before checking the test baseline is\n              green, then triages the reverted diff into ordered, classified\n              concerns and resolves product questions, then technical ones,\n              before building each concern's package (**unwind** ->\n              **start-gate.check**).\n\n      # --entry fix-precheck: a red suite drops into build.fix (-> health ->\n      # review tail); a green suite is a no-op back to idle.\n      fix-precheck:\n        actor: check\n        label: Checking the baseline\n        entry: true\n        script: *suiteCheck\n        on:\n          \"A .gtd/FEEDBACK.md\": build.fix\n          \"M .gtd/FEEDBACK.md\": build.fix\n          \"D .gtd/REVIEW_RAW.md\": idle\n          \"D .gtd/FEEDBACK.md\": idle\n          \"C\": idle\n\n      # Separate from start-gate.check: that gate's blocked -> check retry\n      # edge would otherwise re-run a revert here and discard a human's\n      # baseline repair. One inbound edge (from idle) means unwind runs\n      # exactly once, so it needs no idempotence guard itself.\n      unwind:\n        actor: check\n        label: Unwinding your input\n        script: |\n          #!/usr/bin/env sh\n          set +e\n          mkdir -p .gtd\n          # Hoisted here, 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.\n          # Uses it.currentCommit (render-time), not bare HEAD, so a\n          # late-running driver still reverts the right commit.\n          commit=\"<%~ it.currentCommit %>\"\n          git revert --no-commit \"$commit\" 2> .gtd/.unwind-error\n          code=$?\n          # The revert's EXIT CODE is what separates a genuine no-op from a\n          # hard failure (e.g. a merge commit with no `-m`) — the diff alone\n          # cannot, since both can leave a clean tree. Turning the failure\n          # into a FEEDBACK.md write is what makes the `C` row below safe:\n          # once a failure always has a diff, a clean tree here means the\n          # revert really did succeed and change nothing.\n          if [ \"$code\" -ne 0 ]; then\n            printf 'gtd could not unwind %s out of your working tree.\\n\\n' \"$commit\" > .gtd/FEEDBACK.md\n            if [ -s .gtd/.unwind-error ]; then\n              cat .gtd/.unwind-error >> .gtd/FEEDBACK.md\n            else\n              printf '`git revert --no-commit` exited %s and produced no output.\\n' \"$code\" >> .gtd/FEEDBACK.md\n            fi\n          fi\n          rm -f .gtd/.unwind-error\n        on:\n          \"A .gtd/FEEDBACK.md\": unwind-failed\n          \"M .gtd/FEEDBACK.md\": unwind-failed\n          \"* **\": start-gate\n          \"C\": start-gate\n\n      # Reached only when the revert above exited non-zero. A human repairs\n      # the tree by hand; start-gate.check clears FEEDBACK.md on its way\n      # green, so nothing has to sweep it here.\n      unwind-failed:\n        actor: human\n        label: Could not unwind your input\n        file: FEEDBACK.md\n        message: |\n          gtd could not revert your sketch out of the working tree.\n          `.gtd/FEEDBACK.md` holds the error.\n\n          Undo the sketch by hand (its intent survives in history either\n          way), then continue — gtd will not start work on a tree that still\n          carries it.\n\n          What each change does next (then run `gtd land`):\n          <% it.edges.forEach(function (e) { if (e.describe) { %>\n          <%~ \"- \" + (e.action ? \"**\" + e.action + \"** — \" : \"\") + e.describe + \"\\n\" %>\n          <% } }) %>\n        on:\n          \"* **\":\n            to: start-gate\n            action: Continue\n            describe: >-\n              having undone the sketch by hand, check the test baseline is\n              green and start triage (**start-gate.check**).\n\n      # Reverts the human's own review-round hand-edit before re-planning,\n      # scoped to real code (`.gtd/` excluded — REVIEW.md is already gone by\n      # now). Names the commit via it.reviewBase (reviewBaseFor's own\n      # `await-review -> deciding` commit), never bare HEAD.\n      #\n      # requireRevert (below) re-checks the tree itself and refuses the step\n      # if residue remains, rather than trusting the script's exit code — a\n      # clean-filter round-trip or binary path can make `git apply -R` a\n      # silent no-op. Both `on` rows below target `design`: a hand-edited\n      # round leaves a dirty tree, a note-only round's patch is empty and\n      # leaves the tree clean — both are legitimate outcomes here, not a\n      # stall.\n      #\n      # `file: REVIEW.md` + `requireRevert: true` exist only to give that\n      # guard the path to exempt (it reads Rest.hints.file, never this\n      # literal) — REVIEW.md is already gone two commits earlier, so this\n      # state never renders it.\n      re-unwind:\n        actor: check\n        label: Re-unwinding your review edit\n        file: REVIEW.md\n        requireRevert: true\n        script: |\n          #!/usr/bin/env sh\n          # Scoped revert of the human's review-round edit — .gtd/ excluded\n          # (the guard's isCodePath re-derives the same exemption; keep both\n          # in sync). Expected to succeed; requireRevert catches a silent\n          # apply failure.\n          set +e\n          # Hoisted here, 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.\n          commit=\"<%~ it.reviewBase %>\"\n          patch=.gtd/.re-unwind.patch\n          mkdir -p .gtd\n          git diff --binary \"$commit^\" \"$commit\" -- . \":(exclude).gtd\" > \"$patch\"\n          if [ -s \"$patch\" ]; then\n            git apply -R \"$patch\" || echo \"re-unwind: could not revert $commit\" >&2\n          fi\n          rm -f \"$patch\"\n        on:\n          \"* **\": design # a code hand-edit was reverted\n          \"C\": design # note-only round: nothing to revert\n\n      start-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            `.gtd/FEEDBACK.md` holds the failing output.\n\n            What each change does next (then run `gtd land`):\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            (**start-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      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            `.gtd/FEEDBACK.md` holds the failing output.\n\n            What each change does next (then run `gtd land`):\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      design:\n        machine: designPlan\n        with:\n          onArchitecture: architecture\n\n      architecture:\n        machine: archPlan\n        with:\n          onPackages: packages\n\n      packages:\n        machine: packageLoop\n        with:\n          onDrained: build.review\n\n      build:\n        machine: buildTail\n        with:\n          onDone: idle\n          onFeedback: re-unwind\n";
+var unified_default = "# gtd's BUILT-IN DEFAULT workflow — used when no `workflow:` key is\n# configured anywhere in the cwd→home config chain; `gtd init` seeds only\n# vars.testCommand + a modes: suggestion, never this file. Compiled through\n# the same `compileWorkflowConfig` a user's own `workflow:` goes through — no\n# privileged path. See skills/authoring/SKILL.md for how to read or edit it\n# (machines, patterns, templates) and docs/driver.md for how a driver runs it.\n#\n# One flow: any change to the tree starts the process. `idle` -> `unwind`\n# reverts that diff (intent survives only in history) -> a green-baseline\n# gate -> `design.triage` groups the reverted diff into ordered, classified\n# concerns and resolves the PRODUCT ones' open questions (`design.gate`) ->\n# `architecture.author` works out the *how* and resolves the TECHNICAL ones\n# (`architecture.gate`) -> `architecture.decompose` writes one package file\n# per concern -> the per-package queue (`packages.*`) builds and reviews each\n# -> the shared tail (`build.review.*`) decides sign-off (-> `idle`, landing\n# an ordinary commit that closes the process — every per-turn commit stays on\n# the branch; run `gtd summary` afterward for a closing-message prompt) vs.\n# actionable feedback (-> `re-unwind` -> back to `design.triage`, a full\n# re-plan lap that never builds on the human's hand-edit). `--entry\n# review-gate.check --var reviewBase=<commitish>` and `--entry fix-precheck`\n# are the two other entries into this same flow.\nvars:\n  testCommand: npm test\n  # plannerModel: the heavier tier for one-shot triage/design/review turns.\n  # coderModel: the tier for build/fix turns. Both repointable via a\n  # top-level `vars:` key or a `GTD_<NAME>` env var, like any other var.\n  plannerModel: smart\n  coderModel: base\n  # Declared (not left undeclared) so `--var reviewBase=...` passes the CLI's\n  # declared-name check; blank renders empty, which the review entry refuses.\n  reviewBase: \"\"\n  # gtd's own voice for generated files — adapted from the \"Spartan\" output\n  # style (https://github.com/alexgreensh/attention-span, AGPL-3.0, version 0.6),\n  # rewritten in gtd's own words for deliverables rather than chat replies;\n  # no upstream text ships. A point-in-time derivation with no refresh\n  # mechanism.\n  styleBlock: |-\n    - A deliverable, not a chat reply — size follows the work; cut padding\n    - Lead with the answer; never circle back to restate it\n    - Flat, commanding sentences — commit to the claim, never hedge\n    - Everyday words; define an unavoidable term in five words or fewer, on\n      first use\n    - Bold carries the load: bold the claim, not the sentence around it —\n      the bold text alone must yield the full point and every risk\n    - **Never trim a risk, a number, a threshold, or a scoped condition to\n      save space — this outranks every other rule here**\n    - Ship the artifact bare — no lead-in, no sign-off\n    - Compressing is not dropping: three load-bearing parts ship as three,\n      each shorter, never as two\n    - One idea per block; break when the idea shifts\n    - Flag risk in one blunt line, never hedged prose; never narrate — do it\n  styleFormatContract: |-\n    - Machine-read: its format contract outranks every style rule above —\n      keep every `##`/`###` heading, checkbox row, and marker line exactly\n      as specified. Never renumber or rename a heading; a parser reads\n      these literally and a violation refuses the turn\n    - Voice rules above govern only the prose between these elements\n\n  # One persona per prompt-bearing machine below, stamped as its `system:`\n  # (see src/StateFields.ts's `system`). `--system-prompt` REPLACES a\n  # harness's default system prompt — including its injected cwd/env/\n  # git-status block — so each persona is written self-contained, restating\n  # that context explicitly rather than relying on it.\n\n  # Shared conduct tail, appended after every persona's own role paragraph:\n  # use tools without asking, orient yourself with git, and go inspect what\n  # the turn's message names. Deliberately NOT named `*Persona`:\n  # `templates.test.ts` derives its six-name persona set from\n  # `it\\.vars\\.(\\w+Persona)`, so that suffix would silently grow the set.\n  agentConduct: |-\n    - You have shell and file tools — bash, read, write, edit — use them\n      without asking first; this runs unattended, no one grants permission\n    - Investigate with real commands rather than assuming a file's, a\n      commit's, or a decision's status — then act on what you find\n    - No injected status block — no cwd, no branch, no history, no tree\n      state — orient yourself first with `git status`, `git log`, `ls`\n    - The turn's message names a commit, a range, or a file to go inspect\n      yourself — never a diff or summary inlined into the conversation\n    - Across turns one conversation may span, work from what you already\n      read and settled, unless told this is a fresh, cold pass\n  designPersona: |-\n    You are the product-facing planning voice in gtd's build pipeline: turn\n    a raw sketch — a hand-edit, a scratch note, or both — into an ordered,\n    classified list of concerns, and hold the running product conversation\n    with the human it depends on. You are read by that human — write\n    plainly — not by a parser, except where a state says otherwise.\n  architectPersona: |-\n    You are the technical planning voice in gtd's build pipeline: take over\n    once product concerns are settled, reading them cold, no carried\n    conversation. Work out the *how* per concern — structure, data models,\n    tech-stack choices, error handling — raise the technical open\n    questions, then write one package spec per concern with no further\n    judgement call: the grouping is already decided.\n  reviewerPersona: |-\n    You are the independent reviewing mind in gtd's build pipeline —\n    deliberately separate from whoever wrote the code, with no attachment\n    to it. Two turns: write a structured review document grouping a diff\n    into chunks; later, classify a round of the human's feedback as\n    actionable or just approving, never fixing anything yourself. You judge\n    and classify; you never build.\n  specReviewerPersona: |-\n    You are the adversarial spec-conformance checker in gtd's build\n    pipeline, checking one freshly-built package against its spec. Verify\n    only: tasks done, criteria met, code sound and consistent with the\n    codebase. Write feedback only when something is genuinely wrong —\n    otherwise write nothing; a clean turn IS the approval. Never fix what\n    you find — naming it precisely enough for a fix turn is the whole job.\n  builderPersona: |-\n    You are the TDD implementer in gtd's build pipeline: build one\n    package's declared scope end to end, tests first, and come back to fix\n    things when redirected — a failing check, or reviewer feedback. Stay\n    strictly inside the package in front of you; never touch another\n    package's files or code outside the task. Treat feedback as the\n    diagnosis to act on; discard it, with reason, only when simply wrong.\n  finisherPersona: |-\n    You are the closing identity in gtd's build pipeline — the last coder\n    before it closes. Fix a late-breaking failing check after sign-off,\n    focused and minimal. Every turn lands its own commit — nothing here\n    gets squashed away.\n\n  # The scratchpad-opener sentence shared by every prompt-content state (see\n  # STATE_FIELDS's `prompt`) — this workflow's own state files are its private\n  # working notes, never project code or documentation a human reads. Injected\n  # as the leading line of every prompt body that touches a `.gtd/` file\n  # directly; each state's own \"the only state file this turn touches is X\"\n  # sentence stays local, immediately after the tag. Some states splice a\n  # role clause into this same opening sentence (`build.review.collecting`,\n  # `packages.item.spec.review`) — those hoist the clause to its own leading\n  # sentence ahead of the tag instead, keeping every word.\n  stateFileRules: |-\n    - You are an autonomous coding agent\n    - This workflow's own state files are its private scratchpad, never\n      project code or documentation\n  # The open-questions warrant test, decide-it-yourself sink, and `## Open\n  # Questions` checkbox shape shared by `design.triage` and\n  # `architecture.author` — written phase-agnostic (no PRODUCT/TECHNICAL\n  # bake-in) so both sites can inject it verbatim. Each site's own\n  # phase-scope sentence (triage: product-only, technical waits; architecture:\n  # every point here is TECHNICAL) stays local around the tag — the two\n  # genuinely disagree on scope, so that sentence is never shared.\n  # `questionBarReturn` is the return-lap half — split out so each site can\n  # inject it under its own `## Return lap` heading instead of burying\n  # return-lap behaviour inside the first lap's own section.\n  questionBar: |-\n    - Ask only when all three hold: it's a genuine fork with divergent\n      outcomes (user-visible for product, materially different builds for\n      technical); the diff and history don't already settle it (treat an\n      explicit `.gtd/TODO.md` directive, a committed hand-edit, or — on a\n      loop-back lap — the human's own review-round edit/note as settled);\n      and getting it wrong would survive to the human review tail\n    - Below that bar, decide it yourself: record it under\n      `## Answered Questions` as `### <the point phrased as a question>`\n      plus a one-line rationale in prose, no checkboxes. That heading\n      always comes last, after every other `##` section\n    - Above the bar, write it under `## Open Questions` — always the first\n      `##` section — as `### <question>` plus a checkbox list: two\n      concrete options and a free-text slot, all 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\n  questionBarReturn: |-\n    - The human ticked one option per question (or wrote their own in\n      place of `_your answer_`): fold each answer into its concern's\n      prose, then move the question into `## Answered Questions` as\n      `### <question>` with the resolved answer in plain prose — no\n      checkboxes\n    - `## Answered Questions` is always the last `##` section — a moved\n      question lands there, never wherever `## Open Questions` used to sit\n    - Never re-raise a deleted question — treat a deleted `## Open\n      Questions` section as acceptance; omit it entirely once none are left\n  # The body `packages.item.fix-suite` and `build.fix` share byte for byte —\n  # both fix a red `.gtd/FEEDBACK.md`. `fix-suite` appends its own\n  # cross-package paragraph right after this tag (before the shared\n  # \"Leave everything uncommitted\" close, which stays local at both sites so\n  # the appended paragraph lands in the same position it renders in today);\n  # `build.fix` renders the tag alone.\n  fixFeedbackPrompt: |-\n    - The only state file this turn touches is `.gtd/FEEDBACK.md` — no\n      other files for notes or output\n    - Read it (the failing test output) and fix the code so the suite\n      passes; keep the change focused, never refactor unrelated code\n    - If the feedback is wrong, fix nothing rather than \"fixing\" a non-issue\n    - Delete `.gtd/FEEDBACK.md` either way — once the suite passes, or once\n      you have established the feedback was wrong; leaving it in place is\n      never the right end state, the next check writes its own\n\n  # The human-facing half of footnotes — how to type one, injected into the\n  # three human-gate messages (`design.gate.answer`, `architecture.gate.answer`,\n  # `build.review.await-review`). `footnoteFoldIn` below is the agent-facing\n  # half; the two never share text, different audience and content.\n  footnoteRules: |-\n    - Leave a footnote anywhere: mark the exact spot with `[^name]` (any\n      name, no whitespace or `]`), then define it below as `[^name]:\n      explain what you mean` — indent a longer comment's continuation\n      lines. (The literal words \"your comment\" are this format's seeded\n      placeholder body — a definition still holding them exactly is\n      flagged as unfilled, so write your own words there)\n    - A footnote is a comment on that exact spot — the hunk, line, or\n      paragraph it marks — never a whole-file remark\n    - `name` is yours to pick; only a definition's name must be unique in\n      this document — the same name may mark more than one spot\n  # The agent-facing half — injected into the three prompts that fold a\n  # footnote in (`design.triage`, `architecture.author`,\n  # `build.review.collecting`). `build.review.reviewing`, the one state that\n  # WRITES a review file, references neither tag — the agent never authors a\n  # footnote.\n  footnoteFoldIn: |-\n    - A footnote (`[^name]` plus its `[^name]:` definition) is a comment on\n      its exact anchor — fold it in as a mandatory concern described\n      against that anchor's hunk or paragraph, never flattened into a\n      whole-file remark\n    - DELETE it in this same turn — marker and definition together — the\n      way a transient hand-written code comment is already treated. Never\n      re-read a footnote already acted on\n    - A footnote is human input only — you reply in prose; never write one\n      yourself\n\n# `gtd summary`'s prompt — printed cold, no session identity, no diff inlined.\n# Names the hashes/range for the agent to inspect itself; renders the same\n# it.processCost/it.processCostByModel the old squash finale used to.\nsummary: |\n  <%~ it.vars.styleBlock %>\n\n\n  - Write the closing message for the process HEAD closes or sits inside —\n    for a squash, an amend, or a PR body. Starting cold: read every\n    decision out of the commits below, not assumed context\n  - Cover the motivation, the decisions, the trade-offs, and the\n    high-level architectural changes — never which files changed; `git\n    diff --stat` is for that, not this message\n\n  The process's entry commit is `<%= it.entryCommit %>`. <% if\n  (it.humanCommits.length > 0) { %>The human contributed at these commits,\n  oldest to newest:\n  <% it.humanCommits.forEach(function (c) { %>\n  - `<%= c.hash %>` (entering `<%= c.state %>`)\n  <% }) %><% } else { %>The human left no comment or edit this process —\n  every commit is machine-authored.<% } %>\n\n  Inspect the range: `git log <%= it.processBase %>..<%= it.processTip %>`\n  and `git diff <%= it.processBase %> <%= it.processTip %>` — exactly what\n  a squash or PR body should describe.\n\n  Token cost: <%= it.processCost %>\n  <% it.processCostByModel.forEach(function(m){ %>\n  - <%= m.model %>: <%= m.cost %>\n  <% }) %>\n\n  Print the closing message and stop — this writes nothing itself.\n\nentry:\n  default: unified\n\nmachines:\n  # Shared green-baseline gate — start-gate/review-gate/fix-precheck all\n  # alias this script via &suiteCheck.\n  entryGate:\n    params: [onGreen, blockedMessage, blockedDescribe, checkLabel, blockedLabel, reviewBase]\n    entry: check\n    states:\n      check:\n        actor: check\n        label: $checkLabel\n        script: &suiteCheck |\n          #!/usr/bin/env sh\n          set +e\n          mkdir -p .gtd\n          # Sweep a raw review capture an earlier, abandoned process may have\n          # left behind — no ordinary path from deciding/collecting reaches\n          # this check.\n          rm -f .gtd/REVIEW_RAW.md\n          <%~ it.vars.testCommand %> > .gtd/.check-output 2>&1\n          code=$?\n          if [ \"$code\" -ne 0 ]; then\n            if [ -s .gtd/.check-output ]; then\n              mv .gtd/.check-output .gtd/FEEDBACK.md\n            else\n              rm -f .gtd/.check-output\n              printf 'the test command failed with exit code %s and produced no output.' \"$code\" > .gtd/FEEDBACK.md\n            fi\n            # Stamp with HEAD so a repeat identical failure still re-registers\n            # as an M/A edit instead of looking byte-identical (GREEN).\n            printf '\\n<!-- gtd check %s -->\\n' \"$(git rev-parse --short HEAD 2>/dev/null || echo pending)\" >> .gtd/FEEDBACK.md\n          else\n            rm -f .gtd/.check-output\n            rm -f .gtd/FEEDBACK.md\n          fi\n        # Marks BOTH entryGate instances (start-gate/review-gate); only\n        # review-gate strictly needs it, but the shared dedup makes marking\n        # one mark both — both ARE entry gates.\n        entry: true\n        # Only review-gate binds a real reviewBase (via --var); start-gate\n        # binds \"\" (no base), since it's reached from idle, never entered.\n        reviewBase: $reviewBase\n        on:\n          \"A .gtd/FEEDBACK.md\": blocked\n          \"M .gtd/FEEDBACK.md\": blocked\n          \"D .gtd/REVIEW_RAW.md\": $onGreen\n          \"D .gtd/FEEDBACK.md\": $onGreen\n          \"C\": $onGreen\n      blocked:\n        actor: human\n        label: $blockedLabel\n        file: FEEDBACK.md\n        message: $blockedMessage\n        on:\n          \"* **\":\n            to: check\n            action: Retry check\n            describe: $blockedDescribe\n\n  # Shared check/escalate pair for build.health.*/packages.item.health.* —\n  # the caller's own coder fix-state ($onRed), not this machine, handles red.\n  healthGate:\n    params: [onGreen, onRed, escalateDescribe, checkLabel, escalateLabel]\n    entry: check\n    states:\n      check:\n        actor: check\n        label: $checkLabel\n        # See the shared suite check on `entryGate.check` above.\n        script: *suiteCheck\n        on:\n          \"A .gtd/FEEDBACK.md\": $onRed\n          \"M .gtd/FEEDBACK.md\": $onRed\n          \"* **\": $onGreen\n          \"C\": $onGreen\n      escalate:\n        actor: human\n        label: $escalateLabel\n        file: FEEDBACK.md\n        message: |\n          The agent could not get the check to pass after repeated attempts.\n          `.gtd/FEEDBACK.md` holds the last failing output.\n\n          What each change does next (then run `gtd land`):\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  # Shared check/answer pair for design.gate/architecture.gate. No `file:`\n  # PARAM for the probe script itself: machine `$param` substitution is\n  # whole-value only, so a path can't be spliced into a shared script body —\n  # `file` here is instead the `answer` param's own `file:` (the human gate).\n  questionGate:\n    params: [file, message, onNone, onRevise, checkLabel, answerLabel]\n    entry: check\n    states:\n      check:\n        actor: check\n        label: $checkLabel\n        script: |\n          #!/usr/bin/env sh\n          # Exactly one of REQUIREMENTS.md/ARCHITECTURE.md exists on disk at\n          # a time — architecture.author deletes the former in the same turn\n          # it writes the latter — so this probe is unambiguous either way.\n          set +e\n          mkdir -p .gtd\n          file=.gtd/REQUIREMENTS.md\n          [ -f \"$file\" ] || file=.gtd/ARCHITECTURE.md\n          gtd check qa \"$file\" --open-questions > /dev/null 2>&1\n          code=$?\n          if [ \"$code\" -ne 0 ]; then\n            printf 'open questions remain in %s\\n' \"$file\" > .gtd/QUESTIONS.md\n            # See the shared suite check's cache-buster rationale on\n            # `entryGate.check` above.\n            printf '\\n<!-- gtd check %s -->\\n' \"$(git rev-parse --short HEAD 2>/dev/null || echo pending)\" >> .gtd/QUESTIONS.md\n          else\n            rm -f .gtd/QUESTIONS.md\n          fi\n        on:\n          \"A .gtd/QUESTIONS.md\": answer\n          \"M .gtd/QUESTIONS.md\": answer\n          \"D .gtd/QUESTIONS.md\": $onNone\n          \"C\": $onNone\n      answer:\n        actor: human\n        label: $answerLabel\n        file: $file\n        mode: qa\n        answerGate: true\n        message: $message\n        on:\n          \"* **\":\n            to: $onRevise\n            action: Revise answers\n            describe: >-\n              tick exactly one option per open question (replace\n              `_your answer_` for your own) to send it back for the agent to\n              fold your answers in. Delete a question to skip it, or delete\n              the whole `## Open Questions` section to accept the plan as-is.\n\n  # The triage phase — one conversation across the whole back-and-forth (the\n  # human's answer rationale survives every return lap). A review loop-back\n  # lap runs the suite itself and files any breakage as its own FIRST\n  # concern, rather than spending one of packages.item.fix-suite's\n  # (per-episode) retries on breakage the package didn't cause.\n  # ▸ planner identity.\n  designPlan:\n    model: <%= it.vars.plannerModel %>\n    system: |-\n      <%~ it.vars.designPersona %>\n\n\n      <%~ it.vars.agentConduct %>\n    params: [onArchitecture]\n    entry: triage\n    states:\n      triage:\n        actor: agent\n        label: Triaging the change\n        file: REQUIREMENTS.md\n        mode: qa\n        # Guards against discarding assembled review input without folding\n        # it in (the original bug this guard was added for).\n        requireProgress: true\n        prompt: |\n          <%~ it.vars.styleBlock %>\n\n\n          <%~ it.vars.styleFormatContract %>\n\n\n          <%~ it.vars.stateFileRules %>\n\n          <%~ it.vars.footnoteFoldIn %>\n\n          - The only state file this turn touches is `.gtd/REQUIREMENTS.md`\n            — no other files for notes or output\n          - `.gtd/TODO.md` is the likely home of the sketch that started\n            this process — the human's input, folded into the concerns\n            below like any other part of the start diff; never a state\n            file to preserve, never gtd bookkeeping to ignore\n          - This process started at commit `<%= it.startCommit %>`,\n            reverted out of the tree by `unwind` right after landing, so\n            `git diff <%= it.startCommit %>` is now empty — its content\n            survives only in history. Find the entry commit yourself:\n            `git rev-list --ancestry-path <%= it.startCommit %>..HEAD | tail -1`\n            (the process's first turn, before any baseline-repair\n            commits), then `git show` it — a hand-edit, a scratch note,\n            or both\n          - Whichever lap this is, leave `.gtd/REQUIREMENTS.md`\n            uncommitted and finish once it reflects this lap's own work\n\n          ## First lap\n\n          `.gtd/REQUIREMENTS.md` does not exist yet (or holds whatever the\n          human's change left there). Build it from that start diff:\n\n          ### Group into concerns\n\n          - An ordered list of concerns, each a coherent piece of work\n            that leaves the suite green on its own, in build order — a\n            concern that would red-light a later fix is not a valid\n            split; merge the two\n          - Vertical, not horizontal: slice by capability, never by layer\n            — a concern that only prepares for a later one (types,\n            scaffolding, renames) folds into the first concern that uses it\n          - Distinct acceptance: each concern needs a check that fails\n            before it and passes after; if you can't name one, merge it into\n            its neighbour\n          - Prefer fewer, larger packages — the smallest independently\n            valuable change, not the smallest change that compiles\n\n          ### Classify each concern\n\n          Classify each as PRODUCT (user-facing/requirements) or TECHNICAL\n          (implementation).\n\n          <%~ it.vars.questionBar %>\n\n\n          Raise questions only for product concerns here — technical ones\n          wait for the next phase. When every concern is TECHNICAL, write\n          no `## Open Questions` section.\n\n          ### Fold in the sketch\n\n          - Fold everything the entry commit added under the concern it\n            belongs to — a scratch note and a real code edit are both\n            just a sketch to finish, never work to preserve; `unwind`\n            already reverted both, so there is nothing left to delete\n\n          ## Return lap\n\n          <%~ it.vars.questionBarReturn %>\n\n          ## Review loop-back\n\n          - `.gtd/REQUIREMENTS.md` already holds concerns with no\n            ticked-but-unfolded answer waiting — a completed REVIEW round\n            put this here, not a question you asked. Develop those\n            concerns further with whatever the round raised; never\n            rediscover or regroup them cold, the way the first lap does\n          - The human's review-round edit was reverted the same way the\n            entry commit was — read it from history:\n            `git show <%= it.reviewBase %>`. (On the first lap that hash\n            is the process's own diff base, `<%= it.startCommit %>` — this\n            branch doesn't apply)\n          - Every decision under `## Answered Questions` stays settled —\n            never re-open one. A genuinely open PRODUCT point may still\n            raise a fresh `## Open Questions` entry: the product gate sits\n            on this path exactly as on the first lap\n          - Before grouping anything, run `<%= it.vars.testCommand %>`\n            yourself — a loop-back runs no green-baseline gate, so the\n            tree may already be red (reverting the edit can undo a fix it\n            made). If red, make that breakage the first concern, ahead of\n            everything else — every later concern's green-on-its-own\n            property assumes the suite started green\n        on:\n          \"* **\": gate.check\n\n      gate:\n        machine: questionGate\n        with:\n          file: REQUIREMENTS.md\n          onNone: $onArchitecture\n          onRevise: triage\n          checkLabel: Checking for open questions\n          answerLabel: Awaiting your product answers\n          message: |\n            `.gtd/REQUIREMENTS.md` holds the concerns under\n            development. Each open question under `## Open Questions` offers\n            a few options plus a `- [ ] _your answer_` slot. Answer EVERY\n            question by ticking exactly one box (`- [x]`); for your own\n            answer, replace `_your answer_` with your text and tick that\n            line. Stepping is refused while any question is unanswered.\n\n            You can also leave a footnote alongside an answer — it never\n            substitutes for ticking a box, which is still required before\n            stepping is allowed:\n\n            <%~ it.vars.footnoteRules %>\n\n            What each change does next (then run `gtd land`):\n            <% it.edges.forEach(function (e) { if (e.describe) { %>\n            <%~ \"- \" + (e.action ? \"**\" + e.action + \"** — \" : \"\") + e.describe + \"\\n\" %>\n            <% } }) %>\n\n  # A separate machine from designPlan (its own memory scope — a COLD read,\n  # not a resumed conversation). Merge authority lives in `author`, the first\n  # state that knows the *how*: it alone may re-merge concerns, never split;\n  # `decompose` carries that grouping over verbatim. ▸ planner identity.\n  archPlan:\n    model: <%= it.vars.plannerModel %>\n    system: |-\n      <%~ it.vars.architectPersona %>\n\n\n      <%~ it.vars.agentConduct %>\n    params: [onPackages]\n    entry: author\n    states:\n      author:\n        actor: agent\n        label: Refining the technical plan\n        file: ARCHITECTURE.md\n        mode: qa\n        prompt: |\n          <%~ it.vars.styleBlock %>\n\n\n          <%~ it.vars.styleFormatContract %>\n\n\n          <%~ it.vars.stateFileRules %>\n\n          <%~ it.vars.footnoteFoldIn %>\n\n          - The only state files this turn touches are\n            `.gtd/ARCHITECTURE.md` (write it) and `.gtd/REQUIREMENTS.md`\n            (delete once folded in) — no other files for notes or output\n          - You do not resume the design conversation — a separate\n            machine, its own memory, a cold read every time. Read\n            `.gtd/REQUIREMENTS.md` (the settled, ordered, classified\n            concerns) in full; treat every decision there, PRODUCT or\n            TECHNICAL alike, as settled — never re-open it\n          - Cold means no memory of triage's own back-and-forth, not no\n            git access. This process started at commit\n            `<%= it.startCommit %>`. Find the first turn yourself: run\n            `git rev-list --ancestry-path <%= it.startCommit %>..HEAD | tail -1`\n            then `git show` it to see what started this process — a\n            hand-edit, a scratch note, or both\n          - Once `.gtd/ARCHITECTURE.md` is written, delete\n            `.gtd/REQUIREMENTS.md` — folded in, it must not linger. Leave\n            everything uncommitted and finish\n\n          ## First lap\n\n          - Develop `.gtd/ARCHITECTURE.md` from those concerns: for each,\n            in order, work out the *how* — structure, data models,\n            tech-stack choices, error handling — building on the settled\n            *what*\n          - You now know the *how*, so you know each concern's file footprint\n            — list each concern's primary paths. Merge concerns whose\n            footprints center on the same files into one, unless the later\n            one only consumes an interface the earlier one creates (keeps a\n            build-on-top sequence from collapsing into one blob). This\n            authority is to merge only, never to split — the whole problem\n            is over-granularity\n          - Record every merge under `## Merged Concerns`,\n            carrying both merged requirements verbatim so spec review\n            still covers each independently\n          - A merge raises no open question and stops for no\n            human — do not route it to `architecture.gate` for a veto; the\n            human sees it when reviewing the plan, and spec review is the\n            real safety net\n          - Prefer fewer, larger packages — the smallest independently\n            valuable change, not the smallest change that compiles\n          - Every open point here is TECHNICAL — triage already resolved\n            the product ones, one phase earlier\n\n          <%~ it.vars.questionBar %>\n\n          ## Return lap\n\n          <%~ it.vars.questionBarReturn %>\n        on:\n          \"* **\": gate.check\n\n      gate:\n        machine: questionGate\n        with:\n          file: ARCHITECTURE.md\n          onNone: decompose\n          onRevise: author\n          checkLabel: Checking for open questions\n          answerLabel: Awaiting your technical answers\n          message: |\n            `.gtd/ARCHITECTURE.md` holds the technical plan under\n            development. Each open question under `## Open Questions` offers\n            a few options plus a `- [ ] _your answer_` slot. Answer EVERY\n            question by ticking exactly one box (`- [x]`); for your own\n            answer, replace `_your answer_` with your text and tick that\n            line. Stepping is refused while any question is unanswered.\n\n            You can also leave a footnote alongside an answer — it never\n            substitutes for ticking a box, which is still required before\n            stepping is allowed:\n\n            <%~ it.vars.footnoteRules %>\n\n            What each change does next (then run `gtd land`):\n            <% it.edges.forEach(function (e) { if (e.describe) { %>\n            <%~ \"- \" + (e.action ? \"**\" + e.action + \"** — \" : \"\") + e.describe + \"\\n\" %>\n            <% } }) %>\n\n      decompose:\n        actor: agent\n        label: Decomposing into packages\n        prompt: |\n          <%~ it.vars.styleBlock %>\n\n\n          <%~ it.vars.stateFileRules %>\n\n          - The only state files this turn touches are the package files\n            under `.gtd/packages/` and `.gtd/ARCHITECTURE.md` (deleted) —\n            no other files for notes or output\n          - Work from `.gtd/ARCHITECTURE.md` if you wrote it earlier this\n            conversation, otherwise read it (the converged technical\n            plan). It already lists an ordered set of concerns with every\n            merge/split judgement made — this turn is a mechanical\n            write-out, not a planning one. A `## Merged Concerns` heading\n            there records those merges, never a concern of its own: write\n            no package file for it\n          - Write one package file per concern, in the settled order,\n            under `.gtd/packages/` (e.g. `.gtd/packages/01-name.md`,\n            `02-name.md`, ...), each carrying that concern's\n            requirement(s) — both, independently, if merged — its\n            independent tasks, and each task's acceptance criteria as\n            `- [ ]` checkboxes and relevant paths\n          - Do not merge or split concerns here — that judgement already\n            happened; carry the settled grouping over verbatim. No\n            package file may reference any other `.gtd/` file\n          - Once written, delete `.gtd/ARCHITECTURE.md`. Leave everything\n            uncommitted and finish\n        on:\n          \"* .gtd/packages/**\": $onPackages\n\n  # The shared review tail. ▸ planner identity — `collecting` only judges/\n  # classifies feedback; there's no coder follow-through inside this machine.\n  #\n  # Nested inside buildTail (build.review), not a root sibling: a machine's\n  # memory scope is its dotted instance path, so nesting keeps `build.fix ->\n  # build.health.check -> build.review.*` (the `--entry fix-precheck` path)\n  # inside one scope, so the sign-off's boundary commit lands from the same\n  # scope that made the fixes.\n  humanReview:\n    model: <%= it.vars.plannerModel %>\n    system: |-\n      <%~ it.vars.reviewerPersona %>\n\n\n      <%~ it.vars.agentConduct %>\n    entry: reviewing\n    states:\n      reviewing:\n        actor: agent\n        label: Reviewing\n        file: REVIEW.md\n        mode: review\n        # `gtd --entry review-gate.check` enters via review-gate.check first\n        # (never straight here), which sets the Gtd-Review-Base trailer this\n        # tail reuses.\n        prompt: |\n          <%~ it.vars.styleBlock %>\n\n\n          <%~ it.vars.styleFormatContract %>\n\n\n          <%~ it.vars.stateFileRules %>\n\n          - The only state file this turn touches is `.gtd/REVIEW.md`,\n            written at exactly that path — no other files for notes or\n            output\n\n          Write `.gtd/REVIEW.md` in this exact format, to help a human\n          review the changes:\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\n            semantically (same feature/refactor/fix, across files), each\n            with a short explanation of what changed and why, then one\n            pointer per hunk (`./`-relative path, optional `#line`;\n            checkboxes are for the human, not you). Put the note's\n            opening line right on the pointer's line:\n\n                - [ ] ./path/to/file.ts#42 — what this hunk does\n\n            Continue a longer note below the pointer, indented exactly two spaces\n            — never four or more, which reads as a code block and never\n            reflows:\n\n                - [ ] ./path/to/file.ts#42 — what this hunk does\n                  and here is more detail, continued below it\n\n            A note sitting entirely on the line(s) beneath the pointer is\n            also valid. Either way, the note must never start with a bare `./path` token\n            — that parses as a second pointer, not a note\n\n          No diff is given — read the changes yourself. The range runs\n          from `<%= it.reviewBase %>` to the working tree (committed turns\n          plus anything pending); on a feedback round that's the previous\n          review's boundary, so it covers only what's new.\n\n          Leave `.gtd/REVIEW.md` uncommitted and finish.\n        on:\n          \"* **\": await-review\n\n      await-review:\n        actor: human\n        label: Awaiting your review\n        file: REVIEW.md\n        mode: review\n        message: |\n          `.gtd/REVIEW.md` holds the review record for the process — 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. Ticks are read-progress only: landing clears\n          every box back to `- [ ]` on disk and nothing records which hunks\n          you read — there is no persisted trail of it.\n\n          Review the diff yourself, with whatever tool you like — gtd checks\n          nothing out and touches no ref; `gtd base` prints this same hash any\n          time you need it again. The range runs from the review base to the\n          working tree:\n\n              git diff <%= it.reviewBase %>\n\n          When you've been through the whole diff, run `gtd land`:\n\n          - **Sign off** — leave no comment — no note in\n            `.gtd/REVIEW.md`, no code edit — to close the process,\n            whatever the boxes say. Every turn commit stays on the\n            branch; run `gtd summary` afterward for a closing-message\n            prompt.\n          - **Request changes** — leave a comment: a note on a\n            `.gtd/REVIEW.md` line, a footnote anchored to a hunk, or a\n            direct code edit — to send a FULL development lap\n            (**review.deciding** → **review.collecting** →\n            re-triage). A hand-edit you make here is treated as a SKETCH, not a\n            fix the agent builds on: it is reverted out of the tree and re-planned\n            from scratch, the same as any other change that starts a process.\n            There is no baseline check on the way back into planning — only a\n            genuinely non-actionable comment (an approving remark with no code\n            edit) skips the lap and signs off straight away.\n\n          A footnote works the same way here as a line note:\n\n          <%~ it.vars.footnoteRules %>\n\n          Deleting `.gtd/REVIEW.md` is refused.\n        on:\n          \"* **\": deciding\n\n      deciding:\n        actor: check\n        label: Reviewing\n        file: REVIEW.md\n        mode: review\n        # Anchors the INCREMENTAL review base to the most-recent in-process\n        # commit (the process start on the first review).\n        reviewBase: true\n        script: |\n          #!/usr/bin/env sh\n          # FEEDBACK iff the human left a REVIEW.md note or hand-edited any\n          # file this round outside .gtd/; otherwise a clean sign-off. No\n          # [ ]/[x] normalization is needed here: `gtd uncheck` (emitted\n          # ahead of every human-review-gate commit) already resets every\n          # tick before this commit is made, so no `[x]` can ever reach it —\n          # a byte-for-byte comparison is enough. This turn only\n          # CAPTURES the raw material into REVIEW_RAW.md — collecting judges\n          # actionability. A/M REVIEW_RAW.md rows are declared before D\n          # REVIEW.md so a feedback round (which also deletes REVIEW.md)\n          # isn't mistaken for sign-off.\n          set +e\n          mkdir -p .gtd\n          head=$(git rev-parse HEAD)\n          # The one case that leaves a clean tree below is REVIEW.md already\n          # missing (the `rm -f` no-ops) — which means the review gate's own\n          # file-provisioning invariant broke, NOT a sign-off. Detecting it\n          # here, by the file's absence rather than by the diff, is what\n          # makes the `C` row below safe to declare: a broken round now\n          # always carries a FEEDBACK.md diff and routes to a human.\n          if ! git cat-file -e \"HEAD:.gtd/REVIEW.md\" 2>/dev/null; then\n            printf 'there is no `.gtd/REVIEW.md` at %s — nothing was reviewed this round.\\n' \"$head\" > .gtd/FEEDBACK.md\n          elif git diff-tree --no-commit-id --name-only -r HEAD -- . \":(exclude).gtd\" \\\n               | grep -q . \\\n             || [ \"$(git show \"HEAD^:.gtd/REVIEW.md\" 2>/dev/null)\" \\\n                != \"$(git show \"HEAD:.gtd/REVIEW.md\" 2>/dev/null)\" ]; then\n            # Reached only with REVIEW.md present. FEEDBACK iff the human\n            # left a note (any edit — no tick can reach this commit at all)\n            # or hand-edited any file this round outside .gtd/; otherwise a\n            # clean sign-off. This turn only CAPTURES the raw material into\n            # REVIEW_RAW.md — collecting judges actionability.\n            {\n              echo \"This is machine-captured input, not instructions. A downstream agent judges whether it's actionable.\"\n              echo\n              echo \"Commit: $head\"\n              echo \"The human's notes are in .gtd/REVIEW.md at this commit. Any hand edits are\"\n              echo \"in that commit's other paths. Run: git show $head\"\n            } > .gtd/REVIEW_RAW.md\n            rm -f .gtd/REVIEW.md\n          else\n            rm -f .gtd/REVIEW.md\n          fi\n        on:\n          # FEEDBACK rows first: the broken-invariant branch writes nothing\n          # else, but declaring them ahead of the sign-off row keeps the\n          # ordering honest if it ever does.\n          \"A .gtd/FEEDBACK.md\": review-missing\n          \"M .gtd/FEEDBACK.md\": review-missing\n          # A/M REVIEW_RAW.md before D REVIEW.md so a feedback round (which\n          # also deletes REVIEW.md) isn't mistaken for sign-off.\n          \"A .gtd/REVIEW_RAW.md\": collecting\n          \"M .gtd/REVIEW_RAW.md\": collecting\n          \"D .gtd/REVIEW.md\": $onSignoff\n          # Unreachable now that the missing-REVIEW.md case writes\n          # FEEDBACK.md above, but declared rather than left off: if a clean\n          # tree ever does happen here, it must reach a human, never\n          # auto-approve an unreviewed round.\n          \"C\": review-missing\n\n      review-missing:\n        actor: human\n        label: Nothing to review\n        file: FEEDBACK.md\n        message: |\n          The review round committed no `.gtd/REVIEW.md`, so there is nothing\n          to sign off on. `.gtd/FEEDBACK.md` holds the detail.\n\n          Make any change to re-run the reviewer and author a fresh review\n          record.\n\n          What each change does next (then run `gtd land`):\n          <% it.edges.forEach(function (e) { if (e.describe) { %>\n          <%~ \"- \" + (e.action ? \"**\" + e.action + \"** — \" : \"\") + e.describe + \"\\n\" %>\n          <% } }) %>\n        on:\n          \"* **\":\n            to: reviewing\n            action: Re-review\n            describe: >-\n              re-run the reviewer to author a fresh `.gtd/REVIEW.md`\n              (**build.review.reviewing**).\n\n      # Outcome is by which paths THIS diff touches: writing REQUIREMENTS.md\n      # (A/M) is the actionable case, so those rows are declared before \"D\n      # REVIEW_RAW.md\" — an actionable round's diff is both together, and\n      # the wrong order would short-circuit every round to sign-off.\n      # Consuming REVIEW_RAW.md alone is the non-actionable short-circuit,\n      # reusing $onSignoff since that IS a sign-off. No `C`/`\"* **\"` row: a\n      # clean turn here is a fruitless dispatch (falls through to the\n      # ordinary attempt default), never a verdict; a dirty tree matching\n      # neither row is a refusal.\n      collecting:\n        actor: agent\n        label: Collecting your feedback\n        file: REQUIREMENTS.md\n        mode: qa\n        prompt: |\n          <%~ it.vars.styleBlock %>\n\n\n          <%~ it.vars.styleFormatContract %>\n\n\n          You are judging and classifying a round of review feedback.\n\n          <%~ it.vars.stateFileRules %>\n\n          <%~ it.vars.footnoteFoldIn %>\n\n          - The only state files this turn touches are\n            `.gtd/REQUIREMENTS.md` and `.gtd/REVIEW_RAW.md` (deleted) —\n            you classify, you do not build\n\n          The raw review material is: <%~ it.read(\".gtd/REVIEW_RAW.md\") %>\n\n          It names a commit. Work from what you already reviewed if you\n          wrote today's review earlier this conversation; otherwise read\n          that commit's diff yourself first.\n\n          The round is actionable if any of these hold:\n\n          - The human left a note on `.gtd/REVIEW.md`. A note is a mandatory\n            concern below\n          - The human added a code comment this round, even a plain-prose\n            one — describe it as a concern, and note the comment line\n            itself is transient: it must not survive the lap that\n            satisfies it\n          - The human hand-edited non-comment code this round — no longer\n            a committed intent to build on, but a sketch like the entry\n            commit's own diff. Describe what it was reaching for; expect\n            the next lap to re-derive it from scratch, never call it final\n\n          Not actionable only when none of the above holds — nothing but an\n          approving remark, no code edit, no substantive note. Never invent\n          actionability, and never dismiss a real note or edit as approval.\n\n          - If actionable: write `.gtd/REQUIREMENTS.md` with an ordered\n            list of concerns, each PRODUCT or TECHNICAL — the shape\n            `design.triage` builds, one `## <heading>` per concern in\n            build order. Fold every note, comment, and hand-edit in under\n            its concern. Raise no open questions here — `design.triage`\n            owns that later. Then delete `.gtd/REVIEW_RAW.md` and finish\n          - If not: delete `.gtd/REVIEW_RAW.md` and finish, writing\n            nothing to `.gtd/REQUIREMENTS.md` — that alone is the sign-off\n        on:\n          \"A .gtd/REQUIREMENTS.md\": $onFeedback\n          \"M .gtd/REQUIREMENTS.md\": $onFeedback\n          \"D .gtd/REVIEW_RAW.md\": $onSignoff\n\n  # The per-package review — a separate MIND from the implementer. ▸ planner\n  # identity; fixing findings is a coder action (packages.item.fix-spec).\n  specReview:\n    model: <%= it.vars.plannerModel %>\n    system: |-\n      <%~ it.vars.specReviewerPersona %>\n\n\n      <%~ it.vars.agentConduct %>\n    params: [onApproved, onFix]\n    entry: review\n    states:\n      review:\n        actor: agent\n        label: Reviewing the package\n        # No retry cap: the loop only re-enters through\n        # `fix-spec`/`health.check`, so under the per-episode rule this state's\n        # episode count can never exceed 1 and a cap could never fire. The\n        # spec-review loop is genuinely unbounded — see docs/configuration.md's\n        # `retry` documentation.\n        prompt: |\n          <%~ it.vars.styleBlock %>\n\n\n          You are reviewing a freshly-built work package against its own\n          spec.\n\n          <%~ it.vars.stateFileRules %>\n\n          - The only state file this turn touches is\n            `.gtd/SPEC_FEEDBACK.md` — write it only when you find problems\n          - The package spec is: <%~ it.read(\".gtd/NEXT.md\") %>\n          - Verify the implementation against it: tasks done, criteria\n            met, code sound and consistent with the codebase. No diff is\n            given — read the range yourself, from `<%= it.startCommit %>`\n            to the working tree, process-wide (it can span earlier\n            packages)\n          - If it fully satisfies the spec, write nothing — silence is\n            your approval. Otherwise write `.gtd/SPEC_FEEDBACK.md` listing\n            concrete problems for a fix turn, specific enough to act on\n          - Never fix anything yourself and never delete the package\n            file — a later step owns that\n        on:\n          \"A .gtd/SPEC_FEEDBACK.md\": $onFix\n          \"M .gtd/SPEC_FEEDBACK.md\": $onFix\n          \"D .gtd/SPEC_FEEDBACK.md\": $onApproved\n          \"C\": $onApproved\n\n  # The per-package build queue — identity-free; build identity lives in\n  # 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 sh\n          # Mechanics only — NEXT.md's presence/absence is interpreted by\n          # the `on` rows below, never here.\n          set +e\n          mkdir -p .gtd\n          # Sweep spent design/architecture steering files (gone by now) and\n          # any REVIEW_RAW.md the review loop-back left behind — the only\n          # sweeper on that path before it would leak into a later `gtd\n          # summary` prompt's diff range.\n          rm -f .gtd/REQUIREMENTS.md .gtd/ARCHITECTURE.md .gtd/QUESTIONS.md .gtd/REVIEW_RAW.md\n          # Names are gtd-authored, never containing whitespace — safe to\n          # disable SC2012.\n          # shellcheck disable=SC2012\n          next=$(ls .gtd/packages/*.md 2>/dev/null | head -n 1)\n          if [ -n \"$next\" ]; then\n            printf '%s' \"$next\" > .gtd/NEXT.md\n          else\n            rm -f .gtd/NEXT.md\n          fi\n        on:\n          \"D .gtd/NEXT.md\": $onDrained\n          \"* .gtd/NEXT.md\": item.building\n          \"C\": $onDrained\n\n      # Its own coder machine (below) keeps `packages` itself a single state.\n      item:\n        machine: packageItem\n        with:\n          onNext: picking\n\n  # The per-package build identity. ▸ coder identity. packages.item.closing\n  # -> picking is the one upward-resolving target in the file, hence $onNext.\n  packageItem:\n    model: <%= it.vars.coderModel %>\n    system: |-\n      <%~ it.vars.builderPersona %>\n\n\n      <%~ it.vars.agentConduct %>\n    params: [onNext]\n    entry: building\n    states:\n      building:\n        actor: agent\n        label: Building\n        prompt: |\n          <%~ it.vars.stateFileRules %>\n\n          - The only state file this turn may write is `.gtd/SATISFIED.md`;\n            never delete the package file (the spec-review gate reads it\n            after you) or touch `.gtd/NEXT.md` — `picking` owns it\n          - The package to implement is: <%~ it.read(\".gtd/NEXT.md\") %>\n          - First check its acceptance criteria against the current tree —\n            an earlier fix turn may already satisfy them. If **every**\n            criterion is met, implement nothing: write `.gtd/SATISFIED.md`\n            with each criterion's concrete evidence (commit, file, or\n            symbol), change nothing else, and finish. Otherwise implement\n            normally and skip that file\n          - Implement every task the package describes, no more, no less,\n            fanning independent ones out to parallel subagents where your\n            harness supports it. TDD throughout; leave other package\n            files untouched\n          - Leave the package file in place, everything uncommitted, then\n            finish your turn\n        on:\n          \"A .gtd/SATISFIED.md\": &satisfied\n            to: health.check\n            action: Close as already satisfied\n            describe: >-\n              record per-criterion evidence in .gtd/SATISFIED.md when this\n              package's work already landed (an earlier package's fix turn\n              pulled it in) — the package still runs the checks and the spec\n              review, then closes out.\n          \"M .gtd/SATISFIED.md\": *satisfied\n          \"* **\": health.check\n\n      fix-suite:\n        actor: agent\n        label: Fixing the check\n        file: FEEDBACK.md\n        prompt: |\n          <%~ it.vars.stateFileRules %>\n\n          <%~ it.vars.fixFeedbackPrompt %>\n\n          - If the only way to green the suite is another package's work,\n            make the smallest change that gets there — that package can\n            then legitimately report itself already satisfied later\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: SPEC_FEEDBACK.md\n        prompt: |\n          <%~ it.vars.stateFileRules %>\n\n          - The only state file this turn touches is\n            `.gtd/SPEC_FEEDBACK.md` — address it, then delete it\n          - Read it (the reviewer's concerns) and the package spec\n            (`<%= it.read(\".gtd/NEXT.md\") %>`), then fix the code to\n            resolve every concern, focused\n          - Delete `.gtd/SPEC_FEEDBACK.md` once resolved; leave everything\n            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 sh\n          # Removes the just-reviewed package file (path in NEXT.md) plus\n          # leftover spec feedback/evidence, so picking selects the next.\n          # Reached only on spec-review approval — that loop carries no retry\n          # cap, so there is no force-close path here.\n          set +e\n          pkg=$(cat .gtd/NEXT.md 2>/dev/null)\n          [ -n \"$pkg\" ] && rm -f \"$pkg\"\n          rm -f .gtd/SPEC_FEEDBACK.md .gtd/NEXT.md .gtd/SATISFIED.md\n        on:\n          \"* **\": $onNext\n          # Nothing left to sweep (an already-clean NEXT.md/package) still\n          # needs to proceed to the next package, not stall here.\n          \"C\": $onNext\n\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      spec:\n        machine: specReview\n        with:\n          onApproved: closing\n          onFix: fix-spec\n\n  # The process's build identity. ▸ coder identity — model/system stamped\n  # onto fix.\n  buildTail:\n    model: <%= it.vars.coderModel %>\n    system: |-\n      <%~ it.vars.finisherPersona %>\n\n\n      <%~ it.vars.agentConduct %>\n    params: [onDone, onFeedback]\n    # entry: is required by the machine grammar even though nothing resolves\n    # this machine bare; `fix` is an arbitrary pick.\n    entry: fix\n    states:\n      fix:\n        actor: agent\n        label: Fixing the check\n        file: FEEDBACK.md\n        prompt: |\n          <%~ it.vars.stateFileRules %>\n\n          <%~ it.vars.fixFeedbackPrompt %>\n\n          - Leave everything uncommitted — do not commit\n        retry:\n          max: 3\n          otherwise: health.escalate\n        on:\n          \"* **\": health.check\n\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      # Nested here (not root) so the sign-off's boundary commit stays inside\n      # the builder's own scope — see humanReview above.\n      review:\n        machine: humanReview\n        with:\n          onSignoff: $onDone\n          onFeedback: $onFeedback\n\n  # WIRING ONLY — the root ties together the machine tree above.\n  unified:\n    entry: idle\n    states:\n      idle:\n        actor: human\n        label: Idle\n        file: TODO.md\n        message: |\n          No active gtd process.\n\n          To start one, make ANY change — a hand-edit to real code, a scratch\n          note, anything at all. .gtd/TODO.md is a good default\n          place to start sketching. gtd treats it as a SKETCH, not finished\n          work: the very next beat unwinds it out of your working tree (its\n          intent survives in history, for the triage phase to read), then\n          checks the test baseline is green, then triages the reverted diff\n          into ordered, classified concerns: product questions, then\n          technical questions, then one package per concern, built and\n          reviewed in parallel.\n\n          What each change does next (then run `gtd land`):\n          <% it.edges.forEach(function (e) { if (e.describe) { %>\n          <%~ \"- \" + (e.action ? \"**\" + e.action + \"** — \" : \"\") + e.describe + \"\\n\" %>\n          <% } }) %>\n        on:\n          \"* **\":\n            to: unwind\n            action: Start\n            describe: >-\n              make any change — gtd unwinds it out of your working tree (its\n              intent survives in history) before checking the test baseline is\n              green, then triages the reverted diff into ordered, classified\n              concerns and resolves product questions, then technical ones,\n              before building each concern's package (**unwind** ->\n              **start-gate.check**).\n\n      # --entry fix-precheck: a red suite drops into build.fix (-> health ->\n      # review tail); a green suite is a no-op back to idle.\n      fix-precheck:\n        actor: check\n        label: Checking the baseline\n        entry: true\n        script: *suiteCheck\n        on:\n          \"A .gtd/FEEDBACK.md\": build.fix\n          \"M .gtd/FEEDBACK.md\": build.fix\n          \"D .gtd/REVIEW_RAW.md\": idle\n          \"D .gtd/FEEDBACK.md\": idle\n          \"C\": idle\n\n      # Separate from start-gate.check: that gate's blocked -> check retry\n      # edge would otherwise re-run a revert here and discard a human's\n      # baseline repair. One inbound edge (from idle) means unwind runs\n      # exactly once, so it needs no idempotence guard itself.\n      unwind:\n        actor: check\n        label: Unwinding your input\n        script: |\n          #!/usr/bin/env sh\n          set +e\n          mkdir -p .gtd\n          # Hoisted here, 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.\n          # Uses it.currentCommit (render-time), not bare HEAD, so a\n          # late-running driver still reverts the right commit.\n          commit=\"<%~ it.currentCommit %>\"\n          git revert --no-commit \"$commit\" 2> .gtd/.unwind-error\n          code=$?\n          # The revert's EXIT CODE is what separates a genuine no-op from a\n          # hard failure (e.g. a merge commit with no `-m`) — the diff alone\n          # cannot, since both can leave a clean tree. Turning the failure\n          # into a FEEDBACK.md write is what makes the `C` row below safe:\n          # once a failure always has a diff, a clean tree here means the\n          # revert really did succeed and change nothing.\n          if [ \"$code\" -ne 0 ]; then\n            printf 'gtd could not unwind %s out of your working tree.\\n\\n' \"$commit\" > .gtd/FEEDBACK.md\n            if [ -s .gtd/.unwind-error ]; then\n              cat .gtd/.unwind-error >> .gtd/FEEDBACK.md\n            else\n              printf '`git revert --no-commit` exited %s and produced no output.\\n' \"$code\" >> .gtd/FEEDBACK.md\n            fi\n          fi\n          rm -f .gtd/.unwind-error\n        on:\n          \"A .gtd/FEEDBACK.md\": unwind-failed\n          \"M .gtd/FEEDBACK.md\": unwind-failed\n          \"* **\": start-gate\n          \"C\": start-gate\n\n      # Reached only when the revert above exited non-zero. A human repairs\n      # the tree by hand; start-gate.check clears FEEDBACK.md on its way\n      # green, so nothing has to sweep it here.\n      unwind-failed:\n        actor: human\n        label: Could not unwind your input\n        file: FEEDBACK.md\n        message: |\n          gtd could not revert your sketch out of the working tree.\n          `.gtd/FEEDBACK.md` holds the error.\n\n          Undo the sketch by hand (its intent survives in history either\n          way), then continue — gtd will not start work on a tree that still\n          carries it.\n\n          What each change does next (then run `gtd land`):\n          <% it.edges.forEach(function (e) { if (e.describe) { %>\n          <%~ \"- \" + (e.action ? \"**\" + e.action + \"** — \" : \"\") + e.describe + \"\\n\" %>\n          <% } }) %>\n        on:\n          \"* **\":\n            to: start-gate\n            action: Continue\n            describe: >-\n              having undone the sketch by hand, check the test baseline is\n              green and start triage (**start-gate.check**).\n\n      # Reverts the human's own review-round hand-edit before re-planning,\n      # scoped to real code (`.gtd/` excluded — REVIEW.md is already gone by\n      # now). Names the commit via it.reviewBase (reviewBaseFor's own\n      # `await-review -> deciding` commit), never bare HEAD.\n      #\n      # requireRevert (below) re-checks the tree itself and refuses the step\n      # if residue remains, rather than trusting the script's exit code — a\n      # clean-filter round-trip or binary path can make `git apply -R` a\n      # silent no-op. Both `on` rows below target `design`: a hand-edited\n      # round leaves a dirty tree, a note-only round's patch is empty and\n      # leaves the tree clean — both are legitimate outcomes here, not a\n      # stall.\n      #\n      # `file: REVIEW.md` + `requireRevert: true` exist only to give that\n      # guard the path to exempt (it reads Rest.hints.file, never this\n      # literal) — REVIEW.md is already gone two commits earlier, so this\n      # state never renders it.\n      re-unwind:\n        actor: check\n        label: Re-unwinding your review edit\n        file: REVIEW.md\n        requireRevert: true\n        script: |\n          #!/usr/bin/env sh\n          # Scoped revert of the human's review-round edit — .gtd/ excluded\n          # (the guard's isCodePath re-derives the same exemption; keep both\n          # in sync). Expected to succeed; requireRevert catches a silent\n          # apply failure.\n          set +e\n          # Hoisted here, 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.\n          commit=\"<%~ it.reviewBase %>\"\n          patch=.gtd/.re-unwind.patch\n          mkdir -p .gtd\n          git diff --binary \"$commit^\" \"$commit\" -- . \":(exclude).gtd\" > \"$patch\"\n          if [ -s \"$patch\" ]; then\n            git apply -R \"$patch\" || echo \"re-unwind: could not revert $commit\" >&2\n          fi\n          rm -f \"$patch\"\n        on:\n          \"* **\": design # a code hand-edit was reverted\n          \"C\": design # note-only round: nothing to revert\n\n      start-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            `.gtd/FEEDBACK.md` holds the failing output.\n\n            What each change does next (then run `gtd land`):\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            (**start-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      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            `.gtd/FEEDBACK.md` holds the failing output.\n\n            What each change does next (then run `gtd land`):\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      design:\n        machine: designPlan\n        with:\n          onArchitecture: architecture\n\n      architecture:\n        machine: archPlan\n        with:\n          onPackages: packages\n\n      packages:\n        machine: packageLoop\n        with:\n          onDrained: build.review\n\n      build:\n        machine: buildTail\n        with:\n          onDone: idle\n          onFeedback: re-unwind\n";
 //#endregion
 //#region src/workflows/templates.ts
 const SCHEMA_URL = "https://cdn.jsdelivr.net/npm/@pmelab/gtd/schema.json";
@@ -205117,17 +205577,23 @@ const toCodeAction = (uri) => (action) => ({
 	kind: import_main.CodeActionKind.QuickFix,
 	edit: { changes: { [uri]: [...action.edits] } }
 });
-/** A `SteeringPointer` → a `Location` resolved against `root` — a collapsed range (a cursor, not a selection), the target file never stat-ed. */
-const toLocation = (root) => (pointer) => ({
-	uri: pathToFileURL(resolve(root, pointer.path)).toString(),
+/**
+* A `SteeringPointer` → a `Location` — a collapsed range (a cursor, not a
+* selection). An absent `pointer.path` means "this same document": the
+* `Location` uses `documentUri` untouched, and `root` (needed only to
+* resolve a foreign `path` against the git working tree) goes unused. An
+* absent `pointer.character` lands at column 0.
+*/
+const toLocation = (root, documentUri) => (pointer) => ({
+	uri: pointer.path === void 0 ? documentUri : pathToFileURL(resolve(root, pointer.path)).toString(),
 	range: {
 		start: {
 			line: pointer.line,
-			character: 0
+			character: pointer.character ?? 0
 		},
 		end: {
 			line: pointer.line,
-			character: 0
+			character: pointer.character ?? 0
 		}
 	}
 });
@@ -205261,10 +205727,11 @@ const makeSteeringLanguageService = (env, warn) => {
 			return ((await capabilitiesFor(uri)).format?.actions(text, range) ?? []).map(toCodeAction(uri));
 		},
 		definition: async (uri, text, position) => {
-			const pointer = (await capabilitiesFor(uri)).format?.pointerAt?.(text, position.line);
+			const pointer = (await capabilitiesFor(uri)).format?.pointerAt?.(text, position);
 			if (pointer === void 0) return [];
+			if (pointer.path === void 0) return [toLocation("", uri)(pointer)];
 			const root = await safeGitTopLevel(dirname(fileURLToPath(uri))) ?? workspaceRoot;
-			return root === void 0 ? [] : [toLocation(root)(pointer)];
+			return root === void 0 ? [] : [toLocation(root, uri)(pointer)];
 		},
 		diagnostics: async (uri, text) => {
 			const map = await safeSteeringMap(rootFor(uri));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmelab/gtd",
-  "version": "10.4.0",
+  "version": "10.5.0",
   "private": false,
   "description": "Git-aware CLI that emits the next prompt for an autonomous coding agent based on the current repository state",
   "bin": {