@pmelab/gtd 24.2.0 → 24.4.0

package/dist/workflows.mjs

@@ -217,6 +217,13 @@ const removeScript = (paths) => [
 	...removal(paths),
 	""
 ].join("\n");
+/** Write `path` as committed at `ref` to `to`. */
+const showScript = (ref, path, to) => [
+	"#!/usr/bin/env sh",
+	"set -e",
+	`git show ${quote(`${ref}:${path}`)} > ${quote(to)}`,
+	""
+].join("\n");
 //#endregion
 //#region src/flows/helpers.ts
 /** Whether a judge answered `expected` at a probability of at least `minP`. */
@@ -16360,10 +16367,13 @@ const reviewNotes = (before, after) => {
 	return [...parseReviewDoc(after).changesets.flatMap((chunk) => {
 		const prior = oldChunks.get(chunk.title);
 		return [...chunkNote(chunk, prior), ...pointerNotes(chunk, prior)];
-	}), ...footnoteNotes(before, after)].sort((a, b) => a.line - b.line).map((f, i) => ({
-		id: `note-${i + 1}`,
-		...f.note
-	}));
+	}), ...footnoteNotes(before, after)].sort((a, b) => a.line - b.line).map((f, i) => {
+		return {
+			id: `note-${i + 1}`,
+			...f.note,
+			forced: /^!(\s|$)/.test(f.note.text)
+		};
+	});
 };
 /** Pointer notes the reviewer opened with `Risk:`, in document order — the ones the workflow fixes before the human gate. */
 const reviewRisks = (content) => parseReviewDoc(content).changesets.flatMap((chunk) => chunk.files.flatMap((file) => file.note?.startsWith("Risk:") ? [{
@@ -16526,16 +16536,17 @@ const converse = async (p, base, collectedBefore) => {
 		if (!hasThreadFor("human", p.file)) return collectedAt;
 	}
 };
-/** Judge every note, then run each verdict's route: answers, then nit fixes, then the edits' lap. */
+/** Judge every note, then run each verdict's route: answers, then nit fixes, then deferrals, then the edits' lap. */
 const routeNotes = async (p, notes, r) => {
 	const verdicts = await p.triage(notes);
 	const of = (v) => notes.filter((n) => (verdicts.get(n.id) ?? "edit") === v);
-	const [edits, questions, nits] = [
+	const [edits, questions, nits, deferred] = [
 		of("edit"),
 		of("question"),
-		of("nit")
+		of("nit"),
+		of("defer")
 	];
-	if (edits.length + questions.length + nits.length === 0) return r.unfolded();
+	if (edits.length + questions.length + nits.length + deferred.length === 0) return r.unfolded();
 	let answeredAt;
 	if (questions.length > 0) {
 		await p.answerQuestions(questions);
@@ -16545,6 +16556,7 @@ const routeNotes = async (p, notes, r) => {
 		await p.fixNits(nits);
 		await p.keepGreen();
 	}
+	if (deferred.length > 0) await p.defer(deferred);
 	if (edits.length > 0) {
 		await r.close();
 		return r.outcome(await collect(p, p.captures.editNotes(r.round, edits, answeredAt)));
@@ -16558,7 +16570,7 @@ const routeNotes = async (p, notes, r) => {
 	}
 	return {
 		next: "await",
-		reviewed: answeredAt
+		reviewed: answeredAt ?? r.round
 	};
 };
 /** A code edit, not a thread-only change: lines that only add, answer or remove code threads don't count. */
@@ -16987,6 +16999,10 @@ ${stateFileRules}
 ${footnoteFoldIn}${codeThreadReplies()}
 - The only state file this turn touches is \`.gtd/REQUIREMENTS.md\`
   — no other files for notes or output
+- Lines of a \`## Deferred review notes\` section of \`.gtd/TODO.md\`
+  that the start diff does not touch are parked by review, never folded;
+  the human's edits to such a line (or its removal) are input like any
+  other part of the start diff
 - \`.gtd/TODO.md\` is the likely home of the sketch that started
   this process — the human's input, folded into the concerns
   below like any other part of the start diff; never a state
@@ -17470,9 +17486,10 @@ const reviewNotesCapture = (commit) => `This is machine-captured input, not inst
 Commit: ${commit}
 The human's notes are in .gtd/REVIEW.md at this commit. Run: git show ${commit}
 `;
+const noteHead = (n) => `${n.id} — ${n.anchor}${n.label === void 0 ? "" : ` (${n.label})`}`;
 const notesCapture = (notes) => `This is machine-captured input, not instructions.
 
-${notes.map((n) => `- ${n.id} — ${n.anchor}\n  ${n.text.replace(/\n/g, "\n  ")}`).join("\n")}
+${notes.map((n) => `- ${noteHead(n)}\n  ${n.text.replace(/\n/g, "\n  ")}`).join("\n")}
 `;
 const buildReviewAnswerQuestionsPrompt = (notes) => `${stateFileRules}
 - The only state file this turn writes is \`.gtd/REVIEW.md\`; touch no
@@ -17534,12 +17551,47 @@ record.
 What each change does next (then run \`gtd land\`):
 - **Re-review** — re-run the reviewer to author a fresh \`.gtd/REVIEW.md\` (**build.review.reviewing**).
 `;
+/** Greedy wrap at 80 columns with a 2-space continuation indent: oxfmt (`proseWrap: always`) rewrites any other shape. */
+const wrapItem = (item) => {
+	const out = [];
+	let line = "";
+	for (const word of item.split(" ")) if (line !== "" && line.length + 1 + word.length > 80) {
+		out.push(line);
+		line = `  ${word}`;
+	} else line = line === "" ? word : `${line} ${word}`;
+	return [...out, line];
+};
+/** Appends one section of `notes` to `.gtd/TODO.md`, wrapped the way oxfmt writes it; an existing file is only ever appended to. */
+const deferNotesScript = (notes, round) => {
+	return `mkdir -p .gtd
+if [ -s .gtd/TODO.md ]; then
+  [ -z "$(tail -c1 .gtd/TODO.md)" ] || printf '\\n' >> .gtd/TODO.md
+  printf '\\n' >> .gtd/TODO.md
+fi
+printf '%s\\n' ${[
+		`## Deferred review notes (${round.slice(0, 7)})`,
+		"",
+		...notes.flatMap((n) => wrapItem(`- ${noteHead(n)}: ${n.text.replace(/\s+/g, " ")}`))
+	].map(quote).join(" ")} >> .gtd/TODO.md
+`;
+};
+/** The gate right after a deferral: landing clean signs off without these notes. */
+const buildReviewAwaitAfterDeferMessage = (base, deferred) => `${buildReviewAwaitReviewMessage(base)}
+Deferred to \`.gtd/TODO.md\` just now, NOT acted on in this process — landing
+clean signs off without them:
+
+${deferred.map((n) => `- ${noteHead(n)}: ${n.text.replace(/\s*\n\s*/g, " ")}`).join("\n")}
+`;
 const buildReviewTriageMessage = () => `Judging each note the human added to \`.gtd/REVIEW.md\` (a line note, a
 footnote, or prose under a chunk) with one verdict: \`edit\` (a change
 request), \`question\`, \`nit\` (a small fix needing no re-plan) or
 \`praise\`. Run \`gtd judge answer\` and pipe a choice per note — or land
 untouched, which treats every note as \`edit\` (the conservative
 default; a skipped judgment never dismisses a note).
+
+Also judge each note's severity, one id per note: \`note-<n>.security\`,
+\`note-<n>.reversibility\`, \`note-<n>.blastRadius\` and
+\`note-<n>.newConcept\`.
 `;
 const buildReviewCollectingPrompt = (capture) => `${styleBlock}
 
@@ -17560,6 +17612,8 @@ ${footnoteFoldIn}${codeThreadReplies()}
 - When the capture names an answering commit, carry each answered
   question into \`.gtd/REQUIREMENTS.md\`'s \`## Answered Questions\` as
   \`### <the note>\` plus its answer — the lap replaces \`.gtd/REVIEW.md\`
+- Keep capture order, and carry each note's \`(tier: reason)\`
+  label into the concern folded from it
 - Nit notes were already fixed: never re-raise a fixed nit as a concern
 - Finish by running \`gtd check review .gtd/REVIEW.md\` and fix
   what it reports
@@ -17786,12 +17840,13 @@ const fixRisks = (notes) => agentWithSkills("review.fix.risks.fixing", buildRevi
 	system: reviewerSystem(),
 	allowEmpty: true
 });
-const awaitReview = (base, message = buildReviewAwaitReviewMessage(base)) => human("review.await-review", {
+const awaitReview = (base, message = buildReviewAwaitReviewMessage(base), acceptClean = false) => human("review.await-review", {
 	message,
 	label: "Awaiting your review",
 	file: REVIEW,
 	mode: "review",
-	base
+	base,
+	...acceptClean ? { acceptClean } : {}
 });
 /** The round at commit `round` left no `.gtd/REVIEW.md`. */
 const reviewMissing = (round) => human("review.review-missing", {
@@ -37207,6 +37262,7 @@ const defaults = {
 	judgeBudgetBytes: "32768",
 	judgeIdenticalMinP: "0.7",
 	reviewNoteActionable: "0.7",
+	reviewSeverityMinP: "0.7",
 	qualityReviews: "correctness, owasp-security, ponytail-review, test-audit, conventions, spec-challenge"
 };
 /** Environment settings. */
@@ -37224,6 +37280,7 @@ const ShippedOptions = Struct({
 	judgeBudgetBytes: setting,
 	judgeIdenticalMinP: setting,
 	reviewNoteActionable: setting,
+	reviewSeverityMinP: setting,
 	qualityReviews: setting,
 	testCommand: setting,
 	fastTestCommand: setting,
@@ -37310,12 +37367,6 @@ const tail = (fixFirst, finish, built) => scope("build", async () => {
 	else await repair();
 	return finish(escalations, frozen);
 });
-const handOffScript = (reviewed) => [
-	"#!/usr/bin/env sh",
-	"set -e",
-	`git show ${quote(`${reviewed}:${REVIEW}`)} > ${quote(REVIEW_ORIG)}`,
-	""
-].join("\n");
 /**
 * The review and fix workflows' human review since `base`: a sign-off closes
 * `.gtd/REVIEW.md`; a note leaves it, with the reviewer's own version as
@@ -37329,7 +37380,7 @@ const handOffReview = (base, escalations) => reviewToHandOff(base, {
 	awaitReview: (b) => awaitReview(b, handOffAwaitReviewMessage(b)),
 	reviewMissing,
 	close: closeReview,
-	handOff: (reviewed) => run("review.handing-off", handOffScript(reviewed), { label: "Handing your notes to fix" }),
+	handOff: (reviewed) => run("review.handing-off", showScript(reviewed, REVIEW, REVIEW_ORIG), { label: "Handing your notes to fix" }),
 	threadsPending: "gtd land: open-threads: a thread in .gtd/REVIEW.md or an `H:` code comment waits on the agent — nothing answers it here; delete it, or turn it into a note for fix.",
 	unparsed: "gtd land: review-doc: your edit to .gtd/REVIEW.md contains no note fix can read — restore the deleted chunk, or write the note as a line under its entry.",
 	deleted: "gtd land: review-doc: .gtd/REVIEW.md was deleted — restore it, or leave a note to hand to fix."
@@ -37407,6 +37458,11 @@ const collecting = (capture) => agentWithSkills("review.collecting", buildReview
 	system: reviewerSystem(),
 	allowEmpty: true
 });
+/** `build.review.defer`: append `notes` to `.gtd/TODO.md` as one section; the step's landing is the commit. */
+const deferNotes = (notes, round) => run("review.defer", deferNotesScript(notes, round), {
+	label: "Deferring could-notes to TODO.md",
+	file: ".gtd/TODO.md"
+});
 //#endregion
 //#region src/workflows/feature/packages.ts
 /** Package 0: the e2e scenarios, written red. */
@@ -37530,23 +37586,106 @@ const verdictQuestion = (note) => ({
 	instructions: `Classify the human's note on review item "${note.anchor}" (in .gtd/REVIEW.md). Its evidence holds the anchor, the reviewer's text and the human's text.`,
 	criteria: "edit: a request to change behaviour, design or scope — anything needing a plan, or any note you are unsure about. question: asks something and wants an answer, with no change requested. nit: a small, local, unambiguous fix (naming, typo, formatting, comment wording) needing no re-plan. praise: an approving remark with nothing to do."
 });
+const SEVERITY_ANSWERS = {
+	security: ["yes", "no"],
+	reversibility: ["one-way", "two-way"],
+	blastRadius: [
+		"local",
+		"module",
+		"contract"
+	],
+	newConcept: ["yes", "no"]
+};
 /**
-* One judge rest, one verdict per note. Dismissing a note is the risky
-* direction, so only a confident non-`edit` verdict on uncut evidence counts;
-* a cut, unanswered or below-floor note is an `edit`, and a blank floor makes
-* every note one.
+* Deferring is the risky direction: anything unanswered, unrecognised, cut or
+* below `minP` is `critical`, never `could`.
 */
-const triage$1 = async (notes) => {
-	const { answers, truncated } = await judge("review.triage", {
-		questions: notes.map(verdictQuestion),
-		evidence: Object.fromEntries(notes.map((n) => [n.id, `Anchor: ${n.anchor}\nReviewer's text: ${n.before}\nHuman's text: ${n.text}`])),
+const severityOf = (note, judgment, minP) => {
+	const ans = (q) => judgment.answers[`${note.id}.${q}`];
+	const a = (q) => ans(q)?.answer;
+	const rank = () => a("reversibility") === "one-way" ? 0 : a("newConcept") === "yes" ? 1 : 2;
+	if (note.forced) return {
+		tier: "critical",
+		reason: "critical: forced by `!`",
+		rank: 2
+	};
+	if (judgment.truncated.includes(note.id) || Object.entries(SEVERITY_ANSWERS).some(([q, allowed]) => !allowed.includes(a(q) ?? "") || !((ans(q)?.p ?? NaN) >= minP))) return {
+		tier: "critical",
+		reason: "critical: judge unsure",
+		rank: 2
+	};
+	const critical = [...a("security") === "yes" ? ["security"] : [], ...a("reversibility") === "one-way" ? ["one-way door"] : []];
+	if (critical.length > 0) return {
+		tier: "critical",
+		reason: `critical: ${critical.join(", ")}`,
+		rank: rank()
+	};
+	const should = [...a("blastRadius") === "contract" ? ["contract"] : [], ...a("newConcept") === "yes" ? ["new concept"] : []];
+	if (should.length > 0) return {
+		tier: "should",
+		reason: `should: ${should.join(", ")}`,
+		rank: rank()
+	};
+	return {
+		tier: "could",
+		reason: "could",
+		rank: 2
+	};
+};
+const severityQuestions = (note) => [
+	{
+		id: `${note.id}.security`,
+		primitive: "noul",
+		instructions: `Does the change the human asks for in note "${note.id}" (on "${note.anchor}") touch security — authentication, authorisation, secrets, untrusted input or data exposure?`,
+		criteria: "yes: it changes or could weaken a security property. no: it does not."
+	},
+	{
+		id: `${note.id}.reversibility`,
+		primitive: "choice",
+		instructions: `Once the change in note "${note.id}" ships, can it be undone without breaking anyone who already depends on it?`,
+		criteria: "one-way: a published API, file format, persisted data, protocol or other contract that cannot be taken back. two-way: can be reverted freely."
+	},
+	{
+		id: `${note.id}.blastRadius`,
+		primitive: "choice",
+		instructions: `How far does the change in note "${note.id}" reach?`,
+		criteria: "local: one function or file. module: a whole module or several files. contract: a public interface other code or users depend on."
+	},
+	{
+		id: `${note.id}.newConcept`,
+		primitive: "noul",
+		instructions: `Does the change in note "${note.id}" introduce a concept new to this codebase — a new abstraction, entity or term? Judge from the evidence, never a glossary; reusing or extending an existing concept is not new.`,
+		criteria: "yes: a genuinely new concept. no: reuses or extends an existing one."
+	}
+];
+/**
+* One judge rest: a verdict per unforced note (a forced note is asked
+* nothing) plus four severity answers. Dismissing a note is the risky
+* direction, so only a confident non-`edit` verdict on uncut evidence counts;
+* a cut, unanswered or below-floor note is an `edit`. Severity answers on a
+* non-`edit` note are ignored. A confident `could` edit becomes `defer`.
+*/
+const triage$1 = (severities) => async (notes) => {
+	const asked = notes.filter((n) => !n.forced);
+	const judgment = asked.length === 0 ? {
+		answers: {},
+		truncated: []
+	} : await judge("review.triage", {
+		questions: asked.flatMap((n) => [verdictQuestion(n), ...severityQuestions(n)]),
+		evidence: Object.fromEntries(asked.map((n) => [n.id, `Anchor: ${n.anchor}\nReviewer's text: ${n.before}\nHuman's text: ${n.text}`])),
 		message: buildReviewTriageMessage(),
 		label: "Judging each note"
 	});
+	const { answers, truncated } = judgment;
 	const minP = numeric(vars.reviewNoteActionable, Infinity);
+	const severityMinP = numeric(vars.reviewSeverityMinP, Infinity);
+	severities.clear();
 	return new Map(notes.map((n) => {
-		const verdict = VERDICTS.find((v) => v !== "edit" && answered(answers[n.id], v, minP));
-		return [n.id, truncated.includes(n.id) || verdict === void 0 ? "edit" : verdict];
+		const verdict = n.forced ? void 0 : VERDICTS.find((v) => v !== "edit" && answered(answers[n.id], v, minP));
+		if (verdict !== void 0 && !truncated.includes(n.id)) return [n.id, verdict];
+		const severity = severityOf(n, judgment, severityMinP);
+		severities.set(n.id, severity);
+		return [n.id, severity.tier === "could" ? "defer" : "edit"];
 	}));
 };
 const isCode = (path) => path !== ".gtd" && !path.startsWith(".gtd/");
@@ -37556,30 +37695,59 @@ const isCode = (path) => path !== ".gtd" && !path.startsWith(".gtd/");
 * another planning lap, questions are answered in place, nits fixed in one
 * batch, praise dropped.
 */
-const review$1 = (base, escalations = { rounds: 0 }, frozen) => review$2(base, {
-	file: REVIEW,
-	feedback: REQUIREMENTS,
-	isCode,
-	reviewing,
-	fixRisks: (risks) => guarded(frozen, () => fixRisks(risks), "review")(),
-	keepGreen: () => healthy(guarded(frozen, fixCheck, "review"), { escalations }),
-	awaitReview,
-	reviewMissing,
-	collecting,
-	triage: triage$1,
-	answerQuestions: answerReviewQuestions,
-	fixNits: (notes) => guarded(frozen, () => fixNits(notes), "review")(),
-	close: closeReview,
-	captures: {
-		edits: reviewEditsCapture,
-		notes: reviewNotesCapture,
-		editNotes: reviewEditNotesCapture
-	},
-	refusals: {
-		deleted: "gtd land: review-doc: .gtd/REVIEW.md was deleted — restore it, or leave a note (or edit code) to request changes.",
-		unmatched: "gtd land: no declared pattern matches the pending changes — write .gtd/REQUIREMENTS.md from the feedback, or change nothing when it asks for nothing"
-	}
-});
+const review$1 = (base, escalations = { rounds: 0 }, frozen) => {
+	const severities = /* @__PURE__ */ new Map();
+	let deferred = [];
+	return review$2(base, {
+		file: REVIEW,
+		feedback: REQUIREMENTS,
+		isCode,
+		reviewing: (b, carry) => {
+			deferred = [];
+			return reviewing(b, carry);
+		},
+		fixRisks: (risks) => guarded(frozen, () => fixRisks(risks), "review")(),
+		keepGreen: () => healthy(guarded(frozen, fixCheck, "review"), { escalations }),
+		awaitReview: (b) => {
+			const notes = deferred;
+			deferred = [];
+			return notes.length > 0 ? awaitReview(b, buildReviewAwaitAfterDeferMessage(b, notes), true) : awaitReview(b);
+		},
+		reviewMissing,
+		collecting,
+		triage: triage$1(severities),
+		defer: (notes) => {
+			deferred = notes.map((n) => ({
+				id: n.id,
+				anchor: n.anchor,
+				text: n.text,
+				label: severities.get(n.id).reason
+			}));
+			return deferNotes(deferred, head$1());
+		},
+		answerQuestions: answerReviewQuestions,
+		fixNits: (notes) => guarded(frozen, () => fixNits(notes), "review")(),
+		close: closeReview,
+		captures: {
+			edits: reviewEditsCapture,
+			notes: reviewNotesCapture,
+			editNotes: (round, edits, answeredAt) => reviewEditNotesCapture(round, edits.map((n, i) => ({
+				n,
+				i,
+				s: severities.get(n.id)
+			})).sort((x, y) => Number(x.s?.tier === "should") - Number(y.s?.tier === "should") || (x.s?.rank ?? 2) - (y.s?.rank ?? 2) || x.i - y.i).map(({ n, s }) => ({
+				id: n.id,
+				anchor: n.anchor,
+				text: n.forced ? n.text.replace(/^!\s*/, "") : n.text,
+				...s === void 0 ? {} : { label: s.reason }
+			})), answeredAt)
+		},
+		refusals: {
+			deleted: "gtd land: review-doc: .gtd/REVIEW.md was deleted — restore it, or leave a note (or edit code) to request changes.",
+			unmatched: "gtd land: no declared pattern matches the pending changes — write .gtd/REQUIREMENTS.md from the feedback, or change nothing when it asks for nothing"
+		}
+	});
+};
 /** The build tail: fix (when entered red), keep green, the quality lap, then human review since `base`. */
 const buildTail = (fixFirst, base, built) => tail(fixFirst, (escalations, frozen) => review$1(base, escalations, frozen), built);
 //#endregion
@@ -37673,6 +37841,7 @@ const access = (vars) => ({
 	architecture: { write: [".gtd/REQUIREMENTS.md"] },
 	"architecture.decompose": { write: [".gtd/packages/**", ".gtd/ARCHITECTURE.md"] },
 	"build.review": { write: [".gtd/REVIEW.md"] },
+	"build.review.defer": { write: [".gtd/TODO.md"] },
 	"build.review.fix.nits": {},
 	"build.review.fix.risks": {},
 	...lensScopes("build.quality", lensesOf(vars.qualityReviews ?? ""), () => ({ write: [] }))
@@ -37749,4 +37918,4 @@ var workflows_default = feature;
 */
 const doors = {};
 //#endregion
-export { ARCHITECTURE, ESCALATION, FEEDBACK, FIX_CAP, QUALITY, REQUIREMENTS, REVIEW, REVIEW_ORIG, SCENARIO_PACKAGE, SETUP, ShippedOptions, access, afterTail, agentWithSkills, answerProductQuestions, answerReviewQuestions, answerTechnicalQuestions, architecture, author, awaitReview, base, baseline, build, buildTail, builtInLenses, closeReview, coder, collecting, declaredTests, decompose, workflows_default as default, defaults, describeEscalation, design, doors, driftedScenarios, envDefaults, escalate, escalation, escalationExhausted, fastSuiteGuard, feature, fix, fixCheck, fixFlow, fixNits, fixQuality, fixQualityFindings, fixReviewNotes, fixRisks, fixSuite, freezeScenarios, gate, guarded, handOffReview, handOffTail, healthy, holdWording, lensesOf, nextPackage, ordinaryStart, packageItem, packages, planAndBuild, planner, qualityLap, reUnwind, requireDeclaredTests, retryQuestion, review, reviewFlow, reviewMissing, reviewQuality, reviewing, scenarioText, skills, steering, summary, tail, threads, triage, unwind, wordingDrift };
+export { ARCHITECTURE, ESCALATION, FEEDBACK, FIX_CAP, QUALITY, REQUIREMENTS, REVIEW, REVIEW_ORIG, SCENARIO_PACKAGE, SETUP, ShippedOptions, access, afterTail, agentWithSkills, answerProductQuestions, answerReviewQuestions, answerTechnicalQuestions, architecture, author, awaitReview, base, baseline, build, buildTail, builtInLenses, closeReview, coder, collecting, declaredTests, decompose, workflows_default as default, defaults, deferNotes, describeEscalation, design, doors, driftedScenarios, envDefaults, escalate, escalation, escalationExhausted, fastSuiteGuard, feature, fix, fixCheck, fixFlow, fixNits, fixQuality, fixQualityFindings, fixReviewNotes, fixRisks, fixSuite, freezeScenarios, gate, guarded, handOffReview, handOffTail, healthy, holdWording, lensesOf, nextPackage, ordinaryStart, packageItem, packages, planAndBuild, planner, qualityLap, reUnwind, requireDeclaredTests, retryQuestion, review, reviewFlow, reviewMissing, reviewQuality, reviewing, scenarioText, skills, steering, summary, tail, threads, triage, unwind, wordingDrift };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmelab/gtd",
-  "version": "24.2.0",
+  "version": "24.4.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

@@ -926,6 +926,60 @@ describe("parseArgv — doors", () => {
   })
 })
 
+describe("parseArgv — gtd history", () => {
+  const parse = (...args: string[]) => parseArgv(["node", "gtd.js", ...args])
+  const usage = (plan: CliPlan): string => (plan.kind === "usage" ? plan.message : "")
+
+  it("history list / show <ref> / fetch parse to their commands", () => {
+    expect(parse("history", "list")).toMatchObject({
+      kind: "command",
+      command: { kind: "historyList" },
+    })
+    expect(parse("history", "show", "feat/x")).toMatchObject({
+      kind: "command",
+      command: { kind: "historyShow", ref: "feat/x" },
+    })
+    expect(parse("history", "fetch")).toMatchObject({
+      kind: "command",
+      command: { kind: "historyFetch", remote: "origin" },
+    })
+    expect(parse("history", "fetch", "upstream")).toMatchObject({
+      command: { kind: "historyFetch", remote: "upstream" },
+    })
+  })
+
+  it("bare history and an unknown subcommand are usage errors naming list, show, fetch", () => {
+    for (const args of [["history"], ["history", "nope"]]) {
+      const message = usage(parse(...args))
+      expect(message).toContain("list")
+      expect(message).toContain("show")
+      expect(message).toContain("fetch")
+    }
+  })
+
+  it("show without a ref, and extra arguments, are usage errors", () => {
+    expect(usage(parse("history", "show"))).toContain("missing ref")
+    expect(usage(parse("history", "show", "a", "b"))).toContain("too many arguments")
+    expect(usage(parse("history", "list", "x"))).toContain("too many arguments")
+    expect(usage(parse("history", "fetch", "a", "b"))).toContain("too many arguments")
+  })
+
+  it("--json is accepted for list and show, rejected for fetch", () => {
+    expect(parse("history", "list", "--json")).toMatchObject({ json: { kind: "document" } })
+    expect(parse("history", "show", "x", "--json=ended")).toMatchObject({
+      json: { kind: "select", path: "ended" },
+    })
+    expect(parse("history", "fetch", "--json").kind).toBe("usage")
+  })
+
+  it("help lists the three history rows", () => {
+    const help = renderHelp()
+    expect(help).toMatch(/^ {2}history list\b/m)
+    expect(help).toContain("history show <ref>")
+    expect(help).toContain("history fetch [remote]")
+  })
+})
+
 describe("standaloneKinds / needsOf", () => {
   it("pins the standalone kinds", () => {
     expect(standaloneKinds()).toEqual(["lsp", "check", "uncheck", "install", "loop", "judgeRun"])
@@ -950,6 +1004,9 @@ describe("standaloneKinds / needsOf", () => {
       "judgeAnswer",
       "door",
       "doors",
+      "historyList",
+      "historyShow",
+      "historyFetch",
     ] as const) {
       expect(needsOf(kind)).toBe("state")
     }