@erclx/canon 5.32.0 → 5.33.0

package/src/commands/records.ts

@@ -1,8 +1,5 @@
-import { readFile, writeFile } from 'node:fs/promises'
-import { join } from 'node:path'
 import type { Command } from 'commander'
 import { pullRecords, pushRecords } from '@/records/backup'
-import { migrateRecord } from '@/records/migrate'
 import {
   type ClaimOutcome,
   claimOrdinal,
@@ -24,12 +21,6 @@ import {
   type SizeOutcome,
   sizeRecords,
 } from '@/records/size'
-import {
-  DEFAULT_REVIEW_DAYS,
-  type StaleEntry,
-  type StaleReport,
-  staleMemory,
-} from '@/records/stale'
 import {
   type CanonicalDoc,
   type CanonicalReport,
@@ -37,12 +28,10 @@ import {
 } from '@/records/stale-canonical'
 import {
   type Finding,
-  type FindingRemedy,
   isRecordKind,
   isSharedScratch,
   RECORD_KINDS,
   type RecordKind,
-  recordsDir,
   type ValidateOutcome,
   validateRecords,
 } from '@/records/validate'
@@ -62,9 +51,6 @@ import { readLivePlans, stackFindings } from '@/tasks/stack'
 /** Returned when a record carries a finding, which is the gating result. */
 const EXIT_FINDINGS = 2
 
-/** Returned when a record carries a known transform and `--write` was not passed. */
-const EXIT_MIGRATABLE = 2
-
 /** Returned when `--claim` loses every retry to a collision. */
 const EXIT_CONTENDED = 2
 
@@ -78,24 +64,15 @@ interface ValidateCommandOptions {
 
 type BackupCommandOptions = ValidateCommandOptions
 
-interface MigrateCommandOptions extends ValidateCommandOptions {
-  readonly write?: boolean
-}
-
 interface PruneCommandOptions extends ValidateCommandOptions {
   readonly write?: boolean
   readonly olderThan?: string
 }
 
-interface StaleCommandOptions extends ValidateCommandOptions {
-  readonly days?: string
-}
+type StaleCommandOptions = ValidateCommandOptions
 
-/**
- * The kinds `stale` reads. A memory entry ages by days in the shared pen, and
- * a canonical doc ages by the releases shipped since its review.
- */
-const STALE_KINDS = ['memory', 'canonical'] as const
+/** The kinds `stale` reads. A canonical doc ages by the releases shipped since its review. */
+const STALE_KINDS = ['canonical'] as const
 
 interface OrdinalCommandOptions extends ValidateCommandOptions {
   readonly claim?: boolean
@@ -127,7 +104,6 @@ export function register(program: Command): void {
         '  plans       filename, required sections, and the suggested-and-answer contract',
         '  groundwork  README and current-state files, numbering, dating, and a half-closed track',
         '  intake      overview file, numbering, dating, and the four bullets every item carries',
-        '  memory      filename and type prefix, frontmatter, and the body shape each type carries',
         '  standards   frontmatter, the scope section and its handoff list, and a filename',
         '              derived from the governed path',
         '',
@@ -142,7 +118,6 @@ export function register(program: Command): void {
         '',
         'Examples:',
         '  canon records validate plans',
-        '  canon records validate memory',
         '  canon records validate standards',
         '  canon records validate intake --json',
         '',
@@ -152,44 +127,6 @@ export function register(program: Command): void {
       process.exitCode = await runValidate(kind, opts)
     })
 
-  records
-    .command('migrate')
-    .description('Rewrite the records a validate finding names a transform for')
-    .argument('<kind>', `Record folder: ${RECORD_KINDS.join(', ')}`)
-    .helpOption('-h, --help', 'Show this help message')
-    .option('--json', 'Add a machine-readable record on stdout')
-    .option('--write', 'Rewrite every record a transform can repair')
-    .option(
-      '--root <path>',
-      'Project root, defaulting to the main worktree except on standards',
-    )
-    .addHelpText(
-      'after',
-      [
-        '',
-        'Exit codes:',
-        '  0  nothing carries a known transform, or --write repaired every one',
-        '  1  refused, with the reason on stderr or in the JSON record, every',
-        '     candidate it found failed to repair, or --write repaired only',
-        '     some of them',
-        '  2  a record carries a known transform and --write was not passed',
-        '',
-        'It reports and never writes without --write, matching canon records',
-        'validate: a session record has no history to undo a wrong repair from.',
-        'A transform is only offered where the old value is recoverable from the',
-        'file itself, so a finding with no transform is left for a session to fix.',
-        '',
-        'Examples:',
-        '  canon records migrate memory',
-        '  canon records migrate memory --write',
-        '  canon records migrate memory --json',
-        '',
-      ].join('\n'),
-    )
-    .action(async (kind: string, opts: MigrateCommandOptions) => {
-      process.exitCode = await runMigrate(kind, opts)
-    })
-
   records
     .command('ordinal')
     .description(
@@ -272,51 +209,30 @@ export function register(program: Command): void {
   records
     .command('stale')
     .description(
-      'Report which entries are due for review and which cite paths the tree no longer holds',
+      'Report when the requirements record was last reviewed and how many releases have shipped since',
     )
     .argument('<kind>', `Record folder: ${STALE_KINDS.join(', ')}`)
     .helpOption('-h, --help', 'Show this help message')
     .option('--json', 'Add a machine-readable record on stdout')
-    .option(
-      '--days <n>',
-      `Days after a review before a memory entry is due again (default ${DEFAULT_REVIEW_DAYS})`,
-    )
-    .option(
-      '--root <path>',
-      'Project root, defaulting to the main worktree except on canonical',
-    )
+    .option('--root <path>', 'Project root, defaulting to the current worktree')
     .addHelpText(
       'after',
       [
-        '',
-        'memory: reads the top-level entries of the memory folder, never review/, archive/,',
-        'or index.md. An entry is due when it carries no reviewed date, a reviewed',
-        'value that is not a date, or one older than --days. A path is a backticked',
-        'token holding a / and a file extension, resolved against the project root',
-        'after any :line or #heading anchor is stripped. Tokens under .canon/,',
-        'scratch, or worktrees, and any holding a placeholder, glob, variable, or',
-        'elided ... segment, are never reported.',
-        '',
-        'Entries are ordered due first, then those citing a missing path, then the',
-        'longest unreviewed, then by name, so a review takes the first N as a batch.',
         '',
         'canonical: reads REQUIREMENTS.md at whichever surface root carries it,',
         'in the current worktree since it is tracked. It reports its reviewed date',
         'and the release tags merged into HEAD after that day, or never when it',
-        'carries no date. --days does not apply.',
+        'carries no date.',
         '',
         'Exit codes:',
         '  0  the reading completed, whatever it found',
         '  1  refused, with the reason on stderr or in the JSON record',
         '',
-        'It gates nothing and writes nothing. A due entry is a queue position rather',
-        'than a failure, and a missing path or a release count is a prompt for the',
-        'review to judge.',
+        'It gates nothing and writes nothing. A release count is a prompt for the',
+        'review to judge rather than a failure.',
         '',
         'Examples:',
-        '  canon records stale memory',
-        '  canon records stale memory --json',
-        '  canon records stale memory --days 60 --json',
+        '  canon records stale canonical',
         '  canon records stale canonical --json',
         '',
       ].join('\n'),
@@ -357,8 +273,8 @@ export function register(program: Command): void {
         '     delete failed',
         '  2  candidates exist and --write was not passed',
         '',
-        'It writes nothing until --write is passed, matching canon records',
-        'migrate: a session record has no history to undo a wrong delete from.',
+        'It writes nothing until --write is passed, since a session record has',
+        'no history to undo a wrong delete from.',
         'It reads mtime like canon records size, so a machine restored by canon',
         'records pull reads everything as new, which fails safe by offering',
         'nothing.',
@@ -579,34 +495,7 @@ async function runStale(
     )
   }
 
-  if (kind === 'canonical') return runStaleCanonical(opts, emitJson)
-
-  const days = Number(opts.days ?? DEFAULT_REVIEW_DAYS)
-
-  if (!Number.isInteger(days) || days <= 0) {
-    return reportRefusal(
-      'canon records stale',
-      {
-        reason: 'bad-days',
-        message: `--days must be a positive whole number of days, got ${opts.days}.`,
-      },
-      emitJson,
-    )
-  }
-
-  const root = opts.root ?? (await mainWorktreeRoot())
-  const outcome = await staleMemory(root, days)
-
-  if (!outcome.ok)
-    return reportRefusal('canon records stale', outcome, emitJson)
-
-  if (emitJson) {
-    process.stdout.write(`${JSON.stringify(outcome)}\n`)
-    return 0
-  }
-
-  reportStale(outcome)
-  return 0
+  return runStaleCanonical(opts, emitJson)
 }
 
 /**
@@ -618,18 +507,6 @@ async function runStaleCanonical(
   opts: StaleCommandOptions,
   emitJson: boolean,
 ): Promise<number> {
-  if (opts.days !== undefined) {
-    return reportRefusal(
-      'canon records stale',
-      {
-        reason: 'bad-days',
-        message:
-          '--days does not apply to canonical, which counts releases rather than days.',
-      },
-      emitJson,
-    )
-  }
-
   const root = opts.root ?? (await currentWorktreeRoot())
   const outcome = await staleCanonical(root)
 
@@ -671,48 +548,6 @@ function describeCanonical(
   return `${doc.path}: reviewed ${doc.reviewed}, ${since}`
 }
 
-function staleRow(entry: StaleEntry): string[] {
-  return [
-    entry.name,
-    entry.reviewed ?? (entry.invalidReviewed ? 'invalid' : 'never'),
-    entry.unresolved.join(', '),
-  ]
-}
-
-function reportStale(outcome: StaleReport): void {
-  const due = outcome.entries.filter((entry) => entry.due)
-  const moved = outcome.entries.filter((entry) => entry.unresolved.length > 0)
-
-  intro('canon records stale')
-  logStep('Due')
-
-  if (due.length === 0) {
-    logInfo(`none, every entry reviewed within ${plural(outcome.days, 'day')}`)
-  } else {
-    const headers = ['entry', 'reviewed', 'unresolved']
-    const rows = due.map(staleRow)
-    const widths = headers.map((header, column) =>
-      columnWidth(
-        header,
-        rows.map((row) => row[column]),
-      ),
-    )
-    const render = (cells: readonly string[]): string =>
-      cells
-        .map((cell, column) => cell.padEnd(widths[column]))
-        .join('  ')
-        .trimEnd()
-
-    pipeOutput([render(headers), ...rows.map(render)].join('\n'))
-  }
-
-  logStep('Total')
-  logInfo(
-    `${outcome.due} of ${outcome.total} due, ${moved.length} citing a missing path, in ${outcome.folder}`,
-  )
-  outro()
-}
-
 function pruneRow(entry: PruneUnit): string[] {
   return [
     entry.path,
@@ -917,8 +752,7 @@ async function runValidate(
 
 /**
  * Appends the one plans finding that reads across files. It sits in the command
- * layer because `src/records/` sits below `src/tasks/`, and `migrate` iterates
- * `validateRecords` alone, so it never meets a finding with no safe repair.
+ * layer because `src/records/` sits below `src/tasks/`.
  */
 async function validateWithStacks(
   root: string,
@@ -992,226 +826,6 @@ function describe(found: Finding): string {
   return `${scope}${found.subject} ${found.message}`
 }
 
-export interface Repair {
-  readonly record: string
-  readonly remedy: FindingRemedy
-  readonly path: string
-  readonly text: string
-}
-
-export interface Refusal {
-  readonly record: string
-  readonly message: string
-}
-
-/** The message a rejected promise leaves, for a record whose read or write failed. */
-function describeFailure(reason: unknown): string {
-  return reason instanceof Error ? reason.message : String(reason)
-}
-
-/**
- * Runs every finding's transform, without writing anything back.
- *
- * `Promise.allSettled` rather than `Promise.all`, so a record whose read
- * fails, such as one deleted between `validate`'s listing and this read,
- * becomes a refusal for that one record rather than an unhandled rejection
- * that `program.parse()` has no top-level catch for.
- */
-async function attemptMigrations(
-  dir: string,
-  findings: readonly Finding[],
-): Promise<{ repaired: Repair[]; refused: Refusal[] }> {
-  const candidates = findings.filter(
-    (found): found is Finding & { readonly remedy: FindingRemedy } =>
-      found.remedy !== undefined,
-  )
-
-  const settled = await Promise.allSettled(
-    candidates.map(async (found) => {
-      const path = join(dir, found.record)
-      const outcome = migrateRecord(
-        found.remedy,
-        found.record,
-        await readFile(path, 'utf8'),
-      )
-      return { record: found.record, remedy: found.remedy, path, outcome }
-    }),
-  )
-
-  const repaired: Repair[] = []
-  const refused: Refusal[] = []
-
-  settled.forEach((result, index) => {
-    if (result.status === 'rejected') {
-      refused.push({
-        record: candidates[index].record,
-        message: `could not be read: ${describeFailure(result.reason)}`,
-      })
-      return
-    }
-
-    const { record, remedy, path, outcome } = result.value
-
-    if (outcome.ok) {
-      repaired.push({ record, remedy, path, text: outcome.text })
-    } else {
-      refused.push({ record, message: outcome.message })
-    }
-  })
-
-  return { repaired, refused }
-}
-
-/**
- * Writes every repair, independently. `Promise.allSettled` so one record's
- * write failing does not abort the writes that would otherwise have
- * succeeded, per the concurrency standard's rule on batched partial failure.
- */
-async function writeRepairs(
-  repaired: readonly Repair[],
-): Promise<{ written: Repair[]; failed: Refusal[] }> {
-  const settled = await Promise.allSettled(
-    repaired.map((entry) => writeFile(entry.path, entry.text, 'utf8')),
-  )
-
-  const written: Repair[] = []
-  const failed: Refusal[] = []
-
-  settled.forEach((result, index) => {
-    const entry = repaired[index]
-
-    if (result.status === 'fulfilled') {
-      written.push(entry)
-    } else {
-      failed.push({
-        record: entry.record,
-        message: `could not be written: ${describeFailure(result.reason)}`,
-      })
-    }
-  })
-
-  return { written, failed }
-}
-
-async function runMigrate(
-  kind: string,
-  opts: MigrateCommandOptions,
-): Promise<number> {
-  const emitJson = opts.json ?? false
-
-  if (!isRecordKind(kind)) {
-    return reportRefusal(
-      'canon records migrate',
-      {
-        reason: 'unknown-kind',
-        message: `Not a record kind: ${kind}. Expected one of: ${RECORD_KINDS.join(', ')}.`,
-      },
-      emitJson,
-    )
-  }
-
-  const root = opts.root ?? (await defaultRoot(kind))
-  const outcome = await validateRecords(root, kind)
-
-  if (!outcome.ok) {
-    return reportRefusal('canon records migrate', outcome, emitJson)
-  }
-
-  const write = opts.write ?? false
-  const { repaired, refused } = await attemptMigrations(
-    recordsDir(root, kind),
-    outcome.findings,
-  )
-
-  if (!write) {
-    return reportMigrate(root, outcome.kind, repaired, refused, write, emitJson)
-  }
-
-  const { written, failed } = await writeRepairs(repaired)
-
-  return reportMigrate(
-    root,
-    outcome.kind,
-    written,
-    [...refused, ...failed],
-    write,
-    emitJson,
-  )
-}
-
-function reportMigrate(
-  root: string,
-  kind: RecordKind,
-  repaired: readonly Repair[],
-  refused: readonly Refusal[],
-  write: boolean,
-  emitJson: boolean,
-): number {
-  const total = repaired.length + refused.length
-
-  if (emitJson) {
-    process.stdout.write(
-      `${JSON.stringify({
-        ok: true,
-        root,
-        kind,
-        written: write,
-        migrated: repaired.map((entry) => entry.record),
-        refused,
-      })}\n`,
-    )
-  } else {
-    intro('canon records migrate')
-
-    if (total === 0) {
-      logStep('Clean')
-      logInfo('no finding carries a known transform')
-    } else {
-      logStep(write ? 'Rewritten' : 'Would rewrite')
-      if (repaired.length === 0) {
-        logInfo('none, every candidate refused, see below')
-      } else {
-        for (const entry of repaired)
-          logInfo(`${entry.record}: ${entry.remedy}`)
-      }
-
-      if (refused.length > 0) {
-        logStep('Refused')
-        for (const entry of refused)
-          logWarn(`${entry.record}: ${entry.message}`)
-      }
-
-      if (!write && repaired.length > 0) {
-        logInfo('Re-run with --write to apply.')
-      }
-    }
-
-    outro()
-  }
-
-  return migrateExitCode(repaired, refused, write)
-}
-
-/**
- * `repaired` carries only records a transform actually fixed, whether this
- * is a dry run or the set `--write` wrote, so exit 2 (a write is available)
- * never fires when every candidate refused. A dry run reaching that state
- * previously returned the same code as a genuine offer to write, telling a
- * caller `--write` would repair something when it would repair nothing.
- */
-export function migrateExitCode(
-  repaired: readonly Repair[],
-  refused: readonly Refusal[],
-  write: boolean,
-): number {
-  const total = repaired.length + refused.length
-
-  if (total === 0) return 0
-  if (repaired.length === 0) return 1
-  if (!write) return EXIT_MIGRATABLE
-  return refused.length > 0 ? 1 : 0
-}
-
 async function runOrdinal(
   kind: string,
   slug: string,

package/src/commands/sandbox.ts

@@ -126,13 +126,10 @@ function getCategories(): string[] {
   return listCategories(SANDBOX_DIR)
 }
 
-/** Lists a stem in both forms too, so picking it reaches the refusal that names it. */
 function getCommands(category: string): string[] {
-  const { scenarios, ambiguous } = listScenarioFiles(
-    join(SANDBOX_DIR, category),
-  )
+  const { scenarios } = listScenarioFiles(join(SANDBOX_DIR, category))
 
-  return [...scenarios.map((s) => s.command), ...ambiguous].sort()
+  return scenarios.map((s) => s.command)
 }
 
 async function interactivePicker(): Promise<string> {
@@ -188,7 +185,7 @@ function readEnvelope(path: string | undefined): RunEnvelope | undefined {
 
 /**
  * Shared by `--writes` and `--escapes`, which are both a newline-delimited
- * path list written by `run.sh`. Undefined when no file was given, which is
+ * path list written by `canon sandbox run`. Undefined when no file was given, which is
  * not the same as a run that produced no paths. Write scope and escape scope
  * both need that distinction: an empty list is a finding, an absent list is a
  * gap in what the caller supplied.

package/src/commands/tasks.ts

@@ -347,7 +347,7 @@ export function register(program: Command): void {
       [
         '',
         'Exit codes:',
-        '  0  the branch is derived and conforms to standards/branch.md',
+        '  0  the branch is derived and conforms to claude/skills/git-branch/references/branch.md',
         '  1  refused as no-plan, archived, or bad-input',
         '  2  derived, and conforms is false because the slug breaks a cap',
         '',
@@ -566,7 +566,7 @@ export function register(program: Command): void {
         'same second can take the same answer. --claim reserves the label',
         'under .canon/ordinal-locks/ and counts every reservation in the',
         'scan, so two claims return different labels. A dead claim leaves a',
-        'gap, which standards/versioning.md permits.',
+        'gap, which claude/skills/git-commit/references/versioning.md permits.',
         '',
         'Examples:',
         '  canon tasks next-label',
@@ -1245,7 +1245,7 @@ function reportBranch(
     `derived from ${outcome.plan}, ${outcome.words} words and ${outcome.branch.length} characters.`,
   )
   logError(
-    'The slug breaks a cap in standards/branch.md, so hand the row to a person rather than renaming it.',
+    'The slug breaks a cap in claude/skills/git-branch/references/branch.md, so hand the row to a person rather than renaming it.',
   )
   outro()
 

package/src/context/audit.ts

@@ -10,7 +10,7 @@ import { isStubSeed } from '@/tooling/seed-marker'
  * Checkpoint quoted from the standard stating it. It is not a cap.
  *
  * Entry length rests on one entry per domain, which is a domain fact, so
- * `standards/context.md` keeps it. Depth and bullet weight read the same over
+ * `claude/skills/context-fold/references/context.md` keeps it. Depth and bullet weight read the same over
  * any markdown file, so they are stated at the attribute tier and measured by
  * `canon markdown audit` rather than here.
  */
@@ -111,7 +111,7 @@ const PROVENANCE: readonly { kind: ProvenanceKind; pattern: RegExp }[] = [
 /**
  * Verbs that read the date behind them as stamping a measurement.
  *
- * `standards/context.md` cuts a date attached to a change and permits one
+ * `claude/skills/context-fold/references/context.md` cuts a date attached to a change and permits one
  * stamping a measurement, so a pattern matching every ISO date reports against
  * a rule that admits half of what it finds. Separating the two needs the clause
  * rather than the token, since `measured on 2026-08-19` and `overturned on
@@ -154,7 +154,7 @@ const SENTENCE_END = /[.!?:;]\s(?=[^.!?:;]*$)/
  * JSON record publishes as `checkpoints.provenanceFolder` breaks every consumer
  * reading that field for a gain of one word.
  *
- * `standards/context.md` opens its scope by handing figures to the
+ * `claude/skills/context-fold/references/context.md` opens its scope by handing figures to the
  * `draft-figure` skill, so a marker reported in a diagrams entry would cite a
  * rule that entry's own standard routes elsewhere. The length and table
  * checkpoints are quoted from the same standard and keep reaching every audited
@@ -164,7 +164,7 @@ const SENTENCE_END = /[.!?:;]\s(?=[^.!?:;]*$)/
  * What gates here is a rule only this standard states. Bullet weight does not,
  * since `claude/skills/markdown-craft/references/markdown.md` owns that checkpoint across document types and
  * its remedy sends the overflow to prose, which any entry type can act on.
- * `standards/context.md` specializes that remedy for an entry carrying
+ * `claude/skills/context-fold/references/context.md` specializes that remedy for an entry carrying
  * decisions, and specializing a rule narrows the advice rather than the measure.
  *
  * Restating the exclusion in the sibling standards was the alternative for what
@@ -241,7 +241,7 @@ export interface EntryReport {
 }
 
 /**
- * The three questions `standards/context.md` asks of an entry past the
+ * The three questions `claude/skills/context-fold/references/context.md` asks of an entry past the
  * checkpoint, in the order it states them.
  *
  * The standard calls no entry over the checkpoint wrong. It asks whether the

package/src/context/folders.ts

@@ -10,7 +10,7 @@ import { SURFACE_ROOTS } from '@/roots/surface'
  * 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
+ * `claude/skills/context-fold/references/context.md` governs, and `--folder` admits another without an edit
  * here.
  *
  * It doubles as the citation check's scope, since `citationPattern` spells only

package/src/design/budget.ts

@@ -1,5 +1,5 @@
 /**
- * The prose budget `standards/design.md` sets for a design record, and the
+ * The prose budget `claude/skills/canvas-board/references/design.md` sets for a design record, and the
  * counter the `design` gate stage reads it through.
  *
  * The limits live here and in the standard, never in the stage, so the stage

package/src/design/components.ts

@@ -15,7 +15,7 @@
  * `buildDesignCss`'s `components` option, which is what widening that option
  * from a boolean to `boolean | readonly Component[]` bought.
  *
- * It does not live in `canon/DESIGN.md`. `standards/design.md` keeps CSS class
+ * It does not live in `canon/DESIGN.md`. `claude/skills/canvas-board/references/design.md` keeps CSS class
  * names out of that record and says they live in code, which is here.
  */
 

package/src/design/document.ts

@@ -94,7 +94,7 @@ function borderRows(tokens: readonly BorderToken[]): string[][] {
  * and every reason behind them lives in the entry.
  */
 const LEAD = [
-  'Authoring guidance: `standards/design.md`. Rendered from `src/design/tokens.ts` by `canon design regen`, so edit the module and never this file.',
+  'Authoring guidance: `claude/skills/canvas-board/references/design.md`. Rendered from `src/design/tokens.ts` by `canon design regen`, so edit the module and never this file.',
   'Why each value was chosen lives in `canon/context/design/tokens.md`.',
 ].join(' ')
 

package/src/design/regen.ts

@@ -16,7 +16,7 @@ import { NEUTRAL_TOKENS } from '@/design/neutral'
  * gate stage is what keeps silently out of it.
  */
 
-/** The rendered record, at the path `standards/design.md` fixes for it. */
+/** The rendered record, at the path `claude/skills/canvas-board/references/design.md` fixes for it. */
 export const DESIGN_DOCUMENT = join('canon', 'DESIGN.md')
 
 /**