@erclx/aitk 0.41.1 → 0.44.0

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "aitk",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "0.41.1",
+  "version": "0.44.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/docs/agents/commands.md

@@ -27,6 +27,7 @@ Full help: `aitk <command> --help`. Behavior notes for the install and sync verb
 | `aitk feedback`          | Write toolkit feedback from stdin to `.claude/review/`, or open a GitHub issue with `--github` |
 | `aitk transcripts <url>` | Fetch a YouTube transcript with metadata frontmatter (needs `yt-dlp`)                          |
 | `aitk tasks archive`     | Move a shipped task off the board, clear its ordering row, and regenerate the index            |
+| `aitk tasks validate`    | Report board rows whose plan, task file, group, or file set does not hold (`--json`)           |
 | `aitk comments scan`     | Measure comment density by language and comment kind, with a trend recomputed from git         |
 | `aitk context audit`     | Report required sections, length, depth, bullet weight, cited paths, provenance, and drift     |
 | `aitk capture [source]`  | Render HTML capture sources to PNG, toolkit-only and absent from an installed package          |
@@ -45,7 +46,7 @@ Each domain exposes a consistent shape where applicable: `list`, `install`, `syn
 | `wiki`      | `init`                                                                 |
 | `design`    | `render`                                                               |
 | `slides`    | `render`, `list`                                                       |
-| `tasks`     | `archive`                                                              |
+| `tasks`     | `archive`, `validate`                                                  |
 | `comments`  | `scan`                                                                 |
 | `context`   | `audit`                                                                |
 

package/docs/agents/index.md

@@ -20,4 +20,4 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Overview](overview.md): What this folder covers, the invocation rules every command inherits, and where domain behavior is documented instead
 - [Sandbox](sandbox.md): Scenario routing, the expectation scoring surface, and the coverage census over scenarios and skills
 - [Scripting](scripting.md): The runtime catalogs that replace hardcoded names, what each carries, and a headless invocation per domain
-- [Tasks](tasks.md): Selecting a shipped task by stem or pull request, the refusal reasons, and why the board root defaults to the main worktree
+- [Tasks](tasks.md): Selecting a shipped task by stem or pull request, the refusal reasons, the board checks validate runs, and why the board root defaults to the main worktree

package/docs/agents/tasks.md

@@ -1,10 +1,12 @@
 ---
 title: Tasks
-description: Selecting a shipped task by stem or pull request, the refusal reasons, and why the board root defaults to the main worktree
+description: Selecting a shipped task by stem or pull request, the refusal reasons, the board checks validate runs, and why the board root defaults to the main worktree
 ---
 
 # Tasks
 
+## Archive
+
 `aitk tasks archive` moves a shipped task from `.claude/tasks/` into `.claude/.tmp/task-archive/`, drops its row from `priority.md`, and regenerates the board index. The three run as one unit, so the attended and unattended callers cannot archive differently.
 
 Name the task by its filename stem, or by the pull request it carries:
@@ -30,4 +32,34 @@ Skills branch on the reason rather than on the exit code:
 aitk tasks archive --pull-request 673 --json | jq -r 'if .ok then .task else .reason end'
 ```
 
+## Validate
+
+`aitk tasks validate` reports what each row of `priority.md` claims against what the tree holds. It reads and never writes, because a row is a session's claim about readiness and a validator that repaired one would be asserting the claim it exists to test.
+
+```bash
+aitk tasks validate
+aitk tasks validate --json
+```
+
+Four checks run. Plan and Collisions are the two halves of the `## Run now` test the board standard states. Mapping and Grouping test the folder contract and hold for every group:
+
+| Check      | What it reports                                                                   |
+| ---------- | --------------------------------------------------------------------------------- |
+| Plan       | A `## Run now` row whose Plan column carries no link, or one resolving to no file |
+| Mapping    | A row naming no task file, and a task file no row names                           |
+| Grouping   | A task carrying a row in more than one readiness group                            |
+| Collisions | Two `## Run now` rows whose Touches columns name a path in common                 |
+
+The collision check is the one a person cannot run by eye. Paths come from the backticked spans in the Touches column, a span naming no file is dropped, and a directory collides with any file beneath it. A `## Run now` row whose column parses to nothing is reported rather than skipped, since a row stating no file set makes a claim nothing can check.
+
+Exit codes: `0` every check passed, `1` refused, `2` at least one finding. The `reason` field carries which gate refused: `no-board`, `no-ordering`, or `no-groups`. A board grouping under headings of its own trips `no-groups` rather than being read against columns it never declared.
+
+Columns are read from each table's own header rather than by position, so a project whose board differs from this one is reported for what it lacks. The `index`, `priority`, and `session` siblings are skipped, since none of the three is a task.
+
+Skills branch on the findings rather than on the exit code:
+
+```bash
+aitk tasks validate --json | jq -r '.findings[] | "\(.kind): \(.subject)"'
+```
+
 For the board format, the `Pull request:` line, and the archive rules, see `.claude/standards/tasks.md`.

package/docs/ai-workflow.md

@@ -86,6 +86,8 @@ The sweep reads the whole board rather than the tasks the session touched. It is
 
 `.claude/tasks/` is gitignored and resolves at the main worktree root, so every session shares one board. One file per task is what keeps concurrent sessions from overwriting each other, since a gitignored board has no history to recover a lost write from. Its `index.md` is generated by a hook rather than by `bun run check`, because the whole-repo index walk skips gitignored folders. A hand-maintained `priority.md` sits beside it carrying execution order and what each task is waiting on, which the alphabetical index cannot express.
 
+`aitk tasks validate` checks what those rows claim against what the tree holds: every plan pointer resolves, every row and task file map one to one, no task sits in two groups, and no two rows marked ready touch the same file. That last check is the half a reader cannot run by eye, and it is what keeps two workers from being handed colliding work. It reports and never writes, because a row is the orchestrator's claim and a validator repairing one would assert the claim it exists to test. Nothing fires it automatically, since the board is gitignored per-machine scratch with no shared moment to hang a hook on, so the orchestrator's sweep calls it at the point the readiness claim is made.
+
 `aitk:claude-tasks` owns the two operations that bracket a task's life. It creates the file, holding the filename convention and the frontmatter contract so a malformed write cannot break the index for every sibling, and it moves a shipped task to `.claude/.tmp/task-archive/`. Creation is where the origin invariant is enforced: every task names a plan, a groundwork folder, or an issue, since a task with no origin is either lost context or work nobody decided to do. Archiving a task leaves its plan alone, because `aitk:claude-docs` owns the plans sweep and already holds the last-live-citation rule. That makes the order load-bearing, so the archive verb refuses to run while the `Plan:` line still points into `.claude/plans/`. The sweep only reaches tasks still in the live folder, and archiving the task first would strand the plan there with nothing citing it.
 
 Nothing chained that archive until the `post-merge` git hook landed. Every earlier step fires from `aitk:claude-autoship` or `aitk:git-ship`, both of which finish while the pull request is still open, so a task archived there would close for work that may be abandoned. The board is gitignored, which rules out reading it from anywhere but the machine that pulled. The hook names the board's archive candidates and stays silent otherwise, including on a project with no board.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/aitk",
   "type": "module",
-  "version": "0.41.1",
+  "version": "0.44.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/snippets/claude/orchestrator-sweep.md

@@ -5,6 +5,8 @@ Sweep the board as orchestrator after merging. Run this once per batch of merges
 3. Re-verify every plan already written, not only the ones this sweep writes. A queued plan goes stale from whatever merged while it waited, and the loop's verify step fires at handoff rather than after a merge, so nothing else catches it. Grep each construct the plan names and count the sites against its claim, then open each file rather than trusting its account.
 4. Re-check any precondition a plan states about live state outside the repository. A remote branch, an open issue, or an installed version was true when the plan was written and is not a fact about the tree.
 
+Run `aitk tasks validate` once the board is rewritten and before reporting it. It resolves every plan pointer, maps rows against task files both ways, and tests the `## Run now` file sets for overlap, which is the half of the readiness claim a reading of the board cannot check. It reports and never writes, so fix each row it names and run it again. A finding it reports is a board defect rather than a task finding, so it goes nowhere but the board.
+
 Place every finding the merged work produced before promoting anything. A finding that changes a rule goes to the standard or the rule that states it, one that changes another task goes to that task's Findings, and one that overturns a groundwork lean gets marked answered in that folder. A pull request body counts as nowhere, since the thread stops being read the moment it merges.
 
 Report what closed, what moved, and what is ready to hand a worker. Name the file set each ready task touches, so the reader can check the disjointness claim rather than take it.

package/src/commands/tasks.ts

@@ -2,6 +2,11 @@ import { relative } from 'node:path'
 import { $ } from 'bun'
 import type { Command } from 'commander'
 import { type ArchiveOutcome, archiveTask } from '@/tasks/archive'
+import {
+  type Finding,
+  type ValidateOutcome,
+  validateBoard,
+} from '@/tasks/validate'
 import {
   intro,
   logAdd,
@@ -9,16 +14,25 @@ import {
   logInfo,
   logRemove,
   logStep,
+  logWarn,
   outro,
   pipeOutput,
 } from '@/ui'
 
+/** Returned when the board carries a finding, which is the gating result. */
+const EXIT_FINDINGS = 2
+
 interface ArchiveCommandOptions {
   readonly json?: boolean
   readonly pullRequest?: string
   readonly root?: string
 }
 
+interface ValidateCommandOptions {
+  readonly json?: boolean
+  readonly root?: string
+}
+
 /**
  * The board is shared scratch at the main worktree root, and `git worktree
  * list` puts that root first. A pull inside a linked worktree fires the same
@@ -71,6 +85,105 @@ export function register(program: Command): void {
     .action(async (task: string | undefined, opts: ArchiveCommandOptions) => {
       process.exitCode = await runArchive(task, opts)
     })
+
+  tasks
+    .command('validate')
+    .description(
+      'Report what each board row claims against what the tree holds',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .option('--root <path>', 'Board root, defaulting to the main worktree')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Checks:',
+        '  every Run now row points at a plan file that resolves',
+        '  every row maps to a task file and every task file to a row',
+        '  no task carries more than one row',
+        '  no two Run now rows touch the same file',
+        '',
+        'Exit codes:',
+        '  0  every check passed',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '  2  the board carries at least one finding',
+        '',
+        'It reports and never writes. A row is a claim about readiness, so a',
+        'session fixes the row the report names.',
+        '',
+        'Examples:',
+        '  aitk tasks validate',
+        '  aitk tasks validate --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: ValidateCommandOptions) => {
+      process.exitCode = await runValidate(opts)
+    })
+}
+
+async function runValidate(opts: ValidateCommandOptions): Promise<number> {
+  const root = opts.root ?? (await mainWorktreeRoot())
+  const outcome = await validateBoard(root)
+
+  return reportValidation(outcome, opts.json ?? false, root)
+}
+
+function reportValidation(
+  outcome: ValidateOutcome,
+  emitJson: boolean,
+  root: string,
+): number {
+  if (!outcome.ok) {
+    if (emitJson) {
+      process.stdout.write(
+        `${JSON.stringify({ ok: false, reason: outcome.reason, message: outcome.message })}\n`,
+      )
+      return 1
+    }
+
+    intro('aitk tasks validate')
+    logStep('Refused')
+    logError(outcome.message)
+    outro()
+    return 1
+  }
+
+  if (!emitJson) {
+    intro('aitk tasks validate')
+    logStep('Board')
+    logInfo(
+      `${outcome.rows} row(s) across the readiness groups, ${outcome.tasks} task file(s)`,
+    )
+
+    logStep(outcome.findings.length === 0 ? 'Clean' : 'Findings')
+    if (outcome.findings.length === 0) {
+      logInfo('every row resolves, maps one to one, and touches its own files')
+    } else {
+      for (const finding of outcome.findings) logWarn(describe(finding))
+    }
+    outro()
+  }
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({
+        ok: true,
+        root,
+        rows: outcome.rows,
+        tasks: outcome.tasks,
+        findings: outcome.findings,
+      })}\n`,
+    )
+  }
+
+  return outcome.findings.length > 0 ? EXIT_FINDINGS : 0
+}
+
+function describe(finding: Finding): string {
+  const scope = finding.group ? `${finding.group}: ` : ''
+  return `${scope}${finding.subject} ${finding.message}`
 }
 
 async function runArchive(

package/src/tasks/archive.ts

@@ -8,10 +8,12 @@ const ARCHIVE_DIR = join('.claude', '.tmp', 'task-archive')
 const PLANS_DIR = join('.claude', 'plans')
 
 /**
- * Generated and hand-maintained siblings that sit on the board without being
- * tasks. The post-merge hook skips the same two names.
+ * Siblings that sit on the board without being tasks: the generated index, the
+ * hand-maintained ordering, and the pre-compaction session map. `validate`
+ * reads the same list, so neither verb can count a sibling as a task the other
+ * does not.
  */
-const RESERVED_STEMS = ['index', 'priority'] as const
+export const RESERVED_STEMS = ['index', 'priority', 'session'] as const
 
 export const ARCHIVE_REFUSALS = [
   'no-board',

package/src/tasks/validate.ts

@@ -0,0 +1,401 @@
+import { existsSync } from 'node:fs'
+import { readdir, readFile } from 'node:fs/promises'
+import { join, resolve } from 'node:path'
+import { RESERVED_STEMS, tasksDir } from '@/tasks/archive'
+
+const ORDERING_FILE = 'priority.md'
+
+/**
+ * The readiness headings `.claude/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',
+  'touches-unstated',
+  'touches-collided',
+] 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
+}
+
+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
+}
+
+export interface ValidateReport {
+  readonly ok: true
+  readonly rows: number
+  readonly tasks: number
+  readonly findings: readonly Finding[]
+}
+
+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)
+}
+
+/**
+ * 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}/`)
+  )
+}
+
+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)
+}
+
+/**
+ * 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.
+ */
+export function readBoard(text: string): {
+  readonly rows: readonly BoardRow[]
+  readonly groups: readonly BoardGroup[]
+} {
+  const rows: BoardRow[] = []
+  const groups: BoardGroup[] = []
+
+  let group: BoardGroup | undefined
+  let header: string[] | undefined
+
+  for (const line of text.split('\n')) {
+    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 || !line.trimStart().startsWith('|')) continue
+
+    const cells = splitCells(line)
+    if (isSeparator(cells)) continue
+
+    if (!header) {
+      header = cells
+      continue
+    }
+
+    const taskAt = columnIndex(header, 'task')
+    const planAt = columnIndex(header, 'plan')
+    const touchesAt = columnIndex(header, 'touches')
+
+    const task = taskAt >= 0 ? (cells[taskAt] ?? '') : ''
+    const target = linkTarget(task)
+    const plan = planAt >= 0 ? linkTarget(cells[planAt] ?? '') : undefined
+
+    rows.push({
+      group,
+      label: linkText(task) || task,
+      stem: target ? stemOf(target) : undefined,
+      plan,
+      touches: touchesAt >= 0 ? readPaths(cells[touchesAt] ?? '') : undefined,
+    })
+  }
+
+  return { rows, groups }
+}
+
+async function listTaskStems(dir: string): Promise<string[]> {
+  const entries = await readdir(dir)
+  const reserved: readonly string[] = RESERVED_STEMS
+
+  return entries
+    .filter((entry) => entry.endsWith('.md'))
+    .map((entry) => entry.slice(0, -'.md'.length))
+    .filter((stem) => !reserved.includes(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))
+}
+
+function checkMapping(
+  rows: readonly BoardRow[],
+  stems: readonly string[],
+  dir: string,
+): Finding[] {
+  const findings: Finding[] = []
+  const seen = new Map<string, number>()
+
+  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.`,
+      })
+    }
+  }
+
+  for (const stem of stems) {
+    if (!seen.has(stem)) {
+      findings.push({
+        kind: 'row-missing',
+        group: undefined,
+        subject: stem,
+        message: 'is a task file with no row on the board.',
+      })
+    }
+  }
+
+  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 ?? []).filter((path) =>
+        (right.touches ?? []).some((other) => sharesPath(path, other)),
+      )
+
+      if (shared.length === 0) continue
+
+      findings.push({
+        kind: 'touches-collided',
+        group: 'Run now',
+        subject: `${left.stem ?? left.label} and ${right.stem ?? right.label}`,
+        message: `both touch ${shared.join(', ')}.`,
+      })
+    }
+  }
+
+  return findings
+}
+
+function refuse(reason: ValidateRefusal, message: string): ValidateRefused {
+  return { ok: false, reason, message }
+}
+
+/**
+ * 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): Promise<ValidateOutcome> {
+  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 } = 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(', ')}.`,
+    )
+  }
+
+  const stems = await listTaskStems(dir)
+
+  const findings = [
+    ...checkMapping(rows, stems, dir),
+    ...checkPlans(rows, dir, root),
+    ...checkCollisions(rows),
+  ]
+
+  return { ok: true, rows: rows.length, tasks: stems.length, findings }
+}

package/standards/tasks.md

@@ -26,12 +26,15 @@ Does not govern:
 .claude/tasks/
 ├── index.md              ← generated, never hand-edited
 ├── priority.md           ← hand-maintained execution order
+├── session.md            ← optional, what a compaction is about to destroy
 ├── v09.0-sync-paths.md
 └── v13.0-toolkit-drift.md
 ```
 
 One file per task is what keeps the board safe under parallel sessions. Two sessions working different tasks never write the same file, which matters because a gitignored board has no history to recover a clobbered write from.
 
+Three siblings sit in the folder without being tasks, and each earns its place by being governed somewhere. `index.md` and `priority.md` are governed here. `session.md` is the pre-compaction handoff, written by `orchestrator-handoff` and read by `orchestrator-resume`, and it is optional: a project running no orchestrator carries no such file. Anything reading the folder as a task list skips all three, so a name outside the set is a task whatever it holds.
+
 `index.md` is generated from sibling frontmatter. The folder is gitignored, so the whole-repo index walk skips it and a hook passing the changed path regenerates it instead. Never hand-edit it.
 
 The `claude-tasks` skill creates and archives task files. `claude-docs` marks outcomes `[x]` in an existing file and sweeps the plans those tasks cite. Neither does the other's job.
@@ -50,6 +53,8 @@ Readiness is three groups under fixed headings, `## Run now`, `## Up next`, and
 
 Each group fixes its own columns, which follow from the test above it rather than from preference. Neither half of the `## Run now` test is checkable without the file set and the plan sitting beside the task. The blocker column under `## Up next` names whether a collision or a dependency holds the row. `## Needs a plan` states no file set at all, because a task with no plan has no bounded one to state. A group with no rows keeps its heading and its header row.
 
+`aitk tasks validate` reads those columns and reports where a row's claim and the tree disagree: a plan pointer resolving to no file, a row and a task file that do not map one to one, a task in two groups, and two `## Run now` rows touching a path in common. Run it when the readiness claim is made rather than on a schedule, since the board is gitignored per-machine scratch and no shared moment exists to hang it on. It reports and never writes, so a session fixes the row it names.
+
 ```markdown
 ---
 title: Priority