@pmelab/gtd 29.1.0 → 29.2.0

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

@@ -1,6 +1,6 @@
 import { afterEach, describe, expect, it } from "vitest"
-import { installContext, type Change, type StepRequest } from "../../flows/index.js"
-import { declaredTests, packages } from "./packages.js"
+import { installContext, type Change, type Changes, type StepRequest } from "../../flows/index.js"
+import { declaredTests, packages, requireDeclaredTests } from "./packages.js"
 import { fixtureContext } from "../shared/text.fixture.js"
 
 afterEach(() => installContext(undefined))
@@ -16,8 +16,8 @@ describe("declaredTests", () => {
       "- e2e: `spec/a.feature`",
     ].join("\n")
     expect(declaredTests(text)).toEqual([
-      { level: "unit", path: "lib/a.test.ts" },
-      { level: "e2e", path: "spec/a.feature" },
+      { level: "unit", path: "lib/a.test.ts", unchanged: false },
+      { level: "e2e", path: "spec/a.feature", unchanged: false },
     ])
   })
 
@@ -33,7 +33,88 @@ describe("declaredTests", () => {
       "## Notes",
       "- e2e: `spec/other.feature`",
     ].join("\n")
-    expect(declaredTests(text)).toEqual([{ level: "unit", path: "lib/ok.test.ts" }])
+    expect(declaredTests(text)).toEqual([
+      { level: "unit", path: "lib/ok.test.ts", unchanged: false },
+    ])
+  })
+
+  it("marks a whitespace-led, case-insensitive `(unchanged)` ending at a boundary", () => {
+    const text = [
+      "## Tests",
+      "- unit: `a.test.ts` (unchanged)",
+      "- unit: `b.test.ts` extra",
+      "- unit: `c.test.ts` (unchanged)x",
+      "- unit: `f.test.ts` (unchanged) — kept as is",
+      "- unit: `d.test.ts` (Unchanged)",
+      "- e2e: `e.feature` (unchanged)",
+      "- unit: `g.test.ts`\t(unchanged)",
+      "- unit: `h.test.ts`   (unchanged)",
+      "- unit: `i.test.ts`(unchanged)",
+      "- Unit: `j.test.ts` (unchanged)",
+    ].join("\n")
+    expect(declaredTests(text).map((t) => [t.path, t.unchanged])).toEqual([
+      ["a.test.ts", true],
+      ["b.test.ts", false],
+      ["c.test.ts", false],
+      ["f.test.ts", true],
+      ["d.test.ts", true],
+      ["e.feature", true],
+      ["g.test.ts", true],
+      ["h.test.ts", true],
+      ["i.test.ts", false],
+    ])
+  })
+
+  it("never joins a marker across an empty or whitespace-only line", () => {
+    for (const gap of ["\n\n", "\n  \n", "\n\t\n"]) {
+      const text = `## Tests\n- unit: \`a.test.ts\`${gap}  (unchanged)\n`
+      expect(declaredTests(text).map((t) => t.unchanged)).toEqual([false])
+    }
+  })
+
+  it("reads an entry whose path or marker is wrapped, in any line-end style", () => {
+    const forms = [
+      "- unit: `a/long.test.ts` (unchanged)",
+      "- unit:\n  `a/long.test.ts` (unchanged)",
+      "- unit: `a/long.test.ts`\n  (unchanged)",
+      "- unit:\n  `a/long.test.ts`\n  (unchanged)",
+    ]
+    for (const form of forms) {
+      const lf = `## Tests\n${form}\n- e2e: \`b.feature\`\n`
+      const want = [
+        { level: "unit", path: "a/long.test.ts", unchanged: true },
+        { level: "e2e", path: "b.feature", unchanged: false },
+      ]
+      expect(declaredTests(lf)).toEqual(want)
+      expect(declaredTests(lf.replace(/\n/g, "\r\n"))).toEqual(want)
+      expect(declaredTests(lf.replace(/\n/g, "\r"))).toEqual(want)
+    }
+  })
+
+  it("keeps the heading and its entries when an indented marker follows `## Tests`", () => {
+    const text = "## Tests\n  (unchanged)\n- unit: `a.test.ts`\n"
+    expect(declaredTests(text)).toEqual([{ level: "unit", path: "a.test.ts", unchanged: false }])
+  })
+
+  it("never extends an entry across a new item or a heading", () => {
+    const text = [
+      "## Tests",
+      "- unit: `a.test.ts`",
+      "  - unit: `b.test.ts` (unchanged)",
+      "- unit: `c.test.ts`",
+      "## Tests",
+      "  (unchanged)",
+    ].join("\n")
+    expect(declaredTests(text).map((t) => [t.path, t.unchanged])).toEqual([
+      ["a.test.ts", false],
+      ["b.test.ts", true],
+      ["c.test.ts", false],
+    ])
+  })
+
+  it("closes an entry on an unindented line", () => {
+    const text = "## Tests\n- unit: `a.test.ts`\n(unchanged)\n"
+    expect(declaredTests(text).map((t) => t.unchanged)).toEqual([false])
   })
 
   it("returns nothing without a Tests section", () => {
@@ -72,3 +153,216 @@ describe("packages", () => {
     expect(closings[1]).toContain(".gtd/ARCHITECTURE.md")
   })
 })
+
+describe("requireDeclaredTests", () => {
+  const run = (
+    text: string,
+    tree: readonly string[],
+    changes: readonly Change[],
+    satisfied = false,
+    turn: "build" | "fix" | "default" = "build",
+  ) => {
+    const pkg = ".gtd/packages/01-a.md"
+    installContext(
+      fixtureContext(
+        {},
+        {
+          read: (path: string) =>
+            path === pkg
+              ? text
+              : path === ".gtd/SATISFIED.md"
+                ? satisfied
+                  ? "x"
+                  : undefined
+                : tree.includes(path)
+                  ? "x"
+                  : undefined,
+          refuse: (message: string): never => {
+            throw new Error(message)
+          },
+          changesSince: (): Changes => {
+            const list: Change[] = [
+              { path: pkg, status: "modified", before: text, after: text },
+              ...changes,
+            ]
+            return Object.assign(list, {
+              paths: list.map((c) => c.path),
+              get: (path: string) => list.find((c) => c.path === path),
+            })
+          },
+        },
+      ),
+    )
+    let message = ""
+    try {
+      if (turn === "default") requireDeclaredTests(pkg, "c")
+      else requireDeclaredTests(pkg, "c", turn)
+    } catch (error) {
+      message = String(error instanceof Error ? error.message : error)
+    }
+    return { message }
+  }
+  const deleted = (path: string): Change => ({
+    path,
+    status: "deleted",
+    before: "x",
+    after: undefined,
+  })
+
+  it("groups an unwritten unmarked test and a missing marked test in one refusal", () => {
+    const text = [
+      "## Tests",
+      "- unit: `lib/unwritten.test.ts`",
+      "- unit: `lib/gone.test.ts` (unchanged)",
+      "- unit: `lib/kept.test.ts` (unchanged)",
+    ].join("\n")
+    const { message } = run(text, ["lib/kept.test.ts"], [])
+    expect(message).toContain("gtd land: declared-tests:")
+    expect(message).not.toMatch(/satisf/i)
+    const diffAt = message.indexOf("not in the package's diff")
+    const treeAt = message.indexOf("missing from the tree")
+    expect(diffAt).toBeGreaterThanOrEqual(0)
+    expect(treeAt).toBeGreaterThan(diffAt)
+    expect(message.indexOf("  - lib/unwritten.test.ts")).toBeGreaterThan(diffAt)
+    expect(message.indexOf("  - lib/unwritten.test.ts")).toBeLessThan(treeAt)
+    expect(message.indexOf("  - lib/gone.test.ts")).toBeGreaterThan(treeAt)
+    expect(message).not.toContain("kept.test.ts")
+  })
+
+  it("sends a marked deleted test to restore only", () => {
+    const { message } = run("## Tests\n- unit: `a.test.ts` (unchanged)", [], [deleted("a.test.ts")])
+    expect(message).toContain("declares tests this turn left unmet:")
+    expect(message).toContain("marked (unchanged) but deleted — restore them:\n  - a.test.ts")
+    expect(message).not.toContain("missing from the tree")
+    expect(message).not.toContain("write them")
+  })
+
+  it("keeps a marked absent test with no diff change under missing", () => {
+    const { message } = run("## Tests\n- unit: `a.test.ts` (unchanged)", [], [])
+    expect(message).toContain("missing from the tree:\n  - a.test.ts")
+    expect(message).not.toContain("restore")
+  })
+
+  it("keeps an unmarked deleted test under write, or missing once satisfied", () => {
+    const text = "## Tests\n- unit: `a.test.ts`"
+    expect(run(text, [], [deleted("a.test.ts")]).message).toContain(
+      "not in the package's diff — write them:\n  - a.test.ts",
+    )
+    const done = run(text, [], [deleted("a.test.ts")], true).message
+    expect(done).toContain("missing from the tree:\n  - a.test.ts")
+    expect(done).not.toContain("restore")
+  })
+
+  const modified = (path: string): Change => ({
+    path,
+    status: "modified",
+    before: "x",
+    after: "y",
+  })
+
+  it("refuses a marked test the build modified, even with SATISFIED.md", () => {
+    const text = "## Tests\n- unit: `a.test.ts` (unchanged)"
+    for (const satisfied of [false, true]) {
+      const { message } = run(text, ["a.test.ts"], [modified("a.test.ts")], satisfied)
+      expect(message).toContain("marked (unchanged) but modified — revert them:\n  - a.test.ts")
+    }
+  })
+
+  it("lets a fix turn modify a marked test but not delete it", () => {
+    const text = "## Tests\n- unit: `a.test.ts` (unchanged)\n- unit: `b.test.ts` (unchanged)"
+    expect(run(text, ["a.test.ts"], [modified("a.test.ts")], false, "fix").message).toContain(
+      "missing from the tree:\n  - b.test.ts",
+    )
+    expect(run(text, ["a.test.ts"], [modified("a.test.ts")], false, "fix").message).not.toContain(
+      "revert",
+    )
+    const gone = run(text, [], [deleted("a.test.ts"), deleted("b.test.ts")], false, "fix").message
+    expect(gone).toContain("restore them:\n  - a.test.ts\n  - b.test.ts")
+    const clean = "## Tests\n- unit: `a.test.ts` (unchanged)"
+    expect(run(clean, ["a.test.ts"], [modified("a.test.ts")], false, "fix").message).toBe("")
+  })
+
+  it("lets an unmarked entry for the same file win over a marked one", () => {
+    const text = "## Tests\n- e2e: `x.feature`\n- e2e: `x.feature` (unchanged)"
+    expect(run(text, ["x.feature"], [modified("x.feature")]).message).toBe("")
+  })
+
+  const added = (path: string): Change => ({
+    path,
+    status: "added",
+    before: undefined,
+    after: "x",
+  })
+  const addedGroup =
+    "marked (unchanged) but added by this turn — the marker promises an existing test; stop and leave it to a person"
+
+  it("refuses a marked test the build added, as added and never as modified", () => {
+    const { message } = run(
+      "## Tests\n- unit: `a.test.ts` (unchanged)",
+      ["a.test.ts"],
+      [added("a.test.ts")],
+    )
+    expect(message).toContain(`${addedGroup}:\n  - a.test.ts`)
+    expect(message).not.toContain("revert")
+    expect(message).not.toMatch(/delete|restore/i)
+  })
+
+  it("only the build turn refuses an added marked test (turn split, not a fix-turn flow)", () => {
+    const text = "## Tests\n- unit: `a.test.ts` (unchanged)"
+    expect(run(text, ["a.test.ts"], [added("a.test.ts")], false, "fix").message).toBe("")
+  })
+
+  it.each([
+    ["modified", modified("a.test.ts")],
+    ["added", added("a.test.ts")],
+  ] as [string, Change][])("defaults to the fix turn with two arguments (%s)", (_label, change) => {
+    const text = "## Tests\n- unit: `a.test.ts` (unchanged)"
+    expect(run(text, ["a.test.ts"], [change], false, "default").message).toBe("")
+    expect(run(text, ["a.test.ts"], [change], false, "build").message).not.toBe("")
+  })
+
+  it("lets an unmarked entry win over a marked one the build added", () => {
+    const text = "## Tests\n- unit: `a.test.ts`\n- unit: `a.test.ts` (unchanged)"
+    expect(run(text, ["a.test.ts"], [added("a.test.ts")]).message).toBe("")
+  })
+
+  it("lists a duplicated unwritten line once", () => {
+    const text = "## Tests\n- unit: `a.test.ts`\n- unit: `a.test.ts`"
+    const { message } = run(text, [], [])
+    expect(message.split("a.test.ts").length - 1).toBe(1)
+  })
+
+  it("lists a duplicated marked line missing from the tree once", () => {
+    const text = "## Tests\n- unit: `a.test.ts` (unchanged)\n- unit: `a.test.ts` (unchanged)"
+    const { message } = run(text, [], [])
+    expect(message.split("a.test.ts").length - 1).toBe(1)
+  })
+
+  it("orders write, revert, added, restore, missing and never says satisfied", () => {
+    const text = [
+      "## Tests",
+      "- unit: `w.test.ts`",
+      "- unit: `r.test.ts` (unchanged)",
+      "- unit: `m.test.ts` (unchanged)",
+      "- unit: `v.test.ts` (unchanged)",
+      "- unit: `a.test.ts` (unchanged)",
+    ].join("\n")
+    const { message } = run(
+      text,
+      ["v.test.ts", "a.test.ts"],
+      [deleted("r.test.ts"), modified("v.test.ts"), added("a.test.ts")],
+    )
+    const w = message.indexOf("write them")
+    const v = message.indexOf("revert them")
+    expect(v).toBeGreaterThan(w)
+    const ad = message.indexOf("added by this turn")
+    expect(ad).toBeGreaterThan(v)
+    const r = message.indexOf("restore them")
+    expect(r).toBeGreaterThan(ad)
+    const m = message.indexOf("missing from the tree")
+    expect(w).toBeGreaterThan(0)
+    expect(r).toBeGreaterThan(w)
+    expect(m).toBeGreaterThan(r)
+    expect(message).not.toMatch(/satisf/i)
+  })
+})

package/src/workflows/feature/packages.ts

@@ -15,46 +15,129 @@ import { build, fixSuite } from "./steps.js"
 export interface DeclaredTest {
   readonly level: "unit" | "e2e"
   readonly path: string
+  readonly unchanged: boolean
 }
 
-const TEST_LINE = /^\s*-\s+(unit|e2e):\s+`([^`]+)`/
+const TEST_LINE = /^-\s+(unit|e2e):\s+`([^`]+)`(.*)$/
+const MARKER = /^[ \t]+\(unchanged\)(?=\s|$)/i
+const ITEM = /^\s*-\s/
 
-/** The `## Tests` entries of a package file; malformed lines are ignored. */
+/** The `## Tests` entries of a package file; malformed entries are ignored. */
 export const declaredTests = (packageText: string): readonly DeclaredTest[] => {
   const found: DeclaredTest[] = []
   let inTests = false
-  for (const line of packageText.split("\n")) {
-    if (/^##\s/.test(line)) inTests = /^##\s+Tests\s*$/.test(line)
-    else if (inTests) {
-      const match = TEST_LINE.exec(line)
-      if (match) found.push({ level: match[1] as DeclaredTest["level"], path: match[2]! })
-    }
+  let entry: string | undefined
+  const flush = () => {
+    const match = entry === undefined ? null : TEST_LINE.exec(entry)
+    if (match)
+      found.push({
+        level: match[1] as DeclaredTest["level"],
+        path: match[2]!,
+        unchanged: MARKER.test(match[3]!),
+      })
+    entry = undefined
+  }
+  // An entry is a list line plus its indented continuation lines (oxfmt wraps
+  // long ones); a blank line, a new item or a heading ends it.
+  for (const line of packageText.replace(/\r\n?/g, "\n").split("\n")) {
+    if (/^##\s/.test(line)) {
+      flush()
+      inTests = /^##\s+Tests\s*$/.test(line)
+    } else if (!inTests) continue
+    else if (ITEM.test(line)) {
+      flush()
+      entry = line.trim()
+    } else if (entry !== undefined && /^\s/.test(line) && line.trim() !== "")
+      entry = `${entry} ${line.trim()}`
+    else flush()
   }
+  flush()
   return found
 }
 
+export type DeclaredTestsTurn = "build" | "fix"
+
+type Unmet = "notInDiff" | "modifiedMarked" | "addedMarked" | "deletedMarked" | "notInTree"
+
+type Declared = { path: string; unchanged: boolean }
+
+const diffBucket = (
+  test: Declared,
+  status: string | undefined,
+  turn: DeclaredTestsTurn,
+  satisfied: boolean,
+): Unmet | undefined => {
+  if (test.unchanged) {
+    if (turn !== "build") return undefined
+    if (status === "modified") return "modifiedMarked"
+    return status === "added" ? "addedMarked" : undefined
+  }
+  return !satisfied && (status === undefined || status === "deleted") ? "notInDiff" : undefined
+}
+
+const treeBucket = (test: Declared, status: string | undefined): Unmet | undefined => {
+  if (read(test.path) !== undefined) return undefined
+  return test.unchanged && status === "deleted" ? "deletedMarked" : "notInTree"
+}
+
+const unmetBucket = (
+  test: Declared,
+  change: { status: string } | undefined,
+  turn: DeclaredTestsTurn,
+  satisfied: boolean,
+): Unmet | undefined =>
+  diffBucket(test, change?.status, turn, satisfied) ?? treeBucket(test, change?.status)
+
 /**
  * Refuse a build or fix turn unless every test `pkg` declares exists and is in the
  * diff since `since`. The package text is read as of `since`, so a builder
- * editing its own `## Tests` cannot dodge the guard; with `.gtd/SATISFIED.md`
- * written, existing in the tree suffices.
+ * editing its own `## Tests` (or adding `(unchanged)`) cannot dodge the guard;
+ * with `.gtd/SATISFIED.md` written, or the line marked, existing suffices. The
+ * build turn must neither modify nor add a marked test; a fix turn may edit it.
  */
-export const requireDeclaredTests = (pkg: string, since: string): void => {
+export const requireDeclaredTests = (
+  pkg: string,
+  since: string,
+  turn: DeclaredTestsTurn = "fix",
+): void => {
   const range = changesSince(since)
   const text = range.get(pkg)?.before ?? read(pkg) ?? ""
   const satisfied = read(".gtd/SATISFIED.md") !== undefined
-  const missing = declaredTests(text)
-    .map((test) => test.path)
-    .filter((path) =>
-      satisfied
-        ? read(path) === undefined
-        : range.get(path) === undefined ||
-          range.get(path)?.status === "deleted" ||
-          read(path) === undefined,
-    )
-  if (missing.length === 0) return
+  const buckets = {
+    notInDiff: [] as string[],
+    modifiedMarked: [] as string[],
+    addedMarked: [] as string[],
+    deletedMarked: [] as string[],
+    notInTree: [] as string[],
+  }
+  const entries = declaredTests(text)
+  const seen = new Set<string>()
+  for (const test of entries) {
+    // A file listed both ways is written by the package: the unmarked entry wins.
+    if (test.unchanged && entries.some((e) => !e.unchanged && e.path === test.path)) continue
+    const bucket = unmetBucket(test, range.get(test.path), turn, satisfied)
+    if (bucket && !seen.has(test.path)) {
+      seen.add(test.path)
+      buckets[bucket].push(test.path)
+    }
+  }
+  const { notInDiff, modifiedMarked, addedMarked, deletedMarked, notInTree } = buckets
+  const groups = [
+    ["not in the package's diff — write them", notInDiff],
+    ["marked (unchanged) but modified — revert them", modifiedMarked],
+    [
+      "marked (unchanged) but added by this turn — the marker promises an existing test; stop and leave it to a person",
+      addedMarked,
+    ],
+    ["marked (unchanged) but deleted — restore them", deletedMarked],
+    ["missing from the tree", notInTree],
+  ] as const
+  const reasons = groups.filter(([, paths]) => paths.length > 0)
+  if (reasons.length === 0) return
   refuse(
-    `gtd land: declared-tests: ${pkg} declares tests that are ${satisfied ? "missing from the tree" : "not in the package's diff"} — write them first:\n${missing.map((path) => `  - ${path}`).join("\n")}`,
+    `gtd land: declared-tests: ${pkg} declares tests this turn left unmet:\n${reasons
+      .map(([reason, paths]) => `${reason}:\n${paths.map((path) => `  - ${path}`).join("\n")}`)
+      .join("\n")}`,
   )
 }
 
@@ -66,12 +149,12 @@ export const packageItem = async (pkg: string): Promise<void> => {
   const from = head()
   // Rechecked after every fix too: a fix deleting a red declared test would
   // otherwise green the suite.
-  const declared = (turn: () => Promise<void>) => async () => {
+  const declared = (turn: () => Promise<void>, kind: DeclaredTestsTurn) => async () => {
     await turn()
-    requireDeclaredTests(pkg, from)
+    requireDeclaredTests(pkg, from, kind)
   }
-  await declared(() => build(pkg))()
-  await healthy(declared(fixSuite))
+  await declared(() => build(pkg), "build")()
+  await healthy(declared(fixSuite, "fix"))
   const last = glob(".gtd/packages/*.md").length === 1
   await run("closing", removeScript([pkg, ".gtd/SATISFIED.md", ...(last ? [ARCHITECTURE] : [])]), {
     label: "Closing out the package",

package/src/workflows/feature/refactor.ts

@@ -216,7 +216,13 @@ const refactorLap = async (p: Plan, guard: Guard, feedback?: string): Promise<vo
   )
   await t.agentWithSkills(
     "building",
-    t.refactorBuildingPrompt(REFACTOR_PACKAGE, strays, pattern, reference, feedback !== undefined),
+    t.refactorBuildingPrompt({
+      pkg: REFACTOR_PACKAGE,
+      strays,
+      pattern,
+      reference,
+      feedback: feedback !== undefined,
+    }),
     { label: "Refactoring", model: coder(), system: t.builderSystem() },
   )
   guard()
@@ -275,7 +281,8 @@ export const reviewedRefactor = async (
     for (;;) {
       await refactorLap(p, guard, collected)
       // A person's edit at an escalation rest is never refused, as in the lap.
-      const outcome = await buildTail(false, entry, true, {
+      const outcome = await buildTail(entry, {
+        green: true,
         guard,
         guardRests: false,
         lenses: lensesOf(vars.refactorQualityReviews ?? ""),

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