@erclx/canon 5.59.0 → 5.61.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # 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)
+
+
+### Features
+
+* **design:** add canon design audit verb ([#2661](https://github.com/erclx/canon/issues/2661)) ([303a52a](https://github.com/erclx/canon/commit/303a52ada294d9740205885336b6f1ce006ddbba))
+* **skills:** reach design-taste in planner and later review passes ([#2657](https://github.com/erclx/canon/issues/2657)) ([dedc351](https://github.com/erclx/canon/commit/dedc35132a57cf8f82e9a25603e6128e0c77d6ed))
+* **tooling:** bound the dev dependency install ([#2666](https://github.com/erclx/canon/issues/2666)) ([09017a6](https://github.com/erclx/canon/commit/09017a6bfcf11d3feffa1eccfa1ec99f8a0ff3ae))
+
+
+### Bug Fixes
+
+* **sync:** drop retired domains when reading the stamp ([#2664](https://github.com/erclx/canon/issues/2664)) ([21e0a1c](https://github.com/erclx/canon/commit/21e0a1cccfcab13dba5e50e3a55ea620d0d77907))
+
 ## [5.59.0](https://github.com/erclx/canon/compare/v5.58.0...v5.59.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.59.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, read the requirements record for identity drift when the scope reaches it, and print the `canon records stale canonical` reminder
+- 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

@@ -60,21 +60,31 @@ A refusal, an absent key, and a subcommand the project's binary does not carry e
 - `canon context audit` refuses with `reason: "no-folders"` where the layout is not the expected one. Reading that honest refusal as an empty finding set reports a healthy corpus nothing looked at.
 - A narrower read is not an unread one. The sweep running on its regex layer alone still answered, so report it with the layer named.
 
+### The design record
+
+`canon/DESIGN.md` reads outside both verbs above, since neither measures its prose budget or its tokens. When the scope reaches it, read it through its own verb:
+
+```bash
+canon design audit --json
+```
+
+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
 
 No verb answers whether a document still describes the tree it was written about. Read each document against the surfaces it names and report where the two have parted, taking the file paths, commands, and counts it states as the claims to test.
 
 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.
 
@@ -108,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.
@@ -121,3 +132,12 @@ Structure `canon/context/surfaces/`: `cli.md` (300 lines) splits into `cli.md` t
 The line is a proposal for the operator, with the headings each entry takes and why. Health applies nothing, and `document-repair` offers the proposal before it rewrites.
 
 Keep the evidence line under the table on every run. A table read without it flattens a judgment into a measurement, which is the one shape the three classes exist to prevent.
+
+### The design record row
+
+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, 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

@@ -73,6 +73,26 @@ Both verbs resolve their folders by surface root rather than by a path written i
 - The audit refuses with `reason: "no-folders"`, naming the folders it looked for. Report that refusal as an unread axis.
 - The sweep with the model layer off answers from its regex layer alone, a narrower read rather than a refusal, so say which layer answered
 
+## The design record
+
+| Field          | Value                                                                                            |
+| -------------- | ------------------------------------------------------------------------------------------------ |
+| Measures       | Whether the design record holds to its prose budget and names only properties its stylesheet has |
+| Verb           | `canon design audit --json`                                                                      |
+| Evidence class | `measured`                                                                                       |
+
+The record is exempt from the length and placement verbs above, so this is the only measured read it gets.
+
+- `prose`: each place the record passes the budget, with the count and the cap it was read against. Take the caps from the finding rather than from a number written here.
+- `tokens.missing`: a custom property a table names that the stylesheet the lead names does not declare
+- `tokens.status: "unchecked"`: the lead names no stylesheet, or the one it names does not resolve. Report the axis as unread with the `reason`, since nothing was compared.
+- `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
 
 | Field          | Value                                                            |
@@ -102,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/plan-feature/SKILL.md

@@ -38,7 +38,7 @@ Read these in parallel from the project root, skipping any that do not exist:
 
 Also read `canon/DESIGN.md` when the feature touches code or UI, for visual intent and component rules, with values read from the stylesheet its lead names. Skip it for prose, docs, catalog, or config-only changes. For a UI feature, read `canon/design/index.md` too, if it exists, for the surfaces with an accepted design.
 
-Coding standards live in `.claude/rules/`. Claude Code loads them automatically, and path-scoped rules apply to the files they match.
+Coding standards live in `.claude/rules/`. Claude Code loads them automatically, and path-scoped rules apply to the files they match. For a UI feature, load `canon:design-taste` whether or not `canon/DESIGN.md` exists.
 
 ### Read the domain's context entry
 

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

@@ -78,7 +78,7 @@ Read these in parallel from the project root, skipping any that do not exist:
 - `.canon/tasks/priority.md`: where this feature sits on the board and what each neighbor waits on, resolved at the main root the way `session-worktree` does, since a linked worktree holds no copy
 - `.canon/plans/feature-<slug>.md` for the branch, when present: the intent the PR should satisfy, and its `**Review focus:**` section as the inputs this pass must confirm the diff handles
 
-Coding standards from `.claude/rules/` are auto-loaded by Claude Code.
+Coding standards from `.claude/rules/` are auto-loaded by Claude Code for the files a first pass reads. A path-scoped rule loads only when a session reads a matching file, so a later pass opens each changed file through the Read tool per `references/scope.md`, which loads the rules its trunk path matches and names the gap for an added file.
 
 ## Step 2: scope the read
 

package/claude/skills/review-pr/references/scope.md

@@ -117,3 +117,13 @@ Carry `<prior-heading>` into Step 4 and run Step 3 unchanged. This guard turns o
 ## The read
 
 Read each changed file in scope. Skip deleted files. Run reads in parallel.
+
+### Load the path-scoped rules on a later pass
+
+A path-scoped rule loads when a session uses the Read tool on a matching file, and a Bash call such as `git show` loads none. A later pass reads only `<prior-oid>..<headRefOid>`, so the head copy of each changed file has to reach the Read tool.
+
+- Open the trunk path with the Read tool when it exists, as the trigger, and take the content from `git show <headRefOid>:<path>`, since trunk content is stale
+- For an added file, write its head blob to `.canon/tmp/pr/review/head-read/<number>-<short-sha>/<path>`, in the review body folder, then open that copy with the Read tool
+- The copy loads only `**/` globs, since a root-anchored glob such as `canon/design/**` misses its prefix, so an added file under one loads no rule
+- Read only files the range changed, never the whole tree, so the cost stays bounded by the range
+- A range whose only change is a deletion has no file to read, so skip it and carry on

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.59.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/design.ts

@@ -1,7 +1,9 @@
 import { existsSync } from 'node:fs'
 import { join, relative } from 'node:path'
 import type { Command } from 'commander'
+import { auditDesign } from '@/design/audit'
 import { buildDesignCss } from '@/design/css'
+import { currentWorktreeRoot } from '@/git/worktree'
 import { HAND_DRAWN_FONT_FACES } from '@/design/fonts'
 import { DESIGN_DOCUMENT, regenDesign } from '@/design/regen'
 import { checkoutMismatchWarning, PROJECT_ROOT } from '@/roots/project'
@@ -11,7 +13,7 @@ export function register(program: Command): void {
   const design = program
     .command('design')
     .helpOption('-h, --help', 'Show this help message')
-    .description('Design system commands (regen, css)')
+    .description('Design system commands (regen, css, audit)')
 
   design
     .command('regen')
@@ -77,4 +79,58 @@ export function register(program: Command): void {
         }),
       )
     })
+
+  design
+    .command('audit')
+    .helpOption('-h, --help', 'Show this help message')
+    .description(
+      'Measure the design record against the prose budget and check its custom properties against the stylesheet',
+    )
+    .option('--json', 'Add a machine-readable record on stdout')
+    .option('--root <path>', 'Project root, defaulting to the current worktree')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Reads canon/DESIGN.md. Prose findings carry their counts against the',
+        'budget the design standard sets. Each custom property in the Colors and',
+        'Shapes tables is checked against the stylesheet the lead names. A lead',
+        'naming none reads as `tokens.status: "unchecked"`, never as a pass.',
+        '',
+        'Exit codes:',
+        '  0  the reading completed, whatever it found',
+        '',
+        'It gates nothing and writes nothing.',
+        '',
+        'Examples:',
+        '  canon design audit',
+        '  canon design audit --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: { json?: boolean; root?: string }) => {
+      const root = opts.root ?? (await currentWorktreeRoot())
+      const audit = auditDesign(root)
+
+      if (opts.json ?? false) {
+        process.stdout.write(`${JSON.stringify(audit)}\n`)
+        return
+      }
+
+      intro('canon design audit')
+      if (audit.record === null) {
+        logInfo('No design record to audit')
+      } else {
+        for (const finding of audit.prose) logWarn(finding)
+        if (audit.tokens?.status === 'unchecked') {
+          logWarn(`Tokens unchecked: ${audit.tokens.reason}`)
+        } else if (audit.tokens?.status === 'checked') {
+          for (const property of audit.tokens.missing) {
+            logWarn(`${property} is not declared in ${audit.tokens.stylesheet}`)
+          }
+        }
+        if (audit.clean) logInfo(`${audit.record} is within budget`)
+      }
+      outro()
+    })
 }

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/commands/tooling.ts

@@ -107,6 +107,9 @@ export function register(program: Command): void {
         'A target below its git root syncs as a subfolder. It withholds',
         '.github/, which GitHub reads only at the root.',
         '',
+        'The dependency install is bounded at 120 seconds. A stalled or failed',
+        'install refuses with exit 1, and the stamp stays unwritten.',
+        '',
         'To gate CI on tooling drift, run headlessly with neither flag. That',
         'exits 1 when a file would be replaced and 0 when none would, which is',
         'what `canon sync --check --exit-code` spells with a flag. Pass --check',
@@ -444,7 +447,14 @@ async function runSync(
   }
 
   await injectSeeds(prepared.chain, prepared.target)
-  await injectManifest(prepared.chain, prepared.target)
+  const manifest = await injectManifest(prepared.chain, prepared.target)
+  if (!manifest.ok) {
+    return refuse(
+      opts,
+      manifest.reason,
+      `${manifest.message}\nConfigs and seeds above were written. Scripts, gitignore entries, and the stamp were not, so the next sync retries.`,
+    )
+  }
 
   await stampChain(prepared.chain, prepared.target)
 
@@ -553,7 +563,12 @@ async function runInject(
     await injectSeeds(prepared.chain, prepared.target)
   }
   if (opts.manifest || applyAll) {
-    await injectManifest(prepared.chain, prepared.target)
+    const manifest = await injectManifest(prepared.chain, prepared.target)
+    if (!manifest.ok) {
+      logWarn(manifest.message)
+      if (framed) outro()
+      return 1
+    }
   } else if (opts.gitignore) {
     await injectGitignore(prepared.chain, prepared.target)
   }