@pmelab/gtd 36.0.0 → 38.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,21 +13,28 @@ import {
   kept,
   quote,
   read,
+  refuse,
   removeScript,
   run,
   scope,
-  slice,
+  slice as sliced,
   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, SLICES } from "../shared/steps.js"
 import * as t from "../shared/text.js"
 import { defaults } from "../shared/vars.js"
 import { green, requireCoverage } from "./coverage.js"
-import { criteriaOf, requireCriteria, requireCriteriaFrozen } from "./criteria.js"
+import {
+  criterionIds,
+  requireCriteria,
+  requireCriteriaFrozen,
+  sliceIds,
+  type CriteriaSlice,
+} from "./criteria.js"
 import {
   COMMENT,
   holdsCallSites,
@@ -51,8 +60,8 @@ export const judgeSeam = (tip: KeptTip): Promise<DiffShapeResult> =>
     exempt: tip.changes.filter((c) => c.status === "added").map((c) => c.path),
   })
 
-export const naivePass = (retry?: t.NaiveRetry): Promise<void> =>
-  t.agentWithSkills("naive", t.naivePassPrompt(retry), {
+export const naivePass = (retry?: t.NaiveRetry, slice?: CriteriaSlice): Promise<void> =>
+  t.agentWithSkills("naive", t.naivePassPrompt(retry, sliceIds(slice)), {
     label: retry === undefined ? "Writing the naive pass" : "Rewriting the naive pass",
     keep: true,
     model: coder(),
@@ -101,18 +110,30 @@ 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, slice?: CriteriaSlice): string[] =>
+  criterionIds(read(file) ?? "", slice)
+
+// 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)))
+export const acceptanceFault = (
+  file: string,
+  tip: KeptTip,
+  slice?: CriteriaSlice,
+): string | undefined => {
+  const tests = acceptanceTests(tip.changes)
+  const untested = unnamed(idsOf(file, slice), 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 +152,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, slice?: CriteriaSlice): t.Acceptance => {
+  const ids = idsOf(REQUIREMENTS, slice)
+  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 +230,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 +240,14 @@ 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
+  /** The criteria this slice builds, when the change has more than one slice. */
+  readonly slice?: CriteriaSlice | undefined
+  /** Where the slice began: the coverage judge reads only the tests changed since. */
+  readonly base?: string | undefined
+  /** Not the last slice: `.gtd/REQUIREMENTS.md` and `.gtd/SLICES.md` stay for the next one. */
+  readonly more?: boolean | 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 +273,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 +285,8 @@ export function implement(
           options.amend,
           options.afterRefactor,
           flagModeOn(),
+          options.rebuild,
+          sliceIds(options.slice),
         ),
         {
           label: "Implementing",
@@ -217,14 +296,28 @@ export function implement(
         },
       )
     requireCriteriaFrozen(REQUIREMENTS)
-    await green()
-    await requireCoverage()
-    await run("closing", removeScript([REQUIREMENTS]), { label: "Closing out the implementation" })
+    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(options.base, options.slice)
+    await closing(options.more === true)
   })
 }
 
+/** The last slice's closing, for a last slice a steer left with no criterion to build. */
+export const closeOut = (): Promise<void> => scope("implement", () => closing(false))
+
+/** A slice with `more` after it keeps the criteria and the slicing for the next one. */
+const closing = (more: boolean): Promise<void> =>
+  run("closing", removeScript(more ? [REFACTOR_NOTE] : [REQUIREMENTS, REFACTOR_NOTE, SLICES]), {
+    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
 }
@@ -271,8 +364,12 @@ interface Vetting {
 }
 
 /** Sends a pass whose tests fall short or run red back (`undefined`: it goes on, an overruled one as it is). */
-const vetted = async (tip: KeptTip, vetting: Vetting): Promise<Verdict | undefined> => {
-  const fault = vetting.waived ? undefined : acceptanceFault(REQUIREMENTS, tip)
+const vetted = async (
+  tip: KeptTip,
+  vetting: Vetting,
+  slice: CriteriaSlice | undefined,
+): Promise<Verdict | undefined> => {
+  const fault = vetting.waived ? undefined : acceptanceFault(REQUIREMENTS, tip, slice)
   if (fault !== undefined) {
     const verdict = await vetting.again({ fault, hash: tip.hash })
     if (verdict.kind !== "overruled") return verdict
@@ -286,22 +383,22 @@ 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> =>
+const decide = (slice: CriteriaSlice | undefined): Promise<Decision> =>
   scope("seam", async () => {
     const vetting: Vetting = { again: budget(), waived: false }
     let retry: t.NaiveRetry | undefined
     for (;;) {
-      await naivePass(retry)
+      await naivePass(retry, slice)
       const tip = kept("naive")!
       const outcome =
-        (await vetted(tip, vetting)) ??
-        (flagModeOn() ? await ruled(tip, vetting.again) : { reference: tip.hash })
+        (await vetted(tip, vetting, slice)) ??
+        (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 +412,40 @@ 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
 }
 
-export const seamBuild = async (base: string): Promise<SeamOutcome> => {
-  const { reference, shape } = await decide()
+/** 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 interface SeamSlice {
+  /** Absent for a change built in one slice. */
+  readonly criteria?: CriteriaSlice | undefined
+  readonly refactor?: string | undefined
+}
+
+export const seamBuild = async (base: string, slice: SeamSlice = {}): Promise<SeamOutcome> => {
+  const { reference, tip, shape } = await decide(slice.criteria)
   if (shape === undefined) return { reference, base, land: true }
   if (shape.unreadable.length > 0) {
     await scope("seam", () =>
@@ -328,9 +455,20 @@ export const seamBuild = async (base: string): Promise<SeamOutcome> => {
         acceptClean: true,
       }),
     )
-    return { reference, base }
+    return { reference, base, rebuild: { acceptance: naiveAcceptance(tip, slice.criteria) } }
+  }
+  const strays = refactorStrays(shape)
+  if (strays.length === 0)
+    return { reference, base, rebuild: { acceptance: naiveAcceptance(tip, slice.criteria) } }
+  const note = await scope("seam", () => refactorNote(reference, strays))
+  const refactored = await sliced(slice.refactor ?? "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, slice.criteria) },
   }
-  if (refactorStrays(shape).length === 0) return { reference, base }
-  const refactored = await slice("refactor", () => reviewedRefactor(shape, { reference }))
-  return { reference, base: head(), refactored }
 }

package/src/workflows/feature/slicing-cap.feature

@@ -0,0 +1,14 @@
+@inmem
+Feature: a bad sliceMaxCriteria refuses the landing that would pin it
+
+  The cap is read right after idle, so a value that is not a positive integer
+  never gets pinned into a process that would refuse every later landing.
+
+  Scenario: a zero cap refuses the idle landing
+    Given the shipped workflows, as gtd install scaffolds them
+    And an environment variable "GTD_SLICEMAXCRITERIA" set to "0"
+    And a file "TODO.md" with:
+      """
+      # Something
+      """
+    Then driving the process is refused with "sliceMaxCriteria must be a positive integer, got \"0\""