@erclx/canon 5.42.0 → 5.44.0

package/src/claude/cases/workflow.ts

@@ -22,12 +22,18 @@ export const WORKFLOW_CASES: readonly SkillCase[] = [
   },
   {
     prompt: 'Draw me a diagram of how the pieces of this system connect.',
+    expect: 'draw-figure',
+  },
+  {
+    prompt:
+      'I typed draft-figure and it said the figure skill was renamed to draw-figure.', // canon-keep-retired
+    // The pointer answers under its old name on purpose. canon-keep-retired
     expect: 'draft-figure',
   },
   {
     prompt:
       'This onboarding doc needs a hand-drawn picture of the signup-to-active path, sketch it in and make sure it actually renders correctly.',
-    expect: 'draft-figure',
+    expect: 'draw-figure',
   },
   {
     prompt:
@@ -108,10 +114,22 @@ export const WORKFLOW_CASES: readonly SkillCase[] = [
   },
   {
     prompt: 'Draft me a script with beats for a screencast recording.',
+    expect: 'script-screencast',
+  },
+  {
+    prompt:
+      'I typed draft-screencast and it said the screencast skill was renamed to script-screencast.', // canon-keep-retired
+    // The pointer answers under its old name on purpose. canon-keep-retired
     expect: 'draft-screencast',
   },
   {
     prompt: 'Turn this topic into a slide deck I can render.',
+    expect: 'make-deck',
+  },
+  {
+    prompt:
+      'I typed draft-slides and it said the slides skill was renamed to make-deck.', // canon-keep-retired
+    // The pointer answers under its old name on purpose. canon-keep-retired
     expect: 'draft-slides',
   },
   // Rot across documents nobody changed is what this reads, rather than a

package/src/claude/settings.ts

@@ -5,6 +5,10 @@ import { dirname } from 'node:path'
 const DEFAULT_INDENT = '  '
 const INDENT = /^([ \t]+)\S/m
 
+// The pair setup once wrote to suppress Claude's attribution. Only this exact
+// value is retracted, since anything else is a person's own choice.
+const RETIRED_ATTRIBUTION = { commit: '', pr: '' }
+
 export type SettingsRecord = Record<string, unknown>
 
 export interface SettingsKey {
@@ -107,10 +111,10 @@ export function planSettings(
   }
   keys.push({ label: 'statusLine', changed: statusLineChanged })
 
-  const attribution = template.attribution
-  const attributionChanged = !equals(next.attribution, attribution)
-  if (attributionChanged) next.attribution = attribution
-  keys.push({ label: 'attribution', changed: attributionChanged })
+  if (equals(next.attribution, RETIRED_ATTRIBUTION)) {
+    delete next.attribution
+    keys.push({ label: 'attribution', changed: true })
+  }
 
   const permissions = asRecord(next.permissions)
   const merged: SettingsRecord = { ...permissions }

package/src/claude/skills-audit.ts

@@ -2,7 +2,7 @@ import { existsSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { isFamilyKey } from '@/claude/skills-families'
 import { parseFrontmatter, readField } from '@/indexes/frontmatter'
-import { bodyLines, maskDisplayed } from '@/markdown/scan'
+import { type BodyLine, bodyLines, maskDisplayed } from '@/markdown/scan'
 
 /** Returned when a skill folder carries no `REQUIREMENT.md`, the gating check. */
 export const EXIT_MISSING_REQUIREMENT = 2
@@ -13,6 +13,19 @@ export const DESCRIPTION_LIMIT = 1024
 /** The two headings the requirement template declares, matched at any level. */
 export const REQUIREMENT_SECTIONS: readonly string[] = ['Gap', 'Must']
 
+/**
+ * The caps `claude/skills/create-skill/references/skill-requirement.md` states.
+ * Words count body tokens carrying a letter or digit, so a heading or bullet
+ * marker costs nothing and frontmatter is left out.
+ */
+export const REQUIREMENT_LIMITS = { bullets: 5, words: 400 } as const
+
+/** The section the standard retired into Must not, matched at any level. */
+export const RETIRED_REQUIREMENT_SECTION = 'Guards'
+
+/** The section that states today's failures, where history is reported. */
+const GAP_SECTION = 'Gap'
+
 /** The one tree that ships to a target, and the only one the practice list names. */
 export const SHIPPED_CORPUS = join('claude', 'skills')
 
@@ -100,6 +113,13 @@ const SECTION = /^##\s+(.+?)\s*$/
  */
 const ISO_DATE = /\b\d{4}-\d{2}-\d{2}\b/g
 
+/** An issue or pull request number, which a heading's `#` never matches. */
+const ISSUE_NUMBER = /(?<![\w&/#])#\d+\b/g
+
+const TOP_LEVEL_BULLET = /^(?:[-*+]|\d+[.)])\s/
+
+const WORD = /\S*[\p{L}\p{N}]\S*/gu
+
 export interface SkillFinding {
   readonly rel: string
   readonly detail: string
@@ -126,6 +146,7 @@ export interface SkillsAudit {
   readonly nameMismatch: readonly SkillFinding[]
   readonly longDescription: readonly SkillFinding[]
   readonly requirementSections: readonly SkillFinding[]
+  readonly requirementLimits: readonly SkillFinding[]
   readonly datedProvenance: readonly SkillFinding[]
   readonly practiceShape: readonly SkillFinding[]
   readonly referenceContents: readonly SkillFinding[]
@@ -142,6 +163,7 @@ interface SkillSource {
   readonly family: string | undefined
   /** Undefined when the folder carries no `REQUIREMENT.md` at all. */
   readonly requirementHeadings: readonly string[] | undefined
+  readonly requirement: string | undefined
   /** Every H2 in `SKILL.md` outside a fence, for the practice shape. */
   readonly sections: readonly string[]
   readonly hasLedger: boolean
@@ -198,6 +220,7 @@ export async function auditSkills(root: string): Promise<SkillsAudit> {
     nameMismatch: sources.flatMap(nameFindings),
     longDescription: sources.flatMap(lengthFindings),
     requirementSections: sources.flatMap(sectionFindings),
+    requirementLimits: sources.flatMap(limitFindings),
     datedProvenance: sources.flatMap((source) =>
       source.bodies.flatMap(dateFindings),
     ),
@@ -269,6 +292,7 @@ async function readSkill(
     family: declaredFamily(fields?.fields.metadata),
     requirementHeadings:
       requirement === undefined ? undefined : headings(requirement),
+    requirement,
     sections: sectionsOf(body),
     hasLedger: existsSync(join(skillDir, PRACTICE_LEDGER)),
     bodies: [
@@ -349,6 +373,94 @@ function sectionFindings(source: SkillSource): SkillFinding[] {
   ]
 }
 
+/**
+ * Reports every cap the standard states, each as its own finding so a file
+ * breaching two reads as two edits. Silent on an absent requirement for the
+ * reason `sectionFindings` is.
+ */
+function limitFindings(source: SkillSource): SkillFinding[] {
+  const { requirement, requirementHeadings } = source
+  if (requirement === undefined || requirementHeadings === undefined) return []
+
+  const rel = join(source.rel, 'REQUIREMENT.md')
+  const lines = bodyLines(requirement)
+  const details = [
+    ...bulletDetails(lines),
+    ...wordDetails(lines),
+    ...gapHistoryDetails(lines),
+    ...(requirementHeadings.includes(RETIRED_REQUIREMENT_SECTION)
+      ? [`## ${RETIRED_REQUIREMENT_SECTION}: retired, fold it into Must not`]
+      : []),
+  ]
+
+  return details.map((detail) => ({ rel, detail }))
+}
+
+/**
+ * Counts top-level bullets per H2, since the template holds one list per
+ * section. A nested bullet elaborates its parent rather than adding to it.
+ */
+function bulletDetails(lines: readonly BodyLine[]): string[] {
+  const counts = new Map<string, number>()
+  let section: string | undefined
+
+  for (const line of lines) {
+    if (line.fenced) continue
+    const heading = SECTION.exec(line.text)?.[1]
+    if (heading !== undefined) {
+      section = heading
+      continue
+    }
+    if (section === undefined || !TOP_LEVEL_BULLET.test(line.text)) continue
+    counts.set(section, (counts.get(section) ?? 0) + 1)
+  }
+
+  return [...counts]
+    .filter(([, count]) => count > REQUIREMENT_LIMITS.bullets)
+    .map(
+      ([name, count]) =>
+        `## ${name}: ${count} bullets, cap ${REQUIREMENT_LIMITS.bullets}`,
+    )
+}
+
+function wordDetails(lines: readonly BodyLine[]): string[] {
+  const words = lines.reduce(
+    (total, line) => total + (line.text.match(WORD)?.length ?? 0),
+    0,
+  )
+  if (words <= REQUIREMENT_LIMITS.words) return []
+  return [`${words} words, cap ${REQUIREMENT_LIMITS.words}`]
+}
+
+/**
+ * Gap states what fails today, so a date or a number naming the incident that
+ * earned a line is history git already holds. A code span is quoted data, such
+ * as a sample filename, and is masked before matching.
+ */
+function gapHistoryDetails(lines: readonly BodyLine[]): string[] {
+  const details: string[] = []
+  let inGap = false
+
+  for (const line of lines) {
+    if (line.fenced) continue
+    const heading = HEADING.exec(line.text)?.[1]
+    if (heading !== undefined) {
+      inGap = heading === GAP_SECTION
+      continue
+    }
+    if (!inGap) continue
+    const masked = maskDisplayed(line.text)
+    for (const match of [
+      ...masked.matchAll(ISO_DATE),
+      ...masked.matchAll(ISSUE_NUMBER),
+    ]) {
+      details.push(`line ${line.number}: ${match[0]} in ${GAP_SECTION}`)
+    }
+  }
+
+  return details
+}
+
 /**
  * A listed folder the shipped corpus does not hold, such as a renamed skill or
  * a misspelled append, would otherwise read as a pass. Silent where the

package/src/commands/claude.ts

@@ -32,7 +32,9 @@ import {
   PRACTICE_LEDGER,
   PRACTICE_SECTIONS,
   PRACTICE_SKILLS,
+  REQUIREMENT_LIMITS,
   REQUIREMENT_SECTIONS,
+  RETIRED_REQUIREMENT_SECTION,
   SHIPPED_CORPUS,
   type SkillFinding,
   type SkillsAudit,
@@ -69,6 +71,7 @@ import {
   serializeSettings,
   writeSettings,
 } from '@/claude/settings'
+import { readSessionDefaults } from '@/migrate/session-defaults'
 import { copyPreservingMode } from '@/sync/copy'
 import { checkoutMismatchWarning, PROJECT_ROOT } from '@/roots/project'
 import { recordDir } from '@/roots/record'
@@ -255,7 +258,7 @@ export function register(program: Command): void {
 
   claude
     .command('setup')
-    .description('One-shot user-level config (statusline, attribution)')
+    .description('One-shot user-level config (statusline, permissions)')
     .argument('[dest]', 'User config directory', join(homedir(), '.claude'))
     .helpOption('-h, --help', 'Show this help message')
     .action(async (dest: string) => {
@@ -440,7 +443,7 @@ export function register(program: Command): void {
         'Refuses when neither claude/skills/ nor .claude/skills/ resolves.',
         '',
         'Only a missing REQUIREMENT.md sets a failing exit code. Name, description,',
-        'folder, and requirement-section findings are advisory.',
+        'folder, and requirement shape and limit findings are advisory.',
         '',
         'Examples:',
         '  canon claude skills audit',
@@ -663,6 +666,15 @@ async function runSync(target: string): Promise<number> {
     else logWarn(`${name}/ missing. Run \`canon claude init\``)
   }
 
+  // Sync never rewrites an existing settings file, so a target seeded before
+  // the session defaults learns of them only here.
+  const defaults = await readSessionDefaults(resolved, PROJECT_ROOT)
+  if (defaults.kind === 'planned' && defaults.plan.predates) {
+    logWarn(
+      'settings.json lacks the session defaults. Run `canon migrate session-defaults --write`',
+    )
+  }
+
   logStep('Scanning .gitignore')
   const chain = claudeChain(PROJECT_ROOT)
   const pruned = await pruneGitignore(chain, resolved)
@@ -1493,6 +1505,7 @@ async function runSkillsAudit(
           readme: report.readme,
           folderName: report.folderName,
           requirementSections: report.requirementSections,
+          requirementLimits: report.requirementLimits,
           datedProvenance: report.datedProvenance,
           practiceShape: report.practiceShape,
           referenceContents: report.referenceContents,
@@ -1501,6 +1514,7 @@ async function runSkillsAudit(
         checkpoints: {
           descriptionLimit: DESCRIPTION_LIMIT,
           requirementSections: REQUIREMENT_SECTIONS,
+          requirementLimits: REQUIREMENT_LIMITS,
           corpora: CORPORA,
           practiceSkills: PRACTICE_SKILLS,
           ledgerSkills: LEDGER_SKILLS,
@@ -1661,21 +1675,40 @@ function reportRequirementShape(report: SkillsAudit): void {
     'A folder carrying no requirement is reported above rather than counted twice here.',
   )
 
-  if (report.requirementSections.length === 0) {
-    logInfo('Every requirement declares both.')
+  logInfo(
+    `Each list holds at most ${REQUIREMENT_LIMITS.bullets} top-level bullets, the body at most ${REQUIREMENT_LIMITS.words} words, and Gap no date or issue number outside a code span.`,
+  )
+  logInfo(
+    `A ## ${RETIRED_REQUIREMENT_SECTION} section is retired into Must not. These limits report and never fail the run.`,
+  )
+
+  if (
+    report.requirementSections.length === 0 &&
+    report.requirementLimits.length === 0
+  ) {
+    logInfo('Every requirement declares both and holds to the limits.')
     return
   }
 
-  logWarn(
-    `${plural(report.requirementSections.length, 'requirement')} short a declared section`,
-  )
-  reportFindings(report.requirementSections)
+  if (report.requirementSections.length > 0) {
+    logWarn(
+      `${plural(report.requirementSections.length, 'requirement')} short a declared section`,
+    )
+    reportFindings(report.requirementSections)
+  }
+
+  if (report.requirementLimits.length > 0) {
+    logWarn(
+      `${plural(report.requirementLimits.length, 'finding')} past a requirement limit`,
+    )
+    reportFindings(report.requirementLimits)
+  }
 }
 
 /**
- * Names where the date belongs, since the finding is a date to move rather
- * than one to delete, and reports without failing the run for the same reason
- * the frontmatter measures do.
+ * Names where the date belongs, since a reader deleting it should know git
+ * still holds it, and reports without failing the run for the same reason the
+ * frontmatter measures do.
  */
 function reportProvenance(report: SkillsAudit): void {
   logStep('Provenance')
@@ -1683,7 +1716,7 @@ function reportProvenance(report: SkillsAudit): void {
     'A SKILL.md and its references state the current rule, with no ISO date outside a fence or code span.',
   )
   logInfo(
-    'The incident and date that earned a rule go in REQUIREMENT.md under Gap, or stay in git.',
+    'The incident and date that earned a rule stay in git, where the log of the file finds them.',
   )
 
   if (report.datedProvenance.length === 0) {

package/src/commands/demo.ts

@@ -62,7 +62,7 @@ export function register(program: Command): void {
   demo
     .command('compile')
     .description('Turn a screencast draft into a plan a run can drive')
-    .argument('<draft>', 'Screencast draft written by draft-screencast')
+    .argument('<draft>', 'Screencast draft written by script-screencast')
     .helpOption('-h, --help', 'Show this help message')
     .option('-o, --out <dir>', 'Directory the plan is written to', DEFAULT_OUT)
     .option('-s, --slug <slug>', 'Plan name, defaulting to the draft filename')

package/src/commands/gov.ts

@@ -32,6 +32,16 @@ import {
   SEED_REL,
   SHIPPED_SKILLS_REL,
 } from '@/gov/restated'
+import {
+  auditExit,
+  hasFinding,
+  PRACTICE_FOLDERS,
+  readRuleAudit,
+  RULE_GATED_FOLDERS,
+  RULE_LIMITS,
+  type RuleAuditReport,
+  type RuleReading,
+} from '@/gov/audit'
 import {
   CITATION_MARKER,
   type CitationReport,
@@ -123,6 +133,12 @@ interface CountsOptions {
   readonly json?: boolean
 }
 
+interface AuditOptions {
+  readonly root?: string
+  readonly json?: boolean
+  readonly gate?: boolean
+}
+
 /** What a reader does about each way the sweep produced no reading. */
 const RESTATED_REFUSALS: Record<RestatedRefusal, string> = {
   'no-instructions': `No ${INSTRUCTIONS_REL} here, or it carries no bullet, so there is no instruction corpus to sweep.`,
@@ -573,6 +589,188 @@ export function register(program: Command): void {
     .action((opts: RestatedOptions) => {
       process.exitCode = runRestated(opts)
     })
+
+  gov
+    .command('audit')
+    .description(
+      'Report every rule past a shape limit, and in this repository every outside-practice rule missing a source ledger',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .argument(
+      '[paths...]',
+      'Rule files or folders of rules to read, defaulting to the corpus',
+    )
+    .option('--root <path>', 'Tree to read, defaulting to the cwd')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .option(
+      '--gate',
+      'Set 2 only for a finding in a gated folder, which the push stage reads',
+    )
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Limits, each a finding one past its number:',
+        `  words      ${RULE_LIMITS.words} words in the body`,
+        `  bullets    ${RULE_LIMITS.bullets} bullets in the file`,
+        `  h2         ${RULE_LIMITS.h2} H2 headings`,
+        `  perH2      ${RULE_LIMITS.perH2} bullets under one H2, the text above the first H2 a group`,
+        `  chars      ${RULE_LIMITS.chars} characters in one bullet, continuation lines folded in`,
+        `  sentences  ${RULE_LIMITS.sentences} sentences in one bullet`,
+        '  emphasis   any CRITICAL, IMPORTANT, MUST, ALWAYS, NEVER, or "you must"',
+        '             outside a code span',
+        '',
+        'Corpus:',
+        '  A tree holding governance/rules/ reads it and internal/rules/, and',
+        `  asks a ledger of each rule under ${PRACTICE_FOLDERS.join(', ')}`,
+        '  at governance/ledger/<folder>/<slug>.md, one table row per bullet',
+        '  under a heading of the same name.',
+        '  Any other tree reads .claude/rules/project/ alone and asks no ledger.',
+        '  .claude/rules/canon/ is fixed at the toolkit source and never read',
+        '  unless named. A named path resolves against --root and must sit',
+        '  inside it.',
+        '',
+        `Gated folders: ${RULE_GATED_FOLDERS.length === 0 ? 'none yet' : RULE_GATED_FOLDERS.join(', ')}`,
+        '',
+        'Exit codes:',
+        '  0  no finding, or under --gate no finding in a gated folder',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '  2  at least one finding, or under --gate one in a gated folder',
+        '',
+        'Reasons:',
+        '  no-rules      the tree holds no rule corpus to read, or a named folder holds no rule',
+        '  no-path       a named path does not exist',
+        '  outside-root  a named path sits outside --root',
+        '',
+        'Examples:',
+        '  canon gov audit',
+        '  canon gov audit .claude/rules/project/api.md',
+        '  canon gov audit --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (paths: string[], opts: AuditOptions) => {
+      process.exitCode = await runAudit(paths, opts)
+    })
+}
+
+/**
+ * Reports by default and gates only under `--gate`, and there only for the
+ * folders `RULE_GATED_FOLDERS` lists. The corpus starts far from zero, so the
+ * push stage fails on a folder once its rewrite has brought it there.
+ */
+async function runAudit(
+  paths: readonly string[],
+  opts: AuditOptions,
+): Promise<number> {
+  const root = resolve(opts.root ?? process.cwd())
+  const report = await readRuleAudit(root, paths)
+  const emitJson = opts.json ?? false
+
+  if (report.kind === 'unreadable') {
+    intro('canon gov audit')
+    logStep('Refused')
+    logError(report.message)
+    outro()
+
+    if (emitJson) {
+      process.stdout.write(
+        `${JSON.stringify({ ok: false, reason: report.reason, message: report.message })}\n`,
+      )
+    }
+
+    return 1
+  }
+
+  reportAudit(report, root, paths.length > 0)
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({
+        ok: true,
+        root,
+        limits: RULE_LIMITS,
+        gated: RULE_GATED_FOLDERS,
+        ...report,
+      })}\n`,
+    )
+  }
+
+  return auditExit(report, {
+    gate: opts.gate ?? false,
+    gated: RULE_GATED_FOLDERS,
+  })
+}
+
+function describeLedger(reading: RuleReading): string[] {
+  const { ledger } = reading
+  if (ledger.status === 'missing') {
+    return [`${reading.file}: no ledger at ${ledger.path}`]
+  }
+  if (ledger.status !== 'present') return []
+  return ledger.mismatches.map(
+    (mismatch) =>
+      `${ledger.path}: ${mismatch.heading ?? '(above the first H2)'} has ${mismatch.rows} row(s) for ${mismatch.bullets} bullet(s)`,
+  )
+}
+
+function reportAudit(
+  report: Extract<RuleAuditReport, { kind: 'measured' }>,
+  root: string,
+  named: boolean,
+): void {
+  intro('canon gov audit')
+
+  const shaped = report.rules.filter((reading) => reading.findings.length > 0)
+  const ledgers = report.rules.flatMap(describeLedger)
+
+  logStep('Corpus')
+  logInfo(
+    named
+      ? `${report.rules.length} named rule(s) in ${root}`
+      : `${report.rules.length} rule(s) under ${report.corpus.join(' and ')} in ${root}`,
+  )
+
+  logStep('Shape')
+  if (shaped.length === 0) {
+    logInfo('every rule is within the six limits and carries no emphasis word')
+  } else {
+    for (const reading of shaped) {
+      for (const finding of reading.findings) {
+        const at =
+          finding.line === undefined
+            ? reading.file
+            : `${reading.file}:${finding.line}`
+        logWarn(
+          finding.limit === 'emphasis'
+            ? `${at}: emphasis word`
+            : `${at}: ${finding.limit} ${finding.count} past ${finding.max}`,
+        )
+      }
+    }
+  }
+
+  logStep('Ledgers')
+  if (report.scope === 'target') {
+    logInfo('not read, since ledgers live in the toolkit and never ship')
+  } else if (ledgers.length === 0) {
+    logInfo('every outside-practice rule has a ledger row per bullet')
+  } else {
+    for (const line of ledgers) logWarn(line)
+  }
+
+  const failing = report.rules.filter(hasFinding).length
+  logStep('Summary')
+  logInfo(
+    `${failing} of ${report.rules.length} rule(s) carry a finding: ${shaped.length} with a shape finding, ${ledgers.length} ledger finding(s)`,
+  )
+  logInfo(
+    RULE_GATED_FOLDERS.length === 0
+      ? 'no folder is gated yet, so --gate passes every finding'
+      : `gated: ${RULE_GATED_FOLDERS.join(', ')}`,
+  )
+
+  outro()
 }
 
 /**

package/src/commands/markdown.ts

@@ -486,7 +486,7 @@ function reportDensity(reports: readonly FileReport[], gates: boolean): void {
     `Paragraphs past ${CHECKPOINTS.paragraph} characters, more than 2 paragraphs in a row, bullets past ${CHECKPOINTS.bullet} characters, more than 5 plain bullets in a row, a heading past H3, and an H3 opening with neither a paragraph nor a table.`,
   )
   logInfo(
-    'Measured on context entries, docs, skill bodies and references, tooling seeds and stack references, the wiki, README.md, and CONTRIBUTING.md. Every other path takes no density finding.',
+    'Measured on context entries, docs, skill bodies, references, and requirements, tooling seeds and stack references, the wiki, README.md, and CONTRIBUTING.md. Every other path takes no density finding.',
   )
   logInfo(
     gates