@pmelab/gtd 23.2.0 → 24.1.0

package/src/replay/Trailers.test.ts

@@ -0,0 +1,117 @@
+import { describe, expect, it } from "vitest"
+import { formatCommitMessage, parseCommitMessage, parseSubject } from "./Trailers.js"
+
+describe("the commit-message codec", () => {
+  it("round-trips a step commit's subject and trailers", () => {
+    const message = formatCommitMessage({
+      actor: "judge",
+      from: "health.judge",
+      to: "health.escalate",
+      step: { name: "health.judge", occurrence: 2 },
+      cost: { cost: 1450, model: "smart" },
+      judge: [{ id: "verdict", answer: "identical", p: 0.9 }],
+    })
+    expect(message.split("\n")[0]).toBe("gtd(judge): health.judge → health.escalate")
+    const parsed = parseCommitMessage(message)
+    expect(parsed.parsed).toEqual({ actor: "judge", from: "health.judge", to: "health.escalate" })
+    expect(parsed.step).toEqual({ name: "health.judge", occurrence: 2 })
+    expect(parsed.cost).toEqual([{ cost: 1450, model: "smart" }])
+    expect(parsed.judge).toEqual([{ id: "verdict", answer: "identical", p: 0.9 }])
+  })
+
+  it("collapses a self-loop to the bare subject and keeps entry trailers", () => {
+    const message = formatCommitMessage({
+      actor: "human",
+      to: "review-gate.check",
+      reviewBase: "abc",
+      vars: { reviewBase: "main=x" },
+    })
+    const parsed = parseCommitMessage(message)
+    expect(parsed.subject).toBe("gtd(human): review-gate.check")
+    expect(parsed.step).toBeUndefined()
+    expect(parsed.reviewBase).toBe("abc")
+    expect(parsed.vars).toEqual({ reviewBase: "main=x" })
+  })
+
+  it("round-trips the workflow trailer, written after Gtd-Step and before Gtd-Review-Base", () => {
+    const message = formatCommitMessage({
+      actor: "human",
+      to: "fix-precheck",
+      workflow: "fix",
+      reviewBase: "abc",
+    })
+    expect(message).toBe(
+      "gtd(human): fix-precheck\n\nGtd-Workflow: fix\nGtd-Review-Base: abc\nGtd-Format: 1",
+    )
+    expect(parseCommitMessage(message).workflow).toBe("fix")
+    expect(parseCommitMessage("gtd(human): fix-precheck").workflow).toBeUndefined()
+  })
+
+  it("writes Gtd-Var trailers sorted by name, whatever the insertion order", () => {
+    const one = formatCommitMessage({ actor: "human", to: "x", vars: { b: "2", a: "1", c: "" } })
+    const two = formatCommitMessage({ actor: "human", to: "x", vars: { c: "", a: "1", b: "2" } })
+    expect(one).toBe(two)
+    expect(one).toBe("gtd(human): x\n\nGtd-Var: a=1\nGtd-Var: b=2\nGtd-Var: c=\nGtd-Format: 1")
+    expect(parseCommitMessage(one).vars).toEqual({ a: "1", b: "2", c: "" })
+  })
+
+  it("writes Gtd-Config trailers sorted by path, after Gtd-Var, and reads paths with spaces back", () => {
+    const message = formatCommitMessage({
+      actor: "human",
+      to: "x",
+      vars: { a: "1" },
+      config: { "lib/my flow.ts": "0123456789abcdef", "gtd.config.ts": "deadbeefdeadbeef" },
+    })
+    expect(message).toBe(
+      "gtd(human): x\n\nGtd-Var: a=1\nGtd-Config: deadbeefdeadbeef gtd.config.ts\nGtd-Config: 0123456789abcdef lib/my flow.ts\nGtd-Format: 1",
+    )
+    expect(parseCommitMessage(message).config).toEqual({
+      "gtd.config.ts": "deadbeefdeadbeef",
+      "lib/my flow.ts": "0123456789abcdef",
+    })
+  })
+
+  it("round-trips a Gtd-Config path that git or the trailer syntax would alter", () => {
+    const config = {
+      " lead.ts": "0123456789abcdef",
+      "trail.ts ": "0123456789abcdef",
+      '"q.ts': "0123456789abcdef",
+    }
+    const message = formatCommitMessage({ actor: "human", to: "x", config })
+    expect(message).toContain('Gtd-Config: 0123456789abcdef " lead.ts"')
+    expect(parseCommitMessage(message).config).toEqual(config)
+  })
+
+  it("ignores a Gtd-Config trailer without a 16-digit hex hash, without a path, or with a control character in its path", () => {
+    const read = (value: string) =>
+      parseCommitMessage(`gtd(human): x\n\nGtd-Config: ${value}`).config
+    expect(read("zzzzzzzzzzzzzzzz gtd.config.ts")).toEqual({})
+    expect(read("deadbeef gtd.config.ts")).toEqual({})
+    expect(read("deadbeefdeadbeef")).toEqual({})
+    expect(read("deadbeefdeadbeef a\x1b]0;x\x07.ts")).toEqual({})
+    expect(read('deadbeefdeadbeef "a\\u001b.ts"')).toEqual({})
+  })
+
+  it("writes Gtd-Format last on every message, even one with no other trailer", () => {
+    const message = formatCommitMessage({ actor: "agent", to: "building" })
+    expect(message).toBe("gtd(agent): building\n\nGtd-Format: 1")
+    expect(parseCommitMessage(message).format).toBe(1)
+  })
+
+  it("reads a message without Gtd-Format as format 1, and an explicit one as written", () => {
+    expect(parseCommitMessage("gtd(agent): a → b\n\nGtd-Step: a#1").format).toBe(1)
+    expect(parseCommitMessage("gtd(agent): a → b\n\nGtd-Format: 2").format).toBe(2)
+    expect(parseCommitMessage("gtd(agent): a → b\n\nGtd-Format: two").format).toBe(1)
+  })
+
+  it("skips a malformed trailer instead of failing", () => {
+    const parsed = parseCommitMessage("gtd(judge): a → b\n\nGtd-Judge: {not json\nGtd-Step: nope")
+    expect(parsed.judge).toEqual([])
+    expect(parsed.step).toBeUndefined()
+  })
+
+  it("parses only gtd subjects", () => {
+    expect(parseSubject("feat: add calculator")).toBeUndefined()
+    expect(parseSubject("gtd(agent): fix")).toEqual({ actor: "agent", to: "fix" })
+  })
+})

package/src/replay/Trailers.ts

@@ -0,0 +1,213 @@
+// The commit-message codec: the `gtd(<actor>): <from> → <to>` subject plus
+// the `Gtd-*` trailers a step commit carries. A malformed trailer (never
+// written by gtd) is skipped, not fatal — a corrupt line must never make every
+// command unusable.
+
+import { HISTORY_FORMAT } from "./Format.js"
+
+const TRANSITION_SEP = " → "
+
+export interface ParsedSubject {
+  readonly actor: string
+  readonly to: string
+  readonly from?: string
+}
+
+const SUBJECT_RE = /^gtd\(([^()]+)\): (.+)$/
+
+/** `from` equal to `to` (or absent) collapses to the bare `gtd(<actor>): <to>` form. */
+export const formatSubject = (actor: string, to: string, from?: string): string =>
+  from === undefined || from === to
+    ? `gtd(${actor}): ${to}`
+    : `gtd(${actor}): ${from}${TRANSITION_SEP}${to}`
+
+export const parseSubject = (subject: string): ParsedSubject | undefined => {
+  const match = SUBJECT_RE.exec(subject.trim())
+  const actor = match?.[1]
+  const rest = match?.[2]
+  if (actor === undefined || rest === undefined) return undefined
+  const sep = rest.lastIndexOf(TRANSITION_SEP)
+  if (sep === -1) return { actor, to: rest }
+  const from = rest.slice(0, sep)
+  const to = rest.slice(sep + TRANSITION_SEP.length)
+  if (from === "" || to === "") return undefined
+  return { actor, to, from }
+}
+
+export interface StepId {
+  readonly name: string
+  readonly occurrence: number
+}
+
+export const formatStepId = (id: StepId): string => `${id.name}#${id.occurrence}`
+
+const STEP_ID_RE = /^(.+)#([1-9][0-9]*)$/
+
+const parseStepId = (raw: string): StepId | undefined => {
+  const match = STEP_ID_RE.exec(raw.trim())
+  if (match === null) return undefined
+  return { name: match[1]!, occurrence: Number(match[2]) }
+}
+
+export interface JudgeVerdict {
+  readonly id: string
+  readonly answer: string | number | boolean
+  readonly p: number
+}
+
+export interface CostEntry {
+  readonly cost: number
+  readonly model: string | undefined
+}
+
+export interface CommitMessage {
+  readonly subject: string
+  readonly parsed: ParsedSubject | undefined
+  readonly step: StepId | undefined
+  /** Written only on a process's opening commit. */
+  readonly workflow: string | undefined
+  readonly judge: readonly JudgeVerdict[]
+  readonly vars: Readonly<Record<string, string>>
+  /** Written only on a process's first commit. */
+  readonly config: Readonly<Record<string, string>>
+  readonly reviewBase: string | undefined
+  readonly cost: readonly CostEntry[]
+  readonly format: number
+}
+
+const isVerdict = (value: unknown): value is JudgeVerdict => {
+  if (typeof value !== "object" || value === null) return false
+  const v = value as Record<string, unknown>
+  return (
+    typeof v.id === "string" &&
+    ["string", "number", "boolean"].includes(typeof v.answer) &&
+    typeof v.p === "number"
+  )
+}
+
+const parseJson = (raw: string): unknown => {
+  try {
+    return JSON.parse(raw) as unknown
+  } catch {
+    return undefined
+  }
+}
+
+const TRAILER_RE = /^(Gtd-[A-Za-z-]+):[ \t]*(.*?)[ \t]*$/gm
+const COST_RE = /^([0-9]+(?:\.[0-9]+)?)(?:[ \t]+(.+))?$/
+const VAR_RE = /^([^=\s]+)=(.*)$/
+const CONFIG_RE = /^([0-9a-f]{16}) (.+)$/
+// A path git's message cleanup or the trailer syntax would alter travels as a
+// JSON string. A control character is refused on read: history written by
+// someone else must never put escape sequences on a terminal.
+// eslint-disable-next-line no-control-regex -- the control range IS the point
+const CONTROL_CHARACTER = /[\x00-\x1f\x7f-\x9f]/
+const encodePath = (path: string): string =>
+  path.trim() !== path || path.startsWith('"') || CONTROL_CHARACTER.test(path)
+    ? JSON.stringify(path)
+    : path
+const decodePath = (raw: string): string | undefined => {
+  const path = raw.startsWith('"') ? parseJson(raw) : raw
+  return typeof path === "string" && path !== "" && !CONTROL_CHARACTER.test(path) ? path : undefined
+}
+const FORMAT_RE = /^[1-9][0-9]*$/
+
+interface Trailers {
+  step: StepId | undefined
+  workflow: string | undefined
+  reviewBase: string | undefined
+  readonly judge: JudgeVerdict[]
+  readonly vars: Record<string, string>
+  readonly config: Record<string, string>
+  readonly cost: CostEntry[]
+  format: number | undefined
+}
+
+const TRAILER_READERS: Readonly<Record<string, (value: string, into: Trailers) => void>> = {
+  "Gtd-Step": (value, into) => {
+    into.step ??= parseStepId(value)
+  },
+  "Gtd-Workflow": (value, into) => {
+    if (value !== "") into.workflow ??= value
+  },
+  "Gtd-Judge": (value, into) => {
+    const parsed = parseJson(value)
+    if (isVerdict(parsed)) into.judge.push(parsed)
+  },
+  "Gtd-Var": (value, into) => {
+    const kv = VAR_RE.exec(value)
+    if (kv !== null) into.vars[kv[1]!] = kv[2]!
+  },
+  "Gtd-Config": (value, into) => {
+    const entry = CONFIG_RE.exec(value)
+    const path = entry === null ? undefined : decodePath(entry[2]!)
+    if (path !== undefined) into.config[path] = entry![1]!
+  },
+  "Gtd-Review-Base": (value, into) => {
+    into.reviewBase ??= value.split(/\s/)[0]
+  },
+  "Gtd-Format": (value, into) => {
+    if (FORMAT_RE.test(value)) into.format ??= Number(value)
+  },
+  "Gtd-Cost": (value, into) => {
+    const c = COST_RE.exec(value)
+    if (c !== null) into.cost.push({ cost: Number(c[1]), model: c[2]?.trim() || undefined })
+  },
+}
+
+export const parseCommitMessage = (message: string): CommitMessage => {
+  const newline = message.indexOf("\n")
+  const subject = (newline === -1 ? message : message.slice(0, newline)).trim()
+  const trailers: Trailers = {
+    step: undefined,
+    workflow: undefined,
+    reviewBase: undefined,
+    judge: [],
+    vars: {},
+    config: {},
+    cost: [],
+    format: undefined,
+  }
+  if (newline !== -1) {
+    for (const match of message.slice(newline).matchAll(TRAILER_RE)) {
+      TRAILER_READERS[match[1]!]?.(match[2]!, trailers)
+    }
+  }
+  return { subject, parsed: parseSubject(subject), ...trailers, format: trailers.format ?? 1 }
+}
+
+export interface CommitSpec {
+  readonly actor: string
+  readonly to: string
+  readonly from?: string
+  readonly step?: StepId
+  readonly workflow?: string
+  readonly reviewBase?: string
+  readonly vars?: Readonly<Record<string, string>>
+  readonly config?: Readonly<Record<string, string>>
+  readonly cost?: { readonly cost: number; readonly model?: string }
+  readonly judge?: readonly JudgeVerdict[]
+}
+
+const sortedEntries = (record: Readonly<Record<string, string>> = {}): [string, string][] =>
+  Object.entries(record).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+
+/** Trailer order is fixed so the same spec always yields the same bytes. */
+export const formatCommitMessage = (spec: CommitSpec): string => {
+  const lines: string[] = []
+  if (spec.step !== undefined) lines.push(`Gtd-Step: ${formatStepId(spec.step)}`)
+  if (spec.workflow !== undefined) lines.push(`Gtd-Workflow: ${spec.workflow}`)
+  if (spec.reviewBase !== undefined) lines.push(`Gtd-Review-Base: ${spec.reviewBase}`)
+  for (const [name, value] of sortedEntries(spec.vars)) lines.push(`Gtd-Var: ${name}=${value}`)
+  for (const [path, hash] of sortedEntries(spec.config))
+    lines.push(`Gtd-Config: ${hash} ${encodePath(path)}`)
+  if (spec.cost !== undefined) {
+    lines.push(
+      `Gtd-Cost: ${spec.cost.cost}${spec.cost.model !== undefined ? ` ${spec.cost.model}` : ""}`,
+    )
+  }
+  for (const verdict of spec.judge ?? []) lines.push(`Gtd-Judge: ${JSON.stringify(verdict)}`)
+  lines.push(`Gtd-Format: ${HISTORY_FORMAT}`)
+  const subject = formatSubject(spec.actor, spec.to, spec.from)
+  return `${subject}\n\n${lines.join("\n")}`
+}

package/src/replay/Tree.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from "vitest"
+import { diffTrees, type TreeView } from "./Tree.js"
+
+const tree = (files: Record<string, { id?: string; content: string }>): TreeView => ({
+  paths: () => Object.keys(files).sort(),
+  read: (path) => files[path]?.content,
+  id: (path) => files[path]?.id,
+})
+
+describe("diffTrees", () => {
+  it("compares blob ids where both sides have one, whatever the bytes read", () => {
+    const before = tree({ "a.txt": { id: "1", content: "one\n" } })
+    const after = tree({ "a.txt": { id: "1", content: "one\r\n" } })
+    expect(diffTrees(before, after).modified).toEqual([])
+  })
+
+  it("falls back to contents for a path one side has no id for", () => {
+    const before = tree({
+      "a.txt": { id: "1", content: "one\n" },
+      "b.txt": { id: "2", content: "b" },
+    })
+    const after = tree({ "a.txt": { content: "one\n" }, "b.txt": { content: "changed" } })
+    expect(diffTrees(before, after).modified).toEqual(["b.txt"])
+  })
+})

package/src/replay/Tree.ts

@@ -0,0 +1,45 @@
+/**
+ * One committed (or about-to-be-committed) tree, read synchronously: flow code
+ * calls helpers between two awaits and cannot wait on IO. A git-backed view
+ * reads objects on demand; `id` lets `diffTrees` compare blob ids instead of
+ * contents, and a path whose id is `undefined` is compared by contents.
+ */
+export interface TreeView {
+  readonly paths: () => readonly string[]
+  readonly read: (path: string) => string | undefined
+  readonly id?: (path: string) => string | undefined
+}
+
+export const treeFromRecord = (files: Readonly<Record<string, string>>): TreeView => ({
+  paths: () => Object.keys(files).sort(),
+  read: (path) => (Object.hasOwn(files, path) ? files[path] : undefined),
+})
+
+export interface TreeDiff {
+  readonly added: readonly string[]
+  readonly modified: readonly string[]
+  readonly deleted: readonly string[]
+}
+
+export const diffTrees = (before: TreeView, after: TreeView): TreeDiff => {
+  // Blob ids only compare against blob ids; otherwise fall back to contents.
+  const same = (path: string): boolean => {
+    const a = before.id?.(path)
+    const b = after.id?.(path)
+    return a !== undefined && b !== undefined ? a === b : before.read(path) === after.read(path)
+  }
+  const beforePaths = new Set(before.paths())
+  const afterPaths = new Set(after.paths())
+  const added: string[] = []
+  const modified: string[] = []
+  const deleted: string[] = []
+  for (const path of afterPaths) {
+    if (!beforePaths.has(path)) added.push(path)
+    else if (!same(path)) modified.push(path)
+  }
+  for (const path of beforePaths) if (!afterPaths.has(path)) deleted.push(path)
+  return { added: added.sort(), modified: modified.sort(), deleted: deleted.sort() }
+}
+
+export const isEmptyDiff = (diff: TreeDiff): boolean =>
+  diff.added.length === 0 && diff.modified.length === 0 && diff.deleted.length === 0

package/src/replay/index.ts

@@ -0,0 +1,11 @@
+export { replay, type EpisodeCommit, type ReachedStep, type ReplayOutcome } from "./Replay.js"
+export { treeFromRecord, type TreeView } from "./Tree.js"
+export {
+  formatCommitMessage,
+  formatSubject,
+  parseCommitMessage,
+  type CommitSpec,
+  type JudgeVerdict,
+} from "./Trailers.js"
+export { accessShapeFault, foldAccess } from "./Access.js"
+export { formatFault } from "./Format.js"

package/src/steering/Blocks.fixture.ts

@@ -0,0 +1,6 @@
+// Test-support for `Blocks.test.ts`: `blockNodesOf` takes an already-parsed
+// tree, but a test only has raw markdown source — re-exporting the shared
+// parser here (rather than `Blocks.test.ts` reaching into `MarkdownTree.ts`
+// directly) keeps the boundary rule "a test reaches a neighbour only through
+// its own fixture or the boundary's index.ts" satisfied.
+export { parseMarkdown } from "./MarkdownTree.js"

package/src/steering/Blocks.test.ts

@@ -0,0 +1,167 @@
+import { describe, expect, it } from "vitest"
+import { blockNodesOf, blockRunInline } from "./Blocks.js"
+import { parseMarkdown } from "./Blocks.fixture.js"
+
+describe("blockNodesOf — T1 blast-radius: blockTitle is byte-identical for a list item containing ~~strike~~ and a bare URL", () => {
+  it("a list item's own title keeps the literal markers, unaffected by wiring the two new GFM extensions", () => {
+    const content = ["- A ~~gone~~ item https://example.com/x", ""].join("\n")
+    const tree = parseMarkdown(content)
+    const nodes = blockNodesOf(content, tree)
+    expect(nodes[0]?.title).toBe("A ~~gone~~ item https://example.com/x")
+    expect(nodes[0]?.block?.items?.[0]?.text).toBe("A ~~gone~~ item https://example.com/x")
+  })
+})
+
+describe("blockRunInline — spec-feedback regression: a nested list item's own text is not dropped", () => {
+  it("a nested item's own run joins the flattened detailInline path, unlike a hand-picked top-level-only walk", () => {
+    const content = ["- outer", "  - inner deep text", ""].join("\n")
+    const tree = parseMarkdown(content)
+    const inline = blockRunInline(content, tree.children)
+    const joined = inline.map((n) => ("value" in n ? n.value : "")).join("")
+    expect(joined).toBe("outer inner deep text")
+  })
+
+  it("still recurses at three levels deep, in document order", () => {
+    const content = ["- a", "  - b", "    - c", ""].join("\n")
+    const tree = parseMarkdown(content)
+    const inline = blockRunInline(content, tree.children)
+    const joined = inline.map((n) => ("value" in n ? n.value : "")).join("")
+    expect(joined).toBe("a b c")
+  })
+
+  it("a nested item's own text still stays OUT of its parent's structural BlockListItem.inline — only the flattened detailInline path recurses", () => {
+    const content = ["- outer", "  - inner", ""].join("\n")
+    const tree = parseMarkdown(content)
+    const nodes = blockNodesOf(content, tree)
+    const topItem = nodes[0]?.block?.items?.[0]
+    expect(topItem?.inline).toEqual([{ kind: "text", value: "outer" }])
+    expect(topItem?.items).toEqual([{ text: "inner", inline: [{ kind: "text", value: "inner" }] }])
+  })
+})
+
+describe("blockNodesOf — default walk, no skip predicates", () => {
+  it("yields every top-level block, in document order, when called with no options", () => {
+    const content = [
+      "# Heading",
+      "",
+      "- Item one",
+      "  - Nested item",
+      "",
+      "```",
+      "line one",
+      "line two",
+      "```",
+      "",
+      "> A blockquote.",
+      "",
+      "Paragraph one.",
+      "",
+      "Paragraph two.",
+      "",
+    ].join("\n")
+    const tree = parseMarkdown(content)
+    const nodes = blockNodesOf(content, tree)
+    expect(nodes.map((n) => n.block?.kind)).toEqual([
+      "heading",
+      "list",
+      "code",
+      "blockquote",
+      "paragraph",
+      "paragraph",
+    ])
+  })
+
+  it("excludes a footnoteDefinition node unconditionally", () => {
+    const content = ["Paragraph with a marker[^fn1].", "", "[^fn1]: The note body.", ""].join("\n")
+    const tree = parseMarkdown(content)
+    const nodes = blockNodesOf(content, tree)
+    expect(nodes.map((n) => n.block?.kind)).toEqual(["paragraph"])
+  })
+
+  it("carries a {kind:'paragraph', line} anchor for every node, at its own start line", () => {
+    const content = ["# Heading", "", "Paragraph.", ""].join("\n")
+    const tree = parseMarkdown(content)
+    const nodes = blockNodesOf(content, tree)
+    expect(nodes.map((n) => n.anchor)).toEqual([
+      { kind: "paragraph", line: 0 },
+      { kind: "paragraph", line: 2 },
+    ])
+  })
+
+  it("surfaces a footnote marker anchored at a block's own start line as that block's own note", () => {
+    const content = ["# Heading[^fn1]", "", "[^fn1]: A note on the heading.", ""].join("\n")
+    const tree = parseMarkdown(content)
+    const nodes = blockNodesOf(content, tree)
+    expect(nodes[0]?.note).toBe("A note on the heading.")
+  })
+
+  it("strips the '> ' continuation marker from a soft-broken blockquote's title and block.text", () => {
+    const content = ["> quoted line", "> more", ""].join("\n")
+    const tree = parseMarkdown(content)
+    const nodes = blockNodesOf(content, tree)
+    expect(nodes[0]?.title).not.toContain(">")
+    expect(nodes[0]?.block).toMatchObject({ kind: "blockquote", text: "quoted line more" })
+  })
+
+  it("keeps a two-paragraph blockquote's title unchanged (blank '>' line between paragraphs)", () => {
+    const content = ["> First line.", ">", "> Second para.", ""].join("\n")
+    const tree = parseMarkdown(content)
+    const nodes = blockNodesOf(content, tree)
+    expect(nodes[0]?.title).toBe("First line. Second para.")
+  })
+
+  it("keeps a literal '>' typed mid-prose inside a blockquote", () => {
+    const content = ["> a > b", ""].join("\n")
+    const tree = parseMarkdown(content)
+    const nodes = blockNodesOf(content, tree)
+    expect(nodes[0]?.title).toBe("a > b")
+  })
+
+  it("keeps an inline link's [label](url) syntax intact across a multi-line blockquote", () => {
+    const content = ["> see [label](url)", "> more text", ""].join("\n")
+    const tree = parseMarkdown(content)
+    const nodes = blockNodesOf(content, tree)
+    expect(nodes[0]?.title).toBe("see [label](url) more text")
+  })
+
+  it("keeps a line-leading '>' inside a list item's own fenced code block — the blockquote strip is scoped to blockquotes only", () => {
+    const content = ["- item", "", "  ```", "  a", "  > b", "  ```", ""].join("\n")
+    const tree = parseMarkdown(content)
+    const nodes = blockNodesOf(content, tree)
+    expect(nodes[0]?.block).toMatchObject({ kind: "list", items: [{ text: "item ``` a > b ```" }] })
+  })
+})
+
+describe("blockNodesOf — caller-supplied skip predicates", () => {
+  it("skipNode excludes a top-level node the caller identifies by content", () => {
+    const content = ["# Skip me", "", "Paragraph.", ""].join("\n")
+    const tree = parseMarkdown(content)
+    const nodes = blockNodesOf(content, tree, {
+      skipNode: (_content, node) => node.type === "heading",
+    })
+    expect(nodes.map((n) => n.block?.kind)).toEqual(["paragraph"])
+  })
+
+  it("skipLine excludes a top-level node by its own start line", () => {
+    const content = ["# Heading", "", "Paragraph.", ""].join("\n")
+    const tree = parseMarkdown(content)
+    const nodes = blockNodesOf(content, tree, { skipLine: (line) => line === 0 })
+    expect(nodes.map((n) => n.block?.kind)).toEqual(["paragraph"])
+  })
+})
+
+describe("blockNodesOf — block.text", () => {
+  it("omits block.text entirely for heading/list/paragraph", () => {
+    const content = ["# A heading", "", "Plain paragraph.", ""].join("\n")
+    const tree = parseMarkdown(content)
+    const nodes = blockNodesOf(content, tree)
+    expect(nodes.map((n) => n.block?.text)).toEqual([undefined, undefined])
+  })
+
+  it("omits block entirely for a thematicBreak — unchanged from qa/review's own behaviour", () => {
+    const content = ["Above.", "", "---", "", "Below.", ""].join("\n")
+    const tree = parseMarkdown(content)
+    const nodes = blockNodesOf(content, tree)
+    expect(nodes.map((n) => n.block?.kind)).toEqual(["paragraph", undefined, "paragraph"])
+  })
+})