@erclx/canon 5.59.0 → 5.60.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [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.60.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

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`, routing its findings to `design-record`
 
 ## Must not
 

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

@@ -60,6 +60,16 @@ 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 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`.
+
 ## 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.
@@ -121,3 +131,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
+- 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,24 @@ 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
+
+**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                                                            |

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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "5.59.0",
+  "version": "5.60.0",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
   "license": "MIT",
   "bin": {

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/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)
   }

package/src/design/audit.ts

@@ -0,0 +1,109 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { measureDesignProse } from '@/design/budget'
+import { parseDesignDoc } from '@/design/parse'
+import { DESIGN_DOCUMENT } from '@/design/regen'
+
+/** The custom property a table row names, such as `--color-accent`. */
+const PROPERTY = /--[A-Za-z0-9_-]+/g
+
+/** A custom property declaration, which a stylesheet and a Tailwind `@theme` block share. */
+const DECLARATION = /(--[A-Za-z0-9_-]+)\s*:/g
+
+/** A backticked path to a stylesheet. */
+const STYLESHEET = /`([^`\s]+\.css)`/
+
+export type TokenCheck =
+  | {
+      readonly status: 'checked'
+      readonly stylesheet: string
+      readonly properties: number
+      readonly missing: readonly string[]
+    }
+  | { readonly status: 'unchecked'; readonly reason: string }
+  | { readonly status: 'not-applicable'; readonly reason: string }
+
+export interface DesignAudit {
+  readonly ok: true
+  /** The record read, or null where the project holds none. */
+  readonly record: string | null
+  readonly prose: readonly string[]
+  readonly tokens: TokenCheck | null
+  /** True only when the prose is within budget and the token check ran clean. */
+  readonly clean: boolean
+}
+
+/**
+ * Reads a project's design record against the prose budget and checks each
+ * custom property its tables name against the stylesheet its lead names. It
+ * writes nothing.
+ *
+ * A token check that cannot run says why under `unchecked` and leaves `clean`
+ * false, since a check that did not look is no pass.
+ */
+export function auditDesign(root: string): DesignAudit {
+  const path = join(root, DESIGN_DOCUMENT)
+  if (!existsSync(path)) {
+    return { ok: true, record: null, prose: [], tokens: null, clean: true }
+  }
+
+  const source = readFileSync(path, 'utf8')
+  const prose = measureDesignProse(source)
+  const tokens = checkTokens(root, path, source)
+  const clean =
+    prose.length === 0 &&
+    tokens.status !== 'unchecked' &&
+    (tokens.status !== 'checked' || tokens.missing.length === 0)
+
+  return { ok: true, record: DESIGN_DOCUMENT, prose, tokens, clean }
+}
+
+function checkTokens(root: string, path: string, source: string): TokenCheck {
+  const doc = parseDesignDoc(path)
+  const rows = [...doc.color, ...doc.borders]
+
+  // A values record renders from a token module and carries `Value` where an
+  // intent record carries `Property`, so it has no property to compare.
+  if (!rows.some((row) => 'Property' in row)) {
+    return {
+      status: 'not-applicable',
+      reason:
+        'The record has no Property column, so it holds no property to compare.',
+    }
+  }
+
+  const lead = source.split(/^##\s/m)[0]
+  const named = lead.match(STYLESHEET)?.[1]
+  if (named === undefined) {
+    return {
+      status: 'unchecked',
+      reason: 'The lead names no stylesheet, so no property could be checked.',
+    }
+  }
+
+  const stylesheet = resolve(root, named)
+  if (!stylesheet.startsWith(resolve(root)) || !existsSync(stylesheet)) {
+    return {
+      status: 'unchecked',
+      reason: `The lead names ${named}, which does not resolve in the project.`,
+    }
+  }
+
+  const css = readFileSync(stylesheet, 'utf8').replace(/\/\*[\s\S]*?\*\//g, '')
+  const declared = new Set([...css.matchAll(DECLARATION)].map((m) => m[1]))
+
+  const properties = [
+    ...new Set(
+      rows.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)),
+  }
+}

package/src/design/css.ts

@@ -154,8 +154,6 @@ export function fontFaceBlock(
 }
 
 export interface CssOptions {
-  /** Prepended as a comment, naming what wrote the file and from where. */
-  readonly banner?: string
   /**
    * Component rules ride along by default; a token-only consumer opts out
    * with `false`. Pass an explicit list to emit those instead of the generic default.
@@ -173,8 +171,6 @@ export function buildDesignCss(
   tokens: DesignTokens = TOKENS,
   options: CssOptions = {},
 ): string {
-  const banner =
-    options.banner === undefined ? '' : `/* ${options.banner} */\n\n`
   const root = [':root {', ...tokenProperties(tokens), '}'].join('\n')
   const faces =
     options.embedFonts === true
@@ -193,5 +189,5 @@ export function buildDesignCss(
         : COMPONENTS
   if (components) parts.push(componentBlock(components))
 
-  return `${banner}${parts.join('\n\n')}\n`
+  return `${parts.join('\n\n')}\n`
 }

package/src/sync/stamp.ts

@@ -16,9 +16,10 @@ import { readInstalled } from '@/version/installed'
  *
  * A stamp written before the standards or snippets install channel closed
  * still carries a `standards` or `snippets` record, and one written before the
- * design install retired carries a `design` record. `isStamp` ignores the key
- * and `sortDomains` drops it on the next write, so the target loses a domain
- * nothing can refresh rather than losing the whole file.
+ * design install retired carries a `design` record. `isStamp` ignores the key,
+ * `readStamp` drops it from what it returns, and `sortDomains` drops it from
+ * the file on the next write, so the target loses a domain nothing can refresh
+ * rather than losing the whole file.
  */
 export const STAMP_DOMAINS = ['governance', 'tooling'] as const
 
@@ -183,12 +184,31 @@ function readStampFile(path: string): Stamp | undefined {
 
   try {
     const parsed: unknown = JSON.parse(readFileSync(path, 'utf8'))
-    return isStamp(parsed) ? parsed : undefined
+    return isStamp(parsed) ? withoutRetired(parsed) : undefined
   } catch {
     return undefined
   }
 }
 
+/**
+ * A stamp written before a domain retired still names it until the next write.
+ * Filtering here keeps a report on a target that has not synced since from
+ * listing a domain nothing can refresh. The file itself is left as it is.
+ */
+function withoutRetired(stamp: Stamp): Stamp {
+  const domains: Partial<Record<StampDomain, DomainStamp>> = {}
+  for (const domain of STAMP_DOMAINS) {
+    const record = stamp.domains[domain]
+    if (record !== undefined) domains[domain] = record
+  }
+
+  const covers = Array.isArray(stamp.covers)
+    ? stamp.covers.filter((domain) => STAMP_DOMAINS.includes(domain))
+    : []
+
+  return { covers, domains }
+}
+
 /** The newest canon release that has written this domain, when one was recorded. */
 export function stampedVersion(
   stamp: Stamp | undefined,

package/src/tooling/inject.ts

@@ -1,8 +1,8 @@
 import { existsSync } from 'node:fs'
 import { copyFile, mkdir, readFile, writeFile } from 'node:fs/promises'
 import { dirname, join, relative } from 'node:path'
-import { $ } from 'bun'
 import { copyPreservingMode } from '@/sync/copy'
+import { type InstallResult, installDevDependencies } from '@/tooling/install'
 import { rewritesOnInstall, stripSeedMarker } from '@/tooling/seed-marker'
 import { resolveSurfacePath } from '@/roots/surface'
 import { mergeSections, pruneSections } from '@/tooling/gitignore'
@@ -165,7 +165,7 @@ export async function pruneGitignore(
 export async function injectManifest(
   chain: readonly Manifest[],
   target: string,
-): Promise<void> {
+): Promise<InstallResult> {
   const packagePath = join(target, 'package.json')
 
   if (!existsSync(packagePath) && declaresInstalls(chain)) {
@@ -183,7 +183,8 @@ export async function injectManifest(
 
     if (missing.length > 0) {
       logStep('Installing missing dependencies')
-      await $`bun add -D ${missing}`.cwd(target)
+      const installed = await installDevDependencies(missing, target)
+      if (!installed.ok) return installed
       for (const spec of missing) logAdd(spec)
     }
 
@@ -202,6 +203,8 @@ export async function injectManifest(
   await injectGitignore(chain, target)
 
   if (!pkg) warnUnreadablePackage(chain, target)
+
+  return { ok: true }
 }
 
 /**

package/src/tooling/install.ts

@@ -0,0 +1,55 @@
+import { execa } from 'execa'
+
+export const INSTALL_TIMEOUT_MS = 120_000
+const TAIL_LINES = 20
+
+export type InstallResult =
+  | { ok: true }
+  | {
+      ok: false
+      reason: 'install-timeout' | 'install-failed'
+      message: string
+    }
+
+/**
+ * Runs `bun add -D` for the specs and bounds it, since a registry that accepts
+ * a connection and never answers would otherwise hang the caller for good. A
+ * stall or a failure comes back as a refusal naming the packages and the tail
+ * of the output, never as a thrown error.
+ */
+export async function installDevDependencies(
+  specs: readonly string[],
+  cwd: string,
+  timeoutMs: number = INSTALL_TIMEOUT_MS,
+): Promise<InstallResult> {
+  const tried = specs.join(', ')
+  const result = await execa('bun', ['add', '-D', ...specs], {
+    cwd,
+    all: true,
+    reject: false,
+    stdin: 'ignore',
+    timeout: timeoutMs,
+  })
+
+  if (!result.failed) return { ok: true }
+
+  if (result.timedOut) {
+    return {
+      ok: false,
+      reason: 'install-timeout',
+      message: `Install timed out after ${Math.round(timeoutMs / 1000)}s. Tried: ${tried}`,
+    }
+  }
+
+  const detail = tail(result.all) || String(result.shortMessage ?? '')
+  return {
+    ok: false,
+    reason: 'install-failed',
+    message: `Install failed. Tried: ${tried}${detail === '' ? '' : `\n${detail}`}`,
+  }
+}
+
+function tail(output: unknown): string {
+  if (typeof output !== 'string') return ''
+  return output.replace(/\n$/, '').split('\n').slice(-TAIL_LINES).join('\n')
+}