@pmelab/gtd 64.0.0 → 64.1.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "gtd",
-  "version": "64.0.0",
+  "version": "64.1.0",
   "description": "Drive the gtd loop inside Claude Code: agent turns run as subagents, gtd decides every beat",
   "author": {
     "name": "Philipp Melab"

package/README.md

@@ -610,14 +610,14 @@ approvals as `approvals` (`[]` when none), and `gtd history show` prints each as
 gtd is one package, `@pmelab/gtd`, and every entrypoint shares its version and
 [SemVer promise](https://github.com/pmelab/gtd/blob/main/COMPATIBILITY.md).
 
-| Import                        | What it is                                                                                                                                                                                                                         |
-| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `@pmelab/gtd/flows`           | The flow API a workflow is written in: the steps (`agent`, `human`, `run`, …), `scope`, `workflow()`, workflow factories, `defineConfig` and `FLOWS_PROTOCOL`.                                                                     |
-| `@pmelab/gtd/wire`            | The driver protocol: `WIRE_SCHEMA`, the exit codes and the types of every `--json` document.                                                                                                                                       |
-| `@pmelab/gtd/steering`        | The steering-file formats (`qa`, `review`, `findings`), the review-note readers, and `sections`, `threads` and `openQuestions` as plain functions.                                                                                 |
-| `@pmelab/gtd/workflow-kit`    | Policy-free building blocks to compose a workflow from: health checks, quality laps, scenario freezing, review tails. See [Workflow kit](https://github.com/pmelab/gtd/blob/main/docs/workflow-kit.md).                            |
-| `@pmelab/gtd/testkit`         | Runs any workflow against the real engine in an in-memory repository, under any test runner, plus a flow-context harness for rendering prompts. See [Testing a workflow](https://github.com/pmelab/gtd/blob/main/docs/testing.md). |
-| `@pmelab/gtd/testkit/gherkin` | The testkit as quickpickle steps for vitest. Needs `vitest` and `quickpickle`, optional peer dependencies.                                                                                                                         |
+| Import                        | What it is                                                                                                                                                                                                                                                                                                               |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `@pmelab/gtd/flows`           | The flow API a workflow is written in: the steps (`agent`, `human`, `run`, …), `scope`, `workflow()`, workflow factories, `defineConfig` and `FLOWS_PROTOCOL`.                                                                                                                                                           |
+| `@pmelab/gtd/wire`            | The driver protocol: `WIRE_SCHEMA`, the exit codes and the types of every `--json` document.                                                                                                                                                                                                                             |
+| `@pmelab/gtd/steering`        | The steering-file formats (`qa`, `review`, `findings`), `listFormat`/`sectionFormat` to [declare a format](https://github.com/pmelab/gtd/blob/main/docs/configuration.md#declared-formats) a step's `mode` validates against, the review-note readers, and `sections`, `threads` and `openQuestions` as plain functions. |
+| `@pmelab/gtd/workflow-kit`    | Policy-free building blocks to compose a workflow from: health checks, quality laps, scenario freezing, review tails. See [Workflow kit](https://github.com/pmelab/gtd/blob/main/docs/workflow-kit.md).                                                                                                                  |
+| `@pmelab/gtd/testkit`         | Runs any workflow against the real engine in an in-memory repository, under any test runner, plus a flow-context harness for rendering prompts. See [Testing a workflow](https://github.com/pmelab/gtd/blob/main/docs/testing.md).                                                                                       |
+| `@pmelab/gtd/testkit/gherkin` | The testkit as quickpickle steps for vitest. Needs `vitest` and `quickpickle`, optional peer dependencies.                                                                                                                                                                                                               |
 
 Types come from the TypeScript sources the package ships. Configs never need an
 install for any of these but the testkit's: gtd resolves a `gtd.config.ts`'s

package/dist/chunks/{steering-DkA51qDa.mjs → steering-Cem5i6Xl.mjs}

@@ -16600,6 +16600,426 @@ const freeFormFormat = {
 	clearTicks: (content) => content
 };
 //#endregion
+//#region src/steering/Declared.ts
+const FENCE_RE = /^( *)(`{3,}|~{3,})/;
+const HEADING_RE = /^ {0,3}(#{1,6})(?:[ \t]+(.*?))?(?:[ \t]+#+)?[ \t]*$/;
+const ITEM_RE = /^( *)([-*+]|\d{1,9}[.)])(?:[ \t]+(.*))?$/;
+const CHECKBOX_RE = /^\[([ xX])\](?:[ \t]+|$)/;
+/** Marks fenced lines; an unclosed fence is a problem rather than swallowing the rest of the document. */
+const walk = (content) => {
+	const raw = content.split(/\r?\n/);
+	const lines = [];
+	const problems = [];
+	let open;
+	for (const [index, text] of raw.entries()) {
+		const fence = FENCE_RE.exec(text);
+		if (open === void 0) {
+			if (fence !== null) {
+				open = {
+					char: fence[2][0],
+					length: fence[2].length,
+					line: index,
+					indent: fence[1].length
+				};
+				lines.push({
+					index,
+					text,
+					fenced: true,
+					fenceIndent: open.indent,
+					opens: true
+				});
+			} else lines.push({
+				index,
+				text,
+				fenced: false
+			});
+			continue;
+		}
+		lines.push({
+			index,
+			text,
+			fenced: true,
+			fenceIndent: open.indent
+		});
+		if (fence !== null && fence[2][0] === open.char && fence[2].length >= open.length && text.slice(fence[0].length).trim() === "") open = void 0;
+	}
+	if (open !== void 0) problems.push({
+		line: open.line,
+		message: "code fence is never closed"
+	});
+	return {
+		lines,
+		problems
+	};
+};
+const headingOf = (line) => {
+	if (line.fenced) return void 0;
+	const match = HEADING_RE.exec(line.text);
+	return match === null ? void 0 : {
+		line: line.index,
+		level: match[1].length,
+		title: (match[2] ?? "").trim()
+	};
+};
+const indentOf = (text) => /^ */.exec(text)[0].length;
+const markerKind = (marker) => marker === "-" || marker === "*" || marker === "+" ? marker : "1.";
+const markerList = (markers) => markers.map((m) => `\`${m}\``).join(" or ");
+const titleMatches = (spec, title) => typeof spec.title === "string" ? spec.title.trim().toLowerCase() === title.toLowerCase() : spec.title.test(title);
+const titleShown = (spec) => typeof spec.title === "string" ? spec.title : spec.example;
+/** The lines the list lives on, with the section-heading problems. */
+const regionOf = (spec, lines) => {
+	const section = spec.section;
+	if (section === void 0) return {
+		region: {
+			start: 0,
+			end: lines.length
+		},
+		problems: []
+	};
+	const problems = [];
+	const headings = lines.flatMap((line) => headingOf(line) ?? []);
+	const matching = headings.filter((h) => titleMatches(section, h.title));
+	const wanted = "#".repeat(section.level);
+	for (const h of matching.filter((h) => h.level !== section.level)) problems.push({
+		line: h.line,
+		message: `"${h.title}" is a level-${h.level} heading — write it as \`${wanted} ${h.title}\``
+	});
+	const atLevel = matching.filter((h) => h.level === section.level);
+	for (const h of atLevel.slice(1)) problems.push({
+		line: h.line,
+		message: `"${h.title}" repeats the section on line ${atLevel[0].line + 1} — keep one`
+	});
+	const first = atLevel[0];
+	if (first === void 0) {
+		if (section.required !== false && matching.length === 0) problems.push({ message: `missing the \`${wanted} ${titleShown(section)}\` section` });
+		return { problems };
+	}
+	const next = headings.find((h) => h.line > first.line && h.level <= section.level);
+	return {
+		region: {
+			start: first.line + 1,
+			end: next?.line ?? lines.length
+		},
+		problems
+	};
+};
+/** One pass over the region: items, their continuations, and every lint the format implies. */
+const readItems = (spec, lines, region) => {
+	const markers = spec.markers ?? ["-"];
+	const wrap = spec.wrap ?? "join";
+	const problems = [];
+	const drafts = [];
+	let firstKind;
+	let current;
+	let blank = false;
+	let prose = [];
+	const continueWith = (line, text) => {
+		if (wrap === "forbid") {
+			problems.push({
+				line: line.index,
+				message: "one line per item — this line continues the one above"
+			});
+			return;
+		}
+		current.parts.push(text.trim());
+	};
+	for (const line of lines.slice(region.start, region.end)) {
+		const text = line.text;
+		if (line.fenced) {
+			if (current !== void 0 && (line.fenceIndent ?? 0) >= 2) {
+				blank = false;
+				continue;
+			}
+			if (line.opens === true && current !== void 0) {
+				prose.push(line.index);
+				current = void 0;
+			} else if (line.opens !== true && ITEM_RE.test(text) && indentOf(text) < 2) problems.push({
+				line: line.index,
+				message: "a list item inside a code fence is not read as an item"
+			});
+			blank = false;
+			continue;
+		}
+		if (text.trim() === "") {
+			blank = true;
+			continue;
+		}
+		const item = ITEM_RE.exec(text);
+		const indent = indentOf(text);
+		if (item !== null && indent < 2) {
+			for (const p of prose) problems.push({
+				line: p,
+				message: "text between items — make it part of an item, or move it out of the list"
+			});
+			prose = [];
+			const kind = markerKind(item[2]);
+			if (!markers.includes(kind)) problems.push({
+				line: line.index,
+				message: `\`${item[2]}\` is not an allowed marker — use ${markerList(markers)}`
+			});
+			else if (firstKind !== void 0 && kind !== firstKind) problems.push({
+				line: line.index,
+				message: `\`${item[2]}\` mixes markers in one list — the list started with \`${firstKind}\``
+			});
+			firstKind ??= kind;
+			current = {
+				line: line.index,
+				parts: [(item[3] ?? "").trim()]
+			};
+			drafts.push(current);
+			blank = false;
+			continue;
+		}
+		if (current === void 0) {
+			blank = false;
+			continue;
+		}
+		if (item !== null) problems.push({
+			line: line.index,
+			message: "nested list — this format is flat, one level of items"
+		});
+		else if (indent >= 2) continueWith(line, text);
+		else if (!blank) {
+			problems.push({
+				line: line.index,
+				message: "continuation line is not indented — indent it under its item, or separate it with a blank line"
+			});
+			continueWith(line, text);
+		} else {
+			prose.push(line.index);
+			current = void 0;
+		}
+		blank = false;
+	}
+	return {
+		drafts,
+		problems
+	};
+};
+/** Strips a leading `[ ]`/`[x]`, reporting it where the format forbids or requires one. */
+const readCheckbox = (spec, draft, problems) => {
+	const checkbox = spec.checkbox ?? "forbid";
+	const text = draft.parts.join(" ").trim();
+	const box = CHECKBOX_RE.exec(text);
+	if (box === null) {
+		if (checkbox === "require") problems.push({
+			line: draft.line,
+			message: "every item starts with a checkbox — write `- [ ] …`"
+		});
+		return checkbox === "forbid" ? { text } : {
+			text,
+			checked: false
+		};
+	}
+	if (checkbox === "forbid") problems.push({
+		line: draft.line,
+		message: "no checkboxes in this list — drop the `[ ]`"
+	});
+	const rest = text.slice(box[0].length).trim();
+	return checkbox === "forbid" ? { text: rest } : {
+		text: rest,
+		checked: box[1] !== " "
+	};
+};
+const finishItem = (spec, draft, problems) => {
+	const { text, ...checked } = readCheckbox(spec, draft, problems);
+	const item = spec.item;
+	if (text === "") {
+		problems.push({
+			line: draft.line,
+			message: "empty item"
+		});
+		return;
+	}
+	if (item === void 0) return {
+		line: draft.line,
+		text,
+		...checked
+	};
+	const at = text.indexOf(item.separator);
+	const id = at < 0 ? "" : text.slice(0, at).trim();
+	if (at < 0 || !item.id.test(id)) {
+		problems.push({
+			line: draft.line,
+			message: `item has no ID — start it \`${item.example}${item.separator} …\``
+		});
+		return;
+	}
+	const body = text.slice(at + item.separator.length).trim();
+	if (body === "") problems.push({
+		line: draft.line,
+		message: `empty item — ${id} has no text`
+	});
+	return {
+		line: draft.line,
+		text: body,
+		id,
+		...checked
+	};
+};
+const parseList = (spec, content) => {
+	const walked = walk(content);
+	const { region, problems: sectionProblems } = regionOf(spec, walked.lines);
+	const problems = [...walked.problems, ...sectionProblems];
+	if (region === void 0) return {
+		items: [],
+		problems
+	};
+	const read = readItems(spec, walked.lines, region);
+	problems.push(...read.problems);
+	const items = read.drafts.flatMap((draft) => finishItem(spec, draft, problems) ?? []);
+	if (spec.ids?.unique === true) {
+		const seen = /* @__PURE__ */ new Map();
+		for (const item of items) {
+			if (item.id === void 0) continue;
+			const first = seen.get(item.id);
+			if (first === void 0) seen.set(item.id, item.line);
+			else problems.push({
+				line: item.line,
+				message: `duplicate ID ${item.id} — first on line ${first + 1}`
+			});
+		}
+	}
+	problems.sort((a, b) => (a.line ?? -1) - (b.line ?? -1));
+	return {
+		items,
+		problems
+	};
+};
+const sectionSentence = (spec) => {
+	if (spec.section === void 0) return "The whole document is the list.";
+	return `Write the list under one \`${`${"#".repeat(spec.section.level)} ${titleShown(spec.section)}`}\` heading; it ends at the next heading of the same or a higher level.`;
+};
+const CHECKBOX_SENTENCE = {
+	forbid: "Do not use checkboxes.",
+	strip: "",
+	require: "Start every item with a checkbox: `[ ]`, or `[x]` when done."
+};
+const idSentence = (spec) => {
+	if (spec.item === void 0) return "";
+	const unique = spec.ids?.unique === true ? ", unique within the list" : "";
+	return `Start every item with its ID (like \`${spec.item.example}\`${unique}), then \`${spec.item.separator}\`, then the text.`;
+};
+const listInstructions = (spec) => [
+	sectionSentence(spec),
+	`Write each item as a ${markerList(spec.markers ?? ["-"])} list item, all with the same marker.`,
+	CHECKBOX_SENTENCE[spec.checkbox ?? "forbid"],
+	idSentence(spec),
+	(spec.wrap ?? "join") === "join" ? "Continue a long item on lines indented two spaces under it." : "Keep every item on one line.",
+	"Keep the list flat: no nested items, and no text between items. Items inside a code fence are not read."
+].filter((sentence) => sentence !== "").join(" ");
+const listSample = (spec) => {
+	const item = `${(spec.markers ?? ["-"])[0] === "1." ? "1." : (spec.markers ?? ["-"])[0]} ${spec.checkbox === "require" ? "[ ] " : ""}${spec.item !== void 0 ? `${spec.item.example}${spec.item.separator} ` : ""}Describe the item.\n`;
+	return spec.section === void 0 ? item : `${"#".repeat(spec.section.level)} ${titleShown(spec.section)}\n\n${item}`;
+};
+const bodyOf = (lines, start, end) => lines.slice(start, end).map((l) => l.text).join("\n").trim();
+/** The problem with heading `i` as a section, if any; `null` when it is not a section heading at all. */
+const sectionHeadingProblem = (spec, headings, i, firstLine) => {
+	const h = headings[i];
+	if (h.level < spec.level && headings.slice(0, i).some((p) => p.level === spec.level)) return `"${h.title}" is a level-${h.level} heading — sections are \`${"#".repeat(spec.level)}\``;
+	if (h.level !== spec.level) return null;
+	if (h.title === "") return "section heading has no title";
+	const first = firstLine.get(h.title.toLowerCase());
+	return spec.title === "unique" && first !== void 0 ? `"${h.title}" repeats the section on line ${first + 1} — titles are unique` : void 0;
+};
+const parseSections = (spec, content) => {
+	const walked = walk(content);
+	const problems = [...walked.problems];
+	const headings = walked.lines.flatMap((line) => headingOf(line) ?? []);
+	const sections = [];
+	const firstLine = /* @__PURE__ */ new Map();
+	for (const [i, h] of headings.entries()) {
+		const problem = sectionHeadingProblem(spec, headings, i, firstLine);
+		if (problem === null) continue;
+		if (problem !== void 0) problems.push({
+			line: h.line,
+			message: problem
+		});
+		if (h.level !== spec.level || h.title === "") continue;
+		if (!firstLine.has(h.title.toLowerCase())) firstLine.set(h.title.toLowerCase(), h.line);
+		const end = headings.slice(i + 1).find((n) => n.level <= spec.level)?.line ?? walked.lines.length;
+		sections.push({
+			line: h.line,
+			title: h.title,
+			body: bodyOf(walked.lines, h.line + 1, end)
+		});
+	}
+	problems.sort((a, b) => (a.line ?? -1) - (b.line ?? -1));
+	return {
+		sections,
+		problems
+	};
+};
+const sectionInstructions = (spec) => {
+	const hashes = "#".repeat(spec.level);
+	return [
+		`Write each section under a \`${hashes} Title\` heading.`,
+		spec.title === "unique" ? "No two sections share a title." : "",
+		spec.level > 1 ? `Use deeper headings inside a section only; no heading above \`${hashes}\` after the first section.` : "",
+		"Close every code fence."
+	].filter((s) => s !== "").join(" ");
+};
+const NAME_RE = /^[a-z][a-z0-9-]*$/;
+const pattern = (re) => new RegExp(re.source, re.flags.replace(/[gy]/g, ""));
+const encode = (value) => value instanceof RegExp ? {
+	source: value.source,
+	flags: value.flags
+} : Array.isArray(value) ? value.map(encode) : typeof value === "object" && value !== null ? Object.fromEntries(Object.entries(value).map(([k, v]) => [k, encode(v)])) : value;
+const isPattern = (value) => typeof value === "object" && value !== null && typeof value.source === "string" && typeof value.flags === "string";
+const checkName = (name) => {
+	if (typeof name !== "string" || !NAME_RE.test(name)) throw new Error(`format name must be lowercase letters, digits and "-" — got ${JSON.stringify(name)}`);
+	return name;
+};
+const withThreads = (name, spec, kind, parse, instructions, sample) => ({
+	...freeFormFormat,
+	openThreads: openThreadsOf,
+	name,
+	spec: JSON.stringify({
+		kind,
+		...encode(spec)
+	}),
+	instructions,
+	sample,
+	parse,
+	validate: (content) => [...parse(content).problems, ...threadFindings(content)]
+});
+/** Declares a list format: `parse`, `validate`, `instructions` and `sample` all derive from `spec`. Usable as a step's `mode`. */
+const listFormat = (spec) => {
+	const name = checkName(spec.name);
+	const normalized = {
+		...spec,
+		...spec.section !== void 0 && typeof spec.section.title !== "string" ? { section: {
+			...spec.section,
+			title: pattern(spec.section.title)
+		} } : {},
+		...spec.item !== void 0 ? { item: {
+			...spec.item,
+			id: pattern(spec.item.id)
+		} } : {}
+	};
+	if ((normalized.markers ?? ["-"]).length === 0) throw new Error(`format "${name}": markers is empty`);
+	if (normalized.item !== void 0 && !normalized.item.id.test(normalized.item.example)) throw new Error(`format "${name}": item.example "${normalized.item.example}" does not match item.id`);
+	const section = normalized.section;
+	if (section !== void 0 && typeof section.title !== "string" && (section.example === void 0 || !section.title.test(section.example))) throw new Error(`format "${name}": a RegExp section.title needs a section.example it matches`);
+	const format = withThreads(name, normalized, "list", (content) => parseList(normalized, content), listInstructions(normalized), listSample(normalized));
+	if (format.parse(format.sample).problems.length > 0) throw new Error(`format "${name}": its own sample does not validate`);
+	return format;
+};
+/** Declares a document of headed sections. Usable as a step's `mode`. */
+const sectionFormat = (spec) => {
+	const name = checkName(spec.name);
+	const hashes = "#".repeat(spec.level);
+	return withThreads(name, spec, "section", (content) => parseSections(spec, content), sectionInstructions(spec), `${hashes} First section\n\nWhat this section says.\n`);
+};
+const decodePatterns = (value, key) => (key === "title" || key === "id") && isPattern(value) ? new RegExp(value.source, value.flags) : Array.isArray(value) ? value.map((v) => decodePatterns(v)) : typeof value === "object" && value !== null ? Object.fromEntries(Object.entries(value).map(([k, v]) => [k, decodePatterns(v, k)])) : value;
+/** The format a declared format's `spec` describes — what `gtd check --spec` validates with. Throws on a spec no declaration produces. */
+const formatFromSpec = (spec) => {
+	const { kind, ...rest } = decodePatterns(JSON.parse(spec));
+	if (kind === "list") return listFormat(rest);
+	if (kind === "section") return sectionFormat(rest);
+	throw new Error(`not a declared format spec: ${JSON.stringify(kind)}`);
+};
+//#endregion
 //#region src/steering/registry.ts
 /** The built-in registry: mode name → its format, in registry order. The single place the built-in formats are wired into names — everything else in this module dispatches over a resolved `SteeringFormat`, never a mode-name string. */
 const REGISTRY = /* @__PURE__ */ new Map([
@@ -16827,4 +17247,4 @@ const stripCodeThreads = (path, text) => {
 	return lines.filter((_, i) => !drop.has(i)).join("\n");
 };
 //#endregion
-export { parseThreads as A, FREE_TEXT_PLACEHOLDER as C, findingEntries as D, NOISE_HEADING as E, headingSectionBodies as M, formatFinding as N, openThreadFindings as O, unansweredNotes as S, FIX_BOX as T, reviewChunks as _, sections as a, reviewRisks as b, openThreads as c, freeFormFormat as d, applySteeringEdits as f, REVIEW_SECTIONS as g, ANSWER_WONT_FIX as h, sectionBodies as i, parseThreadsWithFindings as j, parseFootnotes as k, steeringFormatFor as l, ANSWER_LEAD as m, stripCodeThreads as n, threads as o, ANSWER_FIX as p, openQuestions as r, BUILT_IN_MODE_NAMES as s, parseCodeThreads as t, unansweredQuestions as u, reviewDecisions as v, isAnswered as w, reviewSections as x, reviewNotes as y };
+export { findingEntries as A, reviewRisks as C, isAnswered as D, FREE_TEXT_PLACEHOLDER as E, headingSectionBodies as F, formatFinding as I, parseFootnotes as M, parseThreads as N, FIX_BOX as O, parseThreadsWithFindings as P, reviewNotes as S, unansweredNotes as T, ANSWER_LEAD as _, sections as a, reviewChunks as b, openThreads as c, formatFromSpec as d, listFormat as f, ANSWER_FIX as g, applySteeringEdits as h, sectionBodies as i, openThreadFindings as j, NOISE_HEADING as k, steeringFormatFor as l, freeFormFormat as m, stripCodeThreads as n, threads as o, sectionFormat as p, openQuestions as r, BUILT_IN_MODE_NAMES as s, parseCodeThreads as t, unansweredQuestions as u, ANSWER_WONT_FIX as v, reviewSections as w, reviewDecisions as x, REVIEW_SECTIONS as y };

package/dist/chunks/{testkit-zGjNeQNL.mjs → testkit-DfWZQCWQ.mjs}

@@ -1,6 +1,6 @@
 import { C as moveScript, D as revertScript, E as restoreScript, H as installContext, K as markedOptions, O as showScript, S as checkScript, T as removeScript, Y as protocolMismatch, i as configure, k as writeScript$1, n as configProblems, o as isFactoryWorkflow, p as numeric, s as answered, t as flows_exports, x as applyScript } from "./flows-B7ZRCe-B.mjs";
 import { M as renderFormat, O as ACCESS_REFUSAL, a as renderScriptJson, d as renderLandPlain, f as DEMAND_BRIEFING, g as statusOf, h as renderBeatJson, i as judgeJson, k as PIN_PATH, l as noopText, m as beatDocument, n as resolveSession, o as scriptFields, p as renderBeatPlain, r as selectPath, s as landFields, t as globMatches, u as renderLandJson, v as beatKindOf, y as demandOf } from "./wire-CPNSm_9N.mjs";
-import { M as headingSectionBodies, N as formatFinding, a as sections, c as openThreads, i as sectionBodies, l as steeringFormatFor, o as threads, r as openQuestions, s as BUILT_IN_MODE_NAMES, t as parseCodeThreads, u as unansweredQuestions } from "./steering-DkA51qDa.mjs";
+import { F as headingSectionBodies, I as formatFinding, a as sections, c as openThreads, d as formatFromSpec, i as sectionBodies, l as steeringFormatFor, o as threads, r as openQuestions, s as BUILT_IN_MODE_NAMES, t as parseCodeThreads, u as unansweredQuestions } from "./steering-Cem5i6Xl.mjs";
 import { createRequire, isBuiltin } from "node:module";
 import * as Crypto from "node:crypto";
 import { createHash } from "node:crypto";
@@ -24289,6 +24289,8 @@ const replay = async (raw) => {
 const seededValidateCommand = (mode) => `gtd check ${mode} "$GTD_FILE"`;
 /** True when `command` is exactly `mode`'s seeded template (compared literally, not rendered) — distinguishes gtd's own seeding from a user override. */
 const isSeededValidateCommand = (mode, command) => command === seededValidateCommand(mode);
+/** The `validate:` command for a declared format: its spec travels on the command line, so `gtd check` loads no workflow to find it. */
+const declaredValidateCommand = (mode, spec) => `gtd check ${mode} "$GTD_FILE" --spec '${spec.replace(/'/g, "'\\''")}'`;
 //#endregion
 //#region src/workflow/compile.ts
 /**
@@ -25723,8 +25725,27 @@ const capabilitiesFor = (mode, format, validate) => {
 * The `"unknown"` arm carries the whole refusal message, naming what IS known
 * when `def` is given — this is the one place that message is built, so it
 * can never drift from what actually resolved.
+*
+* `spec` is a declared format's: it alone decides, validating through
+* `gtd check --spec` with no `format:` half.
 */
-const resolveMode = (def, state, mode) => {
+const resolveMode = (def, state, mode, spec) => {
+	if (spec !== void 0) {
+		const format = formatFromSpec(spec);
+		return {
+			kind: "resolved",
+			mode,
+			format,
+			validate: {
+				kind: "command",
+				command: declaredValidateCommand(mode, spec)
+			},
+			capabilities: {
+				format,
+				liveValidate: format.validate
+			}
+		};
+	}
 	const declared = def?.modes?.[mode];
 	const format = steeringFormatFor(mode);
 	if (declared === void 0 && format === void 0) return {
@@ -26392,7 +26413,10 @@ const commonOf = (step) => {
 		actor: step.actor,
 		...optional("label", options.label),
 		...optional("file", options.file),
-		...optional("mode", options.mode)
+		...typeof options.mode === "object" ? {
+			mode: options.mode.name,
+			modeSpec: options.mode.spec
+		} : optional("mode", options.mode)
 	};
 };
 const promptDef = (common, request, skills, access) => ({
@@ -26468,6 +26492,13 @@ const hintsOf = (def) => ({
 	...optional("skills", def.skills),
 	...optional("access", def.access)
 });
+/** A step's mode is a name the workflow knows, or a declared format named apart from all of them. */
+const modeFaultOf = (def, stepName, stepDef) => {
+	if (stepDef.mode === void 0) return void 0;
+	const known = def.modes[stepDef.mode] !== void 0;
+	if (stepDef.modeSpec !== void 0) return known ? `gtd: config: step "${stepName}": declared format "${stepDef.mode}" has the name of a mode this workflow already knows — rename the format` : void 0;
+	return known ? void 0 : `gtd: config: step "${stepName}": mode "${stepDef.mode}" is not a mode this workflow knows (${knownModes(def).join(", ")})`;
+};
 const normalizeStatus = (raw) => raw === "A" ? "A" : raw === "D" ? "D" : "M";
 /** Per-model token totals, highest-cost first (ties broken by model name). */
 const costByModel = (entries) => {
@@ -26559,7 +26590,8 @@ const restAt = (ref, startOverrides = {}) => gen(function* () {
 	const { reached, step } = resting;
 	const { stepDef, state, memory } = restFacts(pin, step, reached.trace, run);
 	yield* (yield* Narrator).narrate(`rest resolved: ${state} (awaits ${stepDef.actor})`);
-	if (stepDef.mode !== void 0 && def.modes[stepDef.mode] === void 0) return yield* fail$4(/* @__PURE__ */ new Error(`gtd: config: step "${step.name}": mode "${stepDef.mode}" is not a mode this workflow knows (${knownModes(def).join(", ")})`));
+	const modeFault = modeFaultOf(def, step.name, stepDef);
+	if (modeFault !== void 0) return yield* fail$4(new Error(modeFault));
 	const changes = ref === void 0 ? (yield* pendingChanges(git, stepDef.approve === true)).map((e) => ({
 		status: normalizeStatus(e.status),
 		path: e.path
@@ -28168,8 +28200,8 @@ const runRepinCommand = (json, out) => gen(function* () {
 * `gtd check <mode>` invocation instead, so there's always something concrete
 * to name.
 */
-const selfValidateCommand = (def, state, mode, file) => {
-	const resolved = resolveMode(def, state, mode);
+const selfValidateCommand = (def, state, mode, file, spec) => {
+	const resolved = resolveMode(def, state, mode, spec);
 	const validate = resolved.kind === "resolved" ? resolved.validate : void 0;
 	return commandForFile(validate?.kind === "command" ? validate.command : seededValidateCommand(mode), file);
 };
@@ -28187,7 +28219,7 @@ const resolveValidateScript = (rest) => gen(function* () {
 	const file = rest.hints.file;
 	const mode = rest.stepDef.mode;
 	if (file === void 0 || mode === void 0) return void 0;
-	const resolved = resolveMode(rest.def, rest.state, mode);
+	const resolved = resolveMode(rest.def, rest.state, mode, rest.stepDef.modeSpec);
 	if (resolved.kind === "unknown") return yield* fail$4(new Error(resolved.message));
 	const { script } = yield* validateScriptFor(resolved, file);
 	return {
@@ -28218,7 +28250,7 @@ const runNextCommand = (json, out) => gen(function* () {
 	if (json.kind === "document") out.write(renderBeatJson(fields));
 	else if (json.kind === "select") yield* writeSelection(out, fields, json.path);
 	else {
-		const validateCommand = emitsValidatablePrompt(rendered) ? selfValidateCommand(rest.def, rest.state, rendered.mode, rendered.file) : void 0;
+		const validateCommand = emitsValidatablePrompt(rendered) ? selfValidateCommand(rest.def, rest.state, rendered.mode, rendered.file, rest.stepDef.modeSpec) : void 0;
 		if (DEMAND_BRIEFING[fields.kind].suppressHeader) {
 			const shown = renderBeatPlain({
 				...fields,
@@ -28245,8 +28277,8 @@ const runValidateCommand = (json, out) => gen(function* () {
 * Findings ride the failing Effect's message, so the shared refusal path
 * reports them on stderr.
 */
-const runCheckCommand = (mode, file, openQuestions, openThreadsFlag) => gen(function* () {
-	const format = steeringFormatFor(mode);
+const runCheckCommand = (mode, file, openQuestions, openThreadsFlag, spec) => gen(function* () {
+	const format = spec !== void 0 ? yield* declaredFormat(spec) : steeringFormatFor(mode);
 	if (format === void 0) return yield* fail$4(new GtdUsageError(`gtd check: unknown mode "${mode}" — known modes: ${BUILT_IN_MODE_NAMES.join(", ")}`));
 	if (openThreadsFlag) {
 		if (openQuestions) return yield* fail$4(/* @__PURE__ */ new Error("gtd check: --open-threads and --open-questions are mutually exclusive"));
@@ -28265,6 +28297,10 @@ const runCheckCommand = (mode, file, openQuestions, openThreadsFlag) => gen(func
 	if (errors.length === 0) return;
 	return yield* fail$4(/* @__PURE__ */ new Error(`gtd check: ${file} is not valid under mode "${mode}" (${errors.length} finding(s)):\n` + errors.join("\n")));
 });
+const declaredFormat = (spec) => try_({
+	try: () => formatFromSpec(spec),
+	catch: (error) => new GtdUsageError(`gtd check: --spec is not a declared format: ${error.message}`)
+});
 const existingFile = (file) => flatMap(Workspace, (workspace) => {
 	const content = workspace.atPath(file);
 	return content === void 0 ? fail$4(/* @__PURE__ */ new Error(`gtd check: no such file: ${file}`)) : succeed$1(content);
@@ -28434,7 +28470,7 @@ const dispatchVoidCommand = (command, json, out) => {
 		case "validate": return runValidateCommand(json, out);
 		case "check":
 			if (command.mode === void 0 || command.file === void 0) return runCodeThreadsCheckCommand();
-			return runCheckCommand(command.mode, command.file, command.openQuestions ?? false, command.openThreads ?? false);
+			return runCheckCommand(command.mode, command.file, command.openQuestions ?? false, command.openThreads ?? false, command.spec);
 		case "uncheck": return runUncheckCommand(command.file);
 		case "guide": return runGuideCommand(out);
 		case "bundle": return runBundleCommand(out);
@@ -28729,6 +28765,16 @@ const FLAGS = [
 		valueHint: "",
 		help: "Instead of <mode>'s findings, list the open threads in <file>; exits 1 when any are open. Alone, lists the open code-comment threads in the files the current process changed"
 	},
+	{
+		name: "--spec",
+		arity: 1,
+		repeatable: false,
+		scope: (kind) => kind === "check",
+		decode: ([raw]) => succeed$5(raw ?? ""),
+		scopeError: "gtd: --spec is only valid for `gtd check`",
+		valueHint: "<json>",
+		help: "Check against the declared format this spec describes, named <mode>, instead of a built-in one; validation scripts pass it for a step whose mode is a declared format"
+	},
 	{
 		name: "--verbose",
 		arity: 0,
@@ -28974,7 +29020,7 @@ The fixed answerer reads --answers and leaves out the questions it does not cove
 		arity: { names: ["mode", "file"] },
 		group: "Driver plumbing",
 		summary: "Check a steering file's format",
-		details: `Run the steering format <mode> (qa, review or findings) over <file> and print each finding on a line of its own; exits 1 when there are any, or when <file> does not exist. An unknown <mode> is a usage error (exit 2). Reads no workflow and runs from any directory — emitted validation scripts call it.`
+		details: `Run the steering format <mode> (qa, review or findings, or the declared format --spec describes) over <file> and print each finding on a line of its own; exits 1 when there are any, or when <file> does not exist. An unknown <mode> is a usage error (exit 2). Reads no workflow and runs from any directory — emitted validation scripts call it.`
 	},
 	{
 		token: "uncheck",
@@ -29348,7 +29394,8 @@ const parseArgv = (argv) => {
 			...restPositionals[0] !== void 0 ? { mode: restPositionals[0] } : {},
 			...restPositionals[1] !== void 0 ? { file: restPositionals[1] } : {},
 			...bag["--open-questions"] !== void 0 ? { openQuestions: bag["--open-questions"] } : {},
-			...bag["--open-threads"] !== void 0 ? { openThreads: bag["--open-threads"] } : {}
+			...bag["--open-threads"] !== void 0 ? { openThreads: bag["--open-threads"] } : {},
+			...bag["--spec"] !== void 0 ? { spec: bag["--spec"] } : {}
 		},
 		json,
 		verbose
@@ -30971,13 +31018,13 @@ const recognizeModeContradictionCheck = (repo, commands, block) => {
 	return parsed === void 0 ? void 0 : simulateModeContradictionCheck(repo, commands, parsed);
 };
 const GTD_CHECK_RE = /^gtd check (\S+) (.+)$/;
-/** `gtd check <mode> <file>` — a non-empty findings array fails the script, mirroring a real invocation's non-zero exit under `set -e`. */
+/** `gtd check <mode> <file> [--spec <json>]` — a non-empty findings array fails the script, mirroring a real invocation's non-zero exit under `set -e`. */
 const recognizeGtdCheck = (repo, block) => {
 	const match = GTD_CHECK_RE.exec(block);
 	if (!match) return void 0;
 	const mode = match[1];
-	const [file] = extractQuotedTokens(match[2]);
-	const format = steeringFormatFor(mode);
+	const [file, spec] = extractQuotedTokens(match[2]);
+	const format = / --spec '/.test(match[2]) && spec !== void 0 ? formatFromSpec(spec) : steeringFormatFor(mode);
 	if (format === void 0 || file === void 0) return {
 		kind: "failed",
 		error: `gtd check: unknown mode "${mode}" — known modes: ${BUILT_IN_MODE_NAMES.join(", ")}`