@pmelab/gtd 36.0.0 → 37.0.0

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

@@ -13,6 +13,9 @@ import {
   judgeSeam,
   naivePass,
   acceptanceFault,
+  naiveAcceptance,
+  requireAcceptance,
+  requireAcceptanceKept,
   seamBuild,
   type SeamOutcome,
 } from "./seam.js"
@@ -105,6 +108,67 @@ describe("naivePass", () => {
   })
 })
 
+describe("naiveAcceptance and requireAcceptance", () => {
+  const requirements = "# R\n\n## Acceptance Criteria\n\n- AC-1: adds.\n- AC-2: subtracts.\n"
+  const file = (path: string, before: string | undefined, after: string): Change => ({
+    path,
+    status: before === undefined ? "added" : "modified",
+    before,
+    after,
+  })
+  const install = (since: Change[] = []) =>
+    installContext({
+      ...fixtureContext({}),
+      matches: globMatches,
+      read: (path: string) => (path === ".gtd/REQUIREMENTS.md" ? requirements : undefined),
+      changesSince: () => since,
+      changes: () => since,
+      refuse: (message: string) => {
+        throw new Error(message)
+      },
+    } as unknown as FlowContext)
+
+  it("takes the IDs the pass's tests name on an added line, and only those test files", () => {
+    install()
+    expect(
+      naiveAcceptance(
+        tip(
+          file("src/a.test.ts", 'it("[AC-2] old")', 'it("[AC-2] old")\nit("[AC-1] adds")'),
+          file("src/b.test.ts", undefined, 'it("helper")'),
+          file("src/calc.ts", "x", "AC-2"),
+        ),
+      ),
+    ).toEqual({ hash: "abc", tests: ["src/a.test.ts"], ids: ["AC-1"] })
+  })
+
+  it("refuses a rebuild whose tests leave out an ID, naming the naive tests to carry over", () => {
+    install([file("src/calc.test.ts", undefined, 'it("[AC-1] adds")')])
+    expect(() =>
+      requireAcceptance({ hash: "abc", tests: ["src/a.test.ts"], ids: ["AC-1", "AC-2"] }, "c0"),
+    ).toThrow(
+      /^gtd land: rebuild-acceptance: .*leave out AC-2 — .*git show abc -- 'src\/a\.test\.ts'/,
+    )
+  })
+
+  it("refuses a fix turn that itself drops a carried ID, never one that leaves it alone", () => {
+    const acceptance = { hash: "abc", tests: [], ids: ["AC-1"] }
+    install([file("src/calc.test.ts", 'it("[AC-1] adds")', 'it("adds")')])
+    expect(() => requireAcceptanceKept(acceptance)).toThrow(/drops AC-1/)
+    install([file("src/calc.ts", "a", "b")])
+    expect(() => requireAcceptanceKept(acceptance)).not.toThrow()
+  })
+
+  it("passes a rebuild whose tests name every ID, wherever they live", () => {
+    install([
+      file("tests/x.test.ts", undefined, 'it("[AC-1] adds")'),
+      file("tests/y.feature", "", "Scenario: [AC-2] subtracts"),
+    ])
+    expect(() =>
+      requireAcceptance({ hash: "abc", tests: ["src/a.test.ts"], ids: ["AC-1", "AC-2"] }, "c0"),
+    ).not.toThrow()
+  })
+})
+
 describe("acceptanceFault", () => {
   const requirements = "# R\n\n## Acceptance Criteria\n\n- AC-1: adds.\n- AC-2: subtracts.\n"
   const file = (path: string, status: Change["status"], after: string): Change => ({
@@ -231,6 +295,7 @@ describe("acceptanceFault", () => {
 
 const REVIEW = ".gtd/REVIEW.md"
 const REFACTOR = ".gtd/REFACTOR.md"
+const NOTE = ".gtd/REFACTOR-NOTE.md"
 const reviewDoc = [
   "# Review: abc1234",
   "",
@@ -267,6 +332,7 @@ const driveSeam = async (
   const files = new Map<string, string>([["src/a.ts", "a"]])
   let current = "c0"
   const effects: Record<string, () => void> = {
+    note: () => void files.set(NOTE, "Seam: a shared op"),
     deriving: () => void files.set(REFACTOR, "package"),
     closing: () => void files.delete(REFACTOR),
     "review.reviewing": () => void files.set(REVIEW, reviewDoc),
@@ -366,8 +432,15 @@ describe("seamBuild", () => {
 
   it("refactor-first runs the reviewed refactor in slice refactor and resolves HEAD after it", async () => {
     const h = await driveSeam("refactor-first")
-    expect(h.outcome).toEqual({ reference: "abc", base: "after-refactor", refactored: true })
+    expect(h.outcome).toEqual({
+      reference: "abc",
+      base: "after-refactor",
+      refactored: true,
+      rebuild: { note: "Seam: a shared op", acceptance: { hash: "abc", tests: [], ids: [] } },
+    })
     expect(h.slices).toEqual(["refactor"])
+    expect(h.names.indexOf("seam.note")).toBe(h.names.indexOf("seam.judge") + 1)
+    expect(h.inside.refactor).not.toContain("seam.note")
     expect(h.inside.refactor![0]).toBe("refactor.deriving")
     expect(h.inside.refactor).toContain("refactor.build.review.closing")
     expect(h.names.some((n) => n.includes("approve"))).toBe(false)
@@ -378,7 +451,11 @@ describe("seamBuild", () => {
     const h = await driveSeam("refactor-first", change("src/a.test.ts", "modified"), {
       seamAllow: ".gtd/**",
     })
-    expect(h.outcome).toEqual({ reference: "abc", base: "c-base" })
+    expect(h.outcome).toEqual({
+      reference: "abc",
+      base: "c-base",
+      rebuild: { acceptance: { hash: "abc", tests: [], ids: [] } },
+    })
     expect(h.slices).toEqual([])
     expect(h.names).not.toContain("seam.by-hand")
     expect(h.names.some((n) => n.startsWith("refactor"))).toBe(false)
@@ -403,7 +480,11 @@ describe("seamBuild", () => {
     })
     expect(h.slices).toEqual([])
     expect(h.names).toContain("seam.by-hand")
-    expect(h.outcome).toEqual({ reference: "abc", base: "c-base" })
+    expect(h.outcome).toEqual({
+      reference: "abc",
+      base: "c-base",
+      rebuild: { acceptance: { hash: "abc", tests: [], ids: [] } },
+    })
   })
 })
 
@@ -472,6 +553,30 @@ describe("implement", () => {
     expect(bare).toBe(await building(undefined))
   })
 
+  it("a rebuild quotes the refactor note and names the naive acceptance tests to carry over", async () => {
+    const prompt = await building("abc", undefined, undefined, () =>
+      implement({
+        reference: "abc",
+        rebuild: {
+          note: "# Note\n\nSeam: a shared op",
+          acceptance: { hash: "abc", tests: ["src/a.test.ts"], ids: ["AC-1"] },
+        },
+        // The fixture's turn carries no test, so the acceptance guard refuses it after the prompt.
+      }).catch(() => undefined),
+    )
+    expect(prompt).toContain("  > Seam: a shared op")
+    expect(prompt).toContain("acceptance tests for AC-1")
+    expect(prompt).toContain("git show abc -- 'src/a.test.ts'")
+  })
+
+  it("a rebuild whose naive tests named no ID asks to carry nothing over", async () => {
+    const prompt = await building("abc", undefined, undefined, () =>
+      implement({ reference: "abc", rebuild: { acceptance: { hash: "abc", tests: [], ids: [] } } }),
+    )
+    expect(prompt).not.toContain("Carry over")
+    expect(prompt).not.toContain("refactor note")
+  })
+
   it("names the reference with a git show line", async () => {
     expect(await building("abc")).toContain("git show abc")
   })

package/src/workflows/feature/seam.ts

@@ -1,7 +1,9 @@
 import { posix } from "node:path"
 import {
+  agent,
   applyScript,
   changes,
+  changesSince,
   check,
   codeChanges,
   env,
@@ -11,6 +13,7 @@ import {
   kept,
   quote,
   read,
+  refuse,
   removeScript,
   run,
   scope,
@@ -21,7 +24,7 @@ import {
   type DiffShapeResult,
   type KeptTip,
 } from "../../flows/index.js"
-import { coder, FEEDBACK, REQUIREMENTS } from "../shared/steps.js"
+import { coder, FEEDBACK, REFACTOR_NOTE, REQUIREMENTS } from "../shared/steps.js"
 import * as t from "../shared/text.js"
 import { defaults } from "../shared/vars.js"
 import { green, requireCoverage } from "./coverage.js"
@@ -101,18 +104,26 @@ const addedLines = (change: Change): string => {
     .join("\n")
 }
 
+const acceptanceTests = (changes: readonly Change[]): readonly Change[] =>
+  changes.filter((c) => c.after !== undefined && isCode(c.path) && isTestFile(c.path))
+
+const idsOf = (file: string): string[] =>
+  (criteriaOf(read(file) ?? "") ?? []).map((c) => c.id).filter((id) => id !== "")
+
+// One rule for both gates, so a naive test carried over verbatim always satisfies the rebuild's.
+const unnamed = (ids: readonly string[], tests: readonly Change[]): string[] => {
+  const lines = tests.map(addedLines)
+  return ids.filter((id) => !lines.some((text) => named(id, text)))
+}
+
 /**
  * Why `tip`'s tests fall short, or `undefined`: a criterion ID of `file` no
  * test line of the pass names, or a test importing a file the pass added —
  * naive structure a reset and refactor replaces, which the tests must survive.
  */
 export const acceptanceFault = (file: string, tip: KeptTip): string | undefined => {
-  const ids = (criteriaOf(read(file) ?? "") ?? []).map((c) => c.id).filter((id) => id !== "")
-  const tests = tip.changes.filter(
-    (c) => c.after !== undefined && isCode(c.path) && isTestFile(c.path),
-  )
-  const lines = tests.map(addedLines)
-  const untested = ids.filter((id) => !lines.some((text) => named(id, text)))
+  const tests = acceptanceTests(tip.changes)
+  const untested = unnamed(idsOf(file), tests)
   if (untested.length > 0)
     return `acceptance-tests: no test of the naive pass names ${untested.join(", ")} — write a behaviour-level test for each criterion with its ID in the test or scenario name, e.g. "[${untested[0]}] …"`
   const added = tip.changes
@@ -131,6 +142,49 @@ export const acceptanceFault = (file: string, tip: KeptTip): string | undefined
   return undefined
 }
 
+/** What a rebuild carries over from the naive pass `tip`: the IDs its tests name, and those test files. */
+export const naiveAcceptance = (tip: KeptTip): t.Acceptance => {
+  const ids = idsOf(REQUIREMENTS)
+  const perTest = acceptanceTests(tip.changes).map((c) => {
+    const lines = addedLines(c)
+    return { path: c.path, ids: ids.filter((id) => named(id, lines)) }
+  })
+  return {
+    hash: tip.hash,
+    tests: perTest.filter((c) => c.ids.length > 0).map((c) => c.path),
+    ids: ids.filter((id) => perTest.some((c) => c.ids.includes(id))),
+  }
+}
+
+/**
+ * Refuse a rebuild whose test changes since `since` leave out an ID the naive
+ * pass's tests named. A skipped test still counts: the gate reads text, never runs it.
+ */
+export const requireAcceptance = (acceptance: t.Acceptance, since: string): void => {
+  const missing = unnamed(acceptance.ids, acceptanceTests(changesSince(since)))
+  if (missing.length === 0) return
+  refuse(
+    `gtd land: rebuild-acceptance: the rebuild's tests leave out ${missing.join(", ")} — carry over the naive pass's acceptance tests (\`git show ${acceptance.hash} -- ${acceptance.tests.map(quote).join(" ")}\`), each with its ID in the test or scenario name`,
+  )
+}
+
+/**
+ * Refuse a fix turn that, on its own, drops an ID the naive pass's tests named
+ * from a test file. Turn-local, so a person's edit at an escalation rest never
+ * wedges later fix turns.
+ */
+export const requireAcceptanceKept = (acceptance: t.Acceptance): void => {
+  const dropped = acceptance.ids.filter((id) =>
+    changes()
+      .filter((c) => isCode(c.path) && isTestFile(c.path))
+      .some((c) => named(id, c.before ?? "") && !named(id, c.after ?? "")),
+  )
+  if (dropped.length === 0) return
+  refuse(
+    `gtd land: rebuild-acceptance: this turn drops ${dropped.join(", ")} from the tests — the naive pass's acceptance tests stay; fix the code, not them`,
+  )
+}
+
 const restore = (path: string): string =>
   `if git cat-file -e ${quote(`HEAD:${path}`)} 2>/dev/null; then git checkout -q HEAD -- ${quote(path)}; else rm -f -- ${quote(path)}; fi`
 
@@ -166,6 +220,8 @@ const naiveGreen = (tip: KeptTip): Promise<boolean> => {
   )
 }
 
+export type { Acceptance, Rebuild } from "../shared/text.js"
+
 export interface ImplementOptions {
   readonly reference?: string | undefined
   readonly tier?: RiskTier | undefined
@@ -174,6 +230,8 @@ export interface ImplementOptions {
   readonly afterRefactor?: boolean | undefined
   /** A kept naive tip to apply as the implementation; built fresh only when it no longer applies. */
   readonly naive?: string | undefined
+  /** A rebuild after a refactor-first judgment: the note it plugs into, the acceptance tests it must carry. */
+  readonly rebuild?: t.Rebuild | undefined
 }
 
 /** Resolves `false` when the tip no longer applies (the failure is in `.gtd/FEEDBACK.md`) or has nothing outside `.gtd/` to apply. */
@@ -199,7 +257,10 @@ export function implement(
   const options: ImplementOptions =
     typeof first === "object" && first !== null ? first : { reference: first, tier, amend }
   return scope("implement", async () => {
-    if (options.naive === undefined || !(await applied(options.naive)))
+    const since = head()
+    const acceptance = options.rebuild?.acceptance
+    const built = options.naive === undefined || !(await applied(options.naive))
+    if (built)
       await t.agentWithSkills(
         "building",
         t.implementBuildingPrompt(
@@ -208,6 +269,7 @@ export function implement(
           options.amend,
           options.afterRefactor,
           flagModeOn(),
+          options.rebuild,
         ),
         {
           label: "Implementing",
@@ -217,14 +279,21 @@ export function implement(
         },
       )
     requireCriteriaFrozen(REQUIREMENTS)
-    await green()
+    if (built && acceptance !== undefined) requireAcceptance(acceptance, since)
+    // Fix turns are held to the carried tests too: deleting a red one must not buy a green suite.
+    await green(
+      built && acceptance !== undefined ? () => requireAcceptanceKept(acceptance) : undefined,
+    )
     await requireCoverage()
-    await run("closing", removeScript([REQUIREMENTS]), { label: "Closing out the implementation" })
+    await run("closing", removeScript([REQUIREMENTS, REFACTOR_NOTE]), {
+      label: "Closing out the implementation",
+    })
   })
 }
 
 interface Decision {
   readonly reference: string
+  readonly tip: KeptTip
   /** Absent on `land` (or with `flagMode` off, unjudged): the pass itself is the implementation. */
   readonly shape?: DiffShapeResult
 }
@@ -286,10 +355,10 @@ const vetted = async (tip: KeptTip, vetting: Vetting): Promise<Verdict | undefin
 /** The judge's ruling on a vetted pass: the decision, or the next attempt's verdict. */
 const ruled = async (tip: KeptTip, again: Vetting["again"]): Promise<Decision | Verdict> => {
   const shape = await judgeSeam(tip)
-  if (shape.choice === "land") return { reference: tip.hash }
-  if (shape.choice === "refactor-first") return { reference: tip.hash, shape }
+  if (shape.choice === "land") return { reference: tip.hash, tip }
+  if (shape.choice === "refactor-first") return { reference: tip.hash, tip, shape }
   const next = await again({ strays: shape.strays, p: shape.judgment?.answers.shape?.p ?? 0 })
-  return next.kind === "overruled" ? { reference: tip.hash } : next
+  return next.kind === "overruled" ? { reference: tip.hash, tip } : next
 }
 
 const decide = (): Promise<Decision> =>
@@ -301,7 +370,7 @@ const decide = (): Promise<Decision> =>
       const tip = kept("naive")!
       const outcome =
         (await vetted(tip, vetting)) ??
-        (flagModeOn() ? await ruled(tip, vetting.again) : { reference: tip.hash })
+        (flagModeOn() ? await ruled(tip, vetting.again) : { reference: tip.hash, tip })
       if (!("kind" in outcome)) return outcome
       retry = outcome.kind === "retry" ? outcome.retry : undefined
     }
@@ -315,10 +384,34 @@ export interface SeamOutcome {
   /** The feature slice's base: HEAD after the refactor on refactor-first, else the caller's base. */
   readonly base: string
   readonly refactored?: boolean
+  /** Set on refactor-first: what the rebuild carries over from the naive pass (the note only after a refactor). */
+  readonly rebuild?: t.Rebuild
+}
+
+/** Write the refactor note from the whole naive pass; a turn that changes anything else is refused. */
+export const refactorNote = async (
+  reference: string,
+  strays: readonly string[],
+): Promise<string> => {
+  await agent("note", t.refactorNotePrompt(reference, strays), {
+    label: "Writing the refactor note",
+    file: REFACTOR_NOTE,
+    model: coder(),
+    system: t.builderSystem(),
+  })
+  const others = changes()
+    .map((c) => c.path)
+    .filter((path) => path !== REFACTOR_NOTE)
+  const note = read(REFACTOR_NOTE) ?? ""
+  if (others.length > 0 || note.trim() === "")
+    refuse(
+      `gtd land: refactor-note: write ${REFACTOR_NOTE} and change nothing else${others.length > 0 ? ` — revert these:\n${others.map((path) => `  - ${path}`).join("\n")}` : ""}`,
+    )
+  return note
 }
 
 export const seamBuild = async (base: string): Promise<SeamOutcome> => {
-  const { reference, shape } = await decide()
+  const { reference, tip, shape } = await decide()
   if (shape === undefined) return { reference, base, land: true }
   if (shape.unreadable.length > 0) {
     await scope("seam", () =>
@@ -328,9 +421,17 @@ export const seamBuild = async (base: string): Promise<SeamOutcome> => {
         acceptClean: true,
       }),
     )
-    return { reference, base }
+    return { reference, base, rebuild: { acceptance: naiveAcceptance(tip) } }
+  }
+  const strays = refactorStrays(shape)
+  if (strays.length === 0) return { reference, base, rebuild: { acceptance: naiveAcceptance(tip) } }
+  const note = await scope("seam", () => refactorNote(reference, strays))
+  const refactored = await slice("refactor", () => reviewedRefactor(shape, { reference, note }))
+  return {
+    reference,
+    base: head(),
+    refactored,
+    // Fixed at `seam.note`, like the package's scope: a later edit of the file reaches neither turn.
+    rebuild: { note, acceptance: naiveAcceptance(tip) },
   }
-  if (refactorStrays(shape).length === 0) return { reference, base }
-  const refactored = await slice("refactor", () => reviewedRefactor(shape, { reference }))
-  return { reference, base: head(), refactored }
 }

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

@@ -8,8 +8,9 @@ const { defaults, envDefaults, feature, fix, review, ShippedOptions } = workflow
 const { flagShipped } = options
 
 describe("the shipped workflow factories", () => {
-  it("take exactly the settings the shipped workflows declare as options", () => {
-    expect(Object.keys(ShippedOptions.fields).sort()).toEqual(
+  it("take exactly the settings the shipped workflows declare as options, and contextLimit", () => {
+    const settings = Object.keys(ShippedOptions.fields).filter((name) => name !== "contextLimit")
+    expect(settings.sort()).toEqual(
       [...Object.keys(defaults), ...Object.keys(envDefaults)]
         .filter((name) => !name.startsWith("flag_"))
         .sort(),
@@ -23,6 +24,14 @@ describe("the shipped workflow factories", () => {
       expect(defaults).toHaveProperty(`flag_${name}`, defaultOn ? "1" : "0")
   })
 
+  it("keep contextLimit out of the settings", () => {
+    const built = configure(feature({ contextLimit: { hard: 0.8 } }))
+    expect(built).toMatchObject({ ok: true })
+    const build = built?.ok === true ? built.build : undefined
+    expect(build?.defaults).not.toHaveProperty("contextLimit")
+    expect(build?.envDefaults).not.toHaveProperty("contextLimit")
+  })
+
   it("declare a seamAllow default a factory option overrides", () => {
     expect(configure(feature({ seamAllow: "docs/**" }))).toMatchObject({
       ok: true,

package/src/workflows/shared/options.ts

@@ -6,6 +6,7 @@ import {
   type WorkflowDoors,
   type WorkflowFactory,
   refuse,
+  scope,
   vars,
 } from "../../flows/index.js"
 import { defaultFlagRegistry, defaults, envDefaults } from "./vars.js"
@@ -26,6 +27,13 @@ export const ShippedOptions = Schema.Struct({
   plannerModel: setting,
   coderModel: setting,
   flagMode: Schema.optionalWith(Schema.Boolean, { exact: true }),
+  contextLimit: Schema.optionalWith(
+    Schema.Struct({
+      soft: Schema.optionalWith(Schema.Number, { exact: true }),
+      hard: Schema.optionalWith(Schema.Number, { exact: true }),
+    }),
+    { exact: true },
+  ),
 })
 
 export type ShippedOptions = Schema.Schema.Encoded<typeof ShippedOptions>
@@ -50,6 +58,12 @@ export const flagModeOn = (): boolean => {
   return value === "true"
 }
 
+// Not a setting: a factory option is known at load, so the scope wraps the
+// whole flow without reading a setting before its first step. The engine
+// refuses limits it cannot use when it reaches an agent step.
+const limited = (flow: Flow, context: ShippedOptions["contextLimit"]): Flow =>
+  context === undefined ? flow : () => scope({ context }, flow)
+
 /** A shipped flow as a factory: its options override the settings it declares, each in its own kind. */
 export const shipped = (
   flow: Flow,
@@ -58,8 +72,8 @@ export const shipped = (
 ): WorkflowFactory<ShippedOptions> =>
   defineWorkflow(
     Schema.standardSchemaV1(ShippedOptions, { onExcessProperty: "error", errors: "all" }),
-    (options) => ({
-      flow,
+    ({ contextLimit, ...options }) => ({
+      flow: limited(flow, contextLimit),
       defaults: over(defaults, options),
       envDefaults: over(envDefaults, options),
       doors,
@@ -77,10 +91,10 @@ export const flagShipped = (
 ): WorkflowFactory<FlagOptions> =>
   defineWorkflow(
     Schema.standardSchemaV1(FlagOptions, { onExcessProperty: "error", errors: "all" }),
-    (options) => {
+    ({ contextLimit, ...options }) => {
       const flagDefaults = { ...defaults, flag: "", flagRegistry: defaultFlagRegistry }
       return {
-        flow,
+        flow: limited(flow, contextLimit),
         defaults: over(flagDefaults, options),
         envDefaults: over(envDefaults, options),
         doors: { [name]: { args: [{ name: "flag" }], vars: ({ flag }) => ({ flag: flag ?? "" }) } },

package/src/workflows/shared/steps.ts

@@ -12,6 +12,7 @@ export const ESCALATION = ".gtd/ESCALATION.md"
 export const REQUIREMENTS = ".gtd/REQUIREMENTS.md"
 export const REVIEW = ".gtd/REVIEW.md"
 export const REFACTOR = ".gtd/REFACTOR.md"
+export const REFACTOR_NOTE = ".gtd/REFACTOR-NOTE.md"
 export const QUALITY = ".gtd/QUALITY.md"
 
 export const planner = (): string => env.plannerModel ?? ""

package/src/workflows/shared/text.ts

@@ -350,22 +350,30 @@ export const refactorBuildingPrompt = ({
   pattern,
   reference,
   feedback = false,
+  note = false,
 }: {
   pkg: string
   strays: readonly string[]
   pattern: string
   reference?: string | undefined
   feedback?: boolean | undefined
+  note?: boolean | undefined
 }): string =>
   `${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
+  note
+    ? `- The package's \`## Refactor note\` section names the seams to open and the
+  shape each takes, written from the whole naive pass: build exactly those
 `
     : ""
-}${refactorRules(strays, pattern)}
+}${
+    feedback
+      ? `- The package carries a \`## Review feedback\` section: a human's review of the
+  last refactor. Act on it, within the rules below
+`
+      : ""
+  }${refactorRules(strays, pattern)}
 ${
   reference === undefined
     ? ""
@@ -1217,24 +1225,82 @@ ${criteriaBinding(false)}
 - Leave everything uncommitted and finish your turn — do not commit
 ${retry === undefined ? "" : naiveRetry(retry)}`
 
+/** The naive pass's kept tip, its acceptance test files and the criterion IDs they name. */
+export interface Acceptance {
+  readonly hash: string
+  readonly tests: readonly string[]
+  readonly ids: readonly string[]
+}
+
+/** What a rebuild after a refactor-first judgment carries over from the naive pass. */
+export interface Rebuild {
+  readonly note?: string | undefined
+  readonly acceptance?: Acceptance | undefined
+}
+
+const carries = (rebuild: Rebuild): boolean => (rebuild.acceptance?.ids.length ?? 0) > 0
+
+const rebuildLines = ({ note, acceptance }: Rebuild): string =>
+  `${
+    note === undefined
+      ? ""
+      : `- The refactor note (\`.gtd/REFACTOR-NOTE.md\`) named the seams the refactor
+  opened; plug the change into them:
+
+${note
+  .trimEnd()
+  .split("\n")
+  .map((line) => (line === "" ? "" : `  > ${line}`))
+  .join("\n")}
+
+`
+  }${
+    acceptance === undefined || !carries({ acceptance })
+      ? ""
+      : `- Carry over the naive pass's acceptance tests for ${acceptance.ids.join(", ")}, the
+  one part of it you take as it is: \`git show ${acceptance.hash} -- ${acceptance.tests.map(quote).join(" ")}\`.
+  Copy each test with its \`[AC-<n>]\` name into the tree as the refactor left
+  it — check a file out of the tip whole only where the refactor did not touch
+  it — changing only what reaches the release flag. A turn whose changed tests
+  leave an ID out is refused, and the suite must be green with them
+`
+  }`
+
+export const refactorNotePrompt = (reference: string, strays: readonly string[]): string =>
+  `${stateFileRules}
+- The seam judge ruled the naive pass refactor-first: it is never applied.
+  A behaviour-neutral refactor lands first, then the change is rebuilt on
+  the refactored base. Both turns read the note you write
+- Read the whole naive pass: \`git show ${reference}\`. It changed these
+  existing files outside the allowlist:
+${listed(strays)}
+- Write \`.gtd/REFACTOR-NOTE.md\`: which seams the refactor opens (the existing
+  code to restructure, by path and symbol) and the shape each takes — the
+  signatures and where the new behaviour will plug in. Name only the files
+  listed above: the refactor may change no other path. Never the feature's own
+  behaviour, and no flag read: the refactor adds neither
+- Change nothing else — a turn that does is refused
+- Leave everything uncommitted and finish your turn — do not commit
+`
+
+const afterRefactorLine = (rebuild: Rebuild): string =>
+  `- A reviewed refactor has just landed and may already carry part of the change,
+  though never a release flag. Build only what is still missing, held to every
+  rule below; if nothing is, ${carries(rebuild) ? "carry over the acceptance tests below and change nothing else" : "change nothing and finish your turn"}
+`
+
 export const implementBuildingPrompt = (
   reference: string | undefined,
   tier?: "low" | "high",
   amend?: boolean,
   afterRefactor?: boolean,
   flagMode = true,
+  rebuild: Rebuild = {},
 ): string =>
   `${stateFileRules}
 - Read \`.gtd/REQUIREMENTS.md\`: the settled requirements for this change
 ${criteriaBinding(true)}
-${
-  afterRefactor === true
-    ? `- A reviewed refactor has just landed and may already carry part of the change,
-  though never a release flag. Build only what is still missing, held to every
-  rule below; if nothing is, change nothing and finish your turn
-`
-    : ""
-}${
+${afterRefactor === true ? afterRefactorLine(rebuild) : ""}${
     amend === true
       ? `- The change already exists in the tree from an earlier lap; amend it to meet
   the re-derived requirements instead of rewriting it
@@ -1250,9 +1316,9 @@ ${
       ? ""
       : `- Reference only: \`git show ${reference}\` shows an earlier naive attempt.
   Read it for ideas; never apply, cherry-pick or check it out — write
-  the change fresh
+  the change fresh${carries(rebuild) ? ", its acceptance tests excepted (below)" : ""}
 `
-  }${
+  }${rebuildLines(rebuild)}${
     !flagMode
       ? "- Add no release flag — this project ships without release flags"
       : tier === "low"