@erclx/canon 5.43.0 → 5.44.0

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,
@@ -441,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',
@@ -1503,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,
@@ -1511,6 +1514,7 @@ async function runSkillsAudit(
         checkpoints: {
           descriptionLimit: DESCRIPTION_LIMIT,
           requirementSections: REQUIREMENT_SECTIONS,
+          requirementLimits: REQUIREMENT_LIMITS,
           corpora: CORPORA,
           practiceSkills: PRACTICE_SKILLS,
           ledgerSkills: LEDGER_SKILLS,
@@ -1671,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')
@@ -1693,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/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

package/src/commands/migrate.ts

@@ -1335,6 +1335,10 @@ export function register(program: Command): void {
         '',
         `Rewrites ${Object.keys(SKILL_NAME_MAP).length} skill names and moves the folders that carry them.`,
         `It also carries ${Object.keys(SKILL_CITATION_MAP).length} namespaced-only rows for a skill renamed from a single word.`,
+        'The seven draft- skills move onto verb-first names, such as',
+        // The old spellings below are the rename itself. canon-keep-retired
+        'draft-doc to write-doc and draft-and-pick to pick-by-eye, and a',
+        'pointer left under each old name is never moved.',
         'It takes no scope. The skill folders it moves are authored in the',
         'toolkit and no target holds a copy of that catalog, so in a target it',
         'rewrites citations of a renamed skill and moves nothing.',

package/src/commands/pr.ts

@@ -1,4 +1,4 @@
-import { existsSync } from 'node:fs'
+import { existsSync, statSync } from 'node:fs'
 import { readFile, realpath } from 'node:fs/promises'
 import { basename, join, resolve } from 'node:path'
 import { $ } from 'bun'
@@ -57,6 +57,7 @@ import {
   pruneFramesWithLegacy,
   pushFrame,
   readFrame,
+  isDesignReference,
   referenceSlug,
   type TreeEntry,
 } from '@/pr/frames'
@@ -222,9 +223,9 @@ const FRAMES_REFUSALS: Record<FramesCommandRefusal, string> = {
   'no-number':
     '--add and --drop write for one pull request, so name its number.',
   'bad-box':
-    '--add takes --box <n>, a positive whole number naming the checklist box, or --reference <page>/<frame>, never both.',
+    '--add takes --box <n>, a positive whole number naming the checklist box, or --reference, as <page>/<frame> or a tracked canon/design/<surface>/<name> path, never both.',
   'bad-reference':
-    '--reference takes <page>/<frame>, each half opening on a letter or digit and holding only letters, digits, dots, underscores, and dashes, with no `--` in either, so the capture files under a name that reads back as the frame.',
+    '--reference takes <page>/<frame> or a tracked canon/design/<surface>/<name> path, each half opening on a letter or digit and holding only letters, digits, dots, underscores, and dashes, with no `--` in either, so the capture files under a name that reads back as the frame.',
   'bad-head':
     '--head takes a commit sha, 7 to 40 lowercase hex characters. A branch name or a path would file the frame under a folder that names no commit.',
   'bad-pass':
@@ -1060,7 +1061,7 @@ export function register(program: Command): void {
     .option('--box <n>', 'The checklist box the frame shows, with --add')
     .option(
       '--reference <address>',
-      'The design reference the capture shows, as <page>/<frame>, with --add in place of --box',
+      'The design reference the capture shows, as <page>/<frame> or a tracked canon/design/<surface>/<name> path, with --add in place of --box',
     )
     .option(
       '--head <sha>',
@@ -1087,7 +1088,9 @@ export function register(program: Command): void {
         'so nothing is checked out and no other branch is touched. A frame lands',
         'at pr-<number>/<short-head>/<pass>/box-<n>.png, or box-<n>-<theme>.png',
         'with --theme, or ref-<page>--<frame>.png for a design reference capture',
-        'passed as --reference <page>/<frame> in place of --box, and `link` names that',
+        'passed as --reference <page>/<frame> in place of --box, or',
+        'ref-design--<surface>--<name>.png for a tracked canon/design/<surface>/<name>',
+        'reference, whose --add must name that same file, and `link` names that',
         `path on ${FRAMES_BRANCH}, so it survives a rewrite that drops other pull`,
         'requests and resolves until its own pull request is dropped. The pass',
         'segment keeps a second pass at one head and box from replacing an image',
@@ -1109,7 +1112,7 @@ export function register(program: Command): void {
         '  bad-mode          not exactly one of --add, --drop, --prune',
         '  no-number         --add or --drop named no pull request',
         '  bad-box           --add with both --box and --reference, or neither',
-        '  bad-reference     --reference is not <page>/<frame> in the safe name form',
+        '  bad-reference     --reference is not <page>/<frame> or canon/design/<surface>/<name> in the safe name form, or the tracked path is no file',
         '  bad-head          --head is not 7 to 40 lowercase hex characters',
         '  bad-pass          --add without a compact UTC --pass stamp',
         '  bad-theme         --theme is not dark or light, or no --add, or rides a --reference',
@@ -3192,6 +3195,27 @@ async function runFrames(
   const invalid = framesArgumentRefusal(number, opts)
   if (invalid !== undefined) return refuseFrames(invalid)
 
+  if (opts.reference !== undefined && isDesignReference(opts.reference)) {
+    const tracked = resolve(
+      root,
+      opts.reference.endsWith('.png')
+        ? opts.reference
+        : `${opts.reference}.png`,
+    )
+    const refuseTracked = (message: string) =>
+      refuseWith('bad-reference', message, emitJson, root)
+    if (!statSync(tracked, { throwIfNoEntry: false })?.isFile()) {
+      return refuseTracked(
+        `${opts.reference} is not a file under the repository, so no tracked reference can be filed from it.`,
+      )
+    }
+    if (opts.add === undefined || resolve(opts.add) !== tracked) {
+      return refuseTracked(
+        `--add must name ${tracked}, since a tracked reference files its own image and a different one would disagree with its label.`,
+      )
+    }
+  }
+
   const bytes =
     opts.add === undefined ? undefined : await readFrame(resolve(opts.add))
   if (opts.add !== undefined && bytes === undefined) {