@pmelab/gtd 46.0.0 → 48.0.0

package/src/workflows/fix/fix-lens-origin.feature

@@ -0,0 +1,101 @@
+@inmem
+Feature: each finding the reviewer is handed names the lens that wrote it
+
+  Lenses append to `.gtd/QUALITY.md` in turn, so a finding belongs to the lens
+  whose turn added it — even when two lenses give findings the same title,
+  which the review then tells apart by a numbered suffix.
+
+  Background:
+    Given the shipped workflows, as gtd install scaffolds them
+    And an environment variable "GTD_QUALITYREVIEWS" set to "correctness,tests"
+    And a file "src/calc.ts" with:
+      """
+      export const add = (a: number, b: number) => a + b
+      """
+    And the working tree is committed as "feat: add calculator"
+    And a file ".gtd/REVIEW.orig.md" with:
+      """
+      # Review: abc1234
+
+      <!-- base: 0000000 -->
+
+      ## calc
+
+      - [ ] ./src/calc.ts#1-1
+        new add function
+      """
+    And a file ".gtd/REVIEW.md" with:
+      """
+      # Review: abc1234
+
+      <!-- base: 0000000 -->
+
+      ## calc
+
+      - [ ] ./src/calc.ts#1-1
+        new add function — rename it to sum
+      """
+    And the working tree is committed as "chore: hand off a review"
+    And step "notes.fixing" writes "src/calc.ts" with:
+      """
+      export const sum = (a: number, b: number) => a + b
+      """
+    And step "notes.closing" runs its script
+    And step "build.health.check" changes nothing
+    And step "build.quality.correctness.reviewing" writes ".gtd/QUALITY.md" with:
+      """
+      # Quality
+
+      ## sum is untested
+
+      From correctness.
+      """
+    And step "build.quality.tests.reviewing" writes ".gtd/QUALITY.md" with:
+      """
+      # Quality
+
+      ## sum is untested
+
+      From correctness.
+
+      ## sum is untested
+
+      From tests.
+      """
+    And step "build.quality.sorting" runs its script
+    And step "build.quality.closing" runs its script
+    And step "build.review.reviewing" writes ".gtd/REVIEW.md" with:
+      """
+      # Review: abc1234
+
+      <!-- base: 0000000 -->
+
+      ## calc
+
+      - [ ] ./src/calc.ts#1-1
+        renamed to sum
+      """
+    And step "build.review.carrying" runs its script
+
+  Scenario: two lenses' findings with one title each name their own lens
+    Given judge step "build.quality.triage" answers:
+      """
+      [{"id":"Q1","answer":"design","p":0.9},{"id":"Q2","answer":"design","p":0.9}]
+      """
+    When gtd opens door "fix"
+    And the process is driven
+    Then the process rests at "build.review.await-review"
+    And ".gtd/REVIEW.md" contains:
+      """
+      ## sum is untested
+
+      _From lens correctness._
+
+      From correctness.
+
+      ## sum is untested (2)
+
+      _From lens tests._
+
+      From tests.
+      """

package/src/workflows/fix/fix-quality.feature

@@ -0,0 +1,131 @@
+@inmem
+Feature: fix's quality lap is triaged, and its leftovers go to the hand-off review
+
+  A judge sorts the lap's findings: mechanical ones are fixed for up to three
+  turns, noise is dropped, and design ones — with whatever the fix turns left —
+  are added to the reviewer's `.gtd/REVIEW.md` by gtd, never to a person's
+  gate before the review.
+
+  Background:
+    Given the shipped workflows, as gtd install scaffolds them
+    And an environment variable "GTD_QUALITYREVIEWS" set to "correctness"
+    And a file "src/calc.ts" with:
+      """
+      export const add = (a: number, b: number) => a + b
+      """
+    And the working tree is committed as "feat: add calculator"
+    And a file ".gtd/REVIEW.orig.md" with:
+      """
+      # Review: abc1234
+
+      <!-- base: 0000000 -->
+
+      ## calc
+
+      - [ ] ./src/calc.ts#1-1
+        new add function
+      """
+    And a file ".gtd/REVIEW.md" with:
+      """
+      # Review: abc1234
+
+      <!-- base: 0000000 -->
+
+      ## calc
+
+      - [ ] ./src/calc.ts#1-1
+        new add function — rename it to sum
+      """
+    And the working tree is committed as "chore: hand off a review"
+    And step "notes.fixing" writes "src/calc.ts" with:
+      """
+      export const sum = (a: number, b: number) => a + b
+      """
+    And step "notes.closing" runs its script
+    And step "build.health.check" changes nothing
+    And step "build.quality.correctness.reviewing" writes ".gtd/QUALITY.md" with:
+      """
+      # Quality
+
+      ## sum has no negative test
+
+      Add a test summing negative numbers.
+
+      ## sum should be named plus
+
+      The glossary says plus.
+      """
+    And step "build.quality.sorting" runs its script
+    And step "build.quality.closing" runs its script
+    And step "build.review.reviewing" writes ".gtd/REVIEW.md" with:
+      """
+      # Review: abc1234
+
+      <!-- base: 0000000 -->
+
+      ## calc
+
+      - [ ] ./src/calc.ts#1-1
+        renamed to sum
+      """
+    And step "build.review.carrying" runs its script
+
+  Scenario: a design finding and one the fix cap left reach the reviewer, never an escalation
+    Given judge step "build.quality.triage" answers:
+      """
+      [{"id":"Q1","answer":"mechanical","p":0.9},{"id":"Q2","answer":"design","p":0.9}]
+      """
+    And step "build.fix.quality.fixing" changes nothing
+    When gtd opens door "fix"
+    And the process is driven
+    Then the process rests at "build.review.await-review"
+    And ".gtd/QUALITY.md" does not exist
+    And no commit body contains "build.health.describe"
+    And ".gtd/REVIEW.md" contains:
+      """
+      ## sum has no negative test
+
+      _From lens correctness._
+
+      _The fixer left this unresolved._
+      """
+    And ".gtd/REVIEW.md" contains:
+      """
+      ## sum should be named plus
+
+      _From lens correctness._
+
+      The glossary says plus.
+      """
+    And the commit subjects end with:
+      """
+      gtd(agent): build.quality.correctness.reviewing → build.quality.triage
+      gtd(judge): build.quality.triage → build.quality.sorting
+      gtd(check): build.quality.sorting → build.fix.quality.fixing
+      gtd(agent): build.fix.quality.fixing
+      gtd(agent): build.fix.quality.fixing
+      gtd(agent): build.fix.quality.fixing → build.health.check
+      gtd(check): build.health.check → build.quality.closing
+      gtd(check): build.quality.closing → build.review.reviewing
+      gtd(agent): build.review.reviewing → build.review.carrying
+      gtd(check): build.review.carrying → build.review.await-review
+      """
+
+  Scenario: a fixed finding and a noise one are listed in the review
+    Given judge step "build.quality.triage" answers:
+      """
+      [{"id":"Q1","answer":"mechanical","p":0.9},{"id":"Q2","answer":"noise","p":0.9}]
+      """
+    And step "build.fix.quality.fixing" writes "src/calc.test.ts" with:
+      """
+      it("sums negative numbers", () => {})
+      """
+    And step "build.fix.quality.fixing" deletes ".gtd/QUALITY.md"
+    When gtd opens door "fix"
+    And the process is driven
+    Then the process rests at "build.review.await-review"
+    And no commit body contains "build.quality.closing"
+    And ".gtd/REVIEW.md" contains "## Fixed automatically"
+    And ".gtd/REVIEW.md" contains "- sum has no negative test ("
+    And ".gtd/REVIEW.md" contains the short hash of the commit "gtd(agent): build.fix.quality.fixing → build.health.check"
+    And ".gtd/REVIEW.md" contains "- sum should be named plus (p=0.9, lens correctness)"

package/src/workflows/index.ts

@@ -11,7 +11,6 @@ export * from "./shared/steps.js"
 export * from "./shared/health.js"
 export {
   closeReview,
-  fixQualityFindings,
   handOffReview,
   handOffTail,
   qualityLap,

package/src/workflows/shared/lenses.ts

@@ -15,6 +15,7 @@ import {
 import { FIX_CAP, guarded, healthy, type EscalationCount, type Guard } from "./health.js"
 import { fixCheck, fixQuality, QUALITY } from "./steps.js"
 import * as t from "./text.js"
+import type { Origin } from "./text.js"
 
 /** One `## ` section of `.gtd/QUALITY.md`. */
 export interface Finding {
@@ -29,13 +30,30 @@ type FindingKind = "mechanical" | "noise" | "design"
 /** What the triaged quality lap did with its findings, for the review to list. */
 export interface LensReport {
   /** Design findings, then the mechanical ones the fix cap left. */
-  readonly notes: readonly (Finding & { readonly unresolved?: true; readonly unclear?: true })[]
-  readonly fixed: readonly (Finding & { readonly commit: string })[]
-  readonly noise: readonly (Finding & { readonly p: number })[]
+  readonly notes: readonly (Finding &
+    Origin & {
+      readonly unresolved?: true
+      readonly unclear?: true
+    })[]
+  readonly fixed: readonly (Finding & Origin & { readonly commit: string })[]
+  readonly noise: readonly (Finding & Origin & { readonly p: number })[]
 }
 
 export const NO_FINDINGS: LensReport = { notes: [], fixed: [], noise: [] }
 
+/** `reports` as one, each finding labelled with the slice it came from, in slice order. */
+export const joinReports = (
+  reports: readonly { readonly slice: string; readonly report: LensReport }[],
+): LensReport => {
+  const tag = <F extends Origin>(slice: string, fs: readonly F[]): F[] =>
+    fs.map((f) => ({ ...f, slice }))
+  return {
+    notes: reports.flatMap((r) => tag(r.slice, r.report.notes)),
+    fixed: reports.flatMap((r) => tag(r.slice, r.report.fixed)),
+    noise: reports.flatMap((r) => tag(r.slice, r.report.noise)),
+  }
+}
+
 const UNTITLED = "Quality findings"
 
 const below = (section: string): string => section.split("\n").slice(1).join("\n").trim()
@@ -129,6 +147,8 @@ export interface TriageOptions {
   readonly guard?: Guard | undefined
   readonly guardRests?: boolean | undefined
   readonly rules?: string | undefined
+  /** The lens that wrote a finding, when known; asked once per finding, in file order. */
+  readonly lensOf?: ((f: Finding) => string | undefined) | undefined
 }
 
 /**
@@ -139,7 +159,11 @@ export interface TriageOptions {
  */
 export const triageFindings = async (options: TriageOptions): Promise<LensReport> => {
   const { escalations, guard, guardRests, rules } = options
-  const findings = findingsOf(read(QUALITY) ?? "")
+  const withLens = (f: Finding): Finding & Origin => {
+    const lens = options.lensOf?.(f)
+    return lens === undefined ? f : { ...f, lens }
+  }
+  const findings = findingsOf(read(QUALITY) ?? "").map(withLens)
   if (findings.length === 0) return NO_FINDINGS
   const { mechanical, noise, design } = await classify(findings)
   // Rewritten whenever it is not one chunk per mechanical finding: the fixer deletes chunks.
@@ -160,7 +184,8 @@ export const triageFindings = async (options: TriageOptions): Promise<LensReport
     const commit = head()
     fixed.push(...turn.fixed.map((f) => ({ ...f, commit })))
     unclear.push(...turn.unclear)
-    open = turn.open
+    // A turn that renamed a chunk hands back fresh parses: keep the lens a same-titled finding had.
+    open = turn.open.map((f) => ({ ...mechanical.find((m) => m.title === f.title), ...f }))
   }
   if (mechanical.length > 0)
     await healthy(() => fixCheck(rules), { escalations, guard, guardRests, rules })

package/src/workflows/shared/review.ts

@@ -26,7 +26,6 @@ import {
   fixCheck,
   fixNits,
   fixRisks,
-  QUALITY,
   REQUIREMENTS,
   REVIEW,
   reviewMissing,
@@ -173,7 +172,7 @@ export const isCode = (path: string): boolean => path !== ".gtd" && !path.starts
 
 /**
  * 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
+ * turn. A re-review
  * after fixed nits restores the doc as committed at `carry`, answers kept;
  * a fresh one leaves out the notes the human already answered.
  */
@@ -199,7 +198,6 @@ const composing = (
               undecided: parseStandards(read(STANDARDS) ?? "").undecided,
             },
           }),
-          [QUALITY],
         )
       : showScript(carry, REVIEW, REVIEW),
     { label: "Composing the review", file: REVIEW, base },
@@ -305,7 +303,7 @@ export interface BuildTailOptions extends TailOptions {
   readonly report?: LensReport | undefined
 }
 
-/** The build tail: fix (when entered red), keep green unless `green`, the triaged quality lap, then human review since `base`. */
+/** The build tail: fix (when entered red), keep green unless `green`, the 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(
@@ -329,10 +327,7 @@ export function buildTail(
     )
   }
   const [base, form] = options
-  return tail((escalations, report) => humanReview(base, escalations, { ...form, report }), {
-    ...form,
-    triage: true,
-  })
+  return tail((escalations, report) => humanReview(base, escalations, { ...form, report }), form)
 }
 
 const isOptionalBoolean = (value: unknown): value is boolean | null | undefined =>

package/src/workflows/shared/tail.ts

@@ -1,17 +1,18 @@
-import { read, refuse, removeScript, run, scope, showScript, vars } from "../../flows/index.js"
-import * as kit from "../../workflow-kit/index.js"
 import {
-  escalation,
-  FIX_CAP,
-  guarded,
-  healthy,
-  type EscalationCount,
-  type Guard,
-} from "./health.js"
+  read,
+  refuse,
+  removeScript,
+  run,
+  scope,
+  showScript,
+  vars,
+  writeScript,
+} from "../../flows/index.js"
+import * as kit from "../../workflow-kit/index.js"
+import { guarded, healthy, type EscalationCount, type Guard } from "./health.js"
 import {
   awaitReview,
   fixCheck,
-  fixQuality,
   fixRisks,
   QUALITY,
   REVIEW,
@@ -19,7 +20,7 @@ import {
   reviewMissing,
   reviewQuality,
 } from "./steps.js"
-import { NO_FINDINGS, triageFindings, type LensReport } from "./lenses.js"
+import { findingsOf, NO_FINDINGS, triageFindings, type Finding, type LensReport } from "./lenses.js"
 import * as t from "./text.js"
 
 /** The reviewer's own `.gtd/REVIEW.md`, kept beside the human's notes so `fix` can tell them apart. */
@@ -34,29 +35,30 @@ export const qualityLap = (
   guard?: Guard,
   lenses?: readonly string[],
   base?: string,
+): Promise<"clean" | "findings"> => lensLap(guard, lenses, base, () => {})
+
+// `seen` gets each lens and every finding in the file once its turn is done.
+const lensLap = (
+  guard: Guard | undefined,
+  lenses: readonly string[] | undefined,
+  base: string | undefined,
+  seen: (lens: string, findings: readonly Finding[]) => void,
 ): Promise<"clean" | "findings"> =>
   kit.qualityLap(
     lenses ?? kit.lensEntriesOf(vars.qualityReviews ?? ""),
-    guarded((entry: string) => {
+    guarded(async (entry: string) => {
       const { lens, model } = kit.lensOf(entry)
-      return reviewQuality(lens, base, model)
+      await reviewQuality(lens, base, model)
+      seen(lens, findingsOf(read(QUALITY) ?? ""))
     }, guard),
     QUALITY,
   )
 
-/** Resolves `true` once `.gtd/QUALITY.md` is resolved, `false` when the fix cap escalated instead. */
-export const fixQualityFindings = (
-  escalations: EscalationCount,
-  guard?: Guard,
-  guardRests = true,
-  rules?: string,
-): Promise<boolean> =>
-  kit.fixFindings({
-    fix: guarded(() => fixQuality(rules), guard),
-    findings: QUALITY,
-    cap: FIX_CAP,
-    escalate: () => escalation(escalations, guard, guardRests, rules),
-  })
+// What the fixer left is in the lap's report by now; the next lap must not append to it.
+const closeQuality = async (): Promise<void> => {
+  if (read(QUALITY) === undefined) return
+  await run("quality.closing", removeScript([QUALITY]), { label: "Clearing quality findings" })
+}
 
 /** `.gtd/REVIEW.md` removed at the end of a round at commit `round`. */
 export const closeReview = (round: string): Promise<void> =>
@@ -89,17 +91,12 @@ export interface TailOptions {
   readonly lensBase?: string | undefined
   /** Appended to every fix and describe prompt of the tail. */
   readonly rules?: string | undefined
-  /**
-   * Judge the lap's findings: fix the mechanical ones, drop noise, and hand
-   * `finish` the rest as notes for the human review; default `false`. `finish`
-   * must remove `.gtd/QUALITY.md`, which still holds what the fixer left.
-   */
-  readonly triage?: boolean | undefined
 }
 
 /**
- * The build tail: fix (when entered red), keep green, the quality lap, then
- * `finish` — whatever the calling workflow runs last, a human review or nothing.
+ * The build tail: fix (when entered red), keep green, the quality lap — a
+ * judge sorts its findings, the mechanical ones are fixed, noise dropped —
+ * then `finish` with the rest as notes: a human review, or carrying them on.
  */
 export function tail<T>(
   finish: (escalations: EscalationCount, report: LensReport) => Promise<T>,
@@ -108,7 +105,7 @@ export function tail<T>(
 /** @deprecated Pass `tail(finish, { fixFirst, green, guard, lenses, guardRests, lensBase, rules })`. */
 export function tail<T>(
   fixFirst: boolean,
-  finish: (escalations: EscalationCount) => Promise<T>,
+  finish: (escalations: EscalationCount, report: LensReport) => Promise<T>,
   green?: boolean,
   guard?: Guard,
   lenses?: readonly string[],
@@ -164,29 +161,34 @@ const runTail = <T>(finish: Finish<T>, options: TailOptions): Promise<T> =>
     const guardRests = options.guardRests === undefined ? true : options.guardRests
     const escalations: EscalationCount = { rounds: 0 }
     const fix = () => fixCheck(rules)
-    const repair = async () => {
-      await guarded(fix, guard)()
-      await healthy(fix, { fixesSoFar: 1, escalations, guard, guardRests, rules })
-    }
     // fixFirst's own fix + healthy below already is the full run.
     // Truthy, not `true`: an untyped config's flags read as they always did.
-    if (options.fixFirst) await repair()
-    else if (!options.green) await healthy(fix, { escalations, guard, guardRests, rules })
+    if (options.fixFirst) {
+      await guarded(fix, guard)()
+      await healthy(fix, { fixesSoFar: 1, escalations, guard, guardRests, rules })
+    } else if (!options.green) await healthy(fix, { escalations, guard, guardRests, rules })
     // The lap runs once a tail: after its findings are fixed, `finish` follows.
-    const lap = await qualityLap(guard, lenses, lensBase)
-    if (options.triage) {
-      const report =
-        lap === "findings"
-          ? await triageFindings({ escalations, guard, guardRests, rules })
-          : NO_FINDINGS
-      return finish(escalations, report)
-    }
-    if (lap === "findings") {
-      if (await fixQualityFindings(escalations, guard, guardRests, rules)) {
-        await healthy(fix, { escalations, guard, guardRests, rules })
-      } else await repair()
+    // Lenses append, so a title the file did not hold before a lens's turn is that lens's.
+    const byTitle: { title: string; lens: string }[] = []
+    const lap = await lensLap(guard, lenses, lensBase, (lens, findings) => {
+      const before = byTitle.map((f) => f.title)
+      for (const { title } of findings) {
+        const at = before.indexOf(title)
+        if (at >= 0) before.splice(at, 1)
+        else byTitle.push({ title, lens })
+      }
+    })
+    // Asked once per finding in file order, so a title two lenses wrote goes to each in turn.
+    const lensOf = (f: Finding): string | undefined => {
+      const at = byTitle.findIndex((e) => e.title === f.title)
+      return at < 0 ? undefined : byTitle.splice(at, 1)[0]!.lens
     }
-    return finish(escalations, NO_FINDINGS)
+    const report =
+      lap === "findings"
+        ? await triageFindings({ escalations, guard, guardRests, rules, lensOf })
+        : NO_FINDINGS
+    await closeQuality()
+    return finish(escalations, report)
   })
 
 /**
@@ -198,10 +200,22 @@ export const handOffReview = (
   base: string,
   escalations: EscalationCount,
   guard?: Guard,
+  report: LensReport = NO_FINDINGS,
 ): Promise<void> =>
   kit.reviewToHandOff(base, {
     file: REVIEW,
-    reviewing: guarded((b, carry) => reviewing(b, carry), guard),
+    reviewing: guarded(async (b, carry) => {
+      await reviewing(b, carry)
+      // gtd adds the lap's chunks itself: .gtd/QUALITY.md is gone, so a reviewer leaving one out would lose it.
+      const review = read(REVIEW)
+      if (review === undefined) return
+      const full = t.withLapFindings(review, report)
+      if (full !== review) {
+        await run("review.carrying", writeScript(REVIEW, full), {
+          label: "Adding the quality lap's findings",
+        })
+      }
+    }, guard),
     fixRisks: guarded(fixRisks, guard),
     keepGreen: () => healthy(fixCheck, { escalations, guard }),
     awaitReview: (b) => awaitReview(b, t.handOffAwaitReviewMessage(b)),
@@ -220,6 +234,9 @@ export const handOffReview = (
       "gtd land: review-doc: .gtd/REVIEW.md was deleted — restore it, or leave a note to hand to fix.",
   })
 
-/** The tail the fix workflow runs: ends at the hand-off review since `base`. */
+/** The tail the fix workflow runs: ends at the hand-off review since `base`, which gets what the lap left. */
 export const handOffTail = (fixFirst: boolean, base: string, guard?: Guard): Promise<void> =>
-  tail((escalations) => handOffReview(base, escalations, guard), { fixFirst, guard })
+  tail((escalations, report) => handOffReview(base, escalations, guard, report), {
+    fixFirst,
+    guard,
+  })