@erclx/canon 4.0.0

package/src/claude/cases/claude-workflow.ts

@@ -0,0 +1,158 @@
+import type { SkillCase } from '@/claude/skills-rank'
+
+/**
+ * The `claude-*` skill family: feature planning, review, and the session
+ * artifacts that coordinate work across sessions.
+ *
+ * Every positive is phrased away from its skill's own quoted trigger, since a
+ * verbatim trigger passes by construction and proves nothing about a prompt in
+ * someone's own words. Negatives target the pairs whose bodies already state
+ * an explicit `Do NOT` boundary against each other, since a boundary in a
+ * body does not reach the field a router reads.
+ */
+export const CLAUDE_WORKFLOW_CASES: readonly SkillCase[] = [
+  {
+    prompt: 'Go fix everything the reviewer flagged on my open PR.',
+    expect: 'claude-address-review',
+  },
+  {
+    prompt:
+      'Run the whole implement, verify, review, and ship pipeline for the approved plan.',
+    expect: 'claude-autoship',
+  },
+  {
+    prompt: "Pull together a design system from what's already in the app.",
+    expect: 'claude-design-extract',
+  },
+  {
+    prompt: 'Draw me a diagram of how the pieces of this system connect.',
+    expect: 'claude-diagram',
+  },
+  {
+    prompt:
+      'Bring the internal planning docs under .claude up to date with what we decided this session.',
+    expect: 'claude-docs',
+  },
+  {
+    prompt:
+      'Sketch out a plan for adding this new capability before we touch any code.',
+    expect: 'claude-feature',
+  },
+  {
+    prompt:
+      'We need to measure this properly before committing to an approach.',
+    expect: 'claude-groundwork',
+  },
+  {
+    prompt: 'Take this pile of raw notes and turn it into filed items.',
+    expect: 'claude-intake',
+  },
+  {
+    prompt: 'Walk me through the open intake items so I can decide on each.',
+    expect: 'claude-intake-answer',
+  },
+  {
+    prompt:
+      "Draft a diff-based proposal for tightening this passage in the standard, don't just edit it.",
+    expect: 'claude-markdown-propose',
+  },
+  {
+    prompt: 'Pull the durable lessons out of this session before it ends.',
+    expect: 'claude-memory-capture',
+  },
+  {
+    prompt:
+      'Go through the memory folder and propose what to do with each entry.',
+    expect: 'claude-memory-review',
+  },
+  {
+    prompt:
+      'Take on the orchestrator role and coordinate the parallel feature builds.',
+    expect: 'claude-orchestrate',
+  },
+  {
+    prompt: 'Post a formal review with findings on that open pull request.',
+    expect: 'claude-pr-review',
+  },
+  {
+    prompt:
+      'Look over everything that changed on this branch for bugs and edge cases.',
+    expect: 'claude-review',
+  },
+  {
+    prompt: 'Draft me a script with beats for a screencast recording.',
+    expect: 'canon-screencast',
+  },
+  {
+    prompt:
+      "Check whether my installed Claude seed docs have drifted from the toolkit's.",
+    expect: 'claude-seed-sync',
+  },
+  {
+    prompt: 'Turn this topic into a slide deck I can render.',
+    expect: 'canon-slides-draft',
+  },
+  {
+    prompt:
+      'Check whether the markdown I changed violates any authoring standards.',
+    expect: 'claude-standards-audit',
+  },
+  {
+    prompt: 'Open a new entry on the task board for this piece of work.',
+    expect: 'claude-tasks',
+  },
+  {
+    prompt: 'Open a learning workspace so I can study this topic properly.',
+    expect: 'claude-teach',
+  },
+  {
+    prompt: 'Generate the Playwright tests I need after this UI change.',
+    expect: 'claude-ui-test',
+  },
+  {
+    prompt:
+      'Look over the interface and tell me what feels unfinished or confusing.',
+    expect: 'claude-ux-audit',
+  },
+  {
+    prompt: 'Tell me the paint and layout cost of this page right now.',
+    expect: 'claude-ux-measure',
+  },
+  {
+    prompt:
+      'I am building this branch for another session. What am I on the hook for, and what is off limits?',
+    expect: 'claude-worker',
+  },
+  {
+    prompt: 'Get me set up in a fresh Claude Code worktree for this branch.',
+    expect: 'claude-worktree',
+  },
+
+  // Negatives: pairs whose bodies already carry an explicit Do NOT boundary.
+  {
+    prompt:
+      'Refresh the stale sections of README and the docs folder based on what changed.',
+    expect: 'docs-sync',
+  },
+  {
+    prompt: 'Sort through this brain dump and write it up as findings.',
+    expect: 'claude-intake',
+  },
+  {
+    prompt:
+      "Go through what's still unanswered in the intake folder and decide.",
+    expect: 'claude-intake-answer',
+  },
+  {
+    prompt: 'Check this markdown against the house style rules.',
+    expect: 'claude-standards-audit',
+  },
+  {
+    prompt: 'Find the rough, unfinished-feeling spots in this interface.',
+    expect: 'claude-ux-audit',
+  },
+  {
+    prompt: 'Tell me the render cost of this page in the browser.',
+    expect: 'claude-ux-measure',
+  },
+]

package/src/claude/cases/git.ts

@@ -0,0 +1,44 @@
+import type { SkillCase } from '@/claude/skills-rank'
+
+/** The `git-*` skill family: branch, commit, and pull-request mechanics. */
+export const GIT_CASES: readonly SkillCase[] = [
+  {
+    prompt: 'Come up with a conventional name for this branch.',
+    expect: 'git-branch',
+  },
+  {
+    prompt: "Turn what's staged into one commit message.",
+    expect: 'git-commit',
+  },
+  {
+    prompt: "Push a quick follow-up fix onto the PR that's already open.",
+    expect: 'git-followup',
+  },
+  {
+    prompt: 'Turn this bug into a GitHub issue and file it.',
+    expect: 'git-issue',
+  },
+  {
+    prompt: 'Write the title and body for this pull request.',
+    expect: 'git-pr',
+  },
+  {
+    prompt: 'Take this finished feature all the way through to an opened PR.',
+    expect: 'git-ship',
+  },
+  {
+    prompt:
+      'This branch has unrelated commits mixed together, break it into separate branches.',
+    expect: 'git-split',
+  },
+  {
+    prompt:
+      'These staged changes cover more than one concern, commit them separately.',
+    expect: 'git-stage',
+  },
+  {
+    prompt:
+      'Show me the linked worktrees and clear out the ones already merged.',
+    expect: 'git-worktree',
+  },
+]

package/src/claude/cases/misc.ts

@@ -0,0 +1,27 @@
+import type { SkillCase } from '@/claude/skills-rank'
+
+/** Skills that share no prefix with any other domain file here. */
+export const MISC_CASES: readonly SkillCase[] = [
+  {
+    prompt:
+      'Bundle up every open call that only I can make and ask me all at once.',
+    expect: 'decision-escalate',
+  },
+  {
+    prompt: 'Fire up the dev server the way this project documents it.',
+    expect: 'project-commands',
+  },
+  {
+    prompt:
+      "We're about to hit the context limit, write the handoff before we lose state.",
+    expect: 'session-map',
+  },
+  {
+    prompt: 'Catch me up on what was in progress before this session started.',
+    expect: 'session-resume',
+  },
+  {
+    prompt: "This test just started failing and I don't know why yet.",
+    expect: 'systematic-debugging',
+  },
+]

package/src/claude/cases/setup.ts

@@ -0,0 +1,94 @@
+import type { SkillCase } from '@/claude/skills-rank'
+
+/**
+ * `setup-*`, `migration-*`, `canon-*`, and `create-rule`: scaffolding,
+ * proposal-only migrations, and the toolkit's own reference and feedback
+ * surfaces.
+ */
+export const SETUP_CASES: readonly SkillCase[] = [
+  {
+    prompt:
+      'This project has no rules installed yet, get the right governance in place.',
+    expect: 'setup-gov',
+  },
+  {
+    prompt:
+      "Get the index.md system bootstrapped across this project's folders.",
+    expect: 'setup-indexes',
+  },
+  {
+    prompt:
+      'This is a brand-new project, get the toolkit bootstrapped in one shot.',
+    expect: 'setup-init',
+  },
+  {
+    prompt: 'Get the usual Claude Code plugins provisioned on this machine.',
+    expect: 'setup-plugins',
+  },
+  {
+    prompt:
+      "Run through the generated scaffold's scripts and confirm each one passes.",
+    expect: 'setup-verify',
+  },
+  {
+    prompt:
+      'This CLAUDE.md file has grown huge, break it apart into the tiered context model.',
+    expect: 'migration-claude-md',
+  },
+  {
+    prompt:
+      'Move the agent-flavored docs out of the docs folder and into context.',
+    expect: 'migration-context',
+  },
+  {
+    prompt:
+      'This file was replaced by a folder, help me split its content into it.',
+    expect: 'migration-superseded',
+  },
+  {
+    prompt:
+      'This project still carries a copy of the standards folder, get rid of it and point everything at the CLI.',
+    expect: 'migration-standards-drop',
+  },
+  {
+    prompt:
+      "Before I run this sync, tell me exactly what it's going to overwrite.",
+    expect: 'canon-cli',
+  },
+  {
+    prompt:
+      'Something about the toolkit itself is broken, write it up and send it back to the maintainers.',
+    expect: 'canon-feedback-file',
+  },
+  {
+    prompt:
+      "I don't know which specific toolkit skill I need, just handle it for me.",
+    expect: 'canon-operator',
+  },
+  // The performing skill wins a phrase naming its operation over the front
+  // door's own routing framing, even though canon-operator's description
+  // quotes a phrase near this one. See .claude/context/cli/audits.md.
+  {
+    prompt:
+      "Whatever the right toolkit command is, get this project's rules installed.",
+    expect: 'setup-gov',
+  },
+  {
+    prompt:
+      'Work through the open feedback issues on the toolkit repo one by one.',
+    expect: 'canon-feedback-triage',
+  },
+  // The outbound direction is what separates this from the front door above.
+  // canon-operator runs inside one project the session already stands in, and
+  // this reaches every project the toolkit installed into from the toolkit.
+  {
+    prompt:
+      'Take this change out to every project that installed the toolkit and get each one to a pull request.',
+    expect: 'canon-rollout',
+  },
+  {
+    prompt:
+      "This project needs its own coding rule that the toolkit doesn't ship.",
+    expect: 'create-rule',
+  },
+]

package/src/claude/gitignore.ts

@@ -0,0 +1,51 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { mergeSections } from '@/tooling/gitignore'
+import { type Manifest, resolveChain } from '@/tooling/manifest'
+
+export const CLAUDE_STACK = 'claude'
+
+export interface GitignoreEntry {
+  readonly entry: string
+  readonly present: boolean
+}
+
+export function claudeChain(root: string): Manifest[] {
+  return resolveChain(root, CLAUDE_STACK)
+}
+
+/**
+ * Previews the gitignore merge without writing. The answer comes from
+ * `mergeSections`, the same function the apply step runs, so the preview can
+ * never disagree with what lands.
+ *
+ * The bash matched the manifest's `[gitignore]` table with a line regex that
+ * required the array to open and close on one line, and it re-parsed TOML that
+ * `loadManifest` already reads. Routing through the manifest loader drops both
+ * problems.
+ */
+export function planGitignore(
+  chain: readonly Manifest[],
+  target: string,
+): GitignoreEntry[] {
+  const path = join(target, '.gitignore')
+  const content = existsSync(path) ? readFileSync(path, 'utf8') : ''
+  const entries: GitignoreEntry[] = []
+
+  for (const manifest of chain) {
+    const added = new Set(mergeSections(content, manifest.gitignore).added)
+    for (const section of manifest.gitignore) {
+      for (const entry of section.entries) {
+        entries.push({ entry, present: !added.has(entry) })
+      }
+    }
+  }
+
+  return entries
+}
+
+export function pendingEntries(
+  entries: readonly GitignoreEntry[],
+): GitignoreEntry[] {
+  return entries.filter((entry) => !entry.present)
+}

package/src/claude/routing.ts

@@ -0,0 +1,283 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const CLAUDE_MD = 'CLAUDE.md'
+const RULES_DIR = join('.claude', 'rules')
+
+/** A backticked token, which is how the always-loaded file spells a path. */
+const TOKEN = /`([^`\s]+)`/g
+
+/**
+ * A path a reader could open. Admits no `$`, `*`, or `=`, so an assignment
+ * (`CANON_NON_INTERACTIVE=1`) and a variable are both excluded.
+ */
+const PATH_TOKEN = /^[.A-Za-z0-9_][A-Za-z0-9._/-]*$/
+
+/** A placeholder segment, which a shape carries and a real path does not. */
+const SHAPE = /<[^>]*>/
+
+/** An alphabetic extension, which separates `cspell.json` from `3.6.0`. */
+const EXTENSION = /\.[a-z]{2,5}$/
+
+/** Extensions a folder is probed with, so a glob narrowed by type still hits. */
+const PROBES = ['probe.md', 'probe.ts', 'probe.tsx', 'probe.sh', 'probe.json']
+
+export interface RuleGlobs {
+  /** Path under `.claude/rules/`, which is how a reader cites a rule. */
+  readonly rule: string
+  readonly globs: readonly string[]
+}
+
+export interface Section {
+  /** `Behavior` for an H2, `Behavior / Scope` for the H3 beneath it. */
+  readonly heading: string
+  /** The top-level bullet lines the heading owns, in reading order. */
+  readonly lines: readonly string[]
+}
+
+export interface SectionReport {
+  readonly heading: string
+  readonly bullets: number
+  /** Bullets naming at least one path, which is the reading this measures. */
+  readonly pathScoped: number
+  /** Path-scoped bullets whose named path some rule glob already reaches. */
+  readonly covered: number
+  /** Distinct named paths no rule glob reaches, in reading order. */
+  readonly uncovered: readonly string[]
+}
+
+/** Why a scan produced no reading, which is never the same as a clean one. */
+export type RoutingRefusal = 'no-claude-md' | 'no-rules'
+
+export type RoutingReport =
+  | {
+      readonly kind: 'measured'
+      readonly rules: number
+      readonly sections: readonly SectionReport[]
+    }
+  | { readonly kind: 'refused'; readonly reason: RoutingRefusal }
+
+/**
+ * Every distinct path one bullet names, in reading order.
+ *
+ * Naming a path is what this measures, not firing only on it. A bullet can
+ * name a folder and still apply every session, and one can fire on a path it
+ * never spells, so the count is a reading a person still has to judge.
+ */
+export function namedPaths(line: string): string[] {
+  const paths: string[] = []
+
+  for (const match of line.matchAll(TOKEN)) {
+    const token = concretePrefix(match[1])
+    if (token === undefined) continue
+    if (!PATH_TOKEN.test(token)) continue
+    if (!token.includes('/') && !EXTENSION.test(token)) continue
+    if (!paths.includes(token)) paths.push(token)
+  }
+
+  return paths
+}
+
+/**
+ * The openable part of a token, which for a shape is the folder above the
+ * placeholder.
+ *
+ * `.claude/context/<domain>.md` names `.claude/context/` and nothing narrower,
+ * so dropping the whole token would report the section that carries it as
+ * naming no path at all. A token whose placeholder sits in the first segment
+ * has no openable prefix and is dropped.
+ */
+function concretePrefix(token: string): string | undefined {
+  if (!SHAPE.test(token)) return token
+
+  const prefix = token.slice(0, token.indexOf('<'))
+  return prefix.endsWith('/') ? prefix : undefined
+}
+
+/**
+ * Splits the file into the sections a reader sees, counting top-level bullets.
+ *
+ * A nested bullet belongs to the one above it rather than to the section, and
+ * a fenced block holds example text rather than instruction, so neither is
+ * counted. A heading carrying no bullet is dropped, since the report answers
+ * how many bullets are path-scoped and a section with none answers nothing.
+ */
+export function splitSections(text: string): Section[] {
+  const sections: Section[] = []
+  let parent = ''
+  let heading: string | undefined
+  let lines: string[] = []
+  let fenced = false
+
+  const flush = (): void => {
+    if (heading !== undefined && lines.length > 0)
+      sections.push({ heading, lines })
+  }
+
+  const open = (next: string): void => {
+    flush()
+    heading = next
+    lines = []
+  }
+
+  for (const line of text.split('\n')) {
+    if (line.startsWith('```')) {
+      fenced = !fenced
+      continue
+    }
+    if (fenced) continue
+
+    const h2 = line.match(/^## (.+)$/)
+    if (h2) {
+      parent = h2[1]
+      open(parent)
+      continue
+    }
+
+    const h3 = line.match(/^### (.+)$/)
+    if (h3) {
+      open(parent === '' ? h3[1] : `${parent} / ${h3[1]}`)
+      continue
+    }
+
+    if (line.startsWith('- ')) lines.push(line)
+  }
+
+  flush()
+  return sections
+}
+
+/**
+ * Every path-scoped rule the tree installs, with the globs it declares.
+ *
+ * An always-on rule declares no `paths` and applies at the same priority as
+ * the always-loaded file, so it covers no path in particular and is skipped.
+ */
+export function readRuleGlobs(root: string): RuleGlobs[] {
+  const rulesRoot = join(root, RULES_DIR)
+  if (!existsSync(rulesRoot)) return []
+
+  const rules: RuleGlobs[] = []
+  const files = [
+    ...new Bun.Glob('**/*.md').scanSync({ cwd: rulesRoot, onlyFiles: true }),
+  ].sort()
+
+  for (const file of files) {
+    const text = readFileSync(join(rulesRoot, file), 'utf8')
+    const globs = [...frontmatter(text).matchAll(/^\s*-\s*'([^']+)'\s*$/gm)]
+      .map((match) => match[1])
+      .filter((glob) => glob.includes('*') || glob.includes('.'))
+
+    if (globs.length === 0) continue
+    rules.push({ rule: file.replaceAll('\\', '/'), globs })
+  }
+
+  return rules
+}
+
+/**
+ * The block between the opening and closing `---`, or nothing for a rule
+ * carrying no frontmatter.
+ *
+ * Bounding the read is what keeps a body bullet out of the glob list. A rule
+ * quoting a path in prose would otherwise register it as a scope the rule
+ * never declared, and the resulting coverage would be wrong with nothing
+ * reporting it.
+ */
+function frontmatter(text: string): string {
+  if (!text.startsWith('---\n')) return ''
+
+  const end = text.indexOf('\n---', 3)
+  return end === -1 ? '' : text.slice(4, end)
+}
+
+/**
+ * Whether a glob scopes itself to a location rather than to a file type.
+ *
+ * A glob opening `**` reaches every folder in the tree, so it answers that a
+ * file type is governed and never that a named path is. Counting one would
+ * report every markdown path covered by `501-markdown` and leave the column
+ * saying nothing a reader could act on.
+ */
+function isAnchored(glob: string): boolean {
+  return !glob.startsWith('**/')
+}
+
+/**
+ * The first rule scoping itself to a named path, or undefined for none.
+ *
+ * A folder is probed with a handful of extensions rather than matched as a
+ * literal, because a glob narrowed by file type reaches under the folder
+ * without ever matching the folder's own name.
+ */
+export function coveringRule(
+  path: string,
+  rules: readonly RuleGlobs[],
+): string | undefined {
+  const bare = path.replace(/\/+$/, '')
+  const candidates = [bare, ...PROBES.map((probe) => `${bare}/${probe}`)]
+
+  for (const { rule, globs } of rules) {
+    for (const glob of globs) {
+      if (!isAnchored(glob)) continue
+      const matcher = new Bun.Glob(glob)
+      if (candidates.some((candidate) => matcher.match(candidate))) return rule
+    }
+  }
+
+  return undefined
+}
+
+/**
+ * Reads the always-loaded file against the rules installed beside it.
+ *
+ * Measures the tree it is pointed at rather than the toolkit root, so a linked
+ * worktree reads its own branch and a target reads its own file.
+ */
+export function scanRouting(root: string): RoutingReport {
+  const file = join(root, CLAUDE_MD)
+  if (!existsSync(file)) return { kind: 'refused', reason: 'no-claude-md' }
+
+  const rules = readRuleGlobs(root)
+  if (rules.length === 0) return { kind: 'refused', reason: 'no-rules' }
+
+  const sections = splitSections(readFileSync(file, 'utf8')).map((section) =>
+    classify(section, rules),
+  )
+
+  return { kind: 'measured', rules: rules.length, sections }
+}
+
+/** Counts one section's bullets against the rules installed beside the file. */
+function classify(
+  section: Section,
+  rules: readonly RuleGlobs[],
+): SectionReport {
+  let pathScoped = 0
+  let covered = 0
+  const uncovered: string[] = []
+
+  for (const line of section.lines) {
+    const paths = namedPaths(line)
+    if (paths.length === 0) continue
+    pathScoped += 1
+
+    const reached = paths.filter(
+      (path) => coveringRule(path, rules) !== undefined,
+    )
+    if (reached.length > 0) covered += 1
+
+    for (const path of paths) {
+      if (reached.includes(path) || uncovered.includes(path)) continue
+      uncovered.push(path)
+    }
+  }
+
+  return {
+    heading: section.heading,
+    bullets: section.lines.length,
+    pathScoped,
+    covered,
+    uncovered,
+  }
+}

package/src/claude/seeds-list.ts

@@ -0,0 +1,47 @@
+import { readFile } from 'node:fs/promises'
+import { relative } from 'node:path'
+import { planSeeds } from '@/claude/seeds'
+
+export interface SeedListing {
+  readonly name: string
+  readonly source: string
+  readonly target: string
+  readonly src: string
+}
+
+export interface SeedListingWithContent {
+  readonly name: string
+  readonly source: string
+  readonly target: string
+  readonly content: string
+}
+
+/**
+ * Reads the same plan `canon claude init` applies. The bash re-globbed the seeds
+ * directory with its own hard-coded subdirectory list, which had drifted: it
+ * never listed `.claude/context/`, so a seed init installs went unreported.
+ *
+ * The target is irrelevant to a listing, so it resolves against the source
+ * root and only the source-side fields are read.
+ */
+export function listSeeds(root: string): SeedListing[] {
+  return planSeeds(root, root).map(({ seed }) => ({
+    name: seed.scanLabel,
+    source: relative(root, seed.src),
+    target: seed.applyLabel,
+    src: seed.src,
+  }))
+}
+
+export async function readSeedContents(
+  listings: readonly SeedListing[],
+): Promise<SeedListingWithContent[]> {
+  return Promise.all(
+    listings.map(async ({ name, source, target, src }) => ({
+      name,
+      source,
+      target,
+      content: await readFile(src, 'utf8'),
+    })),
+  )
+}