@pmelab/gtd 29.1.1 → 29.2.0

package/.claude-plugin/plugin.json

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

package/README.md

@@ -601,6 +601,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).
+
 ### Rolling out and cleaning up release flags
 
 Two more bundled workflows retire a release flag. They are opt-in: the

package/dist/chunks/{reserved-fqf-c9dc.mjs → reserved-BzeofpoC.mjs}

@@ -776,16 +776,7 @@ ${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`;
-function refactorBuildingPrompt(first, strays, pattern, reference, feedback) {
-	return refactorBuildingPromptOf(typeof first === "string" ? {
-		pkg: first,
-		strays: strays ?? [],
-		pattern: pattern ?? "",
-		reference,
-		feedback
-	} : first);
-}
-const refactorBuildingPromptOf = ({ pkg, strays, pattern, reference, feedback = false }) => `${stateFileRules}
+const refactorBuildingPrompt = ({ pkg, strays, pattern, reference, feedback = 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
   last refactor. Act on it, within the rules below

package/dist/chunks/{tail-Do11DVcw.mjs → tail-eS_ZSImR.mjs}

@@ -1,6 +1,6 @@
 import { read, refuse, removeScript, run, scope, showScript, vars } from "../flows.mjs";
 import { fixFindings, lensesOf, qualityLap as qualityLap$1, reviewToHandOff } from "../workflow-kit.mjs";
-import { E as reviewing, S as fixRisks, T as reviewQuality, W as handOffAwaitReviewMessage, _ as REVIEW, b as fixCheck, c as escalation, d as healthy, m as QUALITY, u as guarded, v as awaitReview, w as reviewMissing, x as fixQuality } from "./reserved-fqf-c9dc.mjs";
+import { E as reviewing, S as fixRisks, T as reviewQuality, W as handOffAwaitReviewMessage, _ as REVIEW, b as fixCheck, c as escalation, d as healthy, m as QUALITY, u as guarded, v as awaitReview, w as reviewMissing, x as fixQuality } from "./reserved-BzeofpoC.mjs";
 //#region src/workflows/shared/tail.ts
 /** The reviewer's own `.gtd/REVIEW.md`, kept beside the human's notes so `fix` can tell them apart. */
 const REVIEW_ORIG = ".gtd/REVIEW.orig.md";

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-fqf-c9dc.mjs";
-import { i as refusePendingHandOff, r as handOffTail } from "../chunks/tail-Do11DVcw.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-BzeofpoC.mjs";
+import { i as refusePendingHandOff, r as handOffTail } from "../chunks/tail-eS_ZSImR.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-fqf-c9dc.mjs";
-import { a as tail, i as refusePendingHandOff, n as closeReview } from "../chunks/tail-Do11DVcw.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-BzeofpoC.mjs";
+import { a as tail, i as refusePendingHandOff, n as closeReview } from "../chunks/tail-eS_ZSImR.mjs";
 //#region src/workflows/shared/fences.ts
 const markFenced = (text) => {
 	let fence;
@@ -476,13 +476,14 @@ const review = (base, escalations = { rounds: 0 }, options = {}) => {
 	});
 };
 function buildTail(first, second, third = false, fourth = {}) {
-	const base = typeof first === "string" ? first : second;
-	const options = typeof first === "string" ? second ?? {} : {
+	if (typeof first !== "string" && typeof first !== "boolean" && typeof second !== "string") 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, options] = typeof first === "string" ? [first, second ?? {}] : [second, {
 		...fourth,
 		fixFirst: first,
 		green: third
-	};
-	return tail(options.fixFirst ?? false, (escalations) => review(base, escalations, options), options.green ?? false, options.guard, options.lenses, options.guardRests, options.lensBase, options.rules);
+	}];
+	const { fixFirst, green, ...reviewOptions } = options;
+	return tail(fixFirst ?? false, (escalations) => review(base, escalations, reviewOptions), green ?? false, options.guard, options.lenses, options.guardRests, options.lensBase, options.rules);
 }
 /**
 * Undo the human's review-round code edits. A path changed since the human

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-fqf-c9dc.mjs";
-import { r as handOffTail, t as REVIEW_ORIG } from "../chunks/tail-Do11DVcw.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-BzeofpoC.mjs";
+import { r as handOffTail, t as REVIEW_ORIG } from "../chunks/tail-eS_ZSImR.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-fqf-c9dc.mjs";
-import { i as refusePendingHandOff, r as handOffTail } from "../chunks/tail-Do11DVcw.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-BzeofpoC.mjs";
+import { i as refusePendingHandOff, r as handOffTail } from "../chunks/tail-eS_ZSImR.mjs";
 //#region src/workflows/review/review.ts
 /**
 * Pure review of everything since `reviewBase`: a green gate, the quality

package/dist/workflows/rollout.mjs

@@ -1,5 +1,5 @@
 import { agent, changesSince, glob, head, mark, read, refuse, removeScript, run, scope, vars } from "../flows.mjs";
-import { a as flagShipped, dt as defaults, ft as envDefaults, gt as flipProblems, i as skills, l as gate, mt as flagMentions, n as summary, p as FEEDBACK, r as access, t as steering, vt as requireFlag, y as coder } from "../chunks/reserved-fqf-c9dc.mjs";
+import { a as flagShipped, dt as defaults, ft as envDefaults, gt as flipProblems, i as skills, l as gate, mt as flagMentions, n as summary, p as FEEDBACK, r as access, t as steering, vt as requireFlag, y as coder } from "../chunks/reserved-BzeofpoC.mjs";
 //#region src/workflows/rollout/rollout.ts
 const flippingPrompt = (name, registry) => `Roll out the release flag "${name}": in ${registry}, set \`defaultOn: true\` on its entry. Change nothing else — no other entry, no other field, no other file, no comments.`;
 const suiteBlockedMessage = () => "The suite is red after the rollout. Fix it by hand — a rollout may only touch the flag's registry entry — then land.";

package/dist/workflows.mjs

@@ -17560,16 +17560,7 @@ ${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`;
-function refactorBuildingPrompt(first, strays, pattern, reference, feedback) {
-	return refactorBuildingPromptOf(typeof first === "string" ? {
-		pkg: first,
-		strays: strays ?? [],
-		pattern: pattern ?? "",
-		reference,
-		feedback
-	} : first);
-}
-const refactorBuildingPromptOf = ({ pkg, strays, pattern, reference, feedback = false }) => `${stateFileRules}
+const refactorBuildingPrompt = ({ pkg, strays, pattern, reference, feedback = 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
   last refactor. Act on it, within the rules below
@@ -38308,13 +38299,14 @@ const review$1 = (base, escalations = { rounds: 0 }, options = {}) => {
 	});
 };
 function buildTail(first, second, third = false, fourth = {}) {
-	const base = typeof first === "string" ? first : second;
-	const options = typeof first === "string" ? second ?? {} : {
+	if (typeof first !== "string" && typeof first !== "boolean" && typeof second !== "string") 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, options] = typeof first === "string" ? [first, second ?? {}] : [second, {
 		...fourth,
 		fixFirst: first,
 		green: third
-	};
-	return tail(options.fixFirst ?? false, (escalations) => review$1(base, escalations, options), options.green ?? false, options.guard, options.lenses, options.guardRests, options.lensBase, options.rules);
+	}];
+	const { fixFirst, green, ...reviewOptions } = options;
+	return tail(fixFirst ?? false, (escalations) => review$1(base, escalations, reviewOptions), green ?? false, options.guard, options.lenses, options.guardRests, options.lensBase, options.rules);
 }
 /**
 * Undo the human's review-round code edits. A path changed since the human

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmelab/gtd",
-  "version": "29.1.1",
+  "version": "29.2.0",
   "private": false,
   "description": "Git-aware CLI that emits the next prompt for an autonomous coding agent based on the current repository state",
   "bin": {

package/skills/authoring/SKILL.md

@@ -56,7 +56,7 @@ export {
 export default feature
 
 export async function hotfix() {
-  return afterTail(await buildTail(true, start()))
+  return afterTail(await buildTail(start(), { fixFirst: true }))
 }
 
 export const doors = { hotfix: { workflow: "hotfix" } }
@@ -227,9 +227,11 @@ pass (which writes `.gtd/packages/`), then builds the packages. Add a human
 sign-off between the two:
 
 ```ts
-const planAndBuild = async (): Promise<void> => {
+const planAndBuild = async (firstBase: string): Promise<void> => {
+  let base = firstBase
+  let lap: "first" | "feedback" = "first"
   for (;;) {
-    await design()
+    await design(base)
     await architecture()
     await human("approve-plan", {
       message:
@@ -238,8 +240,14 @@ const planAndBuild = async (): Promise<void> => {
       acceptClean: true,
     })
     await packages()
-    if ((await buildTail(false)) === "signoff") return
-    await reUnwind()
+    const outcome = await buildTail(base, {
+      green: true,
+      ...(lap === "first" ? {} : { lap }),
+    })
+    if (outcome.verdict === "signoff") return
+    await reUnwind(outcome)
+    base = outcome.base
+    lap = "feedback"
   }
 }
 ```

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

@@ -131,7 +131,7 @@ describe("afterTail feedback lap", () => {
     `export { feature as default, defaults, envDefaults, summary, base, steering, skills, access } from "@pmelab/gtd/workflows"`,
     `export async function tail() {`,
     `  await gate("review-gate", "The baseline is red.")`,
-    `  return afterTail(await buildTail(false, start()))`,
+    `  return afterTail(await buildTail(start()))`,
     `}`,
   ].join("\n")
 

package/src/workflows/feature/index.ts

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

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

@@ -16,6 +16,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 { fixtureContext } from "../shared/text.fixture.js"
 
 afterEach(() => installContext(undefined))
@@ -771,7 +772,10 @@ describe("severity routing", () => {
 })
 
 describe("BuildTailOptions.lensBase", () => {
-  const lensPrompts = async (options: BuildTailOptions): Promise<string[]> => {
+  const lensPrompts = async (
+    options: BuildTailOptions,
+    call: () => Promise<unknown> = () => buildTail("base", { ...options, green: true }),
+  ): Promise<string[]> => {
     const prompts: string[] = []
     installContext(
       fixtureContext(
@@ -793,7 +797,7 @@ describe("BuildTailOptions.lensBase", () => {
         },
       ),
     )
-    await buildTail(false, "base", true, options).catch((error: unknown) => {
+    await call().catch((error: unknown) => {
       if (!(error instanceof Stop)) throw error
     })
     return prompts
@@ -810,8 +814,104 @@ describe("BuildTailOptions.lensBase", () => {
     expect(prompts).toHaveLength(2)
     for (const prompt of prompts) expect(prompt).toContain("from `START-SHA`")
   })
+
+  it("the deprecated positional form runs the same tail as the options form", async () => {
+    const options = { lensBase: "SLICE-BASE" }
+    const modern = await lensPrompts(options)
+    const legacy = await lensPrompts(options, () => buildTail(false, "base", true, options))
+    expect(legacy).toEqual(modern)
+    expect(legacy).toHaveLength(2)
+  })
+
+  describe("buildTail flags", () => {
+    const requestNames = async (
+      call: () => Promise<unknown>,
+      names: string[] = [],
+    ): Promise<string[]> => {
+      installContext(
+        fixtureContext(
+          {},
+          {
+            step: (request: StepRequest) => {
+              if (request.kind === "restart") return Promise.resolve()
+              names.push(`${request.kind}:${request.name}`)
+              if (names.length >= 4) throw new Stop()
+              return Promise.resolve()
+            },
+            pushScope: () => undefined,
+            popScope: () => undefined,
+            changesSince: () => {
+              throw new Stop()
+            },
+            start: () => "START-SHA",
+          },
+        ),
+      )
+      await call().catch((error: unknown) => {
+        if (!(error instanceof Stop)) throw error
+      })
+      return names
+    }
+
+    for (const [fixFirst, green] of [
+      [true, false],
+      [true, true],
+      [false, true],
+      [false, false],
+    ] as const) {
+      it(`fixFirst ${fixFirst}, green ${green} match the options form`, async () => {
+        const modern = await requestNames(() => buildTail("base", { fixFirst, green }))
+        const legacy = await requestNames(() => buildTail(fixFirst, "base", green))
+        expect(legacy).toEqual(modern)
+      })
+    }
+
+    it("fixFirst and green each change the request sequence", async () => {
+      const seq = (fixFirst: boolean, green: boolean) =>
+        requestNames(() => buildTail(fixFirst, "base", green))
+      const base = await seq(false, false)
+      expect(await seq(true, false)).not.toEqual(base)
+      expect(await seq(false, true)).not.toEqual(base)
+    })
+
+    for (const bad of [undefined, null, 1, {}]) {
+      it(`rejects naming both forms for sole first argument ${String(bad)}`, async () => {
+        const names: string[] = []
+        const rejected = expect(requestNames(() => buildTail(bad as never), names)).rejects
+        await rejected.toThrow("buildTail(base, options?)")
+        await rejected.toThrow("buildTail(fixFirst, base, green?, options?)")
+        expect(names).toEqual([])
+      })
+    }
+
+    it("rejects an undefined first argument followed by an options object", async () => {
+      const names: string[] = []
+      const rejected = expect(
+        requestNames(() => buildTail(undefined as never, { green: true } as never), names),
+      ).rejects
+      await rejected.toThrow("buildTail(base, options?)")
+      await rejected.toThrow("buildTail(fixFirst, base, green?, options?)")
+      expect(names).toEqual([])
+    })
+
+    it("still runs buildTail(undefined, base) as a legacy call", async () => {
+      const names: string[] = []
+      await requestNames(() => buildTail(undefined as never, "base"), names)
+      expect(names).not.toEqual([])
+    })
+
+    // pins `| undefined` on BuildTailOptions under exactOptionalPropertyTypes (typecheck)
+    it("explicitly undefined fixFirst and green default like omitted ones", async () => {
+      expect(
+        await requestNames(() => buildTail("base", { fixFirst: undefined, green: 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]
+
 describe("buildTail without rules", () => {
   const RULES = "Change only these paths"
 
@@ -850,7 +950,7 @@ describe("buildTail without rules", () => {
         },
       ),
     )
-    await buildTail(true, "base", false, {}).catch((error: unknown) => {
+    await buildTail("base", { fixFirst: true }).catch((error: unknown) => {
       if (!(error instanceof Stop)) throw error
     })
     return prompts

package/src/workflows/feature/review.ts

@@ -257,9 +257,9 @@ export interface FeedbackTarget {
 
 export interface BuildTailOptions {
   /** Fix first when entered red; default `false`. */
-  readonly fixFirst?: boolean
-  /** Skip keeping green; default `false`. */
-  readonly green?: boolean
+  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. */
@@ -292,15 +292,23 @@ export function buildTail(
   third = false,
   fourth: Omit<BuildTailOptions, "fixFirst" | "green"> = {},
 ): Promise<kit.ReviewOutcome> {
-  const base = typeof first === "string" ? first : (second as string)
-  const options: BuildTailOptions =
+  // Before any step runs, so a bad call never leaves a half-walked flow.
+  if (typeof first !== "string" && typeof first !== "boolean" && typeof second !== "string") {
+    return Promise.reject(
+      new Error(
+        "buildTail takes buildTail(base, options?) or the deprecated buildTail(fixFirst, base, green?, options?); this call fits neither",
+      ),
+    )
+  }
+  const [base, options]: [string, BuildTailOptions] =
     typeof first === "string"
-      ? ((second as BuildTailOptions | undefined) ?? {})
-      : { ...fourth, fixFirst: first, green: third }
+      ? [first, (second as BuildTailOptions | undefined) ?? {}]
+      : [second as string, { ...fourth, fixFirst: first, green: third }]
+  const { fixFirst, green, ...reviewOptions } = options
   return tail(
-    options.fixFirst ?? false,
-    (escalations) => review(base, escalations, options),
-    options.green ?? false,
+    fixFirst ?? false,
+    (escalations) => review(base, escalations, reviewOptions),
+    green ?? false,
     options.guard,
     options.lenses,
     options.guardRests,

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

@@ -225,6 +225,7 @@ describe("implement", () => {
     reference: string | undefined,
     tier?: "low" | "high",
     amend?: boolean,
+    call: () => Promise<void> = () => implement({ reference, tier, amend }),
   ) => {
     const requests: StepRequest[] = []
     installContext(
@@ -241,12 +242,25 @@ describe("implement", () => {
         },
       ),
     )
-    await implement(reference, tier, amend)
+    await call()
     const request = requests.find((r) => r.kind === "agent" && r.name === "building")
     if (request?.kind !== "agent") throw new Error("no building turn")
     return request.prompt
   }
 
+  it("the deprecated positional form renders the same prompt as the options form", async () => {
+    const modern = await building("abc", "low")
+    const legacy = await building("abc", "low", undefined, () => implement("abc", "low"))
+    expect(legacy).toBe(modern)
+    expect(legacy).toContain("git show abc")
+    const amended = await building(undefined, undefined, true)
+    expect(
+      await building(undefined, undefined, undefined, () => implement(undefined, undefined, true)),
+    ).toBe(amended)
+    const bare = await building(undefined, undefined, undefined, () => implement())
+    expect(bare).toBe(await building(undefined))
+  })
+
   it("names the reference with a git show line", async () => {
     expect(await building("abc")).toContain("git show abc")
   })

package/src/workflows/index.ts

@@ -24,7 +24,7 @@ export * from "./feature/planning.js"
 export * from "./feature/packages.js"
 export * from "./feature/refactor.js"
 export * from "./feature/seam.js"
-export { buildTail, type ReviewOutcome } from "./feature/review.js"
+export { buildTail, type BuildTailOptions, 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/options.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, it } from "vitest"
+import { FLAGS, type FlagDeclaration } from "../../flags/index.js"
 import { configure, type WorkflowDoors } from "../../flows/index.js"
 import * as workflows from "../index.js"
 import * as options from "./options.js"
@@ -10,13 +11,19 @@ describe("the shipped workflow factories", () => {
   it("take exactly the settings the shipped workflows declare as options", () => {
     expect(Object.keys(ShippedOptions.fields).sort()).toEqual(
       [...Object.keys(defaults), ...Object.keys(envDefaults)]
-        .filter((name) => name !== "flag_naive_pass" && name !== "flag_risk_tier")
+        .filter((name) => !name.startsWith("flag_"))
         .sort(),
     )
   })
 
+  it("declare a flag_<name> default for exactly the registered flags", () => {
+    const declared = Object.keys(defaults).filter((name) => name.startsWith("flag_"))
+    expect(declared.sort()).toEqual(FLAGS.map(({ name }) => `flag_${name}`).sort())
+    for (const { name, defaultOn } of FLAGS as readonly FlagDeclaration[])
+      expect(defaults).toHaveProperty(`flag_${name}`, defaultOn ? "1" : "0")
+  })
+
   it("declare seamAllow and flag_naive_pass defaults; flag_naive_pass is no option", () => {
-    expect(defaults.flag_naive_pass).toBe("0")
     expect(Object.keys(ShippedOptions.fields)).not.toContain("flag_naive_pass")
     expect(configure(feature({ seamAllow: "docs/**" }))).toMatchObject({
       ok: true,
@@ -25,7 +32,6 @@ describe("the shipped workflow factories", () => {
   })
 
   it("declare flag_risk_tier off by default; it is no factory option", () => {
-    expect(defaults.flag_risk_tier).toBe("0")
     expect(Object.keys(ShippedOptions.fields)).not.toContain("flag_risk_tier")
   })
 

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

@@ -1063,7 +1063,7 @@ describe("the refactor prompts", () => {
 
   it("building and fix rules forbid every test file, with no stray exception", () => {
     for (const prompt of renderText(() => [
-      refactorBuildingPrompt(".gtd/REFACTOR.md", strays, pattern),
+      refactorBuildingPrompt({ pkg: ".gtd/REFACTOR.md", strays, pattern }),
       refactorFixPrompt(strays, pattern),
     ])) {
       expect(prompt).toContain("never a test file")
@@ -1073,8 +1073,8 @@ describe("the refactor prompts", () => {
 
   it("building adds the act-on-review-feedback line only when asked", () => {
     const [plain, feedback] = renderText(() => [
-      refactorBuildingPrompt(".gtd/REFACTOR.md", strays, pattern),
-      refactorBuildingPrompt(".gtd/REFACTOR.md", strays, pattern, undefined, true),
+      refactorBuildingPrompt({ pkg: ".gtd/REFACTOR.md", strays, pattern }),
+      refactorBuildingPrompt({ pkg: ".gtd/REFACTOR.md", strays, pattern, feedback: true }),
     ])
     expect(plain).not.toContain("## Review feedback")
     expect(feedback).toContain("## Review feedback")

package/src/workflows/shared/text.ts

@@ -473,44 +473,19 @@ ${strays.map((path) => `  - \`${displayPath(path)}\``).join("\n")}
 
 const withRules = (rules?: string): string => (rules === undefined ? "" : `${rules}\n`)
 
-interface RefactorBuildingArgs {
-  pkg: string
-  strays: readonly string[]
-  pattern: string
-  reference?: string | undefined
-  feedback?: boolean | undefined
-}
-
-export function refactorBuildingPrompt(args: RefactorBuildingArgs): string
-/** @deprecated Pass `refactorBuildingPrompt({ pkg, strays, pattern, reference, feedback })`. */
-export function refactorBuildingPrompt(
-  pkg: string,
-  strays: readonly string[],
-  pattern: string,
-  reference?: string,
-  feedback?: boolean,
-): string
-export function refactorBuildingPrompt(
-  first: string | RefactorBuildingArgs,
-  strays?: readonly string[],
-  pattern?: string,
-  reference?: string,
-  feedback?: boolean,
-): string {
-  return refactorBuildingPromptOf(
-    typeof first === "string"
-      ? { pkg: first, strays: strays ?? [], pattern: pattern ?? "", reference, feedback }
-      : first,
-  )
-}
-
-const refactorBuildingPromptOf = ({
+export const refactorBuildingPrompt = ({
   pkg,
   strays,
   pattern,
   reference,
   feedback = false,
-}: RefactorBuildingArgs): string =>
+}: {
+  pkg: string
+  strays: readonly string[]
+  pattern: string
+  reference?: string | undefined
+  feedback?: boolean | undefined
+}): string =>
   `${stateFileRules}
 - The package to implement is \`${pkg}\`; never delete it
 ${