@erclx/canon 5.61.0 → 5.63.0

package/src/commands/tooling.ts

@@ -11,6 +11,7 @@ import {
 } from '@/tooling/inject'
 import { buildStackSummaries, describeStack } from '@/tooling/list'
 import {
+  configFiles,
   isStackExcluded,
   listStacks,
   loadManifest,
@@ -23,6 +24,16 @@ import {
   renderStackSections,
   resolveReference,
 } from '@/tooling/read'
+import { resolveRecorded } from '@/sync/check'
+import { readStamp, stampedChain, writeDispositions } from '@/sync/stamp'
+import {
+  customize,
+  decline,
+  lift,
+  normalizeGoldenPath,
+  readDispositions,
+  resolveGolden,
+} from '@/tooling/disposition'
 import { scan, type ScanResult } from '@/tooling/scan'
 import { recordToolingChain } from '@/tooling/stamp'
 import { subfolderPath } from '@/tooling/subfolder'
@@ -44,14 +55,26 @@ interface SyncOptions {
   readonly skip?: string
   readonly check?: boolean
   readonly write?: boolean
+  readonly replace?: readonly string[]
   readonly diff?: { readonly json: boolean }
 }
 
+function collect(value: string, previous: readonly string[]): string[] {
+  return [...previous, value]
+}
+
 interface DiffOptions {
   readonly skip?: string
   readonly json?: boolean
 }
 
+interface DispositionOptions {
+  readonly reason?: string
+  readonly json?: boolean
+}
+
+type DispositionAction = 'decline' | 'customize' | 'lift'
+
 interface InjectOptions {
   readonly configs?: boolean
   readonly seeds?: boolean
@@ -94,6 +117,12 @@ export function register(program: Command): void {
       'Report what would change and write nothing, always exiting 0. Prefer `canon tooling diff`',
     )
     .option('--write', 'Apply every change without prompting')
+    .option(
+      '--replace <path>',
+      'Replace a held config with the golden copy (repeatable)',
+      collect,
+      [],
+    )
     .addHelpText(
       'after',
       [
@@ -102,6 +131,7 @@ export function register(program: Command): void {
         '  canon tooling sync base',
         '  canon tooling sync base --check',
         '  canon tooling sync base --write',
+        '  canon tooling sync base --write --replace .oxfmtrc.json',
         '  canon tooling sync vite-react web --skip base',
         '',
         'A target below its git root syncs as a subfolder. It withholds',
@@ -115,8 +145,15 @@ export function register(program: Command): void {
         'what `canon sync --check --exit-code` spells with a flag. Pass --check',
         'to report the same list and always exit 0.',
         '',
-        '--write replaces every golden config that differs from the stack.',
+        '--write replaces a golden config only when canon changed it and the',
+        'project did not, which the hash the last write recorded tells apart.',
+        'A config the project edited, or one written before hashes were',
+        'recorded, is held and listed. Name it with --replace to take the',
+        'golden copy, or run `canon tooling customize <path>` to keep yours.',
+        'A config no recorded stack ships is a first install and never held,',
+        'so a fresh scaffold takes every golden config of a stack new to it.',
         'Seeds are copy-once, so a seed the target already holds is left alone.',
+        'A declined or customized path is never written.',
         '',
         'Exit codes:',
         '  0  synced, up to date, cancelled, or run with --check',
@@ -167,6 +204,88 @@ export function register(program: Command): void {
       },
     )
 
+  const dispositionHelp = [
+    '',
+    '<path> is relative to the target, as `canon tooling diff` lists it, and',
+    'resolves against the chain the last sync recorded. These verbs are the',
+    'only writers of the record, kept under domains.tooling.dispositions in',
+    'canon/config/config.json. Nothing here deletes or edits the file itself.',
+    '',
+    'Exit codes:',
+    '  0  recorded',
+    '  1  refused: no-chain, bad-path, not-golden, already-held,',
+    '     seed-not-customizable, missing-file, not-held, or toolkit-root',
+    '',
+  ]
+
+  tooling
+    .command('decline')
+    .description('Keep sync and inject from ever writing one golden file')
+    .argument('<path>', 'Golden file path, relative to the target')
+    .argument('[target]', 'Target directory', '.')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--reason <text>', 'Record why the project declined it')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        ...dispositionHelp,
+        'Examples:',
+        '  canon tooling decline .github/workflows/readme-screenshot.yml',
+        '  canon tooling decline .oxlintrc.json web --reason "lint runs in CI only"',
+        '',
+      ].join('\n'),
+    )
+    .action(async (path: string, target: string, opts: DispositionOptions) => {
+      process.exitCode = await runDisposition('decline', path, target, opts)
+    })
+
+  tooling
+    .command('customize')
+    .description(
+      'Keep the project copy of one golden config through every write',
+    )
+    .argument('<path>', 'Golden config path, relative to the target')
+    .argument('[target]', 'Target directory', '.')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        ...dispositionHelp,
+        'The golden hash is recorded, so `canon tooling diff` exits 1 once the',
+        'stack ships a different copy. A seed cannot be customized, since sync',
+        'never overwrites one.',
+        '',
+        'Examples:',
+        '  canon tooling customize e2e/screenshot.ts',
+        '',
+      ].join('\n'),
+    )
+    .action(async (path: string, target: string, opts: DispositionOptions) => {
+      process.exitCode = await runDisposition('customize', path, target, opts)
+    })
+
+  tooling
+    .command('lift')
+    .description('Hand a declined or customized file back to sync')
+    .argument('<path>', 'Golden file path, relative to the target')
+    .argument('[target]', 'Target directory', '.')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        ...dispositionHelp,
+        'Examples:',
+        '  canon tooling lift .github/workflows/readme-screenshot.yml',
+        '',
+      ].join('\n'),
+    )
+    .action(async (path: string, target: string, opts: DispositionOptions) => {
+      process.exitCode = await runDisposition('lift', path, target, opts)
+    })
+
   tooling
     .command('inject')
     .description('Apply one stack to a target without scanning or prompting')
@@ -380,7 +499,7 @@ async function runSync(
 
   if (opts.check === true && opts.write === true) {
     return refuse(
-      opts,
+      opts.diff?.json,
       'conflicting-flags',
       'Pass --check or --write, not both.',
     )
@@ -388,22 +507,37 @@ async function runSync(
 
   const selected = stack ?? (await promptForStack())
   if (selected === undefined) {
-    return refuse(opts, 'no-stacks', 'No tooling stacks found')
+    return refuse(opts.diff?.json, 'no-stacks', 'No tooling stacks found')
   }
 
   if (isStackExcluded(selected)) {
     return refuse(
-      opts,
+      opts.diff?.json,
       'excluded-stack',
       'Claude is managed by `canon claude`, not `canon tooling`. Run `canon claude sync` instead.',
     )
   }
 
   const prepared = prepare(selected, target, opts.skip)
-  if (!prepared.ok) return refuse(opts, prepared.reason, prepared.error)
+  if (!prepared.ok)
+    return refuse(opts.diff?.json, prepared.reason, prepared.error)
 
   const result = scan(prepared.chain, prepared.target)
 
+  const replace = (opts.replace ?? []).map(
+    (input) => normalizeGoldenPath(input) ?? input,
+  )
+  const unknown = replace.filter(
+    (rel) => !result.configs.some((entry) => entry.rel === rel),
+  )
+  if (unknown.length > 0) {
+    return refuse(
+      opts.diff?.json,
+      'unknown-replace',
+      `--replace names no config this chain writes: ${unknown.join(', ')}`,
+    )
+  }
+
   report(result, prepared.target)
 
   if (opts.diff !== undefined) {
@@ -442,15 +576,16 @@ async function runSync(
     return decision === 'unauthorized' ? 1 : 0
   }
 
+  const held = heldConfigs(result, replace, prepared.chain, prepared.target)
   if (result.configs.some((entry) => entry.state !== 'matching')) {
-    await injectConfigs(prepared.chain, prepared.target)
+    await injectConfigs(prepared.chain, prepared.target, new Set(held))
   }
 
   await injectSeeds(prepared.chain, prepared.target)
   const manifest = await injectManifest(prepared.chain, prepared.target)
   if (!manifest.ok) {
     return refuse(
-      opts,
+      false,
       manifest.reason,
       `${manifest.message}\nConfigs and seeds above were written. Scripts, gitignore entries, and the stamp were not, so the next sync retries.`,
     )
@@ -458,24 +593,170 @@ async function runSync(
 
   await stampChain(prepared.chain, prepared.target)
 
+  if (held.length > 0) {
+    reportHeld(held, selected, target, opts.skip)
+  }
+
   outroSuccess('Tooling sync complete')
   return 0
 }
 
+/**
+ * A drifted config the project edited, or one no write recorded, is held
+ * rather than replaced, since a write naming a stack is not consent to lose an
+ * edit inside it. Only a path `--replace` names is taken over.
+ *
+ * A path no recorded stack ships is a first install of that stack, so it is
+ * never held. `canon init` records `base` before a framework stack syncs over
+ * a fresh scaffold, whose own copies of that stack's configs came from the
+ * scaffold rather than from a project edit.
+ */
+function heldConfigs(
+  result: ScanResult,
+  replace: readonly string[],
+  chain: readonly Manifest[],
+  target: string,
+): string[] {
+  const recorded = new Set(stampedChain(readStamp(target), 'tooling'))
+  const installed = new Set(
+    chain
+      .filter((manifest) => recorded.has(manifest.name))
+      .flatMap(configFiles),
+  )
+
+  return result.configs
+    .filter(
+      (entry) =>
+        entry.state === 'drifted' &&
+        entry.cause !== 'stale' &&
+        installed.has(entry.rel) &&
+        !replace.includes(entry.rel),
+    )
+    .map((entry) => entry.rel)
+}
+
+/**
+ * Names every held path in one copyable command, so taking the first run's
+ * unattributed holds costs one paste rather than one flag per path typed.
+ */
+function reportHeld(
+  held: readonly string[],
+  stack: string,
+  target: string,
+  skip: string | undefined,
+): void {
+  logStep('Held')
+  for (const rel of held) logWarn(rel)
+  logInfo(
+    'The project changed these, or no earlier write recorded them, so --write left them as they are. Keep one with `canon tooling customize <path>`, or take the golden copies with:',
+  )
+  const command = [
+    'canon tooling sync',
+    stack,
+    target,
+    ...(skip === undefined ? [] : ['--skip', skip]),
+    '--write',
+    ...held.flatMap((rel) => ['--replace', rel]),
+  ]
+  logInfo(command.join(' '))
+}
+
 /**
  * A diff caller branches on the record rather than the exit, since a shell
  * wrapper can flatten the status. Every refusal therefore answers with a reason
  * on stdout under `--json`, beside the exit 1 that keeps a gate failing.
  */
-function refuse(opts: SyncOptions, reason: string, message: string): number {
+function refuse(
+  json: boolean | undefined,
+  reason: string,
+  message: string,
+): number {
   logWarn(message)
-  if (opts.diff?.json) {
+  if (json === true) {
     process.stdout.write(`${JSON.stringify({ ok: false, reason, message })}\n`)
   }
   outro()
   return 1
 }
 
+/**
+ * Resolves the path against the chain the last sync recorded rather than a
+ * stack argument, since a disposition belongs to the path whichever stack
+ * ships it. An unstamped target has no chain to resolve against and refuses.
+ */
+async function runDisposition(
+  action: DispositionAction,
+  input: string,
+  target: string,
+  opts: DispositionOptions,
+): Promise<number> {
+  intro(`canon tooling ${action}`)
+
+  const resolved = resolve(target)
+  if (resolved === PROJECT_ROOT) {
+    return refuse(
+      opts.json,
+      'toolkit-root',
+      'Cannot run against toolkit root. Files here are the source of truth.',
+    )
+  }
+
+  const rel = normalizeGoldenPath(input)
+  if (rel === undefined) {
+    return refuse(
+      opts.json,
+      'bad-path',
+      `${input} is not a path inside the target. Pass it relative to the target.`,
+    )
+  }
+
+  const chain = resolveRecorded(
+    PROJECT_ROOT,
+    stampedChain(readStamp(resolved), 'tooling'),
+  )
+  if (chain.length === 0) {
+    return refuse(
+      opts.json,
+      'no-chain',
+      `No tooling chain is recorded in ${resolved}. Run \`canon tooling sync <stack>\` there first.`,
+    )
+  }
+
+  const current = readDispositions(resolved)
+  const golden = resolveGolden(chain, rel)
+  const transition =
+    action === 'decline'
+      ? decline(current, golden, opts.reason)
+      : action === 'customize'
+        ? customize(current, golden, existsSync(join(resolved, rel)))
+        : lift(current, rel)
+
+  if (!transition.ok) {
+    return refuse(opts.json, transition.reason, transition.message)
+  }
+
+  await writeDispositions(
+    resolved,
+    { domain: 'tooling', toolkitRoot: PROJECT_ROOT },
+    transition.dispositions,
+    new Date(),
+  )
+
+  const entry = transition.dispositions[rel]
+  if (opts.json === true) {
+    process.stdout.write(
+      `${JSON.stringify({ ok: true, action, path: rel, ...(entry === undefined ? {} : { entry }) })}\n`,
+    )
+  }
+
+  outroSuccess(
+    entry === undefined
+      ? `Lifted ${rel}. The next sync writes it again.`
+      : `Recorded ${rel} as ${entry.disposition}. Sync and inject skip it.`,
+  )
+  return 0
+}
+
 type WriteMode = 'apply' | 'prompt' | 'report' | 'unauthorized'
 
 type ApplyDecision = 'apply' | 'cancelled' | 'reported' | 'unauthorized'
@@ -629,13 +910,18 @@ function report(result: ScanResult, target: string): void {
     if (entry.state === 'matching') logInfo(entry.rel)
   }
   for (const entry of result.configs) {
-    if (entry.state === 'drifted') logWarn(entry.rel)
+    if (entry.state === 'drifted') {
+      logWarn(
+        entry.cause === 'stale' ? entry.rel : `${entry.rel} (${entry.cause})`,
+      )
+    }
   }
   for (const entry of result.configs) {
     if (entry.state === 'new') logAdd(entry.rel)
   }
 
   if (result.withheld.length > 0) reportWithheld(result, target)
+  reportDispositions(result)
 
   logStep('Scanning seeds')
   for (const entry of result.seeds) {
@@ -681,6 +967,35 @@ function reportWithheld(result: ScanResult, target: string): void {
   logInfo(`working-directory: ${subfolderPath(target) ?? '.'}`)
 }
 
+function reportDispositions(result: ScanResult): void {
+  const declined = result.dispositions.filter(
+    (entry) => entry.disposition === 'declined',
+  )
+  const customized = result.dispositions.filter(
+    (entry) => entry.disposition === 'customized',
+  )
+
+  if (declined.length > 0) {
+    logStep('Declined')
+    for (const entry of declined) {
+      logInfo(entry.present ? `${entry.rel} (still here)` : entry.rel)
+    }
+  }
+
+  if (customized.length > 0) {
+    logStep('Customized')
+    for (const entry of customized) {
+      if (entry.moved === true) {
+        logWarn(
+          `${entry.rel}: the ${entry.stack} golden changed since it was customized. Run \`canon tooling lift ${entry.rel}\` to take the new copy on the next write, or lift and customize again to keep this one.`,
+        )
+      } else {
+        logInfo(entry.rel)
+      }
+    }
+  }
+}
+
 function reportPackage(result: ScanResult): void {
   if (result.scripts.length > 0) {
     logStep('Scanning scripts')
@@ -699,6 +1014,9 @@ function reportPackage(result: ScanResult): void {
     logStep('Scanning dependencies')
     for (const entry of result.deps) {
       if (entry.state === 'present') logInfo(entry.name)
+      if (entry.state === 'ahead') {
+        logInfo(`${entry.name} ${entry.installed} (ahead of ${entry.spec})`)
+      }
     }
     for (const entry of result.deps) {
       if (entry.state === 'missing') logAdd(entry.spec)
@@ -717,6 +1035,10 @@ function summarize(result: ScanResult): string {
     result.configs.filter((entry) => entry.state !== 'matching').length,
     'configs',
   )
+  add(
+    result.dispositions.filter((entry) => entry.moved === true).length,
+    'moved customized',
+  )
   add(result.seeds.filter((entry) => entry.state === 'missing').length, 'seeds')
   add(
     result.scripts.filter((entry) => entry.state !== 'matching').length,

package/src/gate/measures.ts

@@ -12,6 +12,7 @@ import {
   auditSkills,
   LEDGER_SKILLS,
   PRACTICE_LEDGER,
+  SKILL_LEDGERS,
   PRACTICE_SKILLS,
   SHIPPED_CORPUS,
 } from '@/claude/skills-audit'
@@ -384,7 +385,7 @@ export const skillProvenance: Measure = async (ctx) => {
 
 /**
  * Every listed practice skill against the closing sections, and every skill on
- * the wider ledger list against the ledger, both of which
+ * the wider ledger list against a ledger that cites something, both of which
  * `claude/skills/create-skill/references/skill-practice.md` requires.
  *
  * Read in-process for the reason `skillProvenance` is, so the verb keeps its
@@ -407,14 +408,14 @@ export const skillPracticeShape: Measure = async (ctx) => {
       .join(', ')
     return {
       emissions: [],
-      failure: `${plural(found.length, 'practice shape finding')}: ${where}. Add the closing H2 exactly as named to a practice skill, or the ledger at ${PRACTICE_LEDGER} to any skill on the ledger list.`,
+      failure: `${plural(found.length, 'practice shape finding')}: ${where}. Add the closing H2 exactly as named to a practice skill, or the ledger at ${PRACTICE_LEDGER} to any skill on the ledger list, citing one linked source or one House choice row. A reference on the per-bullet list takes one ledger row per bullet under the same H2 at ${SKILL_LEDGERS}.`,
     }
   }
 
   return {
     emissions: [
       info(
-        `${plural(PRACTICE_SKILLS.length, 'practice skill')} carry every closing section, and ${plural(LEDGER_SKILLS.length, 'listed skill')} carry a ledger`,
+        `${plural(PRACTICE_SKILLS.length, 'practice skill')} carry every closing section, and ${plural(LEDGER_SKILLS.length, 'listed skill')} carry a ledger citing a source`,
       ),
     ],
   }

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[] {

package/src/gov/audit.ts

@@ -294,7 +294,12 @@ export function countLedgerRows(text: string): HeadingCount[] {
   return [...counts].map(([key, count]) => ({ heading: key, count }))
 }
 
-function compareLedger(
+/**
+ * Pairs bullets and ledger rows under each heading, naming every heading whose
+ * counts differ. The skill audit reads a practice skill's references through
+ * it, so a rule and a reference are held to one comparison.
+ */
+export function compareLedger(
   groups: readonly HeadingCount[],
   rows: readonly HeadingCount[],
 ): LedgerMismatch[] {

package/src/gov/splits.ts

@@ -0,0 +1,36 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** Held rule basename to the basenames its moved bullets now live in. */
+export type Splits = ReadonlyMap<string, readonly string[]>
+
+function splitsPath(root: string): string {
+  return join(root, 'governance', 'splits.toml')
+}
+
+/**
+ * Reads the shipped split ledger. A toolkit without one declares no splits,
+ * which leaves every sync silent about partners, the way it was before the
+ * ledger existed.
+ */
+export function loadSplits(root: string): Splits {
+  const path = splitsPath(root)
+  if (!existsSync(path)) return new Map()
+
+  const parsed = Bun.TOML.parse(readFileSync(path, 'utf8')) as Record<
+    string,
+    unknown
+  >
+  const table = parsed.split
+  if (typeof table !== 'object' || table === null) return new Map()
+
+  const entries: [string, string[]][] = []
+  for (const [held, value] of Object.entries(table)) {
+    if (!Array.isArray(value)) continue
+    const partners = value.filter(
+      (partner): partner is string => typeof partner === 'string',
+    )
+    if (partners.length > 0) entries.push([held, partners])
+  }
+  return new Map(entries)
+}

package/src/inventory/subjects.ts

@@ -27,7 +27,7 @@ export interface Subject {
 
 /**
  * Reports what each element changes about itself when it takes focus, which is
- * the reading `governance/rules/ui/keyboard.md` states three rules against and
+ * the reading the `ui-craft` keyboard reference states three rules against and
  * nothing measures.
  *
  * The difference between rest and focus is the treatment, rather than the