@pmelab/gtd 29.1.0 → 29.2.0

package/dist/workflows.mjs

@@ -17475,7 +17475,12 @@ ${stateFileRules}
 - Every package with tests has a \`## Tests\` section, one line per
   declared test, copied from the architecture entries:
   \`- unit: \\\`<path>\\\`\` or \`- e2e: \\\`<path>\\\`\`. Chore packages have
-  none
+  none. List every test the package writes or changes; also list an
+  existing test a criterion relies on, marked \`(unchanged)\` —
+  \`- unit: \\\`<path>\\\` (unchanged)\` or
+  \`- e2e: \\\`<path>\\\` (unchanged)\`; list no other untouched test;
+  never mark a file the package also writes or changes — list it once,
+  unmarked; only decompose places the marker
 - Leave everything uncommitted and finish
 `;
 const architectureGateAnswerMessage = () => `This gate stops on every process, even with no open question, so
@@ -17508,15 +17513,26 @@ const packagesItemBuildingPrompt = (pkg) => `${stateFileRules}
   never delete the package file (the declared-tests guard reads it
   after you)
 - The package to implement is \`${pkg}\`
-- First check its acceptance criteria against the current tree —
-  an earlier fix turn may already satisfy them. If **every**
-  criterion is met, implement nothing: write \`.gtd/SATISFIED.md\`
-  with each criterion's concrete evidence (commit, file, or
-  symbol), change nothing else, and finish. Otherwise implement
-  normally and skip that file
+- First check the acceptance criteria against the current tree —
+  an earlier fix turn may already meet them
+- **Every criterion already met in the tree**: write
+  \`.gtd/SATISFIED.md\` with evidence per criterion — commit, file,
+  symbol, issue URL, or command output — and change nothing else
+- **No \`## Tests\` and work outside the tree**: first check it was
+  not already done by an earlier attempt (e.g. an existing issue
+  with the same title via \`gh\`) and reuse that as evidence, or do
+  the work; then write \`.gtd/SATISFIED.md\` with that evidence and
+  change nothing else in the tree
+- **Any other package**: implement normally, write no
+  \`.gtd/SATISFIED.md\`
 - Write the tests the package declares under \`## Tests\` first,
   then the code that makes them pass; the turn is refused unless
-  every declared test is in your diff
+  every declared test is in your diff — except a line marked
+  \`(unchanged)\`, which must exist before the turn and stay
+  untouched — creating, editing or deleting it refuses the turn. If
+  it does not exist yet, or the marker is wrong because the package
+  must change that test, stop without creating it and leave it to
+  a person
 - A declared e2e test is a scenario in the repository's own e2e
   framework for the behaviour its \`## E2E Scenarios\` entry names.
   Word it to fit the existing steps — reuse and generalise them
@@ -17544,7 +17560,7 @@ ${strays.map((path) => `  - \`${displayPath(path)}\``).join("\n")}
 - Introduce no new flag read and add no second read of an existing one:
   every match of \`${pattern}\` may move, never increase in number`;
 const withRules = (rules) => rules === void 0 ? "" : `${rules}\n`;
-const refactorBuildingPrompt = (pkg, strays, pattern, reference, feedback = false) => `${stateFileRules}
+const refactorBuildingPrompt = ({ pkg, strays, pattern, reference, feedback = false }) => `${stateFileRules}
 - The package to implement is \`${pkg}\`; never delete it
 ${feedback ? `- The package carries a \`## Review feedback\` section: a human's review of the
   last refactor. Act on it, within the rules below
@@ -37955,34 +37971,86 @@ const deferNotes = (notes, round) => run("review.defer", deferNotesScript(notes,
 });
 //#endregion
 //#region src/workflows/feature/packages.ts
-const TEST_LINE = /^\s*-\s+(unit|e2e):\s+`([^`]+)`/;
-/** The `## Tests` entries of a package file; malformed lines are ignored. */
+const TEST_LINE = /^-\s+(unit|e2e):\s+`([^`]+)`(.*)$/;
+const MARKER = /^[ \t]+\(unchanged\)(?=\s|$)/i;
+const ITEM = /^\s*-\s/;
+/** The `## Tests` entries of a package file; malformed entries are ignored. */
 const declaredTests = (packageText) => {
 	const found = [];
 	let inTests = false;
-	for (const line of packageText.split("\n")) if (/^##\s/.test(line)) inTests = /^##\s+Tests\s*$/.test(line);
-	else if (inTests) {
-		const match = TEST_LINE.exec(line);
+	let entry;
+	const flush = () => {
+		const match = entry === void 0 ? null : TEST_LINE.exec(entry);
 		if (match) found.push({
 			level: match[1],
-			path: match[2]
+			path: match[2],
+			unchanged: MARKER.test(match[3])
 		});
-	}
+		entry = void 0;
+	};
+	for (const line of packageText.replace(/\r\n?/g, "\n").split("\n")) if (/^##\s/.test(line)) {
+		flush();
+		inTests = /^##\s+Tests\s*$/.test(line);
+	} else if (!inTests) continue;
+	else if (ITEM.test(line)) {
+		flush();
+		entry = line.trim();
+	} else if (entry !== void 0 && /^\s/.test(line) && line.trim() !== "") entry = `${entry} ${line.trim()}`;
+	else flush();
+	flush();
 	return found;
 };
+const diffBucket = (test, status, turn, satisfied) => {
+	if (test.unchanged) {
+		if (turn !== "build") return void 0;
+		if (status === "modified") return "modifiedMarked";
+		return status === "added" ? "addedMarked" : void 0;
+	}
+	return !satisfied && (status === void 0 || status === "deleted") ? "notInDiff" : void 0;
+};
+const treeBucket = (test, status) => {
+	if (read(test.path) !== void 0) return void 0;
+	return test.unchanged && status === "deleted" ? "deletedMarked" : "notInTree";
+};
+const unmetBucket = (test, change, turn, satisfied) => diffBucket(test, change?.status, turn, satisfied) ?? treeBucket(test, change?.status);
 /**
 * Refuse a build or fix turn unless every test `pkg` declares exists and is in the
 * diff since `since`. The package text is read as of `since`, so a builder
-* editing its own `## Tests` cannot dodge the guard; with `.gtd/SATISFIED.md`
-* written, existing in the tree suffices.
+* editing its own `## Tests` (or adding `(unchanged)`) cannot dodge the guard;
+* with `.gtd/SATISFIED.md` written, or the line marked, existing suffices. The
+* build turn must neither modify nor add a marked test; a fix turn may edit it.
 */
-const requireDeclaredTests = (pkg, since) => {
+const requireDeclaredTests = (pkg, since, turn = "fix") => {
 	const range = changesSince(since);
 	const text = range.get(pkg)?.before ?? read(pkg) ?? "";
 	const satisfied = read(".gtd/SATISFIED.md") !== void 0;
-	const missing = declaredTests(text).map((test) => test.path).filter((path) => satisfied ? read(path) === void 0 : range.get(path) === void 0 || range.get(path)?.status === "deleted" || read(path) === void 0);
-	if (missing.length === 0) return;
-	refuse(`gtd land: declared-tests: ${pkg} declares tests that are ${satisfied ? "missing from the tree" : "not in the package's diff"} — write them first:\n${missing.map((path) => `  - ${path}`).join("\n")}`);
+	const buckets = {
+		notInDiff: [],
+		modifiedMarked: [],
+		addedMarked: [],
+		deletedMarked: [],
+		notInTree: []
+	};
+	const entries = declaredTests(text);
+	const seen = /* @__PURE__ */ new Set();
+	for (const test of entries) {
+		if (test.unchanged && entries.some((e) => !e.unchanged && e.path === test.path)) continue;
+		const bucket = unmetBucket(test, range.get(test.path), turn, satisfied);
+		if (bucket && !seen.has(test.path)) {
+			seen.add(test.path);
+			buckets[bucket].push(test.path);
+		}
+	}
+	const { notInDiff, modifiedMarked, addedMarked, deletedMarked, notInTree } = buckets;
+	const reasons = [
+		["not in the package's diff — write them", notInDiff],
+		["marked (unchanged) but modified — revert them", modifiedMarked],
+		["marked (unchanged) but added by this turn — the marker promises an existing test; stop and leave it to a person", addedMarked],
+		["marked (unchanged) but deleted — restore them", deletedMarked],
+		["missing from the tree", notInTree]
+	].filter(([, paths]) => paths.length > 0);
+	if (reasons.length === 0) return;
+	refuse(`gtd land: declared-tests: ${pkg} declares tests this turn left unmet:\n${reasons.map(([reason, paths]) => `${reason}:\n${paths.map((path) => `  - ${path}`).join("\n")}`).join("\n")}`);
 };
 /**
 * Build `pkg`, check its declared tests, keep the full suite green, and close
@@ -37990,12 +38058,12 @@ const requireDeclaredTests = (pkg, since) => {
 */
 const packageItem = async (pkg) => {
 	const from = head$1();
-	const declared = (turn) => async () => {
+	const declared = (turn, kind) => async () => {
 		await turn();
-		requireDeclaredTests(pkg, from);
+		requireDeclaredTests(pkg, from, kind);
 	};
-	await declared(() => build(pkg))();
-	await healthy(declared(fixSuite));
+	await declared(() => build(pkg), "build")();
+	await healthy(declared(fixSuite, "fix"));
 	await run("closing", removeScript([
 		pkg,
 		".gtd/SATISFIED.md",
@@ -38230,8 +38298,16 @@ const review$1 = (base, escalations = { rounds: 0 }, options = {}) => {
 		}
 	});
 };
-/** The build tail: fix (when entered red), keep green unless `green`, the quality lap, then human review since `base`. */
-const buildTail = (fixFirst, base, green = false, options = {}) => tail(fixFirst, (escalations) => review$1(base, escalations, options), green, options.guard, options.lenses, options.guardRests, options.lensBase, options.rules);
+function buildTail(first, second, third = false, fourth = {}) {
+	if (typeof first !== "string" && typeof first !== "boolean" && typeof second !== "string") return Promise.reject(/* @__PURE__ */ new Error("buildTail takes buildTail(base, options?) or the deprecated buildTail(fixFirst, base, green?, options?); this call fits neither"));
+	const [base, options] = typeof first === "string" ? [first, second ?? {}] : [second, {
+		...fourth,
+		fixFirst: first,
+		green: third
+	}];
+	const { fixFirst, green, ...reviewOptions } = options;
+	return tail(fixFirst ?? false, (escalations) => review$1(base, escalations, reviewOptions), green ?? false, options.guard, options.lenses, options.guardRests, options.lensBase, options.rules);
+}
 /**
 * Undo the human's review-round code edits. A path changed since the human
 * left it is not overwritten; requireRevert names it instead.
@@ -38372,7 +38448,13 @@ const refactorLap = async (p, guard, feedback) => {
 		label: "Deriving the refactor package",
 		file: REFACTOR_PACKAGE
 	});
-	await agentWithSkills("building", refactorBuildingPrompt(REFACTOR_PACKAGE, strays, pattern, reference, feedback !== void 0), {
+	await agentWithSkills("building", refactorBuildingPrompt({
+		pkg: REFACTOR_PACKAGE,
+		strays,
+		pattern,
+		reference,
+		feedback: feedback !== void 0
+	}), {
 		label: "Refactoring",
 		model: coder(),
 		system: builderSystem()
@@ -38428,7 +38510,8 @@ const reviewedRefactor = async (shape, options = {}) => {
 		let collected;
 		for (;;) {
 			await refactorLap(p, guard, collected);
-			const outcome = await buildTail(false, entry, true, {
+			const outcome = await buildTail(entry, {
+				green: true,
 				guard,
 				guardRests: false,
 				lenses: lensesOf(vars.refactorQualityReviews ?? ""),
@@ -38461,20 +38544,27 @@ const naivePass = (rejection) => agentWithSkills("naive", naivePassPrompt(reject
 	model: coder(),
 	system: builderSystem()
 });
-const implement = (reference, tier, amend) => scope("implement", async () => {
-	await agentWithSkills("building", implementBuildingPrompt(reference, tier, amend), {
-		label: "Implementing",
-		model: coder(),
-		system: builderSystem()
+function implement(first, tier, amend) {
+	const options = typeof first === "object" && first !== null ? first : {
+		reference: first,
+		tier,
+		amend
+	};
+	return scope("implement", async () => {
+		await agentWithSkills("building", implementBuildingPrompt(options.reference, options.tier, options.amend), {
+			label: "Implementing",
+			model: coder(),
+			system: builderSystem()
+		});
+		await healthy(() => agentWithSkills("fix.suite.fixing", implementFixPrompt(), {
+			label: "Fixing the check",
+			file: FEEDBACK,
+			model: coder(),
+			system: builderSystem()
+		}));
+		await run("closing", removeScript([REQUIREMENTS]), { label: "Closing out the implementation" });
 	});
-	await healthy(() => agentWithSkills("fix.suite.fixing", implementFixPrompt(), {
-		label: "Fixing the check",
-		file: FEEDBACK,
-		model: coder(),
-		system: builderSystem()
-	}));
-	await run("closing", removeScript([REQUIREMENTS]), { label: "Closing out the implementation" });
-});
+}
 const decide = () => scope("seam", async () => {
 	let rejection;
 	let retries = 0;
@@ -38549,7 +38639,10 @@ const planAndBuild = async (firstBase, firstLap = "first") => {
 		await design(base);
 		await architecture();
 		await packages();
-		const outcome = await buildTail(false, base, true, lap === "first" ? {} : { lap });
+		const outcome = await buildTail(base, {
+			green: true,
+			...lap === "first" ? {} : { lap }
+		});
 		if (outcome.verdict === "signoff") return;
 		await reUnwind(outcome);
 		base = outcome.base;
@@ -38561,8 +38654,14 @@ const naivePlanAndBuild = async (firstBase) => {
 	const tier = riskTierOn() ? recordRisk() : void 0;
 	const seam = await seamBuild(firstBase);
 	await slice("feature", async () => {
-		await implement(seam.reference, tier);
-		await featureFeedback(await buildTail(false, seam.base, true, { lensBase: seam.base }), seam.base);
+		await implement({
+			reference: seam.reference,
+			tier
+		});
+		await featureFeedback(await buildTail(seam.base, {
+			green: true,
+			lensBase: seam.base
+		}), seam.base);
 	});
 };
 const featureFeedback = async (first, lensBase) => {
@@ -38570,8 +38669,12 @@ const featureFeedback = async (first, lensBase) => {
 	while (outcome.verdict === "feedback") {
 		await reUnwind(outcome);
 		await design(outcome.base);
-		await implement(void 0, riskTierOn() ? recordRisk() : void 0, true);
-		outcome = await buildTail(false, outcome.base, true, {
+		await implement({
+			tier: riskTierOn() ? recordRisk() : void 0,
+			amend: true
+		});
+		outcome = await buildTail(outcome.base, {
+			green: true,
 			lap: "feedback",
 			...lensBase === void 0 ? {} : { lensBase }
 		});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmelab/gtd",
-  "version": "29.1.0",
+  "version": "29.2.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/skills/authoring/SKILL.md

@@ -56,7 +56,7 @@ export {
 export default feature
 
 export async function hotfix() {
-  return afterTail(await buildTail(true, start()))
+  return afterTail(await buildTail(start(), { fixFirst: true }))
 }
 
 export const doors = { hotfix: { workflow: "hotfix" } }
@@ -227,9 +227,11 @@ pass (which writes `.gtd/packages/`), then builds the packages. Add a human
 sign-off between the two:
 
 ```ts
-const planAndBuild = async (): Promise<void> => {
+const planAndBuild = async (firstBase: string): Promise<void> => {
+  let base = firstBase
+  let lap: "first" | "feedback" = "first"
   for (;;) {
-    await design()
+    await design(base)
     await architecture()
     await human("approve-plan", {
       message:
@@ -238,8 +240,14 @@ const planAndBuild = async (): Promise<void> => {
       acceptClean: true,
     })
     await packages()
-    if ((await buildTail(false)) === "signoff") return
-    await reUnwind()
+    const outcome = await buildTail(base, {
+      green: true,
+      ...(lap === "first" ? {} : { lap }),
+    })
+    if (outcome.verdict === "signoff") return
+    await reUnwind(outcome)
+    base = outcome.base
+    lap = "feedback"
   }
 }
 ```

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

@@ -131,7 +131,7 @@ describe("afterTail feedback lap", () => {
     `export { feature as default, defaults, envDefaults, summary, base, steering, skills, access } from "@pmelab/gtd/workflows"`,
     `export async function tail() {`,
     `  await gate("review-gate", "The baseline is red.")`,
-    `  return afterTail(await buildTail(false, start()))`,
+    `  return afterTail(await buildTail(start()))`,
     `}`,
   ].join("\n")
 

package/src/workflows/feature/feature.ts

@@ -39,7 +39,7 @@ export const planAndBuild = async (
     await design(base)
     await architecture()
     await packages()
-    const outcome = await buildTail(false, base, true, lap === "first" ? {} : { lap })
+    const outcome = await buildTail(base, { green: true, ...(lap === "first" ? {} : { lap }) })
     if (outcome.verdict === "signoff") return
     await reUnwind(outcome)
     base = outcome.base
@@ -54,9 +54,9 @@ const naivePlanAndBuild = async (firstBase: string): Promise<void> => {
   const tier = riskTierOn() ? recordRisk() : undefined
   const seam = await seamBuild(firstBase)
   await slice("feature", async () => {
-    await implement(seam.reference, tier)
+    await implement({ reference: seam.reference, tier })
     await featureFeedback(
-      await buildTail(false, seam.base, true, { lensBase: seam.base }),
+      await buildTail(seam.base, { green: true, lensBase: seam.base }),
       seam.base,
     )
   })
@@ -68,8 +68,9 @@ const featureFeedback = async (first: ReviewOutcome, lensBase?: string): Promise
     await reUnwind(outcome)
     await design(outcome.base)
     const tier = riskTierOn() ? recordRisk() : undefined
-    await implement(undefined, tier, true)
-    outcome = await buildTail(false, outcome.base, true, {
+    await implement({ tier, amend: true })
+    outcome = await buildTail(outcome.base, {
+      green: true,
       lap: "feedback",
       ...(lensBase === undefined ? {} : { lensBase }),
     })

package/src/workflows/feature/index.ts

@@ -5,7 +5,7 @@ export * from "./planning.js"
 export * from "./packages.js"
 export * from "./refactor.js"
 export * from "./seam.js"
-export { buildTail, type ReviewOutcome } from "./review.js"
+export { buildTail, type BuildTailOptions, type ReviewOutcome } from "./review.js"
 export * from "./feature.js"
 export * from "../shared/reserved.js"