@pmelab/gtd 23.2.0 → 24.1.0

package/src/steering/review.ts

@@ -0,0 +1,1180 @@
+import type { ListItem, Root, RootContent } from "mdast"
+import { blockNodesOfRun, blockRunInline } from "./Blocks.js"
+import type { FootnoteAnchor } from "./Footnotes.js"
+import {
+  collapseImages,
+  definitionsOf,
+  joinInlineRuns,
+  projectInline,
+  type InlineNode,
+} from "./Inline.js"
+import {
+  FOOTNOTE_ACTION_TITLE,
+  footnoteAdditionEdits,
+  footnoteAttachEdits,
+  footnotePointerAt,
+  isOnExistingFootnote,
+  openThreadsOf,
+  threadOutlineNodes,
+  threadReplyActions,
+  noteLookup,
+  parseFootnotes,
+  parseThreads,
+} from "./Footnotes.js"
+import {
+  blockEndLine,
+  blockNodeAt,
+  footnoteLeaf,
+  headingText,
+  lineRange,
+  parseMarkdown,
+  sourceText,
+  spanRange,
+  taskItems,
+  toLspPosition,
+  toLspPositionFromOffset,
+  type HeadingBlock,
+} from "./MarkdownTree.js"
+import type {
+  SteeringAnchor,
+  SteeringAnnotateResult,
+  SteeringEdit,
+  SteeringFinding,
+  SteeringFormat,
+  SteeringLink,
+  SteeringOutlineNode,
+  SteeringView,
+  SteeringViewNode,
+} from "./SteeringFormat.js"
+
+interface ReviewFile {
+  readonly path: string
+  /** 1-based post-image line — the range's own start when the pointer carries one, absent entirely for a bare `./path` with no `#` at all. */
+  readonly line?: number
+  /** 1-based post-image end line of a `#<start>-<end>` range — `line` holds the start. Absent for a bare `#<line>` pointer or a `#`-less one. */
+  readonly rangeEnd?: number
+  readonly checked: boolean
+  /** The pointer's explanation: same-line text (if any) first, then the lines gathered from BELOW it, joined with " ". */
+  readonly note?: string
+  /** `note`'s own inline structure, image-collapsed (R2) — feeds the hunk node's `detailInline`. Absent exactly where `note` is. */
+  readonly noteInline?: readonly InlineNode[]
+  /** 0-based line index of this file pointer's own `- [ ]`/`- [x]` line in REVIEW.md, for editor tooling. */
+  readonly sourceLine: number
+  /** 0-based index of the last line of this pointer's OWN span (excluding any nested hunk's span); equals `sourceLine` when it has no explanation. */
+  readonly endLine: number
+}
+
+interface Changeset {
+  readonly title: string
+  readonly description: string
+  /** The same leading run collapsed into `description`, projected as block nodes (`Blocks.ts#blockNodesOfRun`) instead of flattened text — `Review.tsx`'s chunk screen renders these through the shared prose-block rendering. */
+  readonly descriptionNodes: readonly SteeringViewNode[]
+  /** `description`'s own inline structure, image-collapsed (R2) — feeds the chunk node's `detailInline`. */
+  readonly descriptionInline: readonly InlineNode[]
+  readonly files: readonly ReviewFile[]
+  /** 0-based index of this chunk's `##` heading. */
+  readonly headingLine: number
+}
+
+interface ReviewDoc {
+  readonly shortHash?: string
+  readonly fullHash?: string
+  readonly changesets: readonly Changeset[]
+  readonly findings: readonly SteeringFinding[]
+}
+
+/**
+ * The canonical sample. Every detail here is load-bearing for the formatter
+ * round-trip: both footnote bodies exceed 80 characters so a reflow actually
+ * happens, the chunk's is `na`-prefixed (server-attached, not hand-authored)
+ * and carries a multi-word inline code span, and the whole document is
+ * already an oxfmt fixed point.
+ */
+const REVIEW_SAMPLE = `# Review: sample123
+
+<!-- base: 0000000000000000000000000000000000000000 -->
+
+## Sample chunk[^naduiqc4]
+
+- [ ] ./sample.ts#1-1 what this hunk does[^fn1]
+
+[^fn1]:
+    This note explains why the hunk exists in more detail than fits on one line
+    for a reviewer.
+
+[^naduiqc4]:
+    Attached via the phone UI, this note demonstrates a chunk-level comment with
+    a \`multi word code span\` that exceeds eighty characters in total length
+    here.
+`
+
+/** The `# Review: <hash>` header, once a depth-1 heading's own inline text has been extracted. */
+const HEADER_TEXT_RE = /^Review:\s*(\S+)$/
+/** The `<!-- base: <hash> -->` comment, matched against an `html` node's own raw `value`. */
+const BASE_COMMENT_RE = /^<!--\s*base:\s*(\S+)\s*-->$/
+/** A pointer token's trailing `#<start>-<end>` range (greedy, so a `#` inside the path stays in it, and the LAST `#` wins). */
+const POINTER_RANGE_RE = /^(.*)#(\d+)-(\d+)$/
+/** A pointer token's trailing bare `#<line>` (greedy, same rules as `POINTER_RANGE_RE`) — tried only once the range form has failed to match, so a range token is never misread as a bare line whose path happens to end in digits after a dash. */
+const POINTER_LINE_RE = /^(.*)#(\d+)$/
+/** The optional dash that may lead the inline note segment or a continuation block — em dash, en dash, or hyphens. */
+const NOTE_SEPARATOR_RE = /^[—–-]+\s*/
+
+/** A node's own span as a `SteeringFinding.range` — the NODE a heading- or block-shaped finding is about. */
+const nodeRange = (node: RootContent) => ({
+  start: toLspPosition(node.position!.start),
+  end: toLspPosition(node.position!.end),
+})
+
+/** The `# Review: <hash>` header, required as the document's first top-level node — never a heading found merely somewhere inside a fenced example. */
+const parseHeader = (tree: Root, content: string): string | undefined => {
+  const first = tree.children[0]
+  if (!first || first.type !== "heading" || first.depth !== 1) return undefined
+  return HEADER_TEXT_RE.exec(headingText(content, first))?.[1]
+}
+
+/** A node shape wide enough to walk for an `html` node's raw text, at any depth. */
+interface WalkableNode {
+  readonly type: string
+  readonly value?: string
+  readonly children?: readonly WalkableNode[]
+}
+
+/** The `<!-- base: <hash> -->` comment, wherever in the tree it appears — a real `html` node, never a string search over raw lines (which would also match one quoted inside a fence, since that content never becomes an `html` node at all). */
+const parseBaseComment = (tree: Root): string | undefined => {
+  let found: string | undefined
+  const walk = (node: WalkableNode): void => {
+    if (found !== undefined) return
+    if (node.type === "html") {
+      const match = BASE_COMMENT_RE.exec((node.value ?? "").trim())
+      if (match) {
+        found = match[1]
+        return
+      }
+    }
+    node.children?.forEach(walk)
+  }
+  walk(tree as unknown as WalkableNode)
+  return found
+}
+
+/**
+ * The single source of truth for splitting a pointer token, so no caller can
+ * parse the same token two different ways. Range is tried FIRST — the
+ * bare-line regex could not match `#42-70` anyway, but the explicit order
+ * beats relying on that accident.
+ */
+const parsePointerToken = (
+  token: string,
+): {
+  readonly path: string
+  readonly rangeEnd?: number
+  readonly line?: number
+} => {
+  const rangeMatch = POINTER_RANGE_RE.exec(token)
+  if (rangeMatch) {
+    return {
+      path: rangeMatch[1]!,
+      line: Number(rangeMatch[2]),
+      rangeEnd: Number(rangeMatch[3]),
+    }
+  }
+  const lineMatch = POINTER_LINE_RE.exec(token)
+  if (lineMatch) return { path: lineMatch[1]!, line: Number(lineMatch[2]) }
+  return { path: token }
+}
+
+/** The pointer's own display form — `path#start-end` when it carries a range, `path#line` for a bare line, else the bare path. Shared by the second-pointer finding's target and `reviewView`'s hunk title so the two can never render a range pointer differently. */
+const pointerDisplay = (file: {
+  readonly path: string
+  readonly rangeEnd?: number
+  readonly line?: number
+}): string => {
+  if (file.line !== undefined && file.rangeEnd !== undefined) {
+    return `${file.path}#${file.line}-${file.rangeEnd}`
+  }
+  return file.line !== undefined ? `${file.path}#${file.line}` : file.path
+}
+
+/** True when `token` parses as a file pointer's path token — leading `./`, and a path longer than two characters once an optional `#<line>`/`#<start>-<end>` suffix is stripped. The single source of truth for "is this a pointer token", shared by `parseHunk`, the second-pointer finding below, and `reviewClearTicks` so all three can never drift apart. */
+const isPointerToken = (token: string): boolean => {
+  if (!token.startsWith("./")) return false
+  return parsePointerToken(token).path.length > 2 // `./` with nothing after it is not a path
+}
+
+/**
+ * The second-pointer validation error: a note whose first token is itself a
+ * pointer token. The relaxed same-line form would otherwise silently read
+ * `- [ ] ./a.ts#1 ./b.ts#2` (or with a separator, `- [ ] ./a.ts#1 — ./b.ts#2`)
+ * as ONE pointer whose note is `./b.ts#2`, dropping the second hunk entirely —
+ * this is the one case the relaxed parser must still refuse, and it points at
+ * the pointer's own `sourceLine` so it renders as a positioned finding.
+ */
+const secondPointerError = (
+  range: SteeringFinding["range"],
+  title: string,
+  file: ReviewFile,
+  secondToken: string,
+): SteeringFinding => {
+  const target = pointerDisplay(file)
+  return {
+    message: `Chunk "${title}" hunk ${target}'s note starts with a second pointer (${secondToken}) — give it its own "- [ ]" line`,
+    line: file.sourceLine,
+    ...(range ? { range } : {}),
+  }
+}
+
+/** The source OFFSET right after an item's `- [ ]`/`- [x]` marker — the first inline child of the item's first paragraph, never the paragraph node's own (possibly stale) position. `undefined` when the item has no paragraph, or an empty one. */
+const firstParagraphContentOffset = (item: ListItem): number | undefined => {
+  const paragraph = item.children.find((c) => c.type === "paragraph")
+  return paragraph?.children[0]?.position?.start.offset
+}
+
+/**
+ * The text trailing the pointer token on the item's OWN source line — never
+ * a later, merely wrapped-onto-the-item's-first-paragraph line. This is what
+ * the second-pointer check must scope itself to: a below-pointer explanation
+ * that happens to open with a path (`./src/foo.ts is the caller`, on the
+ * NEXT physical line) is not the same thing as `- [ ] ./a.ts#1 ./b.ts#2` (two
+ * pointers crammed onto ONE line), even though both collapse to the same
+ * joined `restOfParagraph` string once whitespace is normalized.
+ */
+const hunkInlineSegment = (
+  content: string,
+  lines: readonly string[],
+  item: ListItem,
+  token: string,
+  sourceLine: number,
+): string => {
+  const contentOffset = firstParagraphContentOffset(item)
+  const contentPos =
+    contentOffset !== undefined ? toLspPositionFromOffset(content, contentOffset) : undefined
+  const sameLineRaw =
+    contentPos && contentPos.line === sourceLine
+      ? (lines[sourceLine] ?? "").slice(contentPos.character).trim()
+      : ""
+  return sameLineRaw.startsWith(token)
+    ? sameLineRaw.slice(token.length).trim().replace(NOTE_SEPARATOR_RE, "")
+    : ""
+}
+
+/** A hunk's composed note: the paragraph's own trailing text (same line and/or lazily wrapped, already joined and whitespace-collapsed by `sourceText`) first, then every further sibling block of the item — EXCLUDING a nested `list` (a nested hunk's own span) and a `footnoteDefinition` — each with its own leading dash separator stripped, joined by a single space. */
+const hunkNote = (
+  content: string,
+  item: ListItem,
+  paragraph: RootContent,
+  restOfParagraph: string,
+): string => {
+  const otherChildren = item.children.filter(
+    (c) => c !== paragraph && c.type !== "list" && c.type !== "footnoteDefinition",
+  )
+  const segments = [
+    restOfParagraph.replace(NOTE_SEPARATOR_RE, ""),
+    ...otherChildren.map((c) => sourceText(content, c).replace(NOTE_SEPARATOR_RE, "")),
+  ].filter((s) => s.length > 0)
+  return segments.join(" ").trim()
+}
+
+/** `nodes` with `NOTE_SEPARATOR_RE` stripped off its own FIRST text node's value, mirroring `hunkNote`'s identical string-side stripping — a no-op when `nodes` doesn't open with a `text` node. */
+const stripLeadingSeparatorInline = (nodes: readonly InlineNode[]): readonly InlineNode[] => {
+  const first = nodes[0]
+  if (first === undefined || first.kind !== "text") return nodes
+  return [
+    { kind: "text" as const, value: first.value.replace(NOTE_SEPARATOR_RE, "") },
+    ...nodes.slice(1),
+  ]
+}
+
+/** `paragraph`'s own inline content strictly AFTER raw source offset `afterOffset` — the structural counterpart of `restOfParagraph`'s string slice: keeps every child entirely past the cut, trims the one child that straddles it (only when it's plain `text`; a straddling non-text child is dropped, the one edge case a token followed immediately by styled text hits), and trims the result's own leading whitespace. `undefined`/`[]` for anything that isn't a real `paragraph`. */
+const trailingParagraphInline = (
+  content: string,
+  paragraph: RootContent,
+  afterOffset: number,
+): readonly InlineNode[] => {
+  if (paragraph.type !== "paragraph") return []
+  const kept = paragraph.children.flatMap((child) => {
+    const start = child.position?.start.offset
+    const end = child.position?.end.offset
+    if (start === undefined || end === undefined || end <= afterOffset) return []
+    if (start >= afterOffset) return [child]
+    if (child.type !== "text") return []
+    return [{ ...child, value: child.value.slice(afterOffset - start) }]
+  })
+  const projected = projectInline(kept, definitionsOf(content))
+  const first = projected[0]
+  if (first === undefined || first.kind !== "text") return projected
+  return [{ kind: "text" as const, value: first.value.trimStart() }, ...projected.slice(1)]
+}
+
+/** `note`'s own inline counterpart, mirroring `hunkNote` structurally: `paragraph`'s own trailing inline content (past the pointer token) first, then every further sibling block's own `nodeInline`-equivalent projection, joined and image-collapsed (R2). `tokenEndOffset` is the raw source offset right after the pointer token itself. */
+const hunkNoteInline = (
+  content: string,
+  item: ListItem,
+  paragraph: RootContent,
+  tokenEndOffset: number,
+): readonly InlineNode[] => {
+  const otherChildren = item.children.filter(
+    (c) => c !== paragraph && c.type !== "list" && c.type !== "footnoteDefinition",
+  )
+  const trailing = stripLeadingSeparatorInline(
+    trailingParagraphInline(content, paragraph, tokenEndOffset),
+  )
+  const runs = [
+    trailing,
+    ...otherChildren.map((c) => stripLeadingSeparatorInline(blockRunInline(content, [c]))),
+  ]
+  return collapseImages(joinInlineRuns(runs))
+}
+
+/** The last line of a hunk's OWN span — every non-`list` child's own end line, at most — excluding a nested hunk's span entirely, so a parent's span never swallows it (for "add a footnote" placement, or for matching which hunk a cursor sits on). */
+const hunkOwnEndLine = (item: ListItem, sourceLine: number): number => {
+  const nonListChildren = item.children.filter((c) => c.type !== "list")
+  if (nonListChildren.length === 0) return sourceLine
+  return Math.max(...nonListChildren.map((c) => toLspPosition(c.position!.end).line))
+}
+
+/** Builds one hunk's `ReviewFile` from its already-located pointer `token` and first `paragraph`. */
+const buildHunkFile = (
+  content: string,
+  item: ListItem,
+  paragraph: RootContent,
+  token: string,
+  sourceLine: number,
+): ReviewFile => {
+  const parsed = parsePointerToken(token)
+  const restOfParagraph = sourceText(content, paragraph).slice(token.length).trim()
+  const note = hunkNote(content, item, paragraph, restOfParagraph)
+  const contentOffset = firstParagraphContentOffset(item)
+  const noteInline =
+    contentOffset !== undefined
+      ? hunkNoteInline(content, item, paragraph, contentOffset + token.length)
+      : []
+  return {
+    path: parsed.path,
+    ...(parsed.line !== undefined ? { line: parsed.line } : {}),
+    ...(parsed.rangeEnd !== undefined ? { rangeEnd: parsed.rangeEnd } : {}),
+    checked: item.checked === true,
+    sourceLine,
+    endLine: hunkOwnEndLine(item, sourceLine),
+    ...(note.length > 0 ? { note, noteInline } : {}),
+  }
+}
+
+/** The pointer token's own `[start, end)` range on `sourceLine` — the token's first paragraph content offset, extended by its own length. `undefined` only when the item has no resolvable paragraph offset (kept total; never happens for a real hunk item). Shared by `hunkLinkFor`'s document-link range and the line-without-a-range finding's range so the two can never disagree about what the token spans. */
+const pointerTokenRange = (
+  content: string,
+  item: ListItem,
+  token: string,
+): SteeringFinding["range"] => {
+  const offset = firstParagraphContentOffset(item)
+  if (offset === undefined) return undefined
+  const start = toLspPositionFromOffset(content, offset)
+  const end = toLspPositionFromOffset(content, offset + token.length)
+  return { start, end }
+}
+
+/**
+ * The "line but no range" finding: a pointer whose token carries a bare
+ * `#<line>` (no `#<start>-<end>`) is a validation finding, never a silent
+ * whole-file pointer — the human chose enforcement over instruction. Absent
+ * for a range pointer (`file.rangeEnd` set) and for a `#`-less pointer
+ * (`file.line` absent entirely).
+ */
+const hunkLineWithoutRangeFinding = (
+  content: string,
+  item: ListItem,
+  token: string,
+  sourceLine: number,
+  title: string,
+  file: ReviewFile,
+): SteeringFinding | undefined => {
+  if (file.rangeEnd !== undefined || file.line === undefined) return undefined
+  const target = pointerDisplay(file)
+  const range = pointerTokenRange(content, item, token)
+  return {
+    message: `Chunk "${title}" hunk ${target} carries a line but no range — write "#${file.line}-<end>"`,
+    line: sourceLine,
+    ...(range ? { range } : {}),
+  }
+}
+
+/** The second pointer token's own `[start, end)` character range on `sourceLine` — found by searching forward from right after the FIRST token, so an earlier, coincidentally-matching substring can never be picked up. `undefined` only if the token somehow isn't found (never happens for a real match; kept total). */
+const secondTokenRange = (
+  lines: readonly string[],
+  sourceLine: number,
+  firstTokenEnd: number,
+  secondToken: string,
+): SteeringFinding["range"] => {
+  const raw = lines[sourceLine] ?? ""
+  const start = raw.indexOf(secondToken, firstTokenEnd)
+  if (start === -1) return undefined
+  return {
+    start: { line: sourceLine, character: start },
+    end: { line: sourceLine, character: start + secondToken.length },
+  }
+}
+
+/** The second-pointer finding for one hunk, or `undefined` when its inline (same-line) segment doesn't itself open with a pointer token. */
+const hunkSecondPointerFinding = (
+  content: string,
+  lines: readonly string[],
+  item: ListItem,
+  token: string,
+  sourceLine: number,
+  title: string,
+  file: ReviewFile,
+): SteeringFinding | undefined => {
+  const inlineSegment = hunkInlineSegment(content, lines, item, token, sourceLine)
+  const secondToken = inlineSegment.split(/\s+/)[0] ?? ""
+  if (!isPointerToken(secondToken)) return undefined
+  const contentOffset = firstParagraphContentOffset(item)
+  const contentPos =
+    contentOffset !== undefined ? toLspPositionFromOffset(content, contentOffset) : undefined
+  const firstTokenEnd = (contentPos?.character ?? 0) + token.length
+  const range = secondTokenRange(lines, sourceLine, firstTokenEnd, secondToken)
+  return secondPointerError(range, title, file, secondToken)
+}
+
+/** The first word of `item`'s first paragraph, whichever comes first. `undefined` when `item` has no paragraph, or an empty one. */
+const firstParagraphToken = (content: string, item: ListItem): string | undefined => {
+  const paragraph = item.children.find((c) => c.type === "paragraph")
+  if (!paragraph) return undefined
+  return sourceText(content, paragraph)
+    .split(/\s+/)
+    .find((w) => w.length > 0)
+}
+
+/** True when `item`'s first paragraph's first word is a pointer token — the single "is this list item a hunk pointer" test, shared by `parseHunk` and `parseChunkBody` so the parse and the description can never disagree about what counts as a pointer. */
+const hasPointerToken = (content: string, item: ListItem): boolean => {
+  const token = firstParagraphToken(content, item)
+  return token !== undefined && isPointerToken(token)
+}
+
+/** One pointer's parse result: its `ReviewFile`, plus the second-pointer finding when its inline (same-line) segment itself opens with a pointer token. `undefined` when `item`'s first paragraph's first word isn't a pointer token at all — a real task-list item whose content isn't a hunk pointer. */
+const parseHunk = (
+  content: string,
+  lines: readonly string[],
+  title: string,
+  item: ListItem,
+): { readonly file: ReviewFile; readonly errors: readonly SteeringFinding[] } | undefined => {
+  const paragraph = item.children.find((c) => c.type === "paragraph")
+  if (!paragraph || !item.position) return undefined
+  if (!hasPointerToken(content, item)) return undefined
+
+  const token = firstParagraphToken(content, item)!
+  const sourceLine = toLspPosition(item.position.start).line
+  const file = buildHunkFile(content, item, paragraph, token, sourceLine)
+  const errors = [
+    hunkSecondPointerFinding(content, lines, item, token, sourceLine, title, file),
+    hunkLineWithoutRangeFinding(content, item, token, sourceLine, title, file),
+  ].filter((e): e is SteeringFinding => e !== undefined)
+  return { file, errors }
+}
+
+/** 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,
+  lines: readonly string[],
+  title: string,
+  body: readonly RootContent[],
+): {
+  readonly description: string
+  readonly descriptionNodes: readonly SteeringViewNode[]
+  readonly descriptionInline: readonly InlineNode[]
+  readonly files: readonly ReviewFile[]
+  readonly errors: readonly SteeringFinding[]
+} => {
+  const firstPointerIndex = body.findIndex((n) =>
+    taskItems(n).some((item) => hasPointerToken(content, item)),
+  )
+  const leadingRun = firstPointerIndex === -1 ? body : body.slice(0, firstPointerIndex)
+  const descriptionNodes = blockNodesOfRun(content, leadingRun)
+  const descriptionInline = collapseImages(blockRunInline(content, leadingRun))
+  const description = leadingRun
+    .filter((n) => n.type !== "footnoteDefinition")
+    .map((n) => sourceText(content, n))
+    .join(" ")
+    .trim()
+
+  const files: ReviewFile[] = []
+  const errors: SteeringFinding[] = []
+  for (const item of body.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 }
+}
+
+/** One `##` chunk heading node with its raw body block nodes (up to the next `##`-or-shallower heading). */
+interface ChunkBlock extends HeadingBlock {
+  readonly headingLine: number
+}
+
+/** Splits the tree's top-level nodes into consecutive `##` chunk blocks — a `## ` line found only inside a fence never becomes a heading node at all, so it's never mistaken for a chunk. */
+const splitChunks = (tree: Root): readonly ChunkBlock[] => {
+  const blocks: ChunkBlock[] = []
+  let i = 0
+  while (i < tree.children.length) {
+    const node = tree.children[i]!
+    if (node.type !== "heading" || node.depth !== 2) {
+      i += 1
+      continue
+    }
+    const heading = node
+    const headingLine = toLspPosition(heading.position!.start).line
+    i += 1
+    const body: RootContent[] = []
+    while (i < tree.children.length) {
+      const next = tree.children[i]!
+      if (next.type === "heading" && next.depth <= 2) break
+      body.push(next)
+      i += 1
+    }
+    blocks.push({ heading, headingLine, body })
+  }
+  return blocks
+}
+
+const parseChangesets = (
+  tree: Root,
+  content: string,
+  lines: readonly string[],
+): { readonly changesets: readonly Changeset[]; readonly errors: readonly SteeringFinding[] } => {
+  const changesets: Changeset[] = []
+  const errors: SteeringFinding[] = []
+  for (const { heading, headingLine, body } of splitChunks(tree)) {
+    const title = headingText(content, heading)
+    const {
+      description,
+      descriptionNodes,
+      descriptionInline,
+      files,
+      errors: bodyErrors,
+    } = parseChunkBody(content, lines, title, body)
+    errors.push(...bodyErrors)
+    if (files.length === 0) {
+      errors.push({
+        message: `Chunk "${title}" has no file pointers`,
+        line: headingLine,
+        range: nodeRange(heading),
+      })
+    }
+    changesets.push({ title, description, descriptionNodes, descriptionInline, files, headingLine })
+  }
+  if (changesets.length === 0) errors.push({ message: "REVIEW.md has no '##' chunks" })
+  return { changesets, errors }
+}
+
+/**
+ * The missing-header finding: "the wrong first block node" — `tree.children[0]`
+ * — is the node this finding is ABOUT, so its range spans that node. An empty
+ * document (no first node at all) has no token to point at, so the finding
+ * stays positionless in that one case.
+ */
+const missingHeaderFinding = (tree: Root): SteeringFinding => {
+  const first = tree.children[0]
+  const message = "Missing or malformed '# Review: <hash>' header as the document's first line"
+  if (first === undefined || !first.position) return { message }
+  return { message, line: toLspPosition(first.position.start).line, range: nodeRange(first) }
+}
+
+/**
+ * Parses the review structure out of `content` (the raw text of
+ * `.gtd/REVIEW.md`). Total and side-effect-free: always returns a result,
+ * never throws — `parseMarkdown`'s `fromMarkdown` never does either.
+ * `findings` is non-empty exactly when the document violates the required
+ * structure — the caller decides what to do with that (`gtd validate` exits
+ * non-zero with them; the LSP publishes them as diagnostics). The one parse
+ * function: there is no second one routing around this return type.
+ */
+export const parseReviewDoc = (content: string): ReviewDoc => {
+  const tree = parseMarkdown(content)
+  const lines = content.split(/\r?\n/)
+  const shortHash = parseHeader(tree, content)
+  const fullHash = parseBaseComment(tree)
+  const { changesets, errors: chunkFindings } = parseChangesets(tree, content, lines)
+
+  const findings: SteeringFinding[] = [
+    ...(shortHash ? [] : [missingHeaderFinding(tree)]),
+    // A missing base comment has no offending token to point at — stays positionless.
+    ...(fullHash ? [] : [{ message: "Missing '<!-- base: <hash> -->' comment" }]),
+    ...chunkFindings,
+  ]
+
+  return {
+    ...(shortHash ? { shortHash } : {}),
+    ...(fullHash ? { fullHash } : {}),
+    changesets,
+    findings,
+  }
+}
+
+/** The character offset of a checked task item's own box character (`x`/`X`) — the first `[` at or after the item's own start offset, bounded by (before) its content's start offset, mirroring how a checkbox toggle resolves the same offset. `undefined` when the item carries no resolvable box (never happens for a real GFM task item, but kept total). */
+const checkboxOffset = (content: string, item: ListItem): number | undefined => {
+  if (!item.position) return undefined
+  const startOffset = item.position.start.offset
+  if (startOffset === undefined) return undefined
+  const boundOffset = firstParagraphContentOffset(item) ?? item.position.end.offset!
+  const bracketOffset = content.indexOf("[", startOffset)
+  if (bracketOffset === -1 || bracketOffset >= boundOffset) return undefined
+  return bracketOffset + 1
+}
+
+/** True when `item`'s first paragraph's first word is itself a hunk pointer token — the scope `reviewClearTicks` clears, so a `qa`-shaped checked option (never a pointer token) is untouched even if content in the wrong shape is fed to it. */
+const isHunkPointerItem = (content: string, item: ListItem): boolean => {
+  const paragraph = item.children.find((c) => c.type === "paragraph")
+  if (!paragraph) return false
+  const token = sourceText(content, paragraph)
+    .split(/\s+/)
+    .find((w) => w.length > 0)
+  return token !== undefined && isPointerToken(token)
+}
+
+/**
+ * Resets every checked HUNK POINTER back to `- [ ]` — ticks are read-progress,
+ * never sign-off. Scoped to real hunk pointers, never "every checked task
+ * item": that looser scope would strip a `qa` answer's tick if this ever ran
+ * against the wrong file.
+ *
+ * A byte-preserving OFFSET SPLICE, never a reserialization — `split`/`join`
+ * normalizes CRLF and would turn a tick-only round into a whole-file diff.
+ * Total and idempotent, and returns `content` ITSELF when there is nothing to
+ * clear, so a caller can skip the write and leave the mtime untouched.
+ */
+const reviewClearTicks = (content: string): string => {
+  const tree = parseMarkdown(content)
+  const offsets = taskItems(tree)
+    .filter((item) => item.checked === true && isHunkPointerItem(content, item))
+    .map((item) => checkboxOffset(content, item))
+    .filter((o): o is number => o !== undefined)
+    .sort((a, b) => a - b)
+  if (offsets.length === 0) return content
+
+  let result = ""
+  let cursor = 0
+  for (const offset of offsets) {
+    result += content.slice(cursor, offset) + " "
+    cursor = offset + 1
+  }
+  result += content.slice(cursor)
+  return result
+}
+
+/** Flips the `[ ]`/`[x]` box of the hunk pointer task item starting at `line`, preserving path/note text exactly. `undefined` when `line` isn't a real task item's own start line, or its content isn't a valid hunk pointer. */
+const toggleFilePointer = (content: string, line: number): SteeringEdit | undefined => {
+  const tree = parseMarkdown(content)
+  const item = taskItems(tree).find((it) => toLspPosition(it.position!.start).line === line)
+  if (!item?.position) return undefined
+
+  const paragraph = item.children.find((c) => c.type === "paragraph")
+  const firstWord = paragraph ? sourceText(content, paragraph).split(/\s+/)[0] : undefined
+  if (!firstWord || !isPointerToken(firstWord)) return undefined
+
+  const offset = checkboxOffset(content, item)
+  if (offset === undefined) return undefined
+  const position = toLspPositionFromOffset(content, offset)
+  return {
+    range: { start: position, end: { line: position.line, character: position.character + 1 } },
+    newText: item.checked === true ? " " : "x",
+  }
+}
+
+/** Every chunk heading's own line → its outline range's real end line (`blockEndLine`) — the node-boundary replacement for the old "next chunk's heading minus one" guess. */
+const chunkEndLines = (content: string): ReadonlyMap<number, number> => {
+  const tree = parseMarkdown(content)
+  const map = new Map<number, number>()
+  for (const block of splitChunks(tree)) map.set(block.headingLine, blockEndLine(block))
+  return map
+}
+
+/**
+ * Document outline for `.gtd/REVIEW.md`: the headlines of chunks (the
+ * user-facing "work packages") that still carry at least one unchecked hunk
+ * — the outline is the list of packages left to review — PLUS any chunk
+ * that carries at least one footnote, even when every hunk in it is ticked:
+ * `reviewOutline` otherwise drops a fully-checked chunk, which would make a
+ * human's own comment vanish the moment they tick the last box. A chunk's
+ * footnotes are `leaf: true` children; a chunk with none has no children.
+ */
+const reviewOutline = (content: string): readonly SteeringOutlineNode[] => {
+  const { changesets } = parseReviewDoc(content)
+  const { markers, definitions } = parseFootnotes(content)
+  const definitionByName = new Map(definitions.map((d) => [d.name, d.body]))
+  const lines = content.split(/\r?\n/)
+  const endLines = chunkEndLines(content)
+  const threads = threadOutlineNodes(content)
+  const nested = new Set<SteeringOutlineNode>()
+  const nodes = changesets
+    .map((chunk) => {
+      const start = chunk.headingLine
+      const end = Math.max(start, endLines.get(start) ?? start)
+      const checkedCount = chunk.files.filter((file) => file.checked).length
+      const chunkMarkers = markers.filter((m) => m.line >= start && m.line <= end)
+      const chunkThreads = threads
+        .filter((t) => t.markerLine !== undefined && t.markerLine >= start && t.markerLine <= end)
+        .map((t) => t.node)
+      chunkThreads.forEach((n) => nested.add(n))
+      const children = [
+        ...chunkMarkers.map((m) => footnoteLeaf(lines, definitionByName, m)),
+        ...chunkThreads,
+      ]
+      return {
+        name: `${chunk.title} (${checkedCount}/${chunk.files.length})`,
+        range: spanRange(lines, start, end),
+        selectionRange: lineRange(lines, start),
+        ...(children.length > 0 ? { children } : {}),
+        unchecked: checkedCount < chunk.files.length || chunkMarkers.length > 0,
+      }
+    })
+    .filter((node) => node.unchecked)
+    .map(({ unchecked: _unchecked, ...node }) => node)
+  return [...nodes, ...threads.map((t) => t.node).filter((n) => !nested.has(n))]
+}
+
+/**
+ * The target state a whole-chunk toggle drives every hunk to: `true` (check
+ * all) unless a strict majority are already checked, in which case `false`
+ * (uncheck all) — a chunk with no strict majority either way (including an
+ * even split) defaults to checking, so it's never a meaningless no-op on a
+ * chunk that's already uniform.
+ */
+const chunkToggleTarget = (checkedCount: number, total: number): boolean =>
+  checkedCount * 2 <= total
+
+/** Toggles every hunk in the chunk headed at `headingLine` to a single target state (`chunkToggleTarget`) — one edit per hunk not already at the target state, none when the chunk is already uniform. */
+const toggleChunkEdits = (content: string, headingLine: number): SteeringEdit[] => {
+  const { changesets } = parseReviewDoc(content)
+  const chunk = changesets.find((c) => c.headingLine === headingLine)
+  if (!chunk || chunk.files.length === 0) return []
+  const checkedCount = chunk.files.filter((file) => file.checked).length
+  const target = chunkToggleTarget(checkedCount, chunk.files.length)
+  const edits: SteeringEdit[] = []
+  for (const file of chunk.files) {
+    if (file.checked === target) continue
+    const edit = toggleFilePointer(content, file.sourceLine)
+    if (edit) edits.push(edit)
+  }
+  return edits
+}
+
+/**
+ * The block a footnote lands after when "add a footnote" fires with the
+ * cursor at `cursorLine`: the containing hunk's own span (`ReviewFile.endLine`
+ * — never a nested hunk's own span, since a parent hunk's `endLine` excludes
+ * it) when the cursor sits in one, otherwise the surrounding top-level block
+ * node's own end line (`blockNodeAt`, from `MarkdownTree.ts`).
+ */
+const footnoteBlockEnd = (content: string, tree: Root, cursorLine: number): number => {
+  const { changesets } = parseReviewDoc(content)
+  const hunk = changesets
+    .flatMap((chunk) => chunk.files)
+    .find((file) => cursorLine >= file.sourceLine && cursorLine <= file.endLine)
+  if (hunk) return hunk.endLine
+  const block = blockNodeAt(tree, cursorLine)
+  return block?.position ? toLspPosition(block.position.end).line : cursorLine
+}
+
+/**
+ * Actions for `.gtd/REVIEW.md`: "check/uncheck this hunk" when `range` sits
+ * on a hunk line, "check/uncheck all hunks" when `range` sits anywhere in a
+ * chunk (heading or body), and "add a footnote" LAST, after every hunk/chunk
+ * action, everywhere EXCEPT inside an existing marker's span or on an
+ * existing definition's own line — planting a new marker/definition there
+ * would corrupt the footnote already written.
+ */
+const reviewActions: SteeringFormat["actions"] = (content, range) => {
+  const { changesets } = parseReviewDoc(content)
+  const tree = parseMarkdown(content)
+  const lines = content.split(/\r?\n/)
+  const cursorLine = range.start.line
+  const actions: Array<{ readonly title: string; readonly edits: readonly SteeringEdit[] }> = [
+    ...threadReplyActions(content, range.start),
+  ]
+
+  // fallow-ignore-next-line complexity
+  changesets.forEach((chunk, i) => {
+    const hunk = chunk.files.find(
+      (file) => cursorLine >= file.sourceLine && cursorLine <= file.endLine,
+    )
+    if (hunk) {
+      const edit = toggleFilePointer(content, hunk.sourceLine)
+      if (edit) {
+        actions.push({
+          title: hunk.checked ? "gtd: uncheck this hunk" : "gtd: check this hunk",
+          edits: [edit],
+        })
+      }
+    }
+
+    const chunkEnd = Math.max(
+      chunk.headingLine,
+      (changesets[i + 1]?.headingLine ?? lines.length) - 1,
+    )
+    if (chunk.files.length > 0 && cursorLine >= chunk.headingLine && cursorLine <= chunkEnd) {
+      const edits = toggleChunkEdits(content, chunk.headingLine)
+      if (edits.length > 0) {
+        const checkedCount = chunk.files.filter((file) => file.checked).length
+        const willCheck = chunkToggleTarget(checkedCount, chunk.files.length)
+        actions.push({
+          title: willCheck
+            ? `gtd: check all hunks in "${chunk.title}"`
+            : `gtd: uncheck all hunks in "${chunk.title}"`,
+          edits,
+        })
+      }
+    }
+  })
+
+  if (!isOnExistingFootnote(content, range.start)) {
+    actions.push({
+      title: FOOTNOTE_ACTION_TITLE,
+      edits: footnoteAdditionEdits(
+        content,
+        range.start,
+        footnoteBlockEnd(content, tree, cursorLine),
+      ),
+    })
+  }
+
+  return actions
+}
+
+/** The file a hunk pointer points into. A pointer's `#line` is 1-based and maps to 0-based here; a bare `./path` lands at 0. Path RESOLUTION against a repo root is the LSP's concern — this returns the raw `./`-relative text. */
+const hunkPointerAt = (
+  content: string,
+  line: number,
+): { path: string; line: number } | undefined => {
+  const { changesets } = parseReviewDoc(content)
+  const hunk = changesets.flatMap((chunk) => chunk.files).find((file) => file.sourceLine === line)
+  if (!hunk) return undefined
+  return { path: hunk.path, line: hunk.line !== undefined ? hunk.line - 1 : 0 }
+}
+
+/**
+ * `.gtd/REVIEW.md`'s `pointerAt`: footnotes resolve FIRST (they're
+ * column-scoped, the hunk jump is line-scoped — a marker sitting in a hunk's
+ * inline note would otherwise be shadowed by it), the hunk-pointer jump to
+ * another file second. An orphan marker/definition resolves (via
+ * `footnotePointerAt`) to "handled, but no pointer" — so it returns
+ * `undefined` here too, rather than falling through to the hunk jump.
+ */
+const reviewPointerAt: SteeringFormat["pointerAt"] = (content, position) => {
+  const footnote = footnotePointerAt(content, position)
+  if (footnote) return footnote.pointer
+  return hunkPointerAt(content, position.line)
+}
+
+/**
+ * One hunk's document link, or `undefined` when `item`'s first paragraph's
+ * first word isn't a pointer token — mirrors `parseHunk`'s own recognition so
+ * the two can never disagree about what counts as a hunk. The token's range
+ * is derived directly from its own source offset (`firstParagraphContentOffset`),
+ * never by calling `pointerAt` per line — that path is one call per line and
+ * cannot yield the token's own range in the first place.
+ */
+const hunkLinkFor = (content: string, item: ListItem): SteeringLink | undefined => {
+  const paragraph = item.children.find((c) => c.type === "paragraph")
+  if (!paragraph || !item.position) return undefined
+  const token = sourceText(content, paragraph)
+    .split(/\s+/)
+    .find((w) => w.length > 0)
+  if (!token || !isPointerToken(token)) return undefined
+  const range = pointerTokenRange(content, item, token)
+  if (!range) return undefined
+  const parsed = parsePointerToken(token)
+  return {
+    range,
+    path: parsed.path,
+    line: parsed.line !== undefined ? parsed.line - 1 : 0,
+  }
+}
+
+/** Every hunk-pointer document link in `content`, at any nesting depth. */
+const reviewDocumentLinks = (content: string): readonly SteeringLink[] => {
+  const tree = parseMarkdown(content)
+  const links: SteeringLink[] = []
+  for (const block of splitChunks(tree)) {
+    for (const item of block.body.flatMap((n) => taskItems(n))) {
+      const link = hunkLinkFor(content, item)
+      if (link) links.push(link)
+    }
+  }
+  return links
+}
+
+/** Every chunk as a container with its file pointers as children, from ONE parse — never one parse per chunk. Pointers nested at any depth are already flattened into `chunk.files`. A chunk's footnote sits at the end of its heading line; a hunk's at its source line. */
+const reviewView = (content: string): SteeringView => {
+  const { shortHash, changesets } = parseReviewDoc(content)
+  const noteAt = noteLookup(content)
+  return {
+    ...(shortHash ? { header: shortHash } : {}),
+    nodes: changesets.map((chunk, chunkIndex) => ({
+      title: chunk.title,
+      detail: chunk.description,
+      detailInline: chunk.descriptionInline,
+      body: chunk.descriptionNodes,
+      anchor: { kind: "chunk", index: chunkIndex },
+      ...noteAt(chunk.headingLine),
+      children: chunk.files.map((file, index) => ({
+        title: pointerDisplay(file),
+        path: file.path,
+        ...(file.line !== undefined ? { line: file.line } : {}),
+        ...(file.rangeEnd !== undefined ? { endLine: file.rangeEnd } : {}),
+        checked: file.checked,
+        ...(file.note !== undefined
+          ? { detail: file.note, detailInline: file.noteInline ?? [] }
+          : {}),
+        ...noteAt(file.sourceLine),
+        anchor: { kind: "hunk", chunkIndex, index },
+      })),
+    })),
+  }
+}
+
+/** Resolves a `chunk` anchor: attaches at the end of the chunk's own heading line, the definition landing after the chunk's whole block (`chunkEndLines`). `undefined` for a stale `index`. */
+const resolveChunkAnchor = (
+  content: string,
+  lines: readonly string[],
+  changesets: readonly Changeset[],
+  index: number,
+): FootnoteAnchor | undefined => {
+  const chunk = changesets[index]
+  if (!chunk) return undefined
+  const end = Math.max(
+    chunk.headingLine,
+    chunkEndLines(content).get(chunk.headingLine) ?? chunk.headingLine,
+  )
+  return {
+    line: chunk.headingLine,
+    endCharacter: (lines[chunk.headingLine] ?? "").length,
+    blockEndLine: end,
+    key: `chunk:${chunk.headingLine}`,
+  }
+}
+
+/** Resolves a `hunk` anchor: attaches at the end of the hunk's own source line, the definition landing after the hunk's whole span (`file.endLine`). `undefined` for a stale `chunkIndex`/`index`. */
+const resolveHunkAnchor = (
+  lines: readonly string[],
+  changesets: readonly Changeset[],
+  chunkIndex: number,
+  index: number,
+): FootnoteAnchor | undefined => {
+  const file = changesets[chunkIndex]?.files[index]
+  if (!file) return undefined
+  return {
+    line: file.sourceLine,
+    endCharacter: (lines[file.sourceLine] ?? "").length,
+    blockEndLine: file.endLine,
+    key: `hunk:${file.sourceLine}`,
+  }
+}
+
+/** Resolves a `paragraph` anchor: attaches at the end of `line`'s own text, the definition landing after that line's containing top-level block node. `undefined` when `line` isn't inside a real block. */
+const resolveParagraphAnchor = (
+  tree: Root,
+  lines: readonly string[],
+  line: number,
+): FootnoteAnchor | undefined => {
+  const block = blockNodeAt(tree, line)
+  if (!block?.position) return undefined
+  return {
+    line,
+    endCharacter: (lines[line] ?? "").length,
+    blockEndLine: toLspPosition(block.position.end).line,
+    key: `paragraph:${line}`,
+  }
+}
+
+/**
+ * Resolves a `chunk`/`hunk`/`paragraph` `SteeringAnchor` against `content`
+ * into the low-level `FootnoteAnchor` `Footnotes.ts#footnoteAttachEdits`
+ * wants — `undefined` for a `question`/`option` anchor (not this format's own
+ * kind) or an index/line that no longer resolves, so a stale anchor is
+ * REJECTED rather than silently attaching to the wrong node.
+ */
+const resolveReviewAnchor = (
+  content: string,
+  tree: Root,
+  lines: readonly string[],
+  changesets: readonly Changeset[],
+  anchor: SteeringAnchor,
+): FootnoteAnchor | undefined => {
+  switch (anchor.kind) {
+    case "chunk":
+      return resolveChunkAnchor(content, lines, changesets, anchor.index)
+    case "hunk":
+      return resolveHunkAnchor(lines, changesets, anchor.chunkIndex, anchor.index)
+    case "paragraph":
+      return resolveParagraphAnchor(tree, lines, anchor.line)
+    default:
+      return undefined
+  }
+}
+
+/** `review`-mode's `annotate`: resolves `anchor` then delegates the two-edit mechanics (`text` carried through verbatim as the new definition's body) to `Footnotes.ts#footnoteAttachEdits`. */
+const reviewAnnotate = (
+  content: string,
+  anchor: SteeringAnchor,
+  text: string,
+): SteeringAnnotateResult => {
+  const { changesets } = parseReviewDoc(content)
+  const tree = parseMarkdown(content)
+  const lines = content.split(/\r?\n/)
+  const resolved = resolveReviewAnchor(content, tree, lines, changesets, anchor)
+  if (!resolved) return { ok: false, reason: "anchor-not-found" }
+  const result = footnoteAttachEdits(content, resolved, text)
+  if (!result.ok) return result
+  return { ok: true, edits: result.edits }
+}
+
+/** Edits that set every one of `files`' ticks to `checked` — one edit per file not already at that state, none when the set is already uniform. Shared by `reviewApply`'s `hunk` (single-element) and `chunk` (every hunk beneath it) cases, so the two can never diverge on how a tick is actually set. */
+const setFileTickEdits = (
+  content: string,
+  files: readonly ReviewFile[],
+  checked: boolean,
+): SteeringEdit[] => {
+  const edits: SteeringEdit[] = []
+  for (const file of files) {
+    if (file.checked === checked) continue
+    const edit = toggleFilePointer(content, file.sourceLine)
+    if (edit) edits.push(edit)
+  }
+  return edits
+}
+
+/** A `hunk` anchor sets one tick; a `chunk` anchor sets every hunk beneath it to the SAME target state — never `toggleChunkEdits`'s majority-flip heuristic, since the caller already knows the state it wants. */
+const reviewApply: SteeringFormat["apply"] = (content, anchor, opts) => {
+  const { changesets } = parseReviewDoc(content)
+  const checked = opts.checked ?? true
+  if (anchor.kind === "hunk") {
+    const file = changesets[anchor.chunkIndex]?.files[anchor.index]
+    if (!file) return { ok: false, reason: "anchor-not-found" }
+    return { ok: true, edits: setFileTickEdits(content, [file], checked) }
+  }
+  if (anchor.kind === "chunk") {
+    const chunk = changesets[anchor.index]
+    if (!chunk) return { ok: false, reason: "anchor-not-found" }
+    return { ok: true, edits: setFileTickEdits(content, chunk.files, checked) }
+  }
+  return { ok: false, reason: "anchor-not-found" }
+}
+
+/** The `review` format: `.gtd/REVIEW.md`'s in-process format — validation, outline, code actions, footnote + hunk `pointerAt`/`documentLinks`, and a hunk-pointer-scoped `clearTicks` (never "every checked task item" — see `reviewClearTicks`). */
+export const reviewDescriptor: SteeringFormat = {
+  sample: REVIEW_SAMPLE,
+  validate: (content) => [...parseReviewDoc(content).findings, ...parseFootnotes(content).findings],
+  outline: reviewOutline,
+  actions: reviewActions,
+  pointerAt: reviewPointerAt,
+  documentLinks: reviewDocumentLinks,
+  view: reviewView,
+  annotate: reviewAnnotate,
+  apply: reviewApply,
+  clearTicks: reviewClearTicks,
+  openThreads: openThreadsOf,
+}
+
+/** One thing the human added to a review document since the baseline. */
+export interface ReviewNote {
+  readonly id: string
+  readonly kind: "pointer" | "footnote" | "chunk"
+  /** The chunk title plus the pointer (path + range), or the footnote's marker line. */
+  readonly anchor: string
+  /** The reviewer's text at this spot; empty when the note is new. */
+  readonly before: string
+  /** The human's text. */
+  readonly text: string
+}
+
+const pointerLabel = (f: ReviewFile): string =>
+  `${f.path}${f.line === undefined ? "" : `#${f.line}${f.rangeEnd === undefined ? "" : `-${f.rangeEnd}`}`}`
+
+type Found = { line: number; note: Omit<ReviewNote, "id"> }
+
+const chunkNote = (chunk: Changeset, prior: Changeset | undefined): Found[] =>
+  chunk.description === (prior?.description ?? "")
+    ? []
+    : [
+        {
+          line: chunk.headingLine,
+          note: {
+            kind: "chunk",
+            anchor: chunk.title,
+            before: prior?.description ?? "",
+            text: chunk.description,
+          },
+        },
+      ]
+
+const pointerNotes = (chunk: Changeset, prior: Changeset | undefined): Found[] =>
+  chunk.files.flatMap((file): Found[] => {
+    const label = pointerLabel(file)
+    const was = prior?.files.find((f) => pointerLabel(f) === label)
+    if (file.note === undefined || file.note === (was?.note ?? "")) return []
+    return [
+      {
+        line: file.sourceLine,
+        note: {
+          kind: "pointer",
+          anchor: `${chunk.title} ${label}`,
+          before: was?.note ?? "",
+          text: file.note,
+        },
+      },
+    ]
+  })
+
+const footnoteNotes = (before: string, after: string): Found[] => {
+  const lines = after.split(/\r?\n/)
+  const threadNames = new Set(parseThreads(after).map((t) => t.name))
+  const knownNames = new Set(parseFootnotes(before).definitions.map((d) => d.name))
+  const parsed = parseFootnotes(after)
+  const markerOf = new Map(parsed.markers.map((m) => [m.name, m.line]))
+  return parsed.definitions
+    .filter((def) => !threadNames.has(def.name) && !knownNames.has(def.name))
+    .map((def) => {
+      const at = markerOf.get(def.name)
+      return {
+        line: def.line,
+        note: {
+          kind: "footnote",
+          anchor: at === undefined ? `[^${def.name}]` : (lines[at] ?? "").trim(),
+          before: "",
+          text: def.body,
+        },
+      }
+    })
+}
+
+/**
+ * Every note the human added to `after` relative to `before`, in document
+ * order: pointer notes, one-shot footnotes (never `H:`/`A:` threads) and
+ * chunk prose.
+ */
+export const reviewNotes = (before: string, after: string): readonly ReviewNote[] => {
+  if (before === after) return []
+  const oldChunks = new Map(parseReviewDoc(before).changesets.map((c) => [c.title, c]))
+  const found = [
+    ...parseReviewDoc(after).changesets.flatMap((chunk) => {
+      const prior = oldChunks.get(chunk.title)
+      return [...chunkNote(chunk, prior), ...pointerNotes(chunk, prior)]
+    }),
+    ...footnoteNotes(before, after),
+  ]
+  return found.sort((a, b) => a.line - b.line).map((f, i) => ({ id: `note-${i + 1}`, ...f.note }))
+}
+
+/** Pointer notes the reviewer opened with `Risk:`, in document order — the ones the workflow fixes before the human gate. */
+export const reviewRisks = (
+  content: string,
+): readonly { id: string; anchor: string; text: string }[] =>
+  parseReviewDoc(content)
+    .changesets.flatMap((chunk) =>
+      chunk.files.flatMap((file) =>
+        file.note?.startsWith("Risk:")
+          ? [{ anchor: `${chunk.title} ${pointerLabel(file)}`, text: file.note }]
+          : [],
+      ),
+    )
+    .map((r, i) => ({ id: `risk-${i + 1}`, ...r }))