@erclx/canon 5.43.0 → 5.45.0

package/src/cli/help.ts

@@ -29,7 +29,6 @@ export const COMMAND_GROUPS: { title: string; rows: CommandRow[] }[] = [
       ['gov [cmd]', 'Governance rules'],
       ['tooling [cmd]', 'Tooling stacks'],
       ['claude [cmd]', 'Claude workflow'],
-      ['wiki [cmd]', 'Wiki pages'],
       ['indexes [cmd]', 'Regenerate index.md files'],
       ['docs [cmd|topic]', 'Emit toolkit reference docs'],
     ],

package/src/cli.ts

@@ -7,7 +7,6 @@ import { register as sync } from '@/commands/sync'
 import { register as gov } from '@/commands/gov'
 import { register as tooling } from '@/commands/tooling'
 import { register as claude } from '@/commands/claude'
-import { register as wiki } from '@/commands/wiki'
 import { register as indexes } from '@/commands/indexes'
 import { register as docs } from '@/commands/docs'
 import { register as design } from '@/commands/design'
@@ -68,7 +67,6 @@ sync(program)
 gov(program)
 tooling(program)
 claude(program)
-wiki(program)
 indexes(program)
 docs(program)
 design(program)

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/gov.ts

@@ -37,6 +37,7 @@ import {
   hasFinding,
   PRACTICE_FOLDERS,
   readRuleAudit,
+  RULE_GATE_EXEMPT,
   RULE_GATED_FOLDERS,
   RULE_LIMITS,
   type RuleAuditReport,
@@ -631,6 +632,7 @@ export function register(program: Command): void {
         '  inside it.',
         '',
         `Gated folders: ${RULE_GATED_FOLDERS.length === 0 ? 'none yet' : RULE_GATED_FOLDERS.join(', ')}`,
+        `Exempt from the gate: ${RULE_GATE_EXEMPT.length === 0 ? 'none' : RULE_GATE_EXEMPT.join(', ')}`,
         '',
         'Exit codes:',
         '  0  no finding, or under --gate no finding in a gated folder',
@@ -691,6 +693,7 @@ async function runAudit(
         root,
         limits: RULE_LIMITS,
         gated: RULE_GATED_FOLDERS,
+        exempt: RULE_GATE_EXEMPT,
         ...report,
       })}\n`,
     )
@@ -699,6 +702,7 @@ async function runAudit(
   return auditExit(report, {
     gate: opts.gate ?? false,
     gated: RULE_GATED_FOLDERS,
+    exempt: RULE_GATE_EXEMPT,
   })
 }
 

package/src/commands/init.ts

@@ -39,8 +39,8 @@ export function register(program: Command): void {
         '',
         'Runs `canon tooling sync base --write` first, which replaces every',
         'base golden config the target holds, then `canon claude init`,',
-        '`canon gov install`, and `canon wiki init`. Refuses a target that is',
-        'not a directory or is the toolkit root.',
+        'and `canon gov install`. Refuses a target that is not a directory or is',
+        'the toolkit root.',
         '',
         'Exit codes:',
         '  0  every domain installed, or the prompt was cancelled',

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) {