@erclx/canon 4.117.0 → 4.119.0

package/src/design/neutral.ts

@@ -0,0 +1,127 @@
+import type { ColorToken, DesignTokens } from '@/design/tokens'
+import { TOKENS } from '@/design/tokens'
+
+/**
+ * The token set `canon design install` hands a target, achromatic so the only
+ * palette a target renders is one it wrote under `.claude/design/project/`.
+ * Type, spacing, and radii are this repository's by spread, and only the color
+ * list is a second copy, held to the same roles by `neutral.test.ts`.
+ *
+ * Grounds, surface, chrome, and border take the OKLCH lightness of the toolkit
+ * role they replace at chroma 0. Text roles are solved against `surface` for
+ * the contrast targets `TOKENS` records (13.5, 8.6, 5.6, 4.6), and the accent
+ * for 15.5, past `text` so it still reads apart from body copy. The state
+ * roles keep the toolkit's values, since a state color is a meaning rather
+ * than a palette.
+ */
+
+const DARK_GROUNDS = ['background', 'surface'] as const
+const LIGHT_GROUNDS = ['light-background', 'light-surface'] as const
+
+function toolkitRole(role: string): ColorToken {
+  const token = TOKENS.color.find((candidate) => candidate.role === role)
+  if (token === undefined) throw new Error(`TOKENS declares no ${role} role`)
+  return token
+}
+
+const NEUTRAL_COLOR: readonly ColorToken[] = [
+  { role: 'background', intent: 'page canvas', value: '#0e0e0e' },
+  {
+    role: 'surface',
+    intent: 'cards, panels, raised blocks',
+    value: '#141414',
+  },
+  {
+    role: 'chrome',
+    intent: 'the window titlebar, one step above the canvas',
+    value: '#1a1a1a',
+  },
+  { role: 'border', intent: 'every rule and panel edge', value: '#292929' },
+  {
+    role: 'text',
+    intent: 'headings, counts, emphasized runs',
+    value: '#dddddd',
+    grounds: DARK_GROUNDS,
+  },
+  {
+    role: 'text-body',
+    intent: 'default body copy',
+    value: '#b2b2b2',
+    grounds: DARK_GROUNDS,
+  },
+  {
+    role: 'text-secondary',
+    intent: 'labels, captions, supporting copy',
+    value: '#8e8e8e',
+    grounds: DARK_GROUNDS,
+  },
+  {
+    role: 'muted',
+    intent: 'the faintest step, trailing notes',
+    value: '#7f7f7f',
+    grounds: DARK_GROUNDS,
+  },
+  {
+    role: 'accent',
+    intent: 'install command, mark, primary action',
+    value: '#ececec',
+    grounds: DARK_GROUNDS,
+  },
+  toolkitRole('success'),
+  toolkitRole('warning'),
+  toolkitRole('error'),
+  {
+    role: 'light-background',
+    intent: 'page canvas on a light ground',
+    value: '#fafafa',
+  },
+  {
+    role: 'light-surface',
+    intent: 'cards and panels on a light ground',
+    value: '#f1f1f1',
+  },
+  {
+    role: 'light-chrome',
+    intent: 'the window titlebar, one step above the canvas',
+    value: '#e8e8e8',
+  },
+  {
+    role: 'light-text',
+    intent: 'primary text on a light ground',
+    value: '#252525',
+    grounds: LIGHT_GROUNDS,
+  },
+  {
+    role: 'light-text-body',
+    intent: 'default body copy on a light ground',
+    value: '#444444',
+    grounds: LIGHT_GROUNDS,
+  },
+  {
+    role: 'light-text-secondary',
+    intent: 'labels, captions, supporting copy on a light ground',
+    value: '#5f5f5f',
+    grounds: LIGHT_GROUNDS,
+  },
+  {
+    role: 'light-muted',
+    intent: 'secondary text on a light ground',
+    value: '#6c6c6c',
+    grounds: LIGHT_GROUNDS,
+  },
+  {
+    role: 'light-accent',
+    intent: 'links and primary action on light',
+    value: '#191919',
+    grounds: LIGHT_GROUNDS,
+  },
+  toolkitRole('light-success'),
+  {
+    role: 'light-border',
+    intent: 'rules and panel edges on light',
+    value: '#d4d4d4',
+    verify: true,
+  },
+]
+
+export const NEUTRAL_TOKENS: DesignTokens = { ...TOKENS, color: NEUTRAL_COLOR }

package/src/design/regen.ts

@@ -2,10 +2,12 @@ import { mkdirSync, writeFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { buildDesignCss } from '@/design/css'
 import { renderDesignDocument } from '@/design/document'
+import { NEUTRAL_TOKENS } from '@/design/neutral'
 
 /**
- * The two artifacts the token source produces, written by `canon design regen`
- * and asserted for drift by the `design` stage of `bun run check`.
+ * The two artifacts the token sources produce, written by `canon design regen`
+ * and asserted for drift by the `design` stage of `bun run check`. The
+ * document renders from `TOKENS` and the stylesheet from `NEUTRAL_TOKENS`.
  *
  * The document is what a person reads and the stylesheet is what a target
  * installs, and neither is edited by hand. That is the cost the operator took
@@ -26,7 +28,7 @@ export const DESIGN_DOCUMENT = join('canon', 'DESIGN.md')
 export const DESIGN_BASE_CSS = join('src', 'design', 'base.css')
 
 const BASE_BANNER = [
-  'Generated by `canon design regen` from src/design/tokens.ts. Do not edit.',
+  'Generated by `canon design regen` from src/design/neutral.ts. Do not edit.',
   'This is the base half of a design install. A target overrides a value in',
   '.claude/design/project/, which the three-way merge leaves alone, so this',
   'file changes freely and nothing a project wrote lives in it.',
@@ -50,7 +52,7 @@ export function regenDesign(root: string): RegenResult {
     cssPath: write(
       root,
       DESIGN_BASE_CSS,
-      buildDesignCss(undefined, { banner: BASE_BANNER }),
+      buildDesignCss(NEUTRAL_TOKENS, { banner: BASE_BANNER }),
     ),
   }
 }

package/src/design/tokens.ts

@@ -386,8 +386,11 @@ export const TOKENS: DesignTokens = {
 }
 
 /** A role's value, or `undefined` where the record declares no such role. */
-export function colorValue(role: string): string | undefined {
-  return TOKENS.color.find((token) => token.role === role)?.value
+export function colorValue(
+  role: string,
+  tokens: DesignTokens = TOKENS,
+): string | undefined {
+  return tokens.color.find((token) => token.role === role)?.value
 }
 
 /**

package/src/gate/measures.ts

@@ -12,6 +12,7 @@ import {
   isOverLength,
   measureArchitecture,
 } from '@/context/architecture'
+import { auditSkills } from '@/claude/skills-audit'
 import { listRepositoryFiles } from '@/git-files'
 import { ceilingFindings } from '@/markdown/ceiling'
 import { resolveMarkdown } from '@/markdown/files'
@@ -277,6 +278,42 @@ export const architectureRecord: Measure = async (ctx) => {
   }
 }
 
+/**
+ * Every skill body and reference against the no-dated-provenance rule, across
+ * both corpora `auditSkills` reads.
+ *
+ * Read in-process rather than through `claude skills audit`, whose exit code
+ * stays a missing requirement only, so a target running the verb is told about
+ * a date without failing on one. This repository holds the corpus at zero,
+ * which is what lets the same finding fail here.
+ */
+export const skillProvenance: Measure = async (ctx) => {
+  const report = await auditSkills(ctx.root)
+  if (report.corpora.length === 0) {
+    return {
+      emissions: [],
+      unmeasured: 'no skill corpus resolved, so no body was read.',
+    }
+  }
+
+  const found = report.datedProvenance
+  if (found.length > 0) {
+    const where = found
+      .map((finding) => `${finding.rel} ${finding.detail}`)
+      .join(', ')
+    return {
+      emissions: [],
+      failure: `${plural(found.length, 'date')} in skill prose: ${where}. Move the incident to REQUIREMENT.md under Gap or leave it to git, or fence the date or put it in a code span when it is an example.`,
+    }
+  }
+
+  return {
+    emissions: [
+      info(`No dated provenance across ${plural(report.skills, 'skill')}`),
+    ],
+  }
+}
+
 /**
  * Every tracked markdown document against the whole-document ceiling.
  *

package/src/gate/stages.ts

@@ -13,6 +13,7 @@ import {
   seedStandards,
   rawFieldFileReference,
   shippedReferences,
+  skillProvenance,
   standardCriteria,
   unreferencedRules,
   visualPathGlobs,
@@ -208,10 +209,10 @@ export const STAGES: readonly Stage[] = [
     success: 'Hero clean',
   },
   {
-    // `canon/DESIGN.md`, the base stylesheet, the web stylesheet, and the
-    // tab icon are all written from `src/design/tokens.ts` and none is edited
-    // by hand. Four artifacts from one source is the cost of the token move,
-    // and a render step that has to run is only safe while something fails
+    // `canon/DESIGN.md`, the web stylesheet, and the tab icon are written
+    // from `src/design/tokens.ts`, the base stylesheet from
+    // `src/design/neutral.ts`, and none is edited by hand. Four artifacts
+    // from two token sources is the cost of the token move, and a render step that has to run is only safe while something fails
     // when it did not, which is this.
     id: 'design',
     label: 'Design',
@@ -468,6 +469,14 @@ export const STAGES: readonly Stage[] = [
     ],
     success: 'Skill requirements present',
   },
+  {
+    // The audit verb only reports a dated line, so a target is told without
+    // failing. This stage makes the same finding fail here, where the corpus is
+    // held at zero. Unscoped, since any branch can add a line to any body.
+    id: 'skill-provenance',
+    label: 'Skill provenance',
+    checks: [{ kind: 'measure', measure: skillProvenance }],
+  },
   {
     id: 'standard-criteria',
     label: 'Standard success criteria',

package/src/gov/adapter.ts

@@ -1,6 +1,7 @@
 import { existsSync } from 'node:fs'
 import { basename, join, relative, resolve } from 'node:path'
-import { canonRulesDir } from '@/gov/install'
+import { canonRulesDir, ruleSubdir } from '@/gov/install'
+import { loadRenames, resolveSuccessor } from '@/gov/renames'
 import { resolveMissingRules } from '@/gov/stacks'
 import type { InstalledFile, RetiredSurface, SyncAdapter } from '@/sync/engine'
 import { readStamp, stampedChain } from '@/sync/stamp'
@@ -44,15 +45,19 @@ export function indexSourceRules(root: string): Map<string, string> {
  * path, so a rule that moved between subdirectories in the toolkit still
  * syncs into the subdirectory the target already uses.
  *
- * Declares no `projectSubdir`. That exemption existed to keep a project's
- * `.claude/rules/project/` folder out of the walk by location before any
- * name lookup ran, and `installedRoot` narrowing to `.claude/rules/canon/`
- * already leaves `project/` outside the walked root, so a second exemption
- * computing a stale `canon/project/` destination would be wrong rather than
- * merely redundant.
+ * Declares `ownsInstalledRoot` and no `projectSubdir`. A project keeps its own
+ * rules under `.claude/rules/project/`, which `installedRoot` narrowing to
+ * `.claude/rules/canon/` leaves outside the walk, so everything the walk does
+ * reach is the toolkit's. A rule there with no source is one the toolkit
+ * retired or renamed, and the sync deletes it rather than leaving it loaded.
+ * A rename `governance/renames.toml` declares also installs the rule under its
+ * new name.
+ * A `projectSubdir` would compute a stale `canon/project/` destination, which
+ * is wrong rather than merely redundant.
  */
 export function createGovAdapter(root: string): SyncAdapter {
   const index = indexSourceRules(root)
+  const renames = loadRenames(root)
 
   return {
     banner: 'canon gov sync',
@@ -65,10 +70,57 @@ export function createGovAdapter(root: string): SyncAdapter {
       index.get(basename(file.path, '.md')),
     collectRetired: (target: string) => collectRetiredGov(target),
     collectMissing: (target: string) => collectMissingGov(root, target),
+    ownsInstalledRoot: true,
+    locateSuccessor: (file: InstalledFile, target: string) => {
+      const successor = resolveSuccessor(
+        renames,
+        index,
+        basename(file.path, '.md'),
+      )
+      if (successor === undefined) return undefined
+
+      const source = index.get(successor)
+      if (source === undefined) return undefined
+
+      return {
+        source,
+        dest:
+          heldRulePath(target, successor) ??
+          join(
+            canonRulesDir(target),
+            ruleSubdir(source, rulesSourceDir(root)),
+            `${successor}.md`,
+          ),
+      }
+    },
     stamp: { domain: 'governance', toolkitRoot: root },
   }
 }
 
+/**
+ * Where the target already holds a rule, in whichever band folder. A
+ * successor held outside the source's band stays where it is, the same way
+ * `locateSource` syncs a moved rule in place, rather than gaining a second copy.
+ *
+ * Holding the predecessor is the whole entitlement test, so no stamped chain
+ * is read here. That covers a rule `--add` layered on and a target installed
+ * before chains were stamped alike.
+ */
+function heldRulePath(target: string, rule: string): string | undefined {
+  const dir = canonRulesDir(target)
+  if (!existsSync(dir)) return undefined
+
+  for (const rel of new Bun.Glob(`**/${rule}.md`).scanSync({
+    cwd: dir,
+    onlyFiles: true,
+    dot: true,
+  })) {
+    return join(dir, rel)
+  }
+
+  return undefined
+}
+
 /**
  * Rules the target's recorded chain entitles it to and its tree does not
  * hold. Reports as `notice` text through the same shape `collectRetired`

package/src/gov/install.ts

@@ -38,8 +38,14 @@ export function installedInternalRulesDir(target: string): string {
  * Rule names a target already holds, read off the installed `canon/` tree by
  * basename rather than off a recorded stack, since a target may hold rules
  * `--add` layered on that no stack lists.
+ *
+ * `successorOf` adds the name a held rule was renamed to, since the next sync
+ * installs it and a reader treating it as missing would name it twice.
  */
-export function installedRuleNames(target: string): Set<string> {
+export function installedRuleNames(
+  target: string,
+  successorOf?: (name: string) => string | undefined,
+): Set<string> {
   const dir = canonRulesDir(target)
   const names = new Set<string>()
   if (!existsSync(dir)) return names
@@ -49,7 +55,11 @@ export function installedRuleNames(target: string): Set<string> {
     onlyFiles: true,
     dot: true,
   })) {
-    names.add(basename(rel, '.md'))
+    const name = basename(rel, '.md')
+    names.add(name)
+
+    const successor = successorOf?.(name)
+    if (successor !== undefined) names.add(successor)
   }
 
   return names
@@ -84,7 +94,7 @@ export function listRuleSourcePaths(root: string): string[] {
  * in two subdirectories resolves deterministically rather than by whichever
  * entry the filesystem yielded first.
  */
-function indexRuleSources(root: string): Map<string, string> {
+export function indexRuleSources(root: string): Map<string, string> {
   const rulesRoot = rulesSourceDir(root)
   const byName = new Map<string, string>()
 

package/src/gov/renames.ts

@@ -0,0 +1,76 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { indexRuleSources } from '@/gov/install'
+
+/** Old rule basename to the basename the same rule ships under now. */
+export type Renames = ReadonlyMap<string, string>
+
+function renamesPath(root: string): string {
+  return join(root, 'governance', 'renames.toml')
+}
+
+/**
+ * Reads the shipped rename ledger. A toolkit without one declares no renames,
+ * which leaves every sourceless rule on the retire path it took before the
+ * ledger existed.
+ */
+export function loadRenames(root: string): Renames {
+  const path = renamesPath(root)
+  if (!existsSync(path)) return new Map()
+
+  const parsed = Bun.TOML.parse(readFileSync(path, 'utf8')) as Record<
+    string,
+    unknown
+  >
+  const table = parsed.renamed
+  if (typeof table !== 'object' || table === null) return new Map()
+
+  return new Map(
+    Object.entries(table).filter(
+      (entry): entry is [string, string] => typeof entry[1] === 'string',
+    ),
+  )
+}
+
+/**
+ * Follows a declared rename to the name the toolkit ships the rule under now,
+ * through every later rename of that name. The ledger is never pruned, so a
+ * target several releases behind still reaches the current name.
+ *
+ * Returns nothing when the chain ends on a name with no source, or loops,
+ * since installing a guess is worse than the retire the caller falls back to.
+ */
+export function resolveSuccessor(
+  renames: Renames,
+  index: ReadonlyMap<string, string>,
+  name: string,
+): string | undefined {
+  const visited = new Set([name])
+  let current = renames.get(name)
+
+  while (current !== undefined) {
+    if (visited.has(current)) return undefined
+    visited.add(current)
+
+    const next = renames.get(current)
+    if (next === undefined) break
+    current = next
+  }
+
+  if (current === undefined || !index.has(current)) return undefined
+  return current
+}
+
+/**
+ * Binds the ledger and the source tree at `root` once, for a caller asking
+ * about many held names.
+ */
+export function successorResolver(
+  root: string,
+): (name: string) => string | undefined {
+  const renames = loadRenames(root)
+  if (renames.size === 0) return () => undefined
+
+  const index = indexRuleSources(root)
+  return (name) => resolveSuccessor(renames, index, name)
+}

package/src/gov/stacks.ts

@@ -7,6 +7,7 @@ import {
   type RuleSource,
   rulesSourceDir,
 } from '@/gov/install'
+import { successorResolver } from '@/gov/renames'
 
 export interface GovStack {
   readonly name: string
@@ -163,6 +164,9 @@ export function unreferencedRules(root: string): string[] {
  * so reading its leaf entry is enough; no second walk resolves the chain
  * itself. A stack the toolkit no longer ships resolves to nothing rather than
  * throwing, the same way `readNewRules`'s band fallback already treats it.
+ *
+ * A held rule's declared successor counts as held, since the sync that
+ * renames the old file installs it.
  */
 export function resolveMissingRules(
   root: string,
@@ -176,7 +180,7 @@ export function resolveMissingRules(
   if (!resolution.ok) return []
 
   const { found } = lookupRules(root, resolution.rules)
-  const held = installedRuleNames(target)
+  const held = installedRuleNames(target, successorResolver(root))
 
   return found
     .filter((source) => !held.has(source.rule))

package/src/records/validate.ts

@@ -271,7 +271,9 @@ const PLAN_SECTIONS = [
   'Summary',
   'Constraints',
   'Files to touch',
+  'Verification',
   'Risks',
+  'Review focus',
   'Questions',
 ] as const
 
@@ -280,7 +282,9 @@ type PlanSection = (typeof PLAN_SECTIONS)[number]
 const PLAN_REQUIRED: readonly PlanSection[] = [
   'Summary',
   'Files to touch',
+  'Verification',
   'Risks',
+  'Review focus',
   'Questions',
 ]
 
@@ -293,7 +297,7 @@ const MARKER_LINE = /^(?:##[ \t]+(.+?)|\*\*(.+?):\*\*)[ \t]*$/
 
 /**
  * A section opens as a bold label or as an H2 and both count. The corpus writes
- * `Summary` as a heading and the other four as bold labels, and roughly a fifth
+ * `Summary` as a heading and the others as bold labels, and roughly a fifth
  * of it swaps one for the other. Reporting the variant would fail nearly every
  * plan present on the rule a reader is least served by, which is what teaches
  * them to skip the output.

package/src/sync/check.ts

@@ -4,6 +4,7 @@ import { execa } from 'execa'
 import { gitEnv } from '@/git-env'
 import { createDesignAdapter, DESIGN_INSTALL_DIR } from '@/design/adapter'
 import { createGovAdapter, rulesSourceDir } from '@/gov/adapter'
+import { successorResolver } from '@/gov/renames'
 import { loadGovStack, resolveMissingRules, resolveRules } from '@/gov/stacks'
 import { planSync, type ScanEntry, type SyncAdapter } from '@/sync/engine'
 import {
@@ -79,6 +80,8 @@ export interface StateCounts {
   readonly orphaned: number
   readonly stranded: number
   readonly missing: number
+  readonly retired: number
+  readonly renamed: number
 }
 
 export interface DomainReport {
@@ -314,6 +317,8 @@ export function countStates(entries: readonly ScanEntry[]): StateCounts {
     orphaned: count(entries, 'orphaned'),
     stranded: count(entries, 'stranded'),
     missing: count(entries, 'missing'),
+    retired: count(entries, 'retired'),
+    renamed: count(entries, 'renamed'),
   }
 }
 
@@ -342,6 +347,11 @@ export function countStates(entries: readonly ScanEntry[]): StateCounts {
  * sync that adds a rule silently changes what a project is governed by, and
  * nobody chose that, so gating CI on the count would pressure a target into
  * adopting a rule nobody picked.
+ *
+ * `retired` counts, since a sync deletes it mechanically. A target's CI goes
+ * red the day a release retires a rule it holds, and one sync clears it.
+ * `renamed` counts on the same grounds, since the sync that moves it is
+ * equally mechanical.
  */
 export function hasDrift(report: CheckReport): boolean {
   if (report.unmigrated.length > 0) return true
@@ -351,7 +361,9 @@ export function hasDrift(report: CheckReport): boolean {
       domain.counts.stale +
         domain.counts.customized +
         domain.counts.drifted +
-        domain.counts.stranded >
+        domain.counts.stranded +
+        domain.counts.retired +
+        domain.counts.renamed >
       0,
   )
 }
@@ -482,8 +494,14 @@ export function parseNewSkills(paths: string): string[] {
  * chain a target consumed survives nowhere else. `installRules` copies each
  * rule into the subdirectory it was authored in, which is what makes the band
  * folders legible as evidence.
+ *
+ * `successorOf` adds the name a held rule was renamed to, which the next sync
+ * installs, so the fallback does not report it as new.
  */
-export function readInstalledRules(target: string): {
+export function readInstalledRules(
+  target: string,
+  successorOf?: (name: string) => string | undefined,
+): {
   held: Set<string>
   bands: Set<string>
 } {
@@ -500,7 +518,10 @@ export function readInstalledRules(target: string): {
     const posix = rel.split(sep).join('/')
     const boundary = posix.indexOf('/')
 
-    held.add(basename(posix, '.md'))
+    const name = basename(posix, '.md')
+    held.add(name)
+    const successor = successorOf?.(name)
+    if (successor !== undefined) held.add(successor)
     if (boundary > 0) bands.add(posix.slice(0, boundary))
   }
 
@@ -634,7 +655,7 @@ export async function readNewRules(
     'governance/rules/',
   ])
 
-  const { held, bands } = readInstalledRules(target)
+  const { held, bands } = readInstalledRules(target, successorResolver(root))
   return selectNewRules(paths, held, bands.union(baseBands(root)))
 }