@pmelab/gtd 24.0.0 → 24.1.0

package/src/steering/SteeringFormats.test.ts

@@ -0,0 +1,163 @@
+import { describe, expect, it } from "vitest"
+import {
+  applySteeringEdits,
+  BUILT_IN_MODE_NAMES,
+  parseFootnotes,
+  parseThreads,
+  steeringFormatFor,
+} from "./index.js"
+
+const QA_FORMAT = steeringFormatFor("qa")!
+const REVIEW_FORMAT = steeringFormatFor("review")!
+
+describe("BUILT_IN_MODE_NAMES", () => {
+  it("lists the two built-in format names", () => {
+    expect(BUILT_IN_MODE_NAMES).toEqual(["qa", "review"])
+  })
+})
+
+describe("steeringFormatFor", () => {
+  it("resolves 'qa' and 'review' to their singleton formats", () => {
+    expect(steeringFormatFor("qa")).toBe(QA_FORMAT)
+    expect(steeringFormatFor("review")).toBe(REVIEW_FORMAT)
+  })
+
+  it("resolves an unknown name to undefined", () => {
+    expect(steeringFormatFor("prose")).toBeUndefined()
+    expect(steeringFormatFor("adr")).toBeUndefined()
+  })
+})
+
+describe("every registry entry's sample", () => {
+  // Load-bearing, not a nicety (see the package's own doc comment on this
+  // acceptance criterion): `src/emit/ModeContradiction.ts` round-trips this exact
+  // sample through a mode's declared `format:` command, then re-validates it
+  // — a sample that doesn't validate clean to begin with would hard-stop
+  // every prompt beat that declares `file:`+`mode:`, at 3 wasted agent turns
+  // each, with no way to tell a real contradiction from a drifted fixture.
+  it("validates clean under its own format's parser", () => {
+    for (const mode of BUILT_IN_MODE_NAMES) {
+      const format = steeringFormatFor(mode)!
+      expect(format.validate(format.sample)).toEqual([])
+    }
+  })
+})
+
+describe("every registry entry declares apply", () => {
+  it("has a function-typed apply member, not just annotate", () => {
+    for (const mode of BUILT_IN_MODE_NAMES) {
+      const format = steeringFormatFor(mode)!
+      expect(typeof format.apply).toBe("function")
+    }
+  })
+})
+
+/** Every `SteeringAnchor` embedded anywhere in `view` — walks whatever shape `view` returns without switching on `kind`, mirroring the server's own "never switch on the mode name" discipline. */
+const anchorsIn = (value: unknown): unknown[] => {
+  if (Array.isArray(value)) return value.flatMap(anchorsIn)
+  if (value === null || typeof value !== "object") return []
+  const record = value as Record<string, unknown>
+  const found: unknown[] = []
+  for (const [key, val] of Object.entries(record)) {
+    if (key === "anchor") found.push(val)
+    else found.push(...anchorsIn(val))
+  }
+  return found
+}
+
+describe("every registry entry's view", () => {
+  it("parses `format.sample` without throwing", () => {
+    for (const mode of BUILT_IN_MODE_NAMES) {
+      const format = steeringFormatFor(mode)!
+      expect(() => format.view(format.sample)).not.toThrow()
+    }
+  })
+
+  // `format.sample` itself, derived from the registry entry alone — never a
+  // per-mode fixture table (a third registry entry with no matching key
+  // there would fail on a confusing `undefined`, not on the property under
+  // test). `format.sample` already carries a note attached at ONE of its own
+  // anchors (T7 requires a server-written note in the sample) — annotating
+  // that SAME anchor again now EDITS the existing note in place
+  // (`Footnotes.ts#footnoteAttachEdits`'s same-anchor update path, T6: "offers
+  // editing it, not a second note"), which this treats as a PASS (`ok: true`)
+  // same as any other anchor; a genuine `id-collision` (an unrelated anchor's
+  // derived id colliding with existing content) remains an acceptable refusal
+  // too. Only `anchor-not-found` — the anchor itself failing to resolve — is
+  // the failure this property actually guards against.
+  it("every anchor `view` reports is one `annotate` accepts (or correctly refuses only as an id-collision, never as anchor-not-found)", () => {
+    for (const mode of BUILT_IN_MODE_NAMES) {
+      const format = steeringFormatFor(mode)!
+      const content = format.sample
+      const view = format.view(content)
+      const anchors = anchorsIn(view)
+      expect(anchors.length).toBeGreaterThan(0)
+      for (const anchor of anchors) {
+        const result = format.annotate(content, anchor as never, "a note a human typed")
+        const acceptable = result.ok || (!result.ok && result.reason === "id-collision")
+        expect(
+          acceptable,
+          `${mode}: ${JSON.stringify(anchor)} was refused: ${JSON.stringify(result)}`,
+        ).toBe(true)
+      }
+    }
+  })
+})
+
+describe("'gtd: add a footnote' refuses where a marker would corrupt a footnote", () => {
+  it("qa: refuses the action with the cursor inside an existing marker's [^name] span, rather than nesting a new marker into it", () => {
+    const cursor = { line: 6, character: 19 } // "- [ ] Option A[^fn1]" — between the name and its "]"
+    const action = QA_FORMAT.actions(QA_FORMAT.sample, { start: cursor, end: cursor }).find(
+      (a) => a.title === "gtd: add a footnote",
+    )
+    expect(action).toBeUndefined()
+  })
+
+  it("qa: refuses the action with the cursor on an existing definition's own label line, rather than splitting it", () => {
+    const cursor = { line: 23, character: 6 } // "[^fn1]:" — the definition's own label line
+    const action = QA_FORMAT.actions(QA_FORMAT.sample, { start: cursor, end: cursor }).find(
+      (a) => a.title === "gtd: add a footnote",
+    )
+    expect(action).toBeUndefined()
+  })
+})
+
+describe("each built-in format's canonical sample (T7: writing into a live worktree)", () => {
+  it("contains a note attached the way the server attaches one — a distinct `na`-prefixed id, from `Footnotes.ts#footnoteAttachEdits`", () => {
+    for (const mode of BUILT_IN_MODE_NAMES) {
+      const format = steeringFormatFor(mode)!
+      const { definitions } = parseFootnotes(format.sample)
+      expect(definitions.some((d) => /^na[0-9a-z]+$/.test(d.name))).toBe(true)
+    }
+  })
+})
+
+describe("thread-aware attach validates clean under every built-in format", () => {
+  const FIRST = "first"
+  for (const mode of BUILT_IN_MODE_NAMES) {
+    it(`${mode}: new thread, reply to an open thread, edit a waiting thread`, () => {
+      const format = steeringFormatFor(mode)!
+      const anchors = anchorsIn(format.view(format.sample))
+      const anchor = anchors.find((a) => {
+        const r = format.annotate(format.sample, a as never, FIRST)
+        return r.ok && parseThreads(applySteeringEdits(format.sample, r.edits)).length > 0
+      })!
+      const attach = (content: string, text: string): string => {
+        const r = format.annotate(content, anchor as never, text)
+        if (!r.ok) throw new Error("annotate refused")
+        return applySteeringEdits(content, r.edits)
+      }
+      const created = attach(format.sample, FIRST)
+      expect(format.validate(created)).toEqual([])
+      const edited = attach(created, "second")
+      expect(format.validate(edited)).toEqual([])
+      const thread = parseThreads(edited).find((t) => t.entries[0]?.text === "second")!
+      expect(thread.entries).toHaveLength(1)
+      const open = edited.replace(new RegExp(`(\\n    - H: second)`), "$1\n    - A: why?")
+      const replied = attach(open, "because")
+      expect(format.validate(replied)).toEqual([])
+      const after = parseThreads(replied).find((t) => t.name === thread.name)!
+      expect(after.entries.map((e) => e.text)).toEqual(["second", "why?", "because"])
+    })
+  }
+})

package/src/steering/Threads.ts

@@ -0,0 +1,163 @@
+import type { List, ListItem, Root } from "mdast"
+import { sourceText, spanRange, toLspPosition } from "./MarkdownTree.js"
+import type { SteeringFinding } from "./SteeringFormat.js"
+
+export interface ThreadMarker {
+  readonly name: string
+  readonly line: number
+  readonly character: number
+  readonly endCharacter: number
+}
+
+export interface ThreadEntry {
+  readonly author: "me" | "agent"
+  readonly text: string
+  readonly line: number
+  /** The entry's own last line — its last block's, never the list item's span (see `itemText`). */
+  readonly endLine: number
+  /** Column of the entry's `-` bullet. */
+  readonly column: number
+}
+
+/** `waitingOn: "human"` means the last entry is the agent's — the thread is OPEN. */
+export interface Thread {
+  readonly name: string
+  readonly line: number
+  readonly endLine: number
+  readonly markers: readonly ThreadMarker[]
+  readonly entries: readonly ThreadEntry[]
+  readonly waitingOn: "human" | "agent"
+}
+
+const PREFIX_RE = /^(H|A):\s*/
+
+interface Def {
+  readonly node: {
+    readonly label?: string | undefined
+    readonly identifier?: string | undefined
+    readonly children: readonly unknown[]
+    readonly position?: unknown
+  }
+}
+
+const lineOf = (node: { readonly position?: unknown }, which: "start" | "end"): number =>
+  toLspPosition((node.position as Record<"start" | "end", { line: number; column: number }>)[which])
+    .line
+
+/** The item's own blocks joined — never the item node's span, which can run past its last line into the next bullet's marker. */
+const itemText = (content: string, item: ListItem): string =>
+  item.children
+    .map((child) => sourceText(content, child))
+    .join(" ")
+    .trim()
+
+const prefixOf = (content: string, item: ListItem): RegExpExecArray | null =>
+  PREFIX_RE.exec(itemText(content, item))
+
+/** A thread is a definition whose body OPENS with a list whose first item carries a prefix — anything else stays a one-shot footnote. */
+const isThreadBody = (content: string, children: readonly unknown[]): List | undefined => {
+  const first = children[0] as { type: string } | undefined
+  if (first?.type !== "list") return undefined
+  const list = first as List
+  const item = list.children[0]
+  return item && prefixOf(content, item) ? list : undefined
+}
+
+const foldName = (name: string): string => name.toLowerCase()
+
+type Report = (message: string, from: number, to: number) => void
+
+/** One list item's entry, reporting any syntax problem; `previous` is the author before it. */
+const entryOf = (
+  content: string,
+  item: ListItem,
+  previous: ThreadEntry["author"] | undefined,
+  report: Report,
+): ThreadEntry | undefined => {
+  const start = lineOf(item, "start")
+  const end = lineOf(item, "end")
+  const match = prefixOf(content, item)
+  if (!match) {
+    report(`an entry must start with "H:" or "A:"`, start, end)
+    return undefined
+  }
+  const author = match[1] === "H" ? "me" : "agent"
+  const text = itemText(content, item).slice(match[0].length).trim()
+  if (text === "") report(`empty "${match[1]}:" entry — write your own words there`, start, end)
+  if (previous === undefined && author === "agent") {
+    report(`the agent never starts a thread — the first entry must be "H:"`, start, end)
+  } else if (previous === author) {
+    report(`two consecutive "${match[1]}:" entries — entries must alternate`, start, end)
+  }
+  const last = item.children[item.children.length - 1]
+  return {
+    author,
+    text,
+    line: start,
+    endLine: last ? lineOf(last, "end") : end,
+    column: toLspPosition(item.position!.start).character,
+  }
+}
+
+const threadOf = (
+  content: string,
+  def: Def["node"],
+  list: List,
+  markers: readonly ThreadMarker[],
+  report: Report,
+): Thread => {
+  const name = def.label ?? def.identifier ?? ""
+  const entries: ThreadEntry[] = []
+  let previous: ThreadEntry["author"] | undefined
+  for (const item of list.children) {
+    const entry = entryOf(content, item, previous, report)
+    if (!entry) continue
+    previous = entry.author
+    entries.push(entry)
+  }
+  for (const extra of def.children.slice(1) as { position?: unknown }[]) {
+    report(
+      `only one list of "H:"/"A:" entries may make up the body`,
+      lineOf(extra, "start"),
+      lineOf(extra, "end"),
+    )
+  }
+  return {
+    name,
+    line: lineOf(def, "start"),
+    endLine: lineOf(def, "end"),
+    markers: markers.filter((m) => foldName(m.name) === foldName(name)),
+    entries,
+    waitingOn: entries[entries.length - 1]?.author === "agent" ? "human" : "agent",
+  }
+}
+
+/** Threads and their syntax findings off ONE tree walk; `markers` come from the caller so this module never re-parses footnotes. */
+export const collectThreads = (
+  content: string,
+  tree: Root,
+  markers: readonly ThreadMarker[],
+): { readonly threads: readonly Thread[]; readonly findings: readonly SteeringFinding[] } => {
+  const lines = content.split(/\r?\n/)
+  const threads: Thread[] = []
+  const findings: SteeringFinding[] = []
+  const walk = (node: { type: string; children?: unknown }): void => {
+    const def = node.type === "footnoteDefinition" ? (node as unknown as Def["node"]) : undefined
+    const list = def && isThreadBody(content, def.children)
+    if (def && list) {
+      const name = def.label ?? def.identifier ?? ""
+      const report: Report = (message, from, to) => {
+        findings.push({
+          message: `Footnote thread "[^${name}]": ${message}`,
+          line: from,
+          range: spanRange(lines, from, to),
+        })
+      }
+      threads.push(threadOf(content, def, list, markers, report))
+    }
+    const children = node.children as readonly (typeof node)[] | undefined
+    if (children) children.forEach(walk)
+  }
+  walk(tree)
+  return { threads, findings }
+}

package/src/steering/contract.test.ts

@@ -0,0 +1,264 @@
+/// <reference types="vite/client" />
+import { describe, expect, it } from "vitest"
+import {
+  applySteeringEdits,
+  freeFormFormat,
+  parseCodeThreads,
+  parseFootnotes,
+  parseThreads,
+  reviewNotes,
+  reviewRisks,
+  steeringFormatFor,
+  stripCodeThreads,
+  type SteeringAnchor,
+  type SteeringFormat,
+  type SteeringViewNode,
+} from "./index.js"
+
+// The format contract (see FORMATS.md). Fixtures are files steering already
+// reads; a change that makes one of these fail stops older committed files
+// from being read the same way. Loaded by the bundler, so steering stays
+// free of filesystem access even in its tests.
+const FIXTURES = import.meta.glob<string>("./fixtures/**/*", {
+  query: "?raw",
+  import: "default",
+  eager: true,
+})
+
+const fixture = (path: string): string => {
+  const content = FIXTURES[`./fixtures/${path}`]
+  if (content === undefined) throw new Error(`no fixture ${path}`)
+  return content
+}
+
+const FORMATS: readonly (readonly [dir: string, format: SteeringFormat, ticks: boolean])[] = [
+  ["qa", steeringFormatFor("qa")!, true],
+  ["review", steeringFormatFor("review")!, true],
+  ["free-form", freeFormFormat, false],
+]
+
+const nodesOf = (nodes: readonly SteeringViewNode[]): readonly SteeringViewNode[] =>
+  nodes.flatMap((n) => [n, ...nodesOf(n.children ?? []), ...nodesOf(n.body ?? [])])
+
+// Presentation-only fields: how a node is rendered, not what the file says.
+const PRESENTATION = new Set(["block", "inline", "detailInline"])
+
+/** What `view` reads out of a file, minus presentation — pinned by `<fixture>.read.json`. */
+const readOf = (format: SteeringFormat, content: string): unknown =>
+  JSON.parse(
+    JSON.stringify(format.view(content), (key, value: unknown) =>
+      PRESENTATION.has(key) ? undefined : value,
+    ),
+  )
+
+/** Every note the document carries: thread entries and one-shot footnote bodies. */
+const notesIn = (content: string): readonly string[] => [
+  ...parseThreads(content).flatMap((t) => t.entries.map((e) => e.text)),
+  ...parseFootnotes(content).definitions.map((d) => d.body),
+]
+
+const write = (
+  content: string,
+  result: ReturnType<SteeringFormat["apply"]>,
+  what: string,
+): string => {
+  if (!result.ok) throw new Error(`${what} refused: ${result.reason}`)
+  return applySteeringEdits(content, result.edits)
+}
+
+describe.each(FORMATS)("the %s format", (dir, format, ticks) => {
+  const files = Object.keys(FIXTURES)
+    .map((key) => key.slice("./fixtures/".length))
+    .filter((path) => path.startsWith(`${dir}/`) && path.endsWith(".md"))
+
+  it("has fixtures", () => {
+    expect(files.length).toBeGreaterThan(0)
+  })
+
+  it(ticks ? "has a fixture with a ticked box" : "has no ticks to read", () => {
+    const ticked = files.some((path) =>
+      nodesOf(format.view(fixture(path)).nodes).some((n) => n.checked),
+    )
+    expect(ticked).toBe(ticks)
+  })
+
+  describe.each(files)("%s", (path) => {
+    const content = fixture(path)
+
+    it("reads clean", () => {
+      expect(format.validate(content)).toEqual([])
+    })
+
+    it("parses to its pinned read", () => {
+      expect(readOf(format, content)).toEqual(
+        JSON.parse(fixture(path.replace(/\.md$/, ".read.json"))),
+      )
+    })
+
+    if (ticks)
+      it("round-trips every tick: writing back what was read leaves the bytes unchanged", () => {
+        for (const node of nodesOf(format.view(content).nodes)) {
+          if (node.checked === undefined || node.anchor.kind === "chunk") continue
+          const anchor: SteeringAnchor = node.anchor
+          const same = write(
+            content,
+            format.apply(content, anchor, { checked: node.checked }),
+            "same",
+          )
+          expect(same).toBe(content)
+          if (!node.checked) continue
+          const off = write(content, format.apply(content, anchor, { checked: false }), "off")
+          expect(off).not.toBe(content)
+          expect(write(off, format.apply(off, anchor, { checked: true }), "on")).toBe(content)
+        }
+      })
+
+    it("round-trips a note at every anchor: it reads back, and the document stays clean", () => {
+      const text = "A note written through the contract test."
+      const anchors = nodesOf(format.view(content).nodes).map((n) => n.anchor)
+      expect(anchors.length).toBeGreaterThan(0)
+      for (const anchor of anchors) {
+        const noted = write(content, format.annotate(content, anchor, text), JSON.stringify(anchor))
+        expect(notesIn(noted), JSON.stringify(anchor)).toContain(text)
+        expect(format.validate(noted), JSON.stringify(anchor)).toEqual([])
+      }
+    })
+  })
+})
+
+describe("footnote threads, shared by every markdown format", () => {
+  it.each([
+    [
+      "review/ticked.md",
+      [
+        [
+          "th1",
+          ["Does this also cover the writer?", "No, the writer keeps the input's line endings."],
+          "human",
+        ],
+      ],
+    ],
+    [
+      "qa/answered.md",
+      [
+        [
+          "th1",
+          ["Is this the git common dir?", "Yes, the directory every worktree shares."],
+          "human",
+        ],
+      ],
+    ],
+    ["free-form/notes.md", [["th1", ["Should this become a plan?"], "agent"]]],
+  ])("%s parses its threads", (path, expected) => {
+    expect(
+      parseThreads(fixture(path)).map((t) => [t.name, t.entries.map((e) => e.text), t.waitingOn]),
+    ).toEqual(expected)
+  })
+})
+
+describe("review notes, the review → fix hand-off", () => {
+  const baseline = fixture("review-notes/baseline.md")
+  const noted = fixture("review-notes/noted.md")
+  const review = steeringFormatFor("review")!
+
+  it("both sides read clean as review documents", () => {
+    expect(review.validate(baseline)).toEqual([])
+    expect(review.validate(noted)).toEqual([])
+  })
+
+  it("reads chunk prose, pointer and footnote notes in document order, never a thread", () => {
+    expect(reviewNotes(baseline, noted)).toEqual([
+      {
+        id: "note-1",
+        kind: "chunk",
+        anchor: "Parser accepts CRLF",
+        before: "**Line endings are normalized before the split.**",
+        text: "**Line endings are normalized before the split.** Also normalize in the writer.",
+      },
+      {
+        id: "note-2",
+        kind: "pointer",
+        anchor: "Parser accepts CRLF ./src/parse.ts#30-31",
+        before: "Risk: a lone `\\r` is still kept as content",
+        text: "Risk: a lone `\\r` is still kept as content. Treat it as a line break too.",
+      },
+      {
+        id: "note-3",
+        kind: "footnote",
+        anchor: "- [x] ./src/parse.test.ts#1-40 — one case per line ending[^fn1]",
+        before: "",
+        text: "Add a mixed-endings case.",
+      },
+    ])
+  })
+
+  it("reads the reviewer's Risk: pointer notes", () => {
+    expect(reviewRisks(baseline)).toEqual([
+      {
+        id: "risk-1",
+        anchor: "Parser accepts CRLF ./src/parse.ts#30-31",
+        text: "Risk: a lone `\\r` is still kept as content",
+      },
+    ])
+  })
+
+  it("an unchanged document carries no notes", () => {
+    expect(reviewNotes(noted, noted)).toEqual([])
+  })
+
+  it("round-trips: a note written at a hunk reads back as a thread, never as a review note", () => {
+    const text = "Rename this."
+    const after = write(
+      baseline,
+      review.annotate(baseline, { kind: "hunk", chunkIndex: 1, index: 0 }, text),
+      "annotate",
+    )
+    expect(reviewNotes(baseline, after)).toEqual([])
+    expect(parseThreads(after).map((t) => [t.entries.map((e) => e.text), t.waitingOn])).toEqual([
+      [[text], "agent"],
+    ])
+  })
+})
+
+describe("code threads", () => {
+  const source = /```ts\n([\s\S]*?)```/.exec(fixture("code-threads/cache.ts.md"))![1]!
+  const stripped = fixture("code-threads/cache.stripped.ts.txt")
+
+  it("parses each H:/A: comment run as a thread", () => {
+    expect(parseCodeThreads("cache.ts", source)).toEqual({
+      threads: [
+        {
+          path: "cache.ts",
+          line: 2,
+          endLine: 4,
+          entries: [
+            {
+              author: "me",
+              text: "Why not the modification time? A checkout could keep it stable.",
+              line: 2,
+            },
+            { author: "agent", text: "A checkout rewrites every mtime.", line: 4 },
+          ],
+          waitingOn: "human",
+        },
+        {
+          path: "cache.ts",
+          line: 8,
+          endLine: 8,
+          entries: [{ author: "me", text: "Should this honour $XDG_CACHE_HOME?", line: 8 }],
+          waitingOn: "agent",
+        },
+      ],
+      findings: [],
+    })
+  })
+
+  it("strips threads and keeps ordinary comments", () => {
+    expect(stripCodeThreads("cache.ts", source)).toBe(stripped)
+  })
+
+  it("round-trips: a thread-free file strips to itself", () => {
+    expect(stripCodeThreads("cache.ts", stripped)).toBe(stripped)
+    expect(parseCodeThreads("cache.ts", stripped).threads).toEqual([])
+  })
+})

package/src/steering/fixtures/code-threads/cache.stripped.ts.txt

@@ -0,0 +1,6 @@
+// The cache key is the content hash.
+export const cacheKey = (content: string): string =>
+  hash(content)
+
+export const cacheDir = (root: string): string =>
+  join(root, ".cache")

package/src/steering/fixtures/code-threads/cache.ts.md

@@ -0,0 +1,15 @@
+A TypeScript source with two code threads. It lives in markdown because gtd
+scans every other file in a change for live threads.
+
+```ts
+// The cache key is the content hash.
+export const cacheKey = (content: string): string =>
+  // H: Why not the modification time? A checkout
+  // could keep it stable.
+  // A: A checkout rewrites every mtime.
+  hash(content)
+
+export const cacheDir = (root: string): string =>
+  // H: Should this honour $XDG_CACHE_HOME?
+  join(root, ".cache")
+```

package/src/steering/fixtures/free-form/notes.md

@@ -0,0 +1,12 @@
+# Notes
+
+Plain prose with no structure to validate.[^th1]
+
+- a list item
+- another one
+
+```sh
+npm test
+```
+
+[^th1]: - H: Should this become a plan?

package/src/steering/fixtures/free-form/notes.read.json

@@ -0,0 +1,42 @@
+{
+  "nodes": [
+    {
+      "title": "Notes",
+      "anchor": {
+        "kind": "paragraph",
+        "line": 0
+      }
+    },
+    {
+      "title": "Plain prose with no structure to validate.",
+      "anchor": {
+        "kind": "paragraph",
+        "line": 2
+      },
+      "thread": {
+        "name": "th1",
+        "entries": [
+          {
+            "author": "me",
+            "text": "Should this become a plan?"
+          }
+        ],
+        "waitingOn": "agent"
+      }
+    },
+    {
+      "title": "a list item another one",
+      "anchor": {
+        "kind": "paragraph",
+        "line": 4
+      }
+    },
+    {
+      "title": "npm test",
+      "anchor": {
+        "kind": "paragraph",
+        "line": 7
+      }
+    }
+  ]
+}

package/src/steering/fixtures/qa/answered.md

@@ -0,0 +1,23 @@
+Move the cache to a shared directory.
+
+## Open Questions
+
+### Where does the cache live?
+
+The cache is per worktree today.
+
+- [ ] In `$XDG_CACHE_HOME`
+  - Shared by every worktree
+- [x] Next to the repository[^th1]
+  - Survives a worktree removal
+- [ ] _your answer_
+
+[^th1]:
+    - H: Is this the git common dir?
+    - A: Yes, the directory every worktree shares.
+
+### How is it invalidated?
+
+- [ ] By content hash
+- [ ] By modification time
+- [x] Keep both, hash wins on conflict