@erclx/canon 5.24.0 → 5.26.0

package/src/claude/seeds.ts

@@ -3,7 +3,7 @@ import { chmod, mkdir, readFile, writeFile } from 'node:fs/promises'
 import { dirname, join, relative } from 'node:path'
 import { copyPreservingMode } from '@/copy'
 import { creationRel, isRecordEntry } from '@/record-root'
-import { rewritesOnInstall, stripSeedMarker } from '@/seed-marker'
+import { rewritesOnInstall, stripSeedMarker } from '@/tooling/seed-marker'
 import { SURFACE_ENTRIES, surfaceDir } from '@/surface-root'
 
 const SEEDS_DIR = join('tooling', 'claude', 'seeds')
@@ -20,7 +20,6 @@ const HOOKS = 'hooks'
 export const SUBDIRS: readonly string[] = [
   HOOKS,
   'context',
-  'diagrams',
   'memory',
   'tasks',
   'wireframes',

package/src/claude/skills-audit.ts

@@ -40,6 +40,21 @@ export const PRACTICE_SKILLS: readonly string[] = [
   join(SHIPPED_CORPUS, 'code-craft'),
   join(SHIPPED_CORPUS, 'build-in-slices'),
   join(SHIPPED_CORPUS, 'deprecation-migration'),
+  join(SHIPPED_CORPUS, 'search-craft'),
+  join(SHIPPED_CORPUS, 'video-craft'),
+]
+
+/**
+ * Every skill carrying the source ledger, being the practice skills and the
+ * skills that teach a craft without the practice closing sections. Kept apart
+ * from `PRACTICE_SKILLS` so citing sources never forces those sections onto a
+ * skill whose body is not shaped around a practice a session cuts short.
+ */
+export const LEDGER_SKILLS: readonly string[] = [
+  ...PRACTICE_SKILLS,
+  join(SHIPPED_CORPUS, 'design-taste'),
+  join(SHIPPED_CORPUS, 'write-human'),
+  join(SHIPPED_CORPUS, 'test-first'),
 ]
 
 /** The closing H2s a practice skill carries, matched exactly outside fences. */
@@ -52,6 +67,16 @@ export const PRACTICE_SECTIONS: readonly string[] = [
 /** The source ledger every practice skill carries beside its body. */
 export const PRACTICE_LEDGER = join('references', 'adopted.md')
 
+/**
+ * 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
+ * `wc -l` counts it, so "over 100" holds at 101 and not at 100.
+ */
+export const CONTENTS_THRESHOLD = 100
+
+/** The H2 a long reference opens with, matched exactly outside fences. */
+export const CONTENTS_SECTION = 'Contents'
+
 /**
  * The one reason this audit refuses. A project carrying neither corpus is the
  * ordinary state of a target that has not adopted either skills convention,
@@ -102,6 +127,7 @@ export interface SkillsAudit {
   readonly requirementSections: readonly SkillFinding[]
   readonly datedProvenance: readonly SkillFinding[]
   readonly practiceShape: readonly SkillFinding[]
+  readonly referenceContents: readonly SkillFinding[]
 }
 
 interface SkillSource {
@@ -126,6 +152,7 @@ interface SkillSource {
 interface SkillText {
   readonly rel: string
   readonly text: string
+  readonly isReference: boolean
 }
 
 /**
@@ -177,6 +204,9 @@ export async function auditSkills(root: string): Promise<SkillsAudit> {
       ),
       ...sources.flatMap(practiceFindings),
     ],
+    referenceContents: sources.flatMap((source) =>
+      source.bodies.flatMap(contentsFindings),
+    ),
   }
 }
 
@@ -233,16 +263,14 @@ async function readSkill(
     description: declared(readField(fields, 'description')),
     requirementHeadings:
       requirement === undefined ? undefined : headings(requirement),
-    sections: bodyLines(body)
-      .filter((line) => !line.fenced)
-      .map((line) => SECTION.exec(line.text)?.[1])
-      .filter((text): text is string => text !== undefined),
+    sections: sectionsOf(body),
     hasLedger: existsSync(join(skillDir, PRACTICE_LEDGER)),
     bodies: [
-      { rel: join(skillRel, 'SKILL.md'), text: body },
+      { rel: join(skillRel, 'SKILL.md'), text: body, isReference: false },
       ...references.map((path, index) => ({
         rel: join(skillRel, path),
         text: referenceTexts[index] ?? '',
+        isReference: true,
       })),
     ],
   }
@@ -257,6 +285,14 @@ function declared(value: string | undefined): string | undefined {
   return trimmed === undefined || trimmed === '' ? undefined : trimmed
 }
 
+/** Every H2 outside a fence, the one level both exact-section checks read. */
+function sectionsOf(source: string): string[] {
+  return bodyLines(source)
+    .filter((line) => !line.fenced)
+    .map((line) => SECTION.exec(line.text)?.[1])
+    .filter((text): text is string => text !== undefined)
+}
+
 function headings(source: string): string[] {
   return source
     .split('\n')
@@ -311,7 +347,7 @@ function missingPracticeSkills(
 ): SkillFinding[] {
   if (!hasShippedCorpus) return []
   const found = new Set(sources.map((source) => source.rel))
-  return PRACTICE_SKILLS.filter((rel) => !found.has(rel)).map((rel) => ({
+  return LEDGER_SKILLS.filter((rel) => !found.has(rel)).map((rel) => ({
     rel,
     detail: 'missing skill: no folder under the shipped corpus',
   }))
@@ -323,14 +359,15 @@ function missingPracticeSkills(
  * standard never names.
  */
 function practiceFindings(source: SkillSource): SkillFinding[] {
-  if (!PRACTICE_SKILLS.includes(source.rel)) return []
-
-  const sections = PRACTICE_SECTIONS.filter(
-    (section) => !source.sections.includes(section),
-  ).map((section) => ({
-    rel: source.rel,
-    detail: `missing section: ${section}`,
-  }))
+  if (!LEDGER_SKILLS.includes(source.rel)) return []
+
+  const isPractice = PRACTICE_SKILLS.includes(source.rel)
+  const sections = (isPractice ? PRACTICE_SECTIONS : [])
+    .filter((section) => !source.sections.includes(section))
+    .map((section) => ({
+      rel: source.rel,
+      detail: `missing section: ${section}`,
+    }))
   const ledger = source.hasLedger
     ? []
     : [{ rel: source.rel, detail: `missing ledger: ${PRACTICE_LEDGER}` }]
@@ -338,6 +375,23 @@ function practiceFindings(source: SkillSource): SkillFinding[] {
   return [...sections, ...ledger]
 }
 
+/**
+ * Reads references alone, since `SKILL.md` carries its own length checkpoint
+ * and no contents rule. Frontmatter counts toward the length, so the count a
+ * finding names is the one `wc -l` prints beside it.
+ */
+function contentsFindings(source: SkillText): SkillFinding[] {
+  if (!source.isReference) return []
+
+  const lines = source.text.replace(/\n$/, '').split('\n').length
+  if (lines <= CONTENTS_THRESHOLD) return []
+  if (sectionsOf(source.text).includes(CONTENTS_SECTION)) return []
+
+  return [
+    { rel: source.rel, detail: `${lines} lines, no ## ${CONTENTS_SECTION}` },
+  ]
+}
+
 /**
  * A date inside a fence or a code span is example data a reader is shown, such
  * as a sample frontmatter block, so only prose outside both is read.

package/src/client-commands.ts

@@ -1,4 +1,4 @@
-import { escapeForPattern, isMarked } from '@/exempt-marker'
+import { escapeForPattern, isMarked } from '@/sweep/exempt-marker'
 
 /**
  * A client command this repository quotes, with the argument spelling every

package/src/commands/claude.ts

@@ -24,8 +24,11 @@ import { listSeeds, readSeedContents } from '@/claude/seeds-list'
 import {
   auditExitCode,
   auditSkills,
+  CONTENTS_SECTION,
+  CONTENTS_THRESHOLD,
   CORPORA,
   DESCRIPTION_LIMIT,
+  LEDGER_SKILLS,
   PRACTICE_LEDGER,
   PRACTICE_SECTIONS,
   PRACTICE_SKILLS,
@@ -1398,6 +1401,7 @@ async function runSkillsAudit(
     reportRequirementShape(report)
     reportProvenance(report)
     reportPracticeShape(report)
+    reportReferenceContents(report)
     reportUnmeasured()
     outro()
   }
@@ -1421,13 +1425,16 @@ async function runSkillsAudit(
           requirementSections: report.requirementSections,
           datedProvenance: report.datedProvenance,
           practiceShape: report.practiceShape,
+          referenceContents: report.referenceContents,
         },
         checkpoints: {
           descriptionLimit: DESCRIPTION_LIMIT,
           requirementSections: REQUIREMENT_SECTIONS,
           corpora: CORPORA,
           practiceSkills: PRACTICE_SKILLS,
+          ledgerSkills: LEDGER_SKILLS,
           practiceSections: PRACTICE_SECTIONS,
+          contentsThreshold: CONTENTS_THRESHOLD,
         },
       })}\n`,
     )
@@ -1626,10 +1633,10 @@ function reportProvenance(report: SkillsAudit): void {
 function reportPracticeShape(report: SkillsAudit): void {
   logStep('Practice shape')
   logInfo(
-    `A listed practice skill closes with ${PRACTICE_SECTIONS.map((section) => `## ${section}`).join(', ')}, and carries ${PRACTICE_LEDGER}.`,
+    `A listed practice skill closes with ${PRACTICE_SECTIONS.map((section) => `## ${section}`).join(', ')}, and every skill on the wider ledger list carries ${PRACTICE_LEDGER}.`,
   )
   logInfo(
-    `The list is kept here and names ${plural(PRACTICE_SKILLS.length, 'shipped skill')}, so a skill outside ${SHIPPED_CORPUS} is never read.`,
+    `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.`,
   )
 
   if (report.practiceShape.length === 0) {
@@ -1643,6 +1650,24 @@ function reportPracticeShape(report: SkillsAudit): void {
   reportFindings(report.practiceShape)
 }
 
+/** Reports without failing the run, the same judgment the practice shape is. */
+function reportReferenceContents(report: SkillsAudit): void {
+  logStep('Reference contents')
+  logInfo(
+    `A reference over ${CONTENTS_THRESHOLD} lines opens with a ## ${CONTENTS_SECTION} list, matched exactly outside fences.`,
+  )
+
+  if (report.referenceContents.length === 0) {
+    logInfo('Every long reference opens with a contents list.')
+    return
+  }
+
+  logWarn(
+    `${plural(report.referenceContents.length, 'long reference')} with no contents list`,
+  )
+  reportFindings(report.referenceContents)
+}
+
 /**
  * Stated on every run, including the run where everything above passed. A
  * report that lists only what it measured reads as a verdict on the standard

package/src/commands/design.ts

@@ -6,30 +6,22 @@ import {
   DESIGN_INSTALL_DIR,
   DESIGN_PROJECT_SUBDIR,
 } from '@/design/adapter'
-import { generateBoard } from '@/design/board'
 import { buildDesignCss } from '@/design/css'
 import { HAND_DRAWN_FONT_FACES } from '@/design/fonts'
 import { renderDesignDoc } from '@/design/render'
 import { DESIGN_BASE_CSS, DESIGN_DOCUMENT, regenDesign } from '@/design/regen'
-import {
-  checkoutMismatchWarning,
-  isOwnCheckout,
-  PROJECT_ROOT,
-} from '@/project-root'
+import { checkoutMismatchWarning, PROJECT_ROOT } from '@/project-root'
 import { creationRel, SCRATCH } from '@/record-root'
 import { surfaceDir } from '@/surface-root'
 import { recordStamp, runDomainSync } from '@/sync/engine'
 import { resolveTarget } from '@/target'
 import { intro, logAdd, logError, logInfo, logWarn, outro, palette } from '@/ui'
-import { mainWorktreeRoot } from '@/worktree'
 
 export function register(program: Command): void {
   const design = program
     .command('design')
     .helpOption('-h, --help', 'Show this help message')
-    .description(
-      'Design system commands (regen, css, render, board, install, sync)',
-    )
+    .description('Design system commands (regen, css, render, install, sync)')
 
   design
     .command('regen')
@@ -145,60 +137,6 @@ export function register(program: Command): void {
       )
     })
 
-  design
-    .command('board')
-    .helpOption('-h, --help', 'Show this help message')
-    .description(
-      'Generate the design board, an index over a project’s design surfaces',
-    )
-    .option(
-      '-o, --out <path>',
-      'Output directory',
-      creationRel(process.cwd(), SCRATCH, 'render', 'board'),
-    )
-    .option('--root <path>', 'Project root, defaulting to the main worktree')
-    .addHelpText(
-      'after',
-      [
-        '',
-        'Reads its sources from --root, defaulting to the main worktree of',
-        'whatever project the caller stands in, and writes a static page',
-        'set, never installed or synced. The surfaces panel’s landing-page',
-        'half and the whole components panel render only when that root is',
-        'this toolkit’s own checkout. Open the result with canon serve <out>.',
-        '',
-      ].join('\n'),
-    )
-    .action(async (opts: { out: string; root?: string }) => {
-      const outDir = resolve(process.cwd(), opts.out)
-      const root = opts.root
-        ? resolve(process.cwd(), opts.root)
-        : await mainWorktreeRoot()
-      const isToolkitCheckout = isOwnCheckout(root)
-      const { GREEN, GREY, NC, RED, WHITE } = palette(process.stderr)
-      const mismatch = checkoutMismatchWarning(process.cwd())
-      process.stderr.write(
-        `${GREY}┌${NC}\n${GREY}│${NC} ${WHITE}Generate design board${NC}\n`,
-      )
-      if (mismatch !== undefined) logWarn(mismatch)
-      const result = generateBoard(
-        root,
-        outDir,
-        process.cwd(),
-        isToolkitCheckout,
-      )
-      if (!result.ok) {
-        process.stderr.write(
-          `${GREY}│${NC} ${RED}✗${NC} ${result.detail}\n${GREY}└${NC}\n`,
-        )
-        process.exitCode = 1
-        return
-      }
-      process.stderr.write(
-        `${GREY}│${NC} ${GREEN}✓${NC} ${relative(process.cwd(), result.indexPath)}\n${GREY}│${NC}   Open with: canon serve ${relative(process.cwd(), result.outDir)}\n${GREY}└${NC}\n`,
-      )
-    })
-
   design
     .command('install')
     .description('Install the base stylesheet into a project')

package/src/commands/feedback.ts

@@ -7,11 +7,11 @@ import {
   deriveTitle,
   missingField,
   missingFieldMessage,
-} from '@/commands/feedback-format'
+} from '@/feedback/body'
 import { checkoutMismatchWarning, PROJECT_ROOT } from '@/project-root'
 import { creationRel } from '@/record-root'
-import { createGithubIssue } from '@/github'
-import { issueFailureMessage } from '@/github-format'
+import { createGithubIssue } from '@/feedback/github'
+import { issueFailureMessage } from '@/feedback/github-format'
 import { frameError, frameSuccess, logWarn, palette } from '@/ui'
 
 function readStdin(): Promise<string> {