@pmelab/gtd 59.0.0 → 60.0.0

package/src/install/Install.ts

@@ -175,7 +175,7 @@ if [ -z "\${1:-}" ]; then
   exit 2
 fi
 cd "$(git rev-parse --show-toplevel)"
-script="$(gtd door "$@")"
+script="$(gtd start "$@")"
 sh -c "$script"
 exec "$GTD_BUILD"`
 
@@ -365,7 +365,7 @@ const DRIVER_OBLIGATIONS = `
     \`--json=judge\`, pipes that rendered \`{ schema, state, questions }\` document to a
     judge model, and pipes ITS verdict (one \`{ id, answer, p }\` per pending
     question, as JSON on stdin) to \`gtd judge answer\` — the FIFTH command
-    that changes anything, alongside \`gtd land\`/\`gtd --workflow\`/\`gtd
+    that changes anything, alongside \`gtd land\`/\`gtd start\`/\`gtd
     abandon\`/\`gtd restore\`. It follows the exact same required-half /
     optional-half script contract as \`gtd land\` in obligation 8 above:
     read \`--json=script\` (and, if you want them, \`--json=settled\`/
@@ -565,9 +565,9 @@ ${EDIT_COMMAND}
 
 ### \`gtd-door <name> [args...]\` — start a process through a door and drive it
 
-Runs \`gtd door <name> [args...]\`, captured by command substitution — never a
+Runs \`gtd start <name> [args...]\`, captured by command substitution — never a
 pipe: a pipeline reports only its LAST command's exit status, so
-\`gtd door ... | sh\` under \`set -e\` would sail past a refusal and \`exec\` a
+\`gtd start ... | sh\` under \`set -e\` would sail past a refusal and \`exec\` a
 loop over a process that was never started. It runs the captured script, then
 \`exec\`s the suite's RESOLVED \`gtd-build\` path — never the literal string
 \`gtd-build\`. This is one invocation that carries the process all the way to
@@ -575,9 +575,9 @@ its next human gate, not just a starter: \`gtd-door review\` on a RED baseline
 hands off to \`gtd-build\`, which halts at the blocked gate and prints it,
 rather than starting the review; \`gtd-door fix\` on a GREEN suite is a no-op
 straight back to \`idle\` — the exec'd \`gtd-build\` exits immediately on it.
-\`gtd doors\` lists the doors a repository offers (those of the workflows its
-config exports — gtd-workflows' \`default\` brings \`fix\` and
-\`review [base]\` — plus any the config declares). Refuses with
+A bare \`gtd start\` lists what a repository can start: its workflows, and
+the doors those workflows bring (gtd-workflows' \`default\` brings \`fix\`
+and \`review [base]\`) plus any the config declares. Refuses with
 \`usage: gtd-door <name> [args...]\` on stderr and exit \`2\` when the name is
 missing — nothing was even attempted. Default path: \`~/.local/bin/gtd-door\`.
 
@@ -682,7 +682,7 @@ const PREREQUISITES = `
 ## Prerequisites and portability
 
 - A POSIX \`sh\` (dash, ash, bash's own POSIX mode, etc.) — gtd's own emitted
-  scripts (\`gtd land --json=script\`, \`gtd --workflow <name>\`, \`gtd abandon\`,
+  scripts (\`gtd land --json=script\`, \`gtd start <name>\`, \`gtd abandon\`,
   \`gtd restore\`, \`gtd judge answer --json=script\`) are POSIX sh; captured,
   then piped into it (see obligation 8 above). Reading
   \`gtd next --json=<path>\`/\`gtd land --json=<path>\`'s own output needs

package/src/replay/Replay.test.ts

@@ -702,7 +702,7 @@ describe("replay: keep", () => {
   it("rejects keep together with allowEmpty", async () => {
     const flow: Flow = async () => {
       await human("idle")
-      await agent("naive", "p", { keep: true, allowEmpty: true })
+      await agent("naive", "p", { keep: true, allowEmpty: true } as never)
     }
     const h = new History().land("human", "idle", 1, "naive", {})
     const outcome = await replayOf(flow, h)
@@ -1166,6 +1166,17 @@ describe("human({ approve })", () => {
     }
   })
 
+  it.each([
+    ["human", async () => human("gate", { mode: "qa" } as never)],
+    ["agent", async () => agent("gate", "p", { mode: "qa" } as never)],
+    ["run", async () => run("gate", "true", { mode: "qa" } as never)],
+  ] as const)("refuses a %s step's mode without a file", async (kind, flow) => {
+    expect(await replayOf(flow, new History())).toEqual({
+      kind: "failed",
+      message: `gtd: step "gate": mode requires file in ${kind}() options — name the steering file the mode checks`,
+    })
+  })
+
   describe("refuses mode and file", () => {
     const tail =
       "in human() options — an approval records exactly the judged tree, and a steering file is rewritten on landing"
@@ -1189,7 +1200,7 @@ describe("human({ approve })", () => {
       for (const options of [
         { approve: true, label: "x" },
         { approve: true, base: "start" },
-        { approve: false, mode: "review" },
+        { approve: false, mode: "review", file: ".gtd/REVIEW.md" },
         { approve: true, mode: undefined },
       ]) {
         expect((await outcomeOf(options)).kind).toBe("rest")

package/src/replay/Replay.ts

@@ -11,14 +11,13 @@ import {
   type StepRequest,
   type Flow,
   type Mark,
-} from "../flows/index.js"
+} from "../flows/internal.js"
 import {
-  headingSectionBodies,
-  headingSections,
-  steeringFormatFor,
+  openQuestions,
   parseCodeThreads,
-  parseThreadsWithFindings,
-  unansweredQuestions,
+  sectionBodies,
+  sections,
+  threads,
 } from "../steering/index.js"
 import { accessShapeFault, foldAccess, sameAccess } from "./Access.js"
 import { globMatches } from "../wire/index.js"
@@ -291,6 +290,13 @@ const approveConflict = (step: ReachedStep): string | undefined => {
   return `gtd: step "${step.name}": approve cannot be combined with ${keys.join(", ")} in human() options — an approval records exactly the judged tree, and a steering file is rewritten on landing`
 }
 
+// A mode names how a steering file is checked; with no file there is nothing to check.
+const modeWithoutFile = (step: ReachedStep): string | undefined => {
+  const options = step.request.options
+  if (options.mode === undefined || options.file !== undefined) return undefined
+  return `gtd: step "${step.name}": mode requires file in ${step.kind}() options — name the steering file the mode checks`
+}
+
 export const replay = async (input: ReplayInput): Promise<ReplayOutcome> => {
   const commits: readonly ParsedCommit[] = input.episode.commits.map((c) => ({
     ...c,
@@ -524,7 +530,8 @@ export const replay = async (input: ReplayInput): Promise<ReplayOutcome> => {
         message: `gtd: commit ${short(expected.hash)} names "${expected.name}" as the next step, but replay reached "${step.name}" — ${DIVERGED}`,
       }
     }
-    const error = unknownOptions(step) ?? approveConflict(step) ?? checkIdentity(step)
+    const error =
+      unknownOptions(step) ?? approveConflict(step) ?? modeWithoutFile(step) ?? checkIdentity(step)
     return error === undefined ? undefined : { kind: "failed", message: error }
   }
 
@@ -604,7 +611,7 @@ export const replay = async (input: ReplayInput): Promise<ReplayOutcome> => {
     const name = scoped(request.name)
     if (request.options.keep === true) {
       // A clean allowEmpty keep would land an ordinary commit with no Gtd-Kept: a silent skip.
-      if (request.options.allowEmpty === true) {
+      if ((request.options as { readonly allowEmpty?: unknown }).allowEmpty === true) {
         return `gtd: step "${name}": keep: true cannot be combined with allowEmpty — a turn that changes nothing has nothing to keep`
       }
       // "/" would let one step's ref directory collide with another step's ref (git refuses `a` and `a/b` together).
@@ -667,28 +674,10 @@ export const replay = async (input: ReplayInput): Promise<ReplayOutcome> => {
     changes: () => changesBetween(previousPosition.tree, position.tree),
     changesSince,
     matches: globMatches,
-    sections: (text) => headingSections(text),
-    sectionBodies: (text) => headingSectionBodies(text),
-    openQuestions: (text) => {
-      const qa = steeringFormatFor("qa")
-      return qa === undefined
-        ? []
-        : unansweredQuestions(qa, text).map((q) => ({
-            question: q.question,
-            line: q.headingLine + 1,
-          }))
-    },
-    threads: (text) => {
-      const { threads, findings } = parseThreadsWithFindings(text)
-      return threads.map((t) => ({
-        name: t.name,
-        line: t.line + 1,
-        waitingOn: t.waitingOn,
-        faults: findings
-          .filter((f) => f.message.startsWith(`Footnote thread "[^${t.name}]": `))
-          .map((f) => f.message),
-      }))
-    },
+    sections,
+    sectionBodies,
+    openQuestions,
+    threads,
     codeThreads: () =>
       changesBetween(
         treeAt(input.start) ?? input.startTree ?? input.episode.base.tree,

package/src/replay/judgeDiffShape.test.ts

@@ -6,7 +6,7 @@ import {
   type FlowContext,
   type JudgeAnswer,
   type StepRequest,
-} from "../flows/index.js"
+} from "../flows/internal.js"
 import { toRequest } from "../judges/index.js"
 import { globMatches } from "../wire/index.js"
 

package/src/steering/Footnotes.test.ts

@@ -697,7 +697,7 @@ describe("case-insensitive definition matching", () => {
   })
 })
 
-import { freeFormFormat, getParseCount, steeringFormatFor } from "./index.js"
+import { freeFormFormat, getParseCount, steeringFormatFor } from "./internal.js"
 
 const qaDescriptor = steeringFormatFor("qa")!
 const reviewDescriptor = steeringFormatFor("review")!

package/src/steering/SteeringFormats.test.ts

@@ -5,7 +5,7 @@ import {
   parseFootnotes,
   parseThreads,
   steeringFormatFor,
-} from "./index.js"
+} from "./internal.js"
 
 const QA_FORMAT = steeringFormatFor("qa")!
 const REVIEW_FORMAT = steeringFormatFor("review")!

package/src/steering/freeform.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest"
 import { freeFormFormat } from "./freeform.js"
-import { BUILT_IN_MODE_NAMES, steeringFormatFor } from "./index.js"
+import { BUILT_IN_MODE_NAMES, steeringFormatFor } from "./internal.js"
 
 /** Applies edits back-to-front — a local copy of the file's own splice pattern, mirroring `qa.test.ts`/`review.test.ts`'s identical helper. */
 const applyEdits = (

package/src/steering/index.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it } from "vitest"
-import { BUILT_IN_MODE_NAMES, steeringFormatFor, unansweredQuestions, viewOf } from "./index.js"
+import * as published from "./index.js"
+import { BUILT_IN_MODE_NAMES, steeringFormatFor, unansweredQuestions, viewOf } from "./internal.js"
 
 const qa = steeringFormatFor("qa")!
 const review = steeringFormatFor("review")!
@@ -60,3 +61,28 @@ describe("viewOf", () => {
     expect(view.documentLinks[0]!.line).toBe(0)
   })
 })
+
+describe("@pmelab/gtd/steering", () => {
+  it("publishes no engine-only name, nor a duplicate of the pure text reads", () => {
+    for (const name of [
+      "FOOTNOTE_ACTION_TITLE",
+      "THREAD_REPLY_ACTION_TITLE",
+      "getParseCount",
+      "BUILT_IN_MODE_NAMES",
+      "steeringFormatOrFreeForm",
+      "viewOf",
+      "headingSections",
+      "headingSectionBodies",
+      "unansweredQuestions",
+    ]) {
+      expect(published, name).not.toHaveProperty(name)
+    }
+  })
+
+  it("publishes the pure text reads a flow also has", () => {
+    expect(published.sections("## A\n\n## B\n")).toEqual(["A", "B"])
+    expect(typeof published.threads).toBe("function")
+    expect(typeof published.openQuestions).toBe("function")
+    expect(typeof published.sectionBodies).toBe("function")
+  })
+})

package/src/steering/index.ts

@@ -1,14 +1,6 @@
-import type {
-  SteeringAction,
-  SteeringFormat,
-  SteeringLink,
-  SteeringOutlineNode,
-  SteeringPointer,
-} from "./SteeringFormat.js"
+// `@pmelab/gtd/steering`, listed name by name. gtd's own code imports
+// `./internal.js`, which adds what only the engine, the LSP and `gtd ui` use.
 export { formatFinding } from "./SteeringFormat.js"
-import { qaDescriptor } from "./qa.js"
-import { reviewDescriptor } from "./review.js"
-import { findingsDescriptor } from "./findings.js"
 export { findingEntries, FIX_BOX, NOISE_HEADING, type FindingEntry } from "./findings.js"
 export {
   ANSWER_FIX,
@@ -30,11 +22,7 @@ export { applySteeringEdits } from "./Edits.js"
 
 export type { InlineNode } from "./Inline.js"
 
-// The free-form format: the mode-less/unregistered-mode FALLBACK —
-// deliberately not a `REGISTRY` entry of its own, since it is never a mode a
-// `mode:` key names.
-import { freeFormFormat } from "./freeform.js"
-export { freeFormFormat }
+export { freeFormFormat } from "./freeform.js"
 
 export type {
   BlockListItem,
@@ -50,15 +38,7 @@ export type {
   SteeringViewThread,
 } from "./SteeringFormat.js"
 
-/** The built-in registry: mode name → its format, in registry order. The single place the built-in formats are wired into names — everything else in this module dispatches over a resolved `SteeringFormat`, never a mode-name string. */
-const REGISTRY: ReadonlyMap<string, SteeringFormat> = new Map([
-  ["qa", qaDescriptor],
-  ["review", reviewDescriptor],
-  ["findings", findingsDescriptor],
-])
-
-/** Every built-in format name, in registry order. */
-export const BUILT_IN_MODE_NAMES: readonly string[] = [...REGISTRY.keys()]
+export { openThreads, steeringFormatFor } from "./registry.js"
 
 // The two `qa` primitives the phone client itself needs: `src/web/screens/
 // Question.tsx` renders the free-text slot and derives answeredness in the
@@ -66,93 +46,15 @@ export const BUILT_IN_MODE_NAMES: readonly string[] = [...REGISTRY.keys()]
 // with — a second copy there would drift silently.
 export { FREE_TEXT_PLACEHOLDER, isAnswered } from "./qa.js"
 
-// `ModeContradiction.ts`'s round-trip check re-parses a formatted sample's
-// footnotes to prove the formatter moved none of them — the one consumer
-// outside this package that needs the footnote parser itself, not a format.
 export {
   parseFootnotes,
   parseThreads,
   parseThreadsWithFindings,
   openThreadFindings,
-  FOOTNOTE_ACTION_TITLE,
-  THREAD_REPLY_ACTION_TITLE,
 } from "./Footnotes.js"
 
-// Test-observability only: the memo-hit counter is the one way "one parse per
-// document" is assertable from outside `MarkdownTree.ts` — timing is not.
-export { getParseCount } from "./MarkdownTree.js"
-
-// A flow's `sections()` is the one caller outside this package.
-export { headingSectionBodies, headingSections } from "./MarkdownTree.js"
-
-/** The built-in `SteeringFormat` registered under `mode`'s name, or `undefined` when it isn't a built-in mode at all. The one place a bare mode-name string is ever looked up — every consumer takes the RESOLVED value this returns, never a name, so "mode is required, never inferred from a file's basename" is a type, not a rule to remember. */
-export const steeringFormatFor = (mode: string): SteeringFormat | undefined => REGISTRY.get(mode)
-
-/**
- * The ui boundary's own resolution: `mode`'s registered format, or
- * `freeFormFormat` when `mode` is absent or names nothing in `REGISTRY` —
- * never `undefined`. `resolveMode` (`SteeringMode.ts`) stays on
- * `steeringFormatFor` alone, so a workflow naming a mode nothing defines
- * still fails to compile; this fallback is deliberately reachable only from
- * `src/ui/View.ts` and `src/ui/Write.ts`, where a mode-less/unknown-mode
- * document must still render and accept a paragraph note, never refuse.
- */
-export const steeringFormatOrFreeForm = (mode: string | undefined): SteeringFormat =>
-  (mode !== undefined ? REGISTRY.get(mode) : undefined) ?? freeFormFormat
-
-/**
- * `qa`-only: every OPEN question in `content` not yet answered, as
- * `{ question, headingLine }` pairs — enough for a refusal message ("which
- * question", "where"). Semantically distinct from `validate`'s findings:
- * a document can be perfectly well-formed (zero findings) while still having
- * open questions nobody has answered, which is the whole point of the
- * answer-completeness gate this feeds. Format-parameterised like everything
- * else here: `review` (or any future format with no such concept) yields
- * `[]` rather than this being a `qa`-specific function some caller has to
- * know not to call on the wrong format.
- */
-export const unansweredQuestions = (
-  format: SteeringFormat,
-  content: string,
-): readonly { readonly question: string; readonly headingLine: number }[] =>
-  format.unansweredQuestions?.(content) ?? []
-
-/**
- * Every positional thing an editor (the LSP, in a later pass) needs for one
- * document, off ONE `viewOf` call rather than four separate ones re-deriving
- * ranges each time: `outline` and `documentLinks` are already fully resolved
- * (each node/link carries its own range — see `SteeringOutlineNode`/
- * `SteeringLink`), while `pointerAt`/`actionsAt` stay closures over `content`
- * because they need a cursor position/selection range the caller supplies
- * per request. `Lsp.ts` reads its ranges straight off `outline`/`documentLinks`.
- */
-export interface SteeringEditorView {
-  readonly outline: readonly SteeringOutlineNode[]
-  readonly documentLinks: readonly SteeringLink[]
-  readonly pointerAt: (position: {
-    readonly line: number
-    readonly character: number
-  }) => SteeringPointer | undefined
-  readonly actionsAt: (range: {
-    readonly start: { readonly line: number; readonly character: number }
-    readonly end: { readonly line: number; readonly character: number }
-  }) => readonly SteeringAction[]
-}
-
-/** Builds `format`'s `SteeringEditorView` of `content` — see `SteeringEditorView`'s own doc for why this is one value, not several. Distinct from `SteeringView` (`SteeringFormat.ts`), which is the format's own node tree the phone client renders. */
-export const viewOf = (format: SteeringFormat, content: string): SteeringEditorView => ({
-  outline: format.outline(content),
-  documentLinks: format.documentLinks ? format.documentLinks(content) : [],
-  pointerAt: (position) => format.pointerAt?.(content, position),
-  actionsAt: (range) => format.actions(content, range),
-})
-
-/** Every OPEN thread — last entry is the agent's — as `{ name, line, firstMe }` (0-based line). `[]` for a format with no thread concept. */
-export const openThreads = (
-  format: SteeringFormat,
-  content: string,
-): readonly { readonly name: string; readonly line: number; readonly firstMe: string }[] =>
-  format.openThreads?.(content) ?? []
+// The pure counterparts of `@pmelab/gtd/flows`' text reads, usable outside a replay.
+export { openQuestions, sectionBodies, sections, threads } from "./reads.js"
 
 // Line-comment `H:`/`A:` threads in changed code files: a flow's `codeThreads()`
 // and `gtd check --open-threads` are the callers outside this package.

package/src/steering/internal.ts

@@ -0,0 +1,11 @@
+// gtd's own imports of the steering formats: everything public, plus what only
+// the engine, the LSP and `gtd ui` use.
+export * from "./index.js"
+export { FOOTNOTE_ACTION_TITLE, THREAD_REPLY_ACTION_TITLE } from "./Footnotes.js"
+export { getParseCount, headingSectionBodies } from "./MarkdownTree.js"
+export {
+  BUILT_IN_MODE_NAMES,
+  steeringFormatOrFreeForm,
+  unansweredQuestions,
+  viewOf,
+} from "./registry.js"

package/src/steering/qa.test.ts

@@ -1,7 +1,12 @@
 import { describe, expect, it } from "vitest"
-import { FOOTNOTE_ACTION_TITLE, steeringFormatFor, unansweredQuestions, viewOf } from "./index.js"
+import {
+  FOOTNOTE_ACTION_TITLE,
+  steeringFormatFor,
+  unansweredQuestions,
+  viewOf,
+} from "./internal.js"
 import { FREE_TEXT_PLACEHOLDER, isAnswered, parseOpenQuestions } from "./qa.js"
-import { getParseCount } from "./index.js"
+import { getParseCount } from "./internal.js"
 
 const qa = steeringFormatFor("qa")!
 

package/src/steering/reads.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from "vitest"
+import { openQuestions, sectionBodies, sections, threads } from "./reads.js"
+
+describe("the pure text reads", () => {
+  it("sections and sectionBodies read the top-level ## headings", () => {
+    const text = "# Title\n\n## One\n\nfirst\n\n### Sub\n\n## Two\n"
+    expect(sections(text)).toEqual(["One", "Two"])
+    expect(sectionBodies(text).map((s) => s.title)).toEqual(["One", "Two"])
+    expect(sectionBodies(text)[0]!.body).toContain("## One")
+  })
+
+  it("openQuestions lists a qa document's unanswered questions with 1-based lines", () => {
+    const text = [
+      "## Open Questions",
+      "",
+      "### Which database?",
+      "",
+      "- [ ] Postgres",
+      "- [ ] SQLite",
+      "",
+    ].join("\n")
+    expect(openQuestions(text)).toEqual([{ question: "Which database?", line: 3 }])
+  })
+
+  it("threads reads a footnote thread with its 1-based line and who it waits on", () => {
+    const text = [
+      "We cache it.[^cache]",
+      "",
+      "[^cache]:",
+      "    - H: why?",
+      "    - A: because",
+      "",
+    ].join("\n")
+    expect(threads(text)).toEqual([{ name: "cache", line: 3, waitingOn: "human", faults: [] }])
+  })
+
+  it("works outside a replay", () => {
+    expect(() => sections("")).not.toThrow()
+    expect(threads("no threads here")).toEqual([])
+    expect(openQuestions("")).toEqual([])
+  })
+})

package/src/steering/reads.ts

@@ -0,0 +1,43 @@
+// The text reads `@pmelab/gtd/flows` offers inside a replay, here as plain
+// functions: the replay context answers with these, so both read alike.
+import { parseThreadsWithFindings } from "./Footnotes.js"
+import { headingSectionBodies, headingSections } from "./MarkdownTree.js"
+import { qaDescriptor } from "./qa.js"
+import { unansweredQuestions } from "./registry.js"
+
+/** The top-level `## ` heading texts of markdown `text`. */
+export const sections = (text: string): readonly string[] => headingSections(text)
+
+/** The top-level `## ` sections of markdown `text`, each with its own markdown, its heading line included. */
+export const sectionBodies = (
+  text: string,
+): readonly { readonly title: string; readonly body: string }[] => headingSectionBodies(text)
+
+/** The `qa`-format questions in `text` still unanswered, each with its heading's 1-based line. */
+export const openQuestions = (
+  text: string,
+): readonly { readonly question: string; readonly line: number }[] =>
+  unansweredQuestions(qaDescriptor, text).map((q) => ({
+    question: q.question,
+    line: q.headingLine + 1,
+  }))
+
+/** Every `H:`/`A:` footnote thread in `text`: its 1-based definition line, who it waits on (`"human"` means open) and its syntax faults. */
+export const threads = (
+  text: string,
+): readonly {
+  readonly name: string
+  readonly line: number
+  readonly waitingOn: "human" | "agent"
+  readonly faults: readonly string[]
+}[] => {
+  const { threads, findings } = parseThreadsWithFindings(text)
+  return threads.map((t) => ({
+    name: t.name,
+    line: t.line + 1,
+    waitingOn: t.waitingOn,
+    faults: findings
+      .filter((f) => f.message.startsWith(`Footnote thread "[^${t.name}]": `))
+      .map((f) => f.message),
+  }))
+}

package/src/steering/registry.ts

@@ -0,0 +1,93 @@
+import type {
+  SteeringAction,
+  SteeringFormat,
+  SteeringLink,
+  SteeringOutlineNode,
+  SteeringPointer,
+} from "./SteeringFormat.js"
+import { qaDescriptor } from "./qa.js"
+import { reviewDescriptor } from "./review.js"
+import { findingsDescriptor } from "./findings.js"
+// The free-form format: the mode-less/unregistered-mode FALLBACK —
+// deliberately not a `REGISTRY` entry of its own, since it is never a mode a
+// `mode:` key names.
+import { freeFormFormat } from "./freeform.js"
+
+/** The built-in registry: mode name → its format, in registry order. The single place the built-in formats are wired into names — everything else in this module dispatches over a resolved `SteeringFormat`, never a mode-name string. */
+const REGISTRY: ReadonlyMap<string, SteeringFormat> = new Map([
+  ["qa", qaDescriptor],
+  ["review", reviewDescriptor],
+  ["findings", findingsDescriptor],
+])
+
+/** Every built-in format name, in registry order. */
+export const BUILT_IN_MODE_NAMES: readonly string[] = [...REGISTRY.keys()]
+
+/** The built-in `SteeringFormat` registered under `mode`'s name, or `undefined` when it isn't a built-in mode at all. The one place a bare mode-name string is ever looked up — every consumer takes the RESOLVED value this returns, never a name, so "mode is required, never inferred from a file's basename" is a type, not a rule to remember. */
+export const steeringFormatFor = (mode: string): SteeringFormat | undefined => REGISTRY.get(mode)
+
+/**
+ * The ui boundary's own resolution: `mode`'s registered format, or
+ * `freeFormFormat` when `mode` is absent or names nothing in `REGISTRY` —
+ * never `undefined`. `resolveMode` (`SteeringMode.ts`) stays on
+ * `steeringFormatFor` alone, so a workflow naming a mode nothing defines
+ * still fails to compile; this fallback is deliberately reachable only from
+ * `src/ui/View.ts` and `src/ui/Write.ts`, where a mode-less/unknown-mode
+ * document must still render and accept a paragraph note, never refuse.
+ */
+export const steeringFormatOrFreeForm = (mode: string | undefined): SteeringFormat =>
+  (mode !== undefined ? REGISTRY.get(mode) : undefined) ?? freeFormFormat
+
+/**
+ * `qa`-only: every OPEN question in `content` not yet answered, as
+ * `{ question, headingLine }` pairs — enough for a refusal message ("which
+ * question", "where"). Semantically distinct from `validate`'s findings:
+ * a document can be perfectly well-formed (zero findings) while still having
+ * open questions nobody has answered, which is the whole point of the
+ * answer-completeness gate this feeds. Format-parameterised like everything
+ * else here: `review` (or any future format with no such concept) yields
+ * `[]` rather than this being a `qa`-specific function some caller has to
+ * know not to call on the wrong format.
+ */
+export const unansweredQuestions = (
+  format: SteeringFormat,
+  content: string,
+): readonly { readonly question: string; readonly headingLine: number }[] =>
+  format.unansweredQuestions?.(content) ?? []
+
+/**
+ * Every positional thing an editor (the LSP, in a later pass) needs for one
+ * document, off ONE `viewOf` call rather than four separate ones re-deriving
+ * ranges each time: `outline` and `documentLinks` are already fully resolved
+ * (each node/link carries its own range — see `SteeringOutlineNode`/
+ * `SteeringLink`), while `pointerAt`/`actionsAt` stay closures over `content`
+ * because they need a cursor position/selection range the caller supplies
+ * per request. `Lsp.ts` reads its ranges straight off `outline`/`documentLinks`.
+ */
+export interface SteeringEditorView {
+  readonly outline: readonly SteeringOutlineNode[]
+  readonly documentLinks: readonly SteeringLink[]
+  readonly pointerAt: (position: {
+    readonly line: number
+    readonly character: number
+  }) => SteeringPointer | undefined
+  readonly actionsAt: (range: {
+    readonly start: { readonly line: number; readonly character: number }
+    readonly end: { readonly line: number; readonly character: number }
+  }) => readonly SteeringAction[]
+}
+
+/** Builds `format`'s `SteeringEditorView` of `content` — see `SteeringEditorView`'s own doc for why this is one value, not several. Distinct from `SteeringView` (`SteeringFormat.ts`), which is the format's own node tree the phone client renders. */
+export const viewOf = (format: SteeringFormat, content: string): SteeringEditorView => ({
+  outline: format.outline(content),
+  documentLinks: format.documentLinks ? format.documentLinks(content) : [],
+  pointerAt: (position) => format.pointerAt?.(content, position),
+  actionsAt: (range) => format.actions(content, range),
+})
+
+/** Every OPEN thread — last entry is the agent's — as `{ name, line, firstMe }` (0-based line). `[]` for a format with no thread concept. */
+export const openThreads = (
+  format: SteeringFormat,
+  content: string,
+): readonly { readonly name: string; readonly line: number; readonly firstMe: string }[] =>
+  format.openThreads?.(content) ?? []

package/src/steering/review.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, it } from "vitest"
-import { FOOTNOTE_ACTION_TITLE, steeringFormatFor, viewOf } from "./index.js"
+import { FOOTNOTE_ACTION_TITLE, steeringFormatFor, viewOf } from "./internal.js"
 import { parseReviewDoc, unansweredNotes } from "./review.js"
-import { getParseCount } from "./index.js"
+import { getParseCount } from "./internal.js"
 
 describe("parseReviewDoc", () => {
   it("parses a well-formed review with one chunk, no explanations", () => {