@pmelab/gtd 24.3.0 → 24.4.0

package/dist/workflow-kit.mjs

@@ -1,5 +1,5 @@
 import { changes, changesSince, hasThreadFor, head, read, refuse, requireReplies, requireThreadsClosed, scope } from "./flows.mjs";
-import { c as stripCodeThreads, d as reviewNotes, f as reviewRisks } from "./chunks/steering-D-PvRC5W.mjs";
+import { c as stripCodeThreads, d as reviewNotes, f as reviewRisks } from "./chunks/steering-DVILanVf.mjs";
 //#region src/workflow-kit/health.ts
 /** Hand a red suite that repeated attempts could not fix to a person, until `limit` rounds are spent. */
 const escalation = async (count, steps) => {
@@ -196,16 +196,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);
@@ -215,6 +216,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)));
@@ -228,7 +230,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. */
@@ -349,4 +351,4 @@ const reviewToHandOff = async (base, p) => {
 	}
 };
 //#endregion
-export { driftedScenarios, escalation, fixFindings, freezeScenarios, gate, healthy, holdWording, lensScopes, lensesOf, qualityLap, review, reviewToHandOff, scenarioText, untilSettled, wordingDrift };
+export { driftedScenarios, escalation, fixFindings, freezeScenarios, gate, healthy, holdWording, lensScopes, lensesOf, qualityLap, review, reviewToHandOff, routeNotes, scenarioText, untilSettled, wordingDrift };

package/dist/workflows/feature.mjs

@@ -1,6 +1,6 @@
 import { answered, changes, changesSince, glob, hasThreadFor, head, human, judge, numeric, read, refuse, removeScript, requireAnswers, requireProgress, requireReplies, requireRevert, requireThreadsClosed, restoreScript, revertScript, run, scope, start, vars } from "../flows.mjs";
 import { freezeScenarios, review as review$1 } from "../workflow-kit.mjs";
-import { $ as unwindFailure, A as architectureAuthorPrompt, B as designTriagePrompt, C as fixCheck, D as reviewing, E as reviewMissing, F as buildReviewFixNitsPrompt, G as packagesItemFixSuitePrompt, I as buildReviewTriageMessage, K as reviewEditNotesCapture, L as builderSystem, M as architectureGateAnswerMessage, N as buildReviewAnswerQuestionsPrompt, O as agentWithSkills, P as buildReviewCollectingPrompt, Q as unwindFailedMessage, R as designGateAnswerMessage, S as coder, T as planner, U as idleMessage, W as packagesItemBuildingPrompt, X as reviewerSystem, Y as reviewNotesCapture, Z as startGateBlockedMessage, _ as ARCHITECTURE, b as REVIEW, c as refusePendingHandOff, d as shipped, f as defaults, g as healthy, h as gate, i as skills, j as architectureDecomposePrompt, k as architectSystem, l as tail, n as summary, o as closeReview, p as envDefaults, q as reviewEditsCapture, r as access, t as steering, u as guarded, v as FEEDBACK, w as fixRisks, x as awaitReview, y as REQUIREMENTS, z as designSystem } from "../chunks/reserved-DJwU5C4z.mjs";
+import { $ as startGateBlockedMessage, A as architectureAuthorPrompt, B as designGateAnswerMessage, C as fixCheck, D as reviewing, E as reviewMissing, F as buildReviewCollectingPrompt, G as idleMessage, H as designTriagePrompt, I as buildReviewFixNitsPrompt, J as reviewEditNotesCapture, K as packagesItemBuildingPrompt, L as buildReviewTriageMessage, M as architectureGateAnswerMessage, N as buildReviewAnswerQuestionsPrompt, O as agentWithSkills, P as buildReviewAwaitAfterDeferMessage, Q as reviewerSystem, R as builderSystem, S as coder, T as planner, V as designSystem, Y as reviewEditsCapture, Z as reviewNotesCapture, _ as ARCHITECTURE, b as REVIEW, c as refusePendingHandOff, d as shipped, et as unwindFailedMessage, f as defaults, g as healthy, h as gate, i as skills, j as architectureDecomposePrompt, k as architectSystem, l as tail, n as summary, o as closeReview, p as envDefaults, q as packagesItemFixSuitePrompt, r as access, t as steering, tt as unwindFailure, u as guarded, v as FEEDBACK, w as fixRisks, x as awaitReview, y as REQUIREMENTS, z as deferNotesScript } from "../chunks/reserved-B9pG93Fc.mjs";
 //#region src/workflows/feature/steps.ts
 /** Turn the sketch since `base` into `.gtd/REQUIREMENTS.md`. */
 const triage = (base) => agentWithSkills("triage", designTriagePrompt(base), {
@@ -71,6 +71,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. */
@@ -194,23 +199,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"]
+};
+/**
+* Deferring is the risky direction: anything unanswered, unrecognised, cut or
+* below `minP` is `critical`, never `could`.
+*/
+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, one verdict per note. Dismissing a note is the risky
+* 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`, and a blank floor makes
-* every note one.
+* 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 = 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 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/");
@@ -220,30 +308,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 = (base, escalations = { rounds: 0 }, frozen) => review$1(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 = (base, escalations = { rounds: 0 }, frozen) => {
+	const severities = /* @__PURE__ */ new Map();
+	let deferred = [];
+	return review$1(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());
+		},
+		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(base, escalations, frozen), built);
 //#endregion
@@ -312,4 +429,4 @@ const feature = shipped(ordinaryStart);
 //#region src/workflows/feature/index.ts
 var feature_default = feature;
 //#endregion
-export { SCENARIO_PACKAGE, access, afterTail, answerProductQuestions, answerReviewQuestions, answerTechnicalQuestions, architecture, author, build, buildTail, collecting, declaredTests, decompose, feature_default as default, defaults, design, envDefaults, feature, fixNits, fixSuite, nextPackage, ordinaryStart, packageItem, packages, planAndBuild, reUnwind, requireDeclaredTests, skills, steering, summary, triage, unwind };
+export { SCENARIO_PACKAGE, access, afterTail, answerProductQuestions, answerReviewQuestions, answerTechnicalQuestions, architecture, author, build, buildTail, collecting, declaredTests, decompose, feature_default as default, defaults, deferNotes, design, envDefaults, feature, fixNits, fixSuite, nextPackage, ordinaryStart, packageItem, packages, planAndBuild, reUnwind, requireDeclaredTests, skills, steering, summary, triage, unwind };

package/dist/workflows/fix.mjs

@@ -1,6 +1,6 @@
 import { read, refuse, removeScript, run, scope, start } from "../flows.mjs";
-import { d as reviewNotes, f as reviewRisks } from "../chunks/steering-D-PvRC5W.mjs";
-import { H as fixReviewNotesPrompt, O as agentWithSkills, S as coder, V as finisherSystem, a as REVIEW_ORIG, b as REVIEW, d as shipped, f as defaults, i as skills, m as baseline, n as summary, p as envDefaults, r as access, s as handOffTail, t as steering } from "../chunks/reserved-DJwU5C4z.mjs";
+import { d as reviewNotes, f as reviewRisks } from "../chunks/steering-DVILanVf.mjs";
+import { O as agentWithSkills, S as coder, U as finisherSystem, W as fixReviewNotesPrompt, a as REVIEW_ORIG, b as REVIEW, d as shipped, f as defaults, i as skills, m as baseline, n as summary, p as envDefaults, r as access, s as handOffTail, t as steering } from "../chunks/reserved-B9pG93Fc.mjs";
 //#region src/workflows/fix/fix.ts
 /**
 * Fix every note a human left in a handed-off `.gtd/REVIEW.md` and every

package/dist/workflows/review.mjs

@@ -1,5 +1,5 @@
 import { start } from "../flows.mjs";
-import { J as reviewGateBlockedMessage, c as refusePendingHandOff, d as shipped, f as defaults, h as gate, i as skills, n as summary, p as envDefaults, r as access, s as handOffTail, t as steering } from "../chunks/reserved-DJwU5C4z.mjs";
+import { X as reviewGateBlockedMessage, c as refusePendingHandOff, d as shipped, f as defaults, h as gate, i as skills, n as summary, p as envDefaults, r as access, s as handOffTail, t as steering } from "../chunks/reserved-B9pG93Fc.mjs";
 //#region src/workflows/review/review.ts
 /**
 * Pure review of everything since `reviewBase`: a green gate, the quality