@pmelab/gtd 35.0.0 → 37.0.0

package/src/workflows/feature/seam.ts

@@ -1,7 +1,11 @@
 import { posix } from "node:path"
 import {
+  agent,
+  applyScript,
   changes,
+  changesSince,
   check,
+  codeChanges,
   env,
   head,
   human,
@@ -9,16 +13,18 @@ import {
   kept,
   quote,
   read,
+  refuse,
   removeScript,
   run,
   scope,
   slice,
   vars,
+  wrote,
   type Change,
   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"
@@ -98,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
@@ -128,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`
 
@@ -144,7 +201,7 @@ const naiveGreen = (tip: KeptTip): Promise<boolean> => {
     [
       ...paths,
       "dirty=$(git -c core.quotePath=false ls-files -m -d -o --exclude-standard)",
-      `if ! git diff --binary ${quote(`${tip.hash}^`)} ${quote(tip.hash)} -- | git apply; then`,
+      `if ! git diff --binary --no-color --no-ext-diff --no-textconv --src-prefix=a/ --dst-prefix=b/ ${quote(`${tip.hash}^`)} ${quote(tip.hash)} -- | git apply --whitespace=nowarn; then`,
       "  echo 'gtd: the kept naive pass no longer applies to HEAD; no test ran'",
       "  exit 1",
       "fi",
@@ -163,12 +220,26 @@ 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
   readonly amend?: boolean | undefined
   /** After a refactor slice, which may already carry the feature: an empty turn completes the step. */
   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. */
+const applied = async (tip: string): Promise<boolean> => {
+  await run("applying", applyScript(tip, FEEDBACK, t.naiveApplyFailure(tip), [".gtd"]), {
+    label: "Applying the naive pass",
+  })
+  return !wrote(FEEDBACK) && codeChanges().length > 0
 }
 
 export function implement(options?: ImplementOptions): Promise<void>
@@ -186,39 +257,51 @@ export function implement(
   const options: ImplementOptions =
     typeof first === "object" && first !== null ? first : { reference: first, tier, amend }
   return scope("implement", async () => {
-    await t.agentWithSkills(
-      "building",
-      t.implementBuildingPrompt(
-        options.reference,
-        options.tier,
-        options.amend,
-        options.afterRefactor,
-        flagModeOn(),
-      ),
-      {
-        label: "Implementing",
-        model: coder(),
-        system: t.builderSystem(),
-        ...(options.afterRefactor === true ? { allowEmpty: true } : {}),
-      },
-    )
+    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(
+          options.reference,
+          options.tier,
+          options.amend,
+          options.afterRefactor,
+          flagModeOn(),
+          options.rebuild,
+        ),
+        {
+          label: "Implementing",
+          model: coder(),
+          system: t.builderSystem(),
+          ...(options.afterRefactor === true ? { allowEmpty: true } : {}),
+        },
+      )
     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
-  /** Present only on `refactor-first`: the refactor runs before the implementation. */
+  readonly tip: KeptTip
+  /** Absent on `land` (or with `flagMode` off, unjudged): the pass itself is the implementation. */
   readonly shape?: DiffShapeResult
 }
 
 /** Resolves `true` when the human steered (edited), `false` on a clean overrule. */
 const steer = async (retry: t.NaiveRetry): Promise<boolean> => {
   await human("steer", {
-    message: t.seamSteerMessage(retry),
+    message: t.seamSteerMessage(retry, flagModeOn()),
     label: "Steer or overrule the naive pass",
     file: REQUIREMENTS,
     acceptClean: true,
@@ -272,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> =>
@@ -285,23 +368,51 @@ const decide = (): Promise<Decision> =>
     for (;;) {
       await naivePass(retry)
       const tip = kept("naive")!
-      const outcome = (await vetted(tip, vetting)) ?? (await ruled(tip, vetting.again))
+      const outcome =
+        (await vetted(tip, vetting)) ??
+        (flagModeOn() ? await ruled(tip, vetting.again) : { reference: tip.hash, tip })
       if (!("kind" in outcome)) return outcome
       retry = outcome.kind === "retry" ? outcome.retry : undefined
     }
   })
 
 export interface SeamOutcome {
-  /** The naive pass's kept tip: the first implement turn's reading material. */
+  /** The naive pass's kept tip: applied as the implementation when `land`, else the first implement turn's reading material. */
   readonly reference: string
+  /** The naive pass lands as it is: no build turn. */
+  readonly land?: boolean
   /** 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()
-  if (shape === undefined) return { reference, base }
+  const { reference, tip, shape } = await decide()
+  if (shape === undefined) return { reference, base, land: true }
   if (shape.unreadable.length > 0) {
     await scope("seam", () =>
       human("by-hand", {
@@ -310,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/review/review-door.feature

@@ -37,11 +37,17 @@ Feature: human review is the review door's, never the feature workflow's
       - AC-1: subtract(a, b) returns a - b.
       """
     And step "design.gate.answer" changes nothing
-    And step "implement.building" writes "src/calc.ts" with:
+    And step "seam.naive" writes "src/calc.test.ts" with:
+      """
+      it("[AC-1] subtracts", () => {})
+      """
+    And step "seam.naive" writes "src/calc.ts" with:
       """
       export const add = (a: number, b: number) => a + b
       export const subtract = (a: number, b: number) => a - b
       """
+    And step "seam.check" changes nothing
+    And step "implement.applying" runs its script
     And step "implement.health.check" changes nothing
     And step "implement.closing" runs its script
     And judge step "implement.coverage" answers:
@@ -56,8 +62,10 @@ Feature: human review is the review door's, never the feature workflow's
     And ".gtd/REVIEW.md" does not exist
     And the commit subjects end with:
       """
-      gtd(human): design.gate.answer → implement.building
-      gtd(agent): implement.building → implement.health.check
+      gtd(human): design.gate.answer → seam.naive
+      gtd(agent): seam.naive → seam.check
+      gtd(check): seam.check → implement.applying
+      gtd(check): implement.applying → implement.health.check
       gtd(check): implement.health.check → implement.coverage
       gtd(judge): implement.coverage → implement.closing
       gtd(check): implement.closing → idle
@@ -80,7 +88,7 @@ Feature: human review is the review door's, never the feature workflow's
       - [ ] ./src/calc.ts#2-2
         new subtract function
       """
-    When gtd opens door "review" with "HEAD~9"
+    When gtd opens door "review" with "HEAD~11"
     And the process is driven
     Then the process rests at "build.review.await-review"
     And the resting step's content contains the hash of the commit "feat: add calculator"

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.test.ts

@@ -1059,6 +1059,14 @@ describe("the seam phase's texts", () => {
     expect(message).not.toContain("outside the expected set")
   })
 
+  it("promises no judge on an overrule with flagMode off", () => {
+    for (const retry of [{ red: "abc123" }, { fault: "acceptance-tests: x", hash: "abc123" }]) {
+      const message = renderText(() => seamSteerMessage(retry, false))
+      expect(message).not.toContain("seam judge")
+      expect(message).toContain("it lands as the implementation")
+    }
+  })
+
   it("names every unreadable path for a by-hand landing", () => {
     const message = renderText(() =>
       seamByHandMessage(["vendor/a.bin", "src/flows/helpers.ts"], ["vendor/a.bin"], "abc123"),

package/src/workflows/shared/text.ts

@@ -58,6 +58,9 @@ export const agentWithSkills = (
 export const unwindFailure = (commit: string): string =>
   `gtd could not unwind ${commit} out of your working tree.`
 
+export const naiveApplyFailure = (commit: string): string =>
+  `gtd could not apply the naive pass ${commit} to the working tree; it is built fresh instead.`
+
 export const idleMessage = (): string =>
   `No active gtd process.
 
@@ -347,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
     ? ""
@@ -1197,8 +1208,8 @@ export const naivePassPrompt = (retry?: NaiveRetry): string =>
 - Read \`.gtd/REQUIREMENTS.md\`: the settled requirements for this change
 ${criteriaBinding(false)}
 - Implement them the quickest way that works — the naive version. Do not
-  restructure, abstract or refactor around the change; a later step judges
-  the shape of your diff and a reviewer makes it fit
+  restructure, abstract or refactor around the change; it may land exactly as
+  you leave it, and a reviewer makes it fit
 - Work breadth-first: rough out every part of the change before finishing any
   one, so a run cut off midway still shows the whole shape
 - Write behaviour-level acceptance tests, at least one per criterion, each
@@ -1214,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
@@ -1247,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"
@@ -1282,14 +1351,15 @@ An edit together with an approval counts as steer. Only
 branch unjudged.
 `
 
-export const seamSteerMessage = (retry: NaiveRetry): string =>
+/** `judged`: whether an overruled pass still meets the seam judge (`flagMode` on). */
+export const seamSteerMessage = (retry: NaiveRetry, judged = true): string =>
   isFault(retry)
     ? `The naive pass failed three times and the retries are spent. The last
 attempt's tests (\`git show ${retry.hash}\`) fall short:
 ${retry.fault}
 
 ${steerChoices(`land a clean tree to go on with the last attempt as it is:
-  \`seam.check\` runs its suite and the seam judge rules on its shape. Use it
+  \`seam.check\` runs its suite and ${judged ? "the seam judge rules on its shape" : "it lands as the implementation"}. Use it
   when the rule cannot fit this change (tests the globs do not see, or no
   entry point that existed before). Risk: a criterion may have no test that
   survives a later refactor — the choice is recorded in history.`)}`
@@ -1302,7 +1372,7 @@ Two ways forward (then run \`gtd land\`):
 - **Steer** — edit \`.gtd/REQUIREMENTS.md\` to redirect the change; the naive
   pass runs again with a fresh retry budget
 - **Overrule** — land a clean tree to go on with the last attempt as it is:
-  the seam judge rules on its shape, and the implementation's health loop
+  ${judged ? "the seam judge rules on its shape" : "it lands as the implementation"}, and the implementation's health loop
   must turn the suite green. Risk: the criteria's tests never passed on the
   naive pass — the choice is recorded in history.
 
@@ -1321,9 +1391,8 @@ Two ways forward (then run \`gtd land\`):
 - **Steer** — edit \`.gtd/REQUIREMENTS.md\` to redirect the change; the naive
   pass runs again with a fresh retry budget (the risk tier stays as the
   design gate settled it; a tier edit here is not applied)
-- **Overrule** — land a clean tree to accept the last attempt's approach:
-  the implementation is built against it as reference, with no seam gate
-  and no refactor. Risk: this ships the seam the judge objected to,
+- **Overrule** — land a clean tree to accept the last attempt as it is: it
+  lands as the implementation, with no seam gate and no refactor. Risk: this ships the seam the judge objected to,
   unaddressed — the choice is recorded in history.
 
 An edit together with an approval counts as steer. Only