@erclx/canon 4.0.0

package/src/claude/skills-list.ts

@@ -0,0 +1,99 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { CORPORA } from '@/claude/skills-audit'
+
+const FRONTMATTER = /^---\n([\s\S]*?)\n---/
+
+export interface SkillListing {
+  readonly name: string
+  readonly description: string
+  readonly requirement: boolean
+}
+
+export interface SkillsCorpus {
+  /**
+   * The corpus spelling in POSIX form, so a report reads the same on Windows.
+   * `CorpusReport.rel` in `skills-audit.ts` is the same spelling left as `join`
+   * produced it, so the two verbs disagree there. Normalizing it is a contract
+   * change on an existing JSON field and belongs to a branch reading the audit.
+   */
+  readonly rel: string
+  /** The folder a listing reads, absolute against the root it was resolved at. */
+  readonly dir: string
+}
+
+/**
+ * The skill corpus a measure reads at a given root: the shipped tree in this
+ * repository and a target's own `.claude/skills/` in a project that consumes
+ * it. `CORPORA` order settles a tree carrying both, so every reading taken
+ * here still comes from `claude/skills/`.
+ *
+ * Kept apart from `listSkills` deliberately. `src/counts/catalogs.ts` counts
+ * the shipped catalog through that function, so teaching it to read both
+ * corpora would move the reported total off the tree that installs and
+ * falsify every sentence in the corpus stating it.
+ */
+export function resolveSkillsCorpus(root: string): SkillsCorpus | undefined {
+  for (const rel of CORPORA) {
+    const dir = join(root, rel)
+    if (existsSync(dir)) return { rel: rel.replaceAll('\\', '/'), dir }
+  }
+
+  return undefined
+}
+
+/**
+ * Enumerates the plugin skill catalog, which is the corpus under `claude/`
+ * rather than the internal skills under `.claude/`. Only the former installs
+ * into a target, so a count taken across both overstates what ships.
+ *
+ * The folder name wins over the frontmatter `name` when they disagree, because
+ * Claude Code invokes a skill by its directory.
+ *
+ * `requirement` reports whether the folder carries `REQUIREMENT.md`. Every skill
+ * is meant to carry one, so a false is a gap rather than a recorded exemption.
+ * `canon claude skills audit` is what fails on it, across both corpora.
+ */
+export function listSkills(root: string): SkillListing[] {
+  return listSkillsAt(join(root, 'claude', 'skills'))
+}
+
+/**
+ * The same enumeration against a corpus folder the caller already resolved,
+ * which is what `resolveSkillsCorpus` hands a measure that reaches a target.
+ */
+export function listSkillsAt(skillsRoot: string): SkillListing[] {
+  if (!existsSync(skillsRoot)) return []
+
+  const paths = [
+    ...new Bun.Glob('*/SKILL.md').scanSync({
+      cwd: skillsRoot,
+      onlyFiles: true,
+    }),
+  ].sort()
+
+  return paths.map((path) => ({
+    name: dirname(path),
+    description: readDescription(join(skillsRoot, path)),
+    requirement: existsSync(join(skillsRoot, dirname(path), 'REQUIREMENT.md')),
+  }))
+}
+
+/**
+ * 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.
+ */
+function readDescription(path: string): string {
+  const match = FRONTMATTER.exec(readFileSync(path, 'utf8'))
+  if (!match) return ''
+
+  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 : ''
+  } catch {
+    return ''
+  }
+}

package/src/claude/skills-rank.ts

@@ -0,0 +1,320 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { listSkillsAt, resolveSkillsCorpus } from '@/claude/skills-list'
+
+/**
+ * Whether a prompt reaches the right skill, measured by TF-IDF cosine
+ * similarity over the shipped catalog's own frontmatter descriptions. This is
+ * a necessary condition rather than a report of real routing behavior: it
+ * asks whether the descriptions are separable by the words they use, and
+ * Claude Code does not route this way.
+ *
+ * Ported from `.claude/groundwork/42-ai-blueprint/evidence/rank.ts`, which
+ * ran once against this catalog and named the collisions this measure now
+ * tracks on a cadence.
+ */
+
+const STOP = new Set(
+  'a about after again all also and any are as at be before but by can do does for from has have help how in into is it its just make not of on or our so that the then there these this to use used uses using want was what when where which who why with you your run'.split(
+    ' ',
+  ),
+)
+
+export interface RankedSkill {
+  readonly name: string
+  readonly description: string
+}
+
+/** One prompt and the skill it should reach. */
+export interface SkillCase {
+  readonly prompt: string
+  readonly expect: string
+}
+
+/** A case whose prompt did not rank its expected skill first. */
+export interface Miss {
+  readonly prompt: string
+  readonly expect: string
+  /** The skill the ranker placed first instead. */
+  readonly won: string
+  /** Where `expect` placed, or 0 when it never appears in the catalog. */
+  readonly rank: number
+}
+
+/** Why a measure produced no reading, which is never the same as a clean one. */
+export type RankRefusal = 'no-skills' | 'no-cases' | 'bad-cases'
+
+/** The refusals a case corpus read produces, which the scan itself cannot raise. */
+export type CaseCorpusRefusal = Extract<RankRefusal, 'no-cases' | 'bad-cases'>
+
+export type CaseCorpusReport =
+  | { readonly kind: 'cases'; readonly cases: readonly SkillCase[] }
+  | {
+      readonly kind: 'refused'
+      readonly reason: CaseCorpusRefusal
+      /** What the caller has to change, which the reason alone never says. */
+      readonly detail: string
+    }
+
+export type RankReport =
+  | {
+      readonly kind: 'measured'
+      /** The corpus spelling measured, since a root can carry either one. */
+      readonly corpus: string
+      readonly skills: number
+      readonly cases: number
+      readonly rank1: number
+      readonly top3: number
+      readonly misses: readonly Miss[]
+      /** Cases whose prompt carried no vocabulary to score. */
+      readonly unmeasurable: readonly SkillCase[]
+    }
+  | { readonly kind: 'refused'; readonly reason: RankRefusal }
+
+/**
+ * Reads a project's own case corpus, which is JSON in the shape `SKILL_CASES`
+ * already holds. A target authors its own skills and its own vocabulary, so
+ * the toolkit corpus answers a question no other project asked.
+ *
+ * No standard stands behind the shape until a third project needs one, so
+ * every way the file fails is reported with what to change rather than
+ * measured against a spec. An empty array refuses for the reason a missing
+ * file does: a corpus of nothing scores 0 of 0 and reads as a clean pass.
+ */
+export function loadCaseCorpus(path: string): CaseCorpusReport {
+  if (!existsSync(path)) {
+    return { kind: 'refused', reason: 'no-cases', detail: path }
+  }
+
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(readFileSync(path, 'utf8'))
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error)
+    return { kind: 'refused', reason: 'bad-cases', detail }
+  }
+
+  if (!Array.isArray(parsed)) {
+    return {
+      kind: 'refused',
+      reason: 'bad-cases',
+      detail: 'the file holds something other than an array of cases',
+    }
+  }
+
+  const cases: SkillCase[] = []
+  for (const [index, entry] of parsed.entries()) {
+    const record = entry as Record<string, unknown> | null
+    if (
+      typeof record !== 'object' ||
+      record === null ||
+      typeof record.prompt !== 'string' ||
+      typeof record.expect !== 'string'
+    ) {
+      return {
+        kind: 'refused',
+        reason: 'bad-cases',
+        detail: `case ${index} carries no string prompt or expect`,
+      }
+    }
+
+    cases.push({ prompt: record.prompt, expect: record.expect })
+  }
+
+  if (cases.length === 0) {
+    return {
+      kind: 'refused',
+      reason: 'bad-cases',
+      detail: 'the file holds no cases at all',
+    }
+  }
+
+  return { kind: 'cases', cases }
+}
+
+/**
+ * Every shipped skill's frontmatter description, read the way a prompt is
+ * matched against it: whole, including the quoted trigger phrases it states.
+ * A skill whose frontmatter carries no description contributes no vocabulary
+ * and never wins a rank, so it is dropped rather than scored on nothing.
+ */
+export function loadCatalog(root: string): RankedSkill[] {
+  const corpus = resolveSkillsCorpus(root)
+  return corpus === undefined ? [] : loadCatalogAt(corpus.dir)
+}
+
+/** The same read against a corpus folder the caller already resolved. */
+export function loadCatalogAt(skillsRoot: string): RankedSkill[] {
+  return listSkillsAt(skillsRoot)
+    .filter((skill) => skill.description !== '')
+    .map((skill) => ({ name: skill.name, description: skill.description }))
+}
+
+function tokenize(text: string): string[] {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9\s-]/g, ' ')
+    .split(/\s+/)
+    .filter((token) => token.length > 2 && !STOP.has(token))
+}
+
+function termCounts(tokens: readonly string[]): Map<string, number> {
+  const counts = new Map<string, number>()
+  for (const token of tokens) counts.set(token, (counts.get(token) ?? 0) + 1)
+  return counts
+}
+
+function buildIdf(
+  docs: readonly Map<string, number>[],
+): (term: string) => number {
+  const total = docs.length
+  const documentFrequency = new Map<string, number>()
+  for (const doc of docs) {
+    for (const term of doc.keys()) {
+      documentFrequency.set(term, (documentFrequency.get(term) ?? 0) + 1)
+    }
+  }
+  return (term) =>
+    Math.log((total + 1) / ((documentFrequency.get(term) ?? 0) + 1)) + 1
+}
+
+function tfIdfVector(
+  terms: Map<string, number>,
+  idf: (term: string) => number,
+): Map<string, number> {
+  const vec = new Map<string, number>()
+  for (const [term, frequency] of terms) vec.set(term, frequency * idf(term))
+  return vec
+}
+
+function cosineSimilarity(
+  a: Map<string, number>,
+  b: Map<string, number>,
+): number {
+  let dot = 0
+  for (const [term, weight] of a) dot += weight * (b.get(term) ?? 0)
+  if (dot === 0) return 0
+
+  const norm = (vec: Map<string, number>) =>
+    Math.sqrt(
+      [...vec.values()].reduce((sum, weight) => sum + weight * weight, 0),
+    )
+  const denominator = norm(a) * norm(b)
+  return denominator === 0 ? 0 : dot / denominator
+}
+
+export interface RankedResult {
+  readonly name: string
+  readonly score: number
+}
+
+/**
+ * Every skill's TF-IDF vector over the catalog it was loaded with, and the
+ * IDF weighting that both the catalog and a scored prompt read from. A model
+ * is built once per catalog and reused across every case, since the IDF
+ * weights are the same question asked of the same corpus each time.
+ */
+export interface RankModel {
+  readonly rank: (prompt: string) => readonly RankedResult[]
+}
+
+export function buildModel(catalog: readonly RankedSkill[]): RankModel {
+  const docs = catalog.map((skill) => termCounts(tokenize(skill.description)))
+  const idf = buildIdf(docs)
+  const vectors = new Map(
+    catalog.map((skill, index) => [skill.name, tfIdfVector(docs[index], idf)]),
+  )
+
+  return {
+    rank: (prompt: string): readonly RankedResult[] => {
+      const promptVector = tfIdfVector(termCounts(tokenize(prompt)), idf)
+      // A prompt built entirely from stopwords and short words tokenizes to
+      // nothing, so every skill would score 0 and the sort would fall through
+      // to `localeCompare`, handing the alphabetically first skill a win no
+      // description earned. Reporting no ranking at all is what keeps that
+      // tie-break from reading as a measurement.
+      if (promptVector.size === 0) return []
+
+      return [...vectors]
+        .map(([name, vector]) => ({
+          name,
+          score: cosineSimilarity(promptVector, vector),
+        }))
+        .sort(
+          (left, right) =>
+            right.score - left.score || left.name.localeCompare(right.name),
+        )
+    },
+  }
+}
+
+/**
+ * Scores every case against the catalog's own descriptions, which is the
+ * production mechanism: Claude Code matches a prompt against the whole
+ * description a skill ships, triggers included.
+ */
+export function measureCases(
+  catalog: readonly RankedSkill[],
+  cases: readonly SkillCase[],
+): {
+  readonly rank1: number
+  readonly top3: number
+  readonly misses: readonly Miss[]
+  readonly unmeasurable: readonly SkillCase[]
+} {
+  const model = buildModel(catalog)
+  let rank1 = 0
+  let top3 = 0
+  const misses: Miss[] = []
+  const unmeasurable: SkillCase[] = []
+
+  for (const skillCase of cases) {
+    const ranked = model.rank(skillCase.prompt)
+    if (ranked.length === 0) {
+      unmeasurable.push(skillCase)
+      continue
+    }
+
+    const at = ranked.findIndex((entry) => entry.name === skillCase.expect) + 1
+
+    if (at === 1) rank1 += 1
+    if (at > 0 && at <= 3) top3 += 1
+    if (at !== 1) {
+      misses.push({
+        prompt: skillCase.prompt,
+        expect: skillCase.expect,
+        won: ranked[0]?.name ?? '',
+        rank: at,
+      })
+    }
+  }
+
+  return { rank1, top3, misses, unmeasurable }
+}
+
+/**
+ * Reads whichever skill corpus the root carries and scores it against the
+ * given cases. Measures the cwd's catalog rather than the toolkit root,
+ * matching the reach and audit verbs, so a linked worktree reads its own
+ * branch and a target reads the skills it wrote itself.
+ */
+export function scanRank(
+  root: string,
+  cases: readonly SkillCase[],
+): RankReport {
+  const corpus = resolveSkillsCorpus(root)
+  if (corpus === undefined) return { kind: 'refused', reason: 'no-skills' }
+
+  const catalog = loadCatalogAt(corpus.dir)
+  const { rank1, top3, misses, unmeasurable } = measureCases(catalog, cases)
+
+  return {
+    kind: 'measured',
+    corpus: corpus.rel,
+    skills: catalog.length,
+    cases: cases.length,
+    rank1,
+    top3,
+    misses,
+    unmeasurable,
+  }
+}

package/src/claude/skills-reach.ts

@@ -0,0 +1,227 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { resolveSkillsCorpus } from '@/claude/skills-list'
+
+/**
+ * The authoring roots this repository owns and no install channel delivers.
+ *
+ * Every entry is a folder a target never holds under that spelling. Standards
+ * and snippets install nowhere and are reached through the plugin corpus,
+ * rules install under `.claude/rules/`, and the rest are this repository's
+ * own source, docs, and catalogs.
+ *
+ * `src/`, `scripts/`, and bare `docs/` are deliberately absent. A body naming
+ * one of those is describing the reader's own tree, so listing them would
+ * report a correct citation on every run and bury the defect this measures.
+ * `docs/agents/` is the exception, being the CLI contract pages that exist
+ * here alone.
+ */
+const AUTHORING_ROOTS = [
+  '.claude/context/',
+  'claude/',
+  'docs/agents/',
+  'governance/',
+  'internal/',
+  'snippets/',
+  'standards/',
+  'tooling/',
+  'wiki/',
+] as const
+
+/**
+ * What marks a citation as deliberately naming this repository's own copy.
+ *
+ * The word rather than a notation, matching the three bodies that already
+ * spell it and the repair the plan settled on. A parser-visible syntax was the
+ * alternative and it invents a spelling for a handful of lines while leaving
+ * the shipped precedent unreadable.
+ */
+const QUALIFIER = /toolkit/i
+
+/** A backticked token, which is how every body spells a path it cites. */
+const TOKEN = /`([^`\s]+)`/g
+
+/**
+ * A path a reader could open, which is the only kind worth measuring.
+ *
+ * Requires an extension and a separator, and admits no `<`, `$`, or `*`. A
+ * body writes `.claude/context/<domain>.md` to name a shape rather than a
+ * file, and `${CLAUDE_SKILL_DIR}/../../standards/markdown.md` to resolve
+ * against the plugin root, which is self-contained by construction.
+ */
+const CONCRETE = /^[.A-Za-z0-9_][A-Za-z0-9._/-]*\.[a-z]{1,4}$/
+
+export interface Citation {
+  readonly file: string
+  /** One-based, matching the `file:line` form a reader clicks. */
+  readonly line: number
+  readonly path: string
+  readonly qualified: boolean
+}
+
+/** Why a scan produced no corpus, which is never the same as a clean one. */
+export type ReachRefusal = 'no-skills'
+
+export type ReachReport =
+  | {
+      readonly kind: 'measured'
+      /** The corpus spelling read, since a root can carry either one. */
+      readonly corpus: string
+      /** Files opened, so a report can state what the verdict covers. */
+      readonly bodies: number
+      readonly qualified: readonly Citation[]
+      readonly unqualified: readonly Citation[]
+    }
+  | { readonly kind: 'refused'; readonly reason: ReachRefusal }
+
+export function isQualified(line: string): boolean {
+  return QUALIFIER.test(line)
+}
+
+/**
+ * The roots that belong to the toolkit rather than to the reader, read
+ * against the corpus being measured.
+ *
+ * A target's `.claude/context/` is the reader's own tree. A seed put the
+ * entries there and the project owns them afterward, so a body under
+ * `.claude/skills/` citing one names a file its reader holds. Measuring it
+ * would report a correct citation on every run, which is exactly why `src/`
+ * and `scripts/` are absent from the list above. In this repository the seed
+ * tree settles the same question through `readReceivedPaths`, which a target
+ * carrying no `tooling/` folder cannot answer at all, so the root comes out
+ * by corpus instead.
+ */
+export function authoringRootsFor(corpus: string): readonly string[] {
+  if (!corpus.startsWith('.claude/')) return AUTHORING_ROOTS
+
+  return AUTHORING_ROOTS.filter((root) => !root.startsWith('.claude/'))
+}
+
+/**
+ * Every path a seed lands on in a target, spelled the way a body would cite it.
+ *
+ * Read off the seed tree rather than listed, so a seed added to any stack
+ * clears its own citations without this module being edited. Dotfiles are in
+ * scope because the whole seeded context corpus sits under `.claude/`.
+ */
+export function readReceivedPaths(root: string): Set<string> {
+  const toolingRoot = join(root, 'tooling')
+  if (!existsSync(toolingRoot)) return new Set()
+
+  const received = new Set<string>()
+  for (const path of new Bun.Glob('*/seeds/**/*').scanSync({
+    cwd: toolingRoot,
+    onlyFiles: true,
+    dot: true,
+  })) {
+    const posix = path.replaceAll('\\', '/')
+    received.add(posix.replace(/^[^/]+\/seeds\//, ''))
+  }
+  return received
+}
+
+/**
+ * Whether a cited path is this repository's own rather than the reader's.
+ *
+ * A seeded path is disowned twice over: under its own name, and under the
+ * folder spelling it takes once a target splits the entry. A domain that
+ * outgrows one file becomes `<domain>/`, which is still the entry the seed
+ * delivered, so reporting the split form would fail a target for growing.
+ */
+export function isToolkitOwned(
+  path: string,
+  received: Set<string>,
+  roots: readonly string[] = AUTHORING_ROOTS,
+): boolean {
+  if (received.has(path)) return false
+
+  for (const seeded of received) {
+    const stem = seeded.replace(/\.md$/, '')
+    if (stem !== seeded && path.startsWith(`${stem}/`)) return false
+  }
+
+  return roots.some((prefix) => path.startsWith(prefix))
+}
+
+/**
+ * Every toolkit-owned path one shipped file cites, with the line's verdict.
+ *
+ * Existence is not checked here. A body may name a path this repository once
+ * held, and separating the shape test from the disk read is what lets the
+ * shape be tested without a tree on disk.
+ */
+export function citationsIn(
+  file: string,
+  text: string,
+  received: Set<string>,
+  roots: readonly string[] = AUTHORING_ROOTS,
+): Citation[] {
+  const citations: Citation[] = []
+
+  for (const [index, line] of text.split('\n').entries()) {
+    const qualified = isQualified(line)
+
+    for (const match of line.matchAll(TOKEN)) {
+      const path = match[1]
+      if (!CONCRETE.test(path) || !path.includes('/')) continue
+      if (!isToolkitOwned(path, received, roots)) continue
+
+      citations.push({ file, line: index + 1, path, qualified })
+    }
+  }
+
+  return citations
+}
+
+/**
+ * Reads every body in the root's skill corpus for a path its reader cannot
+ * open.
+ *
+ * A citation of a path this repository does not hold is dropped rather than
+ * reported. The measure asks whether a claim true here is false in a target,
+ * and a path true in neither is a different defect that `canon context audit`
+ * already reports against its own corpus.
+ *
+ * `resolveSkillsCorpus` prefers `claude/skills/`, which is the tree that
+ * installs into a target, so this repository's own reading is the one it
+ * always was. A project carrying `.claude/skills/` alone has no shipped tree
+ * and its own skills are the whole corpus a reader there opens.
+ */
+export function scanReach(root: string): ReachReport {
+  const corpus = resolveSkillsCorpus(root)
+  if (corpus === undefined) return { kind: 'refused', reason: 'no-skills' }
+
+  const received = readReceivedPaths(root)
+  const roots = authoringRootsFor(corpus.rel)
+  const files = [
+    ...new Bun.Glob('**/*.md').scanSync({ cwd: corpus.dir, onlyFiles: true }),
+  ].sort()
+
+  const qualified: Citation[] = []
+  const unqualified: Citation[] = []
+
+  for (const file of files) {
+    const posix = file.replaceAll('\\', '/')
+    const text = readFileSync(join(corpus.dir, file), 'utf8')
+
+    for (const citation of citationsIn(
+      `${corpus.rel}/${posix}`,
+      text,
+      received,
+      roots,
+    )) {
+      if (!existsSync(join(root, citation.path))) continue
+
+      if (citation.qualified) qualified.push(citation)
+      else unqualified.push(citation)
+    }
+  }
+
+  return {
+    kind: 'measured',
+    corpus: corpus.rel,
+    bodies: files.length,
+    qualified,
+    unqualified,
+  }
+}

package/src/cli-run.ts

@@ -0,0 +1,43 @@
+import { join } from 'node:path'
+import { execa } from 'execa'
+
+export interface CliRunOptions {
+  /** Sets `CANON_NON_INTERACTIVE=1` for the child. Defaults to false. */
+  readonly nonInteractive?: boolean
+  /** Defaults to `inherit`, so a child prompt still reaches the operator. */
+  readonly stdin?: 'ignore' | 'inherit'
+}
+
+export function cliPath(root: string): string {
+  return join(root, 'src', 'cli.ts')
+}
+
+/**
+ * Spawns a `canon` subcommand as its own process, by path rather than through
+ * the global binary, so a linked worktree exercises its own code.
+ *
+ * Both callers want a separately failable child rather than an in-process call:
+ * `canon init` reports each domain's outcome independently, and `canon sync`
+ * relies on each domain opening its own frame. Returns whether the child
+ * succeeded rather than throwing, because a failed domain is a reportable
+ * outcome and not an abort.
+ */
+export function cliRun(
+  path: string,
+  args: readonly string[],
+  options: CliRunOptions = {},
+): () => Promise<boolean> {
+  return async () => {
+    const env = options.nonInteractive
+      ? { ...process.env, CANON_NON_INTERACTIVE: '1' }
+      : process.env
+
+    const result = await execa('bun', [path, ...args], {
+      stdio: [options.stdin ?? 'inherit', 'inherit', 'inherit'],
+      env,
+      reject: false,
+    })
+
+    return result.exitCode === 0
+  }
+}