@erclx/canon 5.62.0 → 5.64.0

package/src/claude/skills-audit.ts

@@ -1,8 +1,20 @@
 import { existsSync } from 'node:fs'
-import { dirname, join } from 'node:path'
+import { dirname, join, relative } from 'node:path'
 import { isFamilyKey } from '@/claude/skills-families'
+import { plural } from '@/cli/ui'
+import {
+  compareLedger,
+  countLedgerRows,
+  type HeadingCount,
+  type LedgerMismatch,
+} from '@/gov/audit'
 import { parseFrontmatter, readField } from '@/indexes/frontmatter'
-import { type BodyLine, bodyLines, maskDisplayed } from '@/markdown/scan'
+import {
+  type BodyLine,
+  bodyLines,
+  maskCodeSpans,
+  maskDisplayed,
+} from '@/markdown/scan'
 
 /** Returned when a skill folder carries no `REQUIREMENT.md`, the gating check. */
 export const EXIT_MISSING_REQUIREMENT = 2
@@ -69,8 +81,52 @@ export const LEDGER_SKILLS: readonly string[] = [
   join(SHIPPED_CORPUS, 'design-taste'),
   join(SHIPPED_CORPUS, 'write-human'),
   join(SHIPPED_CORPUS, 'test-first'),
+  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. 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<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>/<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',
@@ -78,9 +134,32 @@ 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')
 
+/**
+ * A ledger cites a source by linking a page outside the project, as an inline
+ * link or an autolink. A relative link points back into the skill and cites
+ * nothing a reader could check the rule against.
+ */
+const EXTERNAL_LINK = /\]\(\s*https?:\/\/|<https?:\/\//
+
+/**
+ * A table cell opening on the marker the governance ledgers already use for a
+ * rule the toolkit chose, so one check reads every ledger alike.
+ */
+const HOUSE_CHOICE = /\|\s*House choice\b/
+
 /**
  * The line count past which a reference opens with a contents list, from
  * Anthropic's skill authoring guidance. Counted over the whole file the way
@@ -118,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 {
@@ -166,13 +251,25 @@ interface SkillSource {
   readonly requirement: string | undefined
   /** Every H2 in `SKILL.md` outside a fence, for the practice shape. */
   readonly sections: readonly string[]
-  readonly hasLedger: boolean
+  /** Undefined when the folder carries no ledger at all. */
+  readonly ledger: string | undefined
   /**
    * `SKILL.md` and every reference below the folder, keyed by the path a
    * finding names. `REQUIREMENT.md` and `EVAL.md` are left out, since the
    * requirement is where the standard sends a date.
    */
   readonly bodies: readonly SkillText[]
+  /** 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 {
+  readonly rel: string
+  readonly ledgerRel: string
+  /** Undefined when the ledger file is absent. */
+  readonly mismatches: readonly LedgerMismatch[] | undefined
 }
 
 interface SkillText {
@@ -195,7 +292,7 @@ export async function auditSkills(root: string): Promise<SkillsAudit> {
   )
 
   const perCorpus = await Promise.all(
-    present.map((corpus) => readCorpus(corpus.rel, corpus.dir)),
+    present.map((corpus) => readCorpus(root, corpus.rel, corpus.dir)),
   )
   const sources = perCorpus.flat()
 
@@ -247,21 +344,29 @@ export function auditExitCode(report: SkillsAudit): number {
   return report.missingRequirement.length > 0 ? EXIT_MISSING_REQUIREMENT : 0
 }
 
-async function readCorpus(rel: string, dir: string): Promise<SkillSource[]> {
+async function readCorpus(
+  root: string,
+  rel: string,
+  dir: string,
+): Promise<SkillSource[]> {
   const paths = [
     ...new Bun.Glob('*/SKILL.md').scanSync({ cwd: dir, onlyFiles: true }),
   ].sort()
 
-  return Promise.all(paths.map((path) => readSkill(rel, dir, dirname(path))))
+  return Promise.all(
+    paths.map((path) => readSkill(root, rel, dir, dirname(path))),
+  )
 }
 
 async function readSkill(
+  root: string,
   rel: string,
   dir: string,
   folder: string,
 ): Promise<SkillSource> {
   const skillDir = join(dir, folder)
   const requirementPath = join(skillDir, 'REQUIREMENT.md')
+  const ledgerPath = join(skillDir, PRACTICE_LEDGER)
 
   const references = [
     ...new Bun.Glob('references/**/*.md').scanSync({
@@ -270,11 +375,14 @@ async function readSkill(
     }),
   ].sort()
 
-  const [body, requirement, referenceTexts] = await Promise.all([
+  const [body, requirement, ledger, referenceTexts] = await Promise.all([
     Bun.file(join(skillDir, 'SKILL.md')).text(),
     existsSync(requirementPath)
       ? Bun.file(requirementPath).text()
       : Promise.resolve(undefined),
+    existsSync(ledgerPath)
+      ? Bun.file(ledgerPath).text()
+      : Promise.resolve(undefined),
     Promise.all(
       references.map((path) => Bun.file(join(skillDir, path)).text()),
     ),
@@ -282,6 +390,22 @@ async function readSkill(
 
   const fields = parseFrontmatter(body)
   const skillRel = join(rel, folder)
+  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,
@@ -294,7 +418,7 @@ async function readSkill(
       requirement === undefined ? undefined : headings(requirement),
     requirement,
     sections: sectionsOf(body),
-    hasLedger: existsSync(join(skillDir, PRACTICE_LEDGER)),
+    ledger,
     bodies: [
       { rel: join(skillRel, 'SKILL.md'), text: body, isReference: false },
       ...references.map((path, index) => ({
@@ -303,9 +427,62 @@ async function readSkill(
         isReference: true,
       })),
     ],
+    referenceLedgers,
+    staleExemptions,
   }
 }
 
+/**
+ * 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,
+  files: readonly { path: string; text: string }[],
+): Promise<ReferenceLedger[]> {
+  return Promise.all(
+    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.
@@ -493,11 +670,48 @@ function practiceFindings(source: SkillSource): SkillFinding[] {
       rel: source.rel,
       detail: `missing section: ${section}`,
     }))
-  const ledger = source.hasLedger
-    ? []
-    : [{ rel: source.rel, detail: `missing ledger: ${PRACTICE_LEDGER}` }]
 
-  return [...sections, ...ledger]
+  return [
+    ...sections,
+    ...ledgerFindings(source),
+    ...source.referenceLedgers.flatMap(referenceLedgerFindings),
+    ...source.staleExemptions.map((rel) => ({
+      rel,
+      detail: 'missing file: exempt from a ledger',
+    })),
+  ]
+}
+
+function referenceLedgerFindings(entry: ReferenceLedger): SkillFinding[] {
+  if (entry.mismatches === undefined) {
+    return [{ rel: entry.rel, detail: `missing ledger: ${entry.ledgerRel}` }]
+  }
+  return entry.mismatches.map((mismatch) => ({
+    rel: entry.rel,
+    detail: `${mismatch.heading === null ? 'above the first H2' : `## ${mismatch.heading}`}: ${plural(mismatch.bullets, 'bullet')}, ${plural(mismatch.rows, 'ledger row')}`,
+  }))
+}
+
+/**
+ * A ledger present but citing nothing passed for as long as the check read the
+ * file's existence alone, so the contents are read too. A sample block shows a
+ * reader the shape of a row and cites nothing, so fences and code spans are
+ * left out.
+ */
+function ledgerFindings(source: SkillSource): SkillFinding[] {
+  if (source.ledger === undefined) {
+    return [{ rel: source.rel, detail: `missing ledger: ${PRACTICE_LEDGER}` }]
+  }
+
+  const cites = bodyLines(source.ledger)
+    .filter((line) => !line.fenced)
+    .map((line) => maskCodeSpans(line.text))
+    .some((text) => EXTERNAL_LINK.test(text) || HOUSE_CHOICE.test(text))
+  if (cites) return []
+
+  return [
+    { rel: source.rel, detail: `ledger cites nothing: ${PRACTICE_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

@@ -30,6 +30,8 @@ import {
   DESCRIPTION_LIMIT,
   LEDGER_SKILLS,
   PRACTICE_LEDGER,
+  BULLET_LEDGER_SKILLS,
+  SKILL_LEDGERS,
   PRACTICE_SECTIONS,
   PRACTICE_SKILLS,
   REQUIREMENT_LIMITS,
@@ -166,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.
  *
@@ -677,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) {
@@ -1768,6 +1779,9 @@ function reportPracticeShape(report: SkillsAudit): void {
   logInfo(
     `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(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.`,
   )