@erclx/canon 4.0.0

package/src/context/citations.ts

@@ -0,0 +1,196 @@
+import { existsSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { resolve } from 'node:path'
+import { listRepositoryFiles } from '@/git-files'
+
+/**
+ * Suppresses citation checking for the source line carrying it.
+ *
+ * Prose that teaches a naming pattern displays a path rather than pointing at
+ * one, and no syntax separates the two: an illustration and a reference are
+ * both inline code in a sentence. Location covers the fixture trees and fenced
+ * examples, and this covers what is left, which is a sentence naming a
+ * hypothetical entry to show the shape of the name.
+ */
+export const IGNORE_MARKER = 'audit-ignore-citations'
+
+/**
+ * Matches the marker plus an optional comma-separated path list.
+ *
+ * `<!-- audit-ignore-citations: .claude/standards/X.md -->` narrows the skip
+ * to the paths named. The bare form with no colon skips every citation the
+ * line carries, which is the only shape a line with nothing else worth
+ * checking needs and the shape every marker predating this pattern still
+ * carries.
+ */
+const IGNORE_MARKER_LINE =
+  /<!--\s*audit-ignore-citations(?::\s*([^>]+?))?\s*-->/
+
+interface IgnoredCitations {
+  readonly all: boolean
+  readonly paths: ReadonlySet<string>
+}
+
+/**
+ * Reads which citations on a line the marker excuses.
+ *
+ * A bare marker excuses every citation the line carries, matching the
+ * pre-named-path behavior. A named marker excuses only the paths listed,
+ * so a line carrying both a placeholder and a real reference keeps the real
+ * one checked rather than losing it to the placeholder beside it.
+ */
+function ignoredCitations(line: string): IgnoredCitations | undefined {
+  const match = line.match(IGNORE_MARKER_LINE)
+  if (!match) return undefined
+  if (match[1] === undefined) return { all: true, paths: new Set() }
+
+  const paths = match[1]
+    .split(',')
+    .map((path) => path.trim())
+    .filter(Boolean)
+  return { all: false, paths: new Set(paths) }
+}
+
+/**
+ * Trees holding content authored to be parsed rather than followed.
+ *
+ * Sandbox scenarios describe paths inside their own scratch fixtures and the
+ * eval harness names paths in its target project. Neither is a reference into
+ * this repository, so an unresolved path there is correct rather than stale.
+ */
+const FIXTURE_TREES: readonly string[] = ['scripts/sandbox/', 'scripts/eval/']
+
+const FIXTURE_SEGMENTS: readonly string[] = ['fixtures', '__fixtures__']
+
+const FENCE = /^\s*(```|~~~)/
+
+export interface Citation {
+  readonly file: string
+  readonly line: number
+  readonly path: string
+}
+
+export function isFixture(rel: string): boolean {
+  if (rel.endsWith('.test.ts')) return true
+  if (FIXTURE_TREES.some((tree) => rel.startsWith(tree))) return true
+  return rel.split('/').some((segment) => FIXTURE_SEGMENTS.includes(segment))
+}
+
+export function citationPattern(folders: readonly string[]): RegExp {
+  const names = folders.map((name) =>
+    name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'),
+  )
+  return new RegExp(
+    `\\.claude/(?:${names.join('|')})/[A-Za-z0-9._/-]+\\.md`,
+    'g',
+  )
+}
+
+/**
+ * A backticked filename carrying no folder, the form a reference takes when it
+ * names a sibling rather than a path.
+ *
+ * `citationPattern` spells the `.claude/` prefix and cannot see this shape at
+ * all, which is the reason the form rule exists. Widening that expression to
+ * admit a bare name was the alternative and it puts one match in the position of
+ * answering two questions, since a spelled path is a reference by construction
+ * and a bare name is a candidate whichever caller found it still has to test
+ * against the folder it sits in.
+ *
+ * The backticks are required rather than incidental. A filename written into
+ * running prose without them is not a reference a reader follows, and matching
+ * one would report every sentence that happens to name a file.
+ */
+export const BARE_NAME = /`([A-Za-z0-9._-]+\.md)`/g
+
+/**
+ * Pulls the cited paths out of one file's text.
+ *
+ * Fenced blocks are skipped for markdown only. A fence is markdown syntax, and
+ * applying it to a shell or TypeScript source would let a heredoc of triple
+ * backticks silently hide the rest of the file.
+ */
+export function collectCitations(
+  rel: string,
+  text: string,
+  pattern: RegExp,
+): Citation[] {
+  const isMarkdown = rel.endsWith('.md')
+  const found: Citation[] = []
+  let fenced = false
+
+  for (const [index, line] of text.split('\n').entries()) {
+    if (isMarkdown && FENCE.test(line)) {
+      fenced = !fenced
+      continue
+    }
+    if (fenced) continue
+
+    const ignored = ignoredCitations(line)
+
+    for (const match of line.matchAll(pattern)) {
+      if (ignored && (ignored.all || ignored.paths.has(match[0]))) continue
+      found.push({ file: rel, line: index + 1, path: match[0] })
+    }
+  }
+
+  return found
+}
+
+/**
+ * `unavailable` is a distinct state from a clean scan.
+ *
+ * Finding nothing and being unable to look mean opposite things, and only one
+ * of them should let a push through.
+ */
+export type CitationReport =
+  | {
+      readonly kind: 'scanned'
+      readonly scanned: number
+      readonly total: number
+      readonly unresolved: readonly Citation[]
+    }
+  | { readonly kind: 'unavailable' }
+
+/**
+ * Resolves every cited path outside the fixture trees.
+ *
+ * This is the only check that gates the repository check, which makes it the
+ * only one whose false positives cost a contributor anything. It reports a
+ * finding solely for a path that does not resolve on disk, and the exclusions
+ * above are what keep that from firing on prose about paths.
+ */
+export async function auditCitations(
+  root: string,
+  folders: readonly string[],
+): Promise<CitationReport> {
+  const pattern = citationPattern(folders)
+  const listed = await listRepositoryFiles(root)
+  if (!listed) return { kind: 'unavailable' }
+
+  const candidates = listed.filter((rel) => !isFixture(rel))
+  const citations: Citation[] = []
+
+  for (const rel of candidates) {
+    const path = resolve(root, rel)
+    if (!existsSync(path)) continue
+
+    let text: string
+    try {
+      text = await readFile(path, 'utf8')
+    } catch {
+      continue
+    }
+
+    citations.push(...collectCitations(rel, text, pattern))
+  }
+
+  return {
+    kind: 'scanned',
+    scanned: candidates.length,
+    total: citations.length,
+    unresolved: citations.filter(
+      (citation) => !existsSync(resolve(root, citation.path)),
+    ),
+  }
+}

package/src/context/folders.ts

@@ -0,0 +1,186 @@
+import { existsSync } from 'node:fs'
+import { dirname, relative, resolve } from 'node:path'
+import { INDEX_FILE, listIndexes } from '@/indexes/walk'
+
+/**
+ * Folder names under `.claude/` audited by default.
+ *
+ * A named list rather than the index-plus-entry contract read off disk, so a
+ * generated tree satisfying that contract is never measured against a rule
+ * written for per-domain narrative. This list names the folders
+ * `standards/context.md` governs, and `--folder` admits another without an edit
+ * here.
+ *
+ * It doubles as the citation check's scope, since `citationPattern` spells only
+ * these names. A `.claude/` folder left off the list is never resolved, so a
+ * path into one goes stale silently rather than failing a push.
+ */
+export const DEFAULT_FOLDERS: readonly string[] = [
+  'context',
+  'diagrams',
+  'wireframes',
+]
+
+/** The base every folder in the default list sits under. */
+const CLAUDE_BASE = '.claude'
+
+/** The project root, reached only by a name the caller asked for. */
+const ROOT_BASE = '.'
+
+export interface AuditedFolder {
+  /**
+   * The requested folder name this was resolved under, which is what says
+   * which standard governs the entries. A nested split folder carries the name
+   * of the folder it sits beneath rather than its own, so
+   * `.claude/context/claude-plugin` is governed as `context`.
+   */
+  readonly name: string
+  /**
+   * The base the name resolved under, which is what says whether the folder is
+   * in the citation check's scope.
+   */
+  readonly base: string
+  /** Repo-relative folder path, used verbatim in every report line. */
+  readonly rel: string
+  readonly indexPath: string
+  /** Absolute paths of the folder's own entries, excluding its `index.md`. */
+  readonly entries: readonly string[]
+  /**
+   * Whether this is a sub-area a domain split into rather than the folder
+   * named under `.claude/`.
+   *
+   * The entries of a split folder describe one domain between them, so a rule
+   * about what a domain declares is answered by the folder. The entries of the
+   * named folder are one domain each, and a rule answered by a sibling there
+   * would let one entry stand in for domains it says nothing about.
+   */
+  readonly nested: boolean
+}
+
+/**
+ * Names the requested `.claude/` folders that actually exist, which is the
+ * citation check's scope.
+ *
+ * A skill or seed pointing into `.claude/wireframes/` is a live instruction for
+ * a project that carries the folder and says nothing about one that does not.
+ * Checking a path into an absent folder would fail eight shipped references
+ * here for the sole reason that this repository has no wireframes.
+ *
+ * A folder resolved at the project root is measured and stays out of this. The
+ * pattern the citation check builds spells the `.claude/` prefix, so admitting
+ * a root name there would check `.claude/<name>/` paths the audit never read.
+ * Widening the pattern to the root spelling is a separate change, since a bare
+ * `docs/x.md` appears in prose that references nothing.
+ */
+export function presentNames(folders: readonly AuditedFolder[]): string[] {
+  return [
+    ...new Set(
+      folders
+        .filter((folder) => folder.base === CLAUDE_BASE)
+        .map((folder) => folder.name),
+    ),
+  ]
+}
+
+async function readEntries(dir: string): Promise<string[]> {
+  const paths: string[] = []
+
+  for await (const name of new Bun.Glob('*.md').scan({
+    cwd: dir,
+    onlyFiles: true,
+    dot: true,
+  })) {
+    if (name === INDEX_FILE) continue
+    paths.push(resolve(dir, name))
+  }
+
+  return paths.sort()
+}
+
+export interface FolderResolution {
+  /** Every folder that resolved, with the nested splits beneath each. */
+  readonly folders: readonly AuditedFolder[]
+  /**
+   * Requested names that resolved under no base, reported rather than dropped.
+   * Which absences are worth saying out loud is the caller's judgment: a
+   * default folder a project does not carry is ordinary, and a name passed by
+   * hand that resolves nowhere is a typo that would otherwise read as a pass.
+   */
+  readonly missing: readonly string[]
+}
+
+export interface ResolveOptions {
+  /**
+   * Whether a name may resolve at the project root when `.claude/` does not
+   * carry it. False for the default list, which names three folders a project
+   * is expected to hold under `.claude/` and nowhere else.
+   */
+  readonly canResolveAtRoot?: boolean
+}
+
+function locate(
+  root: string,
+  name: string,
+  bases: readonly string[],
+): { readonly dir: string; readonly base: string } | undefined {
+  for (const base of bases) {
+    const dir = resolve(root, base, name)
+    if (existsSync(`${dir}/${INDEX_FILE}`)) return { dir, base }
+  }
+
+  return undefined
+}
+
+/**
+ * Resolves the folders to audit under `root`.
+ *
+ * A named folder contributes its own entries plus those of every nested index
+ * folder beneath it, so a domain that outgrew one file and split is audited at
+ * the same grain as one that did not. Discovery of the nested folders runs
+ * through the shared walker, which is what keeps `.gitignore` and the vendored
+ * prune governing this scan as well as index regeneration. That prune is what
+ * lets a root folder be walked at all, since a name at the project root sits
+ * beside `node_modules` and a build output.
+ *
+ * The project root is reached only when the caller opts in, so a target holding
+ * a root `wireframes/` is not audited against a standard it never adopted by
+ * the mere act of running the command. `.claude/` still wins a name carried by
+ * both, and the scope line prints the resolved path so a caller reads which
+ * base was taken rather than inferring it.
+ *
+ * Nothing above this asks where a folder came from. A name that resolves at the
+ * root is measured by every rule that generalizes and gated out of the rules a
+ * single standard carries, which `governsContent` decides from the name.
+ */
+export async function resolveFolders(
+  root: string,
+  names: readonly string[] = DEFAULT_FOLDERS,
+  { canResolveAtRoot = false }: ResolveOptions = {},
+): Promise<FolderResolution> {
+  const bases = canResolveAtRoot ? [CLAUDE_BASE, ROOT_BASE] : [CLAUDE_BASE]
+  const folders: AuditedFolder[] = []
+  const missing: string[] = []
+
+  for (const name of names) {
+    const found = locate(root, name, bases)
+    if (!found) {
+      missing.push(name)
+      continue
+    }
+
+    const dirs = [found.dir, ...(await listIndexes(found.dir)).map(dirname)]
+
+    for (const each of [...new Set(dirs)].sort()) {
+      folders.push({
+        name,
+        base: found.base,
+        rel: relative(root, each),
+        indexPath: `${each}/${INDEX_FILE}`,
+        entries: await readEntries(each),
+        nested: each !== found.dir,
+      })
+    }
+  }
+
+  return { folders, missing }
+}

package/src/context/gate.ts

@@ -0,0 +1,57 @@
+import type { SectionFinding } from '@/context/audit'
+import type { FolderDrift } from '@/context/index-drift'
+
+export interface GateInput {
+  /** Cited paths that resolved to nothing, which gate under either mode. */
+  readonly unresolvedCitations: number
+  /**
+   * Whether the architecture record is longer than the ceiling it derives for
+   * itself, which gates under either mode for the reason a citation does.
+   *
+   * False when the project carries no record and false under
+   * `--citations-only`, which never measures it. That mode runs one check by
+   * construction, so widening it here would gate on a reading it never took.
+   */
+  readonly recordOverLength: boolean
+  readonly sections: readonly SectionFinding[]
+  readonly drift: readonly FolderDrift[]
+  /**
+   * Whether the caller asked for the widened gate. False leaves a missing
+   * section and a drifted index advisory, which is what the project-root stage
+   * runs so a judgment threshold never fails a push.
+   */
+  readonly widened: boolean
+}
+
+/** Whether any folder disagrees with its own index. */
+export function hasDrift(drift: readonly FolderDrift[]): boolean {
+  return drift.some(
+    (folder) => folder.unlisted.length > 0 || folder.missing.length > 0,
+  )
+}
+
+/**
+ * Whether the audit found something that should fail the caller.
+ *
+ * An unresolved citation is a broken pointer and gates unconditionally, and so
+ * does a record past its own ceiling: the record states the limit for itself
+ * and derives it from a count, which makes it the one measure here that is a
+ * fact rather than a threshold a reader weighs. The two findings `--gate` adds
+ * are the ones answerable from the file itself: a required section it does not
+ * declare, and an index disagreeing with its folder. Entry length, depth,
+ * bullet, table, provenance, and the record's claim coverage are judgments, so
+ * they stay out under both modes.
+ */
+export function isGating({
+  unresolvedCitations,
+  recordOverLength,
+  sections,
+  drift,
+  widened,
+}: GateInput): boolean {
+  if (unresolvedCitations > 0) return true
+  if (recordOverLength) return true
+  if (!widened) return false
+
+  return sections.length > 0 || hasDrift(drift)
+}

package/src/context/index-drift.ts

@@ -0,0 +1,64 @@
+import { existsSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { basename, dirname, resolve } from 'node:path'
+import type { AuditedFolder } from '@/context/folders'
+
+const ENTRY_LINK = /^-\s+\[[^\]]*\]\(([^)]+)\)/
+
+export interface FolderDrift {
+  readonly rel: string
+  /** Entry files present in the folder that the index does not link. */
+  readonly unlisted: readonly string[]
+  /** Names the index links that resolve to nothing on disk. */
+  readonly missing: readonly string[]
+}
+
+/** Collects the link targets of an index's catalog bullets. */
+export function listedTargets(source: string): string[] {
+  const targets: string[] = []
+
+  for (const line of source.split('\n')) {
+    const match = line.match(ENTRY_LINK)
+    if (match) targets.push(match[1])
+  }
+
+  return targets
+}
+
+/**
+ * Compares one folder's index against its siblings in both directions.
+ *
+ * Both halves are reported because they fail differently. An unlisted entry is
+ * invisible to a session reading the catalog to choose what to open, while a
+ * listed name with no file sends one to a path that opens nothing. Neither
+ * surfaces from reading the index alone.
+ */
+export async function auditFolder(folder: AuditedFolder): Promise<FolderDrift> {
+  const dir = dirname(folder.indexPath)
+  const source = await readFile(folder.indexPath, 'utf8')
+  const targets = listedTargets(source)
+
+  // A sub-catalog is linked as `<name>/index.md` and its entries are audited
+  // as their own folder, so only the leading segment is compared here.
+  const listed = new Set(targets.map((target) => target.split('/')[0]))
+
+  const unlisted = folder.entries
+    .map((path) => basename(path))
+    .filter((name) => !listed.has(name))
+
+  const missing = targets.filter((target) => !existsSync(resolve(dir, target)))
+
+  return { rel: folder.rel, unlisted, missing }
+}
+
+export async function auditIndexes(
+  folders: readonly AuditedFolder[],
+): Promise<FolderDrift[]> {
+  const drift: FolderDrift[] = []
+
+  for (const folder of folders) {
+    drift.push(await auditFolder(folder))
+  }
+
+  return drift
+}

package/src/context/narration.ts

@@ -0,0 +1,99 @@
+import { existsSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { resolve } from 'node:path'
+
+/**
+ * The headings a rule carries to publish the two sets.
+ *
+ * Discovery is anchored on these rather than on a filename for the reason
+ * `src/comments/vocabulary.ts` anchors its own: governance rules are numbered,
+ * and a renumber would empty the sets while the check kept reporting clean.
+ * Both open with `Narration` so neither loader can read the other's list.
+ */
+export const PRONOUN_HEADING = '## Narration pronouns'
+export const VERB_HEADING = '## Narration verbs'
+
+/**
+ * Roots searched in order. The installed copy wins over the toolkit source, so
+ * a target project measures against the rule it actually has rather than one
+ * only the toolkit carries.
+ */
+const RULE_ROOTS = ['.claude/rules', 'governance/rules']
+
+export interface NarrationTerms {
+  /** Back-reference openings, matched at the start of a bullet and cased. */
+  readonly pronouns: readonly string[]
+  /** Past-tense verbs, matched anywhere in the bullet and uncased. */
+  readonly verbs: readonly string[]
+}
+
+/**
+ * Absent is a distinct state from empty, the split the comment vocabulary
+ * draws for the same reason: a scan with no terms finds nothing, and reporting
+ * that as zero findings claims the corpus is clean when nothing was looked for.
+ */
+export type Narration =
+  | ({ readonly kind: 'loaded'; readonly source: string } & NarrationTerms)
+  | { readonly kind: 'absent' }
+
+/** Pulls the backticked terms out of the bullets under one heading. */
+export function parseTerms(
+  markdown: string,
+  heading: string,
+): string[] | undefined {
+  const lines = markdown.split('\n')
+  const start = lines.findIndex((line) => line.trim() === heading)
+  if (start === -1) return undefined
+
+  const terms: string[] = []
+
+  for (const line of lines.slice(start + 1)) {
+    if (line.startsWith('## ')) break
+    for (const match of line.matchAll(/`([^`]+)`/g)) {
+      const term = match[1].trim()
+      if (term && !terms.includes(term)) terms.push(term)
+    }
+  }
+
+  return terms
+}
+
+/**
+ * Finds the rule publishing both sets under `root`.
+ *
+ * Both come from one file rather than from whichever rule carries each. A
+ * pronoun set and a verb set are halves of one signal, and pairing them across
+ * files would let a renumber recombine them into a signal nobody wrote.
+ */
+export async function loadNarration(root: string): Promise<Narration> {
+  for (const ruleRoot of RULE_ROOTS) {
+    const dir = resolve(root, ruleRoot)
+    if (!existsSync(dir)) continue
+
+    const paths: string[] = []
+    for await (const rel of new Bun.Glob('**/*.md').scan({
+      cwd: dir,
+      onlyFiles: true,
+    })) {
+      paths.push(rel)
+    }
+    paths.sort()
+
+    for (const rel of paths) {
+      const source = await readFile(resolve(dir, rel), 'utf8')
+      const pronouns = parseTerms(source, PRONOUN_HEADING)
+      const verbs = parseTerms(source, VERB_HEADING)
+
+      if (pronouns && verbs && pronouns.length > 0 && verbs.length > 0) {
+        return {
+          kind: 'loaded',
+          source: `${ruleRoot}/${rel}`,
+          pronouns,
+          verbs,
+        }
+      }
+    }
+  }
+
+  return { kind: 'absent' }
+}

package/src/copy.ts

@@ -0,0 +1,30 @@
+import { chmod, copyFile, mkdir, stat } from 'node:fs/promises'
+import { dirname } from 'node:path'
+
+/**
+ * Copies with `cp` semantics. Two behaviors matter and neither is the default
+ * in the obvious alternatives. `Bun.write` drops the executable bit, which
+ * would land husky hooks and `scripts/verify.sh` non-executable. Plain
+ * `copyFile` imposes the source mode on an existing destination, so a file the
+ * target deliberately restricted to 600, or an earlier stack set executable,
+ * comes back at the source's mode. `cp` leaves an existing destination's mode
+ * alone.
+ *
+ * Every domain that writes into a target routes through here. The tooling
+ * inject path found the trap first, and the sync engine inherits it for every
+ * adapter.
+ */
+export async function copyPreservingMode(
+  src: string,
+  dest: string,
+): Promise<void> {
+  await mkdir(dirname(dest), { recursive: true })
+
+  const existingMode = await stat(dest)
+    .then((info) => info.mode)
+    .catch(() => undefined)
+
+  await copyFile(src, dest)
+
+  if (existingMode !== undefined) await chmod(dest, existingMode)
+}