@pmelab/gtd 30.1.0 → 31.0.0

package/dist/workflows.mjs

@@ -499,7 +499,7 @@ const fixFindings = async (f) => {
 const DOC_STRING = /^("""|```)/;
 const THEN = /^Then\s/;
 const CONTINUATION = /^(And|But|\*)\s/;
-const HEADING = /^(Feature|Rule|Background|Scenario|Scenario Outline|Scenario Template|Example):/;
+const HEADING$1 = /^(Feature|Rule|Background|Scenario|Scenario Outline|Scenario Template|Example):/;
 /** Trimmed lines outside doc strings, whose content is test input, not steps. */
 const stepLines = (source) => {
 	const out = [];
@@ -519,7 +519,7 @@ const assertionLines = (source) => {
 	let inThen = false;
 	let scenario = "";
 	for (const line of stepLines(source)) {
-		if (HEADING.test(line)) scenario = line;
+		if (HEADING$1.test(line)) scenario = line;
 		if (THEN.test(line)) inThen = true;
 		else if (!CONTINUATION.test(line) && !neutral(line)) inThen = false;
 		if (inThen && !neutral(line)) out.push({
@@ -17223,6 +17223,21 @@ const codeThreadReplies = () => {
   concluded thread in and delete its lines:
 ${waiting.map((t) => `  - ${t.path}:${t.line}: ${t.first}`).join("\n")}`;
 };
+const acceptanceCriteriaBlock = `
+## Acceptance criteria
+
+Whichever lap this is, \`.gtd/REQUIREMENTS.md\` carries a
+\`## Acceptance Criteria\` section: one \`- AC-<n>: <criterion>\` line
+per criterion, numbered from \`AC-1\`. They bind every later step —
+the build is done when each one holds — so each must be checkable: a
+test or a command shows it holds or not. A later lap keeps every ID:
+reword a criterion in place, append a new one with the next unused
+number, delete a dropped one — never renumber, never reuse an ID. When
+the file holds no list (a review loop-back rewrites it), recover the
+last settled one from history (\`git log -p -- .gtd/REQUIREMENTS.md\`)
+and carry its IDs over. Landing is refused while a criterion has no ID or
+two share one.
+`;
 const riskTierBlock = `
 ## Risk tier and production signals
 
@@ -17266,7 +17281,7 @@ ${footnoteFoldIn}${codeThreadReplies()}
   or both
 - Whichever lap this is, leave \`.gtd/REQUIREMENTS.md\`
   uncommitted and finish once it reflects this lap's own work
-
+${acceptanceCriteriaBlock}
 ## First lap
 
 \`.gtd/REQUIREMENTS.md\` does not exist yet (or holds whatever the
@@ -17321,6 +17336,34 @@ ${questionBarReturn}
   made). If red, make that breakage the first concern, ahead of
   everything else — the build assumes the suite started green
 ${riskTier ? riskTierBlock : ""}`;
+const clearCriteriaQuestion = {
+	id: "clear",
+	primitive: "noul",
+	instructions: "state.criteria lists the acceptance criteria the human's sketch (state.sketch) stated, as gtd numbered them. Decide whether they can stand as the binding definition of done, with no design conversation.",
+	criteria: "yes: every criterion is clear and checkable — a test or a command can show it holds or not — and together they say what to build. no: any one criterion is vague, subjective or untestable, or the sketch leaves an open product question. Unsure means no."
+};
+const clearCriteriaMessage = () => `The sketch stated its own acceptance criteria. Run \`gtd judge answer\` and
+pipe \`yes\` when every one is clear and checkable, so design is skipped and
+they are recorded as they are — or land without a verdict to run the
+ordinary design conversation.
+`;
+const criterionLine = (c) => `- ${c.id}: ${c.text.replace(/\s+/g, " ")}`;
+/** Writes \`.gtd/REQUIREMENTS.md\` from criteria the sketch stated, wrapped the way oxfmt writes it. */
+const normaliseCriteriaScript = (stated) => {
+	return `mkdir -p .gtd
+printf '%s\\n' ${[
+		"# Requirements",
+		"",
+		`Stated in \`${stated.path}\` by the sketch:`,
+		"",
+		`\`git show ${stated.commit}:${stated.path}\``,
+		"",
+		"## Acceptance Criteria",
+		"",
+		...stated.criteria.flatMap((c) => wrapItem(criterionLine(c)))
+	].map(quote).join(" ")} > ${quote(".gtd/REQUIREMENTS.md")}
+`;
+};
 const designSystem = () => `${designPersona}
 
 ${agentConduct}`;
@@ -17645,7 +17688,8 @@ What each change does next (then run \`gtd land\`):
 const wrapItem = (item) => {
 	const out = [];
 	let line = "";
-	for (const word of item.split(" ")) if (line !== "" && line.length + 1 + word.length > 80) {
+	const words = item.split(" ").reduce((acc, word) => acc.length > 0 && /^([-+*>#]|\d+[.)])$/.test(word) ? [...acc.slice(0, -1), `${acc.at(-1)} ${word}`] : [...acc, word], []);
+	for (const word of words) if (line !== "" && line.length + 1 + word.length > 80) {
 		out.push(line);
 		line = `  ${word}`;
 	} else line = line === "" ? word : `${line} ${word}`;
@@ -17943,8 +17987,12 @@ Print the closing message and stop — this writes nothing itself.
 `;
 };
 const listed = (paths, unreadable = []) => paths.map((path) => `  - \`${displayPath(path)}\`${unreadable.includes(path) ? " (unreadable)" : ""}`).join("\n");
+const criteriaBinding = (refused) => `- Its \`## Acceptance Criteria\` (\`AC-<n>\`) bind this turn: re-read them from
+  the file, never from memory, and stop only when each one holds. They are
+  settled — ${refused ? "a turn that changes them is refused" : "leave them as they are"}`;
 const naivePassPrompt = (rejection) => `${stateFileRules}
 - Read \`.gtd/REQUIREMENTS.md\`: the settled requirements for this change
+${criteriaBinding(false)}
 - Implement them the quickest way that works — the naive version. Do not
   restructure, abstract or refactor around the change; a later step judges
   the shape of your diff and a reviewer makes it fit
@@ -17959,6 +18007,7 @@ Start over and choose a different approach; do not rebuild the same diff.
 `}`;
 const implementBuildingPrompt = (reference, tier, amend, afterRefactor, flagMode = true) => `${stateFileRules}
 - Read \`.gtd/REQUIREMENTS.md\`: the settled requirements for this change
+${criteriaBinding(true)}
 ${afterRefactor === true ? `- A reviewed refactor has just landed and may already carry part of the change,
   though never a release flag. Build only what is still missing, held to every
   rule below; if nothing is, change nothing and finish your turn
@@ -37694,6 +37743,128 @@ const markFenced = (text) => {
 	});
 };
 //#endregion
+//#region src/workflows/feature/criteria.ts
+/** Below this the judge's `yes` is not trusted: a wrong skip builds against criteria nobody can check. */
+const CLEAR_MIN_P = .8;
+const HEADING = /^ {0,3}(#{1,6})\s+(.*?)\s*#*\s*$/;
+const ITEM = /^ ?(?:[-*+]|\d+[.)])\s+(?:\[[ xX]\]\s+)?(.*)$/;
+const ID = /^(AC-\d+):\s*(.*)$/;
+/** The list items under the first heading `title` matches (at `level` when given), up to the next heading; wrapped lines joined, fenced lines ignored. */
+const listUnder = (text, title, level) => {
+	const lines = markFenced(text);
+	const at = lines.findIndex((l) => {
+		const heading = l.fenced ? null : HEADING.exec(l.line);
+		return heading !== null && (level === void 0 || heading[1].length === level) && title.test(heading[2]);
+	});
+	if (at === -1) return void 0;
+	const items = [];
+	let open = false;
+	for (const { line, fenced } of lines.slice(at + 1)) {
+		if (fenced) {
+			open = false;
+			continue;
+		}
+		if (HEADING.test(line)) break;
+		const item = ITEM.exec(line);
+		if (item !== null) {
+			items.push(item[1].trim());
+			open = true;
+		} else if (open && line.trim() !== "") items[items.length - 1] = `${items.at(-1)} ${line.trim()}`.trim();
+		else open = false;
+	}
+	return items;
+};
+/** The `- AC-<n>: …` list of `## Acceptance Criteria`, or `undefined` when the section is missing. */
+const criteriaOf = (text) => listUnder(text, /^acceptance criteria$/i, 2)?.map((item) => {
+	const id = ID.exec(item);
+	return id === null ? {
+		id: "",
+		text: item
+	} : {
+		id: id[1],
+		text: id[2]
+	};
+});
+/** Items numbered `AC-1`…, unless every one already carries its own distinct ID. */
+const numbered = (items) => {
+	const ids = items.map((item) => ID.exec(item));
+	const own = ids.every((id) => id !== null) && new Set(ids.map((id) => id[1])).size === ids.length;
+	return items.map((item, i) => own ? {
+		id: ids[i][1],
+		text: ids[i][2]
+	} : {
+		id: `AC-${i + 1}`,
+		text: item.replace(ID, "$2")
+	});
+};
+const STATED = /^acceptance criteria:?$/i;
+const statedItems = (text) => text === void 0 ? [] : (listUnder(text, STATED) ?? []).filter((item) => item !== "");
+/**
+* The criteria a `TODO.md` in the sketch `sketch` (the idle turn's changes)
+* added or changed under an `Acceptance criteria` heading. More than one such
+* file is ambiguous, and any other change in the sketch is input only triage
+* folds in, so none.
+*/
+const statedCriteria = (sketch, commit) => {
+	const found = sketch.flatMap((change) => {
+		if (!/(^|\/)TODO\.md$/.test(change.path) || change.after === void 0) return [];
+		const items = statedItems(change.after);
+		if (items.length === 0 || items.join("\n") === statedItems(change.before).join("\n")) return [];
+		return [{
+			path: change.path,
+			commit,
+			text: change.after,
+			criteria: numbered(items)
+		}];
+	});
+	return found.length === 1 && sketch.length === 1 ? found[0] : void 0;
+};
+const listing = (criteria) => criteria.map(criterionLine).join("\n");
+/** Refuse a turn that leaves `file` without ID'd acceptance criteria. A deleted file is `requireProgress`'s call. */
+const requireCriteria = (file) => {
+	const text = read(file);
+	if (text === void 0) return;
+	const criteria = criteriaOf(text) ?? [];
+	const unnamed = criteria.filter((c) => c.id === "");
+	const ids = criteria.map((c) => c.id).filter((id) => id !== "");
+	const twice = ids.filter((id, i) => ids.indexOf(id) !== i);
+	if (criteria.length > 0 && unnamed.length === 0 && twice.length === 0) return;
+	refuse(`gtd land: acceptance-criteria: ${file} has ${criteria.length === 0 ? `no "## Acceptance Criteria" list` : unnamed.length > 0 ? `${unnamed.length} criterion without an ID:\n${unnamed.map((c) => `  - ${c.text}`).join("\n")}` : `duplicate IDs: ${[...new Set(twice)].join(", ")}`} — list every criterion under "## Acceptance Criteria" as "- AC-<n>: <checkable criterion>", each ID unique and never reused`);
+};
+/** Refuse a turn that changed the acceptance criteria in `file`: after the design gate only another design lap may. */
+const requireCriteriaFrozen = (file) => {
+	const change = changes().get(file);
+	if (change === void 0) return;
+	if (listing(criteriaOf(change.before ?? "") ?? []) === listing(criteriaOf(change.after ?? "") ?? [])) return;
+	refuse(`gtd land: criteria-frozen: the acceptance criteria in ${file} are settled — restore them; only a design lap changes them`);
+};
+/** Whether the judge trusts `stated` as clear and checkable, every criterion of it. Truncated evidence never is. */
+const clear = async (stated) => {
+	const { answers, truncated } = await judge("clear", {
+		questions: [clearCriteriaQuestion],
+		evidence: {
+			criteria: listing(stated.criteria),
+			sketch: stated.text
+		},
+		message: clearCriteriaMessage(),
+		label: "Judging the stated acceptance criteria"
+	});
+	return truncated.length === 0 && answered(answers.clear, "yes", CLEAR_MIN_P);
+};
+/**
+* The skip path: when the sketch stated clear, checkable criteria, write them
+* to `.gtd/REQUIREMENTS.md` as they are and resolve `true` — no triage, no
+* design gate. `false` when design must run.
+*/
+const skipDesign = (stated) => stated === void 0 ? Promise.resolve(false) : scope("design", async () => {
+	if (!await clear(stated)) return false;
+	await run("normalise", normaliseCriteriaScript(stated), {
+		label: "Recording the stated acceptance criteria",
+		file: REQUIREMENTS
+	});
+	return true;
+});
+//#endregion
 //#region src/workflows/feature/tier.ts
 /** GTD_FLAG_RISK_TIER: pinned at process start, so a mid-process flip never moves a process. */
 const riskTierOn = () => vars.flag_risk_tier === "1";
@@ -37814,6 +37985,7 @@ const design = (base) => scope("design", async () => {
 		await triage(base);
 		requireProgress(REQUIREMENTS);
 		requireReplies(REQUIREMENTS);
+		requireCriteria(REQUIREMENTS);
 	} while (await noteGate(REQUIREMENTS, answerProductQuestions));
 });
 //#endregion
@@ -38308,12 +38480,16 @@ function implement(first, tier, amend) {
 			system: builderSystem(),
 			...options.afterRefactor === true ? { allowEmpty: true } : {}
 		});
+		requireCriteriaFrozen(REQUIREMENTS);
 		await healthy(() => agentWithSkills("fix.suite.fixing", implementFixPrompt(), {
 			label: "Fixing the check",
 			file: FEEDBACK,
 			model: coder(),
 			system: builderSystem()
-		}));
+		}), {
+			guard: () => requireCriteriaFrozen(REQUIREMENTS),
+			guardRests: false
+		});
 		await run("closing", removeScript([REQUIREMENTS]), { label: "Closing out the implementation" });
 	});
 }
@@ -38344,6 +38520,7 @@ const decide = () => scope("seam", async () => {
 			acceptClean: true
 		});
 		if (changes().length === 0) return { reference: tip.hash };
+		requireCriteria(REQUIREMENTS);
 		rejection = void 0;
 		retries = 0;
 	}
@@ -38400,9 +38577,9 @@ const buildFeature = async (firstBase) => {
 		}), base);
 	});
 };
-/** Design, then `buildFeature`. */
-const planAndBuild = async (firstBase) => {
-	await design(firstBase);
+/** Design — skipped when the sketch's own criteria are judged clear — then `buildFeature`. */
+const planAndBuild = async (firstBase, stated) => {
+	if (!await skipDesign(riskTierOn() ? void 0 : stated)) await design(firstBase);
 	await buildFeature(firstBase);
 };
 const featureFeedback = async (first, lensBase) => {
@@ -38432,6 +38609,7 @@ const ordinaryStart = async () => {
 	});
 	refusePendingHandOff();
 	flagModeOn();
+	const stated = statedCriteria(changes(), head$1());
 	await unwind();
 	if (changes(".gtd/FEEDBACK.md").some((c) => c.status !== "deleted")) await human("unwind-failed", {
 		message: unwindFailedMessage(),
@@ -38439,7 +38617,7 @@ const ordinaryStart = async () => {
 		file: FEEDBACK
 	});
 	await gate("start-gate", startGateBlockedMessage());
-	await planAndBuild(start());
+	await planAndBuild(start(), stated);
 };
 const feature = shipped(ordinaryStart);
 //#endregion
@@ -38625,4 +38803,4 @@ var workflows_default = feature;
 */
 const doors = {};
 //#endregion
-export { ESCALATION, FEEDBACK, FIX_CAP, FlagOptions, QUALITY, REFACTOR, REFACTOR_PACKAGE, REQUIREMENTS, REVIEW, REVIEW_ORIG, ShippedOptions, access, afterTail, agentWithSkills, answerProductQuestions, answerReviewQuestions, awaitReview, base, baseline, buildFeature, buildTail, builtInLenses, cleanup, cleanupFlow, closeReview, coder, collecting, workflows_default as default, defaults, deferNotes, describeEscalation, design, doors, envDefaults, escalate, escalation, escalationExhausted, feature, fix, fixCheck, fixFlow, fixNits, fixQuality, fixQualityFindings, fixReviewNotes, fixRisks, gate, guarded, handOffReview, handOffTail, healthy, implement, judgeSeam, lensesOf, naivePass, ordinaryStart, planAndBuild, planner, qualityLap, reUnwind, refactorCollecting, refactorFirst, refactorStrays, requireNoNewFlags, requireNoTestFiles, requireTestCallSitesOnly, requireWithin, retryQuestion, review, reviewFlow, reviewMissing, reviewQuality, reviewedRefactor, reviewing, rollout, rolloutFlow, seamBuild, skills, steering, summary, tail, threads, triage, unwind };
+export { ESCALATION, FEEDBACK, FIX_CAP, FlagOptions, QUALITY, REFACTOR, REFACTOR_PACKAGE, REQUIREMENTS, REVIEW, REVIEW_ORIG, ShippedOptions, access, afterTail, agentWithSkills, answerProductQuestions, answerReviewQuestions, awaitReview, base, baseline, buildFeature, buildTail, builtInLenses, cleanup, cleanupFlow, closeReview, coder, collecting, criteriaOf, workflows_default as default, defaults, deferNotes, describeEscalation, design, doors, envDefaults, escalate, escalation, escalationExhausted, feature, fix, fixCheck, fixFlow, fixNits, fixQuality, fixQualityFindings, fixReviewNotes, fixRisks, gate, guarded, handOffReview, handOffTail, healthy, implement, judgeSeam, lensesOf, naivePass, ordinaryStart, planAndBuild, planner, qualityLap, reUnwind, refactorCollecting, refactorFirst, refactorStrays, requireCriteria, requireCriteriaFrozen, requireNoNewFlags, requireNoTestFiles, requireTestCallSitesOnly, requireWithin, retryQuestion, review, reviewFlow, reviewMissing, reviewQuality, reviewedRefactor, reviewing, rollout, rolloutFlow, seamBuild, skills, skipDesign, statedCriteria, steering, summary, tail, threads, triage, unwind };

package/package.json

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

package/src/workflows/feature/acceptance-criteria-tier.feature

@@ -0,0 +1,25 @@
+@inmem
+Feature: with GTD_FLAG_RISK_TIER on, stated acceptance criteria never skip design
+
+  The risk tier is proposed at `design.triage` and set at the design gate, so
+  with the flag on a sketch that states its own criteria still runs triage and
+  is never judged at `design.clear`.
+
+  Scenario: stated criteria go through triage, where the tier is proposed and set
+    Given the shipped workflows, as gtd install scaffolds them
+    And an environment variable "GTD_QUALITYREVIEWS" set to ""
+    And an environment variable "GTD_FLAG_RISK_TIER" set to "1"
+    And step "unwind" changes nothing
+    And step "start-gate.check" changes nothing
+    And a file "TODO.md" with:
+      """
+      ## Acceptance criteria
+
+      - `greeting` reads "Hello, world".
+      """
+    When the process is driven
+    Then the process rests at "design.triage"
+    And the commit subjects end with:
+      """
+      gtd(check): start-gate.check → design.triage
+      """

package/src/workflows/feature/acceptance-criteria.feature

@@ -0,0 +1,189 @@
+@inmem
+Feature: acceptance criteria carry stable IDs, and a sketch that states clear ones skips design
+
+  `.gtd/REQUIREMENTS.md` lists the change's acceptance criteria as
+  `- AC-<n>: …` under `## Acceptance Criteria`. On the full path
+  `design.triage` writes them and the design gate settles them; a sketch
+  that already states its criteria under an `Acceptance criteria` heading
+  is judged at `design.clear`, and a `yes` records them as they are — no
+  triage, no design gate. After design they are frozen.
+
+  Background:
+    Given the shipped workflows, as gtd install scaffolds them
+    And an environment variable "GTD_QUALITYREVIEWS" set to ""
+    And an environment variable "GTD_FLAG_RISK_TIER" set to "0"
+    And a file "src/greeting.ts" with:
+      """
+      export const greeting = "Helo, world"
+      """
+    And the working tree is committed as "feat: add greeting"
+    And step "unwind" changes nothing
+    And step "start-gate.check" changes nothing
+
+  Rule: the full path
+
+    Background:
+      Given a file "TODO.md" with:
+        """
+        # Fix the typo
+
+        greeting says "Helo"; make it "Hello".
+        """
+
+    Scenario: triage writes ID'd criteria that reach the naive pass through the design gate
+      Given step "design.triage" writes ".gtd/REQUIREMENTS.md" with:
+        """
+        # Requirements
+
+        ## Acceptance Criteria
+
+        - AC-1: `greeting` reads "Hello, world".
+        - AC-2: no other export changes.
+        """
+      And step "design.gate.answer" changes nothing
+      When the process is driven
+      Then the process rests at "seam.naive"
+      And ".gtd/REQUIREMENTS.md" contains "- AC-1: `greeting` reads \"Hello, world\"."
+      And ".gtd/REQUIREMENTS.md" contains "- AC-2: no other export changes."
+      And the resting step's content contains "Acceptance Criteria"
+      And the commit subjects end with:
+        """
+        gtd(check): start-gate.check → design.triage
+        gtd(agent): design.triage → design.gate.answer
+        gtd(human): design.gate.answer → seam.naive
+        """
+
+    Scenario: a triage turn whose criteria carry no ID is refused
+      Given step "design.triage" writes ".gtd/REQUIREMENTS.md" with:
+        """
+        # Requirements
+
+        ## Acceptance Criteria
+
+        - `greeting` reads "Hello, world".
+        """
+      Then driving the process is refused with "acceptance-criteria: .gtd/REQUIREMENTS.md has 1 criterion without an ID"
+
+    Scenario: a triage turn reusing an ID is refused
+      Given step "design.triage" writes ".gtd/REQUIREMENTS.md" with:
+        """
+        # Requirements
+
+        ## Acceptance Criteria
+
+        - AC-1: `greeting` reads "Hello, world".
+        - AC-1: no other export changes.
+        """
+      Then driving the process is refused with "duplicate IDs: AC-1"
+
+    Scenario: an implementation turn that edits the settled criteria is refused
+      Given step "design.triage" writes ".gtd/REQUIREMENTS.md" with:
+        """
+        # Requirements
+
+        ## Acceptance Criteria
+
+        - AC-1: `greeting` reads "Hello, world".
+        """
+      And step "design.gate.answer" changes nothing
+      And step "seam.naive" writes "src/greeting.ts" with:
+        """
+        export const greeting = "Hello, world"
+        """
+      And judge step "seam.judge" answers:
+        """
+        [{"id":"shape","answer":"land","p":0.9}]
+        """
+      And step "implement.building" writes ".gtd/REQUIREMENTS.md" with:
+        """
+        # Requirements
+
+        ## Acceptance Criteria
+
+        - AC-1: `greeting` reads "Hi".
+        """
+      Then driving the process is refused with "criteria-frozen"
+
+  Rule: the skip path
+
+    Scenario: clear stated criteria are normalised into ID'd requirements with no triage and no design gate
+      Given a file "TODO.md" with:
+        """
+        # Fix the typo
+
+        ## Acceptance criteria
+
+        - [ ] `greeting` reads "Hello, world".
+        - [ ] no other export changes.
+        """
+      And judge step "design.clear" answers:
+        """
+        [{"id":"clear","answer":"yes","p":0.9}]
+        """
+      And step "design.normalise" runs its script
+      When the process is driven
+      Then the process rests at "seam.naive"
+      And ".gtd/REQUIREMENTS.md" contains "- AC-1: `greeting` reads \"Hello, world\"."
+      And ".gtd/REQUIREMENTS.md" contains "- AC-2: no other export changes."
+      And the commit subjects end with:
+        """
+        gtd(human): idle → unwind
+        gtd(check): unwind → start-gate.check
+        gtd(check): start-gate.check → design.clear
+        gtd(judge): design.clear → design.normalise
+        gtd(check): design.normalise → seam.naive
+        """
+
+    Scenario: IDs the sketch already gave its criteria are kept
+      Given a file "TODO.md" with:
+        """
+        ## Acceptance criteria
+
+        1. AC-3: `greeting` reads "Hello, world".
+        2. AC-7: no other export changes.
+        """
+      And judge step "design.clear" answers:
+        """
+        [{"id":"clear","answer":"yes","p":0.9}]
+        """
+      And step "design.normalise" runs its script
+      When the process is driven
+      Then the process rests at "seam.naive"
+      And ".gtd/REQUIREMENTS.md" contains "- AC-3: `greeting` reads \"Hello, world\"."
+      And ".gtd/REQUIREMENTS.md" contains "- AC-7: no other export changes."
+
+    Scenario: one criterion the judge finds uncheckable falls back to the full path
+      Given a file "TODO.md" with:
+        """
+        # Fix the typo
+
+        ## Acceptance criteria
+
+        - `greeting` reads "Hello, world".
+        - the greeting feels friendlier.
+        """
+      And judge step "design.clear" answers:
+        """
+        [{"id":"clear","answer":"no","p":0.9}]
+        """
+      When the process is driven
+      Then the process rests at "design.triage"
+      And the commit subjects end with:
+        """
+        gtd(check): start-gate.check → design.clear
+        gtd(judge): design.clear → design.triage
+        """
+
+    Scenario: a sketch with no criteria heading goes straight to triage, unjudged
+      Given a file "TODO.md" with:
+        """
+        # Fix the typo
+
+        - `greeting` reads "Hello, world".
+        """
+      When the process is driven
+      Then the process rests at "design.triage"
+      And the commit subjects end with:
+        """
+        gtd(check): start-gate.check → design.triage
+        """

package/src/workflows/feature/criteria.test.ts

@@ -0,0 +1,106 @@
+import { describe, expect, it } from "vitest"
+import type { Change } from "../../flows/index.js"
+import { criteriaOf, statedCriteria } from "./criteria.js"
+
+const added = (path: string, after: string): Change => ({
+  path,
+  status: "added",
+  before: undefined,
+  after,
+})
+
+describe("criteriaOf", () => {
+  it("reads ID'd items, joining wrapped lines, and stops at the next section", () => {
+    expect(
+      criteriaOf(
+        "# R\n\n## Acceptance Criteria\n\n- AC-1: one\n  continued\n- two\n\n## Notes\n\n- AC-9: not one\n",
+      ),
+    ).toEqual([
+      { id: "AC-1", text: "one continued" },
+      { id: "", text: "two" },
+    ])
+  })
+
+  it("skips fenced lines, reads an indented item, and stops at a subheading", () => {
+    expect(
+      criteriaOf(
+        "## Acceptance Criteria\n\n- AC-1: runs\n\n```sh\n# setup\n- key: v\n```\n - AC-2: two\n\n### Notes\n\n- note\n",
+      ),
+    ).toEqual([
+      { id: "AC-1", text: "runs" },
+      { id: "AC-2", text: "two" },
+    ])
+  })
+
+  it("reads only the level-2 section and joins an unindented wrapped line", () => {
+    expect(
+      criteriaOf(
+        "### Acceptance criteria\n\n- x\n\n## Acceptance Criteria\n\n- AC-1: exits 2 when the config\nfile is missing\n",
+      ),
+    ).toEqual([{ id: "AC-1", text: "exits 2 when the config file is missing" }])
+  })
+
+  it("folds a nested sub-bullet into its criterion", () => {
+    expect(
+      criteriaOf(
+        "## Acceptance Criteria\n\n- AC-1: exits 2 when config is bad\n  - missing file\n",
+      ),
+    ).toEqual([{ id: "AC-1", text: "exits 2 when config is bad - missing file" }])
+  })
+
+  it("is undefined without the section", () => {
+    expect(criteriaOf("# R\n\n- AC-1: x\n")).toBeUndefined()
+  })
+})
+
+describe("statedCriteria", () => {
+  it("numbers a stated checklist from AC-1", () => {
+    const sketch = [added("TODO.md", "# T\n\n### Acceptance criteria:\n\n- [ ] a\n* b\n\nprose\n")]
+    expect(statedCriteria(sketch, "abc")).toMatchObject({
+      path: "TODO.md",
+      commit: "abc",
+      criteria: [
+        { id: "AC-1", text: "a" },
+        { id: "AC-2", text: "b" },
+      ],
+    })
+  })
+
+  it("renumbers when the stated IDs are partial or clash", () => {
+    const sketch = [added("TODO.md", "## Acceptance criteria\n\n- AC-4: a\n- b\n")]
+    expect(statedCriteria(sketch, "abc")?.criteria).toEqual([
+      { id: "AC-1", text: "a" },
+      { id: "AC-2", text: "b" },
+    ])
+  })
+
+  it("ignores a list the sketch left unchanged, a file other than TODO.md, a sketch with more in it, and an ambiguous pair", () => {
+    const list = "## Acceptance criteria\n\n- a\n"
+    expect(
+      statedCriteria(
+        [{ path: "TODO.md", status: "modified", before: list, after: `${list}\nmore\n` }],
+        "abc",
+      ),
+    ).toBeUndefined()
+    expect(
+      statedCriteria(
+        [
+          {
+            path: "TODO.md",
+            status: "modified",
+            before: `${list}- \n`,
+            after: `${list}- \n\nmore\n`,
+          },
+        ],
+        "abc",
+      ),
+    ).toBeUndefined()
+    expect(statedCriteria([added("docs/guide.md", list)], "abc")).toBeUndefined()
+    expect(
+      statedCriteria([added("TODO.md", list), added("src/a.ts", "x\n")], "abc"),
+    ).toBeUndefined()
+    expect(
+      statedCriteria([added("TODO.md", list), added(".gtd/TODO.md", list)], "abc"),
+    ).toBeUndefined()
+  })
+})