@pmelab/gtd 64.0.0 → 64.1.0

package/dist/steering.mjs

@@ -1,2 +1,2 @@
-import { A as parseThreads, C as FREE_TEXT_PLACEHOLDER, D as findingEntries, E as NOISE_HEADING, N as formatFinding, O as openThreadFindings, S as unansweredNotes, T as FIX_BOX, _ as reviewChunks, a as sections, b as reviewRisks, c as openThreads, d as freeFormFormat, f as applySteeringEdits, g as REVIEW_SECTIONS, h as ANSWER_WONT_FIX, i as sectionBodies, j as parseThreadsWithFindings, k as parseFootnotes, l as steeringFormatFor, m as ANSWER_LEAD, n as stripCodeThreads, o as threads, p as ANSWER_FIX, r as openQuestions, t as parseCodeThreads, v as reviewDecisions, w as isAnswered, x as reviewSections, y as reviewNotes } from "./chunks/steering-DkA51qDa.mjs";
-export { ANSWER_FIX, ANSWER_LEAD, ANSWER_WONT_FIX, FIX_BOX, FREE_TEXT_PLACEHOLDER, NOISE_HEADING, REVIEW_SECTIONS, applySteeringEdits, findingEntries, formatFinding, freeFormFormat, isAnswered, openQuestions, openThreadFindings, openThreads, parseCodeThreads, parseFootnotes, parseThreads, parseThreadsWithFindings, reviewChunks, reviewDecisions, reviewNotes, reviewRisks, reviewSections, sectionBodies, sections, steeringFormatFor, stripCodeThreads, threads, unansweredNotes };
+import { A as findingEntries, C as reviewRisks, D as isAnswered, E as FREE_TEXT_PLACEHOLDER, I as formatFinding, M as parseFootnotes, N as parseThreads, O as FIX_BOX, P as parseThreadsWithFindings, S as reviewNotes, T as unansweredNotes, _ as ANSWER_LEAD, a as sections, b as reviewChunks, c as openThreads, f as listFormat, g as ANSWER_FIX, h as applySteeringEdits, i as sectionBodies, j as openThreadFindings, k as NOISE_HEADING, l as steeringFormatFor, m as freeFormFormat, n as stripCodeThreads, o as threads, p as sectionFormat, r as openQuestions, t as parseCodeThreads, v as ANSWER_WONT_FIX, w as reviewSections, x as reviewDecisions, y as REVIEW_SECTIONS } from "./chunks/steering-Cem5i6Xl.mjs";
+export { ANSWER_FIX, ANSWER_LEAD, ANSWER_WONT_FIX, FIX_BOX, FREE_TEXT_PLACEHOLDER, NOISE_HEADING, REVIEW_SECTIONS, applySteeringEdits, findingEntries, formatFinding, freeFormFormat, isAnswered, listFormat, openQuestions, openThreadFindings, openThreads, parseCodeThreads, parseFootnotes, parseThreads, parseThreadsWithFindings, reviewChunks, reviewDecisions, reviewNotes, reviewRisks, reviewSections, sectionBodies, sectionFormat, sections, steeringFormatFor, stripCodeThreads, threads, unansweredNotes };

package/dist/testkit/gherkin.mjs

@@ -1,4 +1,4 @@
-import { n as runsItsScript, r as testRepo } from "../chunks/testkit-zGjNeQNL.mjs";
+import { n as runsItsScript, r as testRepo } from "../chunks/testkit-DfWZQCWQ.mjs";
 import { pathToFileURL } from "node:url";
 import { resolve } from "node:path";
 import { After, AfterAll, Given, QuickPickleWorld, Then, When, setWorldConstructor } from "quickpickle";

package/dist/testkit.mjs

@@ -1,3 +1,3 @@
 import { H as installContext } from "./chunks/flows-B7ZRCe-B.mjs";
-import { a as verdictWhen, i as verdict, n as runsItsScript, o as whenPrompted, r as testRepo, t as inTurn } from "./chunks/testkit-zGjNeQNL.mjs";
+import { a as verdictWhen, i as verdict, n as runsItsScript, o as whenPrompted, r as testRepo, t as inTurn } from "./chunks/testkit-DfWZQCWQ.mjs";
 export { inTurn, installContext, runsItsScript, testRepo, verdict, verdictWhen, whenPrompted };

package/dist/workflow-kit.mjs

@@ -1,5 +1,5 @@
 import { B as head, F as changesSince, G as mark, P as changes, X as read, Z as refuse, d as hasThreadFor, et as scope, g as requireReplies, v as requireThreadsClosed } from "./chunks/flows-B7ZRCe-B.mjs";
-import { A as parseThreads, S as unansweredNotes, b as reviewRisks, n as stripCodeThreads, v as reviewDecisions, y as reviewNotes } from "./chunks/steering-DkA51qDa.mjs";
+import { C as reviewRisks, N as parseThreads, S as reviewNotes, T as unansweredNotes, n as stripCodeThreads, x as reviewDecisions } from "./chunks/steering-Cem5i6Xl.mjs";
 //#region src/workflow-kit/health.ts
 /** Hand a red suite that repeated attempts could not fix to a person, until `limit` rounds are spent. */
 const escalation = async (count, steps) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmelab/gtd",
-  "version": "64.0.0",
+  "version": "64.1.0",
   "private": false,
   "description": "Git-aware CLI that emits the next prompt for an autonomous coding agent based on the current repository state",
   "bin": {

package/src/cli/Cli.ts

@@ -325,6 +325,16 @@ const FLAGS: readonly FlagRow[] = [
     valueHint: "",
     help: "Instead of <mode>'s findings, list the open threads in <file>; exits 1 when any are open. Alone, lists the open code-comment threads in the files the current process changed",
   },
+  {
+    name: "--spec",
+    arity: 1,
+    repeatable: false,
+    scope: (kind) => kind === "check",
+    decode: ([raw]) => Result.succeed(raw ?? ""),
+    scopeError: "gtd: --spec is only valid for `gtd check`",
+    valueHint: "<json>",
+    help: "Check against the declared format this spec describes, named <mode>, instead of a built-in one; validation scripts pass it for a step whose mode is a declared format",
+  },
   {
     name: "--verbose",
     arity: 0,
@@ -587,7 +597,7 @@ The fixed answerer reads --answers and leaves out the questions it does not cove
     arity: { names: ["mode", "file"] },
     group: "Driver plumbing",
     summary: "Check a steering file's format",
-    details: `Run the steering format <mode> (qa, review or findings) over <file> and print each finding on a line of its own; exits 1 when there are any, or when <file> does not exist. An unknown <mode> is a usage error (exit 2). Reads no workflow and runs from any directory — emitted validation scripts call it.`,
+    details: `Run the steering format <mode> (qa, review or findings, or the declared format --spec describes) over <file> and print each finding on a line of its own; exits 1 when there are any, or when <file> does not exist. An unknown <mode> is a usage error (exit 2). Reads no workflow and runs from any directory — emitted validation scripts call it.`,
   },
   {
     token: "uncheck",
@@ -1124,6 +1134,7 @@ export const parseArgv = (argv: readonly string[]): CliPlan => {
     readonly "--threshold"?: Readonly<Record<string, string>>
     readonly "--open-questions"?: boolean
     readonly "--open-threads"?: boolean
+    readonly "--spec"?: string
     readonly "--host"?: string
     readonly "--self-signed"?: boolean
     readonly "--dev"?: boolean
@@ -1199,6 +1210,7 @@ export const parseArgv = (argv: readonly string[]): CliPlan => {
           ? { openQuestions: bag["--open-questions"] }
           : {}),
         ...(bag["--open-threads"] !== undefined ? { openThreads: bag["--open-threads"] } : {}),
+        ...(bag["--spec"] !== undefined ? { spec: bag["--spec"] } : {}),
       },
       json,
       verbose,

package/src/cli/Program.ts

@@ -70,6 +70,7 @@ import { formatCommitMessage, PIN_STATES } from "../replay/index.js"
 import { planStart, planStep as planStepPure, type JudgeVerdict } from "../step/index.js"
 import {
   BUILT_IN_MODE_NAMES,
+  formatFromSpec,
   steeringFormatFor,
   openThreads,
   parseCodeThreads,
@@ -169,6 +170,8 @@ export type Command =
       readonly file?: string
       readonly openQuestions?: boolean
       readonly openThreads?: boolean
+      /** A declared format's spec: `mode` names it, and no built-in is looked up. */
+      readonly spec?: string
     }
   | { readonly kind: "uncheck"; readonly file: string }
   | { readonly kind: "guide" }
@@ -903,8 +906,9 @@ const selfValidateCommand = (
   state: string,
   mode: StateMode,
   file: string,
+  spec: string | undefined,
 ): string => {
-  const resolved = resolveMode(def, state, mode)
+  const resolved = resolveMode(def, state, mode, spec)
   const validate = resolved.kind === "resolved" ? resolved.validate : undefined
   const command = validate?.kind === "command" ? validate.command : seededValidateCommand(mode)
   return commandForFile(command, file)
@@ -934,7 +938,7 @@ const resolveValidateScript = (
     const mode = rest.stepDef.mode
     if (file === undefined || mode === undefined) return undefined
 
-    const resolved = resolveMode(rest.def, rest.state, mode)
+    const resolved = resolveMode(rest.def, rest.state, mode, rest.stepDef.modeSpec)
     if (resolved.kind === "unknown") {
       return yield* Effect.fail(new Error(resolved.message))
     }
@@ -976,7 +980,13 @@ const runNextCommand = (
       yield* writeSelection(out, fields, json.path)
     } else {
       const validateCommand = emitsValidatablePrompt(rendered)
-        ? selfValidateCommand(rest.def, rest.state, rendered.mode!, rendered.file!)
+        ? selfValidateCommand(
+            rest.def,
+            rest.state,
+            rendered.mode!,
+            rendered.file!,
+            rest.stepDef.modeSpec,
+          )
         : undefined
       if (DEMAND_BRIEFING[fields.kind].suppressHeader) {
         // A prompt's stdout is the agent's input, so its header goes to stderr;
@@ -1019,9 +1029,10 @@ const runCheckCommand = (
   file: string,
   openQuestions: boolean,
   openThreadsFlag: boolean,
+  spec: string | undefined,
 ): Effect.Effect<void, Error, Workspace> =>
   Effect.gen(function* () {
-    const format = steeringFormatFor(mode)
+    const format = spec !== undefined ? yield* declaredFormat(spec) : steeringFormatFor(mode)
     if (format === undefined) {
       return yield* Effect.fail(
         new GtdUsageError(
@@ -1071,6 +1082,13 @@ const runCheckCommand = (
     )
   })
 
+const declaredFormat = (spec: string): Effect.Effect<SteeringFormat, GtdUsageError> =>
+  Effect.try({
+    try: () => formatFromSpec(spec),
+    catch: (error) =>
+      new GtdUsageError(`gtd check: --spec is not a declared format: ${(error as Error).message}`),
+  })
+
 const existingFile = (file: string): Effect.Effect<string, Error, Workspace> =>
   Effect.flatMap(Workspace, (workspace) => {
     const content = workspace.atPath(file)
@@ -1384,6 +1402,7 @@ const dispatchVoidCommand = (
         command.file,
         command.openQuestions ?? false,
         command.openThreads ?? false,
+        command.spec,
       )
     case "uncheck":
       return runUncheckCommand(command.file)

package/src/edge/Edge.ts

@@ -705,7 +705,7 @@ const DEFAULT_JUDGE_MESSAGE =
 const optional = <K extends string, V>(key: K, value: V | undefined): { [P in K]?: V } =>
   (value === undefined ? {} : { [key]: value }) as { [P in K]?: V }
 
-type StepCommon = Pick<StepDef, "actor" | "label" | "file" | "mode">
+type StepCommon = Pick<StepDef, "actor" | "label" | "file" | "mode" | "modeSpec">
 
 const commonOf = (step: ReachedStep): StepCommon => {
   const options = step.request.options
@@ -713,7 +713,9 @@ const commonOf = (step: ReachedStep): StepCommon => {
     actor: step.actor,
     ...optional("label", options.label),
     ...optional("file", options.file),
-    ...optional("mode", options.mode),
+    ...(typeof options.mode === "object"
+      ? { mode: options.mode.name, modeSpec: options.mode.spec }
+      : optional("mode", options.mode)),
   }
 }
 
@@ -833,6 +835,23 @@ const hintsOf = (def: StepDef): RestHints => ({
   ...optional("access", def.access),
 })
 
+/** A step's mode is a name the workflow knows, or a declared format named apart from all of them. */
+const modeFaultOf = (
+  def: WorkflowDefinition,
+  stepName: string,
+  stepDef: StepDef,
+): string | undefined => {
+  if (stepDef.mode === undefined) return undefined
+  const known = def.modes[stepDef.mode] !== undefined
+  if (stepDef.modeSpec !== undefined)
+    return known
+      ? `gtd: config: step "${stepName}": declared format "${stepDef.mode}" has the name of a mode this workflow already knows — rename the format`
+      : undefined
+  return known
+    ? undefined
+    : `gtd: config: step "${stepName}": mode "${stepDef.mode}" is not a mode this workflow knows (${knownModes(def).join(", ")})`
+}
+
 const normalizeStatus = (raw: string): ChangeStatus => (raw === "A" ? "A" : raw === "D" ? "D" : "M")
 
 /** The currently rested step and its description — enough for the viewer and the LSP. */
@@ -997,13 +1016,8 @@ export const restAt = (
     const { reached, step } = resting
     const { stepDef, state, memory } = restFacts(pin, step, reached.trace, run)
     yield* (yield* Narrator).narrate(`rest resolved: ${state} (awaits ${stepDef.actor})`)
-    if (stepDef.mode !== undefined && def.modes[stepDef.mode] === undefined) {
-      return yield* Effect.fail(
-        new Error(
-          `gtd: config: step "${step.name}": mode "${stepDef.mode}" is not a mode this workflow knows (${knownModes(def).join(", ")})`,
-        ),
-      )
-    }
+    const modeFault = modeFaultOf(def, step.name, stepDef)
+    if (modeFault !== undefined) return yield* Effect.fail(new Error(modeFault))
     const changes =
       ref === undefined
         ? (yield* pendingChanges(git, stepDef.approve === true)).map((e) => ({

package/src/emit/SteeringMode.ts

@@ -1,12 +1,18 @@
 import { Effect, Path } from "effect"
 import { Host, type HostOps } from "../platform/index.js"
 import {
+  declaredValidateCommand,
   isSeededValidateCommand,
   knownModes,
   type StateMode,
   type WorkflowDefinition,
 } from "../workflow/index.js"
-import { steeringFormatFor, type SteeringFinding, type SteeringFormat } from "../steering/index.js"
+import {
+  formatFromSpec,
+  steeringFormatFor,
+  type SteeringFinding,
+  type SteeringFormat,
+} from "../steering/internal.js"
 import { buildModeContradictionCheck, modeContradictionSkipNotice } from "./ModeContradiction.js"
 import {
   binaryGuard,
@@ -101,12 +107,26 @@ const capabilitiesFor = (
  * The `"unknown"` arm carries the whole refusal message, naming what IS known
  * when `def` is given — this is the one place that message is built, so it
  * can never drift from what actually resolved.
+ *
+ * `spec` is a declared format's: it alone decides, validating through
+ * `gtd check --spec` with no `format:` half.
  */
 export const resolveMode = (
   def: Pick<WorkflowDefinition, "modes"> | undefined,
   state: string,
   mode: StateMode,
+  spec?: string,
 ): ModeResolution => {
+  if (spec !== undefined) {
+    const format = formatFromSpec(spec)
+    return {
+      kind: "resolved",
+      mode,
+      format,
+      validate: { kind: "command", command: declaredValidateCommand(mode, spec) },
+      capabilities: { format, liveValidate: format.validate },
+    }
+  }
   const declared = def?.modes?.[mode]
   const format = steeringFormatFor(mode)
   if (declared === undefined && format === undefined) {

package/src/flows/index.ts

@@ -50,6 +50,7 @@ export {
   type Judgment,
   type KeptTip,
   type Mark,
+  type DeclaredMode,
   type ModeName,
   type OpenQuestion,
   type RunOptions,

package/src/flows/runtime.test.ts

@@ -19,6 +19,7 @@ import {
   type AgentOptions,
   type HumanOptions,
   type Judgment,
+  type DeclaredMode,
   type ModeName,
   type RunOptions,
   type Settings,
@@ -315,6 +316,6 @@ describe("mode", () => {
     expectTypeOf<"qa">().toMatchTypeOf<ModeName>()
     expectTypeOf<string>().toMatchTypeOf<ModeName>()
     expectTypeOf<ModeName>().toMatchTypeOf<string>()
-    expectTypeOf<SteeringOptions["mode"]>().toEqualTypeOf<ModeName | undefined>()
+    expectTypeOf<SteeringOptions["mode"]>().toEqualTypeOf<ModeName | DeclaredMode | undefined>()
   })
 })

package/src/flows/runtime.ts

@@ -8,6 +8,12 @@ import type { WorkflowBuild } from "./factory.js"
 /** A steering-file mode: a built-in format's name or a `config.modes` entry. */
 export type ModeName = "qa" | "review" | "findings" | (string & {})
 
+/** A format declared with `listFormat`/`sectionFormat` from `@pmelab/gtd/steering`, used as a step's mode. */
+export interface DeclaredMode {
+  readonly name: string
+  readonly spec: string
+}
+
 interface SteeringCommon {
   /** Display name for drivers and viewers. */
   readonly label?: string | undefined
@@ -24,8 +30,8 @@ type SteeringFile =
     }
   | {
       readonly file: string
-      /** The steering file's mode — a built-in name or a `modes:` entry. Requires `file`. */
-      readonly mode: ModeName
+      /** The steering file's mode — a built-in name, a `modes:` entry, or a declared format. Requires `file`. */
+      readonly mode: ModeName | DeclaredMode
     }
 
 /** A steering-file declaration shared by the steps that rest on one. `mode` requires `file`. */

package/src/steering/Declared.test.ts

@@ -0,0 +1,218 @@
+import { describe, expect, it } from "vitest"
+import { formatFinding, listFormat, sectionFormat } from "./index.js"
+import { formatFromSpec, steeringFormatFor } from "./internal.js"
+
+const criteria = listFormat({
+  name: "criteria",
+  section: { title: /^acceptance criteria$/i, example: "Acceptance criteria", level: 2 },
+  item: { id: /^AC-\d+$/, separator: ":", example: "AC-1" },
+  ids: { unique: true },
+})
+
+const doc = (...lines: string[]): string => `${lines.join("\n")}\n`
+
+const problems = (format: { validate: (c: string) => readonly unknown[] }, content: string) =>
+  format.validate(content).map((f) => formatFinding("F.md", f as never))
+
+describe("listFormat", () => {
+  it("parses ID'd items, joining indented continuation lines", () => {
+    const parsed = criteria.parse(
+      doc(
+        "# Plan",
+        "",
+        "## Acceptance criteria",
+        "",
+        "- AC-1: first",
+        "  wrapped",
+        "- AC-2: second",
+        "",
+        "## Next",
+        "",
+        "- not read",
+      ),
+    )
+    expect(parsed.problems).toEqual([])
+    expect(parsed.items).toEqual([
+      { line: 4, id: "AC-1", text: "first wrapped" },
+      { line: 6, id: "AC-2", text: "second" },
+    ])
+  })
+
+  it("validates its own sample, and describes itself", () => {
+    expect(criteria.validate(criteria.sample)).toEqual([])
+    expect(criteria.sample).toBe("## Acceptance criteria\n\n- AC-1: Describe the item.\n")
+    expect(criteria.instructions).toContain("`## Acceptance criteria`")
+    expect(criteria.instructions).toContain("`AC-1`")
+  })
+
+  it("reports a missing, repeated or misleveled section", () => {
+    expect(problems(criteria, doc("# Plan"))).toEqual([
+      "missing the `## Acceptance criteria` section",
+    ])
+    expect(problems(criteria, doc("### Acceptance criteria", "", "- AC-1: a"))).toEqual([
+      'F.md:1: "Acceptance criteria" is a level-3 heading — write it as `## Acceptance criteria`',
+    ])
+    expect(
+      problems(
+        criteria,
+        doc("## Acceptance criteria", "", "- AC-1: a", "", "## Acceptance criteria"),
+      ),
+    ).toEqual(['F.md:5: "Acceptance criteria" repeats the section on line 1 — keep one'])
+  })
+
+  it("reports markers it does not allow, and mixed markers", () => {
+    const numbered = listFormat({ name: "steps", markers: ["-", "1."] })
+    expect(problems(criteria, doc("## Acceptance criteria", "", "* AC-1: a"))).toEqual([
+      "F.md:3: `*` is not an allowed marker — use `-`",
+    ])
+    expect(problems(numbered, doc("- a", "1. b"))).toEqual([
+      "F.md:2: `1.` mixes markers in one list — the list started with `-`",
+    ])
+  })
+
+  it("reads a numbered list it allows rather than parsing it as empty", () => {
+    const numbered = listFormat({ name: "signals", markers: ["1."] })
+    expect(numbered.parse(doc("1. a", "2. b")).items.map((i) => i.text)).toEqual(["a", "b"])
+  })
+
+  it("reports an unindented continuation line", () => {
+    expect(problems(criteria, doc("## Acceptance criteria", "", "- AC-1: a", "b"))).toEqual([
+      "F.md:4: continuation line is not indented — indent it under its item, or separate it with a blank line",
+    ])
+  })
+
+  it("never reads a fenced item, and reports an unclosed fence", () => {
+    const parsed = criteria.parse(
+      doc("## Acceptance criteria", "", "- AC-1: a", "", "```", "- AC-2: b", "```"),
+    )
+    expect(parsed.items.map((i) => i.id)).toEqual(["AC-1"])
+    expect(parsed.problems.map((p) => p.message)).toContain(
+      "a list item inside a code fence is not read as an item",
+    )
+    expect(
+      problems(criteria, doc("## Acceptance criteria", "", "- AC-1: a", "", "```", "x")),
+    ).toEqual(["F.md:5: code fence is never closed"])
+  })
+
+  it("keeps a fence indented under its item as part of the item", () => {
+    expect(
+      problems(
+        criteria,
+        doc("## Acceptance criteria", "", "- AC-1: a", "", "  ```", "  - x", "  ```", "- AC-2: b"),
+      ),
+    ).toEqual([])
+  })
+
+  it("reports duplicate and missing IDs, and empty items", () => {
+    expect(
+      problems(
+        criteria,
+        doc("## Acceptance criteria", "", "- AC-1: a", "- AC-1: b", "- c", "- AC-3:"),
+      ),
+    ).toEqual([
+      "F.md:4: duplicate ID AC-1 — first on line 3",
+      "F.md:5: item has no ID — start it `AC-1: …`",
+      "F.md:6: empty item — AC-3 has no text",
+    ])
+    expect(problems(listFormat({ name: "plain" }), doc("- a", "-"))).toEqual(["F.md:2: empty item"])
+  })
+
+  it("reports text between items and nesting", () => {
+    expect(
+      problems(
+        criteria,
+        doc(
+          "## Acceptance criteria",
+          "",
+          "- AC-1: a",
+          "",
+          "Aside.",
+          "",
+          "- AC-2: b",
+          "  - AC-3: c",
+        ),
+      ),
+    ).toEqual([
+      "F.md:5: text between items — make it part of an item, or move it out of the list",
+      "F.md:8: nested list — this format is flat, one level of items",
+    ])
+  })
+
+  it("forbids, strips or requires checkboxes", () => {
+    expect(problems(criteria, doc("## Acceptance criteria", "", "- [ ] AC-1: a"))).toEqual([
+      "F.md:3: no checkboxes in this list — drop the `[ ]`",
+    ])
+    const todo = listFormat({ name: "todo", checkbox: "require" })
+    expect(todo.parse(doc("- [x] a")).items).toEqual([{ line: 0, text: "a", checked: true }])
+    expect(problems(todo, doc("- a"))).toEqual([
+      "F.md:1: every item starts with a checkbox — write `- [ ] …`",
+    ])
+    const stripped = listFormat({ name: "stripped", checkbox: "strip" })
+    expect(stripped.parse(doc("- [ ] a", "- b")).items.map((i) => i.checked)).toEqual([
+      false,
+      false,
+    ])
+  })
+
+  it("forbids wrapping when told to", () => {
+    const flat = listFormat({ name: "flat", wrap: "forbid" })
+    expect(problems(flat, doc("- a", "  b"))).toEqual([
+      "F.md:2: one line per item — this line continues the one above",
+    ])
+  })
+
+  it("refuses an inconsistent declaration", () => {
+    expect(() => listFormat({ name: "Bad Name" })).toThrow("format name")
+    expect(() =>
+      listFormat({ name: "x", item: { id: /^A\d$/, separator: ":", example: "B1" } }),
+    ).toThrow("does not match")
+    expect(() => listFormat({ name: "x", section: { title: /a/, level: 2 } })).toThrow("example")
+  })
+})
+
+describe("sectionFormat", () => {
+  const findings = sectionFormat({ name: "notes", level: 2, title: "unique" })
+
+  it("parses sections with their bodies", () => {
+    expect(
+      findings.parse(doc("# T", "", "## A", "", "one", "### deeper", "## B")).sections,
+    ).toEqual([
+      { line: 2, title: "A", body: "one\n### deeper" },
+      { line: 6, title: "B", body: "" },
+    ])
+    expect(findings.validate(findings.sample)).toEqual([])
+  })
+
+  it("reports repeated titles, a shallower heading, and a heading in an unclosed fence", () => {
+    expect(problems(findings, doc("## A", "## a", "# Up", "```", "## C"))).toEqual([
+      'F.md:2: "a" repeats the section on line 1 — titles are unique',
+      'F.md:3: "Up" is a level-1 heading — sections are `##`',
+      "F.md:4: code fence is never closed",
+    ])
+  })
+})
+
+describe("formatFromSpec", () => {
+  it("rebuilds the same format from its spec, RegExps included", () => {
+    const rebuilt = formatFromSpec(criteria.spec)
+    const content = doc("## Acceptance criteria", "", "- AC-1: a", "- AC-1: b", "* x")
+    expect(rebuilt.name).toBe("criteria")
+    expect(rebuilt.validate(content)).toEqual(criteria.validate(content))
+    const notes = sectionFormat({ name: "notes", level: 2, title: "unique" })
+    expect(formatFromSpec(notes.spec).validate("## A\n## A\n")).toEqual(
+      notes.validate("## A\n## A\n"),
+    )
+  })
+
+  it("throws on a spec no declaration produces", () => {
+    expect(() => formatFromSpec('{"kind":"nope"}')).toThrow("not a declared format spec")
+  })
+})
+
+describe("the built-in formats", () => {
+  it("are not declared formats — none of these rules apply to them", () => {
+    expect(
+      steeringFormatFor("findings")!.validate("## A\n\n- [ ] fix\n\n## A\n\n- [ ] fix\n"),
+    ).toEqual([])
+  })
+})