@erclx/canon 5.25.0 → 5.27.0

package/src/capture/render.ts

@@ -2,9 +2,13 @@ import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { basename, dirname } from 'node:path'
 import { pathToFileURL } from 'node:url'
 import { chromium } from 'playwright-core'
-import type { Browser, Page } from 'playwright-core'
+import type { Browser, Locator, Page } from 'playwright-core'
 import type { CaptureSource } from '@/capture/sources'
-import { primaryFontFamily, resolveCaptureSources } from '@/capture/sources'
+import {
+  isGenericFamily,
+  resolveCaptureSources,
+  textFamilies,
+} from '@/capture/sources'
 import { formatStamp, hashSource, stampPath } from '@/capture/stamp'
 
 /**
@@ -97,15 +101,22 @@ async function captureOne(
     }
 
     await page.evaluate(() => document.fonts.ready.then(() => undefined))
-    const family = primaryFontFamily(
-      await element.evaluate((node) => getComputedStyle(node).fontFamily),
-    )
-    if (family && !(await resolvesFont(page, family))) {
+    const declarations = await renderedTextFamilies(element)
+    const generic = declarations.find(isGenericFamily)
+    if (generic !== undefined) {
       return failed(
         source,
-        `${family} is not installed, so the capture would rewrap against a fallback`,
+        `${generic.split(',')[0]?.trim()} is a generic family that resolves differently per machine, so name a real font`,
       )
     }
+    for (const family of textFamilies(declarations)) {
+      if (!(await resolvesFont(page, family))) {
+        return failed(
+          source,
+          `${family} is not installed, so the capture would rewrap against a fallback`,
+        )
+      }
+    }
 
     mkdirSync(dirname(source.pngPath), { recursive: true })
     const png = await element.screenshot({ omitBackground: true })
@@ -170,6 +181,33 @@ function failed(source: CaptureSource, reason: string): CaptureResult {
   return { status: 'failed', source: sourceIdentifier(source), reason }
 }
 
+/**
+ * The computed families of the captured element and of each element under it
+ * holding a non-blank text node of its own that draws a box, which is the text
+ * the screenshot shows. Testing the text node's box rather than the element's
+ * keeps out `<style>`, `<script>`, `<title>`, and anything hidden, whose
+ * computed family is the browser default and would refuse every source that
+ * styles a descendant rather than the root, and keeps in text directly inside a
+ * `display: contents` element, which draws no box of its own.
+ *
+ * Returns nothing when no element holds text, since a font cannot rewrap text
+ * that is not there, so a container of iframes skips the probe.
+ */
+async function renderedTextFamilies(element: Locator): Promise<string[]> {
+  return element.evaluate((root) => {
+    const range = document.createRange()
+    const holdsText = (node: Element): boolean =>
+      [...node.childNodes].some((child) => {
+        if (child.nodeType !== Node.TEXT_NODE) return false
+        if ((child.textContent ?? '').trim() === '') return false
+        range.selectNodeContents(child)
+        return range.getClientRects().length > 0
+      })
+    const texts = [root, ...root.querySelectorAll('*')].filter(holdsText)
+    return texts.map((node) => getComputedStyle(node).fontFamily)
+  })
+}
+
 /**
  * Compares the family's text metrics against a family that cannot exist. Equal
  * widths mean the browser fell through to its default for both, which is the

package/src/capture/sources.ts

@@ -66,3 +66,46 @@ export function primaryFontFamily(declaration: string): string {
   const first = declaration.split(',')[0]?.trim() ?? ''
   return first.replace(/^['"]|['"]$/g, '')
 }
+
+/**
+ * The CSS generic family keywords. A generic names no font, so each machine
+ * maps it to whatever it has, and a capture measured against one cannot
+ * reproduce on another.
+ */
+export const GENERIC_FAMILIES: ReadonlySet<string> = new Set([
+  'serif',
+  'sans-serif',
+  'monospace',
+  'cursive',
+  'fantasy',
+  'system-ui',
+  'ui-serif',
+  'ui-sans-serif',
+  'ui-monospace',
+  'ui-rounded',
+  'math',
+  'emoji',
+  'fangsong',
+])
+
+/**
+ * Whether the first family of a computed `font-family` is a generic keyword.
+ * Takes the raw declaration rather than `primaryFontFamily`'s result, since
+ * quoting is what separates the keyword from a family that happens to share its
+ * name, and the stripped form has lost it. Keywords match case-insensitively.
+ */
+export function isGenericFamily(declaration: string): boolean {
+  const first = declaration.split(',')[0]?.trim() ?? ''
+  return GENERIC_FAMILIES.has(first.toLowerCase())
+}
+
+/**
+ * Reduces the computed `font-family` of each rendered text element to the
+ * distinct families a capture has to prove resolved, in document order, so a
+ * frame that sets its font on any ancestor of its text is checked against the
+ * face the text actually draws in.
+ */
+export function textFamilies(declarations: readonly string[]): string[] {
+  const families = declarations.map(primaryFontFamily).filter(Boolean)
+  return [...new Set(families)]
+}

package/src/census/count.ts

@@ -1,7 +1,7 @@
 import { readFile } from 'node:fs/promises'
 import { extname, join } from 'node:path'
-import { isBinary } from '@/binary'
-import { listRepositoryFiles } from '@/git-files'
+import { isBinary } from '@/sweep/binary'
+import { listRepositoryFiles } from '@/git/files'
 
 export type CensusRefusal = 'no-git'
 

package/src/claude/cases/workflow.ts

@@ -146,6 +146,11 @@ export const WORKFLOW_CASES: readonly SkillCase[] = [
       'Which of our docs have gone stale, grown too long, or ended up in the wrong file?',
     expect: 'document-health',
   },
+  {
+    prompt:
+      'Are our requirements and architecture docs still true, and when were they last reviewed?',
+    expect: 'document-health',
+  },
   {
     prompt: 'Open a new entry on the task board for this piece of work.',
     expect: 'task-board',

package/src/claude/seeds.ts

@@ -1,9 +1,9 @@
 import { existsSync } from 'node:fs'
 import { chmod, mkdir, readFile, writeFile } from 'node:fs/promises'
 import { dirname, join, relative } from 'node:path'
-import { copyPreservingMode } from '@/copy'
+import { copyPreservingMode } from '@/sync/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')

package/src/claude/skills-audit.ts

@@ -1,5 +1,6 @@
 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'
 
@@ -40,6 +41,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 +68,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 +128,8 @@ export interface SkillsAudit {
   readonly requirementSections: readonly SkillFinding[]
   readonly datedProvenance: readonly SkillFinding[]
   readonly practiceShape: readonly SkillFinding[]
+  readonly referenceContents: readonly SkillFinding[]
+  readonly family: readonly SkillFinding[]
 }
 
 interface SkillSource {
@@ -110,6 +138,8 @@ interface SkillSource {
   readonly hasReadme: boolean
   readonly name: string | undefined
   readonly description: string | undefined
+  /** `metadata.family`, undefined when absent, blank, or not a string. */
+  readonly family: string | undefined
   /** Undefined when the folder carries no `REQUIREMENT.md` at all. */
   readonly requirementHeadings: readonly string[] | undefined
   /** Every H2 in `SKILL.md` outside a fence, for the practice shape. */
@@ -126,6 +156,7 @@ interface SkillSource {
 interface SkillText {
   readonly rel: string
   readonly text: string
+  readonly isReference: boolean
 }
 
 /**
@@ -177,6 +208,10 @@ export async function auditSkills(root: string): Promise<SkillsAudit> {
       ),
       ...sources.flatMap(practiceFindings),
     ],
+    referenceContents: sources.flatMap((source) =>
+      source.bodies.flatMap(contentsFindings),
+    ),
+    family: sources.flatMap(familyFindings),
   }
 }
 
@@ -231,18 +266,17 @@ async function readSkill(
     hasReadme: existsSync(join(skillDir, 'README.md')),
     name: declared(readField(fields, 'name')),
     description: declared(readField(fields, 'description')),
+    family: declaredFamily(fields?.fields.metadata),
     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 +291,21 @@ function declared(value: string | undefined): string | undefined {
   return trimmed === undefined || trimmed === '' ? undefined : trimmed
 }
 
+function declaredFamily(metadata: unknown): string | undefined {
+  if (typeof metadata !== 'object' || metadata === null) return undefined
+  if (Array.isArray(metadata)) return undefined
+  const { family } = metadata as Record<string, unknown>
+  return typeof family === 'string' ? declared(family) : undefined
+}
+
+/** 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 +360,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 +372,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 +388,38 @@ function practiceFindings(source: SkillSource): SkillFinding[] {
   return [...sections, ...ledger]
 }
 
+/**
+ * Asks only the shipped corpus for a family, since the family names the skill
+ * map group a skill's row sits under and an internal skill takes no row.
+ */
+function familyFindings(source: SkillSource): SkillFinding[] {
+  if (dirname(source.rel) !== SHIPPED_CORPUS) return []
+  if (source.family === undefined) {
+    return [
+      { rel: source.rel, detail: 'frontmatter declares no metadata.family' },
+    ]
+  }
+  if (isFamilyKey(source.family)) return []
+  return [{ rel: source.rel, detail: `unknown family: ${source.family}` }]
+}
+
+/**
+ * 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/claude/skills-drift.ts

@@ -1,7 +1,7 @@
 import { existsSync } from 'node:fs'
 import { join } from 'node:path'
 import { execaSync } from 'execa'
-import { gitEnv } from '@/git-env'
+import { gitEnv } from '@/git/env'
 
 /**
  * The shipped corpus alone. A session loads a body from the plugin root, which

package/src/claude/skills-families.ts

@@ -0,0 +1,36 @@
+export interface SkillFamily {
+  /** The value a shipped `SKILL.md` declares as `metadata.family`. */
+  readonly key: string
+  /** The skill map heading the family's rows sit under, verbatim. */
+  readonly group: string
+}
+
+/**
+ * The one vocabulary a shipped skill's family is drawn from, in the order the
+ * skill map reads across its two pages. A heading is the map's prose and a key
+ * is what frontmatter carries, so renaming a heading touches this constant and
+ * no skill.
+ *
+ * Import-free on purpose: `skills-list.ts` and `skills-audit.ts` both read it,
+ * and the first already imports the second.
+ */
+export const SKILL_FAMILIES: readonly SkillFamily[] = [
+  { key: 'setup', group: 'Set up a project' },
+  { key: 'decide', group: 'Decide what to build' },
+  { key: 'build', group: 'Build the feature' },
+  { key: 'check', group: 'Check the work before it leaves the branch' },
+  { key: 'ship', group: 'Ship it' },
+  { key: 'after-pr', group: 'After the pull request opens' },
+  { key: 'parallel', group: 'Run several tracks at once' },
+  { key: 'upkeep', group: 'Keep the project current with the toolkit' },
+  { key: 'generate', group: 'Generate an artifact on demand' },
+  { key: 'answer', group: 'Answer a question at any point' },
+]
+
+export function familyKeys(): string[] {
+  return SKILL_FAMILIES.map((family) => family.key)
+}
+
+export function isFamilyKey(value: string): boolean {
+  return SKILL_FAMILIES.some((family) => family.key === value)
+}

package/src/claude/skills-list.ts

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { CORPORA } from '@/claude/skills-audit'
+import { isFamilyKey, SKILL_FAMILIES } from '@/claude/skills-families'
 
 const FRONTMATTER = /^---\n([\s\S]*?)\n---/
 
@@ -8,6 +9,11 @@ export interface SkillListing {
   readonly name: string
   readonly description: string
   readonly requirement: boolean
+  /**
+   * The `metadata.family` the frontmatter declares, read as written. Whether it
+   * names a vocabulary key is the audit's finding, not the listing's.
+   */
+  readonly family: string | null
 }
 
 export interface SkillsCorpus {
@@ -72,28 +78,83 @@ export function listSkillsAt(skillsRoot: string): SkillListing[] {
     }),
   ].sort()
 
-  return paths.map((path) => ({
-    name: dirname(path),
-    description: readDescription(join(skillsRoot, path)),
-    requirement: existsSync(join(skillsRoot, dirname(path), 'REQUIREMENT.md')),
-  }))
+  return paths.map((path) => {
+    const { description, family } = readListedFields(join(skillsRoot, path))
+    return {
+      name: dirname(path),
+      description,
+      requirement: existsSync(
+        join(skillsRoot, dirname(path), 'REQUIREMENT.md'),
+      ),
+      family,
+    }
+  })
+}
+
+export interface FamilyGroup {
+  readonly key: string
+  readonly group: string
+  readonly skills: readonly string[]
+}
+
+export interface FamilyGrouping {
+  /** Vocabulary order, holding only the families some listing declares. */
+  readonly groups: readonly FamilyGroup[]
+  /** Listings whose family is missing or names no vocabulary key. */
+  readonly unassigned: readonly string[]
+}
+
+export function groupByFamily(
+  listings: readonly SkillListing[],
+): FamilyGrouping {
+  const groups = SKILL_FAMILIES.map((family) => ({
+    ...family,
+    skills: listings
+      .filter((listing) => listing.family === family.key)
+      .map((listing) => listing.name),
+  })).filter((group) => group.skills.length > 0)
+
+  return {
+    groups,
+    unassigned: listings
+      .filter(
+        (listing) => listing.family === null || !isFamilyKey(listing.family),
+      )
+      .map((listing) => listing.name),
+  }
+}
+
+interface ListedFields {
+  readonly description: string
+  readonly family: string | null
 }
 
 /**
- * Returns an empty description rather than throwing on a skill whose
- * frontmatter is missing or unparseable, so one malformed file does not hide
- * the rest of the catalog from a caller counting it.
+ * Returns an empty description and a null family rather than throwing on a
+ * skill whose frontmatter is missing or unparseable, so one malformed file
+ * does not hide the rest of the catalog from a caller counting it.
  */
-function readDescription(path: string): string {
+function readListedFields(path: string): ListedFields {
+  const empty = { description: '', family: null }
   const match = FRONTMATTER.exec(readFileSync(path, 'utf8'))
-  if (!match) return ''
+  if (!match) return empty
 
+  let parsed: unknown
   try {
-    const parsed = Bun.YAML.parse(match[1])
-    if (typeof parsed !== 'object' || parsed === null) return ''
-    const { description } = parsed as Record<string, unknown>
-    return typeof description === 'string' ? description : ''
+    parsed = Bun.YAML.parse(match[1])
   } catch {
-    return ''
+    return empty
   }
+  if (!isRecord(parsed)) return empty
+
+  const { description, metadata } = parsed
+  const family = isRecord(metadata) ? metadata.family : undefined
+  return {
+    description: typeof description === 'string' ? description : '',
+    family: typeof family === 'string' ? family : null,
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
 }

package/src/commands/audits.ts

@@ -19,9 +19,9 @@ import {
   type Summary,
   summarize,
 } from '@/audits/run'
-import { gitEnv } from '@/git-env'
+import { gitEnv } from '@/git/env'
 import { intro, logError, logInfo, logStep, logWarn, outro, plural } from '@/ui'
-import { currentWorktreeRoot } from '@/worktree'
+import { currentWorktreeRoot } from '@/git/worktree'
 
 interface RunCommandOptions {
   readonly json?: boolean