@pmelab/gtd 42.0.0 → 43.0.0

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

@@ -0,0 +1,179 @@
+@inmem
+Feature: every note in the review is answered with one tick
+
+  Each note gtd writes to `.gtd/REVIEW.md` ends in three boxes — fix as
+  suggested, won't fix, or the human's own answer written over the
+  placeholder. The gate refuses to land until every note holds exactly one
+  tick. A fix goes to the nit batch, a won't-fix is dropped and recorded in
+  the gate's commit, an own answer is judged like any other note. Nothing is
+  deferred to `.gtd/TODO.md`.
+
+  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 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:
+      """
+      # Add subtract
+
+      subtract(a, b) returns the difference.
+      """
+    And step "unwind" changes nothing
+    And step "start-gate.check" changes nothing
+    And step "design.triage" writes ".gtd/REQUIREMENTS.md" with:
+      """
+      # Requirements
+
+      ## Concerns
+
+      ### Subtract
+
+      - `subtract(a, b)` returns `a - b`.
+
+      ## Acceptance Criteria
+
+      - AC-1: subtract(a, b) returns a - b.
+      """
+    And step "design.gate.answer" changes nothing
+    And step "seam.naive" writes "src/calc.test.ts" with:
+      """
+      it("[AC-1] subtracts", () => {})
+      """
+    And step "seam.naive" writes "src/calc.ts" with:
+      """
+      export const add = (a: number, b: number) => a + b
+      export const subtract = (a: number, b: number) => a - b
+      """
+    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" answers:
+      """
+      [{"id":"AC-1","answer":"yes","p":0.9}]
+      """
+    And step "build.quality.correctness.reviewing" writes ".gtd/QUALITY.md" with:
+      """
+      # Quality
+
+      ## subtract has no negative test
+
+      Add a test subtracting a larger number.
+
+      ## add could be a method
+
+      A class would read better.
+
+      ## AC-1 ignores floating point
+
+      Should subtract round? The criterion does not say.
+      """
+    And step "build.quality.sorting" runs its script
+    And step "build.review.composing" runs its script
+    And judge step "build.quality.triage" answers:
+      """
+      [{"id":"Q1","answer":"noise","p":0.9},{"id":"Q2","answer":"noise","p":0.9},{"id":"Q3","answer":"design","p":0.9}]
+      """
+    And step "build.review.closing" runs its script
+
+  Scenario: the note ends in its three answer boxes
+    When the process is driven
+    Then the process rests at "build.review.await-review"
+    And ".gtd/REVIEW.md" contains:
+      """
+      ## AC-1 ignores floating point
+
+      Should subtract round? The criterion does not say.
+
+      Tick exactly one:
+
+      - [ ] fix as suggested
+      - [ ] won't fix
+      - [ ] _your answer_
+      """
+
+  Scenario: a sign-off with the note unanswered is refused
+    When the process is driven
+    Then landing is refused with "answer-completeness: 1 note(s) in .gtd/REVIEW.md not answered"
+    And the process rests at "build.review.await-review"
+
+  Scenario: two ticks on one note are refused
+    When the process is driven
+    And the text "- [ ] fix as suggested" in ".gtd/REVIEW.md" is replaced with "- [x] fix as suggested"
+    And the text "- [ ] won't fix" in ".gtd/REVIEW.md" is replaced with "- [x] won't fix"
+    Then landing is refused with "tick exactly one box per note"
+
+  Scenario: a ticked answer still holding the placeholder is refused
+    When the process is driven
+    And the text "- [ ] _your answer_" in ".gtd/REVIEW.md" is replaced with "- [x] _your answer_"
+    Then landing is refused with "answer-completeness"
+
+  Scenario: won't fix drops the note, records it, and signs off
+    When 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 the process is driven
+    Then the process rests at "idle"
+    And the commit "gtd(human): build.review.await-review → build.review.closing" has a body containing "Gtd-Mark: wontfix=AC-1 ignores floating point"
+    And ".gtd/TODO.md" does not exist
+    And no commit body contains "build.review.triage"
+
+  Scenario: fix as suggested goes to the nit batch unjudged, and the note is not asked again
+    Given step "build.review.fix.nits.fixing" writes "src/calc.ts" with:
+      """
+      export const add = (a: number, b: number) => a + b
+      export const subtract = (a: number, b: number) => Math.round(a - b)
+      """
+    And step "build.review.fix.nits.fixing" is prompted with "Should subtract round?"
+    And step "build.health.check" changes nothing
+    When the process is driven
+    And the text "- [ ] fix as suggested" in ".gtd/REVIEW.md" is replaced with "- [x] fix as suggested"
+    And gtd lands
+    And the process is driven
+    Then the process rests at "build.review.await-review"
+    And no commit body contains "build.review.triage"
+    And ".gtd/REVIEW.md" contains "## Fixed from your notes"
+    And ".gtd/REVIEW.md" does not contain "AC-1 ignores floating point"
+    And ".gtd/TODO.md" does not exist
+    When gtd lands
+    And the process is driven
+    Then the process rests at "idle"
+
+  Scenario: an own answer is judged like a note
+    Given judge step "build.review.triage" answers:
+      """
+      [{"id":"answer-1","answer":"nit","p":0.9}]
+      """
+    And step "build.review.fix.nits.fixing" is prompted with "round half up"
+    And step "build.health.check" changes nothing
+    And step "build.review.fix.nits.fixing" writes "src/calc.ts" with:
+      """
+      export const add = (a: number, b: number) => a + b
+      export const subtract = (a: number, b: number) => Math.round(a - b)
+      """
+    When the process is driven
+    And the text "- [ ] _your answer_" in ".gtd/REVIEW.md" is replaced with "- [x] round half up"
+    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.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
+      """
+    And ".gtd/REVIEW.md" does not contain "AC-1 ignores floating point"
+
+  Scenario: deleting a note's boxes instead of answering is refused
+    When the process is driven
+    And the text "- [ ] fix as suggested" in ".gtd/REVIEW.md" is replaced with ""
+    And the text "Tick exactly one:" in ".gtd/REVIEW.md" is replaced with ""
+    Then landing is refused with "its answer boxes were deleted"

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

@@ -675,7 +675,7 @@ describe("severity routing", () => {
     expect(run.prompts.get("review.collecting")).toContain("(critical: forced by `!`)")
   })
 
-  it("a confident could edit defers and, alone, returns to the review gate", async () => {
+  it("a confident could edit is still re-planned, labelled could", async () => {
     const run = await drive({
       notes: ["add — quote", "sub", "mul"],
       answers: { "note-1": verdict("edit"), ...sev("note-1", could) },
@@ -684,9 +684,10 @@ describe("severity routing", () => {
       "review.composing",
       "review.await-review",
       "review.triage",
-      "review.defer",
-      "review.await-review",
+      "review.closing",
+      "review.collecting",
     ])
+    expect(run.prompts.get("review.collecting")).toContain("(could)")
   })
 
   it("severity answers on a nit leave it a nit", async () => {
@@ -730,68 +731,19 @@ describe("severity routing", () => {
     expect(run.judged).toContain("note-1.security")
   })
 
-  it("the gate after a deferral accepts a clean land and lists the deferred notes", async () => {
-    const run = await drive({
-      notes: ["add — quote", "sub", "mul"],
-      answers: { "note-1": verdict("edit"), ...sev("note-1", could) },
-    })
-    expect(run.gates).toEqual([true, true])
-    expect(run.gateMessages[1]).toContain("NOT acted on")
-    expect(run.gateMessages[1]).toContain("note-1")
-    expect(run.gateMessages[0]).not.toContain("NOT acted on")
-  })
-
   it("the first round's gate accepts a clean land", async () => {
     const run = await drive({ notes: ["add", "sub", "mul"] })
     expect(run.gates.length).toBeGreaterThan(0)
     expect(run.gates.every((g) => g)).toBe(true)
   })
 
-  it("a later gate still accepts a clean land after a deferral round with a nit", async () => {
-    const run = await drive({
-      notes: ["add — quote", "sub — typo", "mul"],
-      answers: {
-        "note-1": verdict("edit"),
-        ...sev("note-1", could),
-        "note-2": verdict("nit"),
-      },
-      reviewDocs: [undefined, doc(["add", "sub"])],
-    })
-    expect(run.log).toContain("review.defer")
-    expect(run.log.at(-1)).toBe("review.await-review")
-    expect(run.gates).toEqual([true, true])
-  })
-
-  it("a question and a could note in one round: the gate's base is the answering commit", async () => {
-    const run = await drive({
-      notes: ["add — why?", "sub — quote", "mul"],
-      answers: {
-        "note-1": verdict("question"),
-        "note-2": verdict("edit"),
-        ...sev("note-2", could),
-      },
-      passSecondGate: true,
-    })
-    expect(run.log).toEqual([
-      "review.composing",
-      "review.await-review",
-      "review.triage",
-      "review.answer-review-questions",
-      "review.defer",
-      "review.await-review",
-    ])
-    // c4 is the answering commit, not the defer commit (c5) or the round (c2)
-    expect(run.since.at(-1)).toBe("c4")
-  })
-
   it("a blank reviewSeverityMinP makes every confident could critical", async () => {
     const run = await drive({
       notes: ["add — quote", "sub", "mul"],
       answers: { "note-1": verdict("edit"), ...sev("note-1", could) },
       vars: { reviewSeverityMinP: "" },
     })
-    expect(run.log).toContain("review.collecting")
-    expect(run.log).not.toContain("review.defer")
+    expect(run.prompts.get("review.collecting")).toContain("(critical: judge unsure)")
   })
 })
 

package/src/workflows/feature/review.ts

@@ -29,7 +29,7 @@ import {
 } from "../shared/steps.js"
 import { closeReview, isOptionalObject, tail, type TailOptions } from "../shared/tail.js"
 import * as t from "../shared/text.js"
-import { answerReviewQuestions, collecting, deferNotes, fixNits } from "./steps.js"
+import { answerReviewQuestions, collecting, fixNits } from "./steps.js"
 
 export type { ReviewOutcome } from "../../workflow-kit/index.js"
 
@@ -46,6 +46,12 @@ const verdictQuestion = (note: ReviewNote): JudgeQuestion => ({
 
 type Tier = "critical" | "should" | "could"
 
+const TIER_ORDER: Readonly<Record<Tier, number>> = { critical: 0, should: 1, could: 2 }
+
+/** Capture order: critical, should, could; within a tier one-way doors, then new concepts. */
+const captureKey = (s: Severity | undefined): number =>
+  s === undefined ? 2 : TIER_ORDER[s.tier] * 3 + s.rank
+
 const SEVERITY_ANSWERS: Readonly<Record<string, readonly string[]>> = {
   security: ["yes", "no"],
   reversibility: ["one-way", "two-way"],
@@ -60,10 +66,7 @@ interface Severity {
   readonly rank: 0 | 1 | 2
 }
 
-/**
- * Deferring is the risky direction: anything unanswered, unrecognised, cut or
- * below `minP` is `critical`, never `could`.
- */
+/** Anything unanswered, unrecognised, cut or below `minP` is `critical`, never `could`. */
 export const severityOf = (note: ReviewNote, judgment: Judgment, minP: number): Severity => {
   const ans = (q: string) => judgment.answers[`${note.id}.${q}`]
   const a = (q: string): string | undefined => ans(q)?.answer
@@ -125,7 +128,7 @@ const severityQuestions = (note: ReviewNote): JudgeQuestion[] => [
  * nothing) plus four severity answers. Dismissing a note is the risky
  * direction, so only a confident non-`edit` verdict on uncut evidence counts;
  * a cut, unanswered or below-floor note is an `edit`. Severity answers on a
- * non-`edit` note are ignored. A confident `could` edit becomes `defer`.
+ * non-`edit` note are ignored; on an `edit` they order the collecting turn.
  */
 const triage =
   (severities: Map<string, Severity>) =>
@@ -155,9 +158,8 @@ const triage =
           ? undefined
           : VERDICTS.find((v) => v !== "edit" && answered(answers[n.id], v, minP))
         if (verdict !== undefined && !truncated.includes(n.id)) return [n.id, verdict]
-        const severity = severityOf(n, judgment, severityMinP)
-        severities.set(n.id, severity)
-        return [n.id, severity.tier === "could" ? "defer" : "edit"]
+        severities.set(n.id, severityOf(n, judgment, severityMinP))
+        return [n.id, "edit"]
       }),
     )
   }
@@ -167,13 +169,15 @@ 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
- * after fixed nits restores the doc as committed at `carry`, answers kept.
+ * after fixed nits restores the doc as committed at `carry`, answers kept;
+ * a fresh one leaves out the notes the human already answered.
  */
 const composing = (
   base: string,
   report: LensReport,
   carry?: string,
   nitFix?: string,
+  answered: ReadonlySet<string> = new Set(),
 ): Promise<void> =>
   run(
     "review.composing",
@@ -184,6 +188,7 @@ const composing = (
             ...report,
             weakened: kit.removedAssertions(changesSince(base)),
             nitFix,
+            answered,
           }),
           [QUALITY],
         )
@@ -193,9 +198,10 @@ const composing = (
 
 /**
  * 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.
+ * answers each one — fix as suggested, won't fix, or their own answer — and
+ * may comment. A fix joins the nit batch, a won't-fix is dropped, and an own
+ * answer or comment 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,
@@ -210,42 +216,26 @@ export const review = (
       "gtd land: no declared pattern matches the pending changes — write .gtd/REQUIREMENTS.md from the feedback, or change nothing when it asks for nothing",
   }
   const severities = new Map<string, Severity>()
-  // 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
+  // Every note the human answered in this review, left out of a fresh one.
+  const answered = new Set<string>()
   return kit.review(base, {
     file: REVIEW,
     feedback: feedback.file,
     isCode,
     reviewing: (b, carry) => {
-      deferred = []
       const fixedAt = nitFix
       nitFix = undefined
-      return composing(b, options.report ?? NO_FINDINGS, carry, fixedAt)
+      return composing(b, options.report ?? NO_FINDINGS, carry, fixedAt, answered)
     },
     fixRisks: guarded((notes) => fixRisks(notes, fixAccess, rules), guard),
     keepGreen: () => healthy(() => fixCheck(rules), { escalations, guard, guardRests, rules }),
-    awaitReview: (b) => {
-      const notes = deferred
-      deferred = []
-      return notes.length > 0
-        ? awaitReview(b, t.buildReviewAwaitAfterDeferMessage(b, notes))
-        : awaitReview(b)
-    },
+    awaitReview: (b) => awaitReview(b),
     reviewMissing,
     collecting: feedback.collecting,
     triage: triage(severities),
-    defer: (notes) => {
-      deferred = notes.map((n) => ({
-        id: n.id,
-        anchor: n.anchor,
-        text: n.text,
-        label: severities.get(n.id)!.reason,
-      }))
-      return deferNotes(deferred, head())
-    },
+    decided: (decisions) => decisions.forEach((d) => answered.add(d.anchor)),
     answerQuestions: answerReviewQuestions,
     fixNits: async (notes) => {
       await guarded((n: typeof notes) => fixNits(n, fixAccess, rules), guard)(notes)
@@ -259,14 +249,13 @@ export const review = (
         t.reviewEditNotesCapture(
           round,
           edits
-            .map((n, i) => ({ n, i, s: severities.get(n.id) }))
-            // critical before should, then one-way doors, then new concepts
-            .sort(
-              (x, y) =>
-                Number(x.s?.tier === "should") - Number(y.s?.tier === "should") ||
-                (x.s?.rank ?? 2) - (y.s?.rank ?? 2) ||
-                x.i - y.i,
-            )
+            .map((n, i) => ({
+              n,
+              i,
+              s: severities.get(n.id),
+              key: captureKey(severities.get(n.id)),
+            }))
+            .sort((x, y) => x.key - y.key || x.i - y.i)
             .map(({ n, s }) => ({
               id: n.id,
               anchor: n.anchor,

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

@@ -111,18 +111,6 @@ describe("the feature workflow's own steps declare skills — a step's rendered
     expect(scopes).toEqual([{ name: "review.fix.nits", access }])
     expect(steps_.map((r) => ("name" in r ? r.name : ""))).toEqual(["fixing"])
   })
-
-  it("deferNotes rests at build.review.defer as a script writing .gtd/TODO.md", async () => {
-    const request = await capture(
-      () =>
-        steps.deferNotes([{ id: "note-1", anchor: "a", text: "x", label: "could" }], "abcdef123"),
-      "build",
-    )
-    if (request.kind !== "run") throw new Error("unreachable")
-    expect(request.name).toBe("review.defer")
-    expect(request.body).toContain("## Deferred review notes (abcdef1)")
-    expect(request.options).toMatchObject({ file: ".gtd/TODO.md" })
-  })
 })
 
 describe("the feature workflow's planning steps run on the planner model", () => {

package/src/workflows/feature/steps.ts

@@ -1,4 +1,4 @@
-import { human, run, scope, type ScopeAccess } from "../../flows/index.js"
+import { human, scope, type ScopeAccess } from "../../flows/index.js"
 import type { CollectRound } from "../../workflow-kit/index.js"
 import * as t from "../shared/text.js"
 import { riskTierOn } from "./tier.js"
@@ -52,8 +52,8 @@ export const fixNits = (
 }
 
 /** Turn the review round `capture` describes into `.gtd/REQUIREMENTS.md`, or change nothing. */
-export const collecting = (capture: string): Promise<void> =>
-  t.agentWithSkills("review.collecting", t.buildReviewCollectingPrompt(capture), {
+export const collecting = (capture: string, round?: CollectRound): Promise<void> =>
+  t.agentWithSkills("review.collecting", t.buildReviewCollectingPrompt(capture, undefined, round), {
     label: "Collecting your feedback",
     file: REQUIREMENTS,
     mode: "qa",
@@ -79,10 +79,3 @@ export const refactorCollecting = (
       allowEmpty: true,
     },
   )
-
-/** `build.review.defer`: append `notes` to `.gtd/TODO.md` as one section; the step's landing is the commit. */
-export const deferNotes = (notes: readonly t.NoteInput[], round: string): Promise<void> =>
-  run("review.defer", t.deferNotesScript(notes, round), {
-    label: "Deferring could-notes to TODO.md",
-    file: ".gtd/TODO.md",
-  })

package/src/workflows/shared/__fixtures__/feature-collecting-prompt.txt

@@ -45,11 +45,12 @@ You are judging and classifying a round of review feedback.
 - This turn writes `.gtd/REQUIREMENTS.md` (the folded concerns) and
   replies inside `.gtd/REVIEW.md` (thread replies only; the file stays
   in the tree) — you classify, you do not build
-- Fold every concluded thread, ticked answer and hand-edit — and each
-  `edit` note the capture lists, no other note — into
-  `.gtd/REQUIREMENTS.md` and delete the folded threads from
-  `.gtd/REVIEW.md`; append one `- A:` reply to each thread
-  whose last entry is a `- H:` question
+- Fold every concluded thread and hand-edit — and each `edit` note
+  the capture lists, no other note — into `.gtd/REQUIREMENTS.md` and
+  delete the folded threads from `.gtd/REVIEW.md`; append one `- A:`
+  reply to each thread whose last entry is a `- H:` question
+- Never fold a note's ticked answer box the capture does not list: gtd
+  routes those itself
 - When the capture names an answering commit, carry each answered
   question into `.gtd/REQUIREMENTS.md`'s `## Answered Questions` as
   `### <the note>` plus its answer — the lap replaces `.gtd/REVIEW.md`

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

@@ -11,7 +11,6 @@ describe("the bundled workflow's access export", () => {
     expect(bundled).toEqual({
       design: { write: [] },
       "build.review": { write: [".gtd/REVIEW.md"] },
-      "build.review.defer": { write: [".gtd/TODO.md"] },
       "build.review.fix.nits": {},
       "build.review.fix.risks": {},
       "build.quality.correctness": { write: [] },
@@ -21,7 +20,6 @@ describe("the bundled workflow's access export", () => {
       "build.quality.conventions": { write: [] },
       "build.quality.spec-challenge": { write: [] },
       "refactor.build.review": { write: [".gtd/REVIEW.md"] },
-      "refactor.build.review.defer": { write: [".gtd/TODO.md"] },
       "refactor.build.quality.correctness": { write: [] },
       "refactor.build.quality.ponytail-review": { write: [] },
       "refactor.build.quality.conventions": { write: [] },
@@ -32,7 +30,6 @@ describe("the bundled workflow's access export", () => {
     expect(bundled).not.toHaveProperty(["refactor.build.review.fix.nits"])
     expect(bundled).not.toHaveProperty(["refactor.build.review.fix.risks"])
     expect(bundled["refactor.build.review"]).toEqual({ write: [".gtd/REVIEW.md"] })
-    expect(bundled["refactor.build.review.defer"]).toEqual({ write: [".gtd/TODO.md"] })
   })
 
   it("keys one lens scope per qualityReviews entry", () => {
@@ -54,17 +51,11 @@ describe("the bundled workflow's access export", () => {
       "refactor.build.quality.correctness",
       "refactor.build.quality.my-lens",
       "refactor.build.review",
-      "refactor.build.review.defer",
     ])
   })
 
-  it("keys only turn or script scopes", () => {
-    // `build.review.defer` is a script scope: no turn, so no skills entry.
-    const known = [
-      ...Object.keys(workflow.skills(defaults)),
-      "build.review.defer",
-      "refactor.build.review.defer",
-    ]
+  it("keys only turn scopes", () => {
+    const known = Object.keys(workflow.skills(defaults))
     for (const key of Object.keys(bundled)) expect(known).toContain(key)
   })
 })

package/src/workflows/shared/access.ts

@@ -13,12 +13,10 @@ export const access = (
 ): Readonly<Record<string, ScopeAccess>> => ({
   design: { write: [] },
   "build.review": { write: [".gtd/REVIEW.md"] },
-  "build.review.defer": { write: [".gtd/TODO.md"] },
   // `{}` reopens what `build.review` restricted: the fixes edit code.
   "build.review.fix.nits": {},
   "build.review.fix.risks": {},
   "refactor.build.review": { write: [".gtd/REVIEW.md"] },
-  "refactor.build.review.defer": { write: [".gtd/TODO.md"] },
   ...lensScopes("build.quality", lensesOf(vars.qualityReviews ?? ""), () => ({ write: [] })),
   ...lensScopes("refactor.build.quality", lensesOf(vars.refactorQualityReviews ?? ""), () => ({
     write: [],