@pmelab/gtd 32.1.0 → 33.0.0

package/src/workflows/feature/seam.ts

@@ -1,14 +1,20 @@
+import { posix } from "node:path"
 import {
   changes,
+  check,
+  env,
   head,
   human,
   judgeDiffShape,
   kept,
+  quote,
+  read,
   removeScript,
   run,
   scope,
   slice,
   vars,
+  type Change,
   type DiffShapeResult,
   type KeptTip,
 } from "../../flows/index.js"
@@ -16,12 +22,19 @@ import { healthy } from "../shared/health.js"
 import { coder, FEEDBACK, REQUIREMENTS } from "../shared/steps.js"
 import * as t from "../shared/text.js"
 import { defaults } from "../shared/vars.js"
-import { requireCriteria, requireCriteriaFrozen } from "./criteria.js"
-import { refactorStrays, reviewedRefactor } from "./refactor.js"
+import { criteriaOf, requireCriteria, requireCriteriaFrozen } from "./criteria.js"
+import {
+  COMMENT,
+  holdsCallSites,
+  isTestFile,
+  refactorStrays,
+  reviewedRefactor,
+} from "./refactor.js"
+import { isCode } from "./review.js"
 import { flagModeOn } from "../shared/options.js"
 import type { RiskTier } from "./tier.js"
 
-/** Naive-pass retries after a `reject`; the next `reject` rests at `seam.steer`. */
+/** Naive-pass retries after a `reject` or a red suite; the next one rests at `seam.steer`. */
 const NAIVE_RETRIES = 2
 
 /** A change to an existing file outside the allowlist is a stray even when the task needs it: the judge decides. */
@@ -35,14 +48,121 @@ export const judgeSeam = (tip: KeptTip): Promise<DiffShapeResult> =>
     exempt: tip.changes.filter((c) => c.status === "added").map((c) => c.path),
   })
 
-export const naivePass = (rejection?: t.SeamRejection): Promise<void> =>
-  t.agentWithSkills("naive", t.naivePassPrompt(rejection), {
-    label: rejection === undefined ? "Writing the naive pass" : "Rewriting the naive pass",
+export const naivePass = (retry?: t.NaiveRetry): Promise<void> =>
+  t.agentWithSkills("naive", t.naivePassPrompt(retry), {
+    label: retry === undefined ? "Writing the naive pass" : "Rewriting the naive pass",
     keep: true,
     model: coder(),
     system: t.builderSystem(),
   })
 
+// Only a string an import, `require` or `mock` call takes: a URL route or path-like data is not one.
+const IMPORTED = /(?:\bfrom|\bimport|\brequire\s*\(|\bmock\s*\()\s*\(?\s*(["'`])([^"'`\n]+)\1/g
+const EXTENSION = /\.[\w-]+$/
+const ALIAS = /^(?:[@~]\/|#)/
+
+/** The specifiers an added `path` answers to: itself, without its extension, and its directory for an `index`. */
+const namesOf = (path: string): string[] => {
+  const bare = path.replace(EXTENSION, "")
+  return posix.basename(bare) === "index" ? [path, bare, posix.dirname(bare)] : [path, bare]
+}
+
+/**
+ * The repository paths `test` imports, each with and without an extension: a
+ * relative specifier resolved from its directory, an aliased one (`@/`, `~/`,
+ * `#`) as a path tail, anything else as written. Comments are skipped; a
+ * computed import goes unseen.
+ */
+const importsOf = (test: Change): { readonly path: string; readonly tail: boolean }[] =>
+  [...(test.after ?? "").replace(COMMENT, "").matchAll(IMPORTED)].flatMap(([, , spec]) => {
+    const relative = /^\.\.?(\/|$)/.test(spec!)
+    const tail = ALIAS.test(spec!)
+    const path = relative ? posix.join(posix.dirname(test.path), spec!) : spec!.replace(ALIAS, "")
+    return [path, path.replace(EXTENSION, "")].map((p) => ({ path: p, tail }))
+  })
+
+const reaches = (imports: ReturnType<typeof importsOf>, added: string): boolean =>
+  namesOf(added).some((name) =>
+    imports.some(({ path, tail }) => name === path || (tail && name.endsWith(`/${path}`))),
+  )
+
+const named = (id: string, text: string): boolean =>
+  new RegExp(`(?<![\\w-])${id}(?!\\d)`).test(text)
+
+/** The lines `change` added: an ID an earlier change left in the file does not count. */
+const addedLines = (change: Change): string => {
+  const before = new Set((change.before ?? "").split("\n"))
+  return change
+    .after!.split("\n")
+    .filter((line) => !before.has(line))
+    .join("\n")
+}
+
+/**
+ * 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)))
+  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
+    .filter((c) => c.status === "added" && isCode(c.path) && !isTestFile(c.path))
+    .map((c) => c.path)
+  const reaching = tests
+    .filter((test) => holdsCallSites(test.path))
+    .flatMap((test) => {
+      const imports = importsOf(test)
+      return added
+        .filter((path) => reaches(imports, path))
+        .map((path) => `  - ${test.path} → ${path}`)
+    })
+  if (reaching.length > 0)
+    return `acceptance-internals: these tests import files the naive pass added — test through code that existed before it (a public entry point, an existing module's exports):\n${reaching.join("\n")}`
+  return undefined
+}
+
+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`
+
+/**
+ * Run the suite with `tip`'s diff applied, then take it out again; resolves
+ * `true` when green. The pass's paths go back to HEAD before (an interrupted
+ * run left them applied) and after; afterwards so does anything else the run
+ * changed, judged against what was already dirty, which is left alone.
+ */
+const naiveGreen = (tip: KeptTip): Promise<boolean> => {
+  const paths = tip.changes.map((c) => restore(c.path))
+  return check(
+    "check",
+    [
+      ...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`,
+      "  echo 'gtd: the kept naive pass no longer applies to HEAD; no test ran'",
+      "  exit 1",
+      "fi",
+      "(",
+      env.testCommand ?? "",
+      ")",
+      "code=$?",
+      ...paths,
+      "git -c core.quotePath=false ls-files -m -d -o --exclude-standard | while IFS= read -r path; do",
+      '  printf \'%s\\n\' "$dirty" | grep -qxF -- "$path" && continue',
+      '  if git cat-file -e "HEAD:$path" 2>/dev/null; then git checkout -q HEAD -- "$path"; else rm -f -- "$path"; fi',
+      "done",
+      'exit "$code"',
+    ].join("\n"),
+    { report: FEEDBACK, label: "Running the naive pass's tests" },
+  )
+}
+
 export interface ImplementOptions {
   readonly reference?: string | undefined
   readonly tier?: RiskTier | undefined
@@ -103,34 +223,79 @@ interface Decision {
   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),
+    label: "Steer or overrule the naive pass",
+    file: REQUIREMENTS,
+    acceptClean: true,
+  })
+  if (changes().length === 0) return false
+  requireCriteria(REQUIREMENTS)
+  return true
+}
+
+type Verdict =
+  | { readonly kind: "retry"; readonly retry: t.NaiveRetry }
+  | { readonly kind: "steered" }
+  | { readonly kind: "overruled" }
+
+/** Rejects, test faults and red checks share one budget; a steer or an overrule refills it. */
+const budget = (): ((next: t.NaiveRetry) => Promise<Verdict>) => {
+  let retries = 0
+  return async (next) => {
+    if (retries < NAIVE_RETRIES) {
+      retries++
+      return { kind: "retry", retry: next }
+    }
+    const steered = await steer(next)
+    retries = 0
+    // A steered or overruled red pass leaves its report behind: nothing reads it any more.
+    if (read(FEEDBACK) !== undefined)
+      await run("clear", removeScript([FEEDBACK]), { label: "Clearing the red check" })
+    return { kind: steered ? "steered" : "overruled" }
+  }
+}
+
+interface Vetting {
+  readonly again: ReturnType<typeof budget>
+  /** Set once a human overrules a test fault: the rule does not fit this change, so later passes skip it. */
+  waived: boolean
+}
+
+/** 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)
+  if (fault !== undefined) {
+    const verdict = await vetting.again({ fault, hash: tip.hash })
+    if (verdict.kind !== "overruled") return verdict
+    vetting.waived = true
+  }
+  if (await naiveGreen(tip)) return undefined
+  const verdict = await vetting.again({ red: tip.hash })
+  return verdict.kind === "overruled" ? undefined : verdict
+}
+
+/** 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 }
+  const next = await again({ strays: shape.strays, p: shape.judgment?.answers.shape?.p ?? 0 })
+  return next.kind === "overruled" ? { reference: tip.hash } : next
+}
+
 const decide = (): Promise<Decision> =>
   scope("seam", async () => {
-    let rejection: t.SeamRejection | undefined
-    let retries = 0
+    const vetting: Vetting = { again: budget(), waived: false }
+    let retry: t.NaiveRetry | undefined
     for (;;) {
-      await naivePass(rejection)
+      await naivePass(retry)
       const tip = kept("naive")!
-      const shape = await judgeSeam(tip)
-      if (shape.choice === "land") return { reference: tip.hash }
-      if (shape.choice === "refactor-first") {
-        return { reference: tip.hash, shape }
-      }
-      rejection = { strays: shape.strays, p: shape.judgment?.answers.shape?.p ?? 0 }
-      if (retries < NAIVE_RETRIES) {
-        retries++
-        continue
-      }
-      await human("steer", {
-        message: t.seamSteerMessage(rejection),
-        label: "Steer or overrule the rejected naive pass",
-        file: REQUIREMENTS,
-        acceptClean: true,
-      })
-      // Any edit steers, with a fresh budget and no stale rejection; clean overrules.
-      if (changes().length === 0) return { reference: tip.hash }
-      requireCriteria(REQUIREMENTS)
-      rejection = undefined
-      retries = 0
+      const outcome = (await vetted(tip, vetting)) ?? (await ruled(tip, vetting.again))
+      if (!("kind" in outcome)) return outcome
+      retry = outcome.kind === "retry" ? outcome.retry : undefined
     }
   })
 

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

@@ -965,6 +965,22 @@ describe("the seam phase's texts", () => {
     expect(prompt).toContain("solved the task the wrong way")
   })
 
+  it("asks for a breadth-first pass with ID-tagged behaviour tests, green before it ends", () => {
+    const prompt = renderText(() => naivePassPrompt())
+    expect(prompt).toContain("breadth-first")
+    expect(prompt).toContain("`[AC-3] …`")
+    expect(prompt).toContain("never a file this pass adds")
+    expect(prompt).toContain("green")
+  })
+
+  it("has a red retry pick up the kept attempt instead of starting over", () => {
+    const prompt = renderText(() => naivePassPrompt({ red: "abc123" }))
+    expect(prompt).toContain("left the suite red")
+    expect(prompt).toContain("git diff --binary abc123^ abc123 | git apply")
+    expect(prompt).toContain(".gtd/FEEDBACK.md")
+    expect(prompt).not.toContain("rejected")
+  })
+
   it("cites the reference as reading material only and asks for a new release flag", () => {
     const prompt = renderText(() => implementBuildingPrompt("abc123"))
     expect(prompt).toContain("git show abc123")
@@ -1019,6 +1035,30 @@ describe("the seam phase's texts", () => {
     expect(message).toContain("src/flows/helpers.ts")
   })
 
+  it("hands a faulty pass back with the fault and the kept attempt to pick up", () => {
+    const fault = {
+      fault: "acceptance-tests: no test of the naive pass names AC-2",
+      hash: "abc123",
+    }
+    const prompt = renderText(() => naivePassPrompt(fault))
+    expect(prompt).toContain("names AC-2")
+    expect(prompt).toContain("git diff --binary abc123^ abc123 | git apply")
+    const message = renderText(() => seamSteerMessage(fault))
+    expect(message).toContain("names AC-2")
+    expect(message).toContain("`seam.check` runs its suite")
+    expect(message).toContain("Overrule")
+  })
+
+  it("names the red suite, its report and what overruling it means", () => {
+    const message = renderText(() => seamSteerMessage({ red: "abc123" }))
+    expect(message).toContain("The last\nattempt left the suite red")
+    expect(message).toContain(".gtd/FEEDBACK.md")
+    expect(message).toContain("edit `.gtd/REQUIREMENTS.md`")
+    expect(message).toContain("Overrule")
+    expect(message).toContain("seam judge")
+    expect(message).not.toContain("outside the expected set")
+  })
+
   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

@@ -1134,31 +1134,72 @@ export interface SeamRejection {
   readonly p: number
 }
 
+/** A naive pass whose suite `seam.check` found red; `red` is its kept tip. */
+export interface NaiveRed {
+  readonly red: string
+}
+
+/** A naive pass whose tests break the acceptance-test rules; `hash` is its kept tip. */
+export interface NaiveFault {
+  readonly fault: string
+  readonly hash: string
+}
+
+export type NaiveRetry = SeamRejection | NaiveRed | NaiveFault
+
+const isRed = (retry: NaiveRetry): retry is NaiveRed => "red" in retry
+const isFault = (retry: NaiveRetry): retry is NaiveFault => "fault" in retry
+
+const pickUp = (hash: string): string =>
+  `Pick it up — \`git diff --binary ${hash}^ ${hash} | git apply\``
+
 const criteriaBinding = (refused: boolean): string =>
   `- Its \`## Acceptance Criteria\` (\`AC-<n>\`) bind this turn: re-read them from
   the file, never from memory, and stop only when each one holds. They are
   settled — ${refused ? "a turn that changes them is refused" : "leave them as they are"}`
 
-export const naivePassPrompt = (rejection?: SeamRejection): string =>
+const naiveRetry = (retry: NaiveRetry): string =>
+  isFault(retry)
+    ? `
+Your previous attempt's (\`${retry.hash}\`) tests fall short:
+${retry.fault}
+${pickUp(retry.hash)} — and fix its tests; do not start over.
+`
+    : isRed(retry)
+      ? `
+Your previous attempt (\`${retry.red}\`) left the suite red; \`.gtd/FEEDBACK.md\`
+holds the output. ${pickUp(retry.red)}
+— and fix it until the suite is green; do not start over.
+`
+      : `
+Your previous attempt was rejected: the judge answered \`reject\` (p=${retry.p}),
+meaning the naive pass solved the task the wrong way — discard it and
+re-implement. It changed these files outside the expected set:
+${listed(retry.strays)}
+Start over and choose a different approach; do not rebuild the same diff.
+`
+
+export const naivePassPrompt = (retry?: NaiveRetry): string =>
   `${stateFileRules}
 - 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
-- Add tests as you go, and leave \`.gtd/\` untouched
+- 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
+  naming its ID in the test or scenario name (\`[AC-3] …\`). Test through code
+  that existed before this pass — a public entry point, the CLI, an existing
+  module's exports — never a file this pass adds: that is naive structure a
+  later reset and refactor replaces. A pass that leaves a criterion's ID out
+  of its tests, or whose test imports a file it added, is sent back
+- Run \`${env.testCommand}\` and finish only once it is green with every
+  criterion's test passing: the next step runs it on your diff and sends a red
+  pass back
+- Leave \`.gtd/\` untouched
 - Leave everything uncommitted and finish your turn — do not commit
-${
-  rejection === undefined
-    ? ""
-    : `
-Your previous attempt was rejected: the judge answered \`reject\` (p=${rejection.p}),
-meaning the naive pass solved the task the wrong way — discard it and
-re-implement. It changed these files outside the expected set:
-${listed(rejection.strays)}
-Start over and choose a different approach; do not rebuild the same diff.
-`
-}`
+${retry === undefined ? "" : naiveRetry(retry)}`
 
 export const implementBuildingPrompt = (
   reference: string | undefined,
@@ -1216,9 +1257,49 @@ ${fixFeedbackPrompt}
 - Leave everything uncommitted and finish your turn — do not commit
 `
 
-export const seamSteerMessage = (rejection: SeamRejection): string =>
-  `The naive pass was rejected three times and the retries are spent.
-The last attempt changed these files outside the expected set:
+const steerChoices = (overrule: string): string => `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** — ${overrule}
+
+An edit together with an approval counts as steer. Only
+\`.gtd/REQUIREMENTS.md\` is meant to change here: any other edit lands on the
+branch unjudged.
+`
+
+export const seamSteerMessage = (retry: NaiveRetry): 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
+  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.`)}`
+    : isRed(retry)
+      ? `The naive pass failed three times and the retries are spent. The last
+attempt left the suite red: \`.gtd/FEEDBACK.md\` holds the last run's output; \`git show ${retry.red}\` shows
+the last attempt.
+
+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
+  must turn the suite green. Risk: the criteria's tests never passed on the
+  naive pass — the choice is recorded in history.
+
+An edit together with an approval counts as steer. Only
+\`.gtd/REQUIREMENTS.md\` is meant to change here: any other edit lands on the
+branch unjudged.
+`
+      : seamRejectedMessage(retry)
+
+const seamRejectedMessage = (rejection: SeamRejection): string =>
+  `The naive pass failed three times and the retries are spent. The judge
+rejected the last attempt: it changed these files outside the expected set:
 ${listed(rejection.strays)}
 
 Two ways forward (then run \`gtd land\`):