@erclx/canon 4.84.0 → 4.86.0

package/src/commands/migrate.ts

@@ -30,6 +30,13 @@ import {
   planSurfaceRootsMove,
   type SurfaceRootsPlan,
 } from '@/migrate/surface-roots'
+import {
+  applyRecordLayout,
+  planRecordLayout,
+  readRecordLayoutCorpus,
+  type RecordLayoutPlan,
+  walkRecordLayoutCorpus,
+} from '@/migrate/record-layout'
 import {
   applyScratchEvidence,
   planScratchEvidence,
@@ -746,6 +753,102 @@ function toScratchEvidenceRecord(
   }
 }
 
+interface RecordLayoutOptions {
+  readonly json?: boolean
+  readonly write?: boolean
+  readonly root?: string
+}
+
+/**
+ * Moves review receipts from `.canon/review/memory/` to `.canon/memory/review/`
+ * and retired entries from `.canon/tmp/memory-archive/` to
+ * `.canon/memory/archive/`, and repoints the citations that name either.
+ */
+async function runRecordLayout(opts: RecordLayoutOptions): Promise<number> {
+  const root = opts.root ?? process.cwd()
+
+  const files = await walkRecordLayoutCorpus(root)
+  const sources = await readRecordLayoutCorpus(files)
+  const plan = planRecordLayout(root, sources)
+
+  if (opts.json) {
+    process.stdout.write(
+      `${JSON.stringify(toRecordLayoutRecord(plan, opts.write))}\n`,
+    )
+  }
+
+  reportRecordLayout(plan)
+
+  if (plan.collisions.length > 0) {
+    logError(
+      `${plural(plan.collisions.length, 'destination')} already occupied. Neither side moved.`,
+    )
+    for (const collision of plan.collisions) logError(`  ${collision}`)
+  }
+
+  if (plan.moves.length === 0 && plan.entries.length === 0) {
+    return plan.collisions.length > 0 ? 1 : 0
+  }
+
+  if (!opts.write) {
+    logWarn('Nothing was written. Pass --write to apply this plan.')
+    return 2
+  }
+
+  const applied = await applyRecordLayout(plan)
+  logStep(
+    `Moved ${plural(applied.moved, 'folder')} and rewrote ${plural(applied.written, 'file')}.`,
+  )
+
+  if (applied.failed.length > 0) {
+    logError(`Could not write ${plural(applied.failed.length, 'file')}.`)
+    for (const path of applied.failed) logError(`  ${path}`)
+    return 1
+  }
+
+  return plan.collisions.length > 0 ? 1 : 0
+}
+
+function reportRecordLayout(plan: RecordLayoutPlan): void {
+  logInfo(`${plural(plan.moves.length, 'folder')} to move.`)
+  for (const move of plan.moves) {
+    logInfo(`  ${move.from} -> ${move.to}`)
+  }
+
+  logInfo(
+    `${plural(plan.entries.length, 'file')} to change, ${plural(plan.rewritten, 'citation')} to rewrite.`,
+  )
+  for (const entry of plan.entries) {
+    logInfo(`  ${entry.path}: ${plural(entry.rewritten, 'citation')}`)
+  }
+
+  if (plan.strays.length > 0) {
+    logWarn(
+      `${plural(plan.strays.length, 'stray receipt')} at the flat review/ root. Not moved, move by hand into memory/review/.`,
+    )
+    for (const stray of plan.strays) logWarn(`  ${stray}`)
+  }
+}
+
+function toRecordLayoutRecord(
+  plan: RecordLayoutPlan,
+  wrote: boolean | undefined,
+): unknown {
+  return {
+    ok: true,
+    wrote: wrote === true,
+    moves: plan.moves.map((move) => ({ from: move.from, to: move.to })),
+    collisions: plan.collisions,
+    files: plan.entries.length,
+    rewritten: plan.rewritten,
+    strays: plan.strays,
+    paths: plan.entries.map((entry) => ({
+      path: entry.path,
+      rewritten: entry.rewritten,
+    })),
+  }
+}
+
 interface RuleLayoutOptions {
   readonly json?: boolean
   readonly write?: boolean
@@ -1031,6 +1134,45 @@ export function register(program: Command): void {
       process.exitCode = await runScratchEvidence(opts)
     })
 
+  migrate
+    .command('record-layout')
+    .description('Fold memory review receipts and archive under memory/')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .option('--write', 'Apply the plan rather than reporting it')
+    .option(
+      '--root <path>',
+      'Project root, defaulting to the working directory',
+    )
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Moves review receipts from .canon/review/memory/ to',
+        '.canon/memory/review/, and retired entries from',
+        '.canon/tmp/memory-archive/ to .canon/memory/archive/, backed for',
+        'the first time, and repoints every citation that names either,',
+        'live or archived.',
+        '',
+        'A receipt sitting at the flat review/ root, the shape memory-review',
+        'wrote before review/memory/ existed, is reported rather than moved.',
+        '',
+        'Exit codes:',
+        '  0  nothing to move, or --write applied the whole plan',
+        '  1  a write failed, or an unresolved collision remains',
+        '  2  a plan exists and --write was not passed',
+        '',
+        'Examples:',
+        '  canon migrate record-layout',
+        '  canon migrate record-layout --write',
+        '  canon migrate record-layout --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: RecordLayoutOptions) => {
+      process.exitCode = await runRecordLayout(opts)
+    })
+
   migrate
     .command('rename')
     .description('Rewrite every unprotected aitk token to canon')

package/src/commands/records.ts

@@ -1,7 +1,7 @@
 import { readFile, writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import type { Command } from 'commander'
-import { BACKED_FOLDERS, pullRecords, pushRecords } from '@/records/backup'
+import { pullRecords, pushRecords } from '@/records/backup'
 import { migrateRecord } from '@/records/migrate'
 import {
   type ClaimOutcome,
@@ -14,7 +14,7 @@ import {
   type FolderSize,
   formatBytes,
   GROWTH_WINDOWS,
-  SIZED_FOLDERS,
+  sizedFolders,
   type SizeOutcome,
   sizeRecords,
 } from '@/records/size'
@@ -207,8 +207,9 @@ export function register(program: Command): void {
       'after',
       [
         '',
-        'Folders read under .claude/:',
-        `  ${SIZED_FOLDERS.join(', ')}`,
+        'Folders read, at whichever record root the project carries:',
+        '  every folder canon records push carries, plus the scratch folder',
+        '  (deletable without loss, so a backup skips it, but a reading does not)',
         '',
         'Exit codes:',
         '  0  the reading completed',
@@ -274,8 +275,10 @@ function backupHelp(verb: 'push' | 'pull'): string {
 
   return [
     '',
-    'Backed folders under .claude/:',
-    `  ${BACKED_FOLDERS.join(', ')}`,
+    'Backed folders, at whichever record root the project carries:',
+    '  every top-level entry, less tmp, ordinal-locks, and .records.git',
+    '  (a legacy .claude root instead uses a fixed list; run this with --json',
+    '  to see what actually resolved, including any folder seen for the first time)',
     '',
     'Exit codes:',
     '  0  the records remote and this machine agree',
@@ -404,6 +407,9 @@ async function runPush(opts: BackupCommandOptions): Promise<number> {
   logInfo(
     `${outcome.folders.length} folder(s), ${outcome.changed} path(s) changed`,
   )
+  if (outcome.firstSeen.length > 0) {
+    logWarn(`first seen: ${outcome.firstSeen.join(', ')}`)
+  }
   logStep(outcome.pushed ? 'Pushed' : 'Nothing to push')
   logInfo(
     outcome.commit

package/src/design/tokens.ts

@@ -104,7 +104,7 @@ export const TOKENS: DesignTokens = {
   ].join('\n'),
 
   colorNote: [
-    'Every role clears WCAG AA at 4.5:1 against each ground it declares, asserted in `src/design/contrast.test.ts`. Two corrections landed with this record becoming the source. The light `muted` step moved from `#7A736A`, which read 4.38 and 4.09 against the two light grounds, and the dark `accent` moved off the `#C8602E` the slide theme carried, which read 4.36 and 3.99 against the two dark ones. Both now sit on the values below.',
+    'Every role clears WCAG AA at 4.5:1 against each ground it declares, asserted in `src/design/contrast.test.ts`.',
     '',
     'Warning and error hold ANSI codes because that is what `scripts/lib/ui.sh` writes and no rendered surface implements an equivalent. Giving either a hex value would invent a mapping no file has, so they carry no contrast reading either.',
     '',
@@ -232,7 +232,7 @@ export const TOKENS: DesignTokens = {
   typographyNote: [
     'One family covers every role but `page-display`, which is the landing page hero and takes the proportional sibling of the same superfamily. The size scale runs from 11.5 to 52 pixels, and six values map onto a role. Five further values are adjustments inside a single component and get no role here, since a scale with five invented steps reads as a system the surfaces do not implement. They are 11.5, 12.5, 13, 14, and 15 pixels.',
     '',
-    'The 52 pixel step sits above the 34 the rest of the scale tops out at, and it is the one size no other surface reaches. A hero headline set at the display cap reads as a section heading rather than an opening, which four rendered arms measured on 2026-09-04 before the step was added.',
+    'The 52 pixel step sits above the 34 the rest of the scale tops out at, and it is the one size no other surface reaches, since a hero headline set at the display cap reads as an opening rather than as a section heading.',
     '',
     'A tagged cell is one no rendering surface exercises yet, which is a declaration the system has not tested rather than one it has.',
     '',
@@ -353,8 +353,11 @@ export const TOKENS: DesignTokens = {
   motion:
     'Motion is not used. No transition, animation, or keyframe declaration appears on any rendered surface, and the capture pipeline screenshots a static frame.',
 
-  iconography:
-    "No icon library is installed. `assets/brand/mark.svg` is the one authored icon, embedded inline in the hero topbar, and the surfaces otherwise draw literal glyph characters: `│ ├ ✓ ! ✗ + - ◆ ◇ ❯` for the terminal framing. The same mark also ships as a favicon on every rendered surface, as three independently-maintained copies that track different accents by design rather than by drift: `regen-hero.sh` derives one from the live SVG colored with whatever `--color-accent` (`#e0724b`) the fetched token CSS carries, `src/design/render.ts` carries the path data as a hardcoded literal colored via `colorValue('light-accent')` (`#a4471c`), since a data URI has no CSS context and that page renders on light chrome, and `teach-workspace`'s `SKILL.md` names one in prose colored `rgb(224,114,75)`, the same value as the dark accent written as decimal rather than hex to clear the shipped-references gate's commit-sha check. Unifying the three or repairing the one that looks drifted would break the fit each was chosen for.",
+  iconography: [
+    'No icon library is installed. `assets/brand/mark.svg` is the one authored icon, embedded inline in the hero topbar, and the surfaces otherwise draw literal glyph characters: `│ ├ ✓ ! ✗ + - ◆ ◇ ❯` for the terminal framing.',
+    '',
+    'The same mark ships as a favicon on every rendered surface, as three independently-maintained copies that track different accents by design rather than by drift, colored to fit the chrome each renders on: the dark accent (`#e0724b`) for a dark-chrome surface and the light accent (`#a4471c`) for a light-chrome one. Unifying the three or repairing the one that looks drifted would break the fit each was chosen for. `canon/context/design.md` carries which file holds each copy.',
+  ].join('\n'),
 }
 
 /** A role's value, or `undefined` where the record declares no such role. */

package/src/migrate/record-layout.ts

@@ -0,0 +1,346 @@
+/**
+ * The memory pen's review receipts and retired entries, folded under the pen
+ * itself rather than sitting in three separate record folders.
+ *
+ * `.canon/review/memory/` and `.canon/tmp/memory-archive/` move to
+ * `.canon/memory/review/` and `.canon/memory/archive/`, the second one backed
+ * for the first time: `canon records push` carries every top-level `.canon/`
+ * entry except `EXCLUDED_ENTRIES`, and `tmp/` is one of the three names that
+ * set excludes. `canon/ARCHITECTURE.md`'s "A durable record is named for what
+ * it is, not for how long it lives" already names the cost this closes: two
+ * surfaces both named for memory archived to two different places.
+ *
+ * The move and the citation repoint follow `scratch-evidence.ts`'s shape: a
+ * dry run by default, `--write` to apply, a collision refusal, the
+ * `canon-keep-record-root` marker honored, and archives swept on purpose,
+ * since an archived receipt still cites the row it retired.
+ *
+ * `moves` is a data table rather than one function per pair, so a later
+ * intake batch in the same folder-layout group appends an entry instead of
+ * restructuring the module.
+ */
+
+import { existsSync, readdirSync } from 'node:fs'
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { presentFolders } from '@/records/backup'
+import { recordDir, SCRATCH, spell, type RecordRoot } from '@/record-root'
+
+const CANON: RecordRoot = '.canon'
+const CLAUDE: RecordRoot = '.claude'
+
+export interface RecordLayoutMove {
+  readonly from: readonly string[]
+  readonly to: readonly string[]
+}
+
+/**
+ * Every folder this migration moves, as a record-relative path on each side.
+ *
+ * Derived from the plan's own mapping: the review folder's memory receipts
+ * fold into the pen at `memory/review/`, and the scratch archive folds in at
+ * `memory/archive/`. A later batch in the same intake group appends here
+ * rather than adding a second table.
+ */
+export const RECORD_LAYOUT_MOVES: readonly RecordLayoutMove[] = [
+  { from: ['review', 'memory'], to: ['memory', 'review'] },
+  { from: [SCRATCH, 'memory-archive'], to: ['memory', 'archive'] },
+]
+
+/** Where a move's source sits today. */
+export function sourcePath(root: string, move: RecordLayoutMove): string {
+  const [folder, ...rest] = move.from
+  return recordDir(root, folder, ...rest)
+}
+
+/** Where it lands after, always under whichever root `memory/` resolves at. */
+export function destinationPath(root: string, move: RecordLayoutMove): string {
+  const [folder, ...rest] = move.to
+  return recordDir(root, folder, ...rest)
+}
+
+function escape(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+/**
+ * The prefixes a citation of a move's source is spelled with: absolute at
+ * either record root, spelled the way each root spells the leading segment,
+ * and relative one and two directories up, in both spellings, since a
+ * relative citation carries no root of its own to read the spelling from.
+ */
+function oldPrefixes(from: readonly string[]): readonly string[] {
+  const [head, ...rest] = from
+  const canonSuffix = [spell(CANON, head), ...rest].join('/')
+  const claudeSuffix = [spell(CLAUDE, head), ...rest].join('/')
+
+  const prefixes = new Set<string>([
+    `.canon/${canonSuffix}/`,
+    `.claude/${claudeSuffix}/`,
+  ])
+  for (const suffix of [canonSuffix, claudeSuffix]) {
+    prefixes.add(`../${suffix}/`)
+    prefixes.add(`../../${suffix}/`)
+  }
+
+  return [...prefixes]
+}
+
+function citationPattern(move: RecordLayoutMove): RegExp {
+  const alternation = oldPrefixes(move.from).map(escape).join('|')
+  return new RegExp(`(?:${alternation})`, 'g')
+}
+
+interface Rewrite {
+  readonly pattern: RegExp
+  readonly destination: string
+}
+
+/** One rewrite per move, paired with its citation pattern. */
+function buildRewrites(moves: readonly RecordLayoutMove[]): readonly Rewrite[] {
+  return moves.map((move) => ({
+    pattern: citationPattern(move),
+    destination: `.canon/${move.to.join('/')}/`,
+  }))
+}
+
+/**
+ * Marks a line naming a moved path on purpose, the same marker
+ * `scratch-evidence.ts` and `records.ts` read: on the line itself or on the
+ * nearest non-blank line above it.
+ */
+const KEEP_MARKER = 'canon-keep-record-root'
+
+function isKept(lines: readonly string[], index: number): boolean {
+  if (lines[index]?.includes(KEEP_MARKER)) return true
+
+  let above = index - 1
+  while (above >= 0 && lines[above]?.trim() === '') above -= 1
+
+  return above >= 0 && (lines[above]?.includes(KEEP_MARKER) ?? false)
+}
+
+function rewriteLine(line: string, rewrites: readonly Rewrite[]): string {
+  return rewrites.reduce(
+    (current, { pattern, destination }) =>
+      current.replace(pattern, destination),
+    line,
+  )
+}
+
+interface RewriteOutcome {
+  readonly text: string
+  readonly count: number
+}
+
+/**
+ * Rewrites every unmarked citation a move covers into its destination,
+ * counting each as it goes. A file naming no such path returns
+ * byte-identical with a count of zero, and a marked line is returned
+ * unchanged and uncounted.
+ */
+function applyRewrites(
+  text: string,
+  rewrites: readonly Rewrite[],
+): RewriteOutcome {
+  const lines = text.split('\n')
+  let count = 0
+
+  const rewritten = lines.map((line, index) => {
+    if (isKept(lines, index)) return line
+
+    for (const { pattern } of rewrites) {
+      count += [...line.matchAll(pattern)].length
+    }
+    return rewriteLine(line, rewrites)
+  })
+
+  return { text: rewritten.join('\n'), count }
+}
+
+/** The files under every present backed folder at `root`, archives included. */
+export async function walkRecordLayoutCorpus(root: string): Promise<string[]> {
+  const files: string[] = []
+
+  for (const folder of presentFolders(root)) {
+    const dir = recordDir(root, folder)
+    if (!existsSync(dir)) continue
+
+    const glob = new Bun.Glob('**/*')
+    for await (const path of glob.scan({
+      cwd: dir,
+      onlyFiles: true,
+      dot: true,
+    })) {
+      files.push(join(dir, path))
+    }
+  }
+
+  return files.sort()
+}
+
+export interface RecordLayoutSource {
+  readonly path: string
+  readonly text: string
+}
+
+/** Reads every file the walk found, skipping one that carries a NUL byte. */
+export async function readRecordLayoutCorpus(
+  paths: readonly string[],
+): Promise<RecordLayoutSource[]> {
+  const sources: RecordLayoutSource[] = []
+
+  for (const path of paths) {
+    const bytes = await readFile(path).catch(() => undefined)
+    if (bytes === undefined || bytes.includes(0)) continue
+
+    sources.push({ path, text: bytes.toString('utf8') })
+  }
+
+  return sources
+}
+
+export interface FolderMove {
+  readonly move: RecordLayoutMove
+  readonly from: string
+  readonly to: string
+}
+
+export interface CitationEntry {
+  readonly path: string
+  readonly text: string
+  readonly rewritten: number
+}
+
+export interface RecordLayoutPlan {
+  readonly moves: readonly FolderMove[]
+  readonly collisions: readonly string[]
+  readonly entries: readonly CitationEntry[]
+  readonly rewritten: number
+  readonly strays: readonly string[]
+}
+
+const STRAY_RECEIPT_PATTERN = /^memory-review-.*\.md$/
+
+/**
+ * A receipt sitting at the flat `review/` root, the shape `memory-review`
+ * wrote before `.canon/review/memory/` existed. Neither mapped move covers
+ * it, since it sits one level above the folder either move reads, so it is
+ * reported rather than moved: widening the table for one stray file trades a
+ * data-shaped mapping for a special case.
+ */
+export function strayReceipts(root: string): string[] {
+  const dir = recordDir(root, 'review')
+  const entries = existsSync(dir)
+    ? readdirSync(dir, { withFileTypes: true })
+    : []
+
+  return entries
+    .filter((entry) => entry.isFile() && STRAY_RECEIPT_PATTERN.test(entry.name))
+    .map((entry) => join(dir, entry.name))
+    .sort()
+}
+
+/**
+ * Every mapped move found on disk, with its destination, refusing a move
+ * whose destination is already occupied rather than merging into it.
+ */
+export function planFolderMoves(root: string): {
+  moves: FolderMove[]
+  collisions: string[]
+} {
+  const moves: FolderMove[] = []
+  const collisions: string[] = []
+
+  for (const move of RECORD_LAYOUT_MOVES) {
+    const from = sourcePath(root, move)
+    if (!existsSync(from)) continue
+
+    const to = destinationPath(root, move)
+    if (existsSync(to)) {
+      collisions.push(to)
+      continue
+    }
+
+    moves.push({ move, from, to })
+  }
+
+  return { moves, collisions }
+}
+
+/**
+ * What the migration would do, without doing it. Pure over the sources it is
+ * handed, so a caller reports and applies from the same value. A file whose
+ * text does not change is dropped.
+ */
+export function planRecordLayout(
+  root: string,
+  sources: readonly RecordLayoutSource[],
+): RecordLayoutPlan {
+  const { moves, collisions } = planFolderMoves(root)
+  const collidedDestinations = new Set(collisions)
+  const covered = RECORD_LAYOUT_MOVES.filter(
+    (move) => !collidedDestinations.has(destinationPath(root, move)),
+  )
+  const rewrites = buildRewrites(covered)
+  const entries: CitationEntry[] = []
+
+  for (const source of sources) {
+    const { text, count } = applyRewrites(source.text, rewrites)
+    if (count === 0) continue
+
+    entries.push({ path: source.path, text, rewritten: count })
+  }
+
+  return {
+    moves,
+    collisions,
+    entries,
+    rewritten: entries.reduce((sum, entry) => sum + entry.rewritten, 0),
+    strays: strayReceipts(root),
+  }
+}
+
+export interface RecordLayoutResult {
+  readonly moved: number
+  readonly written: number
+  readonly failed: readonly string[]
+}
+
+/**
+ * Writes the plan: every citation rewrite first, then every folder move.
+ *
+ * A citation can sit inside a file the plan is about to move, since the walk
+ * carries archives on purpose and a receipt can cite the row it retired.
+ * Rewriting first is what keeps that write landing on a path that still
+ * exists: renaming the folder first would send `writeFile` at the pre-move
+ * path into a directory `rename` already cleared.
+ */
+export async function applyRecordLayout(
+  plan: RecordLayoutPlan,
+): Promise<RecordLayoutResult> {
+  let moved = 0
+  let written = 0
+  const failed: string[] = []
+
+  for (const entry of plan.entries) {
+    const done = await writeFile(entry.path, entry.text)
+      .then(() => true)
+      .catch(() => false)
+
+    if (done) written += 1
+    else failed.push(entry.path)
+  }
+
+  for (const move of plan.moves) {
+    await mkdir(dirname(move.to), { recursive: true })
+    const done = await rename(move.from, move.to)
+      .then(() => true)
+      .catch(() => false)
+
+    if (done) moved += 1
+    else failed.push(move.from)
+  }
+
+  return { moved, written, failed }
+}

package/src/migrate/record-tree.ts

@@ -60,7 +60,7 @@ export const OBJECT_STORE = '.records.git'
  * `archive` is the substantive one: an archived plan or a retired memory entry
  * describes work that closed, and a path inside that sentence is history rather
  * than a pointer. It is pruned at any depth because the archives do not all sit
- * at the same one, `review/memory/archive/` being two levels down.
+ * at the same one, `memory/review/archive/` being two levels down.
  */
 export const PRUNED_SEGMENTS: readonly string[] = [
   'archive',

package/src/migrate/scratch-evidence.ts

@@ -26,7 +26,7 @@
 import { existsSync } from 'node:fs'
 import { mkdir, readFile, rename, writeFile } from 'node:fs/promises'
 import { dirname, join } from 'node:path'
-import { BACKED_FOLDERS } from '@/records/backup'
+import { presentFolders } from '@/records/backup'
 import { recordDir, SCRATCH } from '@/record-root'
 
 /**
@@ -168,13 +168,13 @@ function applyRewrites(
   return { text: rewritten.join('\n'), count }
 }
 
-/** The files under every `BACKED_FOLDERS` entry, archives included. */
+/** The files under every present backed folder at `root`, archives included. */
 export async function walkScratchEvidenceCorpus(
   root: string,
 ): Promise<string[]> {
   const files: string[] = []
 
-  for (const folder of BACKED_FOLDERS) {
+  for (const folder of presentFolders(root)) {
     const dir = recordDir(root, folder)
     if (!existsSync(dir)) continue
 

package/src/record-root.ts

@@ -70,9 +70,11 @@ export const RECORD_ENTRIES: readonly string[] = [
   'memory',
   'plans',
   'proposals',
+  'ready',
   'review',
   'tasks',
   'teach',
+  'transcripts',
   'walkthroughs',
 ]