@pmelab/gtd 46.0.0 → 47.0.0

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,
+  })

package/src/workflows/shared/text.ts

@@ -117,16 +117,22 @@ export const qualityFindingsFile = (
 ): string =>
   `# Quality\n\n${findings.map((f) => `## ${f.title}\n\n${f.body}`.trim()).join("\n\n")}\n`
 
+/** Where a reported finding came from; absent when unknown or, for `slice`, a single-slice build. */
+export interface Origin {
+  readonly lens?: string | undefined
+  readonly slice?: string | undefined
+}
+
 export interface ComposedReview {
-  readonly notes: readonly {
+  readonly notes: readonly (Origin & {
     readonly title: string
     readonly body: string
     readonly unresolved?: true
     /** A fix turn removed its chunk while renaming another. */
     readonly unclear?: true
-  }[]
-  readonly fixed: readonly { readonly title: string; readonly commit: string }[]
-  readonly noise: readonly { readonly title: string; readonly p: number }[]
+  })[]
+  readonly fixed: readonly (Origin & { readonly title: string; readonly commit: string })[]
+  readonly noise: readonly (Origin & { readonly title: string; readonly p: number })[]
   /** `Then` lines a `.feature` file at the review base no longer carries. */
   readonly weakened?: readonly RemovedAssertions[]
   /** The commit that fixed the human's nits, on the review that follows it. */
@@ -154,6 +160,34 @@ const unboxed = (body: string): string =>
 
 const short = (hash: string): string => hash.slice(0, 7)
 
+/** `slice 2, lens tests`; empty when neither is known. */
+const originOf = (f: Origin): string =>
+  [
+    ...(f.slice === undefined ? [] : [`slice ${f.slice}`]),
+    ...(f.lens === undefined ? [] : [`lens ${f.lens}`]),
+  ].join(", ")
+
+const originLine = (f: Origin): string => {
+  const origin = originOf(f)
+  return origin === "" ? "" : `_From ${origin}._\n\n`
+}
+
+const withOrigin = (f: Origin, rest: string): string =>
+  [rest, originOf(f)].filter((s) => s !== "").join(", ")
+
+type LapNote = ComposedReview["notes"][number]
+
+const noteBody = (n: LapNote): string => {
+  const body = unboxed(n.body) || "_No detail given._"
+  if (n.unresolved === true) return `_The fixer left this unresolved._\n\n${body}`
+  if (n.unclear === true)
+    return `_A fix turn removed this while renaming another finding — check whether it was fixed._\n\n${body}`
+  return body
+}
+
+// A one-slice review needs no provenance: only carried findings name their slice and lens.
+const carriedOnly = (f: Origin): Origin => (f.slice === undefined ? {} : f)
+
 /**
  * \`.gtd/REVIEW.md\` as gtd writes it: one chunk per note, each ending in its
  * answer boxes, then the fixed and noise lists. Chunk titles are made unique —
@@ -200,23 +234,14 @@ export const composedReview = (base: string, report: ComposedReview): string =>
         ]),
     ...conflicts,
     ...notes.map((n) =>
-      chunk(
-        n.title,
-        `${
-          n.unresolved === true
-            ? `_The fixer left this unresolved._\n\n${unboxed(n.body)}`
-            : n.unclear === true
-              ? `_A fix turn removed this while renaming another finding — check whether it was fixed._\n\n${unboxed(n.body)}`
-              : unboxed(n.body) || "_No detail given._"
-        }\n\n${answerBoxes}`,
-      ),
+      chunk(n.title, `${originLine(carriedOnly(n))}${noteBody(n)}\n\n${answerBoxes}`),
     ),
     ...(report.fixed.length === 0
       ? []
       : [
           chunk(
             "Fixed automatically",
-            report.fixed.map((f) => `- ${f.title} (${short(f.commit)})`).join("\n"),
+            report.fixed.map((f) => fixedLine(f, carriedOnly(f))).join("\n"),
           ),
         ]),
     ...(added.length === 0
@@ -229,7 +254,12 @@ export const composedReview = (base: string, report: ComposedReview): string =>
         ]),
     ...(report.noise.length === 0
       ? []
-      : [chunk("Dropped as noise", report.noise.map((f) => `- ${f.title} (p=${f.p})`).join("\n"))]),
+      : [
+          chunk(
+            "Dropped as noise",
+            report.noise.map((f) => noiseLine(f, carriedOnly(f))).join("\n"),
+          ),
+        ]),
   ]
   const body =
     chunks.length > 0
@@ -243,19 +273,6 @@ export const composedReview = (base: string, report: ComposedReview): string =>
   return `# Review: ${short(base)}\n\n<!-- base: ${base} -->\n\n${body.join("\n\n")}\n`
 }
 
-export const qualityUnresolvedMessage = (): string =>
-  `The quality lap's fix turns hit their cap and \`.gtd/QUALITY.md\` still
-holds findings. Nothing after this fixes them, so the process will not
-go on with them open.
-
-Fix what matters by hand, then delete or empty \`.gtd/QUALITY.md\` —
-dropping a finding is your call to make.
-
-What each change does next (then run \`gtd land\`):
-- **Delete or empty \`.gtd/QUALITY.md\`** — the suite runs on your edits, then the next slice is built, or after the last one you review the change (**build.review.reviewing**).
-- **Anything else** — rests here again.
-`
-
 export const startGateBlockedMessage = (): string =>
   `The test baseline is red — gtd will not start new work on a broken suite.
 \`.gtd/FEEDBACK.md\` holds the failing output.
@@ -1125,6 +1142,45 @@ const lapRange: Record<ReviewRange, string> = {
     "it covers the whole refactor since it started, on every round. A refactor may update an existing test's call sites only: give any test-file hunk its own chunk, and say so if it changes a test, an assertion or an expected value.",
 }
 
+/** What the quality lap left for a reviewer-written review: its notes, fixes and noise. */
+export type LapFindings = Pick<ComposedReview, "notes" | "fixed" | "noise">
+
+const fixedLine = (f: ComposedReview["fixed"][number], origin: Origin = f): string =>
+  `- ${f.title} (${withOrigin(origin, short(f.commit))})`
+
+const noiseLine = (f: ComposedReview["noise"][number], origin: Origin = f): string =>
+  `- ${f.title} (${withOrigin(origin, `p=${f.p}`)})`
+
+/**
+ * `review` with the lap's notes appended as prose chunks — no pointer, no
+ * answer boxes — then what it fixed and dropped. A title the review already
+ * holds gets a numbered suffix, as notes are told apart by title.
+ */
+export const withLapFindings = (review: string, { notes, fixed, noise }: LapFindings): string => {
+  const used = new Set(
+    review
+      .split("\n")
+      .filter((line) => line.startsWith("## "))
+      .map((line) => line.slice(3).trim()),
+  )
+  const unique = (title: string): string => {
+    let name = title
+    for (let n = 2; used.has(name); n++) name = `${title} (${n})`
+    used.add(name)
+    return name
+  }
+  const chunks = [
+    ...notes.map((n) => `## ${unique(n.title)}\n\n${originLine(n)}${noteBody(n)}`),
+    ...(fixed.length === 0
+      ? []
+      : [`## ${unique("Fixed automatically")}\n\n${fixed.map((f) => fixedLine(f)).join("\n")}`]),
+    ...(noise.length === 0
+      ? []
+      : [`## ${unique("Dropped as noise")}\n\n${noise.map((f) => noiseLine(f)).join("\n")}`]),
+  ]
+  return chunks.length === 0 ? review : `${review.trimEnd()}\n\n${chunks.join("\n\n")}\n`
+}
+
 export const buildReviewReviewingPrompt = (
   base: string,
   lap: ReviewRange,

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

@@ -1,121 +0,0 @@
-@inmem
-Feature: quality findings left unresolved between slices hold the next slice back
-
-  Between slices no review reads the quality lap's leftovers, so when the fix
-  cap leaves `.gtd/QUALITY.md` behind the process rests for a person before
-  the next slice. The last slice's leftovers become review notes instead (see
-  `lens-review.feature`).
-
-  Background:
-    Given the shipped workflows, as gtd install scaffolds them
-    And an environment variable "GTD_QUALITYREVIEWS" set to "correctness"
-    And an environment variable "GTD_FLAGMODE" set to "false"
-    And an environment variable "GTD_SLICEMAXCRITERIA" set to "1"
-    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 "TODO.md" with:
-      """
-      # More arithmetic
-
-      subtract and multiply.
-      """
-    And step "unwind" changes nothing
-    And step "start-gate.check" changes nothing
-    And step "design.triage" writes ".gtd/REQUIREMENTS.md" with:
-      """
-      # Requirements
-
-      ## Acceptance Criteria
-
-      - AC-1: subtract(a, b) returns a - b.
-      - AC-2: multiply(a, b) returns a * b.
-      """
-    And step "design.gate.answer" changes nothing
-    And step "design.slicing" writes ".gtd/SLICES.md" with:
-      """
-      # Slices
-
-      ## Subtract
-
-      - AC-1
-
-      ## Multiply
-
-      - AC-2
-      """
-    And step "seam.naive", when prompted with "This slice builds AC-1 only", writes "src/sub.test.ts" with:
-      """
-      it("[AC-1] subtracts", () => {})
-      """
-    And step "seam.naive", when prompted with "This slice builds AC-2 only", writes "src/mul.test.ts" with:
-      """
-      it("[AC-2] multiplies", () => {})
-      """
-    And step "seam.check" changes nothing
-    And step "implement.applying" runs its script
-    And step "implement.health.check" changes nothing
-    And step "implement.closing" runs its script
-    And judge step "implement.coverage", when its questions contain "AC-1", answers:
-      """
-      [{"id":"AC-1","answer":"yes","p":0.9}]
-      """
-    And judge step "implement.coverage", when its questions contain "AC-2", answers:
-      """
-      [{"id":"AC-2","answer":"yes","p":0.9}]
-      """
-
-  Scenario: findings the fix cap left after a slice rest at build.quality-unresolved
-    Given step "build.quality.correctness.reviewing" writes ".gtd/QUALITY.md" with:
-      """
-      # Quality
-
-      ## subtract has no negative test
-
-      Add a test subtracting a larger number.
-      """
-    And step "build.fix.quality.fixing" from now on changes nothing
-    And step "build.health.describe" writes ".gtd/ESCALATION.md" with:
-      """
-      # Escalation
-
-      The fix turn changed nothing.
-      """
-    When the process is driven
-    Then the process rests at "build.health.stop"
-    Given step "build.fix" writes "src/calc.ts" with:
-      """
-      export const add = (a: number, b: number) => a + b
-      // checked
-      """
-    And step "build.health.check" changes nothing
-    When gtd lands
-    And the process is driven
-    Then the process rests at "build.quality-unresolved"
-    And ".gtd/QUALITY.md" contains "subtract has no negative test"
-
-    When gtd lands
-    And the process is driven
-    Then the process rests at "build.quality-unresolved"
-
-    Given the file ".gtd/QUALITY.md" is deleted
-    And step "build.quality.correctness.reviewing" from now on changes nothing
-    And step "build.review.composing" runs its script
-    When gtd lands
-    And the process is driven
-    Then the process rests at "build.review.await-review"
-    And the commit subjects end with:
-      """
-      gtd(human): build.quality-unresolved → build.health.check
-      gtd(check): build.health.check → seam.naive
-      gtd(agent): seam.naive → seam.check
-      gtd(check): seam.check → implement.applying
-      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.quality.correctness.reviewing
-      gtd(agent): build.quality.correctness.reviewing → build.review.composing
-      gtd(check): build.review.composing → build.review.await-review
-      """