@erclx/canon 5.63.0 → 5.65.0

package/src/context/citations.ts

@@ -1,9 +1,10 @@
 import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
-import { resolve } from 'node:path'
+import { relative, resolve } from 'node:path'
 import { listRepositoryFiles } from '@/git/files'
 import { RECORD_ROOTS } from '@/roots/record'
 import { SURFACE_ROOTS } from '@/roots/surface'
+import { stampPaths } from '@/sync/stamp'
 
 /**
  * Suppresses citation checking for the source line carrying it.
@@ -191,7 +192,11 @@ export type CitationReport =
   | { readonly kind: 'unavailable' }
 
 /**
- * Resolves every cited path outside the fixture trees.
+ * Resolves every cited path outside the fixture trees and the install stamp.
+ *
+ * The stamp is written by the toolkit, and `canon tooling decline` records the
+ * declined path as a key in it, so scanning it reports a deliberate decline as
+ * a stale citation.
  *
  * 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
@@ -206,7 +211,8 @@ export async function auditCitations(
   const listed = await listRepositoryFiles(root)
   if (!listed) return { kind: 'unavailable' }
 
-  const candidates = listed.filter((rel) => !isFixture(rel))
+  const stamps = new Set(stampPaths(root).map((path) => relative(root, path)))
+  const candidates = listed.filter((rel) => !isFixture(rel) && !stamps.has(rel))
   const citations: Citation[] = []
 
   for (const rel of candidates) {

package/src/gate/measures.ts

@@ -408,7 +408,7 @@ export const skillPracticeShape: Measure = async (ctx) => {
       .join(', ')
     return {
       emissions: [],
-      failure: `${plural(found.length, 'practice shape finding')}: ${where}. Add the closing H2 exactly as named to a practice skill, or the ledger at ${PRACTICE_LEDGER} to any skill on the ledger list, citing one linked source or one House choice row. A reference on the per-bullet list takes one ledger row per bullet under the same H2 at ${SKILL_LEDGERS}.`,
+      failure: `${plural(found.length, 'practice shape finding')}: ${where}. Add the closing H2 exactly as named to a practice skill, or the ledger at ${PRACTICE_LEDGER} to any skill on the ledger list, citing one linked source or one House choice row. A reference of a skill on the per-bullet list, unless exempted, takes one ledger row per bullet under the same H2 at ${SKILL_LEDGERS}.`,
     }
   }
 
@@ -519,9 +519,12 @@ export const documentCeiling: Measure = async (ctx) => {
  *
  * `canon/context/context-model.md` is exempt, since "context model" is the
  * domain's own name and the entry reads as nothing else without the prefix.
+ * So is a replay snapshot, which copies a consumer's paths verbatim, such as
+ * `canon/config/config.json`, and a renamed copy would sync as another file.
  */
 export function isFolderEchoedName(path: string): boolean {
   if (path === 'canon/context/context-model.md') return false
+  if (path.startsWith('sandbox/fixtures/replay/')) return false
   const segments = path.split('/')
   if (segments.length < 2) return false
   const folder = segments[segments.length - 2] ?? ''

package/src/gate/stages.ts

@@ -304,6 +304,31 @@ export const STAGES: readonly Stage[] = [
     label: 'Unreferenced rules',
     checks: [{ kind: 'measure', measure: unreferencedRules }],
   },
+  {
+    // A defect that only shows after a sync, such as a read crashing on a
+    // rule layout the sync just renamed, passes every unit test and every
+    // stage that reads this repository. Replaying the frozen consumer
+    // snapshots through this checkout's sync is what reaches it before a
+    // consumer does. Scoped to what a sync ships or reads, since a replay
+    // costs seconds a docs-only push should not pay. Governance is whole
+    // but for the ledger, since sync resolves stacks and renames as well as
+    // rules, and a rename is the class the stage was built against.
+    id: 'consumer-replay',
+    label: 'Consumer replay',
+    scope:
+      /^src\/|^governance\/(?!ledger\/)|^tooling\/|^sandbox\/fixtures\/replay\//,
+    skipped:
+      'No synced surface or snapshot changed, so no consumer was replayed',
+    checks: [
+      {
+        kind: 'cli',
+        argv: ['sandbox', 'replay'],
+        failure:
+          'A consumer replay crashed, printed unparsable JSON, left an unformatted write, or drifted from its recorded answer. Run bun src/cli.ts sandbox replay, and when a drift is one the change meant, such as a governance rename moving a sync count, run it with --record and commit the expectations.',
+      },
+    ],
+    success: 'Consumer replays clean',
+  },
   {
     // The facts the audit can answer from the files gate: a cited path that
     // does not resolve, a required section an entry does not declare, an H2

package/src/git/files.ts

@@ -140,7 +140,9 @@ export async function listIgnoreAdditions(
 /**
  * Lists the files under `root`: tracked, plus untracked files git does not
  * ignore. The untracked half is what keeps a file added on this branch in scope
- * rather than one push later.
+ * rather than one push later. A tracked path deleted in the working tree is
+ * left out, since a caller reading the listing would otherwise open a file that
+ * is gone.
  *
  * Returns undefined when git cannot answer, which every caller reports rather
  * than smoothing into an empty list. An empty list passes each of its zero
@@ -161,9 +163,12 @@ export async function listRepositoryFiles(
 
   const tracked = await run(['ls-files'])
   const untracked = await run(['ls-files', '--others', '--exclude-standard'])
-  if (!tracked || !untracked) return undefined
+  const deleted = await run(['ls-files', '--deleted'])
+  if (!tracked || !untracked || !deleted) return undefined
 
-  return [...new Set([...tracked, ...untracked])].sort()
+  const gone = new Set(deleted)
+  const present = tracked.filter((path) => !gone.has(path))
+  return [...new Set([...present, ...untracked])].sort()
 }
 
 /**

package/src/markdown/gated.ts

@@ -120,7 +120,7 @@ export function appendGatedPrefix(
   return 'appended'
 }
 
-/** Written by hand rather than serialized, the way `classifier.toml` is. */
+/** Written by hand rather than serialized, so the list keeps its one-entry-per-line form. */
 function writeGatedList(root: string, prefixes: readonly string[]): void {
   const path = join(root, GATED_CONFIG_REL)
   const mode = existsSync(path) ? statSync(path).mode : undefined

package/src/markdown/scope.ts

@@ -154,7 +154,6 @@ export const GATED_PATHS: readonly string[] = [
   'claude/skills/codebase-layout/references/tests.md',
   'claude/skills/context-fold/REQUIREMENT.md',
   'claude/skills/context-fold/SKILL.md',
-  'claude/skills/context-fold/references/classify.md',
   'claude/skills/context-fold/references/completion-report.md',
   'claude/skills/context-fold/references/context-refresh.md',
   'claude/skills/context-fold/references/context.md',

package/src/migrate/records.ts

@@ -103,6 +103,11 @@ function escape(value: string): string {
  * never match. The guard then stops firing in a project the move has not
  * reached, which is silent: the index goes stale while every save succeeds.
  *
+ * A replay snapshot is a frozen copy of a consumer, its hooks included, and
+ * the replay tests the upgrade from exactly that state. Sweeping one rewrites
+ * the consumer's own old-root citations, so the snapshot stops matching the
+ * release it was cut at.
+ *
  * A file outside this list can still couple to one inside it, naming an
  * excluded path as plain text while it also carries a live citation of its
  * own, which `referencesExcluded` reports separately below. Widening this list
@@ -115,6 +120,7 @@ const EXCLUDED_PREFIXES: readonly string[] = [
   'scripts/eval/result-',
   '.claude/hooks/',
   'tooling/claude/seeds/.claude/hooks/',
+  'sandbox/fixtures/replay/',
 ]
 
 const EXCLUDED_PATHS: readonly string[] = [

package/src/sandbox/replay/expected.ts

@@ -0,0 +1,137 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import type { StepResult } from '@/sandbox/replay/run'
+
+/** Sits in a snapshot's folder beside its `.fixture` files and never reaches the replay tree. */
+export const EXPECTED_FILE = 'expected.json'
+
+export interface StepExpectation {
+  readonly exit: number | null
+  readonly findings: number
+}
+
+/**
+ * A snapshot's recorded answer, keyed by step name. It pins the exit and the
+ * finding count rather than the finding lines, so rewording a warning moves
+ * nothing while a seed sync newly calls missing still drifts.
+ */
+export interface ReplayExpectation {
+  readonly steps: Readonly<Record<string, StepExpectation>>
+}
+
+const RECORD_HINT =
+  'run bun src/cli.ts sandbox replay --record if the change meant it'
+
+export function expectationOf(steps: readonly StepResult[]): ReplayExpectation {
+  return {
+    steps: Object.fromEntries(
+      steps.map((s) => [s.step, { exit: s.exit, findings: s.findings.length }]),
+    ),
+  }
+}
+
+function isStepExpectation(value: unknown): value is StepExpectation {
+  if (typeof value !== 'object' || value === null) return false
+  const { exit, findings } = value as Record<string, unknown>
+
+  return (
+    (exit === null || typeof exit === 'number') && typeof findings === 'number'
+  )
+}
+
+/**
+ * The expectation recorded in `dir`, or undefined when none is. Throws naming
+ * the file and the step when the file holds anything but the recorded shape.
+ */
+export function readExpectation(dir: string): ReplayExpectation | undefined {
+  const path = join(dir, EXPECTED_FILE)
+  if (!existsSync(path)) return undefined
+
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(readFileSync(path, 'utf8'))
+  } catch {
+    throw new Error(`${path} does not parse as JSON`)
+  }
+  const steps =
+    typeof parsed === 'object' && parsed !== null
+      ? (parsed as Record<string, unknown>).steps
+      : undefined
+  if (typeof steps !== 'object' || steps === null)
+    throw new Error(`${path} carries no steps object`)
+  for (const [name, value] of Object.entries(steps))
+    if (!isStepExpectation(value))
+      throw new Error(
+        `${path}: step ${name} needs an exit and a findings count`,
+      )
+
+  return { steps: steps as ReplayExpectation['steps'] }
+}
+
+/** Written the way oxfmt leaves JSON, so a recorded file never fails the format stage. */
+export function writeExpectation(
+  dir: string,
+  expectation: ReplayExpectation,
+): void {
+  writeFileSync(
+    join(dir, EXPECTED_FILE),
+    `${JSON.stringify(expectation, null, 2)}\n`,
+  )
+}
+
+function driftOf(
+  run: StepResult,
+  recorded: StepExpectation | undefined,
+): string | undefined {
+  if (recorded === undefined) return `no recorded answer, ${RECORD_HINT}`
+  if (run.exit !== recorded.exit)
+    return `exit ${run.exit}, recorded ${recorded.exit}`
+  if (run.findings.length !== recorded.findings)
+    return `${run.findings.length} findings, recorded ${recorded.findings}`
+
+  return undefined
+}
+
+/**
+ * Judges a snapshot's steps against its recorded answer. A step that already
+ * failed keeps its verdict, since a crash names more than a changed exit. A
+ * step either side lacks drifts, and with no expectation at all every step
+ * does, since a missing input read as a pass is what the replay exists to stop.
+ */
+export function judgeDrift(
+  steps: readonly StepResult[],
+  expectation: ReplayExpectation | undefined,
+): StepResult[] {
+  if (expectation === undefined)
+    return steps.map((s) =>
+      s.verdict === 'ok'
+        ? {
+            ...s,
+            verdict: 'drifted',
+            detail: `no ${EXPECTED_FILE} for this snapshot, run bun src/cli.ts sandbox replay --record`,
+          }
+        : s,
+    )
+
+  const judged = steps.map((s) => {
+    if (s.verdict !== 'ok') return s
+    const detail = driftOf(s, expectation.steps[s.step])
+
+    return detail === undefined
+      ? s
+      : { ...s, verdict: 'drifted' as const, detail }
+  })
+  const ran = new Set(steps.map((s) => s.step))
+  const dropped = Object.keys(expectation.steps)
+    .filter((name) => !ran.has(name))
+    .map((name): StepResult => ({
+      step: name,
+      argv: [],
+      exit: null,
+      verdict: 'drifted',
+      detail: `recorded but did not run, ${RECORD_HINT}`,
+      findings: [],
+    }))
+
+  return [...judged, ...dropped]
+}

package/src/sandbox/replay/run.ts

@@ -0,0 +1,323 @@
+import { spawnSync } from 'node:child_process'
+import {
+  copyFileSync,
+  cpSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  realpathSync,
+  rmSync,
+} from 'node:fs'
+import { dirname, join, relative } from 'node:path'
+import { gitEnv } from '@/git/env'
+import { EXPECTED_FILE } from '@/sandbox/replay/expected'
+import {
+  findingsOf,
+  judgeFormat,
+  judgeStep,
+  type ReplayVerdict,
+  type StepOutput,
+} from '@/sandbox/replay/verdict'
+import { FIXTURE_SUFFIX, listFixtureFiles } from '@/sandbox/scenario'
+
+export interface ReplaySource {
+  readonly name: string
+  readonly path: string
+  /**
+   * A snapshot is a folder of `.fixture` files with no history, committed
+   * fresh in the copy. A checkout is a consumer's real repository, copied
+   * whole with its history so its gitignored records come along.
+   */
+  readonly kind: 'snapshot' | 'checkout'
+}
+
+export interface ReplayContext {
+  /** The canon checkout whose CLI, formatter, and golden config the replay runs. */
+  readonly checkoutRoot: string
+  /** The folder each replay's temp tree is made under, outside every repository. */
+  readonly tempRoot: string
+}
+
+export interface StepResult {
+  readonly step: string
+  readonly argv: readonly string[]
+  readonly exit: number | null
+  readonly verdict: ReplayVerdict
+  readonly detail?: string
+  /** The `!` lines the step printed, reported whatever the verdict. */
+  readonly findings: readonly string[]
+}
+
+export interface ReplayResult {
+  readonly name: string
+  readonly kind: ReplaySource['kind']
+  readonly steps: readonly StepResult[]
+  /** Paths sync added or changed, relative to the tree, sorted. */
+  readonly written: readonly string[]
+}
+
+/**
+ * The sync, then the reads a consumer runs after one, each `--json` read a
+ * contract on its own stdout. The reads run on the unstaged result, which is
+ * the state a consumer's session meets before anyone commits the sync.
+ */
+const CLI_STEPS: readonly { step: string; args: readonly string[] }[] = [
+  { step: 'sync', args: ['sync', '.'] },
+  { step: 'sync --check', args: ['sync', '--check', '.', '--json'] },
+  { step: 'context audit', args: ['context', 'audit', '--json'] },
+  { step: 'markdown audit', args: ['markdown', 'audit', '--json'] },
+  { step: 'migrate status', args: ['migrate', 'status', '--json'] },
+]
+
+/** Each step took seconds on both consumers in the spike, so five minutes is a hang. */
+const STEP_TIMEOUT_MS = 300_000
+
+/**
+ * A checkout copy skips installs at any depth and the linked worktrees other
+ * sessions hold, neither of which a sync or a health read touches.
+ */
+function isCopied(rel: string): boolean {
+  return rel.split('/').at(-1) !== 'node_modules' && rel !== '.claude/worktrees'
+}
+
+/**
+ * Copies a source into `tree`. A snapshot's files lose their `.fixture`
+ * suffix and its recorded expectation stays behind, and a checkout copies whole rather than cloning, since a clone
+ * drops the gitignored `.canon/` records a consumer's health verbs read.
+ */
+export function copySource(source: ReplaySource, tree: string): void {
+  if (source.kind === 'checkout') {
+    cpSync(source.path, tree, {
+      recursive: true,
+      verbatimSymlinks: true,
+      filter: (from) => isCopied(relative(source.path, from)),
+    })
+    return
+  }
+
+  for (const file of listFixtureFiles(source.path)) {
+    if (relative(source.path, file) === EXPECTED_FILE) continue
+    if (!file.endsWith(FIXTURE_SUFFIX))
+      throw new Error(
+        `Snapshot file missing the ${FIXTURE_SUFFIX} suffix: ${file}`,
+      )
+    const target = join(
+      tree,
+      relative(source.path, file).slice(0, -FIXTURE_SUFFIX.length),
+    )
+    mkdirSync(dirname(target), { recursive: true })
+    copyFileSync(file, target)
+  }
+}
+
+/**
+ * Every child gets git's resolution variables stripped, since a pre-push hook
+ * exports `GIT_DIR` and a commit in the temp tree would otherwise land in the
+ * canon repository running the gate.
+ */
+function childEnv(): NodeJS.ProcessEnv {
+  return { ...gitEnv(), CANON_NON_INTERACTIVE: '1', NO_COLOR: '1' }
+}
+
+function spawn(
+  command: string,
+  argv: readonly string[],
+  cwd: string,
+  json: boolean,
+): StepOutput {
+  const result = spawnSync(command, argv, {
+    cwd,
+    env: childEnv(),
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    timeout: STEP_TIMEOUT_MS,
+    maxBuffer: 64 * 1024 * 1024,
+  })
+
+  return {
+    status: result.status,
+    signal: result.signal,
+    stdout: result.stdout ?? '',
+    stderr: result.stderr ?? result.error?.message ?? '',
+    json,
+  }
+}
+
+function git(tree: string, ...args: string[]): void {
+  const result = spawnSync(
+    'git',
+    [
+      '-c',
+      'user.name=canon-replay',
+      '-c',
+      'user.email=replay@localhost',
+      '-c',
+      'commit.gpgsign=false',
+      ...args,
+    ],
+    { cwd: tree, env: childEnv(), encoding: 'utf8' },
+  )
+  if (result.status !== 0)
+    throw new Error(
+      `git ${args.join(' ')} failed in the replay tree: ${result.stderr.trim()}`,
+    )
+}
+
+/** Every folder under the snapshot root, each one consumer's frozen managed paths. */
+export function listSnapshots(dir: string): ReplaySource[] {
+  if (!existsSync(dir)) return []
+
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort()
+    .map((name) => ({ name, path: join(dir, name), kind: 'snapshot' }))
+}
+
+export interface SourceRefusal {
+  readonly reason: 'not-found' | 'not-a-repo' | 'dirty'
+  readonly message: string
+}
+
+/**
+ * Why a named checkout cannot be replayed, or undefined when it can. A dirty
+ * tree is refused rather than copied, since sync refuses one and the replay
+ * would then read a tree nobody synced, reporting the refusal as a clean run.
+ */
+export function checkoutRefusal(path: string): SourceRefusal | undefined {
+  if (!existsSync(path))
+    return { reason: 'not-found', message: `No folder at ${path}` }
+
+  const top = spawnSync('git', ['rev-parse', '--show-toplevel'], {
+    cwd: path,
+    env: childEnv(),
+    encoding: 'utf8',
+  })
+  if (top.status !== 0 || top.stdout.trim() !== realpathSync(path))
+    return {
+      reason: 'not-a-repo',
+      message: `${path} is not the root of a git repository`,
+    }
+
+  const status = spawnSync('git', ['status', '--porcelain'], {
+    cwd: path,
+    env: childEnv(),
+    encoding: 'utf8',
+  })
+  if (status.stdout.trim() !== '')
+    return {
+      reason: 'dirty',
+      message: `${path} has uncommitted changes. Commit or stash them, then replay it.`,
+    }
+
+  return undefined
+}
+
+/** Added, modified, and untracked paths after the sync. A deletion has nothing to format. */
+function writtenPaths(tree: string): string[] {
+  const result = spawnSync(
+    'git',
+    ['status', '--porcelain', '-z', '--untracked-files=all'],
+    {
+      cwd: tree,
+      env: childEnv(),
+      encoding: 'utf8',
+    },
+  )
+
+  return result.stdout
+    .split('\0')
+    .filter((entry) => entry.length > 3 && !entry.slice(0, 2).includes('D'))
+    .map((entry) => entry.slice(3))
+    .sort()
+}
+
+/**
+ * Copies one source into a fresh temp tree, syncs it with the checkout's own
+ * CLI, and runs the health reads and the format check on the unstaged
+ * result. The tree is removed whatever the steps conclude.
+ */
+export function replaySource(
+  source: ReplaySource,
+  context: ReplayContext,
+): ReplayResult {
+  mkdirSync(context.tempRoot, { recursive: true })
+  const tree = mkdtempSync(join(context.tempRoot, `${source.name}-`))
+  const cli = join(context.checkoutRoot, 'src', 'cli.ts')
+  const steps: StepResult[] = []
+
+  try {
+    copySource(source, tree)
+    if (source.kind === 'snapshot') {
+      git(tree, 'init', '-q', '-b', 'main')
+      git(tree, 'add', '-A')
+      git(tree, 'commit', '-q', '-m', 'snapshot')
+    }
+
+    for (const { step, args } of CLI_STEPS) {
+      const output = spawn('bun', [cli, ...args], tree, args.includes('--json'))
+      steps.push({
+        step,
+        argv: ['canon', ...args],
+        exit: output.status,
+        ...judgeStep(output),
+        findings: findingsOf(output.stderr),
+      })
+    }
+
+    const written = writtenPaths(tree)
+    steps.push(formatStep(context.checkoutRoot, tree, written))
+
+    return { name: source.name, kind: source.kind, steps, written }
+  } finally {
+    rmSync(tree, { recursive: true, force: true })
+  }
+}
+
+/**
+ * Runs the checkout's oxfmt over what sync wrote, under the golden config canon
+ * ships to every target rather than oxfmt's defaults, which quote YAML
+ * frontmatter differently from every consumer and would fail clean files.
+ */
+function formatStep(
+  checkoutRoot: string,
+  tree: string,
+  written: readonly string[],
+): StepResult {
+  const config = join(
+    checkoutRoot,
+    'tooling',
+    'base',
+    'configs',
+    '.oxfmtrc.json',
+  )
+  const args = [
+    '-c',
+    config,
+    '--check',
+    '--no-error-on-unmatched-pattern',
+    ...written,
+  ]
+  const argv = ['oxfmt', '--check', '<written>']
+  if (written.length === 0)
+    return { step: 'format', argv, exit: 0, verdict: 'ok', findings: [] }
+
+  const output = spawn(oxfmtBinary(checkoutRoot), args, tree, false)
+
+  return {
+    step: 'format',
+    argv,
+    exit: output.status,
+    ...judgeFormat(output),
+    findings: [],
+  }
+}
+
+function oxfmtBinary(checkoutRoot: string): string {
+  return join(checkoutRoot, 'node_modules', '.bin', 'oxfmt')
+}
+
+export function hasFormatter(checkoutRoot: string): boolean {
+  return existsSync(oxfmtBinary(checkoutRoot))
+}