@erclx/canon 5.60.0 → 5.62.0

package/src/design/audit.ts

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

package/src/design/budget.ts

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

package/src/design/document.ts

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

package/src/design/themes.ts

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

package/src/design/tokens.ts

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

package/src/driver/drive.ts

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

package/src/driver/probes/axe.ts

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

package/src/driver/steps.ts

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

package/src/gate/measures.ts

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

package/src/gov/adapter.ts

@@ -3,6 +3,7 @@ import { basename, join, relative, resolve } from 'node:path'
 import { readCoverage } from '@/gov/coverage'
 import { canonRulesDir, ruleSubdir } from '@/gov/install'
 import { loadRenames, resolveSuccessor } from '@/gov/renames'
+import { loadSplits } from '@/gov/splits'
 import { resolveMissingRules } from '@/gov/stacks'
 import type { InstalledFile, RetiredSurface, SyncAdapter } from '@/sync/engine'
 import { readStamp, stampedChain } from '@/sync/stamp'
@@ -125,14 +126,15 @@ function heldRulePath(target: string, rule: string): string | 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`
- * already returns, since both are surfaces the file walk cannot see: one an
- * absence to remove, this one an absence to add.
+ * hold, then the partners of a held rule that split. Reports as `notice` text
+ * through the same shape `collectRetired` already returns, since both are
+ * surfaces the file walk cannot see: one an absence to remove, this one an
+ * absence to add.
  */
 function collectMissingGov(root: string, target: string): RetiredSurface[] {
   const chain = stampedChain(readStamp(target), 'governance')
 
-  return resolveMissingRules(root, target, chain).map((source) => {
+  const fromChain = resolveMissingRules(root, target, chain).map((source) => {
     const dest = join(canonRulesDir(target), source.subdir, `${source.rule}.md`)
     const rel = relative(target, dest)
     return {
@@ -141,6 +143,53 @@ function collectMissingGov(root: string, target: string): RetiredSurface[] {
       notice: `${rel} (listed by ${chain[0]}, not installed. Run canon gov install ${chain[0]} to add it.)`,
     }
   })
+
+  const listed = new Set(fromChain.map((entry) => entry.path))
+  const fromSplits = collectSplitPartners(root, target).filter(
+    (entry) => !listed.has(entry.path),
+  )
+
+  return [...fromChain, ...fromSplits]
+}
+
+/**
+ * Partners the split ledger names for a rule the target holds and whose own
+ * file it lacks. The ui rules sit in no stack, so no chain entitles a target
+ * to them and the chain-based read stays silent when one splits. Holding the
+ * rule is the entitlement, found by basename the way `heldRulePath` finds a
+ * predecessor, so a partner held under another folder reads as held.
+ */
+function collectSplitPartners(root: string, target: string): RetiredSurface[] {
+  const splits = loadSplits(root)
+  if (splits.size === 0) return []
+
+  const index = indexSourceRules(root)
+  const notices: RetiredSurface[] = []
+
+  for (const [held, partners] of splits) {
+    if (heldRulePath(target, held) === undefined) continue
+
+    for (const partner of partners) {
+      const source = index.get(partner)
+      if (source === undefined || heldRulePath(target, partner) !== undefined) {
+        continue
+      }
+
+      const dest = join(
+        canonRulesDir(target),
+        ruleSubdir(source, rulesSourceDir(root)),
+        `${partner}.md`,
+      )
+      const rel = relative(target, dest)
+      notices.push({
+        path: dest,
+        rel,
+        notice: `${rel} (${held}.md moved bullets here. Run canon gov install --add ${partner} to add it.)`,
+      })
+    }
+  }
+
+  return notices
 }
 
 function collectRetiredGov(target: string): RetiredSurface[] {