@pmelab/gtd 32.0.0 → 33.0.0

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

@@ -124,3 +124,16 @@ describe("the feature workflow's own steps declare skills — a step's rendered
     expect(request.options).toMatchObject({ file: ".gtd/TODO.md" })
   })
 })
+
+describe("the feature workflow's planning steps run on the planner model", () => {
+  it("design triage defaults to smart and follows plannerModel", async () => {
+    const plain = await captureStep(() => steps.triage("base"), { scope: "design" })
+    const set = await captureStep(() => steps.triage("base"), {
+      scope: "design",
+      env: { plannerModel: "opus" },
+    })
+    if (plain.kind !== "agent" || set.kind !== "agent") throw new Error("unreachable")
+    expect(plain.options.model).toBe("smart")
+    expect(set.options.model).toBe("opus")
+  })
+})

package/src/workflows/index.ts

@@ -19,7 +19,7 @@ export {
   tail,
   type TailOptions,
 } from "./shared/tail.js"
-export { lensesOf } from "../workflow-kit/index.js"
+export { lensEntriesOf, lensesOf, lensOf } from "../workflow-kit/index.js"
 export * from "./feature/steps.js"
 export * from "./feature/criteria.js"
 export * from "./feature/planning.js"

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

@@ -107,4 +107,11 @@ describe("the bundled workflow's skills export", () => {
         .sort(),
     ).toEqual(["build.quality.correctness", "build.quality.my-lens"])
   })
+
+  it("keys a hinted entry by its lens alone, with the lens's own skills", () => {
+    const custom = skills({ ...defaults, qualityReviews: "my-lens=smart, correctness = base" })
+    expect(custom["build.quality.my-lens"]).toEqual(["my-lens"])
+    expect(custom["build.quality.correctness"]).toEqual(["code-review-and-quality"])
+    expect(Object.keys(custom).some((k) => k.includes("="))).toBe(false)
+  })
 })

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

@@ -107,3 +107,48 @@ describe("the bundled workflow's steps declare skills — a bundled step's rende
     expect(carried.prompt).toContain("Carry-over: commit `abc1234`")
   })
 })
+
+describe("the bundled workflow's model hints", () => {
+  const modelOf = async (
+    fn: () => Promise<void>,
+    context: Parameters<typeof captureStep>[1] = {},
+  ): Promise<string | undefined> => {
+    const request = await captureStep(fn, { scope: "build", ...context })
+    if (request.kind !== "agent") throw new Error(`expected an agent step, got ${request.kind}`)
+    return request.options.model
+  }
+
+  it.each([
+    ["correctness", "smart"],
+    ["owasp-security", "smart"],
+    ["spec-challenge", "smart"],
+    ["conventions", "base"],
+    ["ponytail-review", "base"],
+    ["test-audit", "base"],
+    ["my-lens", "smart"],
+  ])("lens %s defaults to %s", async (lens, model) => {
+    expect(await modelOf(() => steps.reviewQuality(lens))).toBe(model)
+  })
+
+  it("a lens's default follows the planner or coder setting it stands for", async () => {
+    const env = { plannerModel: "opus", coderModel: "sonnet" }
+    expect(await modelOf(() => steps.reviewQuality("correctness"), { env })).toBe("opus")
+    expect(await modelOf(() => steps.reviewQuality("conventions"), { env })).toBe("sonnet")
+  })
+
+  it("a model passed in wins over the lens's default; a blank one is none", async () => {
+    expect(await modelOf(() => steps.reviewQuality("correctness", undefined, "base"))).toBe("base")
+    expect(await modelOf(() => steps.reviewQuality("conventions", undefined, "opus"))).toBe("opus")
+    expect(await modelOf(() => steps.reviewQuality("conventions", undefined, ""))).toBe("base")
+  })
+
+  it("a lens named like an Object member still gets its default", async () => {
+    expect(await modelOf(() => steps.reviewQuality("constructor"))).toBe("smart")
+  })
+
+  it("the fix loop runs on the coder model, base by default", async () => {
+    expect(await modelOf(() => steps.fixCheck())).toBe("base")
+    expect(await modelOf(() => steps.fixQuality())).toBe("base")
+    expect(await modelOf(() => steps.fixCheck(), { env: { coderModel: "sonnet" } })).toBe("sonnet")
+  })
+})

package/src/workflows/shared/steps.ts

@@ -66,15 +66,17 @@ export const builtInLenses: Readonly<Record<string, BuiltInLens>> = {
   "spec-challenge": { skills: [], brief: t.specChallengeBrief },
 }
 
+const coderLenses: ReadonlySet<string> = new Set(["conventions", "ponytail-review", "test-audit"])
+
 /** One quality review through `lens`; each lens is its own scope, so its own conversation and skills. */
-export const reviewQuality = (lens: string, base?: string): Promise<void> =>
+export const reviewQuality = (lens: string, base?: string, model?: string): Promise<void> =>
   t.agentWithSkills(
     `quality.${lens}.reviewing`,
     t.buildQualityReviewingPrompt(lens, builtInLenses[lens]?.brief, base),
     {
       label: "Reviewing (one quality lens)",
       file: QUALITY,
-      model: planner(),
+      model: model || (coderLenses.has(lens) ? coder() : planner()),
       system: t.reviewerSystem(),
       allowEmpty: true,
     },

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

@@ -208,18 +208,23 @@ describe("the hand-off review", () => {
 })
 
 const prompts: string[] = []
+const models: (string | undefined)[] = []
 
 describe("the quality lap's lenses", () => {
   const lap = async (run: () => Promise<unknown>, vars: Record<string, string> = {}) => {
     const log: string[] = []
     prompts.length = 0
+    models.length = 0
     installContext(
       fixtureContext(
         { vars },
         {
           step: (request: StepRequest) => {
             if (request.kind !== "restart") log.push(request.name)
-            if (request.kind === "agent") prompts.push(request.prompt)
+            if (request.kind === "agent") {
+              prompts.push(request.prompt)
+              models.push(request.options.model)
+            }
             return Promise.resolve()
           },
           pushScope: () => undefined,
@@ -279,6 +284,31 @@ describe("the quality lap's lenses", () => {
     expect(prompts[0]).not.toContain("from `R`")
   })
 
+  it("each lens runs on its qualityReviews hint, else its default, under its plain name", async () => {
+    const log = await lap(() => qualityLap(), {
+      qualityReviews: "correctness=base, conventions, my-lens",
+    })
+    expect(log).toEqual([
+      "quality.correctness.reviewing",
+      "quality.conventions.reviewing",
+      "quality.my-lens.reviewing",
+    ])
+    expect(models).toEqual(["base", "base", "smart"])
+  })
+
+  it("lenses passed in carry their own hints, never qualityReviews'", async () => {
+    const log = await lap(
+      () =>
+        tail(() => Promise.resolve(), {
+          green: true,
+          lenses: ["correctness", "conventions=opus"],
+        }),
+      { qualityReviews: "correctness=base" },
+    )
+    expect(log).toEqual(["quality.correctness.reviewing", "quality.conventions.reviewing"])
+    expect(models).toEqual(["smart", "opus"])
+  })
+
   it("tail passes lenses to its lap and a guard after each lens turn", async () => {
     let guards = 0
     const log = await lap(() =>

package/src/workflows/shared/tail.ts

@@ -35,8 +35,11 @@ export const qualityLap = (
   base?: string,
 ): Promise<"clean" | "findings"> =>
   kit.qualityLap(
-    lenses ?? kit.lensesOf(vars.qualityReviews ?? ""),
-    guarded((lens: string) => reviewQuality(lens, base), guard),
+    lenses ?? kit.lensEntriesOf(vars.qualityReviews ?? ""),
+    guarded((entry: string) => {
+      const { lens, model } = kit.lensOf(entry)
+      return reviewQuality(lens, base, model)
+    }, guard),
     QUALITY,
   )
 
@@ -77,7 +80,7 @@ export interface TailOptions {
   readonly green?: boolean | undefined
   /** Runs after every code-changing turn: fix-check, quality fix, risk fix, nit fix, escalation describe. */
   readonly guard?: Guard | undefined
-  /** Quality-lap lenses; default `lensesOf(vars.qualityReviews)`. */
+  /** Quality-lap lens entries, `<lens>` or `<lens>=<model>`; default `lensEntriesOf(vars.qualityReviews)`. */
   readonly lenses?: readonly string[] | undefined
   /** `false` leaves the escalation's human rests unguarded; default `true`. */
   readonly guardRests?: boolean | 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\`):