@pmelab/gtd 24.0.0 → 24.2.0

package/src/steering/MarkdownTree.ts

@@ -0,0 +1,260 @@
+import { fromMarkdown } from "mdast-util-from-markdown"
+import { gfmAutolinkLiteralFromMarkdown } from "mdast-util-gfm-autolink-literal"
+import { gfmFootnoteFromMarkdown } from "mdast-util-gfm-footnote"
+import { gfmStrikethroughFromMarkdown } from "mdast-util-gfm-strikethrough"
+import { gfmTaskListItemFromMarkdown } from "mdast-util-gfm-task-list-item"
+import { gfmAutolinkLiteral } from "micromark-extension-gfm-autolink-literal"
+import { gfmFootnote } from "micromark-extension-gfm-footnote"
+import { gfmStrikethrough } from "micromark-extension-gfm-strikethrough"
+import { gfmTaskListItem } from "micromark-extension-gfm-task-list-item"
+import type { Heading, ListItem, Node, Root, RootContent } from "mdast"
+import type { SteeringOutlineNode } from "./Outline.js"
+
+/** The same 0-based shape the LSP protocol uses, everywhere a converted mdast position ends up. */
+export interface LspPosition {
+  readonly line: number
+  readonly character: number
+}
+
+/**
+ * How many times `parseMarkdown` has actually run `fromMarkdown` (memo hits
+ * excluded) — the only way "one parse per document" is assertable, since
+ * timing is not.
+ */
+let parseCount = 0
+export const getParseCount = (): number => parseCount
+
+/** One-entry memo: the last content string parsed and its tree, so re-validating the same document never re-parses. */
+let memoContent: string | undefined
+let memoTree: Root | undefined
+
+/**
+ * Parses `content` into an mdast tree with all four GFM extensions wired —
+ * footnotes, task-list checkboxes, strikethrough, and bare-URL autolinks.
+ * `gfmTable` is deliberately NOT wired: tables are block-level and outside
+ * this parser's scope. Both the micromark and the mdast half of each
+ * extension must be CALLED (`gfmTaskListItem()`, not `gfmTaskListItem`);
+ * passing the bare function is accepted silently and yields, e.g.,
+ * `listItem.checked === null` on every item instead of a real checkbox —
+ * the same trap applies to every extension pair here. Total: `fromMarkdown`
+ * never throws, so this never does either.
+ *
+ * Memoized on the content string, one entry deep — the last document parsed
+ * stays cached so one `validate` call's footnote pass and format pass share
+ * a single parse; a different string evicts it.
+ */
+export const parseMarkdown = (content: string): Root => {
+  if (memoContent === content && memoTree !== undefined) return memoTree
+  const tree = fromMarkdown(content, {
+    extensions: [gfmFootnote(), gfmTaskListItem(), gfmStrikethrough(), gfmAutolinkLiteral()],
+    mdastExtensions: [
+      gfmFootnoteFromMarkdown(),
+      gfmTaskListItemFromMarkdown(),
+      gfmStrikethroughFromMarkdown(),
+      gfmAutolinkLiteralFromMarkdown(),
+    ],
+  })
+  parseCount += 1
+  memoContent = content
+  memoTree = tree
+  return tree
+}
+
+/** mdast gives 1-based line/column; the LSP wants 0-based line/character. Every `- 1` lives here. */
+export const toLspPosition = (point: {
+  readonly line: number
+  readonly column: number
+}): LspPosition => ({
+  line: point.line - 1,
+  character: point.column - 1,
+})
+
+/**
+ * Converts an absolute 0-based character offset into `content` to a 0-based
+ * LSP line/character — the general form a caller needs for a position that
+ * isn't a tree node's own point (a hit found by scanning a `text` node's own
+ * source slice for a pattern the parser didn't turn into a node, say).
+ */
+export const toLspPositionFromOffset = (content: string, offset: number): LspPosition => {
+  let line = 0
+  let lineStart = 0
+  for (let i = 0; i < offset; i += 1) {
+    if (content[i] === "\n") {
+      line += 1
+      lineStart = i + 1
+    }
+  }
+  return { line, character: offset - lineStart }
+}
+
+/** Collects every descendant `footnoteReference` node's own `[start, end)` source-offset range, in document order. */
+const footnoteReferenceRanges = (node: Node): Array<readonly [number, number]> => {
+  const ranges: Array<readonly [number, number]> = []
+  const walk = (n: Node): void => {
+    if (n.type === "footnoteReference" && n.position) {
+      ranges.push([n.position.start.offset!, n.position.end.offset!])
+    }
+    const children = (n as { children?: readonly Node[] }).children
+    if (children) children.forEach(walk)
+  }
+  walk(node)
+  return ranges.sort((a, b) => a[0] - b[0])
+}
+
+/**
+ * `node`'s own source slice, with every descendant `footnoteReference`
+ * range excised and every run of whitespace collapsed to a single space.
+ * Inline code, links, and emphasis are untouched — only footnote markers are
+ * ever cut out, because a marker read back out of a definition's or a
+ * heading's body is noise no caller wants.
+ */
+export const sourceText = (content: string, node: Node): string => {
+  if (!node.position) return ""
+  const start = node.position.start.offset!
+  const end = node.position.end.offset!
+  let result = ""
+  let cursor = start
+  for (const [rangeStart, rangeEnd] of footnoteReferenceRanges(node)) {
+    if (rangeStart < cursor) continue
+    result += content.slice(cursor, rangeStart)
+    cursor = rangeEnd
+  }
+  result += content.slice(cursor, end)
+  return result.replace(/\s+/g, " ").trim()
+}
+
+/** The top-level block of `tree` that contains 0-based `line`, or `undefined` past the end of the document. */
+export const blockNodeAt = (tree: Root, line: number): RootContent | undefined =>
+  tree.children.find((node) => {
+    if (!node.position) return false
+    return line >= node.position.start.line - 1 && line <= node.position.end.line - 1
+  })
+
+/** Every `listItem` under `node` with `checked !== null` (a real task-list item), at any nesting depth. */
+export const taskItems = (node: Node): readonly ListItem[] => {
+  const items: ListItem[] = []
+  const walk = (n: Node): void => {
+    if (n.type === "listItem" && (n as ListItem).checked !== null) items.push(n as ListItem)
+    const children = (n as { children?: readonly Node[] }).children
+    if (children) children.forEach(walk)
+  }
+  walk(node)
+  return items
+}
+
+/** One whole 0-based `line`'s own LSP range, start to end of its text. */
+export const lineRange = (
+  lines: readonly string[],
+  line: number,
+): { readonly start: LspPosition; readonly end: LspPosition } => ({
+  start: { line, character: 0 },
+  end: { line, character: (lines[line] ?? "").length },
+})
+
+/** An LSP range spanning whole lines `startLine` through `endLine` inclusive. */
+export const spanRange = (
+  lines: readonly string[],
+  startLine: number,
+  endLine: number,
+): { readonly start: LspPosition; readonly end: LspPosition } => ({
+  start: { line: startLine, character: 0 },
+  end: { line: endLine, character: (lines[endLine] ?? "").length },
+})
+
+/** One footnote marker rendered as an outline leaf: `[^name] <body>`. Shared by both built-in descriptors — `qa` and `review` render footnotes identically, only the surrounding tree differs. */
+export const footnoteLeaf = (
+  lines: readonly string[],
+  definitionByName: ReadonlyMap<string, string>,
+  marker: { readonly name: string; readonly line: number },
+): SteeringOutlineNode => ({
+  name: `[^${marker.name}] ${definitionByName.get(marker.name) ?? ""}`.trim(),
+  range: lineRange(lines, marker.line),
+  selectionRange: lineRange(lines, marker.line),
+  leaf: true,
+})
+
+/** A parsed `##`/`###` block shared by both descriptors' own block-splitting: a heading node plus its raw body block nodes, up to the next heading. */
+export interface HeadingBlock {
+  readonly heading: Heading
+  readonly body: readonly RootContent[]
+}
+
+/**
+ * One heading block's own outline range end: its last body block's own end
+ * line, or the heading's own end line for a bare/empty block — never "the
+ * next heading's line minus one", which would swallow trailing blank lines
+ * (or, worse, unrelated content) between this block and the next.
+ */
+export const blockEndLine = (block: HeadingBlock): number => {
+  const last = [...block.body].reverse().find((n) => n.position !== undefined)
+  return toLspPosition((last?.position ?? block.heading.position!).end).line
+}
+
+/**
+ * A depth-N heading's own text (footnote references excised via
+ * `sourceText`, internal whitespace collapsed) — `""` for a bare heading with
+ * no inline content. Built from the heading's own CHILDREN span, never the
+ * heading node's own position: that starts at the `#` run, which would pull
+ * the marker and its separating space into `sourceText`'s slice. `strip`
+ * (default: identity) runs on the extracted text before the final whitespace
+ * collapse — `qa`'s own `[^name]`-marker stripping needs this second pass
+ * since removing a marker can leave a double space `sourceText` already
+ * collapsed once, before the strip ever ran.
+ */
+export const headingText = (
+  content: string,
+  heading: Heading,
+  strip: (text: string) => string = (text) => text,
+): string => {
+  const children = heading.children
+  if (children.length === 0) return ""
+  const first = children[0]!
+  const last = children[children.length - 1]!
+  if (!first.position || !last.position) return ""
+  const synthetic = {
+    type: "heading",
+    children,
+    position: { start: first.position.start, end: last.position.end },
+  }
+  return strip(sourceText(content, synthetic)).replace(/\s+/g, " ").trim()
+}
+
+/**
+ * Every depth-`depth` (default 2, `## `) heading's own text, in document
+ * order — the section list a dynamic-count `judge:` template (one noul per
+ * section/finding) counts over. Top-level only (`tree.children`, not nested
+ * inside a list or blockquote), matching how a package/feedback file's own
+ * `## ` headings are always written at the document's own top level.
+ */
+export interface HeadingSection {
+  readonly title: string
+  /** The section's source, heading line included, up to the next heading of the same or a higher level. */
+  readonly body: string
+}
+
+/** Every top-level depth-`depth` section of `content`, with its source text, in document order. */
+export const headingSectionBodies = (content: string, depth = 2): readonly HeadingSection[] => {
+  const lineStart = (offset: number): number => content.lastIndexOf("\n", offset - 1) + 1
+  const tree = parseMarkdown(content)
+  const boundaries = tree.children.filter(
+    (node): node is Heading => node.type === "heading" && node.depth <= depth,
+  )
+  return boundaries.flatMap((heading, i) => {
+    if (heading.depth !== depth || heading.position === undefined) return []
+    const next = boundaries[i + 1]?.position?.start.offset
+    const end = next === undefined ? content.length : lineStart(next)
+    return [
+      {
+        title: headingText(content, heading),
+        body: content.slice(lineStart(heading.position.start.offset ?? 0), end).trimEnd(),
+      },
+    ]
+  })
+}
+
+export const headingSections = (content: string, depth = 2): readonly string[] => {
+  const tree = parseMarkdown(content)
+  return tree.children
+    .filter((node): node is Heading => node.type === "heading" && node.depth === depth)
+    .map((heading) => headingText(content, heading))
+}

package/src/steering/Outline.ts

@@ -0,0 +1,19 @@
+/**
+ * One node of a format's outline tree. `leaf: true` is the only distinction
+ * a node carries — whatever icon or symbol kind an editor shows is the LSP
+ * translation's call, not this module's.
+ */
+export interface SteeringOutlineNode {
+  readonly name: string
+  readonly detail?: string
+  readonly range: {
+    readonly start: { readonly line: number; readonly character: number }
+    readonly end: { readonly line: number; readonly character: number }
+  }
+  readonly selectionRange: {
+    readonly start: { readonly line: number; readonly character: number }
+    readonly end: { readonly line: number; readonly character: number }
+  }
+  readonly leaf?: true
+  readonly children?: readonly SteeringOutlineNode[]
+}

package/src/steering/SteeringFormat.test.ts

@@ -0,0 +1,91 @@
+import { describe, expect, it } from "vitest"
+import { steeringFormatFor } from "./index.js"
+import type { SteeringFinding, SteeringFormat } from "./SteeringFormat.js"
+
+const QA_FORMAT = steeringFormatFor("qa")!
+const REVIEW_FORMAT = steeringFormatFor("review")!
+
+/**
+ * `SteeringFinding`'s two range invariants ("a range is meaningless without a
+ * `line`"; "a range's start line equals `line`") are declared in the type's
+ * own doc comment, not enforced by the type itself — a new finding site (or a
+ * new format entirely) can violate either with the whole suite green unless
+ * something actually asserts it. This drives every built-in format's
+ * `validate` over malformed content and checks the invariant on every finding
+ * returned, so it catches a future violation regardless of which site
+ * introduces it.
+ */
+const assertRangeInvariants = (findings: readonly SteeringFinding[]): void => {
+  for (const finding of findings) {
+    if (finding.range === undefined) continue
+    expect(finding.line, `range without a line: ${JSON.stringify(finding)}`).not.toBeUndefined()
+    expect(finding.range.start.line, `range.start.line !== line: ${JSON.stringify(finding)}`).toBe(
+      finding.line,
+    )
+  }
+}
+
+const MALFORMED_SAMPLES: readonly (readonly [string, SteeringFormat, string])[] = [
+  [
+    "qa: bare heading, misordered sections, indented dropped heading/option",
+    QA_FORMAT,
+    [
+      "## Answered Questions",
+      "",
+      "### Answered already",
+      "",
+      "Use tRPC.",
+      "",
+      "## Open Questions",
+      "",
+      "###",
+      "",
+      "    ### dropped heading",
+      "",
+      "    - [ ] dropped option",
+      "",
+    ].join("\n"),
+  ],
+  ["review: missing header/base, no chunks", REVIEW_FORMAT, "Just some text\n"],
+  [
+    "review: chunk with no pointers, wrong first block",
+    REVIEW_FORMAT,
+    [
+      "Not a heading first.",
+      "",
+      "# Review: abc1234",
+      "<!-- base: abc1234def5678901234567890123456789abcd -->",
+      "",
+      "## Untouched chunk",
+      "",
+      "no pointers here.",
+      "",
+    ].join("\n"),
+  ],
+  [
+    "qa: an orphan and duplicate footnote marker/definition",
+    QA_FORMAT,
+    [
+      "## Open Questions",
+      "",
+      "### Which option?",
+      "",
+      "- [ ] Option A[^missing]",
+      "- [ ] Option B[^dup]",
+      "- [ ] _your answer_",
+      "",
+      "[^dup]: first",
+      "",
+      "[^dup]: second",
+      "",
+    ].join("\n"),
+  ],
+]
+
+describe("SteeringFinding range invariants", () => {
+  it.each(MALFORMED_SAMPLES)("%s", (_label, format, content) => {
+    const findings = format.validate(content)
+    expect(findings.length).toBeGreaterThan(0)
+    assertRangeInvariants(findings)
+  })
+})

package/src/steering/SteeringFormat.ts

@@ -0,0 +1,267 @@
+// `InlineNode` aside, pure vocabulary: shared by the registry and the LSP's
+// translation layer without either pulling in the other's dependencies.
+import type { InlineNode } from "./Inline.js"
+import type { SteeringOutlineNode } from "./Outline.js"
+
+export type { SteeringOutlineNode } from "./Outline.js"
+
+/** The same shape `vscode-languageserver`'s `TextEdit` carries, kept format-side so this module stays protocol-independent. */
+export interface SteeringEdit {
+  readonly range: {
+    readonly start: { readonly line: number; readonly character: number }
+    readonly end: { readonly line: number; readonly character: number }
+  }
+  readonly newText: string
+}
+
+export interface SteeringAction {
+  readonly title: string
+  readonly edits: readonly SteeringEdit[]
+}
+
+/** A go-to-definition target. `path` absent means "this same document" (a footnote jump); `character` defaults to 0. */
+export interface SteeringPointer {
+  readonly path?: string
+  readonly line: number
+  readonly character?: number
+}
+
+/**
+ * One validation finding. `line` is 0-based, absent for a document-level
+ * finding. `range` is independently optional, never a discriminated union:
+ * a shell `validate:` command's output is a bare `{ message }` with no
+ * position at all. That a `range` implies a `line` is pinned by tests.
+ */
+export interface SteeringFinding {
+  readonly message: string
+  readonly line?: number
+  readonly range?: {
+    readonly start: { readonly line: number; readonly character: number }
+    readonly end: { readonly line: number; readonly character: number }
+  }
+}
+
+/** A hunk pointer's document-link target: `range` covers the pointer token itself; `line` is 0-based, so a `#42` suffix resolves down by one and a bare `./path` lands at 0. */
+export interface SteeringLink {
+  readonly range: {
+    readonly start: { readonly line: number; readonly character: number }
+    readonly end: { readonly line: number; readonly character: number }
+  }
+  readonly path: string
+  readonly line: number
+}
+
+/**
+ * Where an `annotate` call attaches a note. A client reads one off `view` and
+ * hands it straight back, never inventing indices. Deliberately closed and
+ * format-agnostic: `review`'s chunk/hunk and `qa`'s question/option are the
+ * same two things here (a container and one of its numbered children), plus
+ * `paragraph`, which a client resolves from its cursor rather than the view.
+ */
+export type SteeringAnchor =
+  | { readonly kind: "chunk"; readonly index: number }
+  | { readonly kind: "hunk"; readonly chunkIndex: number; readonly index: number }
+  | { readonly kind: "question"; readonly index: number }
+  | { readonly kind: "option"; readonly questionIndex: number; readonly index: number }
+  | { readonly kind: "paragraph"; readonly line: number }
+
+/** `annotate`'s result: the edits to splice in, or a typed refusal — a stale/unresolvable `anchor`, or a derived note id that already names a definition. */
+export type SteeringAnnotateResult =
+  | { readonly ok: true; readonly edits: readonly SteeringEdit[] }
+  | { readonly ok: false; readonly reason: "anchor-not-found" | "id-collision" }
+
+/** One item of a `list` block's `items` tree — recursive to whatever depth the source markdown nests. */
+export interface BlockListItem {
+  /** This item's own text, EXCLUDING any nested list under it (that's `items`, below). */
+  readonly text: string
+  /** Set only for a task-list item (`- [ ]`/`- [x]`) — absent for a plain list item. */
+  readonly checked?: boolean
+  /** A nested list directly under this item, recursively. Absent when this item has none. */
+  readonly items?: readonly BlockListItem[]
+  /** `text`'s own inline structure — the shared renderer walks this instead of `text` when present. Populated at every nesting depth. */
+  readonly inline?: readonly InlineNode[]
+}
+
+export interface SteeringViewThread {
+  readonly name: string
+  readonly entries: readonly { readonly author: "me" | "agent"; readonly text: string }[]
+  readonly waitingOn: "human" | "agent"
+}
+
+/**
+ * One node of a format's `view`: a generic container/item tree, the SAME
+ * shape for every format. Deliberately never a closed per-format union — a
+ * third format would have to pretend to be one of the two, or this file would
+ * grow a member, and a user-declared mode is supposed to light up the phone
+ * UI for free. Every field beyond `title`/`anchor` is optional because each
+ * format populates a different subset.
+ */
+export interface SteeringViewNode {
+  /** This node's own display name — a chunk's/question's title, an option's/hunk's own label. */
+  readonly title: string
+  /** A longer description or summary, when the format has one (a chunk's description, a question's first body line). */
+  readonly detail?: string
+  /** A free-form status label, when the format has one (`qa`'s `"open"`/`"answered"`). */
+  readonly status?: string
+  /** `true` when this node's own condition is fully satisfied (`qa`'s answered-question flag) — distinct from `checked`, which is a per-item tick. */
+  readonly answered?: boolean
+  /** This node's own checkbox state, when it has one (a hunk's tick, an option's tick). */
+  readonly checked?: boolean
+  /** An attached one-shot note's text, when this node carries one. A thread fills `thread` instead, never this. */
+  readonly note?: string
+  /** An attached footnote thread — a conversation, not a flat string. `waitingOn: "human"` means the agent spoke last. */
+  readonly thread?: SteeringViewThread
+  /**
+   * `detail`'s own inline counterpart, for the three compact rows (a chunk
+   * card, a hunk's description row, a plan row): built server-side by
+   * concatenating each contributing block's own inline run with a single
+   * space `text` separator, mirroring exactly how `detail` itself joins.
+   * Block structure stays flattened — a list contributes its items' runs
+   * joined by spaces, a fence contributes its plain text — and an image
+   * collapses to its alt text unconditionally, so a compact row can never
+   * fire a remote fetch. Set by `review.ts` (chunk, hunk) and `qa.ts`
+   * (question); absent wherever `detail` itself is absent.
+   */
+  readonly detailInline?: readonly InlineNode[]
+  /** A file path this node points at, when it has one (a `review` hunk). */
+  readonly path?: string
+  /** A 1-based line in `path` this node points at, when it has one. */
+  readonly line?: number
+  /** A 1-based END line in `path`, alongside `line`, for a `review` hunk pointer carrying a range (`#<start>-<end>`). Absent whenever `line` is absent, or for a bare `#<line>` pointer with no range. */
+  readonly endLine?: number
+  /** Where `annotate` attaches a NEW note to this node. */
+  readonly anchor: SteeringAnchor
+  readonly children?: readonly SteeringViewNode[]
+  /**
+   * A node's body, a SIBLING of `children` and never a reuse of it: a `qa`
+   * question's `children` are its options, so a body block riding in that
+   * array would render as a phantom option.
+   *
+   * Set by `qa` questions, `review` chunks, and a `qa` OPTION node too, where
+   * it is that option's own impacts — read-only, since the write-back span an
+   * answer commits through never reaches past the option's label. `[]` — not
+   * absent — for a question/chunk with no body, so `body !== undefined` is
+   * never "this is a question"; absent entirely on the free-text slot, which
+   * never carries impacts.
+   */
+  readonly body?: readonly SteeringViewNode[]
+  /**
+   * The document structure a prose block carries. NO new anchor kind: whatever
+   * `kind` it names, the block still anchors as `{kind: "paragraph", line}`. A
+   * client that ignores this field entirely still has `title` to render.
+   */
+  readonly block?: {
+    readonly kind: "paragraph" | "heading" | "list" | "code" | "blockquote"
+    /** Heading level, 1–6. Set only for `kind: "heading"`. */
+    readonly depth?: number
+    /** Set only for `kind: "list"`. */
+    readonly ordered?: boolean
+    /** This list's own top-level items, recursive. Set only for `kind: "list"`. */
+    readonly items?: readonly BlockListItem[]
+    /** The fenced code block's info-string language, when it has one. Set only for `kind: "code"`. */
+    readonly language?: string
+    /**
+     * This block's own text, verbatim. `qa`/`review` set it only for
+     * `kind: "code"`/`"blockquote"` (the code block's body / the
+     * blockquote's own text); the free-form format (`freeform.ts`) sets it
+     * for EVERY kind — the block's own raw source bytes, unmodified — since
+     * it has no structure of its own to fall back on and an edit there
+     * replaces a block's whole source span with this same shape of text.
+     */
+    readonly text?: string
+    /**
+     * This block's own inline structure — set only for `kind: "paragraph"`,
+     * `"heading"` and `"blockquote"` (a `code` block's `text` has none; a
+     * `list` block's own items each carry their own `inline` instead, on
+     * `BlockListItem`). The shared client renderer walks this instead of
+     * `title`/`text` when present, so `**bold**` and friends survive as real
+     * structure rather than literal markers.
+     */
+    readonly inline?: readonly InlineNode[]
+  }
+}
+
+/** A format's whole domain projection of `content`. The server serializes this without importing a format module or switching on the mode name. */
+export interface SteeringView {
+  readonly header?: string
+  readonly nodes: readonly SteeringViewNode[]
+}
+
+/**
+ * One steering-file FORMAT's whole behavior. `validate` returns the same
+ * `findings` shape `gtd validate` and the capture gate consume (empty =
+ * valid); `pointerAt` is absent for a format with nothing to jump to.
+ */
+export interface SteeringFormat {
+  /**
+   * The clearest minimal document that satisfies this format's own `validate`.
+   * `ModeContradiction.ts` round-trips this exact string through a mode's
+   * `format:` command to catch a formatter that breaks its own validator, so
+   * it is deliberately NOT authored to survive any particular formatter — a
+   * reflow that invalidates it IS the contradiction that check exists to find.
+   */
+  readonly sample: string
+  readonly validate: (content: string) => readonly SteeringFinding[]
+  readonly outline: (content: string) => readonly SteeringOutlineNode[]
+  readonly actions: (
+    content: string,
+    range: {
+      readonly start: { readonly line: number; readonly character: number }
+      readonly end: { readonly line: number; readonly character: number }
+    },
+  ) => readonly SteeringAction[]
+  readonly pointerAt?: (
+    content: string,
+    position: { readonly line: number; readonly character: number },
+  ) => SteeringPointer | undefined
+  /** Every hunk-pointer document link in `content`. Walks the parsed hunks directly: `pointerAt` is one call per line and cannot yield the token's own range. */
+  readonly documentLinks?: (content: string) => readonly SteeringLink[]
+  /** MANDATORY, so a user-declared mode lights up the phone UI the moment it registers one — the server reads a `view` rather than importing a format module. */
+  readonly view: (content: string) => SteeringView
+  /**
+   * Attaches a note at `anchor`. `text` is never a placeholder — unlike the
+   * LSP's "add a footnote" action, which seeds an empty definition for a human
+   * to fill in, a server-attached note already has its real body, so the
+   * document it produces validates clean immediately.
+   */
+  readonly annotate: (
+    content: string,
+    anchor: SteeringAnchor,
+    text: string,
+  ) => SteeringAnnotateResult
+  /**
+   * The checkbox-writing counterpart to `annotate`, sharing its refusal shape.
+   * `qa`'s `option` anchor is RADIO: ticking one unticks every sibling, and
+   * ticking the free-text slot with `text` set also replaces its label, in ONE
+   * edit set. `review`'s `chunk` anchor sets every hunk beneath it to the
+   * caller's stated target state — never a majority-flip heuristic.
+   */
+  readonly apply: (
+    content: string,
+    anchor: SteeringAnchor,
+    opts: { readonly checked?: boolean; readonly text?: string },
+  ) => SteeringAnnotateResult
+  /**
+   * Resets only THIS format's own read-progress ticks. `qa`'s checkbox ticks
+   * ARE its answers — never auto-cleared; `review`'s hunk ticks are
+   * read-progress, cleared on every land. Mandatory so a format can never
+   * accidentally inherit another one's tick-clearing rule.
+   */
+  readonly clearTicks: (content: string) => string
+  /**
+   * `qa`-only: every OPEN question not yet answered — distinct from
+   * `validate`'s structural findings, since a well-formed document can still
+   * have open questions nobody answered. Absent on a format with no such
+   * concept.
+   */
+  readonly unansweredQuestions?: (content: string) => readonly {
+    readonly question: string
+    readonly headingLine: number
+  }[]
+  /** Every OPEN thread (last entry is the agent's), 0-based `line` — mirrors `unansweredQuestions`. */
+  readonly openThreads?: (content: string) => readonly {
+    readonly name: string
+    readonly line: number
+    readonly firstMe: string
+  }[]
+}