@pmelab/gtd 36.0.0 → 37.0.0

package/dist/workflows.mjs

@@ -17436,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
@@ -18057,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
@@ -18180,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 ?? "";
@@ -37697,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,
@@ -37709,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,
@@ -37727,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]: {
@@ -38473,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) => () => {
@@ -38482,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
 	});
@@ -38497,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(),
@@ -38583,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");
@@ -38703,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) => {
@@ -38721,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
@@ -38764,16 +38854,20 @@ function implement(first, tier, amend) {
 		amend
 	};
 	return scope("implement", async () => {
-		if (options.naive === void 0 || !await applied(options.naive)) 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. */
@@ -38823,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 = {
@@ -38843,13 +38944,29 @@ const decide = () => scope("seam", async () => {
 	for (;;) {
 		await naivePass(retry);
 		const tip = kept("naive");
-		const outcome = await vetted(tip, vetting) ?? (flagModeOn() ? await ruled(tip, vetting.again) : { reference: tip.hash });
+		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,
@@ -38863,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
@@ -38893,9 +39021,11 @@ const buildFeature = async (firstBase) => {
 			reference: seam.reference,
 			tier,
 			afterRefactor: seam.refactored,
-			naive: seam.land === true ? seam.reference : void 0
+			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
@@ -39138,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": "36.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/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,
     )
   })

package/src/cli/Cli.ts

@@ -35,7 +35,7 @@ import {
   type JsonMode,
 } from "./Program.js"
 import type { ToolCommands } from "./ToolCommands.js"
-import { EXIT_RUNTIME_ERROR, EXIT_USAGE_ERROR } from "../wire/index.js"
+import { EXIT_RUNTIME_ERROR, EXIT_USAGE_ERROR, parseContextWindow } from "../wire/index.js"
 
 export type { Command, CommandRequirements } from "./Program.js"
 export { needsOf, standaloneKinds } from "./Program.js"
@@ -90,6 +90,13 @@ const nonNegativeNumber = (raw: string, flag: string): Either.Either<number, str
   return Either.right(n)
 }
 
+const share = (raw: string, flag: string): Either.Either<number, string> => {
+  const n = Number(raw)
+  return raw.trim() !== "" && n > 0 && n <= 1
+    ? Either.right(n)
+    : Either.left(`gtd: ${flag} must be a share of the context window in (0, 1] — got "${raw}"`)
+}
+
 const FLAGS: readonly FlagRow[] = [
   {
     name: "--json",
@@ -245,6 +252,41 @@ const FLAGS: readonly FlagRow[] = [
       "GTD_JUDGE_MODEL, then judge.json, then sonnet",
     ],
   },
+  {
+    name: "--soft",
+    arity: 1,
+    repeatable: false,
+    scope: (kind) => kind === "contextHook",
+    decode: ([raw]) => share(raw ?? "", "--soft"),
+    scopeError: "gtd: --soft is only valid for `gtd context-hook`",
+    valueHint: "<share>",
+    help: ["(gtd context-hook only) the soft limit; default 0.6"],
+  },
+  {
+    name: "--hard",
+    arity: 1,
+    repeatable: false,
+    scope: (kind) => kind === "contextHook",
+    decode: ([raw]) => share(raw ?? "", "--hard"),
+    scopeError: "gtd: --hard is only valid for `gtd context-hook`",
+    valueHint: "<share>",
+    help: ["(gtd context-hook only) the hard limit; default 0.7"],
+  },
+  {
+    name: "--window",
+    arity: 1,
+    repeatable: false,
+    scope: (kind) => kind === "contextHook",
+    decode: ([raw]) => {
+      const window = parseContextWindow(raw)
+      return window !== undefined
+        ? Either.right(window)
+        : Either.left(`gtd: --window must be a positive integer — got "${raw ?? ""}"`)
+    },
+    scopeError: "gtd: --window is only valid for `gtd context-hook`",
+    valueHint: "<tokens>",
+    help: ["(gtd context-hook only) the model's context window in", "tokens; default 200000"],
+  },
   {
     name: "--slice",
     arity: 1,
@@ -593,6 +635,22 @@ const COMMAND_ROWS: readonly CommandRow[] = [
       "~/.config/gtd/loop.json); see docs/driver.md",
     ],
   },
+  {
+    token: "context-hook",
+    kind: "contextHook",
+    arity: "none",
+    details: [
+      "A Claude Code PostToolUse and PreCompact hook that stops an",
+      "agent turn at a share of its context window. Reads the",
+      "hook's input on stdin and the context the transcript's",
+      "latest assistant message used. Past --soft it blocks with a",
+      "request to end the turn with a handoff note; past --hard,",
+      "or at PreCompact, it stops the turn with a stopReason",
+      'starting "gtd: context limit". Prints nothing otherwise,',
+      "and for a subagent's tool call. Always exits 0 on valid",
+      "input; see docs/driver.md",
+    ],
+  },
   {
     token: "summary",
     kind: "summary",
@@ -1182,6 +1240,9 @@ export const parseArgv = (argv: readonly string[]): CliPlan => {
     readonly "--provider"?: "fixed" | "jev" | "llm"
     readonly "--answers"?: string
     readonly "--slice"?: string
+    readonly "--soft"?: number
+    readonly "--hard"?: number
+    readonly "--window"?: number
   }
 
   // `present.has("--json")` alone can't distinguish bare `--json` (no value
@@ -1285,6 +1346,20 @@ export const parseArgv = (argv: readonly string[]): CliPlan => {
     }
   }
 
+  if (kind === "contextHook") {
+    return {
+      kind: "command",
+      command: {
+        kind: "contextHook",
+        ...(bag["--soft"] !== undefined ? { soft: bag["--soft"] } : {}),
+        ...(bag["--hard"] !== undefined ? { hard: bag["--hard"] } : {}),
+        ...(bag["--window"] !== undefined ? { window: bag["--window"] } : {}),
+      },
+      json,
+      verbose,
+    }
+  }
+
   if (kind === "summary") {
     return {
       kind: "command",

package/src/cli/Program.test.ts

@@ -1686,6 +1686,7 @@ describe("runCommand — refuses in a repository with no commits", () => {
     uncheck: { kind: "uncheck", file: ".gtd/REVIEW.md" },
     install: { kind: "install" },
     loop: { kind: "loop" },
+    contextHook: { kind: "contextHook" },
     summary: { kind: "summary" },
     base: { kind: "base" },
     judge: { kind: "judge" },

package/src/cli/Program.ts

@@ -162,6 +162,12 @@ export type Command =
   | { readonly kind: "uncheck"; readonly file: string }
   | { readonly kind: "install" }
   | { readonly kind: "loop" }
+  | {
+      readonly kind: "contextHook"
+      readonly soft?: number
+      readonly hard?: number
+      readonly window?: number
+    }
   | { readonly kind: "summary"; readonly slice?: string }
   | { readonly kind: "base" }
   | { readonly kind: "judge" }
@@ -434,6 +440,24 @@ const readStdin = (): Effect.Effect<string, Error> =>
     catch: (e) => (e instanceof Error ? e : new Error(String(e))),
   })
 
+/** Stdout is written once: a hook reads one JSON document, or none. */
+const runContextHookCommand = (
+  command: Extract<Command, { kind: "contextHook" }>,
+  out: ArtifactOut,
+): Effect.Effect<void, Error, ToolCommands> =>
+  Effect.gen(function* () {
+    const tools = yield* ToolCommands
+    const input = yield* readStdin()
+    out.write(
+      yield* tools.contextHook({
+        input,
+        ...(command.soft !== undefined ? { soft: command.soft } : {}),
+        ...(command.hard !== undefined ? { hard: command.hard } : {}),
+        ...(command.window !== undefined ? { window: command.window } : {}),
+      }),
+    )
+  })
+
 /** Stdout is written once, after the answerer resolves — a rejection leaves it empty. */
 const runJudgeRunCommand = (
   command: Extract<Command, { kind: "judgeRun" }>,
@@ -1189,6 +1213,7 @@ export const needsOf = (kind: Command["kind"]): Needs => {
     case "lsp":
     case "install":
     case "loop":
+    case "contextHook":
     case "judgeRun":
     case "strays":
       return "none"
@@ -1207,6 +1232,7 @@ export const standaloneKinds = (): readonly Command["kind"][] => [
   "uncheck",
   "install",
   "loop",
+  "contextHook",
   "judgeRun",
   "strays",
 ]
@@ -1278,6 +1304,8 @@ const dispatchVoidCommand = (
       return runInstallCommand(out)
     case "loop":
       return runLoopCommand()
+    case "contextHook":
+      return runContextHookCommand(command, out)
     case "summary":
       return runSummaryCommand(out, command.slice)
     case "base":

package/src/cli/ToolCommands.ts

@@ -1,6 +1,7 @@
 import { Context } from "effect"
 import type { Effect } from "effect"
 import type { UiSettings } from "../flows/index.js"
+import type { ContextHookRequest } from "../wire/index.js"
 
 /** How to run THIS gtd — a driver (the loop, the LSP) never reads a different version's state than the one it ships with. */
 export type SelfGtd = readonly [string, ...string[]]
@@ -38,6 +39,8 @@ export class ToolCommands extends Context.Tag("ToolCommands")<
     ) => Effect.Effect<void, Error>
     readonly lsp: (gtd: SelfGtd) => Effect.Effect<void, Error>
     readonly loop: (gtd: SelfGtd) => Effect.Effect<void, Error>
+    /** The hook's stdout: a JSON document, or empty to let the turn go on. */
+    readonly contextHook: (request: ContextHookRequest) => Effect.Effect<string, Error>
     readonly judge: (request: JudgeRequest) => Promise<string>
   }
 >() {}