@pmelab/gtd 27.3.0 → 27.5.0

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

@@ -17,6 +17,11 @@ import {
   buildReviewCollectingPrompt,
   designGateAnswerMessage,
   designTriagePrompt,
+  implementBuildingPrompt,
+  implementFixPrompt,
+  naivePassPrompt,
+  seamByHandMessage,
+  seamSteerMessage,
   summaryPrompt,
   withSkills,
 } from "./text.js"
@@ -441,3 +446,57 @@ describe("buildReviewReviewingPrompt scenarios", () => {
     expect(prompt).not.toContain("Weakened:")
   })
 })
+
+describe("the seam phase's texts", () => {
+  const rejection = { strays: ["src/flows/helpers.ts", "src/flows/runtime.ts"], p: 0.85 }
+
+  it("asks the first naive pass for the quickest working change, with no rejection", () => {
+    const prompt = renderText(() => naivePassPrompt())
+    expect(prompt).toContain(".gtd/REQUIREMENTS.md")
+    expect(prompt).not.toContain("rejected")
+  })
+
+  it("names the reject verdict, its p, every stray and the criterion on a retry", () => {
+    const prompt = renderText(() => naivePassPrompt(rejection))
+    expect(prompt).toContain("reject")
+    expect(prompt).toContain("0.85")
+    expect(prompt).toContain("`src/flows/helpers.ts`")
+    expect(prompt).toContain("`src/flows/runtime.ts`")
+    expect(prompt).toContain("solved the task the wrong way")
+  })
+
+  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")
+    expect(prompt).toContain("never apply")
+    expect(prompt).toContain("release flag")
+  })
+
+  it("keeps a fix turn to the feedback file's rules", () => {
+    expect(renderText(() => implementFixPrompt())).toContain(".gtd/FEEDBACK.md")
+  })
+
+  it("names both steer answers and the overrule risk, and lists every stray", () => {
+    const message = renderText(() => seamSteerMessage(rejection))
+    expect(message).toContain("edit `.gtd/REQUIREMENTS.md`")
+    expect(message).toContain("clean")
+    expect(message).toContain("Overrule")
+    expect(message).toContain("unaddressed")
+    expect(message).toContain("src/flows/helpers.ts")
+  })
+
+  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"),
+    )
+    expect(message).toContain("`vendor/a.bin` (unreadable)")
+    expect(message).toContain("`src/flows/helpers.ts`\n")
+    expect(message).toContain("git show abc123 --")
+  })
+
+  it("keeps a stray path with a newline on one line", () => {
+    const message = renderText(() => seamSteerMessage({ strays: ["a\nb.ts"], p: 0.9 }))
+    expect(message).toContain('`"a\\nb.ts"`')
+    expect(message).not.toContain("a\nb.ts")
+  })
+})

package/src/workflows/shared/text.ts

@@ -1,6 +1,7 @@
 import {
   agent,
   codeThreads,
+  displayPath,
   env,
   head,
   quote,
@@ -1017,3 +1018,88 @@ ${it.processCostByModel.map((m) => `- ${m.model}: ${m.cost}\n`).join("")}
 Print the closing message and stop — this writes nothing itself.
 `
 }
+
+// ── The seam phase (release flag `naive_pass`) ──────────────────────────────
+
+const listed = (paths: readonly string[], unreadable: readonly string[] = []): string =>
+  paths
+    .map(
+      (path) => `  - \`${displayPath(path)}\`${unreadable.includes(path) ? " (unreadable)" : ""}`,
+    )
+    .join("\n")
+
+export interface SeamRejection {
+  readonly strays: readonly string[]
+  readonly p: number
+}
+
+export const naivePassPrompt = (rejection?: SeamRejection): string =>
+  `${stateFileRules}
+- Read \`.gtd/REQUIREMENTS.md\`: the settled requirements for this change
+- 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
+- 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.
+`
+}`
+
+export const implementBuildingPrompt = (reference: string): string =>
+  `${stateFileRules}
+- Read \`.gtd/REQUIREMENTS.md\`: the settled requirements for this change
+- Implement them properly, fitting the codebase's seams and conventions
+- 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
+- Put the new behaviour behind a new release flag, following the
+  repository's flag conventions
+- Write the tests first, then the code that makes them pass
+- Leave \`.gtd/REQUIREMENTS.md\` in place and everything uncommitted, then
+  finish your turn
+`
+
+export const implementFixPrompt = (): string =>
+  `${stateFileRules}
+${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:
+${listed(rejection.strays)}
+
+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 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,
+  unaddressed — 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.
+`
+
+export const seamByHandMessage = (
+  strays: readonly string[],
+  unreadable: readonly string[],
+  reference: string,
+): string =>
+  `The judge could not read some of these files, so the diff was never
+fully judged and no refactor runs. Unreadable ones are marked:
+${listed(strays, unreadable)}
+
+See them with \`git show ${reference} -- <path>\` and review by hand. Land a
+clean tree to go on to the implementation, which runs next.
+`

package/src/workflows/shared/vars.ts

@@ -12,6 +12,10 @@ export const defaults: Readonly<Record<string, string>> = {
   reviewNoteActionable: "0.7",
   reviewSeverityMinP: "0.7",
   refactorFlagPattern: "\\bGTD_FLAG_\\w+",
+  seamAllow:
+    "**/*.test.*, **/*.spec.*, **/*.feature, **/tests/**, **/test/**, **/__tests__/**, .gtd/**",
+  // GTD_FLAG_NAIVE_PASS, recorded at process start; only "1" is on.
+  flag_naive_pass: "0",
   // Decides the turn count: one `build.quality.<lens>` scope per entry, each
   // keyed in `./skills.ts`.
   qualityReviews:

package/src/workflows/shared/workflows.steps.ts

@@ -1,7 +1,45 @@
-import { Given } from "quickpickle"
+import { After, Given, Then } from "quickpickle"
 import { CONFIG_SCAFFOLD } from "../../install/index.js"
+import assert from "node:assert"
 import type { TestkitWorld } from "../../testkit/index.js"
 
 Given("the shipped workflows, as gtd install scaffolds them", (world: TestkitWorld) => {
   world.configure(CONFIG_SCAFFOLD)
 })
+
+// Ambient, not explicit: the repository's own env is fixed when it is created,
+// and only a real environment variable can change between two steps of one process.
+const restores: (() => void)[] = []
+
+Given(
+  "the ambient environment variable {string} is {string}",
+  (_: TestkitWorld, name: string, value: string) => {
+    const before = process.env[name]
+    restores.push(() => {
+      if (before === undefined) delete process.env[name]
+      else process.env[name] = before
+    })
+    process.env[name] = value
+  },
+)
+
+After(() => {
+  while (restores.length > 0) restores.pop()!()
+})
+
+Then("the last commit body contains {string}", (world: TestkitWorld, text: string) => {
+  const message = world.repo().messages().at(-1) ?? ""
+  assert.ok(message.includes(text), message)
+})
+
+Then(
+  "the commit {string} has a body containing {string}",
+  (world: TestkitWorld, subject: string, text: string) => {
+    const message = world
+      .repo()
+      .messages()
+      .find((m) => m.split("\n")[0] === subject)
+    assert.ok(message !== undefined, `no commit "${subject}"`)
+    assert.ok(message.includes(text), message)
+  },
+)