@erclx/canon 5.63.0 → 5.64.0

package/src/audits/catalog.ts

@@ -2,7 +2,6 @@ import type { SkillsAuditRefusal } from '@/claude/skills-audit'
 import type { RankRefusal } from '@/claude/skills-rank'
 import type { ReachRefusal } from '@/claude/skills-reach'
 import type { ContextAuditRefusal } from '@/context/audit'
-import type { SweepVerdict } from '@/context/classify/patterns'
 import type { AuditRefusal } from '@/deps/audit'
 import type { RuleAuditRefusal } from '@/gov/audit'
 import type { RestatedRefusal } from '@/gov/restated'
@@ -161,45 +160,6 @@ function requirementsCounts(
   return { requirementsOverWords: record.words > record.wordCap ? 1 : 0 }
 }
 
-/**
- * The retained key for each verdict the sweep can return. A record rather than
- * a list, so the compiler fails here when the classifier gains a verdict,
- * instead of that verdict's sections dropping out of the tally.
- */
-const PLACEMENT_KEYS: Record<SweepVerdict, string> = {
-  KEEP: 'keep',
-  REWRITE: 'rewrite',
-  MOVE: 'move',
-}
-
-function isPlacementVerdict(value: unknown): value is SweepVerdict {
-  return typeof value === 'string' && Object.hasOwn(PLACEMENT_KEYS, value)
-}
-
-/**
- * Tallies the sweep's findings by verdict, with a zero for a verdict nothing
- * returned, so a baseline reads the same three keys on every run.
- *
- * `KEEP` is retained beside the two that ask for a change. It moves when a
- * section is added or split, which is what tells a falling `rewrite` count
- * from a corpus that shrank.
- */
-function placementCounts(record: unknown): Record<string, number> | undefined {
-  const findings = asObject(record)?.findings
-  if (!Array.isArray(findings)) return undefined
-
-  const counts: Record<string, number> = Object.fromEntries(
-    Object.values(PLACEMENT_KEYS).map((key) => [key, 0]),
-  )
-  for (const finding of findings) {
-    const verdict = asObject(finding)?.verdict
-    if (!isPlacementVerdict(verdict)) return undefined
-    counts[PLACEMENT_KEYS[verdict]] += 1
-  }
-
-  return counts
-}
-
 function contextCounts(record: unknown): Record<string, number> | undefined {
   const root = asObject(record)
   if (root === undefined) return undefined
@@ -526,18 +486,6 @@ export const AUDITS: readonly AuditSpec[] = [
     absentReasons: ['no-folders'] satisfies ContextAuditRefusal[],
     counts: contextCounts,
   },
-  {
-    id: 'placement',
-    label: 'Context placement',
-    // Pinned to the regex layer rather than the resolved classifier setting.
-    // A count that moves with whichever model a machine runs is not
-    // comparable across clones, and the model layer turns a sub-second read
-    // into a multi-minute one. `document-health` is where the model reads.
-    argv: ['context', 'classify', 'sweep', '--backend', 'off', '--json'],
-    gatingExits: [],
-    corpus: 'tracked',
-    counts: placementCounts,
-  },
   {
     id: 'markdown',
     label: 'Markdown corpus',

package/src/claude/skills-audit.ts

@@ -5,8 +5,8 @@ import { plural } from '@/cli/ui'
 import {
   compareLedger,
   countLedgerRows,
+  type HeadingCount,
   type LedgerMismatch,
-  measureRule,
 } from '@/gov/audit'
 import { parseFrontmatter, readField } from '@/indexes/frontmatter'
 import {
@@ -84,19 +84,49 @@ export const LEDGER_SKILLS: readonly string[] = [
   join(SHIPPED_CORPUS, 'ui-craft'),
 ]
 
+function references(...names: string[]): string[] {
+  return names.map((name) => join('references', `${name}.md`))
+}
+
+export interface BulletLedgerScope {
+  /** References left off, each a checklist or glossary naming no new source. */
+  readonly exempt: readonly string[]
+  /** True when `SKILL.md` carries directives of its own to ledger. */
+  readonly body: boolean
+}
+
 /**
  * The ledger-listed skills whose every reference but the source record carries
  * a ledger of its own, one table row per bullet under each H2, the way a rule
- * in a practice folder does. The ledgers sit outside the plugin as rule
- * ledgers do, so a target pays nothing for them.
+ * in a practice folder does. A reference is ledgered unless exempted by name,
+ * so one added later fails until its rows land rather than passing unread. The
+ * ledgers sit outside the plugin as rule ledgers do, so a target pays nothing
+ * for them.
  */
-export const BULLET_LEDGER_SKILLS: readonly string[] = [
-  join(SHIPPED_CORPUS, 'ui-craft'),
-]
+export const BULLET_LEDGER_SKILLS: Readonly<Record<string, BulletLedgerScope>> =
+  {
+    [join(SHIPPED_CORPUS, 'ui-craft')]: { exempt: [], body: false },
+    [join(SHIPPED_CORPUS, 'api-design')]: { exempt: [], body: true },
+    [join(SHIPPED_CORPUS, 'code-craft')]: { exempt: [], body: true },
+    [join(SHIPPED_CORPUS, 'deprecation-migration')]: { exempt: [], body: true },
+    [join(SHIPPED_CORPUS, 'design-taste')]: {
+      exempt: references('preflight', 'vocabulary'),
+      body: true,
+    },
+  }
 
-/** Where a per-bullet ledger lives, as `<skill>/<reference>.md` below it. */
+/** Where a per-bullet ledger lives, as `<skill>/<file>.md` below it. */
 export const SKILL_LEDGERS = join('governance', 'ledger', 'skills')
 
+/**
+ * The ledger a ledgered file pairs with, keyed by the file's own name, so a
+ * reference drops its `references/` segment and a `SKILL.md` keeps its name.
+ */
+export function skillLedgerPath(folder: string, file: string): string {
+  const inside = relative('references', file)
+  return join(SKILL_LEDGERS, folder, inside.startsWith('..') ? file : inside)
+}
+
 /** The closing H2s a practice skill carries, matched exactly outside fences. */
 export const PRACTICE_SECTIONS: readonly string[] = [
   'Excuses and rebuttals',
@@ -104,6 +134,16 @@ export const PRACTICE_SECTIONS: readonly string[] = [
   'Before handing over',
 ]
 
+/**
+ * The H2s that end a listed body's concern groups. The closing sections
+ * restate the groups' rules as excuses, signs, and checks, and the delegates
+ * section routes, so neither states a rule of its own to source.
+ */
+export const BODY_CLOSERS: readonly string[] = [
+  ...PRACTICE_SECTIONS,
+  'What this delegates',
+]
+
 /** The source ledger every practice skill carries beside its body. */
 export const PRACTICE_LEDGER = join('references', 'adopted.md')
 
@@ -157,6 +197,12 @@ const ISSUE_NUMBER = /(?<![\w&/#])#\d+\b/g
 
 const TOP_LEVEL_BULLET = /^(?:[-*+]|\d+[.)])\s/
 
+/**
+ * A line a skill ledger pairs with a row: a top-level `- ` bullet as a rule
+ * writes one, or a top-level ordered step, which states a directive as surely.
+ */
+const LEDGERED_LINE = /^(?:- |\d+[.)]\s)/
+
 const WORD = /\S*[\p{L}\p{N}]\S*/gu
 
 export interface SkillFinding {
@@ -213,8 +259,10 @@ interface SkillSource {
    * requirement is where the standard sends a date.
    */
   readonly bodies: readonly SkillText[]
-  /** One entry per reference of a skill on the per-bullet ledger list. */
+  /** One entry per ledgered file of a skill on the per-bullet ledger list. */
   readonly referenceLedgers: readonly ReferenceLedger[]
+  /** Exempted references the skill no longer carries, which exempt nothing. */
+  readonly staleExemptions: readonly string[]
 }
 
 interface ReferenceLedger {
@@ -342,15 +390,22 @@ async function readSkill(
 
   const fields = parseFrontmatter(body)
   const skillRel = join(rel, folder)
-  const referenceLedgers = BULLET_LEDGER_SKILLS.includes(skillRel)
-    ? await readReferenceLedgers(
-        root,
-        skillRel,
-        folder,
-        references,
-        referenceTexts,
-      )
-    : []
+  const scope = BULLET_LEDGER_SKILLS[skillRel]
+  const referenceLedgers =
+    scope === undefined
+      ? []
+      : await readReferenceLedgers(root, skillRel, folder, [
+          ...(scope.body ? [{ path: 'SKILL.md', text: body }] : []),
+          ...references
+            .map((path, index) => ({ path, text: referenceTexts[index] ?? '' }))
+            .filter(
+              ({ path }) =>
+                path !== PRACTICE_LEDGER && !scope.exempt.includes(path),
+            ),
+        ])
+  const staleExemptions = (scope?.exempt ?? [])
+    .filter((path) => !references.includes(path))
+    .map((path) => join(skillRel, path))
 
   return {
     rel: skillRel,
@@ -373,44 +428,61 @@ async function readSkill(
       })),
     ],
     referenceLedgers,
+    staleExemptions,
   }
 }
 
 /**
- * Pairs each reference's bullets with its ledger's rows through the rule
- * audit's own comparison, so a reference and a rule are held to one count.
- * The source record names authorities rather than stating bullets, so it is
- * the one reference asked for no ledger.
+ * Pairs each ledgered file's directives with its ledger's rows through the rule
+ * audit's own comparison, so a skill file and a rule mismatch alike.
  */
 async function readReferenceLedgers(
   root: string,
   skillRel: string,
   folder: string,
-  references: readonly string[],
-  texts: readonly string[],
+  files: readonly { path: string; text: string }[],
 ): Promise<ReferenceLedger[]> {
   return Promise.all(
-    references
-      .map((path, index) => ({ path, text: texts[index] ?? '' }))
-      .filter(({ path }) => path !== PRACTICE_LEDGER)
-      .map(async ({ path, text }) => {
-        const ledgerRel = join(
-          SKILL_LEDGERS,
-          folder,
-          relative('references', path),
-        )
-        const ledgerPath = join(root, ledgerRel)
-        const mismatches = existsSync(ledgerPath)
-          ? compareLedger(
-              measureRule(text).groups,
-              countLedgerRows(await Bun.file(ledgerPath).text()),
-            )
-          : undefined
-        return { rel: join(skillRel, path), ledgerRel, mismatches }
-      }),
+    files.map(async ({ path, text }) => {
+      const ledgerRel = skillLedgerPath(folder, path)
+      const ledgerPath = join(root, ledgerRel)
+      const mismatches = existsSync(ledgerPath)
+        ? compareLedger(
+            ledgerGroups(text, path === 'SKILL.md'),
+            countLedgerRows(await Bun.file(ledgerPath).text()),
+          )
+        : undefined
+      return { rel: join(skillRel, path), ledgerRel, mismatches }
+    }),
   )
 }
 
+/**
+ * Directives per H2, `null` for any above the first. A contents list repeats
+ * the headings rather than stating a rule, so `## Contents` takes no rows. A
+ * nested bullet elaborates its parent, so only a top-level line counts. A body
+ * stops at its first closer, and a ledger table under one then reads as rows
+ * with no bullets rather than passing unread.
+ */
+function ledgerGroups(text: string, isBody: boolean): HeadingCount[] {
+  const counts = new Map<string | null, number>()
+  let heading: string | null = null
+
+  for (const line of bodyLines(text)) {
+    if (line.fenced) continue
+    const section = SECTION.exec(line.text)?.[1]
+    if (section !== undefined) {
+      if (isBody && BODY_CLOSERS.includes(section)) break
+      heading = section
+      continue
+    }
+    if (heading === CONTENTS_SECTION || !LEDGERED_LINE.test(line.text)) continue
+    counts.set(heading, (counts.get(heading) ?? 0) + 1)
+  }
+
+  return [...counts].map(([key, count]) => ({ heading: key, count }))
+}
+
 /**
  * A key carrying an empty value declares nothing, so blank reads as absent
  * rather than as a name that disagrees with every folder.
@@ -603,6 +675,10 @@ function practiceFindings(source: SkillSource): SkillFinding[] {
     ...sections,
     ...ledgerFindings(source),
     ...source.referenceLedgers.flatMap(referenceLedgerFindings),
+    ...source.staleExemptions.map((rel) => ({
+      rel,
+      detail: 'missing file: exempt from a ledger',
+    })),
   ]
 }
 

package/src/cli/retired.ts

@@ -9,6 +9,8 @@ export interface RetiredVerb {
 const DESIGN_MOVED =
   'the design values now live in the stylesheet your canon/DESIGN.md lead names'
 
+const CONTEXT_MOVED = '`canon context audit`, which reports placement findings'
+
 /**
  * Every verb a release dropped, with the release and where the work went. The
  * router reads this ahead of the parser, and `canon migrate status` reads it to
@@ -41,6 +43,12 @@ export const RETIRED_VERBS: readonly RetiredVerb[] = [
     release: '5.53.0',
     movedTo: 'a tool built for composed video',
   },
+  { path: ['context', 'classify'], release: '5.64.0', movedTo: CONTEXT_MOVED },
+  {
+    path: ['context', 'classifier'],
+    release: '5.64.0',
+    movedTo: CONTEXT_MOVED,
+  },
 ]
 
 /**

package/src/commands/claude.ts

@@ -168,6 +168,15 @@ interface RoutingOptions {
 const SEEDED_FILES: readonly string[] = ['REQUIREMENTS.md', 'DESIGN.md']
 const SEEDED_DIRS: readonly string[] = ['tasks']
 
+/**
+ * Where a `SEEDED_FILES` entry resolves for the sync presence check, at either
+ * surface root, so a target holding its records under `canon/` is not sent to
+ * `canon claude init`.
+ */
+export function seededFilePath(resolved: string, name: string): string {
+  return surfaceDir(resolved, name)
+}
+
 /**
  * Where a `SEEDED_DIRS` entry resolves for the sync presence check.
  *
@@ -679,7 +688,7 @@ async function runSync(target: string): Promise<number> {
   // already holds.
   logStep('Seeded')
   for (const name of SEEDED_FILES) {
-    if (existsSync(join(resolved, '.claude', name))) logInfo(name)
+    if (existsSync(seededFilePath(resolved, name))) logInfo(name)
     else logWarn(`${name} missing. Run \`canon claude init\``)
   }
   for (const name of SEEDED_DIRS) {
@@ -1771,7 +1780,7 @@ function reportPracticeShape(report: SkillsAudit): void {
     `A listed practice skill closes with ${PRACTICE_SECTIONS.map((section) => `## ${section}`).join(', ')}, and every skill on the wider ledger list carries ${PRACTICE_LEDGER}.`,
   )
   logInfo(
-    `A skill on the per-bullet list, ${plural(BULLET_LEDGER_SKILLS.length, 'skill')} here, also matches each other reference to a ledger under ${SKILL_LEDGERS}, one row per bullet under each H2.`,
+    `A skill on the per-bullet list, ${plural(Object.keys(BULLET_LEDGER_SKILLS).length, 'skill')} here, also matches each reference it does not exempt, and a listed body, to a ledger under ${SKILL_LEDGERS}, one row per bullet under each H2.`,
   )
   logInfo(
     `Both lists are kept here and name ${plural(PRACTICE_SKILLS.length, 'practice skill')} and ${plural(LEDGER_SKILLS.length, 'ledger skill')}, so a skill outside ${SHIPPED_CORPUS} is never read.`,