@pmelab/gtd 64.0.0 → 64.1.0

package/dist/gtd.bundle.mjs

@@ -7415,7 +7415,7 @@ function isFinite(annotations) {
 * @category constructors
 * @since 4.0.0
 */
-function isPattern(regExp, annotations) {
+function isPattern$1(regExp, annotations) {
 	const copy = new globalThis.RegExp(regExp);
 	const payload = {
 		source: copy.source,
@@ -7626,7 +7626,7 @@ function fromRefinement(ast, refinement) {
 }
 /** @internal */
 function isStringFinite(annotations) {
-	return isPattern(isStringFiniteRegExp, {
+	return isPattern$1(isStringFiniteRegExp, {
 		expected: "a string representing a finite number",
 		representation: {
 			id: "effect/schema/isStringFinite",
@@ -10043,7 +10043,7 @@ var init_Channel = __esmMin((() => {
 }));
 //#endregion
 //#region node_modules/effect/dist/internal/glob.js
-var maxExpansions, maxExpandedLength, maxBraceDepth, compile$1, isUnc, compilePattern, globstarNode, splitSegments, drive, isDrive, isRoot, isAbsolute$1, normalize, compileSegment, range, posixClasses, parsePosixClass, parseClass, expandBraces, matchBraceGroups, parseBraceSequence, countExpansions, expandSequence, matchToken, matchWildcard, closure, step, union, accepts, canDescend, needsDirectory, join$1, isMissing, isIgnorable, isNotLink, byName, make$9, walk;
+var maxExpansions, maxExpandedLength, maxBraceDepth, compile$1, isUnc, compilePattern, globstarNode, splitSegments, drive, isDrive, isRoot, isAbsolute$1, normalize, compileSegment, range, posixClasses, parsePosixClass, parseClass, expandBraces, matchBraceGroups, parseBraceSequence, countExpansions, expandSequence, matchToken, matchWildcard, closure, step, union, accepts, canDescend, needsDirectory, join$1, isMissing, isIgnorable, isNotLink, byName, make$9, walk$1;
 var init_glob = __esmMin((() => {
 	init_Array();
 	init_Effect();
@@ -10447,8 +10447,8 @@ var init_glob = __esmMin((() => {
 	isIgnorable = (error) => isMissing(error) || error.reason._tag === "PermissionDenied";
 	isNotLink = (error) => isIgnorable(error) || error.reason._tag === "Unknown";
 	byName = /*#__PURE__*/ mapInput(String$4, (entry) => entry.name);
-	make$9 = (fs) => (pattern, options) => walk(fs, compile$1([pattern], options?.dot ?? false), options);
-	walk = /*#__PURE__*/ fnUntraced(function* (fs, compiled, options) {
+	make$9 = (fs) => (pattern, options) => walk$1(fs, compile$1([pattern], options?.dot ?? false), options);
+	walk$1 = /*#__PURE__*/ fnUntraced(function* (fs, compiled, options) {
 		if (compiled.initial.size === 0) return [];
 		const root = options?.root ?? "";
 		const excludes = compile$1(options?.exclude ?? [], true);
@@ -31157,6 +31157,423 @@ Nothing here is validated — free-form has no structure to conform to.
 	};
 }));
 //#endregion
+//#region src/steering/Declared.ts
+var FENCE_RE, HEADING_RE, ITEM_RE, CHECKBOX_RE, walk, headingOf, indentOf, markerKind, markerList, titleMatches, titleShown, regionOf, readItems, readCheckbox, finishItem, parseList, sectionSentence, CHECKBOX_SENTENCE, idSentence, listInstructions, listSample, bodyOf, sectionHeadingProblem, parseSections, sectionInstructions, NAME_RE, pattern, encode, isPattern, checkName, withThreads, listFormat, sectionFormat, decodePatterns, formatFromSpec;
+var init_Declared = __esmMin((() => {
+	init_Footnotes();
+	init_freeform();
+	FENCE_RE = /^( *)(`{3,}|~{3,})/;
+	HEADING_RE = /^ {0,3}(#{1,6})(?:[ \t]+(.*?))?(?:[ \t]+#+)?[ \t]*$/;
+	ITEM_RE = /^( *)([-*+]|\d{1,9}[.)])(?:[ \t]+(.*))?$/;
+	CHECKBOX_RE = /^\[([ xX])\](?:[ \t]+|$)/;
+	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
+		};
+	};
+	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()
+		};
+	};
+	indentOf = (text) => /^ */.exec(text)[0].length;
+	markerKind = (marker) => marker === "-" || marker === "*" || marker === "+" ? marker : "1.";
+	markerList = (markers) => markers.map((m) => `\`${m}\``).join(" or ");
+	titleMatches = (spec, title) => typeof spec.title === "string" ? spec.title.trim().toLowerCase() === title.toLowerCase() : spec.title.test(title);
+	titleShown = (spec) => typeof spec.title === "string" ? spec.title : spec.example;
+	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
+		};
+	};
+	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
+		};
+	};
+	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] !== " "
+		};
+	};
+	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
+		};
+	};
+	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
+		};
+	};
+	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.`;
+	};
+	CHECKBOX_SENTENCE = {
+		forbid: "Do not use checkboxes.",
+		strip: "",
+		require: "Start every item with a checkbox: `[ ]`, or `[x]` when done."
+	};
+	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.`;
+	};
+	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(" ");
+	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}`;
+	};
+	bodyOf = (lines, start, end) => lines.slice(start, end).map((l) => l.text).join("\n").trim();
+	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;
+	};
+	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
+		};
+	};
+	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(" ");
+	};
+	NAME_RE = /^[a-z][a-z0-9-]*$/;
+	pattern = (re) => new RegExp(re.source, re.flags.replace(/[gy]/g, ""));
+	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;
+	isPattern = (value) => typeof value === "object" && value !== null && typeof value.source === "string" && typeof value.flags === "string";
+	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;
+	};
+	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)]
+	});
+	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;
+	};
+	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`);
+	};
+	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;
+	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
 var REGISTRY, BUILT_IN_MODE_NAMES, steeringFormatFor, steeringFormatOrFreeForm, unansweredQuestions, viewOf, openThreads;
 var init_registry = __esmMin((() => {
@@ -31385,6 +31802,7 @@ var init_steering = __esmMin((() => {
 	init_review();
 	init_Edits();
 	init_freeform();
+	init_Declared();
 	init_registry();
 	init_qa();
 	init_Footnotes();
@@ -32729,6 +33147,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/steering/internal.ts
 var init_internal = __esmMin((() => {
@@ -32736,6 +33156,7 @@ var init_internal = __esmMin((() => {
 	init_Footnotes();
 	init_MarkdownTree();
 	init_registry();
+	init_Declared();
 }));
 //#endregion
 //#region src/workflow/compile.ts
@@ -34147,7 +34568,7 @@ const modeContradictionSkipNotice = (mode) => {
 //#endregion
 //#region src/emit/SteeringMode.ts
 init_dist$1();
-init_steering();
+init_internal();
 /**
 * `format` alone (no live/external verdict) when there's no validator at
 * all; a live in-process validator for a `"builtin"` validate OR a command
@@ -34187,8 +34608,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 {
@@ -34859,7 +35299,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) => ({
@@ -34935,6 +35378,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) => {
@@ -35026,7 +35476,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$8(/* @__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$8(new Error(modeFault));
 	const changes = ref === void 0 ? (yield* pendingChanges(git, stepDef.approve === true)).map((e) => ({
 		status: normalizeStatus(e.status),
 		path: e.path
@@ -36644,8 +37095,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);
 };
@@ -36663,7 +37114,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$8(new Error(resolved.message));
 	const { script } = yield* validateScriptFor(resolved, file);
 	return {
@@ -36694,7 +37145,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,
@@ -36721,8 +37172,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$8(new GtdUsageError(`gtd check: unknown mode "${mode}" — known modes: ${BUILT_IN_MODE_NAMES.join(", ")}`));
 	if (openThreadsFlag) {
 		if (openQuestions) return yield* fail$8(/* @__PURE__ */ new Error("gtd check: --open-threads and --open-questions are mutually exclusive"));
@@ -36741,6 +37192,10 @@ const runCheckCommand = (mode, file, openQuestions, openThreadsFlag) => gen(func
 	if (errors.length === 0) return;
 	return yield* fail$8(/* @__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$8(/* @__PURE__ */ new Error(`gtd check: no such file: ${file}`)) : succeed$2(content);
@@ -36910,7 +37365,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);
@@ -37206,6 +37661,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$6(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,
@@ -37451,7 +37916,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",
@@ -37825,7 +38290,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