@pmelab/gtd 24.0.0 → 24.2.0

package/src/steering/qa.test.ts

@@ -0,0 +1,2160 @@
+import { describe, expect, it } from "vitest"
+import { FOOTNOTE_ACTION_TITLE, steeringFormatFor, unansweredQuestions, viewOf } from "./index.js"
+import { FREE_TEXT_PLACEHOLDER, isAnswered, parseOpenQuestions } from "./qa.js"
+import { getParseCount } from "./index.js"
+
+const qa = steeringFormatFor("qa")!
+
+const doc = (lines: readonly string[]): string => lines.join("\n")
+
+describe("qa — structure (validate)", () => {
+  it("an empty document has no questions and no findings", () => {
+    expect(qa.validate("")).toEqual([])
+    expect(unansweredQuestions(qa, "")).toEqual([])
+  })
+
+  it("an Open Questions section present but empty is valid", () => {
+    expect(qa.validate(doc(["# Plan", "", "## Open Questions", ""]))).toEqual([])
+  })
+
+  it("a question with a free-form body (no options) validates clean", () => {
+    const content = doc([
+      "# Plan",
+      "",
+      "## Open Questions",
+      "",
+      "### Which operations?",
+      "",
+      "add and subtract.",
+      "",
+    ])
+    expect(qa.validate(content)).toEqual([])
+    expect(unansweredQuestions(qa, content)).toEqual([
+      expect.objectContaining({ question: "Which operations?" }),
+    ])
+  })
+
+  it("stops a questions section at the next H2 heading — a later '### ' under a different section is not a question", () => {
+    const content = doc([
+      "## Open Questions",
+      "",
+      "### Which operations?",
+      "",
+      "- [ ] A",
+      "- [ ] B",
+      "",
+      "## Implementation Notes",
+      "",
+      "### Not a question",
+      "",
+      "This should be ignored entirely.",
+      "",
+    ])
+    expect(unansweredQuestions(qa, content)).toHaveLength(1)
+  })
+
+  it("keeps a well-formed question while also collecting a bare-heading finding elsewhere in the same doc", () => {
+    const content = doc([
+      "## Open Questions",
+      "",
+      "###",
+      "",
+      "### Real question?",
+      "",
+      "- [ ] A",
+      "- [ ] B",
+      "",
+    ])
+    const findings = qa.validate(content)
+    expect(findings).toHaveLength(1)
+    expect(unansweredQuestions(qa, content)).toEqual([
+      expect.objectContaining({ question: "Real question?" }),
+    ])
+  })
+
+  describe("checkbox options", () => {
+    const q = (lines: readonly string[]): string =>
+      ["## Open Questions", "", "### Which API?", ...lines, ""].join("\n")
+
+    it("parses two agent options plus a trailing free-text slot, none ticked = unanswered", () => {
+      const result = parseOpenQuestions(
+        q(["", "- [ ] REST", "- [ ] GraphQL", `- [ ] ${FREE_TEXT_PLACEHOLDER}`]),
+      )
+      const [question] = result.questions
+      expect(question!.options).toEqual([
+        { checked: false, text: "REST", freeText: false, sourceLine: 4, endLine: 4, body: [] },
+        { checked: false, text: "GraphQL", freeText: false, sourceLine: 5, endLine: 5, body: [] },
+        { checked: false, text: "", freeText: true, sourceLine: 6, endLine: 6, body: [] },
+      ])
+      expect(question!.answered).toBe(false)
+    })
+
+    it("is answered when exactly one agent option is ticked", () => {
+      const result = parseOpenQuestions(
+        q(["", "- [ ] REST", "- [x] GraphQL", `- [ ] ${FREE_TEXT_PLACEHOLDER}`]),
+      )
+      expect(result.questions[0]!.answered).toBe(true)
+    })
+
+    it("is unanswered when two options are ticked (ambiguous)", () => {
+      const result = parseOpenQuestions(
+        q(["", "- [x] REST", "- [x] GraphQL", `- [ ] ${FREE_TEXT_PLACEHOLDER}`]),
+      )
+      expect(result.questions[0]!.answered).toBe(false)
+    })
+
+    it("is answered when the free-text slot is ticked WITH text, capturing that text", () => {
+      const result = parseOpenQuestions(q(["", "- [ ] REST", "- [ ] GraphQL", "- [x] use tRPC"]))
+      const question = result.questions[0]!
+      expect(question.answered).toBe(true)
+      const chosen = question.options.find((o) => o.checked)!
+      expect(chosen).toEqual({
+        checked: true,
+        text: "use tRPC",
+        freeText: true,
+        sourceLine: 6,
+        endLine: 6,
+        body: [],
+      })
+    })
+
+    it("is unanswered when the free-text slot is ticked but still the placeholder", () => {
+      const result = parseOpenQuestions(
+        q(["", "- [ ] REST", "- [ ] GraphQL", `- [x] ${FREE_TEXT_PLACEHOLDER}`]),
+      )
+      const question = result.questions[0]!
+      expect(question.answered).toBe(false)
+      expect(question.options[2]).toEqual({
+        checked: true,
+        text: "",
+        freeText: true,
+        sourceLine: 6,
+        endLine: 6,
+        body: [],
+      })
+    })
+
+    it("normalizes the placeholder case-insensitively, regardless of the constant's OWN casing — never assumes FREE_TEXT_PLACEHOLDER itself is already lowercase", () => {
+      const result = parseOpenQuestions(
+        q(["", "- [ ] REST", "- [ ] GraphQL", `- [x] ${FREE_TEXT_PLACEHOLDER.toUpperCase()}`]),
+      )
+      const question = result.questions[0]!
+      expect(question.answered).toBe(false)
+      expect(question.options[2]!.text).toBe("")
+    })
+
+    it("accepts `* [X]` bullet/upper-case tick syntax", () => {
+      const result = parseOpenQuestions(q(["", "* [ ] REST", "* [X] GraphQL"]))
+      expect(result.questions[0]!.answered).toBe(true)
+    })
+
+    it("only normalizes the placeholder on the LAST option", () => {
+      // A non-last option literally equal to the placeholder is NOT the free-text
+      // slot, so it is not normalized to "".
+      const result = parseOpenQuestions(
+        q(["", `- [ ] ${FREE_TEXT_PLACEHOLDER}`, "- [ ] real free text"]),
+      )
+      const [first, last] = result.questions[0]!.options
+      expect(first).toEqual({
+        checked: false,
+        text: FREE_TEXT_PLACEHOLDER,
+        freeText: false,
+        sourceLine: 4,
+        endLine: 4,
+        body: [],
+      })
+      expect(last!.freeText).toBe(true)
+    })
+
+    it("carries no options for an answered-section question even if it has checkbox-looking lines", () => {
+      const content = ["## Answered Questions", "", "### Which API?", "", "Use tRPC.", ""].join(
+        "\n",
+      )
+      const question = parseOpenQuestions(content).questions[0]!
+      expect(question.options).toEqual([])
+      expect(question.answered).toBe(false)
+    })
+  })
+
+  describe("option line span (endLine)", () => {
+    const q = (lines: readonly string[]): string =>
+      ["## Open Questions", "", "### Which API?", ...lines, ""].join("\n")
+
+    it("a single-line option's endLine equals its own sourceLine", () => {
+      const result = parseOpenQuestions(q(["", "- [ ] REST", "- [ ] GraphQL"]))
+      const [rest, graphql] = result.questions[0]!.options
+      expect(rest).toMatchObject({ sourceLine: 4, endLine: 4 })
+      expect(graphql).toMatchObject({ sourceLine: 5, endLine: 5 })
+    })
+
+    it("an indented wrap over two continuation lines extends endLine to the last one", () => {
+      const result = parseOpenQuestions(
+        q(["", "- [ ] REST, specifically", "  a JSON:API-flavored", "  REST endpoint set"]),
+      )
+      const [option] = result.questions[0]!.options
+      expect(option).toMatchObject({ sourceLine: 4, endLine: 6 })
+    })
+
+    it("an unindented (lazy) wrap gets the same span as an indented one", () => {
+      const result = parseOpenQuestions(
+        q(["", "- [ ] REST, specifically", "a JSON:API-flavored", "REST endpoint set"]),
+      )
+      const [option] = result.questions[0]!.options
+      expect(option).toMatchObject({ sourceLine: 4, endLine: 6 })
+    })
+
+    it("the next checkbox line ends the previous option's span", () => {
+      const result = parseOpenQuestions(
+        q(["", "- [ ] REST, specifically", "a wrapped line", "- [ ] GraphQL"]),
+      )
+      const [rest, graphql] = result.questions[0]!.options
+      expect(rest).toMatchObject({ sourceLine: 4, endLine: 5 })
+      expect(graphql).toMatchObject({ sourceLine: 6, endLine: 6 })
+    })
+
+    it("a blank line ends the span, so trailing prose after it stays out of the last option's span", () => {
+      const result = parseOpenQuestions(
+        q(["", "- [ ] _your answer_", "a wrapped answer", "", "some trailing prose"]),
+      )
+      const [option] = result.questions[0]!.options
+      expect(option).toMatchObject({ sourceLine: 4, endLine: 5 })
+    })
+
+    it("the last body line ends the span at the block end, with no overrun past the next heading", () => {
+      const content = [
+        "## Open Questions",
+        "",
+        "### Which API?",
+        "",
+        "- [ ] REST",
+        "a wrapped line",
+        "another wrapped line",
+      ].join("\n")
+      const result = parseOpenQuestions(content)
+      const [option] = result.questions[0]!.options
+      expect(option).toMatchObject({ sourceLine: 4, endLine: 6 })
+    })
+
+    it("answered/text include a wrapped ticked free-text option's whole paragraph span, not the checkbox line alone", () => {
+      const result = parseOpenQuestions(
+        q(["", "- [ ] REST", "- [x] use tRPC", "a wrapped continuation of the answer"]),
+      )
+      const question = result.questions[0]!
+      expect(question.answered).toBe(true)
+      const chosen = question.options.find((o) => o.checked)!
+      expect(chosen).toMatchObject({
+        text: "use tRPC a wrapped continuation of the answer",
+        sourceLine: 5,
+        endLine: 6,
+      })
+    })
+
+    it("a bare marker with no text on its OWN line, whose text starts on the next (indented) line, reads that continuation's text — where it read '' and refused before", () => {
+      const result = parseOpenQuestions(q(["", "- [ ]", "  text here", "- [ ] _your answer_"]))
+      const [option] = result.questions[0]!.options
+      expect(option).toMatchObject({ text: "text here", sourceLine: 4, endLine: 5 })
+    })
+
+    it("a ticked free-text option answered only on its continuation line reads that text and counts as ANSWERED — the paragraph span covers the whole wrap, not just the marker's own line", () => {
+      const result = parseOpenQuestions(q(["", "- [ ] REST", "- [x]", "  my own answer"]))
+      const question = result.questions[0]!
+      const chosen = question.options.find((o) => o.checked)!
+      expect(chosen).toMatchObject({ text: "my own answer", freeText: true })
+      expect(question.answered).toBe(true)
+    })
+  })
+
+  it("a '####' heading inside the section is not treated as a question block at all", () => {
+    const content = doc([
+      "## Open Questions",
+      "",
+      "#### Not a question depth",
+      "",
+      "### Real question?",
+      "",
+      "- [ ] A",
+      "- [ ] B",
+      "",
+    ])
+    expect(unansweredQuestions(qa, content)).toEqual([
+      expect.objectContaining({ question: "Real question?" }),
+    ])
+  })
+})
+
+describe("qa — answer completeness (unansweredQuestions)", () => {
+  const q = (lines: readonly string[]): string =>
+    doc(["## Open Questions", "", "### Which API?", ...lines, ""])
+
+  it("two options, none ticked, is unanswered", () => {
+    const content = q(["", "- [ ] REST", "- [ ] GraphQL", "- [ ] _your answer_"])
+    expect(unansweredQuestions(qa, content)).toHaveLength(1)
+  })
+
+  it("exactly one ticked option is answered", () => {
+    const content = q(["", "- [ ] REST", "- [x] GraphQL", "- [ ] _your answer_"])
+    expect(unansweredQuestions(qa, content)).toEqual([])
+  })
+
+  it("two ticked options (ambiguous) is unanswered", () => {
+    const content = q(["", "- [x] REST", "- [x] GraphQL", "- [ ] _your answer_"])
+    expect(unansweredQuestions(qa, content)).toHaveLength(1)
+  })
+
+  it("the free-text slot ticked WITH real text is answered", () => {
+    const content = q(["", "- [ ] REST", "- [ ] GraphQL", "- [x] use tRPC"])
+    expect(unansweredQuestions(qa, content)).toEqual([])
+  })
+
+  it("the free-text slot ticked but left as the unfilled placeholder is unanswered", () => {
+    const content = q(["", "- [ ] REST", "- [ ] GraphQL", "- [x] _your answer_"])
+    expect(unansweredQuestions(qa, content)).toHaveLength(1)
+  })
+
+  it("accepts '* [X]' bullet/upper-case tick syntax", () => {
+    const content = q(["", "* [ ] REST", "* [X] GraphQL"])
+    expect(unansweredQuestions(qa, content)).toEqual([])
+  })
+
+  it("only the LAST option is ever the free-text slot — a non-last option literally equal to the placeholder is not normalized", () => {
+    const content = q(["", "- [ ] _your answer_", "- [x] real free text"])
+    expect(unansweredQuestions(qa, content)).toEqual([])
+  })
+
+  it("an answered-section question carries no options even with checkbox-looking lines, and is never 'unanswered'", () => {
+    const content = doc(["## Answered Questions", "", "### Which API?", "", "Use tRPC.", ""])
+    expect(unansweredQuestions(qa, content)).toEqual([])
+  })
+
+  it("a bare marker with no text on its own line, text on an indented continuation, stays unanswered when unticked", () => {
+    const content = q(["", "- [ ]", "  text here", "- [ ] _your answer_"])
+    expect(unansweredQuestions(qa, content)).toHaveLength(1)
+  })
+
+  it("a ticked free-text option answered only on its continuation line reads that text and counts as answered — the paragraph span covers the whole wrap", () => {
+    const content = q(["", "- [ ] REST", "- [x]", "  my own answer"])
+    expect(unansweredQuestions(qa, content)).toEqual([])
+  })
+
+  it("returns [] once every open question is answered", () => {
+    const content = doc([
+      "## Open Questions",
+      "",
+      "### A?",
+      "",
+      "- [x] Yes",
+      "- [ ] No",
+      "",
+      "### B?",
+      "",
+      "- [ ] Yes",
+      "- [x] No",
+      "",
+    ])
+    expect(unansweredQuestions(qa, content)).toEqual([])
+  })
+
+  it("lists every unanswered open question with its heading line", () => {
+    const content = doc([
+      "Plan.",
+      "",
+      "## Open Questions",
+      "",
+      "### Which backend?",
+      "",
+      "- [ ] SQLite",
+      "- [ ] Postgres",
+      "",
+    ])
+    expect(unansweredQuestions(qa, content)).toEqual([
+      expect.objectContaining({ question: "Which backend?", headingLine: 4 }),
+    ])
+  })
+})
+
+describe("qa — section ordering", () => {
+  it("reports a finding when a '##' section precedes '## Open Questions'", () => {
+    const content = doc([
+      "## Implementation Notes",
+      "",
+      "some notes.",
+      "",
+      "## Open Questions",
+      "",
+      "### Which operations?",
+      "",
+      "add and subtract.",
+      "",
+    ])
+    expect(qa.validate(content).map((f) => f.message)).toEqual([
+      "A '##' section appears before '## Open Questions', which must come first",
+    ])
+  })
+
+  it("reports a finding when a '##' section follows '## Answered Questions'", () => {
+    const content = doc([
+      "## Answered Questions",
+      "",
+      "### Already resolved?",
+      "",
+      "Yes.",
+      "",
+      "## Implementation Notes",
+      "",
+      "some notes.",
+      "",
+    ])
+    expect(qa.validate(content).map((f) => f.message)).toEqual([
+      "A '##' section appears after '## Answered Questions', which must come last",
+    ])
+  })
+
+  it("reports no ordering finding with only '## Open Questions' present", () => {
+    expect(
+      qa.validate(doc(["## Open Questions", "", "### Which operations?", "", "add.", ""])),
+    ).toEqual([])
+  })
+
+  it("reports at most one 'before' finding even with multiple sections preceding Open Questions", () => {
+    const content = doc([
+      "## Implementation Notes",
+      "",
+      "some notes.",
+      "",
+      "## Constraints",
+      "",
+      "some constraints.",
+      "",
+      "## Open Questions",
+      "",
+      "### Which operations?",
+      "",
+      "add and subtract.",
+      "",
+    ])
+    expect(qa.validate(content).map((f) => f.message)).toEqual([
+      "A '##' section appears before '## Open Questions', which must come first",
+    ])
+  })
+
+  it("reports both findings when '## Answered Questions' comes before '## Open Questions'", () => {
+    const content = doc([
+      "## Answered Questions",
+      "",
+      "### Already resolved?",
+      "",
+      "Yes.",
+      "",
+      "## Open Questions",
+      "",
+      "### Which operations?",
+      "",
+      "add and subtract.",
+      "",
+    ])
+    expect(qa.validate(content).map((f) => f.message)).toEqual([
+      "A '##' section appears before '## Open Questions', which must come first",
+      "A '##' section appears after '## Answered Questions', which must come last",
+    ])
+  })
+
+  it("reports no ordering finding with only '## Answered Questions' present", () => {
+    const content = doc(["## Answered Questions", "", "### Already resolved?", "", "Yes.", ""])
+    expect(qa.validate(content)).toEqual([])
+  })
+
+  it("reports no ordering finding when neither section is present", () => {
+    expect(qa.validate(doc(["## Implementation Notes", "", "some notes.", ""]))).toEqual([])
+  })
+
+  it("reports no finding for lead prose and a level-1 title above '## Open Questions'", () => {
+    const content = doc([
+      "# Plan",
+      "",
+      "Some lead prose describing the plan.",
+      "",
+      "## Open Questions",
+      "",
+      "### Which operations?",
+      "",
+      "add and subtract.",
+      "",
+    ])
+    expect(qa.validate(content)).toEqual([])
+  })
+})
+
+describe("qa — outline (option span, endLine, footnotes, ordering)", () => {
+  it("marks a prose (option-less) open question as unanswered, and answered-section questions as answered", () => {
+    const content = doc([
+      "## Open Questions",
+      "",
+      "### Free-form?",
+      "",
+      "some prose.",
+      "",
+      "## Answered Questions",
+      "",
+      "### Resolved?",
+      "",
+      "yes.",
+      "",
+    ])
+    const outline = viewOf(qa, content).outline
+    expect(outline[0]!.name).toContain("[unanswered]")
+    expect(outline[1]!.name).toContain("[answered]")
+  })
+
+  it("marks an open question with exactly one ticked option as answered, listing options as children", () => {
+    const content = doc([
+      "## Open Questions",
+      "",
+      "### Which API?",
+      "",
+      "- [x] REST",
+      "- [ ] GraphQL",
+      "",
+    ])
+    const outline = viewOf(qa, content).outline
+    expect(outline[0]!.name).toContain("[answered]")
+    expect(outline[0]!.children).toHaveLength(2)
+  })
+
+  it("returns no nodes when there is no Open Questions section", () => {
+    expect(viewOf(qa, "# Plan\n\nBuild a thing.\n").outline).toEqual([])
+  })
+
+  it("omits 'children' entirely for a question with no options", () => {
+    const content = doc(["## Open Questions", "", "### Free-form?", "", "prose.", ""])
+    expect(viewOf(qa, content).outline[0]).not.toHaveProperty("children")
+  })
+
+  it("ends the last question's range at its own last block, not the trailing blank run", () => {
+    const content = doc(["## Open Questions", "", "### Q1?", "", "- [ ] A", "- [ ] B", "", "", ""])
+    const node = viewOf(qa, content).outline[0]!
+    expect(node.range.end.line).toBe(5)
+  })
+
+  it("ends an interior question's range at its own last block too, not at the next heading minus one", () => {
+    const content = doc([
+      "## Open Questions",
+      "",
+      "### Q1?",
+      "",
+      "- [ ] A",
+      "- [ ] B",
+      "",
+      "",
+      "### Q2?",
+      "",
+      "- [ ] C",
+      "- [ ] D",
+      "",
+    ])
+    const node = viewOf(qa, content).outline[0]!
+    expect(node.range.end.line).toBe(5)
+  })
+
+  it("clamps the last question's range.end.line to the true last line when the fixture has no trailing newline", () => {
+    const content = "## Open Questions\n\n### Q1?\n\n- [ ] A"
+    const node = viewOf(qa, content).outline[0]!
+    expect(node.range.end.line).toBe(4)
+  })
+
+  it("places a footnote leaf under the option whose span holds its marker", () => {
+    const content = doc([
+      "## Open Questions",
+      "",
+      "### Q1?",
+      "",
+      "- [ ] A[^fn1]",
+      "- [ ] B",
+      "",
+      "[^fn1]:",
+      "    Detail about option A that is longer than eighty characters for wrapping.",
+      "",
+    ])
+    const option = viewOf(qa, content).outline[0]!.children![0]!
+    expect(option.children).toHaveLength(1)
+  })
+
+  it("places a footnote leaf under the question when its marker is in question-body prose", () => {
+    const content = doc([
+      "## Open Questions",
+      "",
+      "### Q1?",
+      "",
+      "prose with a marker[^fn1].",
+      "",
+      "- [ ] A",
+      "- [ ] B",
+      "",
+      "[^fn1]:",
+      "    Detail that is longer than eighty characters so it wraps across lines nicely.",
+      "",
+    ])
+    const question = viewOf(qa, content).outline[0]!
+    expect(question.children!.some((c) => c.name.includes("fn1") === false)).toBe(true)
+    // the option children (leaf, no footnote) plus one footnote child on the question itself
+    expect(question.children).toHaveLength(3)
+  })
+
+  it("does not set leaf:true on an option node that carries footnote children", () => {
+    const content = doc([
+      "## Open Questions",
+      "",
+      "### Q1?",
+      "",
+      "- [ ] A[^fn1]",
+      "- [ ] B",
+      "",
+      "[^fn1]:",
+      "    Detail about option A that is longer than eighty characters for wrapping.",
+      "",
+    ])
+    const option = viewOf(qa, content).outline[0]!.children![0]!
+    expect(option).not.toHaveProperty("leaf")
+  })
+
+  it("still sets leaf:true on an option node with no footnote children", () => {
+    const content = doc(["## Open Questions", "", "### Q1?", "", "- [ ] A", "- [ ] B", ""])
+    const option = viewOf(qa, content).outline[0]!.children![0]!
+    expect(option).toMatchObject({ leaf: true })
+  })
+
+  it("a '- [ ]'-shaped line quoted inside a footnote definition's own body is not a dropped option", () => {
+    const content = doc([
+      "## Open Questions",
+      "",
+      "### Q1?",
+      "",
+      "- [ ] A[^fn1]",
+      "",
+      "[^fn1]:",
+      "    Example: `- [ ] not a real option, just quoted inside a footnote body here`.",
+      "",
+    ])
+    expect(qa.validate(content)).toEqual([])
+  })
+})
+
+describe("qa — sections and questions come from heading NODES, not string search", () => {
+  it("a '## Open Questions' line quoted inside a fenced code block does not count as the section", () => {
+    const content = doc(["Some prose.", "", "```", "## Open Questions", "", "### fake?", "```", ""])
+    expect(qa.validate(content)).toEqual([])
+    expect(unansweredQuestions(qa, content)).toEqual([])
+  })
+
+  it("a fenced block using '~~~' delimiters is recognized the same way", () => {
+    const content = doc(["Some prose.", "", "~~~", "## Open Questions", "~~~", ""])
+    expect(qa.validate(content)).toEqual([])
+  })
+})
+
+describe("qa — strict indentation reading", () => {
+  it("a '###' heading indented two spaces still counts as a question", () => {
+    const content = doc(["## Open Questions", "", "  ### Real question?", "", "- [ ] A", ""])
+    expect(qa.validate(content)).toEqual([])
+  })
+
+  it("a '###' heading indented four spaces is reported as a positioned refusal, not silently dropped", () => {
+    const content = doc(["## Open Questions", "", "    ### Dropped question?", "", "text", ""])
+    const findings = qa.validate(content)
+    expect(findings.some((f) => f.message.includes("not a question heading"))).toBe(true)
+  })
+
+  it("a '- [ ]' option indented four spaces is reported as a positioned refusal", () => {
+    const content = doc([
+      "## Open Questions",
+      "",
+      "### Real question?",
+      "",
+      "    - [ ] Dropped option",
+      "",
+    ])
+    const findings = qa.validate(content)
+    expect(findings.some((f) => f.message.includes("not an option"))).toBe(true)
+  })
+
+  it("a 4+-space NESTED option under a real option is still reported, not silently absorbed", () => {
+    const content = doc([
+      "## Open Questions",
+      "",
+      "### Real question?",
+      "",
+      "- [ ] Parent option",
+      "    - [ ] Nested option",
+      "",
+    ])
+    const findings = qa.validate(content)
+    expect(findings.some((f) => f.message.includes("not an option"))).toBe(true)
+  })
+
+  it("a genuinely shallow (under 4 spaces) nested option is untouched — no finding", () => {
+    const content = doc([
+      "## Open Questions",
+      "",
+      "### Real question?",
+      "",
+      "- [ ] Parent option",
+      "  - [ ] Shallow nested option",
+      "",
+    ])
+    expect(qa.validate(content)).toEqual([])
+  })
+
+  it("a 4+-space heading folded into a preceding option's own lazy continuation is still reported, and the question it would start stays missing", () => {
+    const content = doc([
+      "## Open Questions",
+      "",
+      "### A?",
+      "",
+      "- [ ] one",
+      "    ### B?",
+      "",
+      "- [ ] two",
+    ])
+    const findings = qa.validate(content)
+    expect(findings).toHaveLength(1)
+    expect(findings[0]!.message).toContain("### B?")
+    expect(unansweredQuestions(qa, content)).toEqual([expect.objectContaining({ question: "A?" })])
+  })
+})
+
+describe("qa — strict-reading ignores indented lines that aren't heading- or option-shaped", () => {
+  it("a plain indented (4+ space) prose line inside the section is not reported at all", () => {
+    const content = doc([
+      "## Open Questions",
+      "",
+      "### Real question?",
+      "",
+      "some prose.",
+      "    just an indented continuation, not heading- or option-shaped",
+      "",
+    ])
+    expect(qa.validate(content)).toEqual([])
+  })
+})
+
+describe("qa — actions (options, footnotes)", () => {
+  it("offers 'pick this option' on an unticked option, and unticks the previously-ticked sibling", () => {
+    const content = doc(["## Open Questions", "", "### Q1?", "", "- [x] A", "- [ ] B", ""])
+    const actions = qa.actions(content, {
+      start: { line: 5, character: 2 },
+      end: { line: 5, character: 2 },
+    })
+    const pick = actions.find((a) => a.title === "gtd: pick this option")!
+    expect(pick.edits).toHaveLength(2)
+  })
+
+  it("offers 'uncheck this option' on the already-ticked option", () => {
+    const content = doc(["## Open Questions", "", "### Q1?", "", "- [x] A", "- [ ] B", ""])
+    const actions = qa.actions(content, {
+      start: { line: 4, character: 2 },
+      end: { line: 4, character: 2 },
+    })
+    expect(actions.some((a) => a.title === "gtd: uncheck this option")).toBe(true)
+  })
+
+  it("has a footnote-only pointerAt", () => {
+    const content = doc([
+      "## Open Questions",
+      "",
+      "### Q1?",
+      "",
+      "- [ ] A[^fn1]",
+      "",
+      "[^fn1]:",
+      "    Detail that is longer than eighty characters so it definitely wraps here.",
+      "",
+    ])
+    const pointer = qa.pointerAt!(content, { line: 4, character: 8 })
+    expect(pointer).toBeDefined()
+  })
+
+  it("'add a footnote' lands after the last line of a contiguous option list, not between items", () => {
+    const content = doc(["## Open Questions", "", "### Q1?", "", "- [ ] A", "- [ ] B", ""])
+    const actions = qa.actions(content, {
+      start: { line: 4, character: 5 },
+      end: { line: 4, character: 5 },
+    })
+    const footnote = actions.find((a) => a.title === "gtd: add a footnote")!
+    expect(footnote).toBeDefined()
+  })
+
+  it("in a question with no options at all, 'add a footnote' still lands after that question's own block", () => {
+    const content = doc(["## Open Questions", "", "### Q1?", "", "just prose.", ""])
+    const actions = qa.actions(content, {
+      start: { line: 4, character: 3 },
+      end: { line: 4, character: 3 },
+    })
+    expect(actions.some((a) => a.title === "gtd: add a footnote")).toBe(true)
+  })
+
+  it("outside every question (lead prose above '## Open Questions'), still offers 'add a footnote'", () => {
+    const content = doc([
+      "Some lead prose.",
+      "",
+      "## Open Questions",
+      "",
+      "### Q1?",
+      "",
+      "text",
+      "",
+    ])
+    const actions = qa.actions(content, {
+      start: { line: 0, character: 3 },
+      end: { line: 0, character: 3 },
+    })
+    expect(actions.some((a) => a.title === "gtd: add a footnote")).toBe(true)
+  })
+
+  it("offers the footnote action under the shared FOOTNOTE_ACTION_TITLE constant", () => {
+    const content = doc(["## Open Questions", "", "### Q1?", "", "- [ ] A", ""])
+    const actions = qa.actions(content, {
+      start: { line: 4, character: 5 },
+      end: { line: 4, character: 5 },
+    })
+    const footnote = actions.find((a) => a.title === FOOTNOTE_ACTION_TITLE)!
+    expect(footnote).toBeDefined()
+  })
+
+  it("offers 'add a footnote' LAST, after the option action, on an open question's option", () => {
+    const content = doc(["## Open Questions", "", "### Q1?", "", "- [ ] A", ""])
+    const actions = qa.actions(content, {
+      start: { line: 4, character: 2 },
+      end: { line: 4, character: 2 },
+    })
+    expect(actions.map((a) => a.title)).toEqual(["gtd: pick this option", FOOTNOTE_ACTION_TITLE])
+  })
+
+  it("is refused with the cursor inside an existing marker's span", () => {
+    const content = doc([
+      "## Open Questions",
+      "",
+      "### Q1?",
+      "",
+      "- [ ] A[^fn1]",
+      "",
+      "[^fn1]:",
+      "    Detail that is longer than eighty characters so it definitely wraps here.",
+      "",
+    ])
+    const actions = qa.actions(content, {
+      start: { line: 4, character: 8 },
+      end: { line: 4, character: 8 },
+    })
+    expect(actions.some((a) => a.title === "gtd: add a footnote")).toBe(false)
+  })
+})
+
+describe("qa — clearTicks is a deliberate no-op", () => {
+  it("never clears its own answer tick — qa's ticks ARE its answers", () => {
+    const content = doc(["## Open Questions", "", "### Q1?", "", "- [x] A", "- [ ] B", ""])
+    expect(qa.clearTicks(content)).toBe(content)
+  })
+})
+
+describe("isAnswered — the ONE predicate exported for a client to reuse, never re-derive (T5)", () => {
+  it("is answered when exactly one option is ticked and it isn't the free-text slot", () => {
+    expect(
+      isAnswered([
+        { checked: true, text: "Option A", freeText: false },
+        { checked: false, text: "Option B", freeText: false },
+      ]),
+    ).toBe(true)
+  })
+
+  it("is unanswered when zero options are ticked", () => {
+    expect(
+      isAnswered([
+        { checked: false, text: "Option A", freeText: false },
+        { checked: false, text: "Option B", freeText: false },
+      ]),
+    ).toBe(false)
+  })
+
+  it("is unanswered when two or more options are ticked at once — the exact divergence a client re-deriving 'take the first checked option' would miss", () => {
+    expect(
+      isAnswered([
+        { checked: true, text: "Option A", freeText: false },
+        { checked: true, text: "Option B", freeText: false },
+      ]),
+    ).toBe(false)
+  })
+
+  it("is unanswered when the ticked option is the free-text slot with empty text", () => {
+    expect(isAnswered([{ checked: true, text: "", freeText: true }])).toBe(false)
+  })
+
+  it("is answered when the ticked option is the free-text slot WITH text", () => {
+    expect(isAnswered([{ checked: true, text: "a real answer", freeText: true }])).toBe(true)
+  })
+})
+
+describe("qa.view", () => {
+  const CONTENT = [
+    "Plan.",
+    "",
+    "## Open Questions",
+    "",
+    "### First?",
+    "",
+    "- [ ] Option A",
+    "- [ ] Option B",
+    "",
+    "## Answered Questions",
+    "",
+    "### Second?",
+    "",
+    "Already decided.",
+    "",
+  ].join("\n")
+
+  it("exposes both open and answered questions, in document order — title carries the actual question, detail the whole body's collapsed text", () => {
+    const view = qa.view(CONTENT)
+    const questionNodes = view.nodes.filter((n) => n.status !== undefined)
+    // "First?"'s own body is ONLY its option list — excluded from the body
+    // walk (that's `children`'s own job) — so its `detail` is "".
+    expect(questionNodes.map((q) => [q.status, q.title, q.detail])).toEqual([
+      ["open", "First?", ""],
+      ["answered", "Second?", "Already decided."],
+    ])
+    expect(questionNodes[0]!.children!.map((o) => o.title)).toEqual(["Option A", "Option B"])
+  })
+
+  it("prepends the plan's own lead prose (before '## Open Questions') as a paragraph node, ahead of every question", () => {
+    const view = qa.view(CONTENT)
+    expect(view.nodes[0]).toMatchObject({ title: "Plan.", anchor: { kind: "paragraph", line: 0 } })
+    expect(view.nodes[0]!.status).toBeUndefined()
+    expect(view.nodes.slice(1).every((n) => n.status !== undefined)).toBe(true)
+  })
+
+  it("is built from one parse of the document, not one per element", () => {
+    const uniqueContent = [
+      "Plan two.",
+      "",
+      "## Open Questions",
+      "",
+      "### Solo?",
+      "",
+      "- [ ] Only option",
+      "",
+    ].join("\n")
+    const before = getParseCount()
+    qa.view(uniqueContent)
+    expect(getParseCount()).toBe(before + 1)
+  })
+})
+
+describe("qa.view — spec-feedback regression: raw HTML stays inert text, never an empty detailInline", () => {
+  it("an answered question's own block-level <div> body carries one text node on detailInline, never []", () => {
+    const content = ["## Answered Questions", "", "### Second?", "", "<div>raw</div>", ""].join(
+      "\n",
+    )
+    const view = qa.view(content)
+    const question = view.nodes.find((n) => n.status !== undefined)!
+    expect(question.detail).toBe("<div>raw</div>")
+    expect(question.detailInline).toEqual([{ kind: "text", value: "<div>raw</div>" }])
+  })
+
+  it("a nested list item's own text is not dropped from an answered question's own detailInline", () => {
+    const content = [
+      "## Answered Questions",
+      "",
+      "### Second?",
+      "",
+      "- item one",
+      "- item two",
+      "  - nested",
+      "",
+    ].join("\n")
+    const view = qa.view(content)
+    const question = view.nodes.find((n) => n.status !== undefined)!
+    // `detail` itself is title-based (`bodyText`/`blockTitle`), which has
+    // never included a nested item's own text — unchanged, not this
+    // regression's own concern. `detailInline` is the flattened path this
+    // regression fixes, and must carry it.
+    const joined = (question.detailInline ?? []).map((n) => ("value" in n ? n.value : "")).join("")
+    expect(joined).toContain("nested")
+  })
+})
+
+describe("qa.view — prose-only projection (T2, no Open/Answered Questions section at all)", () => {
+  it("yields one paragraph node per paragraph, and no questions", () => {
+    const content = ["First paragraph of the plan.", "", "Second paragraph, more detail.", ""].join(
+      "\n",
+    )
+    const view = qa.view(content)
+    expect(view.nodes.every((n) => n.status === undefined)).toBe(true)
+    expect(view.nodes.map((n) => n.title)).toEqual([
+      "First paragraph of the plan.",
+      "Second paragraph, more detail.",
+    ])
+  })
+
+  it("each paragraph node's anchor is a real, server-computed {kind:'paragraph', line} at the paragraph's own start line", () => {
+    const content = ["Line zero paragraph.", "", "Line two paragraph.", ""].join("\n")
+    const view = qa.view(content)
+    expect(view.nodes.map((n) => n.anchor)).toEqual([
+      { kind: "paragraph", line: 0 },
+      { kind: "paragraph", line: 2 },
+    ])
+  })
+
+  it("a paragraph anchor round-trips through annotate/resolve — attaching a note at the projected line actually lands", () => {
+    const content = ["A paragraph worth commenting on.", ""].join("\n")
+    const result = qa.annotate(content, { kind: "paragraph", line: 0 }, "a real comment")
+    expect(result.ok).toBe(true)
+  })
+
+  it("a paragraph already carrying a footnote at its own start line surfaces it as that node's own note, for editing rather than a second note", () => {
+    const content = [
+      "A paragraph with a note attached.[^fn1]",
+      "",
+      "[^fn1]: the reviewer's own comment",
+      "",
+    ].join("\n")
+    const view = qa.view(content)
+    expect(view.nodes[0]?.note).toBe("the reviewer's own comment")
+  })
+
+  it("a document with an Open Questions section is NOT treated as prose-only, even with prose before it", () => {
+    const content = [
+      "Some intro prose.",
+      "",
+      "## Open Questions",
+      "",
+      "### First?",
+      "",
+      "- [ ] Option A",
+      "",
+    ].join("\n")
+    const view = qa.view(content)
+    // NOT prose-only: the real question node is still there — but its own
+    // intro prose is now ALSO a node (a separate, `undefined`-status
+    // paragraph node), never dropped.
+    expect(view.nodes.map((n) => n.status)).toEqual([undefined, "open"])
+    expect(view.nodes[0]).toMatchObject({
+      title: "Some intro prose.",
+      anchor: { kind: "paragraph", line: 0 },
+    })
+  })
+})
+
+describe("qa.view — block nodes (package 02, T1/T2)", () => {
+  it("a heading, a nested list, a fenced code block, a blockquote and two paragraphs yield six block nodes, in document order", () => {
+    const content = [
+      "# Heading",
+      "",
+      "- Item one",
+      "  - Nested item",
+      "",
+      "```",
+      "line one",
+      "line two",
+      "```",
+      "",
+      "> A blockquote.",
+      "",
+      "Paragraph one.",
+      "",
+      "Paragraph two.",
+      "",
+    ].join("\n")
+    const view = qa.view(content)
+    expect(view.nodes.map((n) => n.block?.kind)).toEqual([
+      "heading",
+      "list",
+      "code",
+      "blockquote",
+      "paragraph",
+      "paragraph",
+    ])
+  })
+
+  it("yields block nodes for the prose BEFORE the questions section and for every block AFTER it, and none for any block inside a question's own span", () => {
+    // A question's own body span runs up to the NEXT heading of any depth
+    // (`questionEndLines`/`splitQuestionBlocks`'s existing rule) — so genuine
+    // trailing content past the LAST question needs a heading of its own
+    // (here a `####`, neither a section heading nor a question heading) to
+    // stop that span; without one it reads as part of the last question's own
+    // body, which is exactly what this test's OWN "none inside a question's
+    // span" half already covers via "Already decided."/"Option A".
+    const content = [
+      "Lead prose.",
+      "",
+      "## Open Questions",
+      "",
+      "### First?",
+      "",
+      "- [ ] Option A",
+      "",
+      "## Answered Questions",
+      "",
+      "### Second?",
+      "",
+      "Already decided.",
+      "",
+      "#### Note",
+      "",
+      "Trailing prose.",
+      "",
+    ].join("\n")
+    const view = qa.view(content)
+    const proseTitles = view.nodes.filter((n) => n.status === undefined).map((n) => n.title)
+    expect(proseTitles).toEqual(["Lead prose.", "Note", "Trailing prose."])
+    // "Already decided." is the ANSWERED question's own body text — never a
+    // second, competing block node alongside that question's own node.
+    expect(proseTitles).not.toContain("Already decided.")
+    expect(proseTitles).not.toContain("Option A")
+  })
+
+  it("neither the '## Open Questions' nor the '## Answered Questions' heading is ever itself a block node", () => {
+    const content = [
+      "## Open Questions",
+      "",
+      "### First?",
+      "",
+      "- [ ] Option A",
+      "",
+      "## Answered Questions",
+      "",
+      "### Second?",
+      "",
+      "Already decided.",
+      "",
+    ].join("\n")
+    const view = qa.view(content)
+    expect(view.nodes.map((n) => n.title)).not.toContain("Open Questions")
+    expect(view.nodes.map((n) => n.title)).not.toContain("Answered Questions")
+  })
+
+  it("a prose-only document yields the same block nodes and zero question nodes", () => {
+    const content = ["# Heading", "", "Paragraph.", ""].join("\n")
+    const view = qa.view(content)
+    expect(view.nodes.every((n) => n.status === undefined)).toBe(true)
+    expect(view.nodes.map((n) => n.block?.kind)).toEqual(["heading", "paragraph"])
+  })
+
+  it("a heading node carries block.kind 'heading' and its real depth", () => {
+    const content = ["### A level-3 heading", ""].join("\n")
+    const view = qa.view(content)
+    expect(view.nodes[0]?.block).toMatchObject({ kind: "heading", depth: 3 })
+  })
+
+  it("a list node carries block.kind 'list', its ordered flag, and an items tree whose nesting matches the source — two levels deep for a list nested two deep", () => {
+    const content = ["- Top item", "  - Nested item", ""].join("\n")
+    const view = qa.view(content)
+    expect(view.nodes[0]?.block).toMatchObject({
+      kind: "list",
+      ordered: false,
+      items: [{ text: "Top item", items: [{ text: "Nested item" }] }],
+    })
+  })
+
+  it("an ordered list node carries ordered: true", () => {
+    const content = ["1. First", "2. Second", ""].join("\n")
+    const view = qa.view(content)
+    expect(view.nodes[0]?.block).toMatchObject({ kind: "list", ordered: true })
+  })
+
+  it("a list item with a nested list AND a trailing paragraph of its own yields text containing neither the nested item's text nor its '-' marker, with that item present exactly once in the items tree", () => {
+    const content = ["- Top", "", "  - Nested", "", "  Tail para.", ""].join("\n")
+    const view = qa.view(content)
+    const topItem = view.nodes[0]?.block?.items?.[0]
+    expect(topItem?.text).toBe("Top Tail para.")
+    expect(topItem?.text).not.toContain("Nested")
+    expect(topItem?.text).not.toContain("-")
+    expect(topItem?.items).toEqual([
+      { text: "Nested", inline: [{ kind: "text", value: "Nested" }] },
+    ])
+  })
+
+  it("a task-list item carries its checked state on the item", () => {
+    const content = ["- [ ] Not done", "- [x] Done", ""].join("\n")
+    const view = qa.view(content)
+    expect(view.nodes[0]?.block?.items).toEqual([
+      { text: "Not done", checked: false, inline: [{ kind: "text", value: "Not done" }] },
+      { text: "Done", checked: true, inline: [{ kind: "text", value: "Done" }] },
+    ])
+  })
+
+  it("a fenced code block carries block.kind 'code', its language from the info string, and its body verbatim — leading whitespace intact", () => {
+    const content = ["```ts", "  const x = 1", "const y = 2", "```", ""].join("\n")
+    const view = qa.view(content)
+    expect(view.nodes[0]?.block).toMatchObject({
+      kind: "code",
+      language: "ts",
+      text: "  const x = 1\nconst y = 2",
+    })
+  })
+
+  it("a fenced code block with no info string carries no language field", () => {
+    const content = ["```", "plain", "```", ""].join("\n")
+    const view = qa.view(content)
+    expect(view.nodes[0]?.block?.language).toBeUndefined()
+  })
+
+  it("a fenced code block with an empty body still carries a non-empty title", () => {
+    const content = ["```", "```", ""].join("\n")
+    const view = qa.view(content)
+    expect(view.nodes[0]?.block).toMatchObject({ kind: "code", text: "" })
+    expect(view.nodes[0]?.title.length).toBeGreaterThan(0)
+  })
+
+  it("a blockquote carries block.kind 'blockquote' and its text", () => {
+    const content = ["> Quoted wisdom.", ""].join("\n")
+    const view = qa.view(content)
+    expect(view.nodes[0]?.block).toMatchObject({ kind: "blockquote", text: "Quoted wisdom." })
+  })
+
+  it("a blockquote spanning two paragraphs carries text with no '>' character in it", () => {
+    const content = ["> First line.", ">", "> Second para.", ""].join("\n")
+    const view = qa.view(content)
+    expect(view.nodes[0]?.block?.text).not.toContain(">")
+    expect(view.nodes[0]?.block?.text).toBe("First line. Second para.")
+  })
+
+  it("a soft-broken blockquote (one paragraph, no blank '>' line) carries title and block.text with no '>' character in it", () => {
+    const content = ["> quoted line", "> more", ""].join("\n")
+    const view = qa.view(content)
+    expect(view.nodes[0]?.title).not.toContain(">")
+    expect(view.nodes[0]?.block?.text).not.toContain(">")
+    expect(view.nodes[0]?.block).toMatchObject({ kind: "blockquote", text: "quoted line more" })
+  })
+
+  it("a literal '>' typed mid-prose inside a blockquote survives into title", () => {
+    const content = ["> a > b", ""].join("\n")
+    const view = qa.view(content)
+    expect(view.nodes[0]?.title).toBe("a > b")
+  })
+
+  it("an inline link inside a multi-line blockquote keeps its [label](url) syntax intact", () => {
+    const content = ["> see [label](url)", "> more text", ""].join("\n")
+    const view = qa.view(content)
+    expect(view.nodes[0]?.title).toBe("see [label](url) more text")
+  })
+
+  it("every node still carries a non-empty title", () => {
+    const content = [
+      "# Heading",
+      "",
+      "- Item",
+      "",
+      "```",
+      "code",
+      "```",
+      "",
+      "> Quote.",
+      "",
+      "Paragraph.",
+      "",
+    ].join("\n")
+    const view = qa.view(content)
+    expect(view.nodes.every((n) => n.title.length > 0)).toBe(true)
+  })
+})
+
+describe("qa.view — question body nodes (Task 2: a question's body projects as blocks, not a line)", () => {
+  const questionNodeOf = (content: string) =>
+    qa.view(content).nodes.find((n) => n.status !== undefined)!
+
+  it("a question whose body is a paragraph, a fenced code block and a list projects three body nodes carrying those kinds, in document order", () => {
+    const content = [
+      "## Open Questions",
+      "",
+      "### Which approach?",
+      "",
+      "Some body prose.",
+      "",
+      "```",
+      "example code",
+      "```",
+      "",
+      "* a plain bullet",
+      "* another bullet",
+      "",
+      "- [ ] Option A",
+      "",
+    ].join("\n")
+    const question = questionNodeOf(content)
+    expect(question.body?.map((n) => n.block?.kind)).toEqual(["paragraph", "code", "list"])
+  })
+
+  it("the option list never appears in body, and body blocks never appear in children", () => {
+    const content = [
+      "## Open Questions",
+      "",
+      "### Which approach?",
+      "",
+      "Body prose.",
+      "",
+      "- [ ] Option A",
+      "- [ ] Option B",
+      "",
+    ].join("\n")
+    const question = questionNodeOf(content)
+    expect(question.body?.map((n) => n.title)).toEqual(["Body prose."])
+    expect(question.children?.map((n) => n.title)).toEqual(["Option A", "Option B"])
+  })
+
+  it("a plain (non-task) bullet sharing the SAME list as real options is excluded from children but still surfaces in body — never dropped entirely", () => {
+    const content = [
+      "## Open Questions",
+      "",
+      "### Which approach?",
+      "",
+      "Body prose that matters.",
+      "",
+      "- [ ] Option A",
+      "- a plain bullet that is NOT an option",
+      "- [ ] Option B",
+      "",
+    ].join("\n")
+    const question = questionNodeOf(content)
+    // The two real options are still `children`, exactly as before.
+    expect(question.children?.map((n) => n.title)).toEqual(["Option A", "Option B"])
+    // The plain bullet is excluded from `children` (it's not an option) —
+    // but it must not vanish outright: it belongs in `body`, alongside the
+    // question's other prose, not nowhere.
+    expect(question.body?.map((n) => n.title)).toEqual([
+      "Body prose that matters.",
+      "a plain bullet that is NOT an option",
+    ])
+    expect(question.detail).toContain("a plain bullet that is NOT an option")
+  })
+
+  it("detail on a question node is the whole body's collapsed text — a body wrapped across four source lines reads back complete", () => {
+    const content = [
+      "## Open Questions",
+      "",
+      "### Which approach?",
+      "",
+      "This body prose deliberately wraps across several",
+      "source lines so the whole thing must be collapsed",
+      "into one detail string rather than only the first",
+      "of its own four lines.",
+      "",
+      "- [ ] Option A",
+      "",
+    ].join("\n")
+    const question = questionNodeOf(content)
+    expect(question.detail).toBe(
+      "This body prose deliberately wraps across several source lines so the whole thing must be collapsed into one detail string rather than only the first of its own four lines.",
+    )
+  })
+
+  it("a question with no body at all yields body: [] and detail: ''", () => {
+    const content = ["## Open Questions", "", "### Which approach?", "", "- [ ] Option A", ""].join(
+      "\n",
+    )
+    const question = questionNodeOf(content)
+    expect(question.body).toEqual([])
+    expect(question.detail).toBe("")
+  })
+
+  it("every body node carries a real {kind: 'paragraph', line} anchor at its own start line", () => {
+    const content = [
+      "## Open Questions",
+      "",
+      "### Which approach?",
+      "",
+      "Body prose.",
+      "",
+      "- [ ] Option A",
+      "",
+    ].join("\n")
+    const question = questionNodeOf(content)
+    expect(question.body).toEqual([
+      expect.objectContaining({ anchor: { kind: "paragraph", line: 4 } }),
+    ])
+  })
+})
+
+/** Applies edits back-to-front — a local copy of the file's own `applyEdits` (defined further down, after `qa.apply`'s own describe block) so this earlier suite can assert on the resulting document text too. */
+const applyEditsLocal = (
+  content: string,
+  edits: readonly {
+    readonly range: {
+      readonly start: { readonly line: number; readonly character: number }
+      readonly end: { readonly line: number; readonly character: number }
+    }
+    readonly newText: string
+  }[],
+): string => {
+  const lines = content.split("\n")
+  const toOffset = (pos: { readonly line: number; readonly character: number }): number => {
+    let offset = 0
+    for (let i = 0; i < pos.line; i += 1) offset += (lines[i]?.length ?? 0) + 1
+    return offset + pos.character
+  }
+  const sorted = [...edits].sort((a, b) => toOffset(b.range.start) - toOffset(a.range.start))
+  let result = content
+  for (const edit of sorted) {
+    result =
+      result.slice(0, toOffset(edit.range.start)) +
+      edit.newText +
+      result.slice(toOffset(edit.range.end))
+  }
+  return result
+}
+
+describe("qa.annotate/note — block anchors carry structure beyond paragraphs (package 02, T3)", () => {
+  it("annotate with a paragraph anchor at a heading's start line attaches the marker at the end of that heading's own line and the definition after the heading's own block", () => {
+    const content = ["# Heading", "", "Body text.", ""].join("\n")
+    const result = qa.annotate(content, { kind: "paragraph", line: 0 }, "a note on the heading")
+    expect(result.ok).toBe(true)
+    if (!result.ok) return
+    const markerEdit = result.edits.find((e) => e.range.start.line === 0)
+    expect(markerEdit?.newText).toContain("[^")
+    const applied = applyEditsLocal(content, result.edits)
+    expect(applied.split("\n")[0]).toBe(`# Heading${markerEdit?.newText}`)
+    expect(qa.validate(applied).length).toBe(0)
+  })
+
+  it("annotate with a paragraph anchor at a list's start line and at a blockquote's start line each succeed, and the resulting document still passes validate with zero findings", () => {
+    const listContent = ["- Item one", "- Item two", ""].join("\n")
+    const listResult = qa.annotate(listContent, { kind: "paragraph", line: 0 }, "note on list")
+    expect(listResult.ok).toBe(true)
+    if (listResult.ok) {
+      expect(qa.validate(applyEditsLocal(listContent, listResult.edits)).length).toBe(0)
+    }
+
+    const quoteContent = ["> A quote.", ""].join("\n")
+    const quoteResult = qa.annotate(quoteContent, { kind: "paragraph", line: 0 }, "note on quote")
+    expect(quoteResult.ok).toBe(true)
+    if (quoteResult.ok) {
+      expect(qa.validate(applyEditsLocal(quoteContent, quoteResult.edits)).length).toBe(0)
+    }
+  })
+
+  it("a block node that already carries a footnote marker on its start line surfaces that note as `note`, for every block kind — not just paragraphs", () => {
+    const content = [
+      "# Heading with a note[^fn1]",
+      "",
+      "[^fn1]: the reviewer's own comment",
+      "",
+    ].join("\n")
+    const view = qa.view(content)
+    expect(view.nodes[0]?.block?.kind).toBe("heading")
+    expect(view.nodes[0]?.note).toBe("the reviewer's own comment")
+  })
+
+  // `annotate` deliberately keeps no code-block branch (Task 3's own point):
+  // `footnoteAttachEdits` puts a marker at the end of the anchor line, which
+  // for a code block IS the opening fence — attaching there WOULD corrupt
+  // it. Nothing here prevents that call from succeeding; the server still
+  // emits the code block's own `{kind:"paragraph", line}` anchor like every
+  // other node (below), and it is the CLIENT's job (`ProseBlock`, Task 4)
+  // to never offer the seam that would produce this call in the first place.
+  it("a code block still carries a real {kind:'paragraph', line} anchor — the same kind every other block carries, no separate anchor kind for code", () => {
+    const content = ["```", "line one", "```", ""].join("\n")
+    const view = qa.view(content)
+    expect(view.nodes[0]).toMatchObject({
+      block: { kind: "code" },
+      anchor: { kind: "paragraph", line: 0 },
+    })
+  })
+})
+
+describe("qa — option text span (Task 1: one span, read and written by one helper)", () => {
+  it("an option wrapped across three source lines reads back as its whole text, whitespace-collapsed and marker-stripped", () => {
+    const content = [
+      "## Open Questions",
+      "",
+      "### Which API?",
+      "",
+      "- [ ] REST, specifically a JSON:API-flavored",
+      "  REST endpoint set that keeps every response",
+      "  shaped consistently across the whole service.",
+      "",
+    ].join("\n")
+    const [option] = parseOpenQuestions(content).questions[0]!.options
+    expect(option!.text).toBe(
+      "REST, specifically a JSON:API-flavored REST endpoint set that keeps every response shaped consistently across the whole service.",
+    )
+  })
+
+  it("parse → apply({text}) → parse on a question whose existing free-text answer wraps across lines returns exactly the new answer — no tail of the old answer left behind, no duplication", () => {
+    const content = [
+      "## Open Questions",
+      "",
+      "### Which API?",
+      "",
+      "- [ ] REST",
+      "- [x] a long previous answer that wraps",
+      "  across two whole continuation lines here",
+      "",
+    ].join("\n")
+    const before = parseOpenQuestions(content).questions[0]!
+    expect(before.options[1]!.text).toBe(
+      "a long previous answer that wraps across two whole continuation lines here",
+    )
+    const result = qa.apply(
+      content,
+      { kind: "option", questionIndex: 0, index: 1 },
+      { checked: true, text: "a short new answer" },
+    )
+    expect(result.ok).toBe(true)
+    if (!result.ok) return
+    const applied = applyEditsLocal(content, result.edits)
+    const after = parseOpenQuestions(applied).questions[0]!
+    expect(after.options[1]!.text).toBe("a short new answer")
+    expect(applied).not.toContain("wraps")
+    expect(applied).not.toContain("continuation lines")
+  })
+
+  it("an option carrying a nested list under it keeps that nested list byte-for-byte after a free-text save", () => {
+    const content = [
+      "## Open Questions",
+      "",
+      "### Which API?",
+      "",
+      "- [x] the previous answer",
+      "  - a nested detail that must survive",
+      "  - another nested detail",
+      "- [ ] GraphQL",
+      "",
+    ].join("\n")
+    const result = qa.apply(
+      content,
+      { kind: "option", questionIndex: 0, index: 0 },
+      { checked: true, text: "a brand new answer" },
+    )
+    expect(result.ok).toBe(true)
+    if (!result.ok) return
+    const applied = applyEditsLocal(content, result.edits)
+    expect(applied).toContain("  - a nested detail that must survive")
+    expect(applied).toContain("  - another nested detail")
+    expect(applied).toContain("- [x] a brand new answer")
+  })
+
+  it("an option whose content starts on the line AFTER its marker reads its text and accepts a text edit, where it read '' and refused before", () => {
+    const content = [
+      "## Open Questions",
+      "",
+      "### Which API?",
+      "",
+      "- [ ]",
+      "  content on the next line",
+      "",
+    ].join("\n")
+    const before = parseOpenQuestions(content).questions[0]!.options[0]!
+    expect(before.text).toBe("content on the next line")
+    const result = qa.apply(
+      content,
+      { kind: "option", questionIndex: 0, index: 0 },
+      { checked: true, text: "a replacement" },
+    )
+    expect(result.ok).toBe(true)
+    if (!result.ok) return
+    const applied = applyEditsLocal(content, result.edits)
+    expect(parseOpenQuestions(applied).questions[0]!.options[0]).toMatchObject({
+      checked: true,
+      text: "a replacement",
+    })
+  })
+
+  // A bare, truly content-less "- [ ]" is never even recognized as a task
+  // item by the underlying GFM parser (its own micromark task-list-check
+  // tokenizer requires trailing content or a following sibling to fire at
+  // all — `item.checked` stays `null` and `optionListItems` excludes it
+  // upstream), so `optionTextSpan`'s "no paragraph" branch can't be reached
+  // through real parsed markdown. The `qa.apply` "erasing a free-text
+  // answer" test (below) covers the reachable shape of this same guard: an
+  // erase writes `FREE_TEXT_PLACEHOLDER` rather than truly empty text,
+  // specifically so this anchor never goes stale.
+})
+
+describe("qa — option impacts (nested content under an option)", () => {
+  it("a nested plain bullet list under an option parses into that option's own body, and the option's own text stays the label alone", () => {
+    const content = [
+      "## Open Questions",
+      "",
+      "### Which option?",
+      "",
+      "- [ ] Ship it behind a flag",
+      "  - Rollback is one edit, not a revert",
+      "  - Leaves a config key nobody removes",
+      "- [ ] Ship it directly",
+      "",
+    ].join("\n")
+    const [first, second] = parseOpenQuestions(content).questions[0]!.options
+    expect(first!.text).toBe("Ship it behind a flag")
+    expect(first!.body).toHaveLength(1)
+    expect(first!.body[0]!.block?.kind).toBe("list")
+    expect(first!.body[0]!.block?.items?.map((item) => item.text)).toEqual([
+      "Rollback is one edit, not a revert",
+      "Leaves a config key nobody removes",
+    ])
+    expect(second!.text).toBe("Ship it directly")
+    expect(second!.body).toEqual([])
+  })
+
+  it("a second paragraph under an option parses into its body the same way a nested list does", () => {
+    const content = [
+      "## Open Questions",
+      "",
+      "### Which option?",
+      "",
+      "- [ ] Ship it behind a flag",
+      "",
+      "  A second paragraph of impacts, indented under the option.",
+      "- [ ] Ship it directly",
+      "",
+    ].join("\n")
+    const [first] = parseOpenQuestions(content).questions[0]!.options
+    expect(first!.body.map((n) => n.title)).toEqual([
+      "A second paragraph of impacts, indented under the option.",
+    ])
+  })
+
+  it("a nested plain bullet never becomes a sub-option — optionListItems is unchanged", () => {
+    const content = [
+      "## Open Questions",
+      "",
+      "### Which option?",
+      "",
+      "- [ ] Ship it behind a flag",
+      "  - Rollback is one edit, not a revert",
+      "- [ ] Ship it directly",
+      "",
+    ].join("\n")
+    expect(parseOpenQuestions(content).questions[0]!.options.map((o) => o.text)).toEqual([
+      "Ship it behind a flag",
+      "Ship it directly",
+    ])
+  })
+
+  it("endLine already spans the nested content, so a footnote marker written inside an option's impacts resolves to that option", () => {
+    const content = [
+      "## Open Questions",
+      "",
+      "### Which option?",
+      "",
+      "- [ ] Ship it behind a flag",
+      "  - Rollback is one edit, not a revert[^fn1]",
+      "- [ ] Ship it directly",
+      "",
+      "[^fn1]: a note on the impact itself",
+      "",
+    ].join("\n")
+    const outline = qa.outline(content)
+    const option = outline[0]!.children![0]!
+    expect(option.children!.some((c) => c.name.includes("a note on the impact itself"))).toBe(true)
+  })
+
+  it("a free-text save leaves every other option's nested impacts byte-identical, and moves nothing outside the saved option's own first paragraph", () => {
+    // The WRITTEN option (index 2, the free-text slot) itself carries a
+    // nested bullet under its label — the one shape in which widening
+    // `optionTextSpan`'s `end` from the first paragraph to the whole list
+    // item (the exact corruption its own doc comment and the Requirement's
+    // Risk line call out) would delete something THIS test can catch: a
+    // regression there would swallow "a nested note the human left before
+    // writing an answer" into the replacement text or delete it outright.
+    const content = [
+      "## Open Questions",
+      "",
+      "### Which option?",
+      "",
+      "- [ ] Ship it behind a flag",
+      "  - Rollback is one edit, not a revert",
+      "  - Leaves a config key nobody removes",
+      "- [ ] Ship it directly",
+      "  - No rollback path at all",
+      `- [ ] ${FREE_TEXT_PLACEHOLDER}`,
+      "  - a nested note the human left before writing an answer",
+      "",
+    ].join("\n")
+    const result = qa.apply(
+      content,
+      { kind: "option", questionIndex: 0, index: 2 },
+      { checked: true, text: "go with the flag" },
+    )
+    expect(result.ok).toBe(true)
+    if (!result.ok) return
+    const applied = applyEditsLocal(content, result.edits)
+    // One `toBe` against the WHOLE document, not a handful of `toContain`
+    // substring checks: only the free-text slot's own label line changes
+    // (`- [ ] _your answer_` → `- [x] go with the flag`) — every other byte,
+    // every other option's nested content, and the written option's OWN
+    // nested bullet all stay exactly where they were.
+    expect(applied).toBe(
+      [
+        "## Open Questions",
+        "",
+        "### Which option?",
+        "",
+        "- [ ] Ship it behind a flag",
+        "  - Rollback is one edit, not a revert",
+        "  - Leaves a config key nobody removes",
+        "- [ ] Ship it directly",
+        "  - No rollback path at all",
+        "- [x] go with the flag",
+        "  - a nested note the human left before writing an answer",
+        "",
+      ].join("\n"),
+    )
+  })
+
+  it("the view carries an option's impacts on its own node's body, and the free-text slot's option node carries no body", () => {
+    const content = [
+      "## Open Questions",
+      "",
+      "### Which option?",
+      "",
+      "- [ ] Ship it behind a flag",
+      "  - Rollback is one edit, not a revert",
+      `- [ ] ${FREE_TEXT_PLACEHOLDER}`,
+      "",
+    ].join("\n")
+    const question = qa.view(content).nodes.find((n) => n.status !== undefined)!
+    const [first, freeText] = question.children!
+    expect(first!.body!.map((n) => n.title)).toEqual(["Rollback is one edit, not a revert"])
+    expect(freeText!.body).toBeUndefined()
+  })
+
+  it("the outline's option node carries its impacts' collapsed text as detail, with no extra node per impact", () => {
+    const content = [
+      "## Open Questions",
+      "",
+      "### Which option?",
+      "",
+      "- [ ] Ship it behind a flag",
+      "  - Rollback is one edit, not a revert",
+      "  - Leaves a config key nobody removes",
+      "- [ ] Ship it directly",
+      "",
+    ].join("\n")
+    const outline = qa.outline(content)
+    const [first, second] = outline[0]!.children!
+    expect(first!.detail).toBe(
+      "Rollback is one edit, not a revert Leaves a config key nobody removes",
+    )
+    expect(first!.leaf).toBe(true)
+    expect(first!.children).toBeUndefined()
+    expect(second!.detail).toBeUndefined()
+  })
+})
+
+describe("qa.annotate", () => {
+  const CONTENT = ["## Open Questions", "", "### First?", "", "- [ ] Option A", ""].join("\n")
+
+  it("accepts a question anchor", () => {
+    expect(qa.annotate(CONTENT, { kind: "question", index: 0 }, "a real note").ok).toBe(true)
+  })
+
+  it("annotates the heading of an answered question, definition after the entry", () => {
+    const content = [
+      "## Open Questions",
+      "",
+      "### First?",
+      "",
+      "- [ ] Option A",
+      "",
+      "## Answered Questions",
+      "",
+      "### Second?",
+      "",
+      "- [x] Option B",
+      "",
+    ].join("\n")
+    const result = qa.annotate(content, { kind: "question", index: 1 }, "reconsider this")
+    expect(result.ok).toBe(true)
+    if (!result.ok) return
+    const lines = applyEditsLocal(content, result.edits).split("\n")
+    const heading = lines.findIndex((l) => l.startsWith("### Second?"))
+    expect(lines[heading]).toMatch(/\[\^[^\]]+\]$/)
+    expect(lines[heading - 1]).not.toMatch(/\[\^/)
+    const def = lines.findIndex((l) => /^\[\^[^\]]+\]:/.test(l))
+    expect(def).toBeGreaterThan(heading)
+    expect(lines.slice(def).join("\n")).toContain("reconsider this")
+  })
+
+  it("accepts an option anchor", () => {
+    expect(
+      qa.annotate(CONTENT, { kind: "option", questionIndex: 0, index: 0 }, "a real note").ok,
+    ).toBe(true)
+  })
+
+  it("accepts a paragraph anchor in a prose-only document", () => {
+    expect(
+      qa.annotate("Just some prose.\n", { kind: "paragraph", line: 0 }, "a real note").ok,
+    ).toBe(true)
+  })
+
+  it("rejects an anchor that no longer resolves, rather than silently dropping it", () => {
+    expect(qa.annotate(CONTENT, { kind: "question", index: 5 }, "note")).toEqual({
+      ok: false,
+      reason: "anchor-not-found",
+    })
+    expect(qa.annotate(CONTENT, { kind: "chunk", index: 0 }, "note")).toEqual({
+      ok: false,
+      reason: "anchor-not-found",
+    })
+  })
+
+  it("attaches the given text verbatim, and the resulting document passes its own format's validator (T2's last criterion)", () => {
+    const result = qa.annotate(
+      CONTENT,
+      { kind: "option", questionIndex: 0, index: 0 },
+      "a real reason a human actually typed",
+    )
+    expect(result.ok).toBe(true)
+    if (!result.ok) return
+    const lines = CONTENT.split("\n")
+    const toOffset = (pos: { readonly line: number; readonly character: number }): number => {
+      let offset = 0
+      for (let i = 0; i < pos.line; i += 1) offset += (lines[i]?.length ?? 0) + 1
+      return offset + pos.character
+    }
+    const sorted = [...result.edits].sort(
+      (a, b) => toOffset(b.range.start) - toOffset(a.range.start),
+    )
+    let applied = CONTENT
+    for (const edit of sorted) {
+      applied =
+        applied.slice(0, toOffset(edit.range.start)) +
+        edit.newText +
+        applied.slice(toOffset(edit.range.end))
+    }
+    expect(applied).toContain("a real reason a human actually typed")
+    // qa.validate below already proves this raises no "has an empty body"
+    // finding — stronger than checking for the retired placeholder text.
+    expect(qa.validate(applied)).toEqual([])
+  })
+})
+
+/** Applies edits back-to-front (as `ui/Write.ts#applySteeringEdits` does) — local to this test file so `apply` tests can assert on the resulting document text, mirroring the `annotate` describe block above's own inline `toOffset`/splice pattern. */
+const applyEdits = (
+  content: string,
+  edits: readonly {
+    readonly range: {
+      readonly start: { readonly line: number; readonly character: number }
+      readonly end: { readonly line: number; readonly character: number }
+    }
+    readonly newText: string
+  }[],
+): string => {
+  const lines = content.split("\n")
+  const toOffset = (pos: { readonly line: number; readonly character: number }): number => {
+    let offset = 0
+    for (let i = 0; i < pos.line; i += 1) offset += (lines[i]?.length ?? 0) + 1
+    return offset + pos.character
+  }
+  const sorted = [...edits].sort((a, b) => toOffset(b.range.start) - toOffset(a.range.start))
+  let result = content
+  for (const edit of sorted) {
+    result =
+      result.slice(0, toOffset(edit.range.start)) +
+      edit.newText +
+      result.slice(toOffset(edit.range.end))
+  }
+  return result
+}
+
+describe("qa.apply", () => {
+  const CONTENT = [
+    "## Open Questions",
+    "",
+    "### First?",
+    "",
+    "- [x] Option A",
+    "- [ ] Option B",
+    `- [ ] ${FREE_TEXT_PLACEHOLDER}`,
+    "",
+  ].join("\n")
+
+  it("radio: ticking one option unticks an already-ticked sibling", () => {
+    const result = qa.apply(
+      CONTENT,
+      { kind: "option", questionIndex: 0, index: 1 },
+      {
+        checked: true,
+      },
+    )
+    expect(result.ok).toBe(true)
+    if (!result.ok) return
+    const applied = applyEdits(CONTENT, result.edits)
+    const { questions } = parseOpenQuestions(applied)
+    expect(questions[0]!.options.map((o) => o.checked)).toEqual([false, true, false])
+  })
+
+  it("ticking the free-text slot with text sets both the tick and the label in one edit set", () => {
+    const result = qa.apply(
+      CONTENT,
+      { kind: "option", questionIndex: 0, index: 2 },
+      {
+        checked: true,
+        text: "my real answer",
+      },
+    )
+    expect(result.ok).toBe(true)
+    if (!result.ok) return
+    const applied = applyEdits(CONTENT, result.edits)
+    const { questions } = parseOpenQuestions(applied)
+    expect(questions[0]!.options[2]).toMatchObject({ checked: true, text: "my real answer" })
+    // radio semantics fired too: Option A (already ticked) is now unticked
+    expect(questions[0]!.options[0]!.checked).toBe(false)
+  })
+
+  it("trims trailing whitespace off a typed free-text answer, so the written label stays an oxfmt fixed point", () => {
+    const result = qa.apply(
+      CONTENT,
+      { kind: "option", questionIndex: 0, index: 2 },
+      {
+        checked: true,
+        text: "my real answer   ",
+      },
+    )
+    expect(result.ok).toBe(true)
+    if (!result.ok) return
+    const applied = applyEdits(CONTENT, result.edits)
+    const { questions } = parseOpenQuestions(applied)
+    expect(questions[0]!.options[2]).toMatchObject({ checked: true, text: "my real answer" })
+    expect(applied).not.toMatch(/ +\n/)
+  })
+
+  it("collapses interior newlines in a typed free-text answer to a single line, so the written label stays an oxfmt fixed point", () => {
+    const result = qa.apply(
+      CONTENT,
+      { kind: "option", questionIndex: 0, index: 2 },
+      {
+        checked: true,
+        text: "line one\nline two",
+      },
+    )
+    expect(result.ok).toBe(true)
+    if (!result.ok) return
+    const applied = applyEdits(CONTENT, result.edits)
+    const { questions } = parseOpenQuestions(applied)
+    expect(questions[0]!.options[2]).toMatchObject({ checked: true, text: "line one line two" })
+    // The option's own line count must stay exactly one — a real newline
+    // spliced into the label would split it into two markdown lines, one of
+    // them unindented free-floating text no longer inside the list item.
+    expect(applied.split("\n").filter((line) => line.includes("line one"))).toHaveLength(1)
+  })
+
+  it("erasing a free-text answer ({checked: false, text: \"\"}) restores the placeholder, and the option is still writable afterward — never a dead 'anchor-not-found' anchor", () => {
+    // Seed a question whose free-text slot already carries a real typed
+    // answer — mirrors what `ticking the free-text slot with text` above
+    // just wrote.
+    const answered = applyEdits(
+      CONTENT,
+      (() => {
+        const first = qa.apply(
+          CONTENT,
+          { kind: "option", questionIndex: 0, index: 2 },
+          { checked: true, text: "my typed answer" },
+        )
+        if (!first.ok) throw new Error("setup apply failed")
+        return first.edits
+      })(),
+    )
+    expect(parseOpenQuestions(answered).questions[0]!.options[2]).toMatchObject({
+      checked: true,
+      text: "my typed answer",
+    })
+
+    const erase = qa.apply(
+      answered,
+      { kind: "option", questionIndex: 0, index: 2 },
+      { checked: false, text: "" },
+    )
+    expect(erase.ok).toBe(true)
+    if (!erase.ok) return
+    const erased = applyEdits(answered, erase.edits)
+    // Package 03's own bug: an empty label ("- [ ] ") leaves nothing for
+    // `optionContentOffset` to find, so this must NOT literally write "".
+    expect(erased).toContain(`- [ ] ${FREE_TEXT_PLACEHOLDER}`)
+    expect(parseOpenQuestions(erased).questions[0]!.options[2]).toMatchObject({
+      checked: false,
+      text: "",
+    })
+
+    // The anchor must still resolve — a real retype after an erase, the
+    // round trip a human erasing-then-retyping on the phone depends on.
+    const retype = qa.apply(
+      erased,
+      { kind: "option", questionIndex: 0, index: 2 },
+      { checked: true, text: "a new answer" },
+    )
+    expect(retype.ok).toBe(true)
+    if (!retype.ok) return
+    const retyped = applyEdits(erased, retype.edits)
+    expect(parseOpenQuestions(retyped).questions[0]!.options[2]).toMatchObject({
+      checked: true,
+      text: "a new answer",
+    })
+  })
+
+  it("a stale option index refuses anchor-not-found", () => {
+    expect(
+      qa.apply(CONTENT, { kind: "option", questionIndex: 0, index: 99 }, { checked: true }),
+    ).toEqual({ ok: false, reason: "anchor-not-found" })
+  })
+
+  it("a hunk/chunk anchor — not this format's own kind — refuses anchor-not-found", () => {
+    expect(qa.apply(CONTENT, { kind: "chunk", index: 0 }, { checked: true })).toEqual({
+      ok: false,
+      reason: "anchor-not-found",
+    })
+    expect(qa.apply(CONTENT, { kind: "hunk", chunkIndex: 0, index: 0 }, { checked: true })).toEqual(
+      { ok: false, reason: "anchor-not-found" },
+    )
+  })
+})
+
+describe("qa — Task 4: the real projection over an 80-column-wrapped design document", () => {
+  // Hand-wrapped at 80 columns, the exact shape oxfmt's own hard wrap
+  // produces for a question body and an option written in this workflow's
+  // prescribed prose style — the first document this suite feeds through
+  // the REAL `qa.view`/`parseOpenQuestions`, rather than a hand-built node.
+  const CONTENT = [
+    "## Open Questions",
+    "",
+    "### Which storage backend should the new cache layer use?",
+    "",
+    "The cache needs to survive a process restart without losing recently",
+    "written entries, and it must stay readable by every worker process at",
+    "once rather than being pinned to whichever one wrote it.",
+    "",
+    "- [ ] Redis, since it already runs in every environment this service",
+    "      deploys to and the team already operates it for the session",
+    "      store, so there is no new infrastructure to stand up.",
+    "- [ ] SQLite on a shared volume, trading some write concurrency for",
+    "      zero additional infrastructure and a format every worker can",
+    "      already read directly off disk.",
+    `- [ ] ${FREE_TEXT_PLACEHOLDER}`,
+    "",
+  ].join("\n")
+
+  it("the question body and every option render complete on the question screen (view.nodes[].body), not merely the first source line", () => {
+    const question = qa.view(CONTENT).nodes.find((n) => n.status !== undefined)!
+    expect(question.body).toEqual([
+      expect.objectContaining({
+        title:
+          "The cache needs to survive a process restart without losing recently written entries, and it must stay readable by every worker process at once rather than being pinned to whichever one wrote it.",
+      }),
+    ])
+    expect(question.detail).toBe(question.body![0]!.title)
+    expect(question.children!.map((o) => o.title)).toEqual([
+      "Redis, since it already runs in every environment this service deploys to and the team already operates it for the session store, so there is no new infrastructure to stand up.",
+      "SQLite on a shared volume, trading some write concurrency for zero additional infrastructure and a format every worker can already read directly off disk.",
+      "",
+    ])
+  })
+
+  it("a free-text answer long enough to wrap survives a reopen-and-save round trip byte-for-byte apart from the answer itself", () => {
+    const longAnswer =
+      "Go with Redis for now — it is already deployed everywhere this service runs and the team has years of operational experience keeping it healthy, so there is nothing new to learn."
+    const firstSave = qa.apply(
+      CONTENT,
+      { kind: "option", questionIndex: 0, index: 2 },
+      { checked: true, text: longAnswer },
+    )
+    expect(firstSave.ok).toBe(true)
+    if (!firstSave.ok) return
+    const afterFirstSave = applyEdits(CONTENT, firstSave.edits)
+    const reopened = parseOpenQuestions(afterFirstSave).questions[0]!.options[2]!
+    expect(reopened.text).toBe(longAnswer)
+
+    const newAnswer = "Actually, SQLite on the shared volume — one less service to operate."
+    const secondSave = qa.apply(
+      afterFirstSave,
+      { kind: "option", questionIndex: 0, index: 2 },
+      { checked: true, text: newAnswer },
+    )
+    expect(secondSave.ok).toBe(true)
+    if (!secondSave.ok) return
+    const afterSecondSave = applyEdits(afterFirstSave, secondSave.edits)
+    const final = parseOpenQuestions(afterSecondSave).questions[0]!.options[2]!
+    expect(final.text).toBe(newAnswer)
+    expect(afterSecondSave).not.toContain("years of operational experience")
+    expect(afterSecondSave).not.toContain("nothing new to learn")
+  })
+})
+
+const THREAD_QA_DOC = (agentLast: boolean): string =>
+  [
+    "## Open Questions",
+    "",
+    "### Which one?",
+    "",
+    "- [ ] A [^t1]",
+    "- [ ] B",
+    "",
+    "[^t1]:",
+    "    - H: why A?",
+    ...(agentLast ? ["    - A: because", "      wrapped on two lines"] : []),
+    "",
+    "[^once]: one-shot note",
+    "",
+  ].join("\n")
+
+describe("qa — thread outline", () => {
+  it("qa nests a thread under the option holding its first marker, with waiting-on detail", () => {
+    const outline = qa.outline(THREAD_QA_DOC(true))
+    const option = outline[0]!.children!.find((c) => c.name.includes("A"))!
+    const thread = option.children!.find((c) => c.name === "[^t1]")!
+    expect(thread.detail).toBe("waiting on you")
+  })
+  it("says waiting on the agent when the human spoke last", () => {
+    const outline = qa.outline(THREAD_QA_DOC(false))
+    const option = outline[0]!.children!.find((c) => c.name.includes("A"))!
+    expect(option.children!.find((c) => c.name === "[^t1]")!.detail).toBe("waiting on the agent")
+  })
+  it("a one-shot footnote adds no thread node", () => {
+    const names = JSON.stringify(qa.outline(THREAD_QA_DOC(true)))
+    expect(names).not.toContain('"[^once]"')
+  })
+})
+
+describe("qa view — threads", () => {
+  const doc = [
+    "Intro prose.[^t1]",
+    "",
+    "## Open Questions",
+    "",
+    "### Which option?[^t2]",
+    "",
+    "- [ ] Option A",
+    "- [ ] _your answer_",
+    "",
+    "[^t1]:",
+    "    - H: prose ask",
+    "    - A: why?",
+    "",
+    "[^t2]:",
+    "    - H: q ask",
+    "",
+  ].join("\n")
+
+  it("a prose block and a question with a thread expose `thread` and no `note`", () => {
+    const nodes = steeringFormatFor("qa")!.view(doc).nodes
+    const prose = nodes[0]!
+    expect(prose.note).toBeUndefined()
+    expect(prose.thread).toEqual({
+      name: "t1",
+      entries: [
+        { author: "me", text: "prose ask" },
+        { author: "agent", text: "why?" },
+      ],
+      waitingOn: "human",
+    })
+    const question = nodes.find((n) => n.anchor.kind === "question")!
+    expect(question.note).toBeUndefined()
+    expect(question.thread).toEqual({
+      name: "t2",
+      entries: [{ author: "me", text: "q ask" }],
+      waitingOn: "agent",
+    })
+  })
+
+  it("a one-shot footnote on a prose block still fills `note`", () => {
+    const nodes = steeringFormatFor("qa")!.view("Intro.[^n1]\n\n[^n1]: plain\n").nodes
+    expect(nodes[0]!.note).toBe("plain")
+    expect(nodes[0]!.thread).toBeUndefined()
+  })
+})