@pmelab/gtd 42.0.0 → 44.0.0

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

@@ -5,7 +5,6 @@ import { join } from "node:path"
 import { afterEach, describe, expect, it } from "vitest"
 import {
   buildReviewTriageMessage,
-  deferNotesScript,
   buildReviewReviewingPrompt,
   agentWithSkills,
   buildFixPrompt,
@@ -32,8 +31,7 @@ import {
   withSkills,
   composedReview,
 } from "./text.js"
-import { steeringFormatFor } from "../../steering/index.js"
-import { applyEmittedScript, InMemRepo } from "../../testkit/index.js"
+import { steeringFormatFor, unansweredNotes } from "../../steering/index.js"
 import { captureStep, renderText } from "./text.fixture.js"
 
 describe("withSkills", () => {
@@ -829,53 +827,6 @@ describe("buildReviewReviewingPrompt risk marking", () => {
   })
 })
 
-describe("deferNotesScript", () => {
-  const run = (notes: Parameters<typeof deferNotesScript>[0], existing?: string): string => {
-    const dir = mkdtempSync(join(tmpdir(), "defer-"))
-    mkdirSync(join(dir, ".gtd"))
-    if (existing !== undefined) writeFileSync(join(dir, ".gtd/TODO.md"), existing)
-    execFileSync("sh", ["-c", deferNotesScript(notes, "abcdef1234567890")], { cwd: dir })
-    return readFileSync(join(dir, ".gtd/TODO.md"), "utf8")
-  }
-  const notes = [{ id: "note-1", anchor: "a.ts:3", text: "plain", label: "could: tiny" }]
-
-  it("creates the file with one section headed by the round's short sha", () => {
-    expect(run(notes)).toBe(
-      "## Deferred review notes (abcdef1)\n\n- note-1 — a.ts:3 (could: tiny): plain\n",
-    )
-  })
-
-  it("appends after a blank line, never truncating", () => {
-    const out = run(notes, "# Sketch\n\nkeep me\n")
-    expect(out.startsWith("# Sketch\n\nkeep me\n\n## Deferred review notes (abcdef1)\n")).toBe(true)
-  })
-
-  it("separates from a file lacking a trailing newline", () => {
-    expect(run(notes, "keep")).toContain("keep\n\n## Deferred")
-  })
-
-  it("lands quotes, dollars and backticks verbatim", () => {
-    const text = 'it\'s $HOME `x` "q" \\n'
-    const out = run([{ id: "note-1", anchor: "a", text }])
-    expect(out).toContain(text)
-  })
-
-  it("is an oxfmt fixed point, for a note longer than one line", () => {
-    const long = [
-      {
-        id: "note-3",
-        anchor: "Parser accepts CRLF ./src/parse.ts#30-31",
-        text: "rename the helper to something clearer please",
-        label: "could",
-      },
-    ]
-    const dir = mkdtempSync(join(tmpdir(), "fmt-"))
-    const file = join(dir, "TODO.md")
-    writeFileSync(file, run(long, "# Sketch\n"))
-    execFileSync("npx", ["oxfmt", "--check", file], { cwd: process.cwd() })
-  })
-})
-
 describe("severity wording", () => {
   it("triage message names the four severity ids", () => {
     const m = renderText(() => buildReviewTriageMessage())
@@ -888,44 +839,6 @@ describe("severity wording", () => {
     expect(p).toContain("capture order")
     expect(p).toContain("(tier: reason)")
   })
-
-  it("design triage parks deferred review notes", () => {
-    expect(renderText(() => designTriagePrompt("base"))).toContain("## Deferred review notes")
-  })
-})
-
-describe("deferNotesScript — the in-memory recognizer agrees with the real sh script", () => {
-  const notes = [
-    { id: "note-1", anchor: "a.ts:3", text: 'it\'s $HOME `x` "q" 100%', label: "could" },
-    {
-      id: "note-2",
-      anchor: "Parser accepts CRLF ./src/parse.ts#30-31",
-      text: "rename the helper to something clearer please",
-      label: "could",
-    },
-  ]
-  const cases: [string, string | undefined][] = [
-    ["no file", undefined],
-    ["an empty file", ""],
-    ["a file without a trailing newline", "keep"],
-    ["a file with a trailing newline", "# Sketch\n\nkeep\n"],
-  ]
-
-  it.each(cases)("%s", (_name, existing) => {
-    const script = deferNotesScript(notes, "abcdef1234567890")
-    const dir = mkdtempSync(join(tmpdir(), "defer-contract-"))
-    if (existing !== undefined) {
-      mkdirSync(join(dir, ".gtd"))
-      writeFileSync(join(dir, ".gtd/TODO.md"), existing)
-    }
-    execFileSync("sh", ["-c", script], { cwd: dir })
-    const real = readFileSync(join(dir, ".gtd/TODO.md"), "utf8")
-
-    const repo = new InMemRepo()
-    if (existing !== undefined) repo.writeFile(".gtd/TODO.md", existing)
-    expect(applyEmittedScript(repo, new Map(), script).ok).toBe(true)
-    expect(repo.readFile(".gtd/TODO.md")).toBe(real)
-  })
 })
 
 describe("buildReviewReviewingPrompt scenarios", () => {
@@ -1319,6 +1232,15 @@ it("asks the refactor review, and only it, to flag a test-file hunk that is more
   expect(first).not.toContain("give any test-file hunk its own chunk")
 })
 
+describe("buildReviewCollectingPrompt answer boxes", () => {
+  it("a hand-edit round folds fix and own answers, other rounds leave them to gtd", () => {
+    const edits = renderText(() => buildReviewCollectingPrompt("cap", undefined, "edits"))
+    expect(edits).toContain("A hand-edit round routes no answer box itself")
+    const triaged = renderText(() => buildReviewCollectingPrompt("cap", undefined, "triaged"))
+    expect(triaged).toContain("Never fold a note's ticked answer box")
+  })
+})
+
 describe("composedReview", () => {
   const BASE = "0123456789abcdef0123456789abcdef01234567"
 
@@ -1380,6 +1302,35 @@ describe("composedReview", () => {
 
   it("names the nit fix on the review after it", () => {
     const doc = composedReview(BASE, { notes: [], fixed: [], noise: [], nitFix: "abcdef0123" })
-    expect(doc).toContain("## Fixed from your notes\n\nYour nits were fixed in abcdef0;")
+    expect(doc).toContain(
+      "## Fixed from your notes\n\nYour nits and fix-as-suggested notes were worked on in abcdef0;",
+    )
+  })
+
+  it("ends every note, and only a note, in its three answer boxes", () => {
+    const doc = composedReview(BASE, {
+      notes: [{ title: "a", body: "- ends in a list" }],
+      fixed: [{ title: "f", commit: "fedcba9876543210" }],
+      noise: [],
+    })
+    expect(doc).toContain(
+      "## a\n\n- ends in a list\n\nTick exactly one:\n\n- [ ] fix as suggested\n- [ ] won't fix\n- [ ] _your answer_\n\n## Fixed automatically",
+    )
+    expect(doc.match(/fix as suggested/g)).toHaveLength(1)
+    expect(unansweredNotes(doc)).toEqual([{ title: "a", line: 5, reason: "tick exactly one box" }])
+  })
+
+  it("leaves out the notes already answered", () => {
+    const doc = composedReview(BASE, {
+      notes: [
+        { title: "a", body: "1" },
+        { title: "a", body: "2" },
+      ],
+      fixed: [],
+      noise: [],
+      answered: new Set(["a"]),
+    })
+    expect(doc).not.toContain("## a\n")
+    expect(doc).toContain("## a (2)\n\n2")
   })
 })

package/src/workflows/shared/text.ts

@@ -12,6 +12,12 @@ import {
   type JudgeQuestion,
   type SummaryContext,
 } from "../../flows/index.js"
+import {
+  ANSWER_FIX,
+  ANSWER_LEAD,
+  ANSWER_WONT_FIX,
+  FREE_TEXT_PLACEHOLDER,
+} from "../../steering/index.js"
 import { escapeRegExp } from "./registry.js"
 import { defaultFlagRegistry } from "./vars.js"
 import type { CollectRound, RemovedAssertions, Requested } from "../../workflow-kit/index.js"
@@ -116,6 +122,8 @@ export interface ComposedReview {
   readonly weakened?: readonly RemovedAssertions[]
   /** The commit that fixed the human's nits, on the review that follows it. */
   readonly nitFix?: string | undefined
+  /** Titles of notes the human already answered, left out. */
+  readonly answered?: ReadonlySet<string> | undefined
 }
 
 const SUMMARY_TITLES = [
@@ -133,9 +141,9 @@ const unboxed = (body: string): string =>
 const short = (hash: string): string => hash.slice(0, 7)
 
 /**
- * \`.gtd/REVIEW.md\` as gtd writes it: one chunk per note, then the fixed and
- * noise lists, with no tick boxes. Chunk titles are made unique — notes are
- * matched to their chunk by title.
+ * \`.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 —
+ * notes and answers are matched to their chunk by title.
  */
 export const composedReview = (base: string, report: ComposedReview): string => {
   // Summary titles are taken first, so no note can claim one.
@@ -147,6 +155,11 @@ export const composedReview = (base: string, report: ComposedReview): string =>
     return name
   }
   const chunk = (title: string, body: string): string => `## ${title}\n\n${body.trim()}`
+  // The lead-in line keeps a body that ends in a list from absorbing the boxes.
+  const answerBoxes = `${ANSWER_LEAD}\n\n- [ ] ${ANSWER_FIX}\n- [ ] ${ANSWER_WONT_FIX}\n- [ ] ${FREE_TEXT_PLACEHOLDER}`
+  const notes = report.notes
+    .map((n) => ({ ...n, title: unique(n.title) }))
+    .filter((n) => report.answered?.has(n.title) !== true)
   const weakened = (report.weakened ?? []).flatMap(({ path, lines }) =>
     lines.map((a) => `- ${path} — ${a.scenario} — ${a.line}`),
   )
@@ -156,7 +169,7 @@ export const composedReview = (base: string, report: ComposedReview): string =>
       : [
           chunk(
             "Fixed from your notes",
-            `Your nits were fixed in ${short(report.nitFix)}; the list below is from before.`,
+            `Your nits and fix-as-suggested notes were worked on in ${short(report.nitFix)}; the notes you answered are left out — check the diff.`,
           ),
         ]),
     ...(weakened.length === 0
@@ -167,14 +180,16 @@ export const composedReview = (base: string, report: ComposedReview): string =>
             `These scenarios lost an assertion the review base had:\n\n${weakened.join("\n")}`,
           ),
         ]),
-    ...report.notes.map((n) =>
+    ...notes.map((n) =>
       chunk(
-        unique(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.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}`,
       ),
     ),
     ...(report.fixed.length === 0
@@ -288,10 +303,6 @@ ${stateFileRules}
 ${footnoteFoldIn}${codeThreadReplies()}
 - The only state file this turn touches is \`.gtd/REQUIREMENTS.md\`
   — no other files for notes or output
-- Lines of a \`## Deferred review notes\` section of \`.gtd/TODO.md\`
-  that the start diff does not touch are parked by review, never folded;
-  the human's edits to such a line (or its removal) are input like any
-  other part of the start diff
 - \`.gtd/TODO.md\` is the likely home of the sketch that started
   this process — the human's input, folded into the concerns
   below like any other part of the start diff; never a state
@@ -680,8 +691,12 @@ export const buildReviewAwaitReviewMessage = (base: string): string =>
 per finding that needs your judgement — it questions a criterion or the
 approach, or the fixer could not resolve it — then, for reference only, what
 was **fixed automatically** (with the fixing commit) and what was **dropped
-as noise**. Nothing there needs an answer; disagreeing with a fix or a drop
-means writing a note of your own.
+as noise**. Each finding chunk ends in three boxes — tick exactly one:
+\`fix as suggested\` (fixed in the nit batch below), \`won't fix\` (dropped,
+recorded in the commit), or write your own answer over \`_your answer_\` and
+tick it (judged like a note). Every landing here is refused until each
+finding holds exactly one tick. The fixed and noise lists need no answer;
+disagreeing with a fix or a drop means writing a note of your own.
 
 Review the diff yourself, with whatever tool you like — gtd checks
 nothing out and touches no ref; \`gtd base\` prints this same hash any
@@ -691,8 +706,8 @@ working tree:
     git diff ${base}
 When you've been through the whole diff, run \`gtd land\`:
 
-- **Sign off** — leave no comment — no note in
-  \`.gtd/REVIEW.md\`, no code edit — to close the process.
+- **Sign off** — answer every finding, leave no other comment — no note
+  in \`.gtd/REVIEW.md\`, no code edit — to close the process.
   Every turn commit stays on the
   branch; run \`gtd summary\` afterward for a closing-message
   prompt.
@@ -860,6 +875,17 @@ The reviewer's risks are:
 
 ${risks.length === 0 ? "(none)\n" : notesCapture(risks)}`
 
+export const reviewFeedbackFixPrompt = (): string =>
+  `${stateFileRules}
+- Read \`.gtd/REQUIREMENTS.md\` — the concerns the human's review asked for,
+  one \`## \` heading each, in build order
+- Build every concern in this one turn; an answered question is context,
+  not a concern
+- Where a change is behavioural, add a test that fails without it
+- Leave \`.gtd/REQUIREMENTS.md\` untouched — the next step removes it
+- Leave everything uncommitted and finish your turn
+`
+
 export const buildReviewReviewMissingMessage = (commit: string): string =>
   `The review round committed no \`.gtd/REVIEW.md\` (at ${commit}), so there is
 nothing to sign off on.
@@ -894,34 +920,6 @@ const wrapItem = (item: string): string[] => {
   return [...out, line]
 }
 
-/** Appends one section of `notes` to `.gtd/TODO.md`, wrapped the way oxfmt writes it; an existing file is only ever appended to. */
-export const deferNotesScript = (notes: readonly NoteInput[], round: string): string => {
-  const lines = [
-    `## Deferred review notes (${round.slice(0, 7)})`,
-    "",
-    ...notes.flatMap((n) => wrapItem(`- ${noteHead(n)}: ${n.text.replace(/\s+/g, " ")}`)),
-  ]
-  return `mkdir -p .gtd
-if [ -s .gtd/TODO.md ]; then
-  [ -z "$(tail -c1 .gtd/TODO.md)" ] || printf '\\n' >> .gtd/TODO.md
-  printf '\\n' >> .gtd/TODO.md
-fi
-printf '%s\\n' ${lines.map(quote).join(" ")} >> .gtd/TODO.md
-`
-}
-
-/** The gate right after a deferral: landing clean signs off without these notes. */
-export const buildReviewAwaitAfterDeferMessage = (
-  base: string,
-  deferred: readonly NoteInput[],
-): string =>
-  `${buildReviewAwaitReviewMessage(base)}
-Deferred to \`.gtd/TODO.md\` just now, NOT acted on in this process — landing
-clean signs off without them:
-
-${deferred.map((n) => `- ${noteHead(n)}: ${n.text.replace(/\s*\n\s*/g, " ")}`).join("\n")}
-`
-
 export const buildReviewTriageMessage = (): string =>
   `Judging each note the human added to \`.gtd/REVIEW.md\` (a line note, a
 footnote, or prose under a chunk) with one verdict: \`edit\` (a change
@@ -932,12 +930,14 @@ default; a skipped judgment never dismisses a note).
 
 Also judge each note's severity, one id per note: \`note-<n>.security\`,
 \`note-<n>.reversibility\`, \`note-<n>.blastRadius\` and
-\`note-<n>.newConcept\`.
+\`note-<n>.newConcept\`. An own answer under a finding's boxes is judged
+the same way, keyed \`answer-<n>\`.
 `
 const closedFold = (round: CollectRound, target: string): string =>
   round === "edits"
     ? `- Fold every hand-edit and every note the human left that round into
-  \`${target}\`
+  \`${target}\` — a note ticked \`fix as suggested\` or answered in its
+  own words included; one ticked \`won't fix\` is dropped
 `
     : round === "notes"
       ? `- Fold each note that asks for a change into \`${target}\`
@@ -954,6 +954,7 @@ export const buildReviewCollectingPrompt = (
     /** `"reply"` is the in-gate reply turn; any other round is closed and folds what that round left. */
     readonly round: CollectRound
   },
+  round?: CollectRound,
 ): string => {
   const target = refactor ? ".gtd/REFACTOR.md" : ".gtd/REQUIREMENTS.md"
   const fence = refactor
@@ -1038,12 +1039,20 @@ ${closedFold(refactor.round, target)}`
     : `- This turn writes \`${target}\` (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
-  \`${target}\` 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 \`${target}\` and
+  delete the folded threads from \`.gtd/REVIEW.md\`; append one \`- A:\`
+  reply to each thread whose last entry is a \`- H:\` question
+${
+  round === "edits"
+    ? `- A hand-edit round routes no answer box itself: fold each note
+  ticked \`fix as suggested\` or answered in its own words, too; drop one
+  ticked \`won't fix\`
 `
+    : `- 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 \`${target}\`'s \`## Answered Questions\` as
   \`### <the note>\` plus its answer — the lap replaces \`.gtd/REVIEW.md\`