@pmelab/gtd 35.0.0 → 37.0.0

package/dist/workflows.mjs

@@ -214,25 +214,21 @@ const checkScript = (command, options) => {
 		""
 	].join("\n");
 };
-/**
-* Reverse-apply `commit`'s changes to the working tree. A failure — the
-* patch no longer applies — writes `failure` and git's error to `report`,
-* since a failed revert and one with nothing to undo both leave the tree clean.
-*/
-const revertScript = (commit, report, failure) => {
+const patchScript = (commit, report, failure, reverse, exclude = []) => {
+	const paths = exclude.length === 0 ? "" : ` . ${exclude.map((p) => quote(`:(exclude,literal)${p}`)).join(" ")}`;
 	const range = `${quote(`${commit}^`)} ${quote(commit)}`;
 	const error = quote(`${report}.output`);
 	return [
 		"#!/usr/bin/env sh",
 		"set +e",
-		`if ! git diff --quiet ${range} --; then`,
+		`if ! git diff --quiet ${range} --${paths}; then`,
 		`  mkdir -p "$(dirname ${quote(report)})"`,
-		`  git diff --binary ${range} -- | git apply -R 2> ${error}`,
+		`  git diff --binary --no-color --no-ext-diff --no-textconv --src-prefix=a/ --dst-prefix=b/ ${range} --${paths} | git apply --whitespace=nowarn${reverse ? " -R" : ""} 2> ${error}`,
 		"  code=$?",
 		"  if [ \"$code\" -ne 0 ]; then",
 		"    {",
 		`      printf '%s\\n\\n' ${quote(failure)}`,
-		`      if [ -s ${error} ]; then cat ${error}; else printf 'Reverting it exited %s and produced no output.\\n' "$code"; fi`,
+		`      if [ -s ${error} ]; then cat ${error}; else printf '${reverse ? "Reverting" : "Applying"} it exited %s and produced no output.\\n' "$code"; fi`,
 		`    } > ${quote(report)}`,
 		"  fi",
 		`  rm -f ${error}`,
@@ -241,6 +237,14 @@ const revertScript = (commit, report, failure) => {
 	].join("\n");
 };
 /**
+* Reverse-apply `commit`'s changes to the working tree. A failure — the
+* patch no longer applies — writes `failure` and git's error to `report`,
+* since a failed revert and one with nothing to undo both leave the tree clean.
+*/
+const revertScript = (commit, report, failure) => patchScript(commit, report, failure, true);
+/** Apply `commit`'s changes outside `exclude` to the working tree; a failure is reported as `revertScript`'s is. */
+const applyScript = (commit, report, failure, exclude = []) => patchScript(commit, report, failure, false, exclude);
+/**
 * Undo the edits one commit made to `paths`: each goes back to its content
 * before `commit` — or away, when `commit` added it — but only while it is
 * still exactly as `commit` left it. A path changed since is left alone.
@@ -17188,6 +17192,7 @@ const agentWithSkills = (name, prompt, options = {}) => {
 	return agent(name, withSkills(skillsFor(name).join(", "), body), options);
 };
 const unwindFailure = (commit) => `gtd could not unwind ${commit} out of your working tree.`;
+const naiveApplyFailure = (commit) => `gtd could not apply the naive pass ${commit} to the working tree; it is built fresh instead.`;
 const idleMessage = () => `No active gtd process.
 
 To start one, make ANY change — a hand-edit to real code, a scratch
@@ -17431,9 +17436,11 @@ ${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, note = 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
+${note ? `- The package's \`## Refactor note\` section names the seams to open and the
+  shape each takes, written from the whole naive pass: build exactly those
+` : ""}${feedback ? `- The package carries a \`## Review feedback\` section: a human's review of the
   last refactor. Act on it, within the rules below
 ` : ""}${refactorRules(strays, pattern)}
 ${reference === void 0 ? "" : `- Reference only: \`git show ${reference} -- ${strays.map(quote).join(" ")}\` shows an
@@ -18036,8 +18043,8 @@ const naivePassPrompt = (retry) => `${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
+  restructure, abstract or refactor around the change; it may land exactly as
+  you leave it, and a reviewer makes it fit
 - Work breadth-first: rough out every part of the change before finishing any
   one, so a run cut off midway still shows the whole shape
 - Write behaviour-level acceptance tests, at least one per criterion, each
@@ -18052,21 +18059,50 @@ ${criteriaBinding(false)}
 - Leave \`.gtd/\` untouched
 - Leave everything uncommitted and finish your turn — do not commit
 ${retry === void 0 ? "" : naiveRetry(retry)}`;
-const implementBuildingPrompt = (reference, tier, amend, afterRefactor, flagMode = true) => `${stateFileRules}
+const carries = (rebuild) => (rebuild.acceptance?.ids.length ?? 0) > 0;
+const rebuildLines = ({ note, acceptance }) => `${note === void 0 ? "" : `- The refactor note (\`.gtd/REFACTOR-NOTE.md\`) named the seams the refactor
+  opened; plug the change into them:
+
+${note.trimEnd().split("\n").map((line) => line === "" ? "" : `  > ${line}`).join("\n")}
+
+`}${acceptance === void 0 || !carries({ acceptance }) ? "" : `- Carry over the naive pass's acceptance tests for ${acceptance.ids.join(", ")}, the
+  one part of it you take as it is: \`git show ${acceptance.hash} -- ${acceptance.tests.map(quote).join(" ")}\`.
+  Copy each test with its \`[AC-<n>]\` name into the tree as the refactor left
+  it — check a file out of the tip whole only where the refactor did not touch
+  it — changing only what reaches the release flag. A turn whose changed tests
+  leave an ID out is refused, and the suite must be green with them
+`}`;
+const refactorNotePrompt = (reference, strays) => `${stateFileRules}
+- The seam judge ruled the naive pass refactor-first: it is never applied.
+  A behaviour-neutral refactor lands first, then the change is rebuilt on
+  the refactored base. Both turns read the note you write
+- Read the whole naive pass: \`git show ${reference}\`. It changed these
+  existing files outside the allowlist:
+${listed(strays)}
+- Write \`.gtd/REFACTOR-NOTE.md\`: which seams the refactor opens (the existing
+  code to restructure, by path and symbol) and the shape each takes — the
+  signatures and where the new behaviour will plug in. Name only the files
+  listed above: the refactor may change no other path. Never the feature's own
+  behaviour, and no flag read: the refactor adds neither
+- Change nothing else — a turn that does is refused
+- Leave everything uncommitted and finish your turn — do not commit
+`;
+const afterRefactorLine = (rebuild) => `- 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, ${carries(rebuild) ? "carry over the acceptance tests below and change nothing else" : "change nothing and finish your turn"}
+`;
+const implementBuildingPrompt = (reference, tier, amend, afterRefactor, flagMode = true, rebuild = {}) => `${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
-` : ""}${amend === true ? `- The change already exists in the tree from an earlier lap; amend it to meet
+${afterRefactor === true ? afterRefactorLine(rebuild) : ""}${amend === true ? `- The change already exists in the tree from an earlier lap; amend it to meet
   the re-derived requirements instead of rewriting it
 ` : flagMode ? `- Implement them properly, fitting the codebase's seams and conventions
 ` : `- Implement them the quickest way that works — the naive version. Do not
   restructure, abstract or refactor around the change
 `}${reference === void 0 || amend === true ? "" : `- Reference only: \`git show ${reference}\` shows an earlier naive attempt.
   Read it for ideas; never apply, cherry-pick or check it out — write
-  the change fresh
-`}${!flagMode ? "- Add no release flag — this project ships without release flags" : tier === "low" ? "- Add no release flag — this change is low risk tier" : amend === true ? "- Keep the release flag the earlier lap added, if it added one; otherwise put\n  the behaviour behind a new release flag" : `- Put the new behaviour behind a new release flag, following the
+  the change fresh${carries(rebuild) ? ", its acceptance tests excepted (below)" : ""}
+`}${rebuildLines(rebuild)}${!flagMode ? "- Add no release flag — this project ships without release flags" : tier === "low" ? "- Add no release flag — this change is low risk tier" : amend === true ? "- Keep the release flag the earlier lap added, if it added one; otherwise put\n  the behaviour behind a new release flag" : `- Put the new behaviour behind a new release flag, following the
   repository's flag conventions`}
 - Write the tests first, then the code that makes them pass. Name each
   criterion's ID in the test that covers it (\`[AC-3] …\`): once the suite is
@@ -18087,12 +18123,13 @@ An edit together with an approval counts as steer. Only
 \`.gtd/REQUIREMENTS.md\` is meant to change here: any other edit lands on the
 branch unjudged.
 `;
-const seamSteerMessage = (retry) => isFault(retry) ? `The naive pass failed three times and the retries are spent. The last
+/** `judged`: whether an overruled pass still meets the seam judge (`flagMode` on). */
+const seamSteerMessage = (retry, judged = true) => isFault(retry) ? `The naive pass failed three times and the retries are spent. The last
 attempt's tests (\`git show ${retry.hash}\`) fall short:
 ${retry.fault}
 
 ${steerChoices(`land a clean tree to go on with the last attempt as it is:
-  \`seam.check\` runs its suite and the seam judge rules on its shape. Use it
+  \`seam.check\` runs its suite and ${judged ? "the seam judge rules on its shape" : "it lands as the implementation"}. Use it
   when the rule cannot fit this change (tests the globs do not see, or no
   entry point that existed before). Risk: a criterion may have no test that
   survives a later refactor — the choice is recorded in history.`)}` : isRed(retry) ? `The naive pass failed three times and the retries are spent. The last
@@ -18103,7 +18140,7 @@ Two ways forward (then run \`gtd land\`):
 - **Steer** — edit \`.gtd/REQUIREMENTS.md\` to redirect the change; the naive
   pass runs again with a fresh retry budget
 - **Overrule** — land a clean tree to go on with the last attempt as it is:
-  the seam judge rules on its shape, and the implementation's health loop
+  ${judged ? "the seam judge rules on its shape" : "it lands as the implementation"}, and the implementation's health loop
   must turn the suite green. Risk: the criteria's tests never passed on the
   naive pass — the choice is recorded in history.
 
@@ -18119,9 +18156,8 @@ Two ways forward (then run \`gtd land\`):
 - **Steer** — edit \`.gtd/REQUIREMENTS.md\` to redirect the change; the naive
   pass runs again with a fresh retry budget (the risk tier stays as the
   design gate settled it; a tier edit here is not applied)
-- **Overrule** — land a clean tree to accept the last attempt's approach:
-  the implementation is built against it as reference, with no seam gate
-  and no refactor. Risk: this ships the seam the judge objected to,
+- **Overrule** — land a clean tree to accept the last attempt as it is: it
+  lands as the implementation, with no seam gate and no refactor. Risk: this ships the seam the judge objected to,
   unaddressed — the choice is recorded in history.
 
 An edit together with an approval counts as steer. Only
@@ -18175,6 +18211,7 @@ const ESCALATION = ".gtd/ESCALATION.md";
 const REQUIREMENTS = ".gtd/REQUIREMENTS.md";
 const REVIEW = ".gtd/REVIEW.md";
 const REFACTOR = ".gtd/REFACTOR.md";
+const REFACTOR_NOTE = ".gtd/REFACTOR-NOTE.md";
 const QUALITY = ".gtd/QUALITY.md";
 const planner = () => env.plannerModel ?? "";
 const coder = () => env.coderModel ?? "";
@@ -37692,7 +37729,11 @@ const ShippedOptions = Struct({
 	testCommand: setting,
 	plannerModel: setting,
 	coderModel: setting,
-	flagMode: optionalWith(Boolean$, { exact: true })
+	flagMode: optionalWith(Boolean$, { exact: true }),
+	contextLimit: optionalWith(Struct({
+		soft: optionalWith(Number$, { exact: true }),
+		hard: optionalWith(Number$, { exact: true })
+	}), { exact: true })
 });
 const over = (base, options) => ({
 	...base,
@@ -37704,12 +37745,13 @@ const flagModeOn = () => {
 	if (value !== "true" && value !== "false") refuse(`gtd: flagMode must be "true" or "false", got ${JSON.stringify(value)}`);
 	return value === "true";
 };
+const limited = (flow, context) => context === void 0 ? flow : () => scope({ context }, flow);
 /** A shipped flow as a factory: its options override the settings it declares, each in its own kind. */
 const shipped = (flow, doors, base) => defineWorkflow(standardSchemaV1(ShippedOptions, {
 	onExcessProperty: "error",
 	errors: "all"
-}), (options) => ({
-	flow,
+}), ({ contextLimit, ...options }) => ({
+	flow: limited(flow, contextLimit),
 	defaults: over(defaults, options),
 	envDefaults: over(envDefaults, options),
 	doors,
@@ -37722,14 +37764,14 @@ const FlagOptions = Struct({
 const flagShipped = (flow, name) => defineWorkflow(standardSchemaV1(FlagOptions, {
 	onExcessProperty: "error",
 	errors: "all"
-}), (options) => {
+}), ({ contextLimit, ...options }) => {
 	const flagDefaults = {
 		...defaults,
 		flag: "",
 		flagRegistry: defaultFlagRegistry
 	};
 	return {
-		flow,
+		flow: limited(flow, contextLimit),
 		defaults: over(flagDefaults, options),
 		envDefaults: over(envDefaults, options),
 		doors: { [name]: {
@@ -38468,7 +38510,8 @@ const plan = (shape, options) => {
 	return {
 		pattern,
 		strays,
-		reference: options.reference?.trim() ? options.reference : void 0
+		reference: options.reference?.trim() ? options.reference : void 0,
+		note: options.note?.trim() ? options.note : void 0
 	};
 };
 const guardOf = ({ pattern, strays }, entry) => () => {
@@ -38477,13 +38520,22 @@ const guardOf = ({ pattern, strays }, entry) => () => {
 };
 /** Derive, build, check and close one refactor lap; `feedback` is the collected review text of the lap before. */
 const refactorLap = async (p, guard, feedback) => {
-	const { pattern, strays, reference } = p;
-	await run("deriving", deriveScript([...packageLines(strays, pattern, reference), ...feedback === void 0 ? [] : [
-		"## Review feedback",
-		"",
-		...demoteHeadings(feedback),
-		""
-	]]), {
+	const { pattern, strays, reference, note } = p;
+	await run("deriving", deriveScript([
+		...packageLines(strays, pattern, reference),
+		...note === void 0 ? [] : [
+			"## Refactor note",
+			"",
+			...demoteHeadings(note),
+			""
+		],
+		...feedback === void 0 ? [] : [
+			"## Review feedback",
+			"",
+			...demoteHeadings(feedback),
+			""
+		]
+	]), {
 		label: "Deriving the refactor package",
 		file: REFACTOR_PACKAGE
 	});
@@ -38492,7 +38544,8 @@ const refactorLap = async (p, guard, feedback) => {
 		strays,
 		pattern,
 		reference,
-		feedback: feedback !== void 0
+		feedback: feedback !== void 0,
+		note: note !== void 0
 	}), {
 		label: "Refactoring",
 		model: coder(),
@@ -38578,13 +38631,16 @@ const COVERED_MIN_P = .7;
 /** Covering turns before the process rests at `uncovered`; a human edit there refills them. */
 const COVERING_RETRIES = 2;
 const frozen = () => requireCriteriaFrozen(REQUIREMENTS);
-const green = () => healthy(() => agentWithSkills("fix.suite.fixing", implementFixPrompt(), {
+const green = (guard) => healthy(() => agentWithSkills("fix.suite.fixing", implementFixPrompt(), {
 	label: "Fixing the check",
 	file: FEEDBACK,
 	model: coder(),
 	system: builderSystem()
 }), {
-	guard: frozen,
+	guard: () => {
+		frozen();
+		guard?.();
+	},
 	guardRests: false
 });
 const testsSince = (base) => changesSince(base).filter((c) => c.after !== void 0 && isCode$1(c.path) && isTestFile(c.path)).sort((a, b) => Number(/\bAC-\d/.test(a.after)) - Number(/\bAC-\d/.test(b.after))).map((c) => `=== ${c.path} (${c.status})\n${c.after}`).join("\n");
@@ -38698,16 +38754,20 @@ const addedLines = (change) => {
 	const before = new Set((change.before ?? "").split("\n"));
 	return change.after.split("\n").filter((line) => !before.has(line)).join("\n");
 };
+const acceptanceTests = (changes) => changes.filter((c) => c.after !== void 0 && isCode$1(c.path) && isTestFile(c.path));
+const idsOf = (file) => (criteriaOf(read(file) ?? "") ?? []).map((c) => c.id).filter((id) => id !== "");
+const unnamed = (ids, tests) => {
+	const lines = tests.map(addedLines);
+	return ids.filter((id) => !lines.some((text) => named(id, text)));
+};
 /**
 * Why `tip`'s tests fall short, or `undefined`: a criterion ID of `file` no
 * test line of the pass names, or a test importing a file the pass added —
 * naive structure a reset and refactor replaces, which the tests must survive.
 */
 const acceptanceFault = (file, tip) => {
-	const ids = (criteriaOf(read(file) ?? "") ?? []).map((c) => c.id).filter((id) => id !== "");
-	const tests = tip.changes.filter((c) => c.after !== void 0 && isCode$1(c.path) && isTestFile(c.path));
-	const lines = tests.map(addedLines);
-	const untested = ids.filter((id) => !lines.some((text) => named(id, text)));
+	const tests = acceptanceTests(tip.changes);
+	const untested = unnamed(idsOf(file), tests);
 	if (untested.length > 0) return `acceptance-tests: no test of the naive pass names ${untested.join(", ")} — write a behaviour-level test for each criterion with its ID in the test or scenario name, e.g. "[${untested[0]}] …"`;
 	const added = tip.changes.filter((c) => c.status === "added" && isCode$1(c.path) && !isTestFile(c.path)).map((c) => c.path);
 	const reaching = tests.filter((test) => holdsCallSites(test.path)).flatMap((test) => {
@@ -38716,6 +38776,41 @@ const acceptanceFault = (file, tip) => {
 	});
 	if (reaching.length > 0) return `acceptance-internals: these tests import files the naive pass added — test through code that existed before it (a public entry point, an existing module's exports):\n${reaching.join("\n")}`;
 };
+/** What a rebuild carries over from the naive pass `tip`: the IDs its tests name, and those test files. */
+const naiveAcceptance = (tip) => {
+	const ids = idsOf(REQUIREMENTS);
+	const perTest = acceptanceTests(tip.changes).map((c) => {
+		const lines = addedLines(c);
+		return {
+			path: c.path,
+			ids: ids.filter((id) => named(id, lines))
+		};
+	});
+	return {
+		hash: tip.hash,
+		tests: perTest.filter((c) => c.ids.length > 0).map((c) => c.path),
+		ids: ids.filter((id) => perTest.some((c) => c.ids.includes(id)))
+	};
+};
+/**
+* Refuse a rebuild whose test changes since `since` leave out an ID the naive
+* pass's tests named. A skipped test still counts: the gate reads text, never runs it.
+*/
+const requireAcceptance = (acceptance, since) => {
+	const missing = unnamed(acceptance.ids, acceptanceTests(changesSince(since)));
+	if (missing.length === 0) return;
+	refuse(`gtd land: rebuild-acceptance: the rebuild's tests leave out ${missing.join(", ")} — carry over the naive pass's acceptance tests (\`git show ${acceptance.hash} -- ${acceptance.tests.map(quote).join(" ")}\`), each with its ID in the test or scenario name`);
+};
+/**
+* Refuse a fix turn that, on its own, drops an ID the naive pass's tests named
+* from a test file. Turn-local, so a person's edit at an escalation rest never
+* wedges later fix turns.
+*/
+const requireAcceptanceKept = (acceptance) => {
+	const dropped = acceptance.ids.filter((id) => changes().filter((c) => isCode$1(c.path) && isTestFile(c.path)).some((c) => named(id, c.before ?? "") && !named(id, c.after ?? "")));
+	if (dropped.length === 0) return;
+	refuse(`gtd land: rebuild-acceptance: this turn drops ${dropped.join(", ")} from the tests — the naive pass's acceptance tests stay; fix the code, not them`);
+};
 const restore = (path) => `if git cat-file -e ${quote(`HEAD:${path}`)} 2>/dev/null; then git checkout -q HEAD -- ${quote(path)}; else rm -f -- ${quote(path)}; fi`;
 /**
 * Run the suite with `tip`'s diff applied, then take it out again; resolves
@@ -38728,7 +38823,7 @@ const naiveGreen = (tip) => {
 	return check("check", [
 		...paths,
 		"dirty=$(git -c core.quotePath=false ls-files -m -d -o --exclude-standard)",
-		`if ! git diff --binary ${quote(`${tip.hash}^`)} ${quote(tip.hash)} -- | git apply; then`,
+		`if ! git diff --binary --no-color --no-ext-diff --no-textconv --src-prefix=a/ --dst-prefix=b/ ${quote(`${tip.hash}^`)} ${quote(tip.hash)} -- | git apply --whitespace=nowarn; then`,
 		"  echo 'gtd: the kept naive pass no longer applies to HEAD; no test ran'",
 		"  exit 1",
 		"fi",
@@ -38747,6 +38842,11 @@ const naiveGreen = (tip) => {
 		label: "Running the naive pass's tests"
 	});
 };
+/** Resolves `false` when the tip no longer applies (the failure is in `.gtd/FEEDBACK.md`) or has nothing outside `.gtd/` to apply. */
+const applied = async (tip) => {
+	await run("applying", applyScript(tip, FEEDBACK, naiveApplyFailure(tip), [".gtd"]), { label: "Applying the naive pass" });
+	return !wrote(".gtd/FEEDBACK.md") && codeChanges().length > 0;
+};
 function implement(first, tier, amend) {
 	const options = typeof first === "object" && first !== null ? first : {
 		reference: first,
@@ -38754,22 +38854,26 @@ function implement(first, tier, amend) {
 		amend
 	};
 	return scope("implement", async () => {
-		await agentWithSkills("building", implementBuildingPrompt(options.reference, options.tier, options.amend, options.afterRefactor, flagModeOn()), {
+		const since = head$1();
+		const acceptance = options.rebuild?.acceptance;
+		const built = options.naive === void 0 || !await applied(options.naive);
+		if (built) await agentWithSkills("building", implementBuildingPrompt(options.reference, options.tier, options.amend, options.afterRefactor, flagModeOn(), options.rebuild), {
 			label: "Implementing",
 			model: coder(),
 			system: builderSystem(),
 			...options.afterRefactor === true ? { allowEmpty: true } : {}
 		});
 		requireCriteriaFrozen(REQUIREMENTS);
-		await green();
+		if (built && acceptance !== void 0) requireAcceptance(acceptance, since);
+		await green(built && acceptance !== void 0 ? () => requireAcceptanceKept(acceptance) : void 0);
 		await requireCoverage();
-		await run("closing", removeScript([REQUIREMENTS]), { label: "Closing out the implementation" });
+		await run("closing", removeScript([REQUIREMENTS, REFACTOR_NOTE]), { label: "Closing out the implementation" });
 	});
 }
 /** Resolves `true` when the human steered (edited), `false` on a clean overrule. */
 const steer = async (retry) => {
 	await human("steer", {
-		message: seamSteerMessage(retry),
+		message: seamSteerMessage(retry, flagModeOn()),
 		label: "Steer or overrule the naive pass",
 		file: REQUIREMENTS,
 		acceptClean: true
@@ -38813,16 +38917,23 @@ const vetted = async (tip, vetting) => {
 /** The judge's ruling on a vetted pass: the decision, or the next attempt's verdict. */
 const ruled = async (tip, again) => {
 	const shape = await judgeSeam(tip);
-	if (shape.choice === "land") return { reference: tip.hash };
+	if (shape.choice === "land") return {
+		reference: tip.hash,
+		tip
+	};
 	if (shape.choice === "refactor-first") return {
 		reference: tip.hash,
+		tip,
 		shape
 	};
 	const next = await again({
 		strays: shape.strays,
 		p: shape.judgment?.answers.shape?.p ?? 0
 	});
-	return next.kind === "overruled" ? { reference: tip.hash } : next;
+	return next.kind === "overruled" ? {
+		reference: tip.hash,
+		tip
+	} : next;
 };
 const decide = () => scope("seam", async () => {
 	const vetting = {
@@ -38833,16 +38944,33 @@ const decide = () => scope("seam", async () => {
 	for (;;) {
 		await naivePass(retry);
 		const tip = kept("naive");
-		const outcome = await vetted(tip, vetting) ?? await ruled(tip, vetting.again);
+		const outcome = await vetted(tip, vetting) ?? (flagModeOn() ? await ruled(tip, vetting.again) : {
+			reference: tip.hash,
+			tip
+		});
 		if (!("kind" in outcome)) return outcome;
 		retry = outcome.kind === "retry" ? outcome.retry : void 0;
 	}
 });
+/** Write the refactor note from the whole naive pass; a turn that changes anything else is refused. */
+const refactorNote = async (reference, strays) => {
+	await agent("note", refactorNotePrompt(reference, strays), {
+		label: "Writing the refactor note",
+		file: REFACTOR_NOTE,
+		model: coder(),
+		system: builderSystem()
+	});
+	const others = changes().map((c) => c.path).filter((path) => path !== REFACTOR_NOTE);
+	const note = read(".gtd/REFACTOR-NOTE.md") ?? "";
+	if (others.length > 0 || note.trim() === "") refuse(`gtd land: refactor-note: write ${REFACTOR_NOTE} and change nothing else${others.length > 0 ? ` — revert these:\n${others.map((path) => `  - ${path}`).join("\n")}` : ""}`);
+	return note;
+};
 const seamBuild = async (base) => {
-	const { reference, shape } = await decide();
+	const { reference, tip, shape } = await decide();
 	if (shape === void 0) return {
 		reference,
-		base
+		base,
+		land: true
 	};
 	if (shape.unreadable.length > 0) {
 		await scope("seam", () => human("by-hand", {
@@ -38852,18 +38980,29 @@ const seamBuild = async (base) => {
 		}));
 		return {
 			reference,
-			base
+			base,
+			rebuild: { acceptance: naiveAcceptance(tip) }
 		};
 	}
-	if (refactorStrays(shape).length === 0) return {
+	const strays = refactorStrays(shape);
+	if (strays.length === 0) return {
 		reference,
-		base
+		base,
+		rebuild: { acceptance: naiveAcceptance(tip) }
 	};
-	const refactored = await slice("refactor", () => reviewedRefactor(shape, { reference }));
+	const note = await scope("seam", () => refactorNote(reference, strays));
+	const refactored = await slice("refactor", () => reviewedRefactor(shape, {
+		reference,
+		note
+	}));
 	return {
 		reference,
 		base: head$1(),
-		refactored
+		refactored,
+		rebuild: {
+			note,
+			acceptance: naiveAcceptance(tip)
+		}
 	};
 };
 //#endregion
@@ -38873,17 +39012,20 @@ const unwind = () => {
 	const commit = head$1();
 	return run("unwind", revertScript(commit, FEEDBACK, unwindFailure(commit)), { label: "Unwinding your input" });
 };
-/** A judged naive pass (none with `flagMode` off), then implement and the quality lap; design must have run since `firstBase`. */
+/** A naive pass (judged only with `flagMode` on), then implement and the quality lap; design must have run since `firstBase`. */
 const buildFeature = async (firstBase) => {
 	const tier = riskTierOn() ? recordRisk() : void 0;
-	const seam = flagModeOn() ? await seamBuild(firstBase) : { base: firstBase };
+	const seam = await seamBuild(firstBase);
 	await slice("feature", async () => {
 		await implement({
 			reference: seam.reference,
 			tier,
-			afterRefactor: seam.refactored
+			afterRefactor: seam.refactored,
+			naive: seam.land === true ? seam.reference : void 0,
+			rebuild: seam.rebuild
 		});
-		const base = seam.refactored === true && !changesSince(seam.base).some((c) => isCode$1(c.path)) ? firstBase : seam.base;
+		const carried = seam.rebuild?.acceptance?.tests ?? [];
+		const base = seam.refactored === true && !changesSince(seam.base).some((c) => isCode$1(c.path) && !carried.includes(c.path)) ? firstBase : seam.base;
 		await tail(settleQuality, {
 			green: true,
 			lensBase: base
@@ -39126,4 +39268,4 @@ var workflows_default = feature;
 */
 const doors = {};
 //#endregion
-export { COMMENT, ESCALATION, FEEDBACK, FIX_CAP, FlagOptions, QUALITY, REFACTOR, REFACTOR_PACKAGE, REQUIREMENTS, REVIEW, REVIEW_ORIG, ShippedOptions, acceptanceFault, 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, holdsCallSites, implement, isTestFile, judgeSeam, lensEntriesOf, lensOf, 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 };
+export { COMMENT, ESCALATION, FEEDBACK, FIX_CAP, FlagOptions, QUALITY, REFACTOR, REFACTOR_NOTE, REFACTOR_PACKAGE, REQUIREMENTS, REVIEW, REVIEW_ORIG, ShippedOptions, acceptanceFault, 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, holdsCallSites, implement, isTestFile, judgeSeam, lensEntriesOf, lensOf, lensesOf, naiveAcceptance, naivePass, ordinaryStart, planAndBuild, planner, qualityLap, reUnwind, refactorCollecting, refactorFirst, refactorNote, refactorStrays, requireAcceptance, requireAcceptanceKept, 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": "35.0.0",
+  "version": "37.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/skills/authoring/SKILL.md

@@ -223,9 +223,9 @@ workflow.
 ## Worked example: add an approval gate before building
 
 In the bundled default, `planAndBuild` runs the design phase, then
-`buildFeature`: the naive pass and its seam judge, then the implementation and
-the quality lap, ending with no human review. Add a human sign-off before the
-build:
+`buildFeature`: the naive pass and its seam judge, then the implementation (the
+pass itself on `land`) and the quality lap, ending with no human review. Add a
+human sign-off before the build:
 
 ```ts
 const planAndBuild = async (firstBase: string): Promise<void> => {

package/src/cli/Cli.test.ts

@@ -1106,6 +1106,7 @@ describe("standaloneKinds / needsOf", () => {
       "uncheck",
       "install",
       "loop",
+      "contextHook",
       "judgeRun",
       "strays",
     ])
@@ -1117,6 +1118,7 @@ describe("standaloneKinds / needsOf", () => {
     expect(needsOf("uncheck")).toBe("fs")
     expect(needsOf("install")).toBe("none")
     expect(needsOf("loop")).toBe("none")
+    expect(needsOf("contextHook")).toBe("none")
     expect(needsOf("judgeRun")).toBe("none")
     expect(needsOf("strays")).toBe("none")
     for (const kind of [
@@ -1202,19 +1204,24 @@ describe("renderHelp", () => {
 
   it("README.md and COMPATIBILITY.md list exactly the commands", () => {
     const commands = new Set(
-      [...renderHelp().matchAll(/^ {2}([a-z]+(?: [a-z]+)?)(?= )/gm)].map(([, name]) => name),
+      [...renderHelp().matchAll(/^ {2}([a-z]+(?:-[a-z]+)?(?: [a-z]+)?)(?= )/gm)].map(
+        ([, name]) => name,
+      ),
     )
     expect(commands).toContain("judge answer")
+    expect(commands).toContain("context-hook")
     const listed = (file: string, list: RegExp): Set<string> => {
       const doc = readFileSync(resolve(import.meta.dirname, file), "utf8")
       const match = doc.match(list)
       expect(match, file).not.toBeNull()
-      return new Set([...match![1]!.matchAll(/`([a-z]+(?: [a-z]+)?)`/g)].map(([, name]) => name!))
+      return new Set(
+        [...match![1]!.matchAll(/`([a-z]+(?:-[a-z]+)?(?: [a-z]+)?)`/g)].map(([, name]) => name!),
+      )
     }
     expect(
       listed("../../README.md", /The `gtd` bin's commands — ([\s\S]*?) — are\s+listed/),
     ).toEqual(commands)
-    expect(listed("../../COMPATIBILITY.md", /every command \(([\s\S]*?)\), option/)).toEqual(
+    expect(listed("../../COMPATIBILITY.md", /every command \(([\s\S]*?)\),\s+option/)).toEqual(
       commands,
     )
   })