@erclx/canon 5.61.0 → 5.63.0

package/governance/ledger/{ui/ux-completeness.md → skills/ui-craft/states.md}

@@ -1,19 +1,20 @@
 ---
-title: UX completeness rule ledger
-description: Sources for governance/rules/ui/ux-completeness.md, one row per bullet
+title: UX completeness reference ledger
+description: Sources for claude/skills/ui-craft/references/states.md, one row per bullet
 ---
 
-# UX completeness rule ledger
+# UX completeness reference ledger
 
 The field is interaction design, and the authorities are the Nielsen Norman Group's research articles, WCAG 2.2 for timing, MDN for the `title` attribute and CSS truncation, and web.dev for layout shift.
 
 ## Feedback
 
-| Bullet                                | Source                                                                                                                                                                                                                                                                     | Read                 |
-| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
-| Confirm success and failure           | [Visibility of system status](https://www.nngroup.com/articles/visibility-system-status/): "Whenever users interact with a system, they need to know whether the interaction was successful"                                                                               | 2026-10-18           |
-| Auto-dismiss only a redundant message | [Understanding Timing Adjustable](https://www.w3.org/WAI/WCAG22/Understanding/timing-adjustable.html): "If the user has no other means of discovering the same information (or performing the same function), then each message would need to meet this success criterion" | 2026-10-18, WCAG 2.2 |
-| No optimistic status                  | House choice: a "connected" dot shown over unsaved edits reports a state the system has not reached, and the person leaves believing their change took                                                                                                                     | 2026-10-18           |
+| Bullet                                 | Source                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Read                 |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
+| Confirm success and failure            | [Visibility of system status](https://www.nngroup.com/articles/visibility-system-status/): "Whenever users interact with a system, they need to know whether the interaction was successful"                                                                                                                                                                                                                                                                        | 2026-10-18           |
+| Auto-dismiss only a redundant message  | [Understanding Timing Adjustable](https://www.w3.org/WAI/WCAG22/Understanding/timing-adjustable.html): "If the user has no other means of discovering the same information (or performing the same function), then each message would need to meet this success criterion"                                                                                                                                                                                          | 2026-10-18, WCAG 2.2 |
+| Timed messages pause and take no focus | [Fluent 2, Toast usage](https://fluent2.microsoft.design/components/web/react/core/toast/usage): a toast with no action times out "after seven seconds", and mouse users "can pause the timer by hovering". [Understanding Status Messages](https://www.w3.org/WAI/WCAG22/Understanding/status-messages.html): status messages are presented "without receiving focus". The pause leaves the redundant-message bullet's rule for when a message may leave unchanged | 2026-10-23           |
+| No optimistic status                   | House choice: a "connected" dot shown over unsaved edits reports a state the system has not reached, and the person leaves believing their change took                                                                                                                                                                                                                                                                                                              | 2026-10-18           |
 
 ## Empty states
 
@@ -29,26 +30,13 @@ The field is interaction design, and the authorities are the Nielsen Norman Grou
 | Indicator past one second      | [Progress indicators](https://www.nngroup.com/articles/progress-indicators/): "Use a progress indicator for any action that takes longer than about 1.0 second"                                         | 2026-10-18 |
 | Mark stale content as updating | [Progress indicators](https://www.nngroup.com/articles/progress-indicators/): "Without any visual change from the system, most users will assume the action was not registered and they will try again" | 2026-10-18 |
 
-## Destructive actions
-
-| Bullet                  | Source                                                                                                                                                                                     | Read       |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
-| Confirm unless undoable | [Confirmation dialogs](https://www.nngroup.com/articles/confirmation-dialog/): "consider a confirmation dialog before actions that cannot be undone", and "do try your best to offer undo" | 2026-10-18 |
-
-## Element states
-
-| Bullet                      | Source                                                                                                                                                                                                                          | Read       |
-| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
-| Distinct interaction states | [Visibility of system status](https://www.nngroup.com/articles/visibility-system-status/): "Did the system actually catch that button press", and an element with no pressed or hover response leaves the person unable to tell | 2026-10-18 |
-| No intermediate flash       | [Cumulative Layout Shift](https://web.dev/articles/cls): "Unexpected layout shifts can disrupt the user experience", caused by content "dynamically added to the page before existing content"                                  | 2026-10-18 |
-
 ## Overflow
 
-| Bullet                        | Source                                                                                                                                                                                                                                  | Read       |
-| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
-| Ellipsis over overflow        | [text-overflow](https://developer.mozilla.org/en-US/docs/Web/CSS/text-overflow): `text-overflow: ellipsis` with `overflow: hidden` and `white-space: nowrap` clips text at the box with a visible marker                                | 2026-10-18 |
-| Never `title` alone           | [The title attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/title): "Use of the title attribute is highly problematic for" people using touch-only devices, keyboards, and assistive technology | 2026-10-18 |
-| Focus rings clear of clipping | House choice: a ring cut off by a parent's `overflow` shows on the middle items of a list and vanishes on the first and last, so the focus indicator fails exactly where the list ends                                                  | 2026-10-18 |
+| Bullet                    | Source                                                                                                                                                                                                                                  | Read       |
+| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Ellipsis over overflow    | [text-overflow](https://developer.mozilla.org/en-US/docs/Web/CSS/text-overflow): `text-overflow: ellipsis` with `overflow: hidden` and `white-space: nowrap` clips text at the box with a visible marker                                | 2026-10-18 |
+| Never `title` alone       | [The title attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/title): "Use of the title attribute is highly problematic for" people using touch-only devices, keyboards, and assistive technology | 2026-10-18 |
+| Borders clear of clipping | House choice: a ring cut off by a parent's `overflow` shows on the middle items of a list and vanishes on the first and last, so the focus indicator fails exactly where the list ends                                                  | 2026-10-18 |
 
 ## Declined
 

package/governance/ledger/ui/craft.md

@@ -0,0 +1,19 @@
+---
+title: UI craft rule ledger
+description: Sources for governance/rules/ui/craft.md, one row per bullet
+---
+
+# UI craft rule ledger
+
+The rule is a pointer to the `ui-craft` and `design-taste` skills, which carry their own sources, so both rows are house choices naming the bug the pointer prevents.
+
+## Authority
+
+| Bullet                     | Source                                                                                                                                                                                      | Read       |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Load the skills            | House choice: a rendered edit made without the behavior floor or the layer order reaches for a model's defaults, and a second copy of either in the rule drifts from the skill that owns it | 2026-10-24 |
+| Report an unresolved skill | House choice: the rule ships with the CLI and the skills with the plugin, so a project holding governance alone would otherwise proceed silently without them                               | 2026-10-18 |
+
+## Declined
+
+The fold kept both bullets and widened the first to name `ui-craft` beside `design-taste`, since the practice rules it replaced now live in that skill.

package/governance/renames.toml

@@ -3,9 +3,11 @@
 # so `canon gov sync` replaces a held old file with the rule under its new name
 # rather than only deleting it.
 #
-# An entry declares one-to-one identity and nothing else. A fold of several
-# rules into one, or a split of one into several, is a retirement plus an
-# addition and takes no entry here. Add the entry in the same change as the
+# An entry declares one-to-one identity, or a fold onto a pointer rule that
+# now routes to the skill carrying the folded rules, so a target holding any
+# of them lands on the pointer rather than losing the practice with nothing in
+# its place. Any other fold of several rules into one, or a split of one into
+# several, is a retirement plus an addition and takes no entry here. Add the entry in the same change as the
 # rename or renumber. Prune an entry only once its target rule is retired and
 # the retire path covers it, since a chain ending on a rule nothing ships
 # resolves to nothing and a sync deletes the held file instead. Otherwise leave
@@ -73,3 +75,15 @@
 "460-design-taste" = "design-taste"
 "465-interface-casing" = "interface-casing"
 "470-motion" = "motion"
+"design-taste" = "craft"
+"a11y" = "craft"
+"keyboard" = "craft"
+"pointer" = "craft"
+"forms" = "craft"
+"motion" = "craft"
+"ux-controls" = "craft"
+"ux-completeness" = "craft"
+"surface-capture" = "craft"
+"copy" = "craft"
+"interface-casing" = "craft"
+"link-behavior" = "craft"

package/governance/rules/lib/test-scope.md

@@ -20,5 +20,5 @@ paths:
 
 - Answer a question about the running page with a script against the dev server rather than with the suite.
 - Do not enable `fullyParallel` in the Playwright config.
-- Follow `.claude/rules/canon/ui/surface-capture.md` for capture scope.
+- Follow the `canon:ui-craft` skill's capture reference for capture scope, reporting it when the skill does not resolve.
 - Follow `.claude/rules/canon/lib/e2e-reliability.md` for waits and guards.

package/governance/rules/ui/craft.md

@@ -0,0 +1,22 @@
+---
+description: Route edits to a rendered surface to the ui-craft skill for how it behaves and to the design-taste skill for how it looks
+paths:
+  - '**/*.tsx'
+  - '**/*.jsx'
+  - '**/*.vue'
+  - '**/*.svelte'
+  - '**/*.astro'
+  - '**/*.html'
+  - '**/*.mdx'
+  - '**/*.css'
+  - '**/*.scss'
+  - '**/content/**/*.ts'
+  - 'canon/DESIGN.md'
+---
+
+# UI craft standards
+
+## Authority
+
+- Load the `canon:ui-craft` skill for how a surface behaves and the `canon:design-taste` skill for how it looks. Each is the single source for its half.
+- Report it rather than proceeding silently when either skill does not resolve. Both ship with the plugin and this rule ships with the CLI, so governance alone carries neither.

package/governance/splits.toml

@@ -0,0 +1,13 @@
+# Rule splits a sync tells a target about. Each key under [split] is the
+# basename of a rule that shed bullets into others, and its value lists the
+# basenames those bullets moved to. `canon gov sync` adds no rule, so a target
+# holding the key and not a partner reads a notice naming the partner and the
+# `canon gov install --add` command that installs it.
+#
+# This ledger is not the rename ledger. A rename entry resolves to a successor
+# the sync installs, and a split key is a live rule the target keeps. Add the
+# entry in the same change as the split. The notice is stateless, so a target
+# installed after the split reads it too until it adds the partner. Prune an
+# entry only once its key or partner is retired, which the live-rule check in
+# `src/gov/splits.test.ts` forces.
+[split]

package/package.json

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

package/src/claude/cases/misc.ts

@@ -17,6 +17,11 @@ export const MISC_CASES: readonly SkillCase[] = [
       'Which layer of this landing page should I settle first, and what has to stay constant across it?',
     expect: 'design-taste',
   },
+  {
+    prompt:
+      'This settings form needs validation and an empty state, so what does it owe for keyboard users and error messages before I build it?',
+    expect: 'ui-craft',
+  },
   {
     prompt:
       'This project has no logo yet. Draft one and give me a social card to go with it.',

package/src/claude/skills-audit.ts

@@ -1,8 +1,20 @@
 import { existsSync } from 'node:fs'
-import { dirname, join } from 'node:path'
+import { dirname, join, relative } from 'node:path'
 import { isFamilyKey } from '@/claude/skills-families'
+import { plural } from '@/cli/ui'
+import {
+  compareLedger,
+  countLedgerRows,
+  type LedgerMismatch,
+  measureRule,
+} from '@/gov/audit'
 import { parseFrontmatter, readField } from '@/indexes/frontmatter'
-import { type BodyLine, bodyLines, maskDisplayed } from '@/markdown/scan'
+import {
+  type BodyLine,
+  bodyLines,
+  maskCodeSpans,
+  maskDisplayed,
+} from '@/markdown/scan'
 
 /** Returned when a skill folder carries no `REQUIREMENT.md`, the gating check. */
 export const EXIT_MISSING_REQUIREMENT = 2
@@ -69,8 +81,22 @@ export const LEDGER_SKILLS: readonly string[] = [
   join(SHIPPED_CORPUS, 'design-taste'),
   join(SHIPPED_CORPUS, 'write-human'),
   join(SHIPPED_CORPUS, 'test-first'),
+  join(SHIPPED_CORPUS, 'ui-craft'),
 ]
 
+/**
+ * The ledger-listed skills whose every reference but the source record carries
+ * a ledger of its own, one table row per bullet under each H2, the way a rule
+ * in a practice folder does. The ledgers sit outside the plugin as rule
+ * ledgers do, so a target pays nothing for them.
+ */
+export const BULLET_LEDGER_SKILLS: readonly string[] = [
+  join(SHIPPED_CORPUS, 'ui-craft'),
+]
+
+/** Where a per-bullet ledger lives, as `<skill>/<reference>.md` below it. */
+export const SKILL_LEDGERS = join('governance', 'ledger', 'skills')
+
 /** The closing H2s a practice skill carries, matched exactly outside fences. */
 export const PRACTICE_SECTIONS: readonly string[] = [
   'Excuses and rebuttals',
@@ -81,6 +107,19 @@ export const PRACTICE_SECTIONS: readonly string[] = [
 /** The source ledger every practice skill carries beside its body. */
 export const PRACTICE_LEDGER = join('references', 'adopted.md')
 
+/**
+ * A ledger cites a source by linking a page outside the project, as an inline
+ * link or an autolink. A relative link points back into the skill and cites
+ * nothing a reader could check the rule against.
+ */
+const EXTERNAL_LINK = /\]\(\s*https?:\/\/|<https?:\/\//
+
+/**
+ * A table cell opening on the marker the governance ledgers already use for a
+ * rule the toolkit chose, so one check reads every ledger alike.
+ */
+const HOUSE_CHOICE = /\|\s*House choice\b/
+
 /**
  * The line count past which a reference opens with a contents list, from
  * Anthropic's skill authoring guidance. Counted over the whole file the way
@@ -166,13 +205,23 @@ interface SkillSource {
   readonly requirement: string | undefined
   /** Every H2 in `SKILL.md` outside a fence, for the practice shape. */
   readonly sections: readonly string[]
-  readonly hasLedger: boolean
+  /** Undefined when the folder carries no ledger at all. */
+  readonly ledger: string | undefined
   /**
    * `SKILL.md` and every reference below the folder, keyed by the path a
    * finding names. `REQUIREMENT.md` and `EVAL.md` are left out, since the
    * requirement is where the standard sends a date.
    */
   readonly bodies: readonly SkillText[]
+  /** One entry per reference of a skill on the per-bullet ledger list. */
+  readonly referenceLedgers: readonly ReferenceLedger[]
+}
+
+interface ReferenceLedger {
+  readonly rel: string
+  readonly ledgerRel: string
+  /** Undefined when the ledger file is absent. */
+  readonly mismatches: readonly LedgerMismatch[] | undefined
 }
 
 interface SkillText {
@@ -195,7 +244,7 @@ export async function auditSkills(root: string): Promise<SkillsAudit> {
   )
 
   const perCorpus = await Promise.all(
-    present.map((corpus) => readCorpus(corpus.rel, corpus.dir)),
+    present.map((corpus) => readCorpus(root, corpus.rel, corpus.dir)),
   )
   const sources = perCorpus.flat()
 
@@ -247,21 +296,29 @@ export function auditExitCode(report: SkillsAudit): number {
   return report.missingRequirement.length > 0 ? EXIT_MISSING_REQUIREMENT : 0
 }
 
-async function readCorpus(rel: string, dir: string): Promise<SkillSource[]> {
+async function readCorpus(
+  root: string,
+  rel: string,
+  dir: string,
+): Promise<SkillSource[]> {
   const paths = [
     ...new Bun.Glob('*/SKILL.md').scanSync({ cwd: dir, onlyFiles: true }),
   ].sort()
 
-  return Promise.all(paths.map((path) => readSkill(rel, dir, dirname(path))))
+  return Promise.all(
+    paths.map((path) => readSkill(root, rel, dir, dirname(path))),
+  )
 }
 
 async function readSkill(
+  root: string,
   rel: string,
   dir: string,
   folder: string,
 ): Promise<SkillSource> {
   const skillDir = join(dir, folder)
   const requirementPath = join(skillDir, 'REQUIREMENT.md')
+  const ledgerPath = join(skillDir, PRACTICE_LEDGER)
 
   const references = [
     ...new Bun.Glob('references/**/*.md').scanSync({
@@ -270,11 +327,14 @@ async function readSkill(
     }),
   ].sort()
 
-  const [body, requirement, referenceTexts] = await Promise.all([
+  const [body, requirement, ledger, referenceTexts] = await Promise.all([
     Bun.file(join(skillDir, 'SKILL.md')).text(),
     existsSync(requirementPath)
       ? Bun.file(requirementPath).text()
       : Promise.resolve(undefined),
+    existsSync(ledgerPath)
+      ? Bun.file(ledgerPath).text()
+      : Promise.resolve(undefined),
     Promise.all(
       references.map((path) => Bun.file(join(skillDir, path)).text()),
     ),
@@ -282,6 +342,15 @@ async function readSkill(
 
   const fields = parseFrontmatter(body)
   const skillRel = join(rel, folder)
+  const referenceLedgers = BULLET_LEDGER_SKILLS.includes(skillRel)
+    ? await readReferenceLedgers(
+        root,
+        skillRel,
+        folder,
+        references,
+        referenceTexts,
+      )
+    : []
 
   return {
     rel: skillRel,
@@ -294,7 +363,7 @@ async function readSkill(
       requirement === undefined ? undefined : headings(requirement),
     requirement,
     sections: sectionsOf(body),
-    hasLedger: existsSync(join(skillDir, PRACTICE_LEDGER)),
+    ledger,
     bodies: [
       { rel: join(skillRel, 'SKILL.md'), text: body, isReference: false },
       ...references.map((path, index) => ({
@@ -303,9 +372,45 @@ async function readSkill(
         isReference: true,
       })),
     ],
+    referenceLedgers,
   }
 }
 
+/**
+ * Pairs each reference's bullets with its ledger's rows through the rule
+ * audit's own comparison, so a reference and a rule are held to one count.
+ * The source record names authorities rather than stating bullets, so it is
+ * the one reference asked for no ledger.
+ */
+async function readReferenceLedgers(
+  root: string,
+  skillRel: string,
+  folder: string,
+  references: readonly string[],
+  texts: readonly string[],
+): Promise<ReferenceLedger[]> {
+  return Promise.all(
+    references
+      .map((path, index) => ({ path, text: texts[index] ?? '' }))
+      .filter(({ path }) => path !== PRACTICE_LEDGER)
+      .map(async ({ path, text }) => {
+        const ledgerRel = join(
+          SKILL_LEDGERS,
+          folder,
+          relative('references', path),
+        )
+        const ledgerPath = join(root, ledgerRel)
+        const mismatches = existsSync(ledgerPath)
+          ? compareLedger(
+              measureRule(text).groups,
+              countLedgerRows(await Bun.file(ledgerPath).text()),
+            )
+          : undefined
+        return { rel: join(skillRel, path), ledgerRel, mismatches }
+      }),
+  )
+}
+
 /**
  * A key carrying an empty value declares nothing, so blank reads as absent
  * rather than as a name that disagrees with every folder.
@@ -493,11 +598,44 @@ function practiceFindings(source: SkillSource): SkillFinding[] {
       rel: source.rel,
       detail: `missing section: ${section}`,
     }))
-  const ledger = source.hasLedger
-    ? []
-    : [{ rel: source.rel, detail: `missing ledger: ${PRACTICE_LEDGER}` }]
 
-  return [...sections, ...ledger]
+  return [
+    ...sections,
+    ...ledgerFindings(source),
+    ...source.referenceLedgers.flatMap(referenceLedgerFindings),
+  ]
+}
+
+function referenceLedgerFindings(entry: ReferenceLedger): SkillFinding[] {
+  if (entry.mismatches === undefined) {
+    return [{ rel: entry.rel, detail: `missing ledger: ${entry.ledgerRel}` }]
+  }
+  return entry.mismatches.map((mismatch) => ({
+    rel: entry.rel,
+    detail: `${mismatch.heading === null ? 'above the first H2' : `## ${mismatch.heading}`}: ${plural(mismatch.bullets, 'bullet')}, ${plural(mismatch.rows, 'ledger row')}`,
+  }))
+}
+
+/**
+ * A ledger present but citing nothing passed for as long as the check read the
+ * file's existence alone, so the contents are read too. A sample block shows a
+ * reader the shape of a row and cites nothing, so fences and code spans are
+ * left out.
+ */
+function ledgerFindings(source: SkillSource): SkillFinding[] {
+  if (source.ledger === undefined) {
+    return [{ rel: source.rel, detail: `missing ledger: ${PRACTICE_LEDGER}` }]
+  }
+
+  const cites = bodyLines(source.ledger)
+    .filter((line) => !line.fenced)
+    .map((line) => maskCodeSpans(line.text))
+    .some((text) => EXTERNAL_LINK.test(text) || HOUSE_CHOICE.test(text))
+  if (cites) return []
+
+  return [
+    { rel: source.rel, detail: `ledger cites nothing: ${PRACTICE_LEDGER}` },
+  ]
 }
 
 /**

package/src/commands/claude.ts

@@ -30,6 +30,8 @@ import {
   DESCRIPTION_LIMIT,
   LEDGER_SKILLS,
   PRACTICE_LEDGER,
+  BULLET_LEDGER_SKILLS,
+  SKILL_LEDGERS,
   PRACTICE_SECTIONS,
   PRACTICE_SKILLS,
   REQUIREMENT_LIMITS,
@@ -1768,6 +1770,9 @@ function reportPracticeShape(report: SkillsAudit): void {
   logInfo(
     `A listed practice skill closes with ${PRACTICE_SECTIONS.map((section) => `## ${section}`).join(', ')}, and every skill on the wider ledger list carries ${PRACTICE_LEDGER}.`,
   )
+  logInfo(
+    `A skill on the per-bullet list, ${plural(BULLET_LEDGER_SKILLS.length, 'skill')} here, also matches each other reference to a ledger under ${SKILL_LEDGERS}, one row per bullet under each H2.`,
+  )
   logInfo(
     `Both lists are kept here and name ${plural(PRACTICE_SKILLS.length, 'practice skill')} and ${plural(LEDGER_SKILLS.length, 'ledger skill')}, so a skill outside ${SHIPPED_CORPUS} is never read.`,
   )

package/src/commands/sync.ts

@@ -285,7 +285,9 @@ function renderTooling(report: CheckReport): void {
     if (count > 0) logWarn(`${count} ${category}`)
   }
   logInfo(
-    'Run `canon tooling sync --check` to see which files, `--write` to apply.',
+    tooling.changes === tooling.counts.customized
+      ? 'A customized config moved upstream, and no write touches it. Run `canon tooling diff` to see which, and `canon tooling lift <path>` to take it.'
+      : 'Run `canon tooling sync --check` to see which files, `--write` to apply.',
   )
 }