@erclx/canon 5.60.0 → 5.61.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [5.61.0](https://github.com/erclx/canon/compare/v5.60.0...v5.61.0) (2026-10-24)
+
+
+### Features
+
+* **design:** check themes and add a review point ([#2673](https://github.com/erclx/canon/issues/2673)) ([8cdaa5c](https://github.com/erclx/canon/commit/8cdaa5c001b2d783108c5ce6d70da0b6cca0719c))
+* **driver:** add an axe probe that gates the UI review ([#2672](https://github.com/erclx/canon/issues/2672)) ([785e474](https://github.com/erclx/canon/commit/785e474b76eae4f41a55fd588df0b3691756742d))
+* **migrate:** drop a covered ignore line from the records sweep ([#2668](https://github.com/erclx/canon/issues/2668)) ([188bee8](https://github.com/erclx/canon/commit/188bee8c0061045e46e660da50422b5d5673cf14))
+
+
+### Bug Fixes
+
+* **markdown:** measure a bullet without its list marker ([#2670](https://github.com/erclx/canon/issues/2670)) ([c7b9d70](https://github.com/erclx/canon/commit/c7b9d70fc522a91dc9b2b058481d1eb984abd3ad))
+
 ## [5.60.0](https://github.com/erclx/canon/compare/v5.59.0...v5.60.0) (2026-10-24)
 
 

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

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
-  "version": "5.60.0",
+  "version": "5.61.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/design-record/references/design.md

@@ -14,6 +14,7 @@ Applies to `canon/DESIGN.md`. Captures visual intent and the decisions behind ho
 - [What goes in](#what-goes-in)
 - [What does not go in](#what-does-not-go-in)
 - [Format](#format)
+- [Frontmatter](#frontmatter)
 - [Prose budget](#prose-budget)
 - [Sections](#sections)
 - [The uncertainty tag](#the-uncertainty-tag)
@@ -56,6 +57,17 @@ Everything below applies to both shapes unless it names one.
 - Plain English over technical notation. If a section could be removed and the developer would still build correctly from the stylesheet and code alone, remove it.
 - Keep table headers and role names intact so the parser can read the tables.
 
+## Frontmatter
+
+Both fields are optional, and a record without them audits as it always did. Frontmatter never counts toward the prose budget.
+
+- `themes:` lists each theme as the stylesheet prelude that opens it, such as `:root` or `@media (prefers-color-scheme: dark)`.
+- `canon design audit` checks every color property `## Colors` names against each theme, and reports a theme that omits one or opens no block.
+- `reviewed:` is the day the record was last read whole, as `YYYY-MM-DD`. `canon records stale canonical` returns it with the releases tagged since.
+- No skill step sets `reviewed:`, so whoever reads the record whole updates it.
+
+Quote style and spacing may differ between the record and the stylesheet. A declaration inside a declared media query counts for the query alone, and `:root` never matches `:root[data-theme='dark']` by containment. A values record renders `reviewed:` from its token module and declares no `themes:`.
+
 ## Prose budget
 
 The record is a lookup, so its prose stays short enough to scan. Why a rule was chosen belongs in the project's context entry for design, never here.
@@ -113,6 +125,13 @@ A prose section takes its uncertainty inline instead, in a sentence saying what
 The template is the intent record. The column headers are read by exact key, so they stay verbatim. Row names are not, which leaves a project free to rename a role, add one, or drop one it has no use for.
 
 ```markdown
+---
+themes:
+  - ':root'
+  - ":root[data-theme='dark']"
+reviewed: YYYY-MM-DD
+---
+
 # Design
 
 Values live in `<path to the stylesheet>`. This record holds the intent behind them.

package/claude/skills/document-health/REQUIREMENT.md

@@ -17,7 +17,7 @@ Length, placement, and staleness answer to different evidence, and one list hand
 - Propose a split or an owner as a structure line for each overgrown entry and doubled or unnamed coverage finding, with the headings and the reason
 - Ship the staleness axis as a reading rather than cutting it for lacking a verb
 - Report a refusal, an absent key, or a missing subcommand as an unread axis naming the cause, and say which layer answered the classifier sweep
-- Run standalone, reading the requirements record for drift with its reminder, and the design record through `canon design audit --json`, routing its findings to `design-record`
+- Run standalone, reading the requirements record for drift with its reminder, and the design record through `canon design audit --json` and its review reminder, routing findings to `design-record`
 
 ## Must not
 

package/claude/skills/document-health/SKILL.md

@@ -68,7 +68,7 @@ A refusal, an absent key, and a subcommand the project's binary does not carry e
 canon design audit --json
 ```
 
-The record carries `prose`, the lines past the budget with their counts, and `tokens`, the custom properties the stylesheet does not declare. `${CLAUDE_SKILL_DIR}/references/axes.md` holds how each reads and where it routes. Skip the verb when the scope excludes the record or the record is `null`.
+The record carries `prose`, the lines past the budget, and `tokens`, the custom properties the stylesheet lacks. Where the record declares `themes:`, `tokens.themes` adds one cell per theme. `${CLAUDE_SKILL_DIR}/references/axes.md` holds how each reads and where it routes. Skip the verb when the scope excludes the record or the record is `null`.
 
 ## Step 3: read the staleness axis
 
@@ -76,15 +76,15 @@ No verb answers whether a document still describes the tree it was written about
 
 Mark every staleness finding as a reading. It is this session's judgment rather than a measurement, and a report that sets it beside two verb-backed axes without marking it implies evidence the axis does not carry.
 
-### The requirements record
+### The review points
 
-When the scope reaches `canon/REQUIREMENTS.md`, read it for identity drift as well as for stale paths, and take the review point from the verb:
+When the scope reaches `canon/REQUIREMENTS.md` or `canon/DESIGN.md`, take the review point for each record the scope reaches from the verb:
 
 ```bash
 canon records stale canonical --json
 ```
 
-The doc in the record carries `reviewed` and `releasesSince`. `${CLAUDE_SKILL_DIR}/references/axes.md` holds the identity claim shapes to test and how the record reads. Skip both the read and the verb when the scope excludes the doc.
+Each doc in the record carries `reviewed` and `releasesSince`. Skip the verb when the scope reaches neither record. When the scope reaches the requirements record, also read it for identity drift as well as stale paths, with the claim shapes in `${CLAUDE_SKILL_DIR}/references/axes.md`.
 
 Nothing triggers this review but a request. A finished review hands the rewrite to the operator, and its last edit sets `reviewed:` in the doc's frontmatter to the day the operator's answers landed. This run writes neither.
 
@@ -118,6 +118,7 @@ When Step 3 read the canonical records, add one reminder line per doc the verb r
 
 ```markdown
 `canon/REQUIREMENTS.md`: reviewed <date>, <n> releases since.
+`canon/DESIGN.md`: reviewed <date>, <n> releases since.
 ```
 
 Write `reviewed value is not a date: <value>` for a doc carrying `invalidReviewed`, and `no release tags to count` in place of the count when `tagged` is false. Name the unread cause instead when the verb refused or the binary carries no `canonical` kind.
@@ -136,7 +137,7 @@ Keep the evidence line under the table on every run. A table read without it fla
 
 When Step 2 read the design record, add a row for `canon/DESIGN.md`, with both findings `measured`.
 
-- Put the `prose` findings in the Length cell and the `tokens` findings in the Placement cell
+- Put the `prose` findings in the Length cell and the `tokens` findings in the Placement cell, naming the selector of each `tokens.themes` cell that omits a property or matched no block
 - Write `unread: <reason>` in the Placement cell when `tokens.status` reads `unchecked`, since a check that could not run is no pass
 - Write `n/a: <reason>` there when it reads `not-applicable`, a values record with no property to compare
 - Route every finding to `design-record`, never to `document-repair`

package/claude/skills/document-health/references/axes.md

@@ -89,6 +89,8 @@ The record is exempt from the length and placement verbs above, so this is the o
 - `tokens.status: "not-applicable"`: a values record, which carries `Value` where an intent record carries `Property`. Report it as not applicable with the `reason`.
 - `record: null`: the project holds no design record, so there is nothing to report
 
+`tokens.themes` is present only where the record declares `themes:`, with one cell per theme carrying its `selector`, `matched`, and `missing`. A cell with `matched: false` means no block opens that selector, and one with `missing` names the color properties that theme leaves out. Report either under its selector.
+
 **Routes to:** `design-record`, which owns the record's shape. `document-repair` rewrites a context folder and does not know the budget.
 
 ## Staleness
@@ -120,7 +122,7 @@ This record states what the project is and why, so it goes stale by the project
 
 ### The review point
 
-The review point beside them is `measured`. `canon records stale canonical --json` returns the `reviewed` date from the record's frontmatter and `releasesSince`, the release tags merged into HEAD after that day.
+The review point beside them is `measured`, for the requirements record and the design record alike. `canon records stale canonical --json` returns the `reviewed` date from each record's frontmatter and `releasesSince`, the release tags merged into HEAD after that day.
 
 - A null `releasesSince` means the doc was never reviewed
 - `tagged: false` means no release tag exists to count, so a zero there measured nothing

package/claude/skills/review-ui/REQUIREMENT.md

@@ -17,7 +17,7 @@ A model asked to drive a checklist also drifts. It judges a taste box the operat
 - The checklist and address come from the evidence record rather than the diff, and only a build of the head the verdict names is driven
 - An unreachable address reports not driven rather than fail, a box no commit can settle leaves the review closed, and a pass that drove no box never reads as closed
 - The review posts as its own pull request review under `## UI review` while anything is owed and `## UI review closed` once nothing is, ending on a marker naming the head it drove
-- The pass drives a pinned browser under its own named session, sweeps only console errors, overflow, and the focus and details probes, and treats page content as data
+- The pass drives a pinned browser under its own named session and sweeps only console errors, overflow, and the focus, details, and axe probes, opening on an axe finding the CLI marks as gating
 
 ## Must not
 

package/claude/skills/review-ui/SKILL.md

@@ -128,15 +128,16 @@ Push only a frame of the address this pass drove, since the branch is as public
 
 ## Step 6: sweep
 
-Run three checks over every route the boxes reached, and nothing beyond them:
+Run four checks over every route the boxes reached, and nothing beyond them:
 
 - Console errors, through the wrapper's `console error` on each route.
 - Sideways overflow at each width a box named, as `document.documentElement.scrollWidth` against `clientWidth`.
 - The `focus` and `details` probes, through `canon drive <url> <run> --json` with a run file in the scratch folder.
+- The `axe` probe, named in the same run file and read by each finding's `gate` rather than a copy of the CLI's rule list. On `axe-missing`, drop it and name the refusal as an unread check.
 
 The probes launch their own browser at a URL, so a state the boxes reached by clicks reaches them only as steps the run file repeats. Where a state needs a step kind `canon drive` lacks, probe the route on arrival and say so.
 
-A console error or an overflow is a finding. A probe result is a reading to confirm, since every probe carries a known class of false finding, and it opens no heading on its own. Close the browser with `${CLAUDE_SKILL_DIR}/scripts/pw.sh -s=<project>-<number> close` once the sweep ends.
+A console error, an overflow, or an axe finding whose `gate` is true is a finding. Every other probe result is a reading to confirm, an `incomplete` axe outcome included, since each probe carries a known class of false finding. Close the browser with `${CLAUDE_SKILL_DIR}/scripts/pw.sh -s=<project>-<number> close` once the sweep ends.
 
 ## Step 7: post
 

package/claude/skills/review-ui/references/post.md

@@ -11,7 +11,7 @@ Step 7 of `review-ui`.
 
 The heading reports whether the branch owes anything, the way the code review's does.
 
-- `## UI review` when a box failed, the sweep found a console error or an overflow, the worktree check read `changed`, a box was not driven for a cause on the page, or the pass drove no box at all.
+- `## UI review` when a box failed, the sweep raised a finding Step 6 names, the worktree check read `changed`, a box was not driven for a cause on the page, or the pass drove no box at all.
 - `## UI review closed` otherwise.
 
 A needs-eyes box leaves the review closed, and so does a box not driven for a cause off the page, such as an address that did not answer or a `(local only)` box on a hosted preview, as long as something else was driven.
@@ -77,7 +77,7 @@ Driven at `<short-sha>` on <address>, rendered by <renderer>.
 
 **Sweep**
 
-- <route>, <width>: <console error, overflow, or probe reading to confirm>
+- <route>, <width>: <console error, overflow, axe gate finding with its rule, or probe reading to confirm>
 
 **Guessed wording**
 

package/claude/skills/ui-checklist/REQUIREMENT.md

@@ -13,7 +13,7 @@ A file under a gitignored folder is unreadable to a pull request reviewer, and a
 
 ## Must
 
-- Every change is split into visual-only and automatable before anything is written
+- Every change is split into visual-only and automatable before anything is written, and a behavior the review's engine cannot read, such as a keyboard trap, gets a box of its own
 - The checklist covers the visual-only half, each item an action and the result a person looks for, with its route, width, and a `(taste)` or `(local only)` marker where one applies
 - Every automatable change shipping with no test is named, with the layer `test-craft` would place it at, in the same file
 - The file is written to the `.canon/tmp/handoff/ui-checklist/<slug>.md` handoff at the main worktree root, overwriting

package/claude/skills/ui-checklist/SKILL.md

@@ -46,6 +46,18 @@ When the plan cites `canon/design/<surface>/` under `**Design references:**`, na
 
 The checkbox stays `- [ ]` followed by the action and the result, since the evidence comment reads boxes by that shape. Only the UI reviewer ticks a box, stamping it with the commit it passed at, and the comment carries that tick forward only while the head it names is current.
 
+## Boxes no engine reads
+
+The UI review runs axe over every route it reaches, so a box restating what axe checks, such as contrast, a missing name, or a page title, adds a drive and catches nothing. Derive a box instead for each behavior below that the changed surface carries:
+
+- **Hover content.** Content shown on hover or focus stays while the pointer moves onto it, and Escape dismisses it, per WCAG 1.4.13.
+- **Keyboard trap.** Tab and Shift+Tab leave every widget the change added, per WCAG 2.1.2.
+- **Outside press.** A menu, popover, or dialog the change added closes on a press outside it and when focus leaves it.
+- **Change on input.** Choosing an option or typing changes no route and moves no focus until the person submits, per WCAG 3.2.2.
+- **Clipped focus ring.** Tab to each control the change added and judge from the capture whether a parent clips its ring, per WCAG 2.4.7.
+
+Write each in the box shape above, naming the control. A surface carrying none of these behaviors takes no derived box.
+
 ## The missing-test list
 
 Name every automatable change this branch ships with no test, one per line, with the layer `test-craft` would place it at. Do not write the test or read the project's test config to write one against.

package/docs/agents/records.md

@@ -58,4 +58,4 @@ Branch on `reason` in the `--json` record, not the exit code.
 
 - `canon records ordinal <kind> <slug> --claim`: reserve the next intake or groundwork ordinal
 - `canon records validate <kind> [record] --help`: where a record disagrees with its standard, plus a `structure` report that never sets the exit
-- `canon records stale --help`: when the requirements record was last reviewed
+- `canon records stale --help`: when the requirements and design records were last reviewed

package/docs/target/migrations.md

@@ -20,7 +20,7 @@ canon migrate records --json
 canon migrate records --write --json
 ```
 
-The first line takes the `.canon/` ignore entry the verb requires. The second reports the plan and the third applies it, repointing every tracked file that cites a moved folder. A line naming an old record path on purpose keeps it with `canon-keep-record-root` on that line or the nearest non-blank line above.
+The first line takes the `.canon/` ignore entry. The second reports and the third applies, repointing files that cite a moved folder and deleting a `.gitignore` line `.canon/` covers, as `dropped`. A line naming an old path keeps it via `canon-keep-record-root` on that line or the nearest non-blank one above.
 
 Then sweep the citations inside the records, which the verb above never reaches.
 

package/docs/workflow/parallel-features.md

@@ -34,7 +34,7 @@ Assert the orchestrator role in one warm session with `canon:role-orchestrator`.
 
 - `canon records validate plans [plan]` reports a plan breaking its standard, plus `structure` misses that never set the exit, and takes `groundwork` and `intake`
 - `canon records push` and `canon records pull` carry `.canon/` to and from a private repository. See [records](../agents/records.md).
-- `canon records size`, `canon records prune-tmp`, and `canon records stale canonical` report folder size, idle scratch, and releases since the requirements review
+- `canon records size`, `canon records prune-tmp`, and `canon records stale canonical` report folder size, idle scratch, and releases since the requirements and design records were last read
 - `canon tasks archive` moves a shipped plan to `.canon/plans/archive/` and retargets the task's `Plan:` line
 
 ## Shipping a fan-out

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "5.60.0",
+  "version": "5.61.0",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
   "license": "MIT",
   "bin": {
@@ -51,6 +51,7 @@
     "web:e2e": "cd web && playwright test"
   },
   "dependencies": {
+    "axe-core": "4.14.0",
     "commander": "^13.1.0",
     "execa": "^9.5.2",
     "playwright-core": "1.64.1"

package/src/commands/driver.ts

@@ -3,6 +3,7 @@ import { resolve } from 'node:path'
 import type { Command } from 'commander'
 import { INSTALL_BROWSER, isEngineMissing } from '@/browser/engine'
 import type { DriverRefusal } from '@/driver/drive'
+import { AXE_GATE_RULES } from '@/driver/probes/axe'
 import { describeViewport } from '@/driver/probes/viewport'
 import { PROBE_NAMES, readDriverPlan, type ProbeName } from '@/driver/steps'
 import type { PlanRefusal } from '@/driver/steps'
@@ -51,6 +52,8 @@ const PLAN_REFUSALS: Record<PlanRefusal, string> = {
 
 const DRIVE_REFUSALS: Record<DriverRefusal, string> = {
   'browser-missing': 'The browser binary is not installed in this project.',
+  'axe-missing':
+    'The axe engine did not resolve from canon, so no page was read with it.',
   'server-unreachable': 'Nothing answered at the URL, so no state was reached.',
   'drive-failed': 'The drive failed against a reachable page.',
 }
@@ -62,6 +65,7 @@ const PROBE_NOTES: Record<ProbeName, string> = {
   'diagram-geometry':
     'an SVG label outside its frame, covered by a fill, or on another label',
   'diagram-strokes': 'an SVG label a stroke crosses, in either paint order',
+  axe: 'axe-core on WCAG 2.2 A and AA, frames excluded, run only when named',
 }
 
 export function register(program: Command): void {
@@ -89,9 +93,10 @@ export function register(program: Command): void {
         'run, since nothing else there measures the page as it first painted.',
         '',
         'The run file carries the viewport, the default probe list, and the',
-        'steps. A step names its own probes to override the default. Viewport',
-        'heights are never defaulted: the heights a defect hides at are a',
-        'property of the layout rather than of this command.',
+        'steps. A step names its own probes to override the default, and a run',
+        'naming no list gets every probe but axe. Viewport heights are never',
+        'defaulted: the heights a defect hides at are a property of the layout',
+        'rather than of this command.',
         '',
         '  {',
         '    "viewport": { "width": 1440, "heights": [900, 1200, 1500] },',
@@ -116,6 +121,11 @@ export function register(program: Command): void {
           (name) => `  ${name.padEnd(18)}${PROBE_NOTES[name]}`,
         ),
         '',
+        'An axe finding carries rule, outcome, and gate. outcome is violation or',
+        'incomplete, the second being axe declining to decide. gate is true for',
+        'a violation of one of these rules, which a UI review holds open on:',
+        ...wrapRules(AXE_GATE_RULES),
+        '',
         'Reasons:',
         '  no-run-file         nothing readable at the run path',
         '  unreadable-plan     the run file is not valid JSON',
@@ -128,6 +138,7 @@ export function register(program: Command): void {
         '  no-heights          the viewport names no height, which is never defaulted',
         '  engine-missing      the browser engine is not installed in this project',
         '  browser-missing     the engine is installed and its browser binary is not',
+        '  axe-missing         the run names axe and its engine did not resolve',
         '  server-unreachable  nothing answered at the URL, so no state was reached',
         '  drive-failed        the drive failed against a reachable page',
         '',
@@ -153,6 +164,21 @@ export function register(program: Command): void {
     })
 }
 
+/** Lays the gate list out at the help text's width. */
+function wrapRules(rules: readonly string[]): string[] {
+  const lines: string[] = []
+  let line = ' '
+  for (const rule of rules) {
+    if (line.length + rule.length + 1 > 74) {
+      lines.push(line)
+      line = ' '
+    }
+    line += ` ${rule}`
+  }
+  lines.push(line)
+  return lines
+}
+
 async function runDriver(
   url: string,
   runPath: string,

package/src/commands/migrate.ts

@@ -326,6 +326,11 @@ function reportRecords(plan: RecordsPlan, records: number): void {
   logInfo(
     `${plural(plan.entries.length, 'file')} to change, ${plural(plan.rewritten, 'citation')} to rewrite.`,
   )
+  if (plan.dropped > 0) {
+    logInfo(
+      `${plural(plan.dropped, 'ignore line')} dropped, already covered by .canon/.`,
+    )
+  }
   logInfo(`${plural(plan.kept, 'citation')} marked to keep the old root.`)
 
   // A count rather than a list, and its own line rather than a place in
@@ -401,6 +406,7 @@ function toRecordsRecord(
     collisions: plan.collisions,
     files: plan.entries.length,
     rewritten: plan.rewritten,
+    dropped: plan.dropped,
     kept: plan.kept,
     excluded: plan.excluded.length,
     coupled: plan.coupled,
@@ -414,6 +420,7 @@ function toRecordsRecord(
     paths: plan.entries.map((entry) => ({
       path: entry.path,
       rewritten: entry.rewritten,
+      dropped: entry.dropped,
     })),
   }
 }

package/src/commands/records.ts

@@ -223,7 +223,7 @@ export function register(program: Command): void {
   records
     .command('stale')
     .description(
-      'Report when the requirements record was last reviewed and how many releases have shipped since',
+      'Report when the requirements and design records were last reviewed and how many releases have shipped since',
     )
     .argument('<kind>', `Record folder: ${STALE_KINDS.join(', ')}`)
     .helpOption('-h, --help', 'Show this help message')
@@ -233,7 +233,8 @@ export function register(program: Command): void {
       'after',
       [
         '',
-        'canonical: reads REQUIREMENTS.md at whichever surface root carries it,',
+        'canonical: reads REQUIREMENTS.md and DESIGN.md at whichever surface root',
+        'carries each, skipping one the project lacks,',
         'in the current worktree since it is tracked. It reports its reviewed date',
         'and the release tags merged into HEAD after that day, or never when it',
         'carries no date.',

package/src/design/audit.ts

@@ -3,6 +3,12 @@ import { join, resolve } from 'node:path'
 import { measureDesignProse } from '@/design/budget'
 import { parseDesignDoc } from '@/design/parse'
 import { DESIGN_DOCUMENT } from '@/design/regen'
+import {
+  checkThemes,
+  readThemes,
+  scanDeclarations,
+  type ThemeResult,
+} from '@/design/themes'
 
 /** The custom property a table row names, such as `--color-accent`. */
 const PROPERTY = /--[A-Za-z0-9_-]+/g
@@ -19,6 +25,8 @@ export type TokenCheck =
       readonly stylesheet: string
       readonly properties: number
       readonly missing: readonly string[]
+      /** One entry per theme the record declares, absent where it declares none. */
+      readonly themes?: readonly ThemeResult[]
     }
   | { readonly status: 'unchecked'; readonly reason: string }
   | { readonly status: 'not-applicable'; readonly reason: string }
@@ -53,7 +61,11 @@ export function auditDesign(root: string): DesignAudit {
   const clean =
     prose.length === 0 &&
     tokens.status !== 'unchecked' &&
-    (tokens.status !== 'checked' || tokens.missing.length === 0)
+    (tokens.status !== 'checked' ||
+      (tokens.missing.length === 0 &&
+        (tokens.themes ?? []).every(
+          (theme) => theme.matched && theme.missing.length === 0,
+        )))
 
   return { ok: true, record: DESIGN_DOCUMENT, prose, tokens, clean }
 }
@@ -100,10 +112,22 @@ function checkTokens(root: string, path: string, source: string): TokenCheck {
     ),
   ]
 
+  const themes = readThemes(source)
+  const colors = [
+    ...new Set(
+      doc.color.flatMap((row) =>
+        [...(row['Property']?.value.matchAll(PROPERTY) ?? [])].map((m) => m[0]),
+      ),
+    ),
+  ]
+
   return {
     status: 'checked',
     stylesheet: named,
     properties: properties.length,
     missing: properties.filter((property) => !declared.has(property)),
+    ...(themes.length > 0 && {
+      themes: checkThemes(themes, scanDeclarations(css), colors),
+    }),
   }
 }

package/src/design/budget.ts

@@ -1,4 +1,5 @@
 import { canonicalHeading } from '@/design/parse'
+import { stripFrontmatter } from '@/markdown/frontmatter'
 
 /**
  * The prose budget `claude/skills/design-record/references/design.md` sets for a design record, and the
@@ -91,7 +92,7 @@ function splitSections(source: string): Section[] {
   const sections: { heading: string | undefined; lines: string[] }[] = [
     { heading: undefined, lines: [] },
   ]
-  for (const line of source.split('\n')) {
+  for (const line of stripFrontmatter(source).split('\n')) {
     const match = line.match(/^##\s+(.+?)\s*$/)
     if (match) {
       sections.push({ heading: match[1], lines: [] })

package/src/design/document.ts

@@ -5,7 +5,7 @@ import type {
   SpaceToken,
   TypeToken,
 } from '@/design/tokens'
-import { TOKENS } from '@/design/tokens'
+import { REVIEWED, TOKENS } from '@/design/tokens'
 
 /**
  * Renders `canon/DESIGN.md` from the token source.
@@ -110,6 +110,10 @@ function section(heading: string, ...blocks: string[]): string {
 
 export function renderDesignDocument(tokens: DesignTokens = TOKENS): string {
   const body = [
+    '---',
+    `reviewed: ${REVIEWED}`,
+    '---',
+    '',
     '# Design',
     '',
     LEAD,

package/src/design/themes.ts

@@ -0,0 +1,176 @@
+const RAW_FRONTMATTER = /^---\n([\s\S]*?)\n---/
+const THEMES_BLOCK = /^themes:[ \t]*\n((?:[ \t]+-[^\n]*\n?|[ \t]*\n)+)/m
+const LIST_ITEM = /^[ \t]*-[ \t]+(.*?)[ \t]*$/
+const FLOW_LIST = /^themes:[ \t]*\[(.*)\][ \t]*$/m
+const ENTRY = /\s*(?:'([^']*)'|"([^"]*)"|([^,#]*?))\s*(?:,|(?:#.*)?$)/y
+const DECLARATION = /^\s*(--[A-Za-z0-9_-]+)\s*:/
+
+/**
+ * One custom property declaration and the preludes enclosing it, outermost
+ * first. Each level holds the alternatives of its selector list, normalized so
+ * a record and a stylesheet compare equal.
+ */
+export interface ScannedDeclaration {
+  readonly property: string
+  readonly chain: readonly (readonly string[])[]
+}
+
+/**
+ * Reads the `themes:` list off the raw frontmatter block, for the reason
+ * `readReviewed` in `@/records/stale-canonical` gives. Each entry is the
+ * stylesheet prelude that opens the theme, such as `:root` or
+ * `@media (prefers-color-scheme: dark)`. A record declaring none reads as an
+ * empty list.
+ */
+export function readThemes(source: string): string[] {
+  const block = RAW_FRONTMATTER.exec(source.replaceAll('\r\n', '\n'))?.[1]
+  if (!block) return []
+
+  const flow = FLOW_LIST.exec(block)?.[1]
+  const list = THEMES_BLOCK.exec(`${block}\n`)?.[1]
+  const entries =
+    flow !== undefined
+      ? splitEntries(flow)
+      : (list ?? '')
+          .split('\n')
+          .map((line) => LIST_ITEM.exec(line)?.[1])
+          .filter((item): item is string => item !== undefined)
+          .flatMap((item) => splitEntries(item).slice(0, 1))
+
+  return entries.filter((entry) => entry !== '')
+}
+
+/**
+ * Splits a flow list or one block item into entries, honoring quotes and
+ * dropping a trailing ` #` comment, since a selector may carry a comma or a
+ * hash inside quotes.
+ */
+function splitEntries(text: string): string[] {
+  const out: string[] = []
+  ENTRY.lastIndex = 0
+  while (ENTRY.lastIndex < text.length) {
+    const match = ENTRY.exec(text)
+    if (match === null || match[0] === '') break
+    out.push((match[1] ?? match[2] ?? match[3] ?? '').trim())
+  }
+  return out
+}
+
+/**
+ * Collapses the differences a hand-written prelude carries: runs of
+ * whitespace, the quote style around an attribute value, and spacing inside
+ * an at-rule condition.
+ */
+export function normalizePrelude(prelude: string): string {
+  const flat = prelude.replace(/\s+/g, ' ').trim()
+  if (flat.startsWith('@')) return flat.replace(/\s*:\s*/g, ': ')
+  return flat
+    .replace(
+      /\[\s*([^\]=\s]+)\s*=\s*["']?([^"'\]]*?)["']?\s*\]/g,
+      (_, name: string, value: string) => `[${name}=${value}]`,
+    )
+    .replace(/\s*([>+~])\s*/g, ' $1 ')
+    .replace(/\s+/g, ' ')
+}
+
+/** Splits a selector list at its top-level commas, and leaves an at-rule whole. */
+function members(prelude: string): string[] {
+  if (prelude.trimStart().startsWith('@')) return [normalizePrelude(prelude)]
+
+  const out: string[] = []
+  let depth = 0
+  let start = 0
+  for (let index = 0; index < prelude.length; index += 1) {
+    const char = prelude[index]
+    if (char === '(' || char === '[') depth += 1
+    else if (char === ')' || char === ']') depth -= 1
+    else if (char === ',' && depth === 0) {
+      out.push(prelude.slice(start, index))
+      start = index + 1
+    }
+  }
+  out.push(prelude.slice(start))
+  return out.map(normalizePrelude).filter((member) => member !== '')
+}
+
+/**
+ * Walks a stylesheet and returns every custom property declaration with the
+ * block chain around it.
+ */
+export function scanDeclarations(css: string): ScannedDeclaration[] {
+  const source = css.replace(/\/\*[\s\S]*?\*\//g, '')
+  const found: ScannedDeclaration[] = []
+  const stack: (readonly string[])[] = []
+  let buffer = ''
+
+  const flush = (): void => {
+    const property = DECLARATION.exec(buffer)?.[1]
+    if (property !== undefined) found.push({ property, chain: [...stack] })
+    buffer = ''
+  }
+
+  for (const char of source) {
+    if (char === '{') {
+      stack.push(members(buffer))
+      buffer = ''
+    } else if (char === '}') {
+      flush()
+      stack.pop()
+    } else if (char === ';') {
+      flush()
+    } else {
+      buffer += char
+    }
+  }
+  flush()
+
+  return found
+}
+
+export interface ThemeResult {
+  readonly selector: string
+  /** False when no block in the stylesheet opens this theme. */
+  readonly matched: boolean
+  /** Properties the record names that the theme's blocks do not declare. */
+  readonly missing: readonly string[]
+}
+
+/**
+ * Checks each declared theme for the properties given. A declaration counts
+ * for the outermost enclosing prelude that is a declared theme, so a `:root`
+ * inside a declared media query belongs to the query and never to the light
+ * `:root` as well, and `:root` never matches `:root[data-theme='dark']` by
+ * containment.
+ */
+export function checkThemes(
+  themes: readonly string[],
+  declarations: readonly ScannedDeclaration[],
+  properties: readonly string[],
+): ThemeResult[] {
+  const declared = new Set(themes.map(normalizePrelude))
+  const owned = new Map<string, Set<string>>()
+
+  for (const { property, chain } of declarations) {
+    const level = chain.find((alternatives) =>
+      alternatives.some((prelude) => declared.has(prelude)),
+    )
+    for (const prelude of level ?? []) {
+      if (!declared.has(prelude)) continue
+      const set = owned.get(prelude) ?? new Set<string>()
+      set.add(property)
+      owned.set(prelude, set)
+    }
+  }
+
+  return themes.map((selector) => {
+    const theme = owned.get(normalizePrelude(selector))
+    return {
+      selector,
+      matched: theme !== undefined,
+      missing:
+        theme === undefined
+          ? []
+          : properties.filter((property) => !theme.has(property)),
+    }
+  })
+}

package/src/design/tokens.ts

@@ -95,6 +95,9 @@ const SANS = 'Geist Variable, DejaVu Sans, sans-serif'
 const DARK_GROUNDS = ['background', 'surface'] as const
 const LIGHT_GROUNDS = ['light-background', 'light-surface'] as const
 
+/** The day the record was last read whole, rendered into its frontmatter so `canon design regen` and the review point agree. */
+export const REVIEWED = '2026-10-24'
+
 export const TOKENS: DesignTokens = {
   personality:
     'Warm neutrals under one rust accent, set in Geist. The page reads as prose, and monospace appears only where a surface shows what a shell printed. One accent carries every count, link, and primary action.',

package/src/driver/drive.ts

@@ -1,6 +1,7 @@
 import { chromium } from 'playwright-core'
 import type { Browser, Page } from 'playwright-core'
 import { isBrowserMissing, isServerUnreachable } from '@/browser/engine'
+import { AxeEngineMissing, probeAxe } from '@/driver/probes/axe'
 import { probeDetails } from '@/driver/probes/details'
 import {
   probeDiagramGeometry,
@@ -43,6 +44,19 @@ const PROBES: Record<ProbeName, (page: Page) => Promise<Finding[]>> = {
   details: probeDetails,
   'diagram-geometry': probeDiagramGeometry,
   'diagram-strokes': probeDiagramStrokes,
+  axe: probeAxe,
+}
+
+/**
+ * Runs `axe` after every other probe a step names, whatever order the run
+ * wrote, so every probe sharing its step reads the page before the engine's
+ * script has ever loaded into it.
+ */
+function inRunOrder(names: readonly ProbeName[]): ProbeName[] {
+  return [
+    ...names.filter((name) => name !== 'axe'),
+    ...names.filter((name) => name === 'axe'),
+  ]
 }
 
 export interface DriveOptions {
@@ -60,6 +74,7 @@ export interface PassReading {
 
 export type DriverRefusal =
   | 'browser-missing'
+  | 'axe-missing'
   | 'server-unreachable'
   | 'drive-failed'
 
@@ -107,6 +122,7 @@ export async function drive(options: DriveOptions): Promise<DriverResult> {
       passes.push(...pass.passes)
     }
   } catch (error) {
+    if (error instanceof AxeEngineMissing) return failed('axe-missing', error)
     return failed(
       isServerUnreachable(error) ? 'server-unreachable' : 'drive-failed',
       error,
@@ -159,7 +175,7 @@ async function driveViewport(
 
       const names = stepProbes(options.plan, step)
       let count = 0
-      for (const name of names) {
+      for (const name of inRunOrder(names)) {
         const probe = PROBES[name]
         for (const finding of await probe(page)) {
           findings.push({ ...finding, step: step.name, viewport: where })

package/src/driver/probes/axe.ts

@@ -0,0 +1,195 @@
+import { readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import type { Page } from 'playwright-core'
+import type { Finding } from '@/driver/steps'
+
+/**
+ * Runs axe-core on the WCAG A and AA tags and reports what it found, marking
+ * the findings a UI review holds open on.
+ *
+ * The engine is canon's own dependency and is read from canon's install at run
+ * time, so nothing reaches a target's manifest or production build.
+ *
+ * The bundle assigns `window.axe`, `doT`, and `_encodeHTML` as it loads, and
+ * registers with any AMD loader the page carries. It is evaluated with
+ * `define`, `module`, and `exports` shadowed, and every global it added or
+ * replaced as it loaded is put back once the run settles, so a page owning a
+ * global named `axe` keeps it, a global the page sets during the run survives,
+ * and a probe running after this one reads the page it found.
+ */
+
+/** The tags the groundwork measured on, which together are WCAG 2.2 A and AA. */
+const TAGS = ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'wcag22aa']
+
+/**
+ * The rules a violation of which keeps a UI review open. Each raised no false
+ * finding across frameboard's real screens, and a rule moves to report-only on
+ * its first false finding on a real pull request.
+ *
+ * `label-content-name-mismatch` stays off it as a text heuristic, and every
+ * incomplete result stays off it as axe saying it could not decide.
+ */
+export const AXE_GATE_RULES: readonly string[] = [
+  'color-contrast',
+  'target-size',
+  'button-name',
+  'link-name',
+  'input-button-name',
+  'select-name',
+  'label',
+  'image-alt',
+  'document-title',
+  'html-has-lang',
+  'html-lang-valid',
+  'aria-valid-attr',
+  'aria-required-attr',
+  'aria-roles',
+  'nested-interactive',
+]
+
+const ENGINE = 'axe-core/axe.min.js'
+
+/**
+ * The engine was not where canon's install should hold it. Thrown rather than
+ * returned as an empty list, since no findings and no engine read the same to
+ * a caller counting findings.
+ */
+export class AxeEngineMissing extends Error {
+  override readonly name = 'AxeEngineMissing'
+}
+
+/** Reads the engine bundle out of canon's own install. */
+export function readAxeEngine(specifier: string = ENGINE): string {
+  try {
+    const path = createRequire(import.meta.url).resolve(specifier)
+    return readFileSync(path, 'utf8')
+  } catch (error) {
+    throw new AxeEngineMissing(
+      `axe-core did not resolve from canon's install as ${specifier}. ${error instanceof Error ? error.message : String(error)}`,
+      { cause: error },
+    )
+  }
+}
+
+let cached: string | undefined
+
+/** Read once per process, since a drive calls the probe after every step. */
+function cachedEngine(): string {
+  cached ??= readAxeEngine()
+  return cached
+}
+
+interface Row {
+  readonly rule: string
+  readonly outcome: 'violation' | 'incomplete'
+  readonly help: string
+  readonly criteria: string
+  readonly selector: string
+  readonly summary: string
+}
+
+const OUTCOME_ORDER = { violation: 0, incomplete: 1 } as const
+
+export async function probeAxe(
+  page: Page,
+  engine: () => string = cachedEngine,
+): Promise<Finding[]> {
+  const source = engine()
+  const rows = (await page.evaluate(runner(source))) as Row[]
+  const gating = new Set(AXE_GATE_RULES)
+
+  return [...rows]
+    .sort(
+      (a, b) =>
+        OUTCOME_ORDER[a.outcome] - OUTCOME_ORDER[b.outcome] ||
+        a.rule.localeCompare(b.rule) ||
+        a.selector.localeCompare(b.selector),
+    )
+    .map((row) => ({
+      probe: 'axe' as const,
+      selector: row.selector,
+      detail:
+        row.outcome === 'violation'
+          ? row.help
+          : `${row.help}, which axe could not decide and a person reads`,
+      measured: [row.criteria, row.summary].filter(Boolean).join(': '),
+      rule: row.rule,
+      outcome: row.outcome,
+      gate: row.outcome === 'violation' && gating.has(row.rule),
+    }))
+}
+
+/**
+ * Builds the expression the page evaluates. A string rather than a function,
+ * so the bundle is evaluated by the debugging protocol, which a page's content
+ * security policy does not govern, where a `new Function` inside the page would
+ * be refused by any policy without `unsafe-eval`.
+ */
+function runner(source: string): string {
+  const options = JSON.stringify({
+    runOnly: { type: 'tag', values: TAGS },
+    resultTypes: ['violations', 'incomplete'],
+    iframes: false,
+  })
+
+  return `(async () => {
+    const scope = window
+    const before = new Map()
+    for (const key of Object.getOwnPropertyNames(scope)) {
+      before.set(key, Object.getOwnPropertyDescriptor(scope, key))
+    }
+    const prior = before.get('axe')
+
+    // The keys the bundle's load added or replaced, read once it has loaded and
+    // before the run awaits, so a global the page sets mid-run stays the page's.
+    const loaded = () =>
+      Object.getOwnPropertyNames(scope).filter((key) => {
+        const was = before.get(key)
+        if (!was) return true
+        const now = Object.getOwnPropertyDescriptor(scope, key)
+        return Boolean(now && 'value' in was && now.value !== was.value)
+      })
+    let touched
+
+    try {
+      ;(function (define, module, exports) {
+${source}
+      }).call(scope)
+      touched = loaded()
+
+      const engine = scope.axe
+      if (!engine || engine === prior?.value || typeof engine.run !== 'function') {
+        throw new Error('the page holds window.axe in a property the engine could not replace')
+      }
+
+      const result = await engine.run(document, ${options})
+      const rows = []
+      const read = (outcome, rules) => {
+        for (const rule of rules) {
+          const criteria = rule.tags.filter((tag) => /^wcag\\d{3,}$/.test(tag)).join(' ')
+          for (const node of rule.nodes) {
+            rows.push({
+              rule: rule.id,
+              outcome,
+              help: rule.help,
+              criteria,
+              selector: node.target.map((part) => [].concat(part).join(' >>> ')).join(' '),
+              summary: (node.failureSummary || '').replace(/\\s+/g, ' ').trim(),
+            })
+          }
+        }
+      }
+      read('violation', result.violations)
+      read('incomplete', result.incomplete)
+      return rows
+    } finally {
+      // A load that threw partway set nothing the page could have raced, so
+      // the keys that differ now are all the bundle's.
+      for (const key of touched ?? loaded()) {
+        const was = before.get(key)
+        if (was) Object.defineProperty(scope, key, was)
+        else delete scope[key]
+      }
+    }
+  })()`
+}

package/src/driver/steps.ts

@@ -28,10 +28,20 @@ export const PROBE_NAMES = [
   'details',
   'diagram-geometry',
   'diagram-strokes',
+  'axe',
 ] as const
 
 export type ProbeName = (typeof PROBE_NAMES)[number]
 
+/**
+ * What a run that names no list measures. `axe` is left out because it loads a
+ * third-party script into the page under test, which a run opts into by name
+ * rather than inheriting.
+ */
+export const DEFAULT_PROBES: readonly ProbeName[] = PROBE_NAMES.filter(
+  (name) => name !== 'axe',
+)
+
 /**
  * One thing a probe measured and judged wrong. The step and the viewport are
  * filled in by the orchestrator rather than by the probe, since a probe runs
@@ -44,6 +54,15 @@ export interface Finding {
   readonly selector: string
   readonly detail: string
   readonly measured: string
+  /** The engine rule that raised it, set by a probe that delegates to one. */
+  readonly rule?: string
+  /** Whether the engine judged the element or declined to decide. */
+  readonly outcome?: 'violation' | 'incomplete'
+  /**
+   * True when the finding is one a review holds open on. The probe sets it and
+   * still never gates, since a gate belongs to the reader, not to this command.
+   */
+  readonly gate?: boolean
 }
 
 /** A finding once the run has said where it happened. */
@@ -169,7 +188,7 @@ export function readDriverPlan(source: string): PlanRead {
 
 /** Returns the parsed list, or the message naming what failed. */
 function readProbeList(value: unknown): ProbeName[] | string {
-  if (value === undefined) return [...PROBE_NAMES]
+  if (value === undefined) return [...DEFAULT_PROBES]
   if (!Array.isArray(value)) return 'probes is not a list'
 
   const names: ProbeName[] = []

package/src/gate/measures.ts

@@ -590,10 +590,16 @@ export const recordIdempotence: Measure = async (ctx) => {
   }
 
   const record = parseJson(run.stdout) as
-    | { moves?: unknown; rewritten?: unknown; paths?: unknown }
+    | {
+        moves?: unknown
+        rewritten?: unknown
+        dropped?: unknown
+        paths?: unknown
+      }
     | undefined
   const moves = record?.moves
   const rewritten = record?.rewritten
+  const dropped = typeof record?.dropped === 'number' ? record.dropped : 0
 
   if (!Array.isArray(moves) || typeof rewritten !== 'number') {
     return {
@@ -613,14 +619,14 @@ export const recordIdempotence: Measure = async (ctx) => {
     }
   }
 
-  if (rewritten > 0) {
+  if (rewritten + dropped > 0) {
     return {
       // The payload already names every file, so listing them here is what
       // separates a count a reader has to go and reproduce from a remedy they
       // can act on. A malformed `paths` costs the list and not the finding,
       // since the count above it was read from a field of its own.
       emissions: citedPaths(record).map((path) => warn(path)),
-      failure: `The records are at .canon/ and ${rewritten} citation(s) still name the old root, so a second run of canon migrate records would rewrite them. Repoint each one, or mark it canon-keep-record-root where the sentence has to keep the old spelling.`,
+      failure: `The records are at .canon/ and ${rewritten + dropped} citation(s) still name the old root, so a second run of canon migrate records would rewrite or drop them. Repoint each one, or mark it canon-keep-record-root where the sentence has to keep the old spelling.`,
     }
   }
 

package/src/markdown/structure.ts

@@ -422,6 +422,9 @@ export function longestRun(
  * continuing a bullet do fold in, so a heavy bullet cannot fall under the
  * checkpoint by being wrapped across two source lines. A fenced line closes the
  * open bullet, which keeps a bullet from absorbing the example below it.
+ *
+ * A bullet is measured without its list marker, the way the `bullet-length`
+ * gate measures it, so the count and the gate agree at the checkpoint.
  */
 export function heavyBullets(
   lines: readonly BodyLine[],
@@ -470,7 +473,7 @@ function foldBullets(
       close()
       open = {
         line: line.number,
-        characters: visibleText(text).length,
+        characters: visibleText(text.replace(LIST_ITEM, '')).length,
         text,
         indent: item[1].length,
       }

package/src/migrate/records.ts

@@ -56,14 +56,21 @@ export function destinationPath(entry: string): string {
  * shorter entry can claim its prefix, and each entry is escaped because two of
  * them carry a dot.
  */
+const ENTRY_ALTERNATION = [...MOVED_ENTRIES]
+  .sort((left, right) => right.length - left.length)
+  .map(escape)
+  .join('|')
+
 const CITATION = new RegExp(
-  `${escape(FROM_ROOT)}/(${[...MOVED_ENTRIES]
-    .sort((left, right) => right.length - left.length)
-    .map(escape)
-    .join('|')})(?![A-Za-z0-9._-])`,
+  `${escape(FROM_ROOT)}/(${ENTRY_ALTERNATION})(?![A-Za-z0-9._-])`,
   'g',
 )
 
+/** A gitignore line that is wholly an entry for one moved folder or file. */
+const IGNORE_ENTRY = new RegExp(
+  `^/?${escape(FROM_ROOT)}/(?:${ENTRY_ALTERNATION})/?$`,
+)
+
 function escape(value: string): string {
   return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
 }
@@ -386,6 +393,30 @@ export function scanText(text: string): {
   return { rewritten, kept, globs, crossRepo, dated }
 }
 
+/**
+ * Deletes each live line that is wholly an entry for a moved folder, counting
+ * them. Only a root `.gitignore` that already ignores `.canon/` may be handed
+ * here, since the dropped line is redundant only under that entry. Splitting on
+ * `\n` and matching the trimmed line leaves CRLF endings and a missing final
+ * newline on the lines that stay.
+ */
+export function dropCoveredIgnoreLines(text: string): {
+  readonly text: string
+  readonly dropped: number
+} {
+  const lines = text.split('\n')
+  const frontmatterEndIndex = frontmatterEnd(lines)
+  const kept = lines.filter(
+    (line, index) =>
+      !(
+        IGNORE_ENTRY.test(line.trim()) &&
+        classifyLine(lines, index, frontmatterEndIndex) === 'live'
+      ),
+  )
+
+  return { text: kept.join('\n'), dropped: lines.length - kept.length }
+}
+
 /** Where a citation sits, so a reader can judge it before `--write` runs. */
 export interface CitationLine {
   readonly line: number
@@ -503,6 +534,7 @@ export interface CitationEntry {
   readonly text: string
   readonly rewritten: number
   readonly kept: number
+  readonly dropped: number
 }
 
 /** One file whose frontmatter `paths:` glob names a moved root, held rather than rewritten. */
@@ -533,6 +565,7 @@ export interface RecordsPlan {
   readonly crossRepoCitations: readonly CrossRepoCitationEntry[]
   readonly datedCitations: readonly DatedCitationEntry[]
   readonly rewritten: number
+  readonly dropped: number
   readonly kept: number
   readonly globs: number
   readonly crossRepo: number
@@ -578,7 +611,11 @@ export function planRecordsMove(
       continue
     }
 
-    const counts = scanText(source.text)
+    const swept =
+      source.path === '.gitignore' && ignoresDestination(source.text)
+        ? dropCoveredIgnoreLines(source.text)
+        : { text: source.text, dropped: 0 }
+    const counts = scanText(swept.text)
     kept += counts.kept
     globs += counts.globs
     crossRepo += counts.crossRepo
@@ -599,15 +636,16 @@ export function planRecordsMove(
     if (dates.length > 0)
       datedCitations.push({ path: source.path, lines: dates })
 
-    if (counts.rewritten === 0) continue
+    if (counts.rewritten === 0 && swept.dropped === 0) continue
 
     if (referencesExcluded(source.text)) coupled.push(source.path)
 
     entries.push({
       path: source.path,
-      text: rewriteText(source.text),
+      text: rewriteText(swept.text),
       rewritten: counts.rewritten,
       kept: counts.kept,
+      dropped: swept.dropped,
     })
   }
 
@@ -621,6 +659,7 @@ export function planRecordsMove(
     crossRepoCitations,
     datedCitations,
     rewritten: entries.reduce((sum, entry) => sum + entry.rewritten, 0),
+    dropped: entries.reduce((sum, entry) => sum + entry.dropped, 0),
     kept,
     globs,
     crossRepo,

package/src/records/stale-canonical.ts

@@ -5,8 +5,8 @@ import { relative } from 'node:path'
 import { gitEnv } from '@/git/env'
 import { surfaceDir } from '@/roots/surface'
 
-/** The record whose drift is identity rather than a stale path. */
-const CANONICAL_DOCS = ['REQUIREMENTS.md'] as const
+/** The records carrying a `reviewed:` review point, whose drift is how far the project moved since they were read whole. */
+const CANONICAL_DOCS = ['REQUIREMENTS.md', 'DESIGN.md'] as const
 
 export interface CanonicalDoc {
   /** Relative to the root, at whichever surface root carries the doc. */