@pmelab/gtd 29.2.7 → 29.3.1

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "gtd",
-  "version": "29.2.7",
+  "version": "29.3.1",
   "description": "Drive the gtd loop inside Claude Code: agent turns run as subagents, gtd decides every beat",
   "author": {
     "name": "Philipp Melab"

package/README.md

@@ -341,16 +341,20 @@ wait for the next rest. When the process finishes, Claude offers to squash it
 and open its pull request(s) (or run `/gtd ship`; `GTD_SHIP_MODE` picks one
 stacked pull request per slice or one commit per slice, see the
 [driver doc](docs/driver.md)); a process started for an issue ships with
-`Closes #N` on its top pull request; a closed pull request whose branch was
-deleted from origin is left behind and a new one opens; re-running `/gtd ship`
-after a lower stacked pull request merged restacks the rest (it refuses, with
-nothing changed, when that pull request merged anywhere but the default branch
-(unless into a lower slice branch before that one merged into it), a slice
-branch is checked out in another worktree, an unrelated local branch sits inside
-the rebased commits, or a slice's change is already upstream; a failed rebase is
-rolled back). A process can change hands at any gate: ask Claude to hand it off
-(or run `/gtd throw @dev`) and it opens a draft pull request assigned to them,
-and `/gtd catch <pr>` picks it up exactly where it waits, so whoever wrote the
+`Closes #N` on its top pull request; a later process on an already-stacked
+branch, such as review fixes, lands one commit per slice on the top pull request
+and keeps the stack; a closed pull request whose branch was deleted from origin
+is left behind and a new one opens; re-running `/gtd ship` after a lower stacked
+pull request merged restacks the rest (it refuses, with nothing changed, when
+that pull request merged anywhere but the default branch (unless into a lower
+slice branch before that one merged into it), a slice branch is checked out in
+another worktree, an unrelated local branch sits inside the rebased commits, or
+a slice's change is already upstream; a failed rebase is rolled back; to tear a
+stack down from its worktree, delete the top branch with
+`git push origin --delete`, since `gh pr close --delete-branch` cannot). A
+process can change hands at any gate: ask Claude to hand it off (or run
+`/gtd throw @dev`) and it opens a draft pull request assigned to them, and
+`/gtd catch <pr>` picks it up exactly where it waits, so whoever wrote the
 requirements can hand the architecture to someone else. Ship, hand-off and throw
 answer at once and run in the background, with progress on the status line; they
 report by waking Claude, a toast, a transcript line and a push notification, and
@@ -607,8 +611,9 @@ means `high`. Each lap lands a `Gtd-Mark: risk-tier=<low|high>` trailer and a
 lap's only. Its "needs a human reviewer" line for `high` is advisory, not a
 gate.
 
-A `gtd.config.ts` call to `buildTail` that fits neither call form is rejected;
-see [docs/configuration.md](docs/configuration.md).
+A `gtd.config.ts` call to `buildTail` or `tail` that fits neither call form is
+rejected; `tail`'s positional form is deprecated for `tail(finish, options?)`.
+See [docs/configuration.md](docs/configuration.md).
 
 ### Rolling out and cleaning up release flags
 

package/claude/hooks/ship.ts

@@ -495,8 +495,7 @@ async function squash(
   if (!msgs.ok) return msgs
   const { fulls, history } = msgs
   const warn = () => (mode === "commits" && many ? rebaseWarning(io) : undefined)
-  if (resume?.links)
-    return squashOntoStack(io, git, ok, groups[0]!, fulls[0]!, history, resume, isDry, tip)
+  if (resume?.links) return squashOntoStack(io, git, ok, groups, fulls, history, resume, isDry, tip)
   if (isDry)
     return dryRun(
       groups,
@@ -552,18 +551,21 @@ async function stackReads(
   mode: ShipMode,
 ): Promise<Resumed | string | undefined> {
   if (mode !== "stack") return undefined
-  if (groups.length > 1) return await stackPrecheck(io, git, ok, branch, baseBranch, groups)
+  if (groups.length > 1)
+    return await stackPrecheck(io, git, ok, branch, baseBranch, groups, base, isDry)
   return resumable(io, git, ok, branch, baseBranch, isDry, base)
 }
 
-// One slice on a recorded stack: its commit becomes the new top of the stack, and
-// the record, including the recorded top the missing-branch fallbacks read, stays.
+// A process on a recorded stack — a re-ship, or a follow-up such as review fixes —
+// lands its slice commits on the top branch, so they join the top pull request.
+// The record, including the recorded top the missing-branch fallbacks and the
+// restack read, stays.
 async function squashOntoStack(
   io: ShipIo,
   git: Git,
   ok: Ok,
-  group: Group,
-  full: string,
+  groups: Group[],
+  fulls: string[],
   history: string | undefined,
   resume: Resumed,
   isDry: boolean,
@@ -572,16 +574,16 @@ async function squashOntoStack(
   const links = resume.links!
   const top = links.length - 1
   if (isDry) {
-    const messages = links.map((_, i) => (i === top ? full : ""))
-    return {
-      ...dryRun([group], [full], history, undefined, links),
-      messages,
-      restack: resume.restack,
-    }
+    // the follow-up's slice names are not stack slices: no [name] headers
+    const messages = links.map((_, i) => (i === top ? fulls.join("\n\n") : ""))
+    return { ok: true as const, text: "", history, stack: links, messages, restack: resume.restack }
   }
   const pushed = await pushHistory(io, history)
   if (pushed) return fail(pushed)
-  const one = await commitSquash(io, git, ok, group.base, full)
+  const one =
+    groups.length === 1
+      ? await commitSquash(io, git, ok, groups[0]!.base, fulls[0]!)
+      : await commitChain(io, git, ok, groups, fulls)
   if (!one.ok) return one
   const failed = await resume.revive?.()
   if (failed) return fail(failed)
@@ -709,24 +711,30 @@ async function takenSlice(git: Git, ok: Ok, branch: string, groups: Group[], dea
   return undefined
 }
 
-async function recordedRefusal(
+// A live record takes the process onto its top branch; a dead one (no links)
+// leaves the way open for a fresh stack.
+async function liveRecord(
   io: ShipIo,
   git: Git,
   ok: Ok,
   branch: string,
   baseBranch: string,
   recorded: string[],
-): Promise<string | undefined> {
-  // The staleness test a resume uses: a dead record is not a live stack.
+  base: string,
+  isDry: boolean,
+): Promise<Resumed | string> {
+  // The staleness test a resume uses, without the restack's origin and worktree
+  // reads: a dead record is not a live stack, and its dropped-record line is
+  // silenced since a fresh stack replaces it.
   const quiet = { ...io, log: () => {} }
   const found = await resumable(quiet, git, ok, branch, baseBranch, true, "HEAD", false)
   // resumable refuses (a missing branch, a closed slice PR) before it tests the
   // chain; only a record that still chains to HEAD may refuse a fresh stack.
-  if (typeof found === "string")
-    return (await chainsToHead(git, ok, branch, recorded)) ? found : undefined
-  if (!found.forget)
-    return `${branch} already has a recorded stack (${recorded.join(", ")}); nothing changed. Ship with GTD_SHIP_MODE=commits, or run git config --local --unset branch.${branch}.gtdStack and git config --local --unset branch.${branch}.gtdStackTop, delete or rename the ${branch}-<slice> branches, then ship again.`
-  return undefined
+  if (typeof found === "string") return (await chainsToHead(git, ok, branch, recorded)) ? found : {}
+  // `forget` with links is a live stack a restack ends, not a dead record.
+  if (!found.links) return {}
+  // Live: any refusal of the full resume (origin, worktrees) stands.
+  return resumable(io, git, ok, branch, baseBranch, isDry, base)
 }
 
 async function chainsToHead(git: Git, ok: Ok, branch: string, recorded: string[]) {
@@ -760,11 +768,14 @@ async function stackPrecheck(
   branch: string,
   baseBranch: string,
   groups: Group[],
-): Promise<string | undefined> {
+  base: string,
+  isDry: boolean,
+): Promise<Resumed | string | undefined> {
   const recorded = names(await git("config", "--local", "--get", STACK_KEY(branch)))
   if (recorded.length) {
-    const refused = await recordedRefusal(io, git, ok, branch, baseBranch, recorded)
-    if (refused) return refused
+    const live = await liveRecord(io, git, ok, branch, baseBranch, recorded, base, isDry)
+    // Without links the squash builds a fresh stack, so the collision checks still run.
+    if (typeof live === "string" || live?.links) return live
   }
   const retired = names(await git("config", "--local", "--get", RETIRED_KEY(branch)))
   const taken = await takenSlice(git, ok, branch, groups, [...recorded, ...retired])

package/dist/chunks/{tail-BOJYJctg.mjs → tail-CLyE5VFR.mjs}

@@ -26,13 +26,31 @@ const closeReview = (round) => run("review.closing", removeScript([REVIEW, REVIE
 const refusePendingHandOff = () => {
 	if (read(".gtd/REVIEW.orig.md") !== void 0) refuse(`gtd: ${REVIEW_ORIG} is a pending hand-off — run \`gtd door fix\`, or remove ${REVIEW} and ${REVIEW_ORIG}.`);
 };
-/**
-* The build tail: fix (when entered red), keep green, the quality lap, then
-* `finish` — the human review, as the calling workflow runs it. `green`: the
-* caller just left the full suite green (the package loop), so no run opens it.
-* `guardRests: false` leaves the escalation's human rests unguarded.
-*/
-const tail = (fixFirst, finish, green = false, guard, lenses, guardRests = true, lensBase, rules) => scope("build", async () => {
+function tail(first, second, ...rest) {
+	const form = tailForm(first, second, rest);
+	if (form === void 0) return Promise.reject(/* @__PURE__ */ new Error("tail takes tail(finish, options?) or the deprecated tail(fixFirst, finish, green?, guard?, lenses?, guardRests?, lensBase?, rules?); this call fits neither"));
+	const [finish, options] = form;
+	return runTail(finish, options);
+}
+const isOptionalObject = (value) => value == null || typeof value === "object" && !Array.isArray(value) && typeof value.then !== "function";
+const tailForm = (first, second, rest) => {
+	if (typeof second === "function" && typeof first !== "function") {
+		const [green, guard, lenses, guardRests, lensBase, rules] = rest;
+		return [second, {
+			fixFirst: first,
+			green,
+			guard,
+			lenses,
+			guardRests,
+			lensBase,
+			rules
+		}];
+	}
+	if (typeof first === "function" && isOptionalObject(second) && rest.every((v) => v == null)) return [first, second ?? {}];
+};
+const runTail = (finish, options) => scope("build", async () => {
+	const { guard, lenses, lensBase, rules } = options;
+	const guardRests = options.guardRests === void 0 ? true : options.guardRests;
 	const escalations = { rounds: 0 };
 	const fix = () => fixCheck(rules);
 	const repair = async () => {
@@ -45,8 +63,8 @@ const tail = (fixFirst, finish, green = false, guard, lenses, guardRests = true,
 			rules
 		});
 	};
-	if (fixFirst) await repair();
-	else if (!green) await healthy(fix, {
+	if (options.fixFirst) await repair();
+	else if (!options.green) await healthy(fix, {
 		escalations,
 		guard,
 		guardRests,
@@ -83,6 +101,9 @@ const handOffReview = (base, escalations, guard) => reviewToHandOff(base, {
 	deleted: "gtd land: review-doc: .gtd/REVIEW.md was deleted — restore it, or leave a note to hand to fix."
 });
 /** The tail the review and fix workflows run: ends at the hand-off review since `base`. */
-const handOffTail = (fixFirst, base, guard) => tail(fixFirst, (escalations) => handOffReview(base, escalations, guard), false, guard);
+const handOffTail = (fixFirst, base, guard) => tail((escalations) => handOffReview(base, escalations, guard), {
+	fixFirst,
+	guard
+});
 //#endregion
-export { tail as a, refusePendingHandOff as i, closeReview as n, handOffTail as r, REVIEW_ORIG as t };
+export { refusePendingHandOff as a, isOptionalObject as i, closeReview as n, tail as o, handOffTail as r, REVIEW_ORIG as t };

package/dist/workflows/cleanup.mjs

@@ -1,6 +1,6 @@
 import { agent, changes, glob, read, refuse, scope, start, vars } from "../flows.mjs";
 import { _t as registryEntry, a as flagShipped, dt as defaults, ft as envDefaults, ht as flagReferences, i as skills, n as summary, r as access, t as steering, vt as requireFlag, y as coder } from "../chunks/reserved-Dmpg6dAp.mjs";
-import { i as refusePendingHandOff, r as handOffTail } from "../chunks/tail-BOJYJctg.mjs";
+import { a as refusePendingHandOff, r as handOffTail } from "../chunks/tail-CLyE5VFR.mjs";
 //#region src/workflows/cleanup/cleanup.ts
 const removingPrompt = (name, registry) => `Clean up the release flag "${name}", which is default-on: delete its entry in ${registry}, and remove every \`GTD_FLAG_${name.toUpperCase()}\` check from the shipped sources. Keep the flag-on path; delete code only the off path reached, including tests that pin the off path.`;
 const cleanupFlow = async () => {

package/dist/workflows/feature.mjs

@@ -1,7 +1,7 @@
 import { answered, changes, changesSince, glob, hasThreadFor, head, human, judge, judgeDiffShape, kept, mark, matches, numeric, quote, read, refuse, removeScript, requireAnswers, requireProgress, requireReplies, requireRevert, requireThreadsClosed, restoreScript, revertScript, run, scope, slice, start, vars } from "../flows.mjs";
 import { lensesOf, review as review$1 } from "../workflow-kit.mjs";
 import { $ as refactorFixPrompt, A as architectureDecomposePrompt, B as designSystem, C as planner, D as agentWithSkills, E as reviewing, F as buildReviewFixNitsPrompt, G as idleMessage, I as buildReviewTriageMessage, J as naivePassPrompt, K as implementBuildingPrompt, L as builderSystem, M as buildReviewAnswerQuestionsPrompt, N as buildReviewAwaitAfterDeferMessage, O as architectSystem, P as buildReviewCollectingPrompt, Q as refactorDroppedRefusal, R as deferNotesScript, S as fixRisks, V as designTriagePrompt, X as packagesItemFixSuitePrompt, Y as packagesItemBuildingPrompt, Z as refactorBuildingPrompt, _ as REVIEW, at as reviewerSystem, b as fixCheck, ct as startGateBlockedMessage, d as healthy, dt as defaults, et as refactorRules, f as ARCHITECTURE, ft as envDefaults, g as REQUIREMENTS, h as REFACTOR, i as skills, it as reviewNotesCapture, j as architectureGateAnswerMessage, k as architectureAuthorPrompt, l as gate, lt as unwindFailedMessage, n as summary, nt as reviewEditsCapture, o as shipped, ot as seamByHandMessage, p as FEEDBACK, pt as testFileGlobs, q as implementFixPrompt, r as access, st as seamSteerMessage, t as steering, tt as reviewEditNotesCapture, u as guarded, ut as unwindFailure, v as awaitReview, w as reviewMissing, y as coder, z as designGateAnswerMessage } from "../chunks/reserved-Dmpg6dAp.mjs";
-import { a as tail, i as refusePendingHandOff, n as closeReview } from "../chunks/tail-BOJYJctg.mjs";
+import { a as refusePendingHandOff, i as isOptionalObject, n as closeReview, o as tail } from "../chunks/tail-CLyE5VFR.mjs";
 //#region src/workflows/shared/fences.ts
 const markFenced = (text) => {
 	let fence;
@@ -479,10 +479,8 @@ function buildTail(first, second, ...rest) {
 	const options = callForm(first, second, rest);
 	if (options === void 0) return Promise.reject(/* @__PURE__ */ new Error("buildTail takes buildTail(base, options?) or the deprecated buildTail(fixFirst, base, green?, options?); this call fits neither"));
 	const [base, form] = options;
-	const { fixFirst, green, ...reviewOptions } = form;
-	return tail(fixFirst ?? false, (escalations) => review(base, escalations, reviewOptions), green ?? false, form.guard, form.lenses, form.guardRests, form.lensBase, form.rules);
+	return tail((escalations) => review(base, escalations, form), form);
 }
-const isOptionalObject = (value) => value == null || typeof value === "object" && !Array.isArray(value) && typeof value.then !== "function";
 const isOptionalBoolean = (value) => value == null || typeof value === "boolean";
 const legacyForm = (fixFirst, base, green, options) => isOptionalBoolean(fixFirst) && isOptionalBoolean(green) && isOptionalObject(options) ? [base, {
 	...options,
@@ -866,7 +864,7 @@ const planAndBuild = async (firstBase, firstLap = "first") => {
 		await packages();
 		const outcome = await buildTail(base, {
 			green: true,
-			...lap === "first" ? {} : { lap }
+			lap
 		});
 		if (outcome.verdict === "signoff") return;
 		await reUnwind(outcome);
@@ -903,7 +901,7 @@ const featureFeedback = async (first, lensBase) => {
 		outcome = await buildTail(outcome.base, {
 			green: true,
 			lap: "feedback",
-			...lensBase === void 0 ? {} : { lensBase }
+			lensBase
 		});
 	}
 };

package/dist/workflows/fix.mjs

@@ -1,7 +1,7 @@
 import { read, refuse, removeScript, run, scope, start } from "../flows.mjs";
 import { d as reviewNotes, f as reviewRisks } from "../chunks/steering-DVILanVf.mjs";
 import { D as agentWithSkills, H as finisherSystem, U as fixReviewNotesPrompt, _ as REVIEW, dt as defaults, ft as envDefaults, i as skills, n as summary, o as shipped, r as access, s as baseline, t as steering, y as coder } from "../chunks/reserved-Dmpg6dAp.mjs";
-import { r as handOffTail, t as REVIEW_ORIG } from "../chunks/tail-BOJYJctg.mjs";
+import { r as handOffTail, t as REVIEW_ORIG } from "../chunks/tail-CLyE5VFR.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,6 +1,6 @@
 import { start } from "../flows.mjs";
 import { dt as defaults, ft as envDefaults, i as skills, l as gate, n as summary, o as shipped, r as access, rt as reviewGateBlockedMessage, t as steering } from "../chunks/reserved-Dmpg6dAp.mjs";
-import { i as refusePendingHandOff, r as handOffTail } from "../chunks/tail-BOJYJctg.mjs";
+import { a as refusePendingHandOff, r as handOffTail } from "../chunks/tail-CLyE5VFR.mjs";
 //#region src/workflows/review/review.ts
 /**
 * Pure review of everything since `reviewBase`: a green gate, the quality

package/dist/workflows.mjs

@@ -37791,13 +37791,31 @@ const closeReview = (round) => run("review.closing", removeScript([REVIEW, REVIE
 const refusePendingHandOff = () => {
 	if (read(".gtd/REVIEW.orig.md") !== void 0) refuse(`gtd: ${REVIEW_ORIG} is a pending hand-off — run \`gtd door fix\`, or remove ${REVIEW} and ${REVIEW_ORIG}.`);
 };
-/**
-* The build tail: fix (when entered red), keep green, the quality lap, then
-* `finish` — the human review, as the calling workflow runs it. `green`: the
-* caller just left the full suite green (the package loop), so no run opens it.
-* `guardRests: false` leaves the escalation's human rests unguarded.
-*/
-const tail = (fixFirst, finish, green = false, guard, lenses, guardRests = true, lensBase, rules) => scope("build", async () => {
+function tail(first, second, ...rest) {
+	const form = tailForm(first, second, rest);
+	if (form === void 0) return Promise.reject(/* @__PURE__ */ new Error("tail takes tail(finish, options?) or the deprecated tail(fixFirst, finish, green?, guard?, lenses?, guardRests?, lensBase?, rules?); this call fits neither"));
+	const [finish, options] = form;
+	return runTail(finish, options);
+}
+const isOptionalObject = (value) => value == null || typeof value === "object" && !Array.isArray(value) && typeof value.then !== "function";
+const tailForm = (first, second, rest) => {
+	if (typeof second === "function" && typeof first !== "function") {
+		const [green, guard, lenses, guardRests, lensBase, rules] = rest;
+		return [second, {
+			fixFirst: first,
+			green,
+			guard,
+			lenses,
+			guardRests,
+			lensBase,
+			rules
+		}];
+	}
+	if (typeof first === "function" && isOptionalObject(second) && rest.every((v) => v == null)) return [first, second ?? {}];
+};
+const runTail = (finish, options) => scope("build", async () => {
+	const { guard, lenses, lensBase, rules } = options;
+	const guardRests = options.guardRests === void 0 ? true : options.guardRests;
 	const escalations = { rounds: 0 };
 	const fix = () => fixCheck(rules);
 	const repair = async () => {
@@ -37810,8 +37828,8 @@ const tail = (fixFirst, finish, green = false, guard, lenses, guardRests = true,
 			rules
 		});
 	};
-	if (fixFirst) await repair();
-	else if (!green) await healthy(fix, {
+	if (options.fixFirst) await repair();
+	else if (!options.green) await healthy(fix, {
 		escalations,
 		guard,
 		guardRests,
@@ -37848,7 +37866,10 @@ const handOffReview = (base, escalations, guard) => reviewToHandOff(base, {
 	deleted: "gtd land: review-doc: .gtd/REVIEW.md was deleted — restore it, or leave a note to hand to fix."
 });
 /** The tail the review and fix workflows run: ends at the hand-off review since `base`. */
-const handOffTail = (fixFirst, base, guard) => tail(fixFirst, (escalations) => handOffReview(base, escalations, guard), false, guard);
+const handOffTail = (fixFirst, base, guard) => tail((escalations) => handOffReview(base, escalations, guard), {
+	fixFirst,
+	guard
+});
 //#endregion
 //#region src/workflows/shared/fences.ts
 const markFenced = (text) => {
@@ -38327,10 +38348,8 @@ function buildTail(first, second, ...rest) {
 	const options = callForm(first, second, rest);
 	if (options === void 0) return Promise.reject(/* @__PURE__ */ new Error("buildTail takes buildTail(base, options?) or the deprecated buildTail(fixFirst, base, green?, options?); this call fits neither"));
 	const [base, form] = options;
-	const { fixFirst, green, ...reviewOptions } = form;
-	return tail(fixFirst ?? false, (escalations) => review$1(base, escalations, reviewOptions), green ?? false, form.guard, form.lenses, form.guardRests, form.lensBase, form.rules);
+	return tail((escalations) => review$1(base, escalations, form), form);
 }
-const isOptionalObject = (value) => value == null || typeof value === "object" && !Array.isArray(value) && typeof value.then !== "function";
 const isOptionalBoolean = (value) => value == null || typeof value === "boolean";
 const legacyForm = (fixFirst, base, green, options) => isOptionalBoolean(fixFirst) && isOptionalBoolean(green) && isOptionalObject(options) ? [base, {
 	...options,
@@ -38714,7 +38733,7 @@ const planAndBuild = async (firstBase, firstLap = "first") => {
 		await packages();
 		const outcome = await buildTail(base, {
 			green: true,
-			...lap === "first" ? {} : { lap }
+			lap
 		});
 		if (outcome.verdict === "signoff") return;
 		await reUnwind(outcome);
@@ -38751,7 +38770,7 @@ const featureFeedback = async (first, lensBase) => {
 		outcome = await buildTail(outcome.base, {
 			green: true,
 			lap: "feedback",
-			...lensBase === void 0 ? {} : { lensBase }
+			lensBase
 		});
 	}
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmelab/gtd",
-  "version": "29.2.7",
+  "version": "29.3.1",
   "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/workflows/feature/feature.ts

@@ -49,7 +49,7 @@ export const planAndBuild = async (
     await design(base)
     await architecture()
     await packages()
-    const outcome = await buildTail(base, { green: true, ...(lap === "first" ? {} : { lap }) })
+    const outcome = await buildTail(base, { green: true, lap })
     if (outcome.verdict === "signoff") return
     await reUnwind(outcome)
     base = outcome.base
@@ -81,11 +81,7 @@ const featureFeedback = async (first: ReviewOutcome, lensBase?: string): Promise
     await design(outcome.base)
     const tier = riskTierOn() ? recordRisk() : undefined
     await implement({ tier, amend: true })
-    outcome = await buildTail(outcome.base, {
-      green: true,
-      lap: "feedback",
-      ...(lensBase === undefined ? {} : { lensBase }),
-    })
+    outcome = await buildTail(outcome.base, { green: true, lap: "feedback", lensBase })
   }
 }
 

package/src/workflows/feature/index.ts

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

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

@@ -17,7 +17,7 @@ import {
 } from "./review.js"
 import type { ReviewNote } from "../../steering/index.js"
 import * as bundled from "../index.js"
-import type { BuildTailOptions as PublicBuildTailOptions } from "./index.js"
+import type * as featureEntry from "./index.js"
 import { fixtureContext } from "../shared/text.fixture.js"
 import { toRequest } from "../../judges/index.js"
 
@@ -999,17 +999,38 @@ describe("BuildTailOptions.lensBase", () => {
       expect(names).not.toEqual([])
     })
 
-    // pins `| undefined` on BuildTailOptions under exactOptionalPropertyTypes (typecheck)
-    it("explicitly undefined fixFirst and green default like omitted ones", async () => {
+    // pins `| undefined` on every BuildTailOptions field under exactOptionalPropertyTypes (typecheck)
+    it("explicitly undefined options default like omitted ones", async () => {
       expect(
-        await requestNames(() => buildTail("base", { fixFirst: undefined, green: undefined })),
+        await requestNames(() =>
+          buildTail("base", {
+            fixFirst: undefined,
+            green: undefined,
+            guard: undefined,
+            guardRests: undefined,
+            lenses: undefined,
+            feedback: undefined,
+            fixAccess: undefined,
+            lensBase: undefined,
+            rules: undefined,
+            lap: undefined,
+          }),
+        ),
       ).toEqual(await requestNames(() => buildTail("base")))
     })
   })
 })
 
 // pins the public re-exports from the feature entry point and the published workflows entry
-export type _PublicBuildTailOptions = [PublicBuildTailOptions, bundled.BuildTailOptions]
+export type _PublicBuildTailOptions = [
+  featureEntry.BuildTailOptions,
+  featureEntry.FeedbackTarget,
+  featureEntry.ReviewRange,
+  bundled.BuildTailOptions,
+  bundled.FeedbackTarget,
+  bundled.ReviewRange,
+  bundled.TailOptions,
+]
 
 describe("buildTail without rules", () => {
   const RULES = "Change only these paths"

package/src/workflows/feature/review.ts

@@ -13,7 +13,7 @@ import {
 } from "../../flows/index.js"
 import type { ReviewNote } from "../../steering/index.js"
 import * as kit from "../../workflow-kit/index.js"
-import { guarded, healthy, type EscalationCount, type Guard } from "../shared/health.js"
+import { guarded, healthy, type EscalationCount } from "../shared/health.js"
 import {
   awaitReview,
   fixCheck,
@@ -23,7 +23,7 @@ import {
   reviewing,
   reviewMissing,
 } from "../shared/steps.js"
-import { closeReview, tail } from "../shared/tail.js"
+import { closeReview, isOptionalObject, tail, type TailOptions } from "../shared/tail.js"
 import * as t from "../shared/text.js"
 import { answerReviewQuestions, collecting, deferNotes, fixNits } from "./steps.js"
 
@@ -169,7 +169,7 @@ export const isCode = (path: string): boolean => path !== ".gtd" && !path.starts
 export const review = (
   base: string,
   escalations: EscalationCount = { rounds: 0 },
-  options: BuildTailOptions = {},
+  options: Omit<BuildTailOptions, "fixFirst" | "green"> = {},
 ): Promise<kit.ReviewOutcome> => {
   const { guard, guardRests, fixAccess, rules } = options
   const feedback: FeedbackTarget = options.feedback ?? {
@@ -255,26 +255,12 @@ export interface FeedbackTarget {
   readonly dropped?: (requested: kit.Requested) => string
 }
 
-export interface BuildTailOptions {
-  /** Fix first when entered red; default `false`. */
-  readonly fixFirst?: boolean | undefined
-  /** Asserts the tree is already green, so the tail skips keep-green; default `false`. */
-  readonly green?: boolean | undefined
-  /** Runs after every code-changing turn: fix-check, quality fix, risk fix, nit fix, escalation describe. */
-  readonly guard?: Guard
-  /** `false`: `guard` skips the escalation's human rests. */
-  readonly guardRests?: boolean
-  /** Quality-lap lenses; default `lensesOf(vars.qualityReviews)`. */
-  readonly lenses?: readonly string[]
-  readonly feedback?: FeedbackTarget
+export interface BuildTailOptions extends TailOptions {
+  readonly feedback?: FeedbackTarget | undefined
   /** Write access for the nit and risk fix turns; absent: the bundled `access` export decides. */
-  readonly fixAccess?: ScopeAccess
-  /** The commit the quality lap reviews from; absent: `start()`. */
-  readonly lensBase?: string
-  /** Appended to every fix and describe prompt of the tail. */
-  readonly rules?: string
+  readonly fixAccess?: ScopeAccess | undefined
   /** Absent: "first". */
-  readonly lap?: t.ReviewRange
+  readonly lap?: t.ReviewRange | undefined
 }
 
 /** The build tail: fix (when entered red), keep green unless `green`, the quality lap, then human review since `base`. */
@@ -301,26 +287,9 @@ export function buildTail(
     )
   }
   const [base, form] = options
-  const { fixFirst, green, ...reviewOptions } = form
-  return tail(
-    fixFirst ?? false,
-    (escalations) => review(base, escalations, reviewOptions),
-    green ?? false,
-    form.guard,
-    form.lenses,
-    form.guardRests,
-    form.lensBase,
-    form.rules,
-  )
+  return tail((escalations) => review(base, escalations, form), form)
 }
 
-// null reads as absent; an un-awaited Promise is a mistake, not options.
-const isOptionalObject = (value: unknown): value is BuildTailOptions | null | undefined =>
-  value == null ||
-  (typeof value === "object" &&
-    !Array.isArray(value) &&
-    typeof (value as { then?: unknown }).then !== "function")
-
 const isOptionalBoolean = (value: unknown): value is boolean | null | undefined =>
   value == null || typeof value === "boolean"
 

package/src/workflows/index.ts

@@ -6,7 +6,7 @@ import { feature } from "./feature/feature.js"
 export { threads, type ThreadInfo } from "../flows/index.js"
 export * from "./shared/reserved.js"
 export { FlagOptions, ShippedOptions } from "./shared/options.js"
-export { agentWithSkills } from "./shared/text.js"
+export { agentWithSkills, type ReviewRange } from "./shared/text.js"
 export * from "./shared/steps.js"
 export * from "./shared/health.js"
 export {
@@ -17,6 +17,7 @@ export {
   qualityLap,
   REVIEW_ORIG,
   tail,
+  type TailOptions,
 } from "./shared/tail.js"
 export { lensesOf } from "../workflow-kit/index.js"
 export * from "./feature/steps.js"
@@ -24,7 +25,12 @@ export * from "./feature/planning.js"
 export * from "./feature/packages.js"
 export * from "./feature/refactor.js"
 export * from "./feature/seam.js"
-export { buildTail, type BuildTailOptions, type ReviewOutcome } from "./feature/review.js"
+export {
+  buildTail,
+  type BuildTailOptions,
+  type FeedbackTarget,
+  type ReviewOutcome,
+} from "./feature/review.js"
 export * from "./feature/feature.js"
 export { base, review, reviewFlow } from "./review/review.js"
 export { fix, fixFlow, fixReviewNotes } from "./fix/fix.js"

package/src/workflows/shared/tail.test.ts

@@ -260,32 +260,147 @@ describe("the quality lap's lenses", () => {
 
   it("tail threads lensBase to every lens turn", async () => {
     await lap(() =>
-      tail(
-        false,
-        () => Promise.resolve(),
-        true,
-        undefined,
-        ["conventions", "correctness"],
-        true,
-        "BASE-SHA",
-      ),
+      tail(() => Promise.resolve(), {
+        green: true,
+        lenses: ["conventions", "correctness"],
+        lensBase: "BASE-SHA",
+      }),
     )
     expect(prompts).toHaveLength(2)
     for (const prompt of prompts) expect(prompt).toContain("from `BASE-SHA`")
   })
 
+  it("the deprecated form threads lensBase from its seventh slot", async () => {
+    await lap(() =>
+      tail(false, () => Promise.resolve(), true, undefined, ["conventions"], true, "BASE-SHA", "R"),
+    )
+    expect(prompts).toHaveLength(1)
+    expect(prompts[0]).toContain("from `BASE-SHA`")
+    expect(prompts[0]).not.toContain("from `R`")
+  })
+
   it("tail passes lenses to its lap and a guard after each lens turn", async () => {
     let guards = 0
     const log = await lap(() =>
-      tail(
-        false,
-        () => Promise.resolve(),
-        true,
-        () => void guards++,
-        ["conventions"],
-      ),
+      tail(() => Promise.resolve(), {
+        green: true,
+        guard: () => void guards++,
+        lenses: ["conventions"],
+      }),
     )
     expect(log).toEqual(["quality.conventions.reviewing"])
     expect(guards).toBe(1)
   })
 })
+
+describe("tail's call forms", () => {
+  class Stop extends Error {}
+  const requestNames = async (
+    call: () => Promise<unknown>,
+    names: string[] = [],
+  ): Promise<string[]> => {
+    installContext(
+      fixtureContext(
+        { vars: { qualityReviews: "correctness" } },
+        {
+          step: (request: StepRequest) => {
+            if (request.kind === "restart") return Promise.resolve()
+            names.push(`${request.kind}:${request.name}`)
+            if (request.kind === "agent") prompts.push(request.prompt)
+            if (names.length >= 4) throw new Stop()
+            return Promise.resolve()
+          },
+          pushScope: () => undefined,
+          popScope: () => undefined,
+          start: () => "START-SHA",
+        },
+      ),
+    )
+    await call().catch((error: unknown) => {
+      if (!(error instanceof Stop)) throw error
+    })
+    return names
+  }
+  const finish = () => Promise.resolve()
+
+  for (const [fixFirst, green] of [
+    [true, false],
+    [true, true],
+    [false, true],
+    [false, false],
+  ] as const) {
+    it(`the deprecated positional form matches the options form for fixFirst ${fixFirst}, green ${green}`, async () => {
+      const modern = await requestNames(() => tail(finish, { fixFirst, green }))
+      const legacy = await requestNames(() => tail(fixFirst, finish, green))
+      expect(legacy).toEqual(modern)
+    })
+  }
+
+  it("the deprecated form passes every positional on", async () => {
+    let guards = 0
+    const guard = () => void guards++
+    const modern = await requestNames(() =>
+      tail(finish, { green: true, guard, lenses: ["conventions"], guardRests: false }),
+    )
+    const modernGuards = guards
+    guards = 0
+    const legacy = await requestNames(() =>
+      tail(false, finish, true, guard, ["conventions"], false),
+    )
+    expect(legacy).toEqual(modern)
+    expect(guards).toBe(modernGuards)
+  })
+
+  it("the deprecated form threads rules from its eighth slot", async () => {
+    prompts.length = 0
+    await requestNames(() =>
+      tail(true, finish, false, undefined, [], true, "BASE-SHA", "RULES-TEXT"),
+    )
+    expect(prompts.some((p) => p.includes("RULES-TEXT"))).toBe(true)
+    expect(prompts.some((p) => p.includes("BASE-SHA"))).toBe(false)
+  })
+
+  it("the deprecated form still runs untyped flags as truthy or falsy", async () => {
+    expect(await requestNames(() => tail(1 as never, finish, 0 as never))).toEqual(
+      await requestNames(() => tail(finish, { fixFirst: true })),
+    )
+  })
+
+  it("reads an explicit undefined in every option as absent", async () => {
+    const absent = await requestNames(() => tail(finish))
+    const explicit = await requestNames(() =>
+      tail(finish, {
+        fixFirst: undefined,
+        green: undefined,
+        guard: undefined,
+        lenses: undefined,
+        guardRests: undefined,
+        lensBase: undefined,
+        rules: undefined,
+      }),
+    )
+    expect(explicit).toEqual(absent)
+  })
+
+  const fitsNeither: [string, () => Promise<unknown>][] = [
+    ["no finish", () => (tail as (...args: unknown[]) => Promise<unknown>)(false)],
+    ["a finish followed by a boolean", () => tail(finish, true as never)],
+    ["a finish followed by a function", () => tail(finish, finish as never)],
+    ["a finish followed by a Promise", () => tail(finish, Promise.resolve({}) as never)],
+    [
+      "a finish with a third argument",
+      () => (tail as (...args: unknown[]) => Promise<unknown>)(finish, {}, true),
+    ],
+  ]
+  for (const [label, call] of fitsNeither) {
+    it(`rejects ${label} before any step runs`, async () => {
+      const names: string[] = []
+      const rejected = expect(requestNames(call, names)).rejects
+      await rejected.toThrow("tail(finish, options?)")
+      await rejected.toThrow(
+        "tail(fixFirst, finish, green?, guard?, lenses?, guardRests?, lensBase?, rules?)",
+      )
+      expect(names).toEqual([])
+    })
+  }
+})

package/src/workflows/shared/tail.ts

@@ -70,23 +70,88 @@ export const refusePendingHandOff = (): void => {
   }
 }
 
+export interface TailOptions {
+  /** Fix first when entered red; default `false`. */
+  readonly fixFirst?: boolean | undefined
+  /** Asserts the tree is already green, so the tail skips keep-green; default `false`. */
+  readonly green?: boolean | undefined
+  /** Runs after every code-changing turn: fix-check, quality fix, risk fix, nit fix, escalation describe. */
+  readonly guard?: Guard | undefined
+  /** Quality-lap lenses; default `lensesOf(vars.qualityReviews)`. */
+  readonly lenses?: readonly string[] | undefined
+  /** `false` leaves the escalation's human rests unguarded; default `true`. */
+  readonly guardRests?: boolean | undefined
+  /** The commit the quality lap reviews from; absent: `start()`. */
+  readonly lensBase?: string | undefined
+  /** Appended to every fix and describe prompt of the tail. */
+  readonly rules?: string | undefined
+}
+
 /**
  * The build tail: fix (when entered red), keep green, the quality lap, then
- * `finish` — the human review, as the calling workflow runs it. `green`: the
- * caller just left the full suite green (the package loop), so no run opens it.
- * `guardRests: false` leaves the escalation's human rests unguarded.
+ * `finish` — the human review, as the calling workflow runs it.
  */
-export const tail = <T>(
+export function tail<T>(
+  finish: (escalations: EscalationCount) => Promise<T>,
+  options?: TailOptions,
+): Promise<T>
+/** @deprecated Pass `tail(finish, { fixFirst, green, guard, lenses, guardRests, lensBase, rules })`. */
+export function tail<T>(
   fixFirst: boolean,
   finish: (escalations: EscalationCount) => Promise<T>,
-  green = false,
+  green?: boolean,
   guard?: Guard,
   lenses?: readonly string[],
-  guardRests = true,
+  guardRests?: boolean,
   lensBase?: string,
   rules?: string,
-): Promise<T> =>
+): Promise<T>
+export function tail<T>(first: unknown, second?: unknown, ...rest: unknown[]): Promise<T> {
+  const form = tailForm<T>(first, second, rest)
+  // Before any step runs, so a bad call never leaves a half-walked flow.
+  if (form === undefined) {
+    return Promise.reject(
+      new Error(
+        "tail takes tail(finish, options?) or the deprecated tail(fixFirst, finish, green?, guard?, lenses?, guardRests?, lensBase?, rules?); this call fits neither",
+      ),
+    )
+  }
+  const [finish, options] = form
+  return runTail(finish, options)
+}
+
+type Finish<T> = (escalations: EscalationCount) => Promise<T>
+
+// null reads as absent; an un-awaited Promise is a mistake, not options.
+export const isOptionalObject = (value: unknown): value is object | null | undefined =>
+  value == null ||
+  (typeof value === "object" &&
+    !Array.isArray(value) &&
+    typeof (value as { then?: unknown }).then !== "function")
+
+// Picks the form by shape only: the deprecated form never validated its
+// positionals, and still runs whatever it ran before.
+const tailForm = <T>(
+  first: unknown,
+  second: unknown,
+  rest: readonly unknown[],
+): [Finish<T>, TailOptions] | undefined => {
+  // A function first is a misplaced finish, never a fixFirst.
+  if (typeof second === "function" && typeof first !== "function") {
+    const [green, guard, lenses, guardRests, lensBase, rules] = rest
+    const options = { fixFirst: first, green, guard, lenses, guardRests, lensBase, rules }
+    return [second as Finish<T>, options as TailOptions]
+  }
+  if (typeof first === "function" && isOptionalObject(second) && rest.every((v) => v == null))
+    return [first as Finish<T>, (second as TailOptions | null | undefined) ?? {}]
+  return undefined
+}
+
+const runTail = <T>(finish: Finish<T>, options: TailOptions): Promise<T> =>
   scope("build", async () => {
+    const { guard, lenses, lensBase, rules } = options
+    // Only undefined defaults: a null reaches every escalation as falsy, as it reaches review's.
+    const guardRests = options.guardRests === undefined ? true : options.guardRests
     const escalations: EscalationCount = { rounds: 0 }
     const fix = () => fixCheck(rules)
     const repair = async () => {
@@ -94,8 +159,9 @@ export const tail = <T>(
       await healthy(fix, { fixesSoFar: 1, escalations, guard, guardRests, rules })
     }
     // fixFirst's own fix + healthy below already is the full run.
-    if (fixFirst) await repair()
-    else if (!green) await healthy(fix, { escalations, guard, guardRests, rules })
+    // Truthy, not `true`: an untyped config's flags read as they always did.
+    if (options.fixFirst) await repair()
+    else if (!options.green) await healthy(fix, { escalations, guard, guardRests, rules })
     // The lap runs once a tail: after its findings are fixed, review follows.
     if ((await qualityLap(guard, lenses, lensBase)) === "findings") {
       if (await fixQualityFindings(escalations, guard, guardRests, rules)) {
@@ -138,4 +204,4 @@ export const handOffReview = (
 
 /** The tail the review and fix workflows run: ends at the hand-off review since `base`. */
 export const handOffTail = (fixFirst: boolean, base: string, guard?: Guard): Promise<void> =>
-  tail(fixFirst, (escalations) => handOffReview(base, escalations, guard), false, guard)
+  tail((escalations) => handOffReview(base, escalations, guard), { fixFirst, guard })