basalt-ui 1.25.0 → 1.27.0

package/src/cli/index.ts

@@ -5,10 +5,12 @@
  * BasaltConfig, builds a GuardConfig, walks the source roots, calls `checkSource` per file,
  * collects Finding[], groups/reports findings, and returns an exit code.
  *
- * `checkCoverage` asserts 8 invariants: guardKinds ⊆ GUARD_RULES, rule files on disk,
- * skill union ⊆ plugin.json, subpath-export-coverage, exports→SURFACES reverse, globs
- * required for non-empty forbiddenImports, headless Mantine-ban completeness, and
- * optionalPeers peerDependencies/peerDependenciesMeta presence.
+ * `checkCoverage` asserts 11 invariants: guardKinds ⊆ GUARD_RULES, rule files on disk, skill files
+ * on disk, subpath-export-coverage, exports→SURFACES reverse, globs required for non-empty
+ * forbiddenImports, headless Mantine-ban completeness, optionalPeers
+ * peerDependencies/peerDependenciesMeta presence, every plugin rule on exactly one surface, every
+ * guard kind on at least one, and the agent-layer line budgets. See `checkCoverage`'s own JSDoc for
+ * what each one buys.
  *
  * `init` / `sync` scaffold and reconcile the framework's *agentic* surface into a consumer repo:
  * Claude Code rules + skills, a managed CLAUDE.md block, a DESIGN.md seed, and the toolchain
@@ -26,6 +28,7 @@ import {
   mkdirSync,
   readdirSync,
   readFileSync,
+  rmdirSync,
   statSync,
   unlinkSync,
   writeFileSync,
@@ -47,8 +50,14 @@ import {
 } from '../guard'
 import type { Finding, GuardConfig, GuardKind, GuardSeverity } from '../guard'
 import { evaluateGuardHook } from '../guard/guard-hook'
-import { RULE_NAMES, SKILL_NAMES, SURFACES, TOKEN_LAYER_BOUNDARY_SURFACES } from '../surfaces'
-import type { DoctrineSpec, SurfaceSpec } from '../surfaces'
+import {
+  PLUGIN_RULE_ID_LIST,
+  RULE_NAMES,
+  SKILL_NAMES,
+  SURFACES,
+  TOKEN_LAYER_BOUNDARY_SURFACES,
+} from '../surfaces'
+import type { DoctrineSpec, RuleName, SurfaceSpec } from '../surfaces'
 import { buildPaletteCss, deriveSpacing } from '../tokens'
 
 /** Shape of the optional `"basalt"` key in a consumer's package.json. */
@@ -1838,6 +1847,113 @@ function migrateLegacyOxfmt(cwd: string, pkgRoot: string, manifest: Manifest): v
   if (shipped !== null && onDisk === shipped) unlinkSync(legacyAbs)
 }
 
+/**
+ * The two managed NAMESPACES whose membership is derived, not fixed: `RULE_NAMES` and `SKILL_NAMES`
+ * decide which files `managedFiles()` places under them, so a rule or skill that is RETIRED
+ * upstream leaves a file behind in every consumer that ever synced it — and Claude keeps loading it.
+ *
+ * Scoped to these two patterns on purpose, and never applied to the manifest wholesale: several
+ * managed/seed entries are legitimately absent from `managedFiles()` for a run (`lefthook.yml` and
+ * `check.yml` when the package is not the repo root, `src/query-client.ts` when it was relocated,
+ * the scaffolds without their peers). Deleting a dest just because this run did not place it would
+ * remove a consumer's CI workflow on a monorepo.
+ */
+const RETIREABLE_DEST_PATTERNS: readonly RegExp[] = [
+  /^\.claude\/rules\/basalt-[a-z0-9-]+\.md$/,
+  /^\.claude\/skills\/basalt-[a-z0-9-]+\/SKILL\.md$/,
+]
+
+/** A tracked dest inside a derived namespace that this basalt version no longer ships. */
+export function retiredManagedDests(
+  manifest: Manifest,
+  files: readonly ManagedFile[],
+): readonly string[] {
+  const shipped = new Set(files.map((f) => f.dest))
+  return Object.keys(manifest.files)
+    .filter((dest) => !shipped.has(dest))
+    .filter((dest) => RETIREABLE_DEST_PATTERNS.some((re) => re.test(dest)))
+    .toSorted()
+}
+
+/** Outcome of one prune pass — `removed` was deleted, `drifted` was locally edited and left alone. */
+type PruneResult = { removed: string[]; drifted: string[] }
+
+/**
+ * Report a prune pass. Always names the files: a doctrine file DISAPPEARING from a consumer's
+ * `.claude/` is exactly the class of change the sync diff exists to be reviewed, and `9 removed`
+ * with no names is what made the kept-files line a false green before 1.23.0.
+ */
+function reportPrune(pruned: PruneResult): void {
+  if (pruned.removed.length > 0) {
+    console.log(
+      `\nRetired by this basalt-ui version (deleted — they no longer ship):\n` +
+        pruned.removed.map((dest) => `  · ${dest}`).join('\n'),
+    )
+  }
+  if (pruned.drifted.length === 0) return
+  console.log(
+    `\nRetired but locally edited, so left in place — your agent still loads them. Delete them, ` +
+      'or run `basalt-ui sync --force`:\n' +
+      pruned.drifted.map((dest) => `  · ${dest}`).join('\n'),
+  )
+}
+
+/**
+ * Delete the managed rule/skill files this basalt version retired, and drop their manifest entries.
+ *
+ * The 13→6 rule merge (`docs/CONTROLS-SPEC.md` §7) is the case this exists for: nine
+ * `.claude/rules/basalt-*.md` files stopped shipping in one minor, and without this a consumer's
+ * agent would go on reading `basalt-router.md`'s superseded placement doctrine forever, with
+ * `sync --check` reporting green because nothing in the ledger asks about a dest the run no longer
+ * places.
+ *
+ * Same three-way discipline as every other managed unit, so a consumer edit is never discarded
+ * silently: an untouched file (matching its recorded hash, raw or normalized) is deleted and its
+ * entry dropped; a locally-edited one is LEFT in place, reported, and keeps its entry so
+ * `sync --check` stays red and `--force` can still finish the job. `dryRun` is `--check`.
+ */
+function pruneRetiredManagedFiles(
+  cwd: string,
+  manifest: Manifest,
+  files: readonly ManagedFile[],
+  opts: { dryRun?: boolean; force?: boolean } = {},
+): PruneResult {
+  const result: PruneResult = { removed: [], drifted: [] }
+  for (const dest of retiredManagedDests(manifest, files)) {
+    const abs = resolve(cwd, dest)
+    const current = readIfExists(abs)
+    const recorded = manifest.files[dest]
+    const untouched =
+      current === null ||
+      sha256(current) === recorded ||
+      sha256(normalizeForLedger(current)) === recorded
+    if (!untouched && opts.force !== true) {
+      result.drifted.push(dest)
+      continue
+    }
+    result.removed.push(dest)
+    if (opts.dryRun === true) continue
+    delete manifest.files[dest]
+    if (current !== null) unlinkSync(abs)
+    removeEmptyParentDir(abs)
+  }
+  return result
+}
+
+/**
+ * Remove a now-empty `.claude/skills/basalt-x/` directory after its `SKILL.md` was pruned. Silent by
+ * design — a leftover empty directory is cosmetic, and a consumer file sitting beside the skill is a
+ * reason to keep it, not an error to report.
+ */
+function removeEmptyParentDir(fileAbs: string): void {
+  const dir = dirname(fileAbs)
+  try {
+    if (readdirSync(dir).length === 0) rmdirSync(dir)
+  } catch {
+    /* not empty, not readable, or already gone — nothing to clean up */
+  }
+}
+
 /** The frozen `> Managed by basalt-ui (1.9.0).` opener every pre-fix DESIGN.md seed carries. */
 const DESIGN_VERSION_LINE = /^(> Managed by basalt-ui) \(\d+\.\d+\.\d+\)\./m
 
@@ -2506,6 +2622,11 @@ export function init(cwd: string = process.cwd(), scaffoldFlags: ScaffoldFlags =
     writtenFiles.push(file.dest)
   }
 
+  // A re-`init` over an existing install reconciles the derived namespaces too — otherwise the only
+  // route out of a retired rule file is `sync`, and `init` is what a consumer reaches for after an
+  // upgrade that changed the doctrine set.
+  const pruned = pruneRetiredManagedFiles(cwd, manifest, files)
+
   const mergeLint: MergeLintResult | null =
     scaffoldFlags.mergeLint === true ? mergeOxlintExtends(cwd, ctx.vars.OXLINT_PRESET_PATH) : null
 
@@ -2516,6 +2637,7 @@ export function init(cwd: string = process.cwd(), scaffoldFlags: ScaffoldFlags =
   console.log(
     `basalt-ui init: ${writtenFiles.length} written, ${keptFiles.length} kept, manifest at ${MANIFEST_PATH}`,
   )
+  reportPrune(pruned)
   if (missingSources.length > 0) {
     console.log(
       `basalt-ui init: ${missingSources.length} shipped asset(s) not present, skipped: ${missingSources.join(', ')}`,
@@ -2825,6 +2947,16 @@ export function sync(opts: SyncOptions = {}, invocationCwd: string = process.cwd
     else created++
   }
 
+  // Retired rules/skills: the derived namespaces (RULE_NAMES / SKILL_NAMES) are the only managed
+  // sets whose MEMBERSHIP moves between versions, so this is where an upstream deletion reaches a
+  // consumer. Counted into `staleForCheck` so `sync --check` is red until it is applied — a rule
+  // file basalt stopped shipping is drift, and the agent goes on reading it otherwise.
+  const pruned = pruneRetiredManagedFiles(cwd, manifest, files, {
+    dryRun: opts.check === true,
+    force: opts.force === true,
+  })
+  staleForCheck += pruned.removed.length + pruned.drifted.length
+
   // Placement notices — informational, never affect the exit code (a skipped tooling seed or a
   // relocated scaffold is a legitimate consumer choice, not a sync failure).
   if (!placement.isPackageRepoRoot) {
@@ -2881,6 +3013,13 @@ export function sync(opts: SyncOptions = {}, invocationCwd: string = process.cwd
       console.error('basalt-ui sync --check: locally-drifted managed files:')
       for (const l of driftLines) console.error(l)
     }
+    const retired = [...pruned.removed, ...pruned.drifted]
+    if (retired.length > 0) {
+      console.error(
+        `basalt-ui sync --check: ${retired.length} retired rule/skill file(s) still present: ` +
+          `${retired.join(', ')} — run \`basalt-ui sync\`.`,
+      )
+    }
     if (staleForCheck > 0) {
       console.error(`basalt-ui sync --check: ${staleForCheck} managed file(s) out of date.`)
       return 1
@@ -2895,8 +3034,9 @@ export function sync(opts: SyncOptions = {}, invocationCwd: string = process.cwd
 
   console.log(
     `basalt-ui sync: ${updated} updated, ${created} created, ${recreated} recreated, ` +
-      `${skippedDrift} skipped (drift).`,
+      `${skippedDrift} skipped (drift), ${pruned.removed.length} retired.`,
   )
+  reportPrune(pruned)
   if (driftLines.length > 0) {
     console.log('Locally-edited files were skipped (run with --force to overwrite):')
     for (const l of driftLines) console.log(l)
@@ -2910,14 +3050,160 @@ export function sync(opts: SyncOptions = {}, invocationCwd: string = process.cwd
 }
 
 // ──────────────────────────────────────────────────────────────────────────────
-// check-coverage — 8-assertion coverage gate
+// coverage headers — the generated `<!-- basalt:coverage -->` block per rule file
+// ──────────────────────────────────────────────────────────────────────────────
+
+/** The block's delimiters. Both are HTML comments, so the block renders as nothing in a viewer. */
+export const COVERAGE_BLOCK_OPEN = '<!-- basalt:coverage -->'
+export const COVERAGE_BLOCK_CLOSE = '<!-- /basalt:coverage -->'
+
+const COVERAGE_BLOCK_RE = /<!-- basalt:coverage -->[\s\S]*?<!-- \/basalt:coverage -->/
+
+/**
+ * What actually enforces one rule file's doctrine, as the file itself should state it.
+ *
+ * Derived from SURFACES — the union over every doctrine surface carrying that `rule`, because
+ * `rule` is many-to-one (`data` covers `./data`, `./data/table`, `./data/virtual`; `mantine` covers
+ * `.` and `./connectivity`). Naming only one surface's coverage would understate the rule.
+ */
+export function coverageFor(rule: RuleName): {
+  guardKinds: string[]
+  pluginRules: string[]
+  advisoryLaws: string[]
+} {
+  const specs = (Object.values(SURFACES) as SurfaceSpec[]).filter(
+    (s): s is DoctrineSpec => s.kind === 'doctrine' && s.rule === rule,
+  )
+  const unique = (values: readonly string[]): string[] => [...new Set(values)].toSorted()
+  return {
+    guardKinds: unique(specs.flatMap((s) => [...s.guardKinds])),
+    pluginRules: unique(specs.flatMap((s) => [...s.pluginRules])),
+    // NOT sorted, and not deduped across surfaces by content: an advisory law is a sentence, and
+    // its order is the order the spec argues it in.
+    advisoryLaws: specs.flatMap((s) => [...(s.advisoryLaws ?? [])]),
+  }
+}
+
+/**
+ * The generated block for one rule, verbatim — HTML comments only, one claim per line so a diff
+ * points at the claim that changed rather than at a reflowed paragraph.
+ *
+ * `not guarded` is printed even when empty, and that is the point: a rule file whose block says
+ * `not guarded: —` is claiming full coverage, which is a claim someone can check. A block that
+ * simply omitted the section would read as "nothing to declare" whether or not anyone had looked
+ * (D8 — see docs/CONTROLS-SPEC.md §6 "Honest coverage").
+ */
+export function coverageBlock(rule: RuleName): string {
+  const { guardKinds, pluginRules, advisoryLaws } = coverageFor(rule)
+  const backedBy = [
+    guardKinds.length > 0 ? `guard kinds — ${guardKinds.join(', ')}` : 'guard kinds — none',
+    pluginRules.length > 0
+      ? `oxlint rules — ${pluginRules.map((id) => `basalt/${id}`).join(', ')}`
+      : 'oxlint rules — none',
+  ].join(' · ')
+  const lines = [
+    COVERAGE_BLOCK_OPEN,
+    '<!-- GENERATED from src/surfaces.ts — `basalt-ui check-coverage --write`. Do not hand-edit. -->',
+    `<!-- backed by: ${backedBy} -->`,
+  ]
+  if (advisoryLaws.length === 0) lines.push('<!-- not guarded: — -->')
+  else for (const law of advisoryLaws) lines.push(`<!-- not guarded: ${law} -->`)
+  lines.push(COVERAGE_BLOCK_CLOSE)
+  return lines.join('\n')
+}
+
+/** The block a rule file currently carries, or null when it has none yet. */
+export function readCoverageBlock(text: string): string | null {
+  return COVERAGE_BLOCK_RE.exec(text)?.[0] ?? null
+}
+
+/**
+ * `text` with `block` in it — replacing the existing block, or inserted directly below the YAML
+ * frontmatter (the rule files' `paths:` header is load-bearing and must stay first).
+ */
+export function applyCoverageBlock(text: string, block: string): string {
+  if (COVERAGE_BLOCK_RE.test(text)) return text.replace(COVERAGE_BLOCK_RE, block)
+  const frontmatter = /^---\n[\s\S]*?\n---\n/.exec(text)
+  if (frontmatter === null) return `${block}\n\n${text}`
+  const end = frontmatter[0].length
+  return `${text.slice(0, end)}\n${block}\n${text.slice(end)}`
+}
+
+/**
+ * Reconcile every rule file's coverage block against SURFACES.
+ *
+ * `'write'` refreshes them; `'check'` is the CI gate. A rule file with NO block yet is REPORTED,
+ * never failed — the blocks are inserted by the agent-layer wave that rewrites those files, and a
+ * gate that failed before they exist would have to be landed disabled, which is how a gate stays
+ * disabled. A block that exists and DISAGREES is a hard failure: that is drift, and drift in a
+ * coverage claim is the defect the block was added for.
+ */
+export function reconcileCoverageBlocks(
+  pkgRoot: string,
+  mode: 'write' | 'check',
+): { failures: string[]; notes: string[] } {
+  const failures: string[] = []
+  const notes: string[] = []
+  for (const rule of RULE_NAMES) {
+    const rel = `agent/rules/basalt-${rule}.md`
+    const path = resolve(pkgRoot, rel)
+    if (!existsSync(path)) continue // assertion 2 already reports a missing rule file
+    const text = readFileSync(path, 'utf8')
+    const current = readCoverageBlock(text)
+    const expected = coverageBlock(rule)
+    if (mode === 'check') {
+      if (current === null) notes.push(`${rel}: no <!-- basalt:coverage --> block yet`)
+      else if (current !== expected) {
+        failures.push(
+          `${rel}: coverage block is out of sync with SURFACES (check-coverage --write)`,
+        )
+      }
+      continue
+    }
+    if (current === expected) {
+      notes.push(`${rel}: unchanged`)
+      continue
+    }
+    writeFileSync(path, applyCoverageBlock(text, expected), 'utf8')
+    notes.push(`${rel}: ${current === null ? 'block inserted' : 'block updated'}`)
+  }
+  return { failures, notes }
+}
+
+// ──────────────────────────────────────────────────────────────────────────────
+// check-coverage — 10-assertion coverage gate
 // ──────────────────────────────────────────────────────────────────────────────
 
 /**
- * Assert the 8 SURFACES invariants against the live SURFACES + GUARD_RULES + plugin.json.
- * Returns 0 when all pass; 1 when any fail (console.error each failure).
+ * Per-file line budgets for the shipped agent layer (`docs/CONTROLS-SPEC.md` §7's target table).
  *
- * Eight assertions:
+ * A budget, not a guideline: seven `src/**`-scoped rules loaded ~2,000 lines on any source edit
+ * before the merge, and 55% of that text was doctrine nothing enforced. The numbers are the bar the
+ * spec argued, so they live beside the gate that reads them rather than in prose.
+ */
+const AGENT_LINE_BUDGETS: Readonly<Record<string, number>> = {
+  'agent/rules/basalt-tokens.md': 160,
+  'agent/rules/basalt-mantine.md': 180,
+  'agent/rules/basalt-charts.md': 140,
+  'agent/rules/basalt-state.md': 160,
+  'agent/rules/basalt-controls.md': 160,
+  'agent/rules/basalt-batteries.md': 220,
+  'agent/skills/basalt-app/SKILL.md': 100,
+  'agent/skills/basalt-design/SKILL.md': 100,
+  'agent/skills/basalt-charts/SKILL.md': 100,
+  'agent/templates/CLAUDE-block.md.tpl': 40,
+  'agent/templates/DESIGN.md.tpl': 45,
+}
+
+/** The whole-layer bar — a per-file budget alone can be satisfied by adding a seventh rule file. */
+const AGENT_RULE_TOTAL_BUDGET = 1050
+
+/**
+ * Assert the 11 invariants against the live SURFACES + GUARD_RULES + the shipped agent layer, and
+ * (with `--write` / `--check`) reconcile the generated `<!-- basalt:coverage -->` header of every
+ * rule file against SURFACES. Returns 0 when all pass; 1 when any fail (console.error each failure).
+ *
+ * Eleven assertions:
  *  1. Every doctrine spec's guardKinds ⊆ keyof GUARD_RULES.
  *  2. Every doctrine rule (deduped) maps to agent/rules/basalt-{rule}.md on disk.
  *  3. Every doctrine skill (deduped) maps to agent/skills/{skill}/SKILL.md on disk.
@@ -2931,14 +3217,29 @@ export function sync(opts: SyncOptions = {}, invocationCwd: string = process.cwd
  *     the assertion's own comment below for why); basalt's own CI does
  *     (`tests/surfaces-coverage.test.ts`).
  *  8. Every doctrine optionalPeers entry exists in peerDependencies AND peerDependenciesMeta.
+ *  9. Every registered oxlint plugin rule (PLUGIN_RULE_ID_LIST) maps to EXACTLY ONE surface's
+ *     `pluginRules` — so a new rule cannot ship homeless, and one rule cannot be counted twice as
+ *     coverage. Like assertion 7 this reads SURFACES only: whether the plugin really registers
+ *     those ids is asserted against the plugin itself in `configs/oxlint-plugin.test.ts`, which a
+ *     shipped CLI running from a consumer's node_modules cannot do.
+ * 10. Every shipped agent-layer file is inside its line budget, and the six rules are inside the
+ *     whole-layer total (`AGENT_LINE_BUDGETS` / `AGENT_RULE_TOTAL_BUDGET`).
+ * 11. Every `GUARD_RULES` kind appears on at least one doctrine surface — assertion 9's twin for
+ *     the text lane. Without it a kind could ship, be documented as a law in the spec, and be
+ *     omitted from every generated coverage header, which is how two wave-6 kinds left
+ *     `agent/rules/basalt-controls.md` printing "guard kinds — none" (D8). Unlike 9 this is
+ *     one-directional: a kind may legitimately appear on SEVERAL surfaces (`raw-hex` is on
+ *     `./charts` and `./tokens`), because a text scan is not partitioned by subpath the way a
+ *     plugin rule id is.
  *
  * Tooling surfaces are exempt from assertions 1–3 by the discriminant.
  * Synthetic #-keys participate in assertions 1 and 2 but feed assertion 3 only
  * via the deduped skill union (no independent per-#-surface skill row).
  */
-export function checkCoverage(): number {
+export function checkCoverage(flags: readonly string[] = []): number {
   const pkgRoot = packageRoot()
   const failures: string[] = []
+  const notes: string[] = []
 
   const allSpecs = Object.entries(SURFACES) as [string, SurfaceSpec][]
   const doctrineSpecs = (Object.values(SURFACES) as SurfaceSpec[]).filter(
@@ -3082,9 +3383,83 @@ export function checkCoverage(): number {
     }
   }
 
+  // ── Assertion 9: every plugin rule maps to exactly one surface ───────────────
+  // The plugin's own rules were the one half of the enforcement seam SURFACES did not model, so a
+  // generated coverage header could name a guard kind and stay silent about the AST rule doing the
+  // actual work (D8). Now every id has exactly one home, and "exactly" is both directions: an
+  // unmapped id is a rule no doc claims, a doubly-mapped one is coverage counted twice.
+  const surfacesPerPluginRule = new Map<string, string[]>()
+  for (const [key, spec] of allSpecs) {
+    if (spec.kind !== 'doctrine') continue
+    for (const id of spec.pluginRules) {
+      surfacesPerPluginRule.set(id, [...(surfacesPerPluginRule.get(id) ?? []), key])
+    }
+  }
+  for (const id of PLUGIN_RULE_ID_LIST) {
+    const owners = surfacesPerPluginRule.get(id) ?? []
+    if (owners.length === 1) continue
+    failures.push(
+      owners.length === 0
+        ? `Plugin rule 'basalt/${id}' maps to no surface — add it to one surface's pluginRules`
+        : `Plugin rule 'basalt/${id}' maps to ${owners.length} surfaces (${owners.join(', ')}) — exactly one`,
+    )
+  }
+
+  // ── Assertion 10: the agent layer stays inside its line budgets ─────────────
+  // The budgets ARE the doctrine (docs/CONTROLS-SPEC.md §7): thirteen rules reached 4,177 lines by
+  // growing a few lines at a time, each addition locally reasonable, and the only thing that
+  // notices is a number nobody is checking. A rule over budget is over budget in the commit that
+  // did it, not four minors later.
+  for (const [rel, budget] of Object.entries(AGENT_LINE_BUDGETS)) {
+    const abs = resolve(pkgRoot, rel)
+    if (!existsSync(abs)) continue // assertions 2/3 already report a missing rule or skill
+    const lines = readFileSync(abs, 'utf8').split('\n').length - 1
+    if (lines > budget) failures.push(`${rel}: ${lines} lines exceeds its ${budget}-line budget`)
+  }
+  const ruleTotal = RULE_NAMES.reduce((sum, rule) => {
+    const abs = resolve(pkgRoot, `agent/rules/basalt-${rule}.md`)
+    return existsSync(abs) ? sum + readFileSync(abs, 'utf8').split('\n').length - 1 : sum
+  }, 0)
+  if (ruleTotal > AGENT_RULE_TOTAL_BUDGET) {
+    failures.push(
+      `agent/rules/*.md: ${ruleTotal} lines total exceeds the ${AGENT_RULE_TOTAL_BUDGET}-line budget`,
+    )
+  }
+
+  // ── Assertion 11: every guard kind maps to at least one surface ──────────────
+  // The guard-kind twin of assertion 9. Assertion 1 already checks the other direction (no surface
+  // names a kind that does not exist); this one catches the kind nobody claims, whose coverage
+  // header therefore under-reports the lane that actually enforces it.
+  const surfacedGuardKinds = new Set<string>()
+  for (const spec of doctrineSpecs) {
+    for (const kind of spec.guardKinds) surfacedGuardKinds.add(kind)
+  }
+  for (const kind of Object.keys(GUARD_RULES)) {
+    if (surfacedGuardKinds.has(kind)) continue
+    failures.push(
+      `Guard kind '${kind}' maps to no surface — add it to one surface's guardKinds so the ` +
+        `generated coverage headers name it`,
+    )
+  }
+
+  // ── Coverage headers (--write / --check) ─────────────────────────────────────
+  const write = flags.includes('--write')
+  const check = flags.includes('--check')
+  if (write && check) {
+    failures.push('--write and --check are alternatives; pass one')
+  } else if (write || check) {
+    const result = reconcileCoverageBlocks(pkgRoot, write ? 'write' : 'check')
+    failures.push(...result.failures)
+    notes.push(...result.notes)
+  }
+
   // ── Report ──────────────────────────────────────────────────────────────────
+  for (const note of notes) {
+    console.log(`  ${note}`)
+  }
+
   if (failures.length === 0) {
-    console.log('✓ check-coverage: all 8 assertions pass.')
+    console.log('✓ check-coverage: all 11 assertions pass.')
     return 0
   }
 
@@ -4596,7 +4971,7 @@ const COMMAND_FLAGS: Record<string, readonly string[]> = {
   init: ['--with-router', '--with-query', '--merge-lint'],
   sync: ['--force', '--check', '--tokens-only', '--framework'],
   'check-theme': ['--audit-allows', '--tokens-only', '--framework'],
-  'check-coverage': [],
+  'check-coverage': ['--write', '--check'],
   info: ['--json'],
   doctor: ['--tokens-only', '--framework'],
   'guard-hook': [],
@@ -4647,7 +5022,8 @@ function unknownFlag(cmd: string, flags: readonly string[]): string | null {
 const USAGE =
   'Usage: basalt-ui <--version | init [--with-router] [--with-query] [--merge-lint] |\n' +
   '                  sync [--force] [--check] [--tokens-only|--framework] |\n' +
-  '                  check-theme [--audit-allows] | check-coverage | info [--json] |\n' +
+  '                  check-theme [--audit-allows] | check-coverage [--write|--check] |\n' +
+  '                  info [--json] |\n' +
   '                  doctor [--tokens-only|--framework] | guard-hook | tokens:css | fonts:css | help>\n\n' +
   'check-theme [--tokens-only|--framework] [--audit-allows]\n' +
   '  --audit-allows reports instead of scanning: every `theme-allow` annotation and every\n' +
@@ -4737,7 +5113,7 @@ export function run(argv: string[], cwd: string = process.cwd()): number | Promi
     case 'check-theme':
       return checkTheme(cwd, flags)
     case 'check-coverage':
-      return checkCoverage()
+      return checkCoverage(flags)
     case 'info':
       return info(flags)
     case 'doctor':

package/src/cli/init-sync.test.ts

@@ -4,8 +4,10 @@
  *  - the legacy `oxfmt.json` → `.oxfmtrc.json` manifest/file migration
  *  - the `basalt doctor` CLI-vs-installed version-mismatch warning
  *  - the `basalt init` first-run hint to run `check-theme` and tune per-rule config
+ *  - pruning managed rule/skill files a newer basalt-ui no longer ships
  */
 import { afterEach, beforeEach, describe, expect, it } from 'bun:test'
+import { createHash } from 'node:crypto'
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join, resolve } from 'node:path'
@@ -244,3 +246,98 @@ describe('seeds derive from basalt.roots', () => {
     expect(readFileSync(resolve(dir, 'DESIGN.md'), 'utf8')).toContain('custom/p.ts')
   })
 })
+
+/**
+ * Retired managed files — the 13→6 rule merge (`docs/CONTROLS-SPEC.md` §7) is the case this exists
+ * for: nine `.claude/rules/basalt-*.md` stopped shipping in one minor, and a consumer that never
+ * loses them goes on reading superseded doctrine with every gate green.
+ */
+describe('sync — retired rules and skills', () => {
+  const RETIRED_RULE = '.claude/rules/basalt-router.md'
+  const RETIRED_SKILL = '.claude/skills/basalt-legacy/SKILL.md'
+
+  /** Seed a real install, then plant a managed file this basalt version no longer ships. */
+  function plantRetired(dest: string, body: string, tracked = true): void {
+    writeFixture('package.json', JSON.stringify({ name: 'fixture' }))
+    capture(() => init(dir))
+    writeFixture(dest, body)
+    const manifestAbs = resolve(dir, MANIFEST_PATH)
+    const manifest = JSON.parse(readFileSync(manifestAbs, 'utf8')) as {
+      files: Record<string, string>
+    }
+    // The raw-hash ledger path — what a pre-normalization CLI recorded, and enough to prove
+    // "untouched since basalt wrote it" without reaching into the module's private normalizer.
+    if (tracked) manifest.files[dest] = createHash('sha256').update(body, 'utf8').digest('hex')
+    writeFixture(MANIFEST_PATH, `${JSON.stringify(manifest, null, 2)}\n`)
+  }
+
+  function manifestFiles(): Record<string, string> {
+    return (
+      JSON.parse(readFileSync(resolve(dir, MANIFEST_PATH), 'utf8')) as {
+        files: Record<string, string>
+      }
+    ).files
+  }
+
+  it('deletes an untouched retired rule file and drops its manifest entry', () => {
+    plantRetired(RETIRED_RULE, '# superseded by basalt-state.md\n')
+    const { code, log } = capture(() => sync({}, dir))
+    expect(code).toBe(0)
+    expect(existsSync(resolve(dir, RETIRED_RULE))).toBe(false)
+    expect(manifestFiles()[RETIRED_RULE]).toBeUndefined()
+    expect(log).toContain(RETIRED_RULE)
+    // The six live rules are untouched by the prune.
+    expect(existsSync(resolve(dir, '.claude/rules/basalt-state.md'))).toBe(true)
+  })
+
+  it('deletes a retired skill and removes the now-empty skill directory', () => {
+    plantRetired(RETIRED_SKILL, '---\nname: basalt-legacy\n---\n')
+    capture(() => sync({}, dir))
+    expect(existsSync(resolve(dir, RETIRED_SKILL))).toBe(false)
+    expect(existsSync(resolve(dir, '.claude/skills/basalt-legacy'))).toBe(false)
+    expect(existsSync(resolve(dir, '.claude/skills/basalt-app/SKILL.md'))).toBe(true)
+  })
+
+  it('leaves a locally-edited retired rule in place, keeps its entry, and says so', () => {
+    plantRetired(RETIRED_RULE, '# shipped body\n')
+    writeFixture(RETIRED_RULE, '# shipped body\n\nplus a local paragraph nobody else wrote\n')
+    const { code, log } = capture(() => sync({}, dir))
+    expect(code).toBe(0)
+    expect(existsSync(resolve(dir, RETIRED_RULE))).toBe(true)
+    expect(manifestFiles()[RETIRED_RULE]).toBeDefined()
+    expect(log).toContain('locally edited')
+  })
+
+  it('--force deletes a locally-edited retired rule', () => {
+    plantRetired(RETIRED_RULE, '# shipped body\n')
+    writeFixture(RETIRED_RULE, '# shipped body\n\nlocal edit\n')
+    capture(() => sync({ force: true }, dir))
+    expect(existsSync(resolve(dir, RETIRED_RULE))).toBe(false)
+    expect(manifestFiles()[RETIRED_RULE]).toBeUndefined()
+  })
+
+  it('--check reports a retired rule, exits 1, and writes nothing', () => {
+    plantRetired(RETIRED_RULE, '# superseded\n')
+    const { code, log } = capture(() => sync({ check: true }, dir))
+    expect(code).toBe(1)
+    expect(log).toContain('retired rule/skill file(s) still present')
+    expect(existsSync(resolve(dir, RETIRED_RULE))).toBe(true)
+    expect(manifestFiles()[RETIRED_RULE]).toBeDefined()
+  })
+
+  it('never prunes a tracked dest outside the rules/skills namespaces', () => {
+    // `src/routes/__root.tsx` is legitimately absent from `managedFiles()` whenever the router or
+    // query peer is missing — pruning on "this run did not place it" would delete a real scaffold.
+    plantRetired('src/routes/__root.tsx', 'export const Route = null\n')
+    capture(() => sync({}, dir))
+    expect(existsSync(resolve(dir, 'src/routes/__root.tsx'))).toBe(true)
+    expect(manifestFiles()['src/routes/__root.tsx']).toBeDefined()
+  })
+
+  it('init prunes a retired rule too', () => {
+    plantRetired(RETIRED_RULE, '# superseded\n')
+    const { log } = capture(() => init(dir))
+    expect(existsSync(resolve(dir, RETIRED_RULE))).toBe(false)
+    expect(log).toContain('no longer ship')
+  })
+})