@erclx/canon 4.0.0

package/src/tasks/validate.ts

@@ -0,0 +1,1001 @@
+import { existsSync, statSync } from 'node:fs'
+import { readdir, readFile } from 'node:fs/promises'
+import { join, resolve } from 'node:path'
+import {
+  archiveDir,
+  isReservedStem,
+  readOutcomes,
+  readPullRequest,
+  tasksDir,
+} from '@/tasks/archive'
+import { gitTrunkReader, type TrunkReader } from '@/tasks/trunk'
+
+const ORDERING_FILE = 'priority.md'
+const BACKLOG_FILE = 'backlog.md'
+
+/**
+ * The readiness headings `standards/tasks.md` fixes. The names are the
+ * contract rather than a suggestion, so a board grouping under names of its own
+ * reads as carrying no group at all and the run refuses instead of reporting a
+ * clean board it never parsed.
+ */
+export const BOARD_GROUPS = ['Run now', 'Up next', 'Needs a plan'] as const
+
+export type BoardGroup = (typeof BOARD_GROUPS)[number]
+
+export const VALIDATE_REFUSALS = [
+  'no-board',
+  'no-ordering',
+  'no-groups',
+] as const
+
+export type ValidateRefusal = (typeof VALIDATE_REFUSALS)[number]
+
+export const FINDING_KINDS = [
+  'plan-unstated',
+  'plan-unresolved',
+  'task-unresolved',
+  'row-missing',
+  'row-duplicated',
+  'row-misshapen',
+  'row-untabled',
+  'row-misordered',
+  'touches-unstated',
+  'touches-collided',
+  'blocker-settled',
+  'blocker-unresolved',
+] as const
+
+export type FindingKind = (typeof FINDING_KINDS)[number]
+
+export interface Finding {
+  readonly kind: FindingKind
+  readonly group: BoardGroup | undefined
+  readonly subject: string
+  readonly message: string
+}
+
+/**
+ * A parked row neither half of the blocker check reached. Three of the five
+ * blocker kinds put no fact on disk, so a run reporting findings alone would
+ * read as a board with nothing stale on it.
+ */
+export interface Untested {
+  readonly group: BoardGroup
+  readonly subject: string
+  readonly message: string
+}
+
+/**
+ * A `Touches` cell naming a bare folder, which claims every file under it and
+ * so collides with every row a later session writes there. The claim is often
+ * correct, since a row rewriting a whole directory has no other way to say so,
+ * which is why it reports beside the findings rather than inside them and moves
+ * no exit code.
+ */
+export interface FolderClaim {
+  readonly group: BoardGroup
+  readonly subject: string
+  readonly message: string
+}
+
+/**
+ * A backlog line, which carries a pointer and nothing else. The backlog is
+ * explicitly unordered, so a line has no position to read and no columns to
+ * resolve.
+ */
+export interface BacklogRow {
+  readonly label: string
+  readonly stem: string | undefined
+}
+
+export interface BoardRow {
+  readonly group: BoardGroup
+  readonly label: string
+  readonly stem: string | undefined
+  readonly plan: string | undefined
+  /** Absent when the group fixes no `Touches` column, empty when it read none. */
+  readonly touches: readonly string[] | undefined
+  /** Absent when the group fixes no `Waiting on` column, which is `## Run now`. */
+  readonly waiting: string | undefined
+  /** The ordinal phrase a `Waiting on` cell states about its own position, undefined when the cell carries none. */
+  readonly ordinal: OrdinalWord | 'last' | undefined
+}
+
+export interface ValidateReport {
+  readonly ok: true
+  readonly rows: number
+  readonly backlog: number
+  readonly tasks: number
+  readonly findings: readonly Finding[]
+  readonly untested: readonly Untested[]
+  readonly claims: readonly FolderClaim[]
+}
+
+export interface ValidateRefused {
+  readonly ok: false
+  readonly reason: ValidateRefusal
+  readonly message: string
+}
+
+export type ValidateOutcome = ValidateReport | ValidateRefused
+
+export function orderingPath(root: string): string {
+  return join(tasksDir(root), ORDERING_FILE)
+}
+
+export function backlogPath(root: string): string {
+  return join(tasksDir(root), BACKLOG_FILE)
+}
+
+/**
+ * Pulls the target out of a markdown link, which is how both the `Task` and the
+ * `Plan` column spell their pointer. A cell carrying prose instead of a link
+ * yields nothing, and that absence is the finding rather than a parse failure.
+ */
+function linkTarget(cell: string): string | undefined {
+  const match = /\[[^\]]*\]\(([^)]+)\)/.exec(cell)
+  return match ? match[1].trim() : undefined
+}
+
+function linkText(cell: string): string {
+  const match = /\[([^\]]*)\]\([^)]+\)/.exec(cell)
+  return (match ? match[1] : cell).trim()
+}
+
+function stemOf(target: string): string | undefined {
+  const name = target.split('/').pop()
+  if (!name || !name.endsWith('.md')) return undefined
+  return name.slice(0, -'.md'.length)
+}
+
+/**
+ * Reads the file set out of a `Touches` cell written as prose. Paths are the
+ * backticked spans, which is the only marker the column carries, and a span
+ * naming a skill or a command rather than a file is dropped by the same test.
+ *
+ * An extension opens with a letter, which is what separates `commands.md` from
+ * a task version like `v40.2`. Reading the version as a path would collide two
+ * rows that merely cite the same task.
+ */
+export function readPaths(cell: string): string[] {
+  const spans = cell.match(/`[^`]+`/g) ?? []
+  const paths = spans
+    .map((span) => span.slice(1, -1).trim())
+    .filter(
+      (span) => span.includes('/') || /\.[A-Za-z][A-Za-z0-9]*$/.test(span),
+    )
+    .map((span) => span.replace(/^\.\//, '').replace(/\/+$/, ''))
+
+  return [...new Set(paths)]
+}
+
+/**
+ * Two paths touch the same work when they are equal or one contains the other.
+ * A row naming a directory and a row naming a file inside it collide, which a
+ * set intersection on the written strings alone would miss.
+ */
+function sharesPath(left: string, right: string): boolean {
+  return (
+    left === right ||
+    left.startsWith(`${right}/`) ||
+    right.startsWith(`${left}/`)
+  )
+}
+
+/**
+ * Whether a `Touches` path names a directory. The tree answers for a path that
+ * resolves, which is the only reading that separates a folder from a file
+ * carrying no extension, such as a hook script.
+ *
+ * A path the row has yet to create resolves to nothing, so the name decides
+ * there. `readPaths` admits a span for one of two reasons, a slash or an
+ * extension, so a span surviving without an extension is one a slash let
+ * through and reads as a folder.
+ */
+function isFolder(path: string, root: string): boolean {
+  const target = resolve(root, path)
+  if (existsSync(target)) return statSync(target).isDirectory()
+
+  return !/\.[A-Za-z][A-Za-z0-9]*$/.test(path)
+}
+
+function splitCells(line: string): string[] {
+  return line
+    .trim()
+    .replace(/^\|/, '')
+    .replace(/\|$/, '')
+    .split('|')
+    .map((cell) => cell.trim())
+}
+
+function isSeparator(cells: readonly string[]): boolean {
+  return cells.every((cell) => /^:?-{3,}:?$/.test(cell))
+}
+
+function columnIndex(header: readonly string[], name: string): number {
+  return header.findIndex((cell) => cell.toLowerCase() === name)
+}
+
+function isGroup(heading: string): heading is BoardGroup {
+  return (BOARD_GROUPS as readonly string[]).includes(heading)
+}
+
+const ORDINAL_WORDS = [
+  'first',
+  'second',
+  'third',
+  'fourth',
+  'fifth',
+  'sixth',
+  'seventh',
+  'eighth',
+  'ninth',
+  'tenth',
+  'eleventh',
+  'twelfth',
+  'thirteenth',
+  'fourteenth',
+  'fifteenth',
+  'sixteenth',
+  'seventeenth',
+  'eighteenth',
+  'nineteenth',
+  'twentieth',
+] as const
+
+type OrdinalWord = (typeof ORDINAL_WORDS)[number]
+
+const ORDINAL_HERE = new RegExp(
+  `\\b(${ORDINAL_WORDS.join('|')})\\s+here\\b`,
+  'i',
+)
+const LAST_AT_END = /\blast\.?\s*$/i
+
+/**
+ * Reads the ordinal phrase a `Waiting on` cell states about its own position,
+ * searching the whole cell for `<ordinal> here` or the bare word `last` rather
+ * than anchoring to where the cell opens. The phrase sits at the end of the
+ * sentence on every row that carries one, as in `nothing, cleared 2026-08-31
+ * when it merged. Third here`. The two-word phrase is safe to find anywhere,
+ * since it needs both a closed vocabulary word and `here` beside it, but a
+ * bare `last` is one of the commonest words in English and this corpus writes
+ * it constantly, as in `the last of the two instruments this rename needs`.
+ * Anchoring it to the end of the cell is what keeps that prose out of the
+ * findings, since every row that actually declares itself last puts the word
+ * there and nowhere else. A cell carrying neither reads as unordered rather
+ * than as an error, which keeps a legitimately-phrased row out of the
+ * findings.
+ */
+function readOrdinal(cell: string): OrdinalWord | 'last' | undefined {
+  const here = ORDINAL_HERE.exec(cell)
+  if (here?.[1]) return here[1].toLowerCase() as OrdinalWord
+
+  return LAST_AT_END.test(cell) ? 'last' : undefined
+}
+
+function isRowLine(line: string): boolean {
+  return line.trimStart().startsWith('|')
+}
+
+/**
+ * Whether a header candidate genuinely opens a table, meaning the line right
+ * behind it is a separator carrying the same cell count. A row landing where a
+ * blank line already closed the table above it looks identical to a fresh
+ * header until this read, since both are the first pipe line the walk has
+ * seen since the reset.
+ */
+function opensTable(
+  header: readonly string[],
+  next: string | undefined,
+): boolean {
+  if (next === undefined || !isRowLine(next)) return false
+  const cells = splitCells(next)
+  return isSeparator(cells) && cells.length === header.length
+}
+
+/**
+ * Parses the ordering file into rows keyed by readiness group. Columns are read
+ * from each table's own header rather than by position, so a group whose shape
+ * differs from this repository's is reported for what it lacks instead of
+ * having its second cell read as something it never was.
+ *
+ * The walk carries one more piece of state than a header: whether the table
+ * that header opened is still open. A blank or prose line closes it, so a row
+ * stranded behind that close is read as one candidate header among many rather
+ * than as a continuation of the table above, and each surviving row's cell
+ * count is checked against the header it actually followed.
+ */
+export function readBoard(text: string): {
+  readonly rows: readonly BoardRow[]
+  readonly groups: readonly BoardGroup[]
+  readonly findings: readonly Finding[]
+} {
+  const rows: BoardRow[] = []
+  const groups: BoardGroup[] = []
+  const findings: Finding[] = []
+
+  const lines = text.split('\n')
+
+  let group: BoardGroup | undefined
+  let header: string[] | undefined
+
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i] ?? ''
+    const heading = /^##\s+(.+?)\s*$/.exec(line)
+    if (heading) {
+      const title = heading[1]
+      group = isGroup(title) ? title : undefined
+      header = undefined
+      if (group && !groups.includes(group)) groups.push(group)
+      continue
+    }
+
+    if (!group) continue
+
+    if (!isRowLine(line)) {
+      header = undefined
+      continue
+    }
+
+    const cells = splitCells(line)
+    if (isSeparator(cells)) continue
+
+    if (!header) {
+      if (!opensTable(cells, lines[i + 1])) {
+        findings.push({
+          kind: 'row-untabled',
+          group,
+          subject: line.trim(),
+          message:
+            'sits outside a table. The table above it already closed at the line before it.',
+        })
+        continue
+      }
+
+      header = cells
+      continue
+    }
+
+    if (cells.length !== header.length) {
+      findings.push({
+        kind: 'row-misshapen',
+        group,
+        subject: line.trim(),
+        message: `carries ${cells.length} cell(s) against the ${header.length}-cell header above it.`,
+      })
+      continue
+    }
+
+    const taskAt = columnIndex(header, 'task')
+    const planAt = columnIndex(header, 'plan')
+    const touchesAt = columnIndex(header, 'touches')
+    const waitingAt = columnIndex(header, 'waiting on')
+
+    const task = taskAt >= 0 ? (cells[taskAt] ?? '') : ''
+    const target = linkTarget(task)
+    const plan = planAt >= 0 ? linkTarget(cells[planAt] ?? '') : undefined
+    const waiting = waitingAt >= 0 ? (cells[waitingAt] ?? '') : undefined
+
+    rows.push({
+      group,
+      label: linkText(task) || task,
+      stem: target ? stemOf(target) : undefined,
+      plan,
+      touches: touchesAt >= 0 ? readPaths(cells[touchesAt] ?? '') : undefined,
+      waiting,
+      ordinal: waiting ? readOrdinal(waiting) : undefined,
+    })
+  }
+
+  return { rows, groups, findings }
+}
+
+/**
+ * Reports a `## Needs a plan` row whose stated ordinal disagrees with where it
+ * actually sits in that group. Reading the sequence for gaps and duplicates on
+ * its own would detect less, since row position is contiguous by
+ * construction, and a hand-renumbered sequence is exactly a case where the
+ * prose and the position have come apart.
+ */
+function checkOrdinals(rows: readonly BoardRow[]): Finding[] {
+  const findings: Finding[] = []
+  const parked = rows.filter((row) => row.group === 'Needs a plan')
+
+  parked.forEach((row, index) => {
+    if (!row.ordinal) return
+
+    const position = index + 1
+    const expected =
+      row.ordinal === 'last'
+        ? parked.length
+        : ORDINAL_WORDS.indexOf(row.ordinal) + 1
+
+    if (expected === position) return
+
+    const phrase = row.ordinal === 'last' ? 'last' : `${row.ordinal} here`
+    findings.push({
+      kind: 'row-misordered',
+      group: row.group,
+      subject: subjectOf(row),
+      message: `declares itself "${phrase}", but sits at position ${position} of ${parked.length} in ${row.group}.`,
+    })
+  })
+
+  return findings
+}
+
+/**
+ * Parses the backlog into one row per bullet carrying a link. The backlog is a
+ * flat list rather than a table, so there is no header to resolve and no group
+ * to sit under, and a bullet holding prose instead of a pointer is skipped.
+ *
+ * Skipping it rather than reporting it is what keeps the intro paragraph and
+ * any explanatory bullet out of the findings. The task that bullet meant to
+ * name is still accounted for, because a stem no line reaches is reported by
+ * `checkMapping` as carrying no row on either surface.
+ */
+export function readBacklog(text: string): readonly BacklogRow[] {
+  const rows: BacklogRow[] = []
+
+  for (const line of text.split('\n')) {
+    if (!/^\s*[-*]\s/.test(line)) continue
+
+    const target = linkTarget(line)
+    if (!target) continue
+
+    // A pointer carrying a directory names something other than a sibling task,
+    // the way `citedStem` reads the same shape on the board.
+    const path = target.split('#')[0] ?? ''
+    if (path.includes('/')) continue
+
+    const stem = stemOf(path)
+    if (stem && isReservedStem(stem)) continue
+
+    rows.push({ label: linkText(line) || line.trim(), stem })
+  }
+
+  return rows
+}
+
+async function listTaskStems(dir: string): Promise<string[]> {
+  const entries = await readdir(dir)
+
+  return entries
+    .filter((entry) => entry.endsWith('.md'))
+    .map((entry) => entry.slice(0, -'.md'.length))
+    .filter((stem) => !isReservedStem(stem))
+    .sort()
+}
+
+/**
+ * Resolves a pointer against the board and against the project root both, the
+ * way `claude-docs` reads the same line. A fragment is dropped first, since an
+ * anchor is part of the link and never part of the path.
+ */
+function resolves(target: string, dir: string, root: string): boolean {
+  const path = target.split('#')[0]
+  if (!path) return false
+
+  return existsSync(resolve(dir, path)) || existsSync(resolve(root, path))
+}
+
+/**
+ * Accounts every task file against both surfaces the board spans. A task sits
+ * on `priority.md` when it would plausibly be planned soon and on `backlog.md`
+ * otherwise, so a file reached by neither is the dropped one this reports and a
+ * file reached by both claims two contradictory things about itself.
+ */
+function checkMapping(
+  rows: readonly BoardRow[],
+  backlog: readonly BacklogRow[],
+  stems: readonly string[],
+  dir: string,
+): Finding[] {
+  const findings: Finding[] = []
+  const seen = new Map<string, number>()
+  const listed = new Set<string>()
+
+  for (const row of backlog) {
+    if (!row.stem) {
+      findings.push({
+        kind: 'task-unresolved',
+        group: undefined,
+        subject: row.label,
+        message: 'is a backlog line naming no task file.',
+      })
+      continue
+    }
+
+    listed.add(row.stem)
+
+    if (!existsSync(join(dir, `${row.stem}.md`))) {
+      findings.push({
+        kind: 'task-unresolved',
+        group: undefined,
+        subject: row.stem,
+        message: 'has a backlog line and no task file.',
+      })
+    }
+  }
+
+  for (const row of rows) {
+    if (!row.stem) {
+      findings.push({
+        kind: 'task-unresolved',
+        group: row.group,
+        subject: row.label,
+        message: 'names no task file, so the row points at nothing.',
+      })
+      continue
+    }
+
+    seen.set(row.stem, (seen.get(row.stem) ?? 0) + 1)
+
+    if (!existsSync(join(dir, `${row.stem}.md`))) {
+      findings.push({
+        kind: 'task-unresolved',
+        group: row.group,
+        subject: row.stem,
+        message: 'has a row and no task file.',
+      })
+    }
+  }
+
+  for (const [stem, count] of seen) {
+    if (count > 1) {
+      findings.push({
+        kind: 'row-duplicated',
+        group: undefined,
+        subject: stem,
+        message: `carries ${count} rows. A task belongs to exactly one group.`,
+      })
+    }
+
+    if (listed.has(stem)) {
+      findings.push({
+        kind: 'row-duplicated',
+        group: undefined,
+        subject: stem,
+        message:
+          'carries a row on the board and a line on the backlog. A task sits on one surface.',
+      })
+    }
+  }
+
+  for (const stem of stems) {
+    if (!seen.has(stem) && !listed.has(stem)) {
+      findings.push({
+        kind: 'row-missing',
+        group: undefined,
+        subject: stem,
+        message:
+          'is a task file with no row on the board and no line on the backlog.',
+      })
+    }
+  }
+
+  return findings
+}
+
+function checkPlans(
+  rows: readonly BoardRow[],
+  dir: string,
+  root: string,
+): Finding[] {
+  const findings: Finding[] = []
+
+  for (const row of rows) {
+    if (row.group !== 'Run now') continue
+
+    if (!row.plan) {
+      findings.push({
+        kind: 'plan-unstated',
+        group: row.group,
+        subject: row.stem ?? row.label,
+        message:
+          'states no plan pointer, so the readiness claim cannot be checked.',
+      })
+      continue
+    }
+
+    if (!resolves(row.plan, dir, root)) {
+      findings.push({
+        kind: 'plan-unresolved',
+        group: row.group,
+        subject: row.stem ?? row.label,
+        message: `points at ${row.plan}, which resolves to no file.`,
+      })
+    }
+  }
+
+  return findings
+}
+
+/**
+ * The half of the `## Run now` test a person cannot check by eye. Two rows a
+ * worker may be handed at once must touch disjoint files, and the `Touches`
+ * column is the only place either set is written down.
+ */
+function checkCollisions(rows: readonly BoardRow[]): Finding[] {
+  const findings: Finding[] = []
+  const ready = rows.filter((row) => row.group === 'Run now')
+
+  for (const row of ready) {
+    // An absent column and an unreadable one both leave the row untested by
+    // the loop below, so reporting only the second would pass a board whose
+    // `## Run now` table declares no file set at all.
+    if (!row.touches || row.touches.length === 0) {
+      findings.push({
+        kind: 'touches-unstated',
+        group: row.group,
+        subject: row.stem ?? row.label,
+        message: 'names no file, so its collisions cannot be read.',
+      })
+    }
+  }
+
+  for (let i = 0; i < ready.length; i += 1) {
+    for (let j = i + 1; j < ready.length; j += 1) {
+      const left = ready[i]
+      const right = ready[j]
+      const shared = (left.touches ?? []).flatMap((path) => {
+        const other = (right.touches ?? []).find((candidate) =>
+          sharesPath(path, candidate),
+        )
+        return other === undefined
+          ? []
+          : [describeShared(path, other, left, right)]
+      })
+
+      if (shared.length === 0) continue
+
+      findings.push({
+        kind: 'touches-collided',
+        group: 'Run now',
+        subject: `${subjectOf(left)} and ${subjectOf(right)}`,
+        message: `both touch ${joinShared(shared)}.`,
+      })
+    }
+  }
+
+  return findings
+}
+
+function subjectOf(row: BoardRow): string {
+  return row.stem ?? row.label
+}
+
+/**
+ * Names one path two rows share, and the row that claimed it as a folder when
+ * one side named a directory holding the other's file. Which side contributed
+ * the containing path is the fact a reader acts on, and printing the shared
+ * strings alone leaves an over-broad cell and a genuine overlap identical.
+ *
+ * The shorter path is the container, because `sharesPath` holds for an unequal
+ * pair only when one is a prefix of the other up to a separator.
+ */
+function describeShared(
+  path: string,
+  other: string,
+  left: BoardRow,
+  right: BoardRow,
+): string {
+  if (path === other) return path
+
+  const container = path.length < other.length ? path : other
+  const owner = container === path ? left : right
+  return `${container}, which ${subjectOf(owner)} claims as a folder`
+}
+
+/**
+ * A folder clause carries a comma of its own, so a comma between clauses would
+ * read as another path. The plain list keeps the comma it has always had.
+ */
+function joinShared(clauses: readonly string[]): string {
+  const separator = clauses.some((clause) => clause.includes(',')) ? '; ' : ', '
+  return clauses.join(separator)
+}
+
+/**
+ * Reports a `Touches` cell naming a bare folder. The claim collides with every
+ * row a later session writes under that folder, and it is legitimate whenever
+ * the row does rewrite the directory, so this states the reach rather than
+ * calling it a defect.
+ *
+ * The scan takes `## Run now` alone, where `checkCollisions` takes it. A cell in
+ * another group describes work nobody has planned, so it is written as a
+ * sentence and rewritten at planning time, and a claim read off one reports on
+ * prose rather than on a file set. That is the shape that teaches a reader to
+ * skip the report. A parked folder claim surfaces when the row is promoted,
+ * which is also when its cell becomes a set anything can act on.
+ */
+function checkFolderClaims(
+  rows: readonly BoardRow[],
+  root: string,
+): FolderClaim[] {
+  const claims: FolderClaim[] = []
+
+  for (const row of rows.filter((candidate) => candidate.group === 'Run now')) {
+    for (const path of row.touches ?? []) {
+      if (!isFolder(path, root)) continue
+
+      claims.push({
+        group: row.group,
+        subject: subjectOf(row),
+        message: `claims the whole ${path} folder, so it collides with every row written under it.`,
+      })
+    }
+  }
+
+  return claims
+}
+
+/**
+ * Reads the task a blocker cell cites. A task pointer is a bare sibling
+ * filename, the way every `Task` column spells one, so a target carrying a
+ * directory names something else and yields nothing. A row waiting on a plan
+ * links that plan, and reading its stem as a task would report the row settled
+ * against a folder the plan does not sit in.
+ */
+function citedStem(cell: string): string | undefined {
+  const target = linkTarget(cell)?.split('#')[0]
+  if (!target || target.includes('/')) return undefined
+  return stemOf(target)
+}
+
+/** What one blocker citation produced, since a row can be neither settled nor open. */
+interface CitedResult {
+  readonly findings: readonly Finding[]
+  readonly untested: readonly Untested[]
+}
+
+function nothing(): CitedResult {
+  return { findings: [], untested: [] }
+}
+
+/**
+ * Reports what a cited task does to the row waiting on it. A file sitting in
+ * the archive settles the row, and a live file settles it only once the work it
+ * carries is on the trunk. A file carrying no outcome box settles nothing,
+ * since a file the check could not parse is not evidence of a finished one.
+ *
+ * A citation resolving in neither folder is a broken pointer rather than a
+ * closed task, and the two take different findings. Reading an absent file as
+ * archived states a specific fact about a file nobody ever wrote, which is what
+ * a renamed task or a typo produces.
+ *
+ * A closed outcome is not the same fact as landed work. The ship chain marks
+ * outcomes as its first step and opens the pull request several steps later, so
+ * a check reading the checkbox reports the row settled while the branch is
+ * still in review. The pull request the task names is what the trunk is asked
+ * about, and a task naming none leaves the row untested rather than settled,
+ * because the only local signal left is the checkbox that produced the defect.
+ *
+ * The outcome list comes off `readOutcomes` rather than a pattern of its own,
+ * so this check cannot disagree with the archive and outcome verbs about which
+ * checkboxes are outcomes and which sit inside a block a task displays.
+ */
+async function checkCitedTask(
+  group: BoardGroup,
+  subject: string,
+  cited: string,
+  root: string,
+  trunk: TrunkReader,
+): Promise<CitedResult> {
+  const live = join(tasksDir(root), `${cited}.md`)
+
+  if (!existsSync(live)) {
+    if (existsSync(join(archiveDir(root), `${cited}.md`))) {
+      return settled(group, subject, `waits on ${cited}, which is archived.`)
+    }
+
+    return {
+      findings: [
+        {
+          kind: 'blocker-unresolved',
+          group,
+          subject,
+          message: `waits on ${cited}, which is neither on the board nor archived.`,
+        },
+      ],
+      untested: [],
+    }
+  }
+
+  const text = await readFile(live, 'utf8')
+  const { open, closed } = readOutcomes(text)
+  if (open.length > 0 || closed.length === 0) return nothing()
+
+  const pullRequest = readPullRequest(text)
+  if (pullRequest === undefined) {
+    return untestedRow(
+      group,
+      subject,
+      `waits on ${cited}, which closed every outcome but names no pull request, so nothing tests whether the work reached the trunk.`,
+    )
+  }
+
+  const landed = await trunk(pullRequest)
+  if (landed === undefined) {
+    return untestedRow(
+      group,
+      subject,
+      `waits on ${cited}, whose pull request #${pullRequest} could not be read against the trunk.`,
+    )
+  }
+
+  if (!landed) return nothing()
+
+  return settled(
+    group,
+    subject,
+    `waits on ${cited}, whose pull request #${pullRequest} reached the trunk.`,
+  )
+}
+
+function settled(
+  group: BoardGroup,
+  subject: string,
+  message: string,
+): CitedResult {
+  return {
+    findings: [{ kind: 'blocker-settled', group, subject, message }],
+    untested: [],
+  }
+}
+
+function untestedRow(
+  group: BoardGroup,
+  subject: string,
+  message: string,
+): CitedResult {
+  return { findings: [], untested: [{ group, subject, message }] }
+}
+
+/**
+ * Re-takes the two blocker kinds a command can settle, over every row outside
+ * `## Run now`. A cited task is settled by being archived or by closing every
+ * outcome, and a cited path is settled by no `## Run now` row still holding it.
+ *
+ * Both halves gate on a citation the cell carries, never on a column beside it.
+ * The board standard gives a collision cell the file held by the running task,
+ * so a row whose cell names no file was parked by something else and its
+ * `Touches` column says nothing about what holds it. Reading that column
+ * instead reports a cleared collision on a row no collision ever parked, and
+ * counts the row as re-tested, which is the more expensive half of that error.
+ *
+ * The cell is read for citations rather than parsed into fields, since the
+ * standard fixes three forms for it and leaves it prose. A row neither half
+ * reached is returned as untested, because the other three kinds are a person's
+ * to judge and silence about them reads as a board with nothing stale on it.
+ */
+async function checkParked(
+  rows: readonly BoardRow[],
+  root: string,
+  trunk: TrunkReader,
+): Promise<{ findings: Finding[]; untested: Untested[] }> {
+  const findings: Finding[] = []
+  const untested: Untested[] = []
+  const running = rows.filter((row) => row.group === 'Run now')
+
+  for (const row of rows) {
+    if (row.group === 'Run now') continue
+
+    const subject = row.stem ?? row.label
+    const cell = row.waiting ?? ''
+    const cited = citedStem(cell)
+    const contested = readPaths(cell)
+
+    if (cited) {
+      const result = await checkCitedTask(
+        row.group,
+        subject,
+        cited,
+        root,
+        trunk,
+      )
+      findings.push(...result.findings)
+      untested.push(...result.untested)
+    }
+
+    const held = contested.filter((path) =>
+      running.some((run) =>
+        (run.touches ?? []).some((other) => sharesPath(path, other)),
+      ),
+    )
+
+    if (contested.length > 0 && held.length === 0) {
+      findings.push({
+        kind: 'blocker-settled',
+        group: row.group,
+        subject,
+        message: `waits on ${contested.join(', ')}, which nothing under Run now holds.`,
+      })
+    }
+
+    if (!cited && contested.length === 0) {
+      untested.push({
+        group: row.group,
+        subject,
+        message:
+          'cites no task and no file, so neither half of its blocker is mechanical.',
+      })
+    }
+  }
+
+  return { findings, untested }
+}
+
+function refuse(reason: ValidateRefusal, message: string): ValidateRefused {
+  return { ok: false, reason, message }
+}
+
+export interface ValidateOptions {
+  /** Overridden by tests, which supply the trunk rather than reaching for git. */
+  readonly trunk?: TrunkReader
+}
+
+/**
+ * Reports what every board row claims against what the tree holds. It writes
+ * nothing: a row is a session's claim about readiness, and a validator that
+ * repaired one would be asserting the claim it exists to test.
+ */
+export async function validateBoard(
+  root: string,
+  options: ValidateOptions = {},
+): Promise<ValidateOutcome> {
+  const trunk = options.trunk ?? gitTrunkReader(root)
+  const dir = tasksDir(root)
+  if (!existsSync(dir)) {
+    return refuse('no-board', `No task board at ${dir}.`)
+  }
+
+  const ordering = orderingPath(root)
+  if (!existsSync(ordering)) {
+    return refuse('no-ordering', `No ordering file at ${ordering}.`)
+  }
+
+  const {
+    rows,
+    groups,
+    findings: shapeFindings,
+  } = readBoard(await readFile(ordering, 'utf8'))
+
+  if (groups.length === 0) {
+    return refuse(
+      'no-groups',
+      `No readiness group in ${ORDERING_FILE}. Expected one of: ${BOARD_GROUPS.join(', ')}.`,
+    )
+  }
+
+  // An absent backlog reads as empty rather than refusing. A project that has
+  // never needed the second surface keeps every task on the board, which is the
+  // one-to-one mapping this check ran before the backlog existed.
+  const backlogFile = backlogPath(root)
+  const backlog = existsSync(backlogFile)
+    ? readBacklog(await readFile(backlogFile, 'utf8'))
+    : []
+
+  const stems = await listTaskStems(dir)
+  const parked = await checkParked(rows, root, trunk)
+
+  const findings = [
+    ...shapeFindings,
+    ...checkMapping(rows, backlog, stems, dir),
+    ...checkPlans(rows, dir, root),
+    ...checkCollisions(rows),
+    ...checkOrdinals(rows),
+    ...parked.findings,
+  ]
+
+  return {
+    ok: true,
+    rows: rows.length,
+    backlog: backlog.length,
+    tasks: stems.length,
+    findings,
+    untested: parked.untested,
+    claims: checkFolderClaims(rows, root),
+  }
+}