@pmelab/gtd 42.0.0 → 44.0.0

package/src/cli/Program.ts

@@ -109,6 +109,7 @@ export {
 } from "./Output.js"
 import { runStraysCommand } from "./Strays.js"
 import { runHistoryFetchCommand, runHistoryListCommand, runHistoryShowCommand } from "./History.js"
+import { runHistoryJudgesCommand } from "./Judges.js"
 import { runHistoryMetricsCommand } from "./Metrics.js"
 
 /**
@@ -176,6 +177,12 @@ export type Command =
   | { readonly kind: "historyList" }
   | { readonly kind: "historyShow"; readonly ref: string }
   | { readonly kind: "historyMetrics"; readonly refs: readonly string[] }
+  | {
+      readonly kind: "historyJudges"
+      readonly refs: readonly string[]
+      readonly vars: Readonly<Record<string, string>>
+      readonly jsonl: boolean
+    }
   | { readonly kind: "historyFetch"; readonly remote: string }
   | {
       readonly kind: "strays"
@@ -1324,6 +1331,8 @@ const dispatchVoidCommand = (
       return runHistoryShowCommand(command.ref, json, out)
     case "historyMetrics":
       return runHistoryMetricsCommand(command.refs, json, out)
+    case "historyJudges":
+      return runHistoryJudgesCommand(command.refs, command.vars, command.jsonl, json, out)
     case "historyFetch":
       return runHistoryFetchCommand(command.remote, out)
   }

package/src/steering/FORMATS.md

@@ -24,11 +24,11 @@ read them.
   its first line starts `H:`.
 - **Review notes**: what a human added to a `review` document since the reviewer
   wrote it — changed chunk prose, pointer notes, and new one-shot footnotes,
-  never threads. **This is the hand-off from the `review` workflow to the `fix`
-  workflow**: `review` leaves the annotated file beside the reviewer's own copy
+  never threads. **This is the hand-off from a `fix` review to the next `fix`**:
+  the review leaves the annotated file beside the reviewer's own copy
   (`.gtd/REVIEW.orig.md`), and `fix` reads its work from the notes between the
-  two and from the risks, so a file `review` wrote must read the same in any
-  `fix` that consumes it.
+  two and from the risks, so a hand-off file must read the same in any `fix`
+  that consumes it.
 
 ## What may change
 

package/src/steering/index.ts

@@ -8,7 +8,18 @@ import type {
 export { formatFinding } from "./SteeringFormat.js"
 import { qaDescriptor } from "./qa.js"
 import { reviewDescriptor } from "./review.js"
-export { reviewNotes, reviewRisks, type ReviewNote } from "./review.js"
+export {
+  ANSWER_FIX,
+  ANSWER_LEAD,
+  ANSWER_WONT_FIX,
+  reviewDecisions,
+  reviewNotes,
+  reviewRisks,
+  unansweredNotes,
+  type ReviewChoice,
+  type ReviewDecision,
+  type ReviewNote,
+} from "./review.js"
 export { applySteeringEdits } from "./Edits.js"
 
 export type { InlineNode } from "./Inline.js"

package/src/steering/review.test.ts

@@ -1839,3 +1839,110 @@ describe("reviewRisks", async () => {
     expect(reviewRisks(doc("Prose.", ["- [ ] ./src/a.ts#1-3 — fine"]))).toEqual([])
   })
 })
+
+describe("answer boxes", async () => {
+  const { reviewDecisions, reviewNotes, unansweredNotes } = await import("./review.js")
+  const note = (title: string, boxes: readonly [string, string, string]): string =>
+    [
+      `## ${title}`,
+      "",
+      "Should subtract round?",
+      "",
+      "Tick exactly one:",
+      "",
+      `- [${boxes[0]}] fix as suggested`,
+      `- [${boxes[1]}] won't fix`,
+      `- [${boxes[2] === "" ? " " : "x"}] ${boxes[2] === "" || boxes[2] === "x" ? "_your answer_" : boxes[2]}`,
+    ].join("\n")
+  const doc = (...chunks: string[]): string =>
+    ["# Review: abc1234", "", "<!-- base: abc1234 -->", "", ...chunks, ""].join("\n")
+  const open = doc(note("Rounding", [" ", " ", ""]))
+
+  it("are no file pointers, no finding and no part of the note's text", () => {
+    expect(steeringFormatFor("review")!.validate(open)).toEqual([])
+    expect(parseReviewDoc(open).changesets[0]).toMatchObject({
+      description: "Should subtract round?",
+      files: [],
+    })
+  })
+
+  it("survive the gate's tick reset", () => {
+    const ticked = doc(note("Rounding", ["x", " ", ""]))
+    expect(steeringFormatFor("review")!.clearTicks(ticked)).toBe(ticked)
+  })
+
+  it("a tick is never a note", () => {
+    expect(reviewNotes(open, doc(note("Rounding", [" ", "x", ""])))).toEqual([])
+  })
+
+  it("an unticked note, or one with two ticks, is unanswered", () => {
+    expect(unansweredNotes(open)).toEqual([
+      { title: "Rounding", line: 5, reason: "tick exactly one box" },
+    ])
+    expect(unansweredNotes(doc(note("Rounding", ["x", "x", ""])))).toHaveLength(1)
+  })
+
+  it("a ticked free-text slot still holding the placeholder is unanswered", () => {
+    expect(unansweredNotes(doc(note("Rounding", [" ", " ", "x"])))).toHaveLength(1)
+  })
+
+  it("each box decides its note", () => {
+    const after = doc(
+      note("Fix it", ["x", " ", ""]),
+      note("Leave it", [" ", "x", ""]),
+      note("Answer it", [" ", " ", "round half up"]),
+    )
+    expect(unansweredNotes(after)).toEqual([])
+    expect(reviewDecisions("", after)).toEqual([
+      { anchor: "Fix it", body: "Should subtract round?", choice: "fix", text: "" },
+      { anchor: "Leave it", body: "Should subtract round?", choice: "wontfix", text: "" },
+      {
+        anchor: "Answer it",
+        body: "Should subtract round?",
+        choice: "answer",
+        text: "round half up",
+      },
+    ])
+  })
+
+  it("an answer the baseline already held is no new decision", () => {
+    const answered = doc(note("Rounding", ["x", " ", ""]))
+    expect(reviewDecisions(answered, answered)).toEqual([])
+    expect(reviewDecisions(answered, doc(note("Rounding", [" ", "x", ""])))).toMatchObject([
+      { choice: "wontfix" },
+    ])
+  })
+
+  it("are read by position: an edited label or a path-like answer still answers", () => {
+    const edited = doc(
+      note("Rounding", [" ", " ", ""]).replace("- [ ] fix as suggested", "- [x] fix it, but floor"),
+    )
+    expect(reviewDecisions("", edited)).toMatchObject([{ choice: "fix" }])
+    const pathy = doc(note("Rounding", [" ", " ", "./src/calc.ts#1-1 round here"]))
+    expect(steeringFormatFor("review")!.validate(pathy)).toEqual([])
+    expect(reviewDecisions("", pathy)).toMatchObject([
+      { choice: "answer", text: "./src/calc.ts#1-1 round here" },
+    ])
+    expect(steeringFormatFor("review")!.clearTicks(pathy)).toBe(pathy)
+  })
+
+  it("a note whose boxes were deleted is unanswered", () => {
+    const gone = doc("## Rounding\n\nShould subtract round?")
+    expect(unansweredNotes(gone, open)).toEqual([
+      { title: "Rounding", line: 0, reason: "its answer boxes were deleted — restore them" },
+    ])
+    expect(unansweredNotes(doc(), open)).toHaveLength(1)
+  })
+
+  it("a box added or removed leaves the note unanswered", () => {
+    const four = doc(note("Rounding", ["x", " ", ""]).concat("\n- [ ] another"))
+    expect(unansweredNotes(four)).toHaveLength(1)
+  })
+
+  it("a box list other than gtd's three is a pointer gone wrong", () => {
+    const stray = doc("## Chunk\n\n- [ ] fix as suggested\n- [ ] something else\n- [ ] third")
+    expect(steeringFormatFor("review")!.validate(stray)).toEqual([
+      expect.objectContaining({ message: 'Chunk "Chunk" has no file pointers' }),
+    ])
+  })
+})

package/src/steering/review.ts

@@ -1,4 +1,4 @@
-import type { ListItem, Root, RootContent } from "mdast"
+import type { List, ListItem, Root, RootContent } from "mdast"
 import { blockNodesOfRun, blockRunInline } from "./Blocks.js"
 import type { FootnoteAnchor } from "./Footnotes.js"
 import {
@@ -35,6 +35,7 @@ import {
   toLspPositionFromOffset,
   type HeadingBlock,
 } from "./MarkdownTree.js"
+import { FREE_TEXT_PLACEHOLDER } from "./qa.js"
 import type {
   SteeringAnchor,
   SteeringAnnotateResult,
@@ -74,8 +75,20 @@ interface Changeset {
   readonly files: readonly ReviewFile[]
   /** 0-based index of this chunk's `##` heading. */
   readonly headingLine: number
+  /** The chunk's answer boxes, when gtd gave it some. */
+  readonly answers?: readonly AnswerOption[]
 }
 
+interface AnswerOption {
+  readonly checked: boolean
+  /** The free-text slot's unfilled placeholder normalizes to `""`. */
+  readonly text: string
+}
+
+export const ANSWER_LEAD = "Tick exactly one:"
+export const ANSWER_FIX = "fix as suggested"
+export const ANSWER_WONT_FIX = "won't fix"
+
 interface ReviewDoc {
   readonly shortHash?: string
   readonly fullHash?: string
@@ -470,6 +483,44 @@ const parseHunk = (
   return { file, errors }
 }
 
+const itemText = (content: string, item: ListItem): string =>
+  item.children
+    .map((c) => sourceText(content, c))
+    .join(" ")
+    // A ticked item's first paragraph span starts at its `[x]`.
+    .replace(/^\[[ xX]\]\s*/, "")
+    .trim()
+
+/**
+ * The task list right after the `Tick exactly one:` paragraph, with that
+ * paragraph's index. Read by position, never by label, so an edited label or
+ * a free text opening with `./path` is still an answer, not a pointer. Any
+ * count but three boxes is kept, and reads as unanswered.
+ */
+const answerListOf = (
+  content: string,
+  body: readonly RootContent[],
+): { readonly lead: number; readonly list: List; readonly options: AnswerOption[] } | undefined => {
+  const lead = body.findIndex(
+    (n, i) =>
+      n.type === "paragraph" &&
+      sourceText(content, n) === ANSWER_LEAD &&
+      body[i + 1]?.type === "list" &&
+      (body[i + 1] as List).children.every((item) => item.checked != null),
+  )
+  if (lead === -1) return undefined
+  const list = body[lead + 1] as List
+  const last = list.children.length - 1
+  const options = list.children.map((item, i) => {
+    const text = itemText(content, item)
+    return {
+      checked: item.checked === true,
+      text: i === last && text.toLowerCase() === FREE_TEXT_PLACEHOLDER.toLowerCase() ? "" : text,
+    }
+  })
+  return { lead, list, options }
+}
+
 /** Splits one chunk's body nodes into its file pointers (hunk pointers are task items, collected recursively at ANY nesting depth via `taskItems` — a nested hunk is the same kind of hunk as a top-level one) and description prose. The description is the chunk's own leading run and never a node that contains a hunk pointer: it stops at the first node whose `taskItems` include a real pointer (at any depth — a blockquote wrapping a pointer list stops it just as a top-level list would). Every node kind in what's left before that point contributes — a `footnoteDefinition` is the one exception, excluded by `blockNodesOfRun` itself (it's a note, never document content). */
 const parseChunkBody = (
   content: string,
@@ -482,11 +533,19 @@ const parseChunkBody = (
   readonly descriptionInline: readonly InlineNode[]
   readonly files: readonly ReviewFile[]
   readonly errors: readonly SteeringFinding[]
+  readonly answers?: readonly AnswerOption[]
+  /** Whether a task box outside the answer list exists. */
+  readonly boxed: boolean
 } => {
-  const firstPointerIndex = body.findIndex((n) =>
-    taskItems(n).some((item) => hasPointerToken(content, item)),
+  const answer = answerListOf(content, body)
+  const isAnswer = (n: RootContent): boolean =>
+    answer !== undefined && (n === answer.list || n === body[answer.lead])
+  const firstPointerIndex = body.findIndex(
+    (n) => !isAnswer(n) && taskItems(n).some((item) => hasPointerToken(content, item)),
+  )
+  const leadingRun = (firstPointerIndex === -1 ? body : body.slice(0, firstPointerIndex)).filter(
+    (n) => !isAnswer(n),
   )
-  const leadingRun = firstPointerIndex === -1 ? body : body.slice(0, firstPointerIndex)
   const descriptionNodes = blockNodesOfRun(content, leadingRun)
   const descriptionInline = collapseImages(blockRunInline(content, leadingRun))
   const description = leadingRun
@@ -497,13 +556,21 @@ const parseChunkBody = (
 
   const files: ReviewFile[] = []
   const errors: SteeringFinding[] = []
-  for (const item of body.flatMap((n) => taskItems(n))) {
+  for (const item of body.filter((n) => !isAnswer(n)).flatMap((n) => taskItems(n))) {
     const parsed = parseHunk(content, lines, title, item)
     if (!parsed) continue
     files.push(parsed.file)
     errors.push(...parsed.errors)
   }
-  return { description, descriptionNodes, descriptionInline, files, errors }
+  return {
+    description,
+    descriptionNodes,
+    descriptionInline,
+    files,
+    errors,
+    ...(answer === undefined ? {} : { answers: answer.options }),
+    boxed: body.some((n) => !isAnswer(n) && taskItems(n).length > 0),
+  }
 }
 
 /** One `##` chunk heading node with its raw body block nodes (up to the next `##`-or-shallower heading). */
@@ -550,18 +617,28 @@ const parseChangesets = (
       descriptionNodes,
       descriptionInline,
       files,
+      answers,
+      boxed,
       errors: bodyErrors,
     } = parseChunkBody(content, lines, title, body)
     errors.push(...bodyErrors)
     // A prose-only chunk is a note gtd composed; a box with no pointer is a pointer gone wrong.
-    if (files.length === 0 && body.some((n) => taskItems(n).length > 0)) {
+    if (files.length === 0 && boxed) {
       errors.push({
         message: `Chunk "${title}" has no file pointers`,
         line: headingLine,
         range: nodeRange(heading),
       })
     }
-    changesets.push({ title, description, descriptionNodes, descriptionInline, files, headingLine })
+    changesets.push({
+      title,
+      description,
+      descriptionNodes,
+      descriptionInline,
+      files,
+      headingLine,
+      ...(answers === undefined ? {} : { answers }),
+    })
   }
   if (changesets.length === 0) errors.push({ message: "REVIEW.md has no '##' chunks" })
   return { changesets, errors }
@@ -645,8 +722,13 @@ const isHunkPointerItem = (content: string, item: ListItem): boolean => {
  */
 const reviewClearTicks = (content: string): string => {
   const tree = parseMarkdown(content)
+  const answers = new Set(
+    splitChunks(tree).flatMap(({ body }) => answerListOf(content, body)?.list.children ?? []),
+  )
   const offsets = taskItems(tree)
-    .filter((item) => item.checked === true && isHunkPointerItem(content, item))
+    .filter(
+      (item) => item.checked === true && !answers.has(item) && isHunkPointerItem(content, item),
+    )
     .map((item) => checkboxOffset(content, item))
     .filter((o): o is number => o !== undefined)
     .sort((a, b) => a - b)
@@ -1185,3 +1267,71 @@ export const reviewRisks = (
       ),
     )
     .map((r, i) => ({ id: `risk-${i + 1}`, ...r }))
+
+export type ReviewChoice = "fix" | "wontfix" | "answer"
+
+/** A note's answer: one box ticked, and a ticked free-text slot filled in. */
+export interface ReviewDecision {
+  /** The note's chunk title. */
+  readonly anchor: string
+  /** The note's text as gtd wrote it. */
+  readonly body: string
+  readonly choice: ReviewChoice
+  /** The human's free text; empty unless `choice` is `answer`. */
+  readonly text: string
+}
+
+const CHOICES: readonly ReviewChoice[] = ["fix", "wontfix", "answer"]
+
+const decisionOf = (chunk: Changeset): ReviewDecision | undefined => {
+  if (chunk.answers?.length !== 3) return undefined
+  const ticked = chunk.answers.flatMap((o, i) => (o.checked ? [i] : []))
+  if (ticked.length !== 1) return undefined
+  const i = ticked[0]!
+  const text = i === 2 ? chunk.answers![2]!.text : ""
+  if (i === 2 && text === "") return undefined
+  return { anchor: chunk.title, body: chunk.description, choice: CHOICES[i]!, text }
+}
+
+/**
+ * Notes whose answer boxes do not hold exactly one tick (a ticked free-text
+ * slot filled in), with their 1-based heading line and why; and, given the
+ * file `before` the edit, every note whose boxes were deleted.
+ */
+export const unansweredNotes = (
+  content: string,
+  before?: string,
+): readonly { title: string; line: number; reason: string }[] => {
+  const now = parseReviewDoc(content).changesets
+  const boxed = new Set(now.filter((c) => c.answers !== undefined).map((c) => c.title))
+  const removed = (before === undefined ? [] : parseReviewDoc(before).changesets)
+    .filter((c) => c.answers !== undefined && !boxed.has(c.title))
+    .map((c) => ({
+      title: c.title,
+      line: 0,
+      reason: "its answer boxes were deleted — restore them",
+    }))
+  const open = now
+    .filter((c) => c.answers !== undefined && decisionOf(c) === undefined)
+    .map((c) => ({
+      title: c.title,
+      line: c.headingLine + 1,
+      reason:
+        c.answers!.length === 3
+          ? "tick exactly one box"
+          : `it has ${c.answers!.length} boxes — restore the three gtd wrote`,
+    }))
+  return [...open, ...removed]
+}
+
+/** Every answer in `after` that `before` did not already hold for the same note, in document order. */
+export const reviewDecisions = (before: string, after: string): readonly ReviewDecision[] => {
+  const prior = new Map(parseReviewDoc(before).changesets.map((c) => [c.title, c]))
+  return parseReviewDoc(after).changesets.flatMap((chunk) => {
+    const decision = decisionOf(chunk)
+    if (decision === undefined) return []
+    const was = prior.get(chunk.title)
+    const old = was === undefined ? undefined : decisionOf(was)
+    return old?.choice === decision.choice && old.text === decision.text ? [] : [decision]
+  })
+}

package/src/testkit/EmittedScriptRecognizer.ts

@@ -670,19 +670,6 @@ const splitBlocks = (script: string): readonly string[] => {
   return blocks
 }
 
-/** `deferNotesScript`: append its one section to `.gtd/TODO.md`, reading the section's lines off the final `printf`. */
-const DEFER_HEAD = "mkdir -p .gtd\nif [ -s .gtd/TODO.md ]; then"
-const recognizeDeferNotes = (repo: InMemRepo, block: string): BlockOutcome | undefined => {
-  if (!block.startsWith(DEFER_HEAD)) return undefined
-  const at = block.lastIndexOf("\nprintf '%s\\n' ")
-  if (at === -1) return undefined
-  const lines = extractQuotedTokens(block.slice(at + "\nprintf '%s\\n' ".length))
-  const old = repo.readFile(".gtd/TODO.md") ?? ""
-  const sep = old === "" ? "" : `${old.endsWith("\n") ? "" : "\n"}\n`
-  repo.writeFile(".gtd/TODO.md", `${old}${sep}${lines.join("\n")}\n`)
-  return { kind: "applied" }
-}
-
 /** `mkdir -p <dir>` then `printf '%s\n' <quoted lines> > <path>`: a flow's one-file write. Re-rendered from what was extracted, so any other shape stays unrecognized. */
 const recognizeWriteLines = (repo: InMemRepo, block: string): BlockOutcome | undefined => {
   const [mkdir, printf, ...rest] = block.split("\n")
@@ -715,7 +702,6 @@ const recognizersFor = (
   (block) => recognizeFileExistsGuard(repo, block),
   (block) => recognizeBinaryGuard(commands, block),
   (block) => (git ? recognizeGitBuilders(repo, block) : undefined),
-  (block) => recognizeDeferNotes(repo, block),
   (block) => recognizeWriteLines(repo, block),
   (block) => recognizeFailurePromptWrapper(repo, commands, block),
   (block) => recognizePresentationSubshell(repo, commands, block, git),

package/src/testkit/steps.ts

@@ -267,6 +267,10 @@ Then(
   },
 )
 
+Then("landing is refused with {string}", async (world: TestkitWorld, message: string) => {
+  await assert.rejects(world.repo().land(), (error: Error) => error.message.includes(message))
+})
+
 Then(
   "driving the process is refused with {string}",
   async (world: TestkitWorld, message: string) => {