@pmelab/gtd 40.0.0 → 42.0.0

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

@@ -48,7 +48,7 @@ interface Drive {
   readonly vars?: Readonly<Record<string, string>>
   /** The REVIEW.md the human leaves; defaults to `notes` laid over the baseline. */
   readonly after?: string
-  /** The REVIEW.md each `review.reviewing` turn writes, in order; also raises the review-turn stop to one past the last. */
+  /** The REVIEW.md each `review.composing` turn writes, in order; also raises the review-turn stop to one past the last. */
   readonly reviewDocs?: readonly (string | undefined)[]
   /** Let the run pass the second gate, stopping at the first range read after it. */
   readonly passSecondGate?: boolean
@@ -95,7 +95,7 @@ const drive = async (d: Drive): Promise<Run> => {
   let awaits = 0
   let reviews = 0
   const effects: Record<string, () => void> = {
-    "review.reviewing": () => {
+    "review.composing": () => {
       const docs = d.reviewDocs
       if (++reviews > (docs?.length ?? 0) + (docs === undefined ? 1 : 0)) throw new Stop()
       const written = docs?.[reviews - 1]
@@ -116,6 +116,7 @@ const drive = async (d: Drive): Promise<Run> => {
       gateMessages.push(request.options.message ?? "")
     }
     if (request.kind === "agent") prompts.set(request.name, request.prompt)
+    if (request.kind === "run") prompts.set(request.name, request.body)
     if (request.kind === "judge") asked.push(...request.questions)
   }
   const context = fixtureContext(
@@ -184,10 +185,10 @@ describe("the risk-fix pass", () => {
   it("a marked risk is fixed, kept green, re-reviewed, then rests at the gate", async () => {
     const run = await drive({ notes: [], reviewDocs: [risky, clean] })
     expect(run.log.slice(0, 5)).toEqual([
-      "review.reviewing",
+      "review.composing",
       "review.fix.risks.fixing",
       "health.check",
-      "review.reviewing",
+      "review.composing",
       "review.await-review",
     ])
     expect(run.prompts.get("review.fix.risks.fixing")).toContain("risk-1")
@@ -199,10 +200,10 @@ describe("the risk-fix pass", () => {
     const run = await drive({ notes: [], reviewDocs: [risky, risky] })
     expect(run.log.filter((n) => n === "review.fix.risks.fixing")).toHaveLength(1)
     expect(run.log.slice(0, 5)).toEqual([
-      "review.reviewing",
+      "review.composing",
       "review.fix.risks.fixing",
       "health.check",
-      "review.reviewing",
+      "review.composing",
       "review.await-review",
     ])
   })
@@ -232,7 +233,7 @@ describe("the risk-fix pass", () => {
   it("no marker means no fix-risks step", async () => {
     const run = await drive({ notes: [], reviewDocs: [clean] })
     expect(run.log).not.toContain("review.fix.risks.fixing")
-    expect(run.log[0]).toBe("review.reviewing")
+    expect(run.log[0]).toBe("review.composing")
     expect(run.log[1]).toBe("review.await-review")
   })
 
@@ -243,16 +244,16 @@ describe("the risk-fix pass", () => {
       reviewDocs: [undefined, risky, clean],
     })
     expect(run.log).toEqual([
-      "review.reviewing",
+      "review.composing",
       "review.await-review",
       "review.triage",
       "review.fix.nits.fixing",
       "health.check",
       "review.closing",
-      "review.reviewing",
+      "review.composing",
       "review.fix.risks.fixing",
       "health.check",
-      "review.reviewing",
+      "review.composing",
       "review.await-review",
     ])
   })
@@ -265,7 +266,7 @@ describe("the guard", () => {
   it("runs right after the risk-fix turn", async () => {
     const run = await drive({ notes: [], reviewDocs: [risky, clean], guarded: true })
     expect(run.log.slice(0, 4)).toEqual([
-      "review.reviewing",
+      "review.composing",
       "review.fix.risks.fixing",
       "guard",
       "health.check",
@@ -443,7 +444,7 @@ describe("review verdict routing", () => {
   it("an unanswered note counts as edit", async () => {
     const run = await drive({ notes: ["add — typo", "sub", "mul"], answers: {} })
     expect(run.log).toEqual([
-      "review.reviewing",
+      "review.composing",
       "review.await-review",
       "review.triage",
       "review.closing",
@@ -478,7 +479,7 @@ describe("review verdict routing", () => {
   it("only praise closes and signs off with no agent turn", async () => {
     const run = await drive({ notes, answers: { "note-1": verdict("praise") } })
     expect(run.log).toEqual([
-      "review.reviewing",
+      "review.composing",
       "review.await-review",
       "review.triage",
       "review.closing",
@@ -492,7 +493,7 @@ describe("review verdict routing", () => {
       answers: { "note-1": verdict("question"), "note-2": verdict("question") },
     })
     expect(run.log).toEqual([
-      "review.reviewing",
+      "review.composing",
       "review.await-review",
       "review.triage",
       "review.answer-review-questions",
@@ -508,17 +509,17 @@ describe("review verdict routing", () => {
       answers: { "note-1": verdict("question"), "note-2": verdict("nit") },
     })
     expect(run.log).toEqual([
-      "review.reviewing",
+      "review.composing",
       "review.await-review",
       "review.triage",
       "review.answer-review-questions",
       "review.fix.nits.fixing",
       "health.check",
       "review.closing",
-      "review.reviewing",
+      "review.composing",
     ])
     expect(run.prompts.get("review.fix.nits.fixing")).not.toContain("why?")
-    expect(run.prompts.get("review.reviewing")).toContain("Carry-over: commit `c4`")
+    expect(run.prompts.get("review.composing")).toContain("git show 'c4:.gtd/REVIEW.md'")
     expect(run.result).toBe("stopped")
   })
 
@@ -527,7 +528,8 @@ describe("review verdict routing", () => {
       notes: ["add — typo", "sub", "mul"],
       answers: { "note-1": verdict("nit") },
     })
-    expect(run.prompts.get("review.reviewing")).not.toContain("Carry-over")
+    expect(run.prompts.get("review.composing")).not.toContain("git show")
+    expect(run.prompts.get("review.composing")).toContain("## Fixed from your notes")
   })
 
   it("edits run after questions and nits, and the capture names only the edits and the answering commit", async () => {
@@ -536,7 +538,7 @@ describe("review verdict routing", () => {
       answers: { "note-2": verdict("question"), "note-3": verdict("nit") },
     })
     expect(run.log).toEqual([
-      "review.reviewing",
+      "review.composing",
       "review.await-review",
       "review.triage",
       "review.answer-review-questions",
@@ -556,7 +558,7 @@ describe("review verdict routing", () => {
   it("a noted round with no extractable note collects as one edit, without judging", async () => {
     const run = await drive({ notes: [], after: BEFORE + "\nSome stray prose.\n" })
     expect(run.log).toEqual([
-      "review.reviewing",
+      "review.composing",
       "review.await-review",
       "review.closing",
       "review.collecting",
@@ -679,7 +681,7 @@ describe("severity routing", () => {
       answers: { "note-1": verdict("edit"), ...sev("note-1", could) },
     })
     expect(run.log).toEqual([
-      "review.reviewing",
+      "review.composing",
       "review.await-review",
       "review.triage",
       "review.defer",
@@ -771,7 +773,7 @@ describe("severity routing", () => {
       passSecondGate: true,
     })
     expect(run.log).toEqual([
-      "review.reviewing",
+      "review.composing",
       "review.await-review",
       "review.triage",
       "review.answer-review-questions",
@@ -807,7 +809,7 @@ describe("BuildTailOptions.lensBase", () => {
             if (request.kind === "restart") return Promise.resolve()
             if (request.kind === "agent" && request.name.startsWith("quality."))
               prompts.push(request.prompt)
-            if (request.name === "review.reviewing") throw new Stop()
+            if (request.name === "review.composing") throw new Stop()
             return Promise.resolve()
           },
           pushScope: () => undefined,
@@ -1048,10 +1050,12 @@ describe("buildTail without rules", () => {
             if (request.kind === "agent") prompts.set(request.name, request.prompt)
             if (request.name === "health.check") checks++
             if (request.name === "fix.quality.fixing") files.delete(".gtd/QUALITY.md")
-            if (request.name === "review.reviewing" || request.name === "health.stop")
+            if (request.name === "review.composing" || request.name === "health.stop")
               throw new Stop()
             return Promise.resolve(
-              request.kind === "judge" ? { answers: {}, truncated: [] } : undefined,
+              request.kind === "judge"
+                ? { answers: { Q1: { answer: "mechanical", p: 0.9 } }, truncated: [] }
+                : undefined,
             )
           },
           pushScope: () => undefined,

package/src/workflows/feature/review.ts

@@ -1,12 +1,15 @@
 import {
   answered,
+  changesSince,
   head,
   judge,
   numeric,
   requireRevert,
   restoreScript,
   run,
+  showScript,
   vars,
+  writeScript,
   type JudgeQuestion,
   type Judgment,
   type ScopeAccess,
@@ -14,13 +17,14 @@ import {
 import type { ReviewNote } from "../../steering/index.js"
 import * as kit from "../../workflow-kit/index.js"
 import { guarded, healthy, type EscalationCount } from "../shared/health.js"
+import { NO_FINDINGS, type LensReport } from "../shared/lenses.js"
 import {
   awaitReview,
   fixCheck,
   fixRisks,
+  QUALITY,
   REQUIREMENTS,
   REVIEW,
-  reviewing,
   reviewMissing,
 } from "../shared/steps.js"
 import { closeReview, isOptionalObject, tail, type TailOptions } from "../shared/tail.js"
@@ -161,10 +165,37 @@ const triage =
 export const isCode = (path: string): boolean => path !== ".gtd" && !path.startsWith(".gtd/")
 
 /**
- * A reviewer writes `.gtd/REVIEW.md` over everything since `base`, a human
- * reviews and signs off or comments, and each note is judged: edits go to
- * another planning lap, questions are answered in place, nits fixed in one
- * batch, praise dropped.
+ * gtd writes `.gtd/REVIEW.md` from the quality lap's `report` — no reviewer
+ * turn — and removes what the fixer left in `.gtd/QUALITY.md`. A re-review
+ * after fixed nits restores the doc as committed at `carry`, answers kept.
+ */
+const composing = (
+  base: string,
+  report: LensReport,
+  carry?: string,
+  nitFix?: string,
+): Promise<void> =>
+  run(
+    "review.composing",
+    carry === undefined
+      ? writeScript(
+          REVIEW,
+          t.composedReview(base, {
+            ...report,
+            weakened: kit.removedAssertions(changesSince(base)),
+            nitFix,
+          }),
+          [QUALITY],
+        )
+      : showScript(carry, REVIEW, REVIEW),
+    { label: "Composing the review", file: REVIEW, base },
+  )
+
+/**
+ * The quality lap's notes reach a human over everything since `base`, who
+ * signs off or comments, and each note is judged: edits go to another
+ * planning lap, questions are answered in place, nits fixed in one batch,
+ * praise dropped.
  */
 export const review = (
   base: string,
@@ -182,13 +213,17 @@ export const review = (
   // Armed by a defer-only round to pick the next gate's message; a fresh
   // review (`reviewing`) disarms it.
   let deferred: readonly t.NoteInput[] = []
+  // Set by a nit fix, so the fresh review that follows names its commit.
+  let nitFix: string | undefined
   return kit.review(base, {
     file: REVIEW,
     feedback: feedback.file,
     isCode,
     reviewing: (b, carry) => {
       deferred = []
-      return reviewing(b, carry, options.lap)
+      const fixedAt = nitFix
+      nitFix = undefined
+      return composing(b, options.report ?? NO_FINDINGS, carry, fixedAt)
     },
     fixRisks: guarded((notes) => fixRisks(notes, fixAccess, rules), guard),
     keepGreen: () => healthy(() => fixCheck(rules), { escalations, guard, guardRests, rules }),
@@ -212,7 +247,10 @@ export const review = (
       return deferNotes(deferred, head())
     },
     answerQuestions: answerReviewQuestions,
-    fixNits: guarded((notes) => fixNits(notes, fixAccess, rules), guard),
+    fixNits: async (notes) => {
+      await guarded((n: typeof notes) => fixNits(n, fixAccess, rules), guard)(notes)
+      nitFix = head()
+    },
     close: closeReview,
     captures: {
       edits: t.reviewEditsCapture,
@@ -259,11 +297,13 @@ export interface BuildTailOptions extends TailOptions {
   readonly feedback?: FeedbackTarget | undefined
   /** Write access for the nit and risk fix turns; absent: the bundled `access` export decides. */
   readonly fixAccess?: ScopeAccess | undefined
-  /** Absent: "first". */
+  /** @deprecated No reviewer turn reads it since the review is composed. */
   readonly lap?: t.ReviewRange | undefined
+  /** What the triaged quality lap left for the review; absent: nothing. */
+  readonly report?: LensReport | undefined
 }
 
-/** The build tail: fix (when entered red), keep green unless `green`, the quality lap, then human review since `base`. */
+/** The build tail: fix (when entered red), keep green unless `green`, the triaged quality lap, then human review since `base`. */
 export function buildTail(base: string, options?: BuildTailOptions): Promise<kit.ReviewOutcome>
 /** @deprecated Pass `buildTail(base, { fixFirst, green, ...options })`. */
 export function buildTail(
@@ -287,7 +327,10 @@ export function buildTail(
     )
   }
   const [base, form] = options
-  return tail((escalations) => review(base, escalations, form), form)
+  return tail((escalations, report) => review(base, escalations, { ...form, report }), {
+    ...form,
+    triage: true,
+  })
 }
 
 const isOptionalBoolean = (value: unknown): value is boolean | null | undefined =>

package/src/workflows/feature/seam-rejection.feature

@@ -100,7 +100,7 @@ Feature: rejected naive passes walk one fixed path through the steer gate to the
     And step "implement.applying" runs its script
     When gtd lands
     And the process is driven
-    Then the process rests at "build.review.reviewing"
+    Then the process rests at "build.review.composing"
     And the commit subjects end with:
       """
       gtd(human): idle → unwind
@@ -124,7 +124,7 @@ Feature: rejected naive passes walk one fixed path through the steer gate to the
       gtd(check): implement.applying → implement.health.check
       gtd(check): implement.health.check → implement.coverage
       gtd(judge): implement.coverage → implement.closing
-      gtd(check): implement.closing → build.review.reviewing
+      gtd(check): implement.closing → build.review.composing
       """
     And the commit "gtd(human): idle → unwind" has a body containing "Gtd-Var: flag_risk_tier=0"
     And the commit "gtd(agent): seam.naive → seam.check" has a body containing "Gtd-Kept:"

package/src/workflows/feature/seam.feature

@@ -152,7 +152,7 @@ Feature: the naive pass and seam judge decide how a feature is built
       [{"id":"AC-1","answer":"yes","p":0.9}]
       """
     When the process is driven
-    Then the process rests at "build.review.reviewing"
+    Then the process rests at "build.review.composing"
     And "src/calc.ts" contains "subtract"
     And the commit subjects end with:
       """
@@ -160,7 +160,7 @@ Feature: the naive pass and seam judge decide how a feature is built
       gtd(check): implement.applying → implement.health.check
       gtd(check): implement.health.check → implement.coverage
       gtd(judge): implement.coverage → implement.closing
-      gtd(check): implement.closing → build.review.reviewing
+      gtd(check): implement.closing → build.review.composing
       """
     And ".gtd/REQUIREMENTS.md" does not exist
 

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

@@ -335,7 +335,7 @@ const driveSeam = async (
     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),
+    "review.composing": () => void files.set(REVIEW, reviewDoc),
     "review.closing": () => {
       files.delete(REVIEW)
       current = "after-refactor"

package/src/workflows/feature/slicing.feature

@@ -51,7 +51,7 @@ Feature: a change with more criteria than the cap is built in coarse slices
       [{"id":"AC-1","answer":"yes","p":0.9},{"id":"AC-2","answer":"yes","p":0.9}]
       """
     When the process is driven
-    Then the process rests at "build.review.reviewing"
+    Then the process rests at "build.review.composing"
     And the commit subjects end with:
       """
       gtd(human): design.gate.answer → seam.naive
@@ -60,7 +60,7 @@ Feature: a change with more criteria than the cap is built in coarse slices
       gtd(check): implement.applying → implement.health.check
       gtd(check): implement.health.check → implement.coverage
       gtd(judge): implement.coverage → implement.closing
-      gtd(check): implement.closing → build.review.reviewing
+      gtd(check): implement.closing → build.review.composing
       """
     And the output lines of gtd "slices" start with:
       """
@@ -112,7 +112,7 @@ Feature: a change with more criteria than the cap is built in coarse slices
       [{"id":"AC-2","answer":"yes","p":0.9}]
       """
     When the process is driven
-    Then the process rests at "build.review.reviewing"
+    Then the process rests at "build.review.composing"
     And the commit subjects end with:
       """
       gtd(agent): design.triage → design.gate.answer
@@ -129,7 +129,7 @@ Feature: a change with more criteria than the cap is built in coarse slices
       gtd(check): implement.applying → implement.health.check
       gtd(check): implement.health.check → implement.coverage
       gtd(judge): implement.coverage → implement.closing
-      gtd(check): implement.closing → build.review.reviewing
+      gtd(check): implement.closing → build.review.composing
       """
     And the output lines of gtd "slices" start with:
       """
@@ -268,7 +268,7 @@ Feature: a change with more criteria than the cap is built in coarse slices
       """
     When gtd lands
     And the process is driven
-    Then the process rests at "build.review.reviewing"
+    Then the process rests at "build.review.composing"
     And the commit subjects end with:
       """
       gtd(human): seam.steer → seam.naive
@@ -277,7 +277,7 @@ Feature: a change with more criteria than the cap is built in coarse slices
       gtd(check): implement.applying → implement.health.check
       gtd(check): implement.health.check → implement.coverage
       gtd(judge): implement.coverage → implement.closing
-      gtd(check): implement.closing → build.review.reviewing
+      gtd(check): implement.closing → build.review.composing
       """
     And ".gtd/REQUIREMENTS.md" does not exist
     And ".gtd/SLICES.md" does not exist

package/src/workflows/index.ts

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

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

@@ -116,3 +116,33 @@ describe("healthy describeGuard", () => {
     ).rejects.toThrow("guarded: nope")
   })
 })
+
+describe("healthy at the fix cap", () => {
+  // Blank reports are not comparable; at an 8-byte budget the cut trims both.
+  it.each([
+    ["could not compare", "", (n: number) => "\n".repeat(n)],
+    ["saw only cut", `, judgeBudgetBytes: "8"`, (n: number) => `a long failing report ${n}\n`],
+  ])("grants no extra turn on progress the judge %s", async (_, extra, report) => {
+    let runs = 0
+    const repo = testRepo({
+      workflow: [
+        `import { healthy } from "@pmelab/gtd/workflows"`,
+        `import { agent } from "@pmelab/gtd/flows"`,
+        `export const defaults = { judgeIdenticalMinP: "0.7"${extra} }`,
+        `export const held = async () => { await agent("first", "go"); await healthy(() => agent("fix", "go")) }`,
+        `export default held`,
+      ].join("\n"),
+      env: { GTD_TEST_COMMAND: "true" },
+    })
+    await repo.start("held")
+    const rest = await repo.drive({
+      first: (_, r) => r.write("start", "1\n"),
+      "health.check": (_, r) => r.write(".gtd/FEEDBACK.md", report(++runs)),
+      "health.judge": () => '[{"id":"verdict","answer":"progress","p":0.9}]',
+      fix: (_, r) => r.write("f", `${runs}\n`),
+      "health.recheck": (_, r) => r.write(".gtd/FEEDBACK.md", "red again\n"),
+    })
+    expect(rest.state).toBe("health.describe")
+    expect(repo.subjects().filter((s) => s.startsWith("gtd(agent): fix")).length).toBe(3)
+  })
+})

package/src/workflows/shared/health.ts

@@ -105,7 +105,10 @@ export const retryQuestion = (comparable: boolean): JudgeQuestion =>
           "new-failure: a materially different failure than before. progress: still red, but closer to green — the default if genuinely unsure.",
       }
 
-const sameFailure = async (previous: string, current: string): Promise<boolean> => {
+const compare = async (
+  previous: string,
+  current: string,
+): Promise<kit.RetryVerdict | undefined> => {
   const comparable = current.trim() !== "" && previous.trim() !== ""
   const { answers, truncated } = await judge("health.judge", {
     questions: [retryQuestion(comparable)],
@@ -113,12 +116,11 @@ const sameFailure = async (previous: string, current: string): Promise<boolean>
     message: t.healthJudgeMessage(),
     label: "Judging the retry",
   })
-  // Evidence the budget cut can make two different reports look alike: never sameness.
-  return (
-    comparable &&
-    truncated.length === 0 &&
-    answered(answers.verdict, "identical", numeric(vars.judgeIdenticalMinP, Infinity))
-  )
+  // Evidence the budget cut can make two different reports look alike: neither sameness nor progress.
+  if (!comparable || truncated.length > 0) return undefined
+  const minP = numeric(vars.judgeIdenticalMinP, Infinity)
+  if (answered(answers.verdict, "identical", minP)) return "identical"
+  return answered(answers.verdict, "progress", minP) ? "progress" : undefined
 }
 
 export interface HealthOptions {
@@ -153,7 +155,8 @@ const runSuite = (options: HealthOptions): Promise<boolean> =>
 /**
  * Loop until the suite is green: check, and on red run `fix` — escalating
  * first once `FIX_CAP` fixes are spent, or a judge calls the failure
- * identical to the previous round's. An escalation re-runs the suite once
+ * identical to the previous round's. A judge calling it progress at the cap
+ * buys one extra fix per run of fixes. An escalation re-runs the suite once
  * first; a green re-run ends the loop.
  */
 export const healthy = (fix: () => Promise<void>, options: HealthOptions = {}): Promise<void> =>
@@ -162,7 +165,7 @@ export const healthy = (fix: () => Promise<void>, options: HealthOptions = {}):
     report: FEEDBACK,
     fixCap: FIX_CAP,
     fixesSoFar: options.fixesSoFar ?? 0,
-    sameFailure,
+    compare,
     escalations: options.escalations ?? { rounds: 0 },
     recheck: () =>
       recheck("health.recheck", "health.check", { sweepOnGreen: healthSweep(options) }),

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

@@ -0,0 +1,39 @@
+import { afterEach, describe, expect, it } from "vitest"
+import { installContext } from "../../flows/index.js"
+import { headingSectionBodies } from "../../steering/index.js"
+import { findingsOf } from "./lenses.js"
+import { fixtureContext } from "./text.fixture.js"
+
+afterEach(() => installContext(undefined))
+
+const parse = (text: string) => {
+  installContext(fixtureContext({}, { sectionBodies: (t) => headingSectionBodies(t) }))
+  return findingsOf(text)
+}
+
+describe("findingsOf", () => {
+  it("numbers one finding per ## chunk, the heading cut from its body", () => {
+    expect(parse("# Quality\n\n## a\n\nfix a\n\n## b\n\nfix b\n")).toEqual([
+      { id: "Q1", title: "a", body: "fix a" },
+      { id: "Q2", title: "b", body: "fix b" },
+    ])
+  })
+
+  it("keeps prose outside every chunk as a finding of its own", () => {
+    expect(parse("# Quality\n\n- stray\n\n## a\n\nfix a\n")).toEqual([
+      { id: "Q1", title: "Quality findings", body: "- stray" },
+      { id: "Q2", title: "a", body: "fix a" },
+    ])
+  })
+
+  it("keeps prose a later lens wrote under a # heading after the chunks", () => {
+    expect(parse("## a\n\nfix a\n\n# Conventions\n\n- naming off\n")).toEqual([
+      { id: "Q1", title: "Quality findings", body: "- naming off" },
+      { id: "Q2", title: "a", body: "fix a" },
+    ])
+  })
+
+  it("reads a file with only a title as no finding", () => {
+    expect(parse("# Quality\n")).toEqual([])
+  })
+})