@pmelab/gtd 55.0.0 → 56.0.0

package/src/workflows/review/review-door.feature

@@ -2,9 +2,10 @@
 Feature: the review door fixes its notes in the same process
 
   `gtd door review` runs the feature's review over everything since its base:
-  the triaged quality lap writes `.gtd/REVIEW.md`, the human answers each note,
-  and what they ask for is fixed in place under the health loop before the
-  review comes back. A sign-off ends the process; nothing is left for `fix`.
+  the triaged quality lap and its finding gate, then a reviewer's walkthrough
+  of the change with the lap's summary, where the human's notes are fixed in
+  place under the health loop before the review comes back. A sign-off ends
+  the process; nothing is left for `fix`.
 
   Background:
     Given the shipped workflows, as gtd install scaffolds them
@@ -24,15 +25,27 @@ Feature: the review door fixes its notes in the same process
 
       Add a test for add.
       """
-    And step "build.quality.sorting" runs its script
     And judge step "build.quality.triage" answers:
       """
       [{"id":"Q1","answer":"design","p":0.9}]
       """
-    And step "build.review.composing" runs its script
+    And step "build.quality.gating" runs its script
+    And step "build.quality.gate" changes nothing
+    And step "build.quality.closing" runs its script
+    And step "build.review.reviewing" writes ".gtd/REVIEW.md" with:
+      """
+      # Review: abc1234
+
+      <!-- base: 0000000 -->
+
+      ## Calculator
+
+      - [ ] ./src/calc.ts#1-1 — add(a, b)
+      """
+    And step "build.review.carrying" runs its script
     And step "build.review.closing" runs its script
 
-  Scenario: the review is composed from the lap's notes, with answer boxes
+  Scenario: the review is a walkthrough, its summary listing what the finding gate dropped
     When gtd opens door "review" with "HEAD~1"
     And the process is driven
     Then the process rests at "build.review.await-review"
@@ -41,72 +54,65 @@ Feature: the review door fixes its notes in the same process
       gtd(human): review-gate.check
       gtd(check): review-gate.check → build.quality.correctness.reviewing
       gtd(agent): build.quality.correctness.reviewing → build.quality.triage
-      gtd(judge): build.quality.triage → build.quality.sorting
-      gtd(check): build.quality.sorting → build.review.composing
-      gtd(check): build.review.composing → build.review.await-review
+      gtd(judge): build.quality.triage → build.quality.gating
+      gtd(check): build.quality.gating → build.quality.gate
+      gtd(human): build.quality.gate → 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
       """
     And ".gtd/REVIEW.md" contains:
       """
-      ## add has no test
-
-      Add a test for add.
+      ## Calculator
 
-      Tick exactly one:
+      - [ ] ./src/calc.ts#1-1 — add(a, b)
 
-      - [ ] fix as suggested
-      - [ ] won't fix
-      - [ ] _your answer_
+      ## Quality lap
       """
-
-  Scenario: a won't-fix signs off, and no review is left for fix
-    Given judge step "build.review.standards.judge" answers:
+    And ".gtd/REVIEW.md" contains:
       """
-      [{"id":"standard-1","answer":"no","p":0.9}]
+      Dropped at the finding gate:
+
+      - add has no test (lens correctness)
       """
-    When gtd opens door "review" with "HEAD~1"
-    And the process is driven
-    And the text "- [ ] won't fix" in ".gtd/REVIEW.md" is replaced with "- [x] won't fix"
-    And gtd lands
+    And ".gtd/REVIEW.md" does not contain "Tick exactly one:"
+    When gtd lands
     And the process is driven
     Then the process rests at "idle"
     And ".gtd/REVIEW.md" does not exist
     And ".gtd/REVIEW.orig.md" does not exist
 
-  Scenario: a note ticked fix as suggested is fixed in place, then reviewed again
-    Given step "build.review.fix.nits.fixing" writes "src/calc.test.ts" with:
+  Scenario: a nit note is fixed in place, then reviewed again
+    Given judge step "build.review.triage" answers:
+      """
+      [{"id":"note-1","answer":"nit","p":0.9}]
+      """
+    And step "build.review.fix.nits.fixing" writes "src/calc.test.ts" with:
       """
       it("adds", () => {})
       """
     When gtd opens door "review" with "HEAD~1"
     And the process is driven
-    And the text "- [ ] fix as suggested" in ".gtd/REVIEW.md" is replaced with "- [x] fix as suggested"
+    And the text "— add(a, b)" in ".gtd/REVIEW.md" is replaced with "— add(a, b) — add a test for it"
     And 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.review.await-review → build.review.fix.nits.fixing
+      gtd(human): build.review.await-review → build.review.triage
+      gtd(judge): build.review.triage → build.review.fix.nits.fixing
       gtd(agent): build.review.fix.nits.fixing → build.health.check
       gtd(check): build.health.check → build.review.closing
-      gtd(check): build.review.closing → build.review.composing
-      gtd(check): build.review.composing → build.review.await-review
+      gtd(check): build.review.closing → build.review.reviewing
+      gtd(agent): build.review.reviewing → build.review.carrying
+      gtd(check): build.review.carrying → build.review.await-review
       """
-    And ".gtd/REVIEW.md" contains "## Fixed from your notes"
     And "src/calc.test.ts" contains "adds"
-    When gtd lands
-    And the process is driven
-    Then the process rests at "idle"
-    And ".gtd/REVIEW.md" does not exist
-    And ".gtd/REVIEW.orig.md" does not exist
 
-  Scenario: an own answer asking for a change is fixed in place, then reviewed again
-    Given judge step "build.review.standards.judge" answers:
-      """
-      [{"id":"standard-1","answer":"no","p":0.9}]
-      """
-    And judge step "build.review.triage" answers:
+  Scenario: a note asking for a change is fixed in place, then reviewed again
+    Given judge step "build.review.triage" answers:
       """
-      [{"id":"answer-1","answer":"edit","p":0.9}]
+      [{"id":"note-1","answer":"edit","p":0.9}]
       """
     And step "build.review.collecting" writes ".gtd/REQUIREMENTS.md" with:
       """
@@ -125,14 +131,13 @@ Feature: the review door fixes its notes in the same process
     And step "feedback.closing" runs its script
     When gtd opens door "review" with "HEAD~1"
     And the process is driven
-    And the text "- [ ] _your answer_" in ".gtd/REVIEW.md" is replaced with "- [x] test negatives too"
+    And the text "— add(a, b)" in ".gtd/REVIEW.md" is replaced with "— add(a, b) — test negatives too"
     And 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.review.await-review → build.review.standards.judge
-      gtd(judge): build.review.standards.judge → build.review.triage
+      gtd(human): build.review.await-review → build.review.triage
       gtd(judge): build.review.triage → build.review.closing
       gtd(check): build.review.closing → build.review.collecting
       gtd(agent): build.review.collecting → re-unwind
@@ -141,9 +146,12 @@ Feature: the review door fixes its notes in the same process
       gtd(check): feedback.closing → build.health.check
       gtd(check): build.health.check → build.quality.correctness.reviewing
       gtd(agent): build.quality.correctness.reviewing → build.quality.triage
-      gtd(judge): build.quality.triage → build.quality.sorting
-      gtd(check): build.quality.sorting → build.review.composing
-      gtd(check): build.review.composing → build.review.await-review
+      gtd(judge): build.quality.triage → build.quality.gating
+      gtd(check): build.quality.gating → build.quality.gate
+      gtd(human): build.quality.gate → 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
       """
     And ".gtd/REQUIREMENTS.md" does not exist
     And "src/calc.test.ts" contains "adds negatives"
@@ -158,17 +166,12 @@ Feature: the review door fixes its notes in the same process
     Then opening door "review" is refused with ".gtd/REQUIREMENTS.md is left over"
 
   Scenario: a note added with its own boxes is fixed as ticked, never judged
-    Given judge step "build.review.standards.judge" answers:
-      """
-      [{"id":"standard-1","answer":"no","p":0.9}]
-      """
-    And step "build.review.fix.nits.fixing" writes "src/calc.ts" with:
+    Given step "build.review.fix.nits.fixing" writes "src/calc.ts" with:
       """
       export const add = (a: number, b: number): number => a + b
       """
     When gtd opens door "review" with "HEAD~1"
     And the process is driven
-    And the text "- [ ] won't fix" in ".gtd/REVIEW.md" is replaced with "- [x] won't fix"
     And ".gtd/REVIEW.md" gets appended:
       """
       ## src/calc.ts:1 (thread PRRT_1)
@@ -186,11 +189,11 @@ Feature: the review door fixes its notes in the same process
     Then the process rests at "build.review.await-review"
     And the commit subjects end with:
       """
-      gtd(human): build.review.await-review → build.review.standards.judge
-      gtd(judge): build.review.standards.judge → build.review.fix.nits.fixing
+      gtd(human): build.review.await-review → build.review.fix.nits.fixing
       gtd(agent): build.review.fix.nits.fixing → build.health.check
       gtd(check): build.health.check → build.review.closing
-      gtd(check): build.review.closing → build.review.composing
-      gtd(check): build.review.composing → build.review.await-review
+      gtd(check): build.review.closing → build.review.reviewing
+      gtd(agent): build.review.reviewing → build.review.carrying
+      gtd(check): build.review.carrying → build.review.await-review
       """
     And "src/calc.ts" contains "): number =>"

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

@@ -117,20 +117,6 @@ describe("learnStandards", () => {
 })
 
 describe("learnStandards, from a won't-fix", () => {
-  it("states the finding, not gtd's banner", async () => {
-    state.answers = { "standard-1": yes }
-    await learnStandards([
-      {
-        anchor: "Slow loop",
-        // As the review parser hands it over: paragraphs joined by a space.
-        body: "_The fixer left this unresolved._ The loop is quadratic.",
-        choice: "wontfix",
-        text: "",
-      },
-    ])
-    expect(kept()).toBe(file("- Won't fix: Slow loop — The loop is quadratic."))
-  })
-
   it("replaces an old standard hand-edited in case only", async () => {
     state.files[STANDARDS] = file(
       "- use classes.",

package/src/workflows/shared/learn.ts

@@ -32,13 +32,8 @@ interface Candidate {
 
 const SUMMARY_MAX = 200
 
-// The banners composedReview opens a note with say nothing about the finding; the
-// parsed body has its paragraphs joined, so they are matched by their own text.
-const BANNER =
-  /^_(?:The fixer left this unresolved\.|A fix turn removed this while renaming another finding — check whether it was fixed\.|No detail given\.)_\s*/
-
 const summary = (body: string): string => {
-  const text = oneLine(body).replace(BANNER, "")
+  const text = oneLine(body)
   return text.length > SUMMARY_MAX ? `${text.slice(0, SUMMARY_MAX - 1)}…` : text
 }
 

package/src/workflows/shared/lenses.ts

@@ -1,17 +1,24 @@
 import {
   answered,
   head,
+  human,
   judge,
   mark,
   numeric,
   read,
-  removeScript,
+  refuse,
   run,
   sectionBodies,
   vars,
   writeScript,
   type JudgeQuestion,
 } from "../../flows/index.js"
+import {
+  findingEntries,
+  formatFinding,
+  steeringFormatFor,
+  type FindingEntry,
+} from "../../steering/index.js"
 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"
@@ -27,19 +34,27 @@ export interface Finding {
 
 type FindingKind = "mechanical" | "noise" | "design"
 
-/** What the triaged quality lap did with its findings, for the review to list. */
+/** What the triaged quality lap and its finding gate did with the findings, for the review to list. */
 export interface LensReport {
-  /** Design findings, then the mechanical ones the fix cap left. */
-  readonly notes: readonly (Finding &
-    Origin & {
-      readonly unresolved?: true
-      readonly unclear?: true
-    })[]
+  /** Fixed by the fix turns the judge sent them to, with the fixing commit. */
   readonly fixed: readonly (Finding & Origin & { readonly commit: string })[]
-  readonly noise: readonly (Finding & Origin & { readonly p: number })[]
+  /** Ticked at the finding gate and fixed, with the fixing commit. */
+  readonly gateFixed: readonly (Finding & Origin & { readonly commit: string })[]
+  /** Left unticked at the finding gate. */
+  readonly dropped: readonly (Finding & Origin)[]
+  /** Called noise by the judge and left unticked at the finding gate; `p` absent on one the human added there. */
+  readonly noise: readonly (Finding & Origin & { readonly p?: number })[]
+  /** Ticked at the finding gate, still open after the fix turns. */
+  readonly unresolved: readonly (Finding & Origin & { readonly unclear?: true })[]
 }
 
-export const NO_FINDINGS: LensReport = { notes: [], fixed: [], noise: [] }
+export const NO_FINDINGS: LensReport = {
+  fixed: [],
+  gateFixed: [],
+  dropped: [],
+  noise: [],
+  unresolved: [],
+}
 
 const UNTITLED = "Quality findings"
 
@@ -138,14 +153,117 @@ export interface TriageOptions {
   readonly lensOf?: ((f: Finding) => string | undefined) | undefined
 }
 
+type Note = Finding & Origin & { readonly unresolved?: true; readonly unclear?: true }
+
+interface Fixing {
+  readonly fixed: readonly (Finding & Origin & { readonly commit: string })[]
+  readonly open: readonly (Finding & Origin)[]
+  readonly unclear: readonly (Finding & Origin)[]
+}
+
+const NOTHING_FIXED: Fixing = { fixed: [], open: [], unclear: [] }
+
+/** Up to `FIX_CAP` fix turns over `.gtd/QUALITY.md`, which holds one chunk per finding in `findings`. */
+const fixTurns = async (
+  findings: readonly (Finding & Origin)[],
+  options: TriageOptions,
+): Promise<Fixing> => {
+  const fixed: (Finding & Origin & { commit: string })[] = []
+  const unclear: (Finding & Origin)[] = []
+  let open: readonly (Finding & Origin)[] = findings
+  for (let turns = 0; turns < FIX_CAP && open.length > 0; turns++) {
+    await guarded(() => fixQuality(options.rules), options.guard)()
+    const turn = afterFix(open, findingsOf(read(QUALITY) ?? ""))
+    const commit = head()
+    fixed.push(...turn.fixed.map((f) => ({ ...f, commit })))
+    unclear.push(...turn.unclear)
+    // A turn that renamed a chunk hands back fresh parses: keep the lens a same-titled finding had.
+    open = turn.open.map((f) => ({ ...findings.find((m) => m.title === f.title), ...f }))
+  }
+  const { escalations, guard, guardRests, rules } = options
+  await healthy(() => fixCheck(rules), { escalations, guard, guardRests, rules })
+  return { fixed, open, unclear }
+}
+
+/** Matches each entry the human left to the finding it was written from, by title, first unused first; `left` is what no entry claimed. */
+const matcher = <F extends Finding>(findings: readonly F[]) => {
+  const left = [...findings]
+  const of = (e: FindingEntry): F | undefined => {
+    const at = left.findIndex((f) => f.title === e.title)
+    return at < 0 ? undefined : left.splice(at, 1)[0]
+  }
+  return { of, left }
+}
+
+const gateProblems = (text: string): readonly string[] =>
+  steeringFormatFor("findings")!
+    .validate(text)
+    .map((f) => `  - ${formatFinding(QUALITY, f)}`)
+
 /**
- * Judge each finding in `.gtd/QUALITY.md`, set the noise and design ones
- * aside, and fix the mechanical ones for up to `FIX_CAP` turns. Leaves
- * `.gtd/QUALITY.md` holding only what the fixer left: the caller must remove
- * it, or the next lap appends to stale findings.
+ * The human gate over the open notes and the noise: a ticked finding is
+ * fixed — never re-planned — and the rest dropped. No notes and no noise, no gate.
+ */
+const findingGate = async (
+  notes: readonly Note[],
+  noise: readonly (Finding & Origin & { readonly p: number })[],
+  options: TriageOptions,
+): Promise<Omit<LensReport, "fixed">> => {
+  if (notes.length + noise.length === 0) return NO_FINDINGS
+  const written = t.findingGateFile(notes, noise)
+  await run("quality.gating", writeScript(QUALITY, written), {
+    label: "Listing the findings for you",
+  })
+  await human("quality.gate", {
+    message: t.findingGateMessage(),
+    label: "Deciding on the quality findings",
+    file: QUALITY,
+    mode: "findings",
+    acceptClean: true,
+  })
+  // A deleted file decides nothing: every finding is dropped, as if untouched.
+  const answered = read(QUALITY) ?? written
+  const problems = gateProblems(answered)
+  if (problems.length > 0)
+    refuse(
+      `gtd land: finding-gate: ${problems.length} problem(s) in ${QUALITY} — keep one \`- [ ] fix\` box per finding, ticked to fix it or unticked to drop it, and write guidance only under a ticked one:\n${problems.join("\n")}`,
+    )
+  const noteOf = matcher(notes)
+  const noiseOf = matcher(noise)
+  // An entry the human added is a finding of its own.
+  const decided = findingEntries(answered).map((e) => ({
+    e,
+    finding: (e.noise ? noiseOf.of(e) : noteOf.of(e)) ?? { id: "", title: e.title, body: e.body },
+  }))
+  // The finding as gtd wrote it: a human steers with guidance, not by editing its text.
+  const ticked = decided
+    .filter(({ e }) => e.fix)
+    .map(({ e, finding }) => ({ ...finding, body: t.withGuidance(finding.body, e.guidance) }))
+  let fixing = NOTHING_FIXED
+  if (ticked.length > 0) {
+    await run("quality.picking", writeScript(QUALITY, t.qualityFindingsFile(ticked)), {
+      label: "Keeping the findings you ticked",
+    })
+    fixing = await fixTurns(ticked, options)
+  }
+  const unticked = (noisy: boolean) =>
+    decided.filter(({ e }) => !e.fix && e.noise === noisy).map(({ finding }) => finding)
+  // A finding whose entry the human deleted is dropped too.
+  return {
+    gateFixed: fixing.fixed,
+    dropped: [...unticked(false), ...noteOf.left],
+    noise: [...unticked(true), ...noiseOf.left],
+    unresolved: [...fixing.open, ...fixing.unclear.map((f) => ({ ...f, unclear: true as const }))],
+  }
+}
+
+/**
+ * Judge each finding in `.gtd/QUALITY.md` and fix the mechanical ones for up
+ * to `FIX_CAP` turns; the rest — design, unresolved and noise — go to the
+ * finding gate. Leaves `.gtd/QUALITY.md` holding only what the last fixer
+ * left: the caller must remove it, or the next lap appends to stale findings.
  */
 export const triageFindings = async (options: TriageOptions): Promise<LensReport> => {
-  const { escalations, guard, guardRests, rules } = options
   const withLens = (f: Finding): Finding & Origin => {
     const lens = options.lensOf?.(f)
     return lens === undefined ? f : { ...f, lens }
@@ -153,36 +271,24 @@ export const triageFindings = async (options: TriageOptions): Promise<LensReport
   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.
-  const sorted = t.qualityFindingsFile(mechanical)
-  if (read(QUALITY) !== sorted) {
-    await run(
-      "quality.sorting",
-      mechanical.length === 0 ? removeScript([QUALITY]) : writeScript(QUALITY, sorted),
-      { label: "Setting findings aside for the review" },
-    )
+  let auto = NOTHING_FIXED
+  if (mechanical.length > 0) {
+    // Rewritten whenever it is not one chunk per mechanical finding: the fixer deletes chunks.
+    const sorted = t.qualityFindingsFile(mechanical)
+    if (read(QUALITY) !== sorted)
+      await run("quality.sorting", writeScript(QUALITY, sorted), {
+        label: "Setting findings aside for the finding gate",
+      })
+    auto = await fixTurns(mechanical, options)
   }
-  const fixed: (Finding & { commit: string })[] = []
-  const unclear: Finding[] = []
-  let open: readonly Finding[] = mechanical
-  for (let turns = 0; turns < FIX_CAP && open.length > 0; turns++) {
-    await guarded(() => fixQuality(rules), guard)()
-    const turn = afterFix(open, findingsOf(read(QUALITY) ?? ""))
-    const commit = head()
-    fixed.push(...turn.fixed.map((f) => ({ ...f, commit })))
-    unclear.push(...turn.unclear)
-    // 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 })
-  return {
-    notes: [
+  const gated = await findingGate(
+    [
       ...design,
-      ...open.map((f) => ({ ...f, unresolved: true as const })),
-      ...unclear.map((f) => ({ ...f, unclear: true as const })),
+      ...auto.open.map((f) => ({ ...f, unresolved: true as const })),
+      ...auto.unclear.map((f) => ({ ...f, unclear: true as const })),
     ],
-    fixed,
     noise,
-  }
+    options,
+  )
+  return { ...gated, fixed: auto.fixed }
 }