@erclx/canon 4.86.0 → 4.87.0

package/docs/workflow/visual-design-workflow.md

@@ -22,7 +22,7 @@ Claude Code reads both and writes the implementation. Works for CLI tools, inter
 
 The toolkit seed in `tooling/claude/seeds/canon/DESIGN.md` ships a token-table template with a starting set of roles, and `standards/design.md` carries the same tables under `## Template` with placeholder rows. The column headers are what the renderer parses, so they stay verbatim in either, while the rows and values are the project's own.
 
-The `canon:design-extract` skill drafts the file, sourcing tokens from a project's existing prose and CLI UI surfaces, or proposing them from `canon/REQUIREMENTS.md` and a `## Personality` paragraph when no UI code exists yet. `canon design render` writes an HTML plus CSS preview to `.canon/review/design/` for eyeballing the current system without leaving Claude Code. See `canon/context/design.md`.
+The `canon:design-extract` skill drafts the file, sourcing tokens from a project's existing prose and CLI UI surfaces, or proposing them from `canon/REQUIREMENTS.md` and a `## Personality` paragraph when no UI code exists yet. `canon design render` writes an HTML plus CSS preview to `.canon/tmp/render/design/` for eyeballing the current system without leaving Claude Code. See `canon/context/design.md`.
 
 A project wanting the toolkit's own values rather than its own runs `canon design install`, which copies one stylesheet to `.claude/design/base.css` carrying the token set as custom properties and two components built on them. That file is toolkit-owned and `canon design sync` refreshes it, so a project overrides a value in `.claude/design/project/` instead, which sync never touches. Nothing arrives without that install, and the two channels are independent: a record drafted by the extract skill is the project's own, and the installed stylesheet is the toolkit's.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "4.86.0",
+  "version": "4.87.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/src/cli.ts

@@ -72,7 +72,7 @@ function showHelp(): void {
     `${GREY}│${NC}    demo [cmd]         ${GREY}# Record a running app (compile, run)${NC}`,
     `${GREY}│${NC}    inventory [subj]   ${GREY}# Report one computed property across every route${NC}`,
     `${GREY}│${NC}    drive <url> <run>  ${GREY}# Walk a page through named interactions and measure each state${NC}`,
-    `${GREY}│${NC}    feedback           ${GREY}# Write toolkit feedback from stdin to .canon/review/feedback/${NC}`,
+    `${GREY}│${NC}    feedback           ${GREY}# Write toolkit feedback from stdin to .canon/feedback/${NC}`,
     `${GREY}│${NC}    transcripts <url>  ${GREY}# Fetch a YouTube transcript with metadata frontmatter${NC}`,
     `${GREY}│${NC}    tasks [cmd]        ${GREY}# Task board commands (archive)${NC}`,
     `${GREY}│${NC}    intake [cmd]       ${GREY}# Intake folders under .canon/intake/ (list, answer)${NC}`,

package/src/commands/design.ts

@@ -16,7 +16,7 @@ import {
   isOwnCheckout,
   PROJECT_ROOT,
 } from '@/project-root'
-import { creationRel } from '@/record-root'
+import { creationRel, SCRATCH } from '@/record-root'
 import { surfaceDir } from '@/surface-root'
 import { recordStamp, runDomainSync } from '@/sync/engine'
 import { resolveTarget } from '@/target'
@@ -113,7 +113,7 @@ export function register(program: Command): void {
     .option(
       '-o, --out <path>',
       'Output directory',
-      creationRel(process.cwd(), 'review', 'design'),
+      creationRel(process.cwd(), SCRATCH, 'render', 'design'),
     )
     .action((opts: { source: string; out: string }) => {
       const sourcePath = resolve(process.cwd(), opts.source)
@@ -143,7 +143,7 @@ export function register(program: Command): void {
     .option(
       '-o, --out <path>',
       'Output directory',
-      creationRel(process.cwd(), 'review', 'board'),
+      creationRel(process.cwd(), SCRATCH, 'render', 'board'),
     )
     .option('--root <path>', 'Project root, defaulting to the main worktree')
     .addHelpText(

package/src/commands/feedback.ts

@@ -40,20 +40,20 @@ function isToolkitSource(): boolean {
 }
 
 /**
- * One producer, one subfolder. The review folder carries the output of four
- * unrelated producers, and the filename prefix was doing the folder's job by
- * hand, so each writes under its own name and the enclosing folder keeps the
- * single ignore entry and the single backed-folder entry it already had.
+ * One producer, one record folder. Feedback is not a review, so it writes
+ * under a root folder of its own rather than inside `review/`, and `canon
+ * records push` backs it with no list edit, since it carries every `.canon/`
+ * entry it does not exclude.
  */
 function writeLocal(body: string, mismatch: string | undefined): string {
-  // Resolved against the same root the write joins onto, so a checkout that has
-  // not migrated its records writes this beside the ones already there rather
-  // than opening a second root nothing reads.
-  const relativeDir = creationRel(PROJECT_ROOT, 'review', 'feedback')
-  const reviewDir = join(PROJECT_ROOT, relativeDir)
-  mkdirSync(reviewDir, { recursive: true })
+  // Resolved against the same root the write joins onto. `creationRel` reads
+  // whichever root already carries a `feedback/` folder and falls back to the
+  // creation root when neither does.
+  const relativeDir = creationRel(PROJECT_ROOT, 'feedback')
+  const feedbackDir = join(PROJECT_ROOT, relativeDir)
+  mkdirSync(feedbackDir, { recursive: true })
   const filename = `feedback-${deriveSlug(body)}-${timestamp()}.md`
-  const filePath = join(reviewDir, filename)
+  const filePath = join(feedbackDir, filename)
   writeFileSync(filePath, `${body}\n`, 'utf8')
 
   // Manual frame rather than `frameSuccess`, since the mismatch warning is a
@@ -72,7 +72,7 @@ export function register(program: Command): void {
   program
     .command('feedback')
     .description(
-      'Write toolkit feedback from stdin to .canon/review/feedback/, or open a GitHub issue with --github',
+      'Write toolkit feedback from stdin to .canon/feedback/, or open a GitHub issue with --github',
     )
     .option(
       '--github',

package/src/commands/migrate.ts

@@ -671,7 +671,7 @@ interface ScratchEvidenceOptions {
 
 /**
  * Moves the nine cited-and-unwritten folders under `.canon/tmp/` to
- * `.canon/review/evidence/`, and repoints the citations that name them,
+ * `.canon/evidence/`, and repoints the citations that name them,
  * archives included.
  */
 async function runScratchEvidence(
@@ -760,9 +760,10 @@ interface RecordLayoutOptions {
 }
 
 /**
- * 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.
+ * Moves every row of `RECORD_LAYOUT_MOVES`: the memory pen's receipts and
+ * retired entries under `.canon/memory/`, and everything under
+ * `.canon/review/` that is not a review out to its own folder, then repoints
+ * the citations that name any of them.
  */
 async function runRecordLayout(opts: RecordLayoutOptions): Promise<number> {
   const root = opts.root ?? process.cwd()
@@ -797,7 +798,7 @@ async function runRecordLayout(opts: RecordLayoutOptions): Promise<number> {
 
   const applied = await applyRecordLayout(plan)
   logStep(
-    `Moved ${plural(applied.moved, 'folder')} and rewrote ${plural(applied.written, 'file')}.`,
+    `Moved ${plural(applied.moved, 'path')} and rewrote ${plural(applied.written, 'file')}.`,
   )
 
   if (applied.failed.length > 0) {
@@ -810,9 +811,10 @@ async function runRecordLayout(opts: RecordLayoutOptions): Promise<number> {
 }
 
 function reportRecordLayout(plan: RecordLayoutPlan): void {
-  logInfo(`${plural(plan.moves.length, 'folder')} to move.`)
+  logInfo(`${plural(plan.moves.length, 'path')} to move.`)
   for (const move of plan.moves) {
-    logInfo(`  ${move.from} -> ${move.to}`)
+    const label = move.classified === undefined ? '' : ` (${move.classified})`
+    logInfo(`  ${move.from} -> ${move.to}${label}`)
   }
 
   logInfo(
@@ -837,7 +839,11 @@ function toRecordLayoutRecord(
   return {
     ok: true,
     wrote: wrote === true,
-    moves: plan.moves.map((move) => ({ from: move.from, to: move.to })),
+    moves: plan.moves.map((move) => ({
+      from: move.from,
+      to: move.to,
+      ...(move.classified === undefined ? {} : { classified: move.classified }),
+    })),
     collisions: plan.collisions,
     files: plan.entries.length,
     rewritten: plan.rewritten,
@@ -1097,7 +1103,7 @@ export function register(program: Command): void {
 
   migrate
     .command('scratch-evidence')
-    .description('Promote cited measurement folders out of tmp into review')
+    .description('Promote cited measurement folders out of tmp into evidence')
     .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')
@@ -1110,7 +1116,7 @@ export function register(program: Command): void {
       [
         '',
         'Moves nine folders cited as measurement evidence from .canon/tmp/ to',
-        '.canon/review/evidence/, which canon records push already backs, and',
+        '.canon/evidence/<nn>-<folder>/, numbered by first appearance, and',
         'repoints every citation that names one, live or archived.',
         '',
         'A promoted folder is one a durable record cites and no source file',
@@ -1136,7 +1142,7 @@ export function register(program: Command): void {
 
   migrate
     .command('record-layout')
-    .description('Fold memory review receipts and archive under memory/')
+    .description('Move record folders to their batch layout')
     .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')
@@ -1151,8 +1157,25 @@ export function register(program: Command): void {
         '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.',
+        'the first time.',
+        '',
+        'Leaves .canon/review/ holding only reviews:',
+        '  review/feedback/                -> feedback/',
+        '  review/{design,board,slides,diagrams}/ -> tmp/render/<kind>/',
+        '  review/references/              -> picks/references/',
+        '  review/branch/review-<slug>.md  -> review/branch-<slug>.md',
+        '  review/ui-checklist-<slug>.md   -> tmp/ui-checklist/<slug>.md',
+        '  review/evidence/<slug>/         -> picks/<slug>/ or evidence/<nn>-<slug>/',
+        '',
+        'An evidence folder is a pick when it directly holds an arm-<id>',
+        'capture or a design-handoff.md, and evidence otherwise. Evidence',
+        'folders are numbered by the oldest file each holds, continuing past',
+        'any ordinal evidence/ already carries. The dry run labels every',
+        'derived destination, so check the split before passing --write.',
+        '',
+        'A citation reaching into a moved folder or naming a moved file is',
+        'repointed, live or archived. A bare mention of an emptied folder, such',
+        'as review/evidence/ with no slug, matches no row and stays as written.',
         '',
         'A receipt sitting at the flat review/ root, the shape memory-review',
         'wrote before review/memory/ existed, is reported rather than moved.',

package/src/commands/slides.ts

@@ -1,7 +1,7 @@
 import { existsSync } from 'node:fs'
 import { resolve } from 'node:path'
 import type { Command } from 'commander'
-import { creationRel } from '@/record-root'
+import { creationRel, SCRATCH } from '@/record-root'
 import { LAYOUTS } from '@/slides/layouts'
 import { openDeck } from '@/slides/open'
 import { renderSlidesDoc } from '@/slides/render'
@@ -20,7 +20,7 @@ export function register(program: Command): void {
     .option(
       '-o, --out <path>',
       'Output directory',
-      creationRel(process.cwd(), 'review', 'slides'),
+      creationRel(process.cwd(), SCRATCH, 'render', 'slides'),
     )
     .option('-v, --variant <variant>', 'Override variant (light or dark)')
     .option(

package/src/design/board.ts

@@ -399,7 +399,7 @@ function isImage(name: string): boolean {
   return IMAGE_EXTENSIONS.some((ext) => name.toLowerCase().endsWith(ext))
 }
 
-/** Every image file directly inside an evidence arm folder, one level deep. */
+/** Every image file directly inside a pick folder, one level deep. */
 function imagesIn(dir: string): string[] {
   return readdirSync(dir, { withFileTypes: true })
     .filter((entry) => entry.isFile() && isImage(entry.name))
@@ -407,32 +407,39 @@ function imagesIn(dir: string): string[] {
     .sort()
 }
 
+/**
+ * The folder under `picks/` holding operator-supplied reference images, which
+ * the References panel reads. It sits beside the captures of the choices it
+ * fed, so the candidates panel steps over it rather than listing it as a pick.
+ */
+const REFERENCES_FOLDER = 'references'
+
 function writeCandidatesPanel(root: string, outDir: string): void {
   const dir = join(outDir, 'candidates')
   mkdirSync(dir, { recursive: true })
 
-  const evidenceDir = recordDir(root, 'review', 'evidence')
-  if (!existsSync(evidenceDir)) {
+  const picksDir = recordDir(root, 'picks')
+  if (!existsSync(picksDir)) {
     writeFileSync(
       join(dir, 'index.html'),
       panelPage(
         'Past candidates',
-        `<p class="empty">No ${relative(root, evidenceDir)} folder yet.</p>`,
+        `<p class="empty">No ${relative(root, picksDir)} folder yet.</p>`,
       ),
     )
     return
   }
 
-  const folders = readdirSync(evidenceDir, { withFileTypes: true })
-    .filter((entry) => entry.isDirectory())
+  const folders = readdirSync(picksDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && entry.name !== REFERENCES_FOLDER)
     .map((entry) => entry.name)
     .sort()
 
   const found: Array<{ folder: string; images: string[] }> = []
   for (const folder of folders) {
-    const images = imagesIn(join(evidenceDir, folder))
+    const images = imagesIn(join(picksDir, folder))
     if (images.length > 0) {
-      cpSync(join(evidenceDir, folder), join(dir, folder), { recursive: true })
+      cpSync(join(picksDir, folder), join(dir, folder), { recursive: true })
       found.push({ folder, images })
     }
   }
@@ -442,7 +449,7 @@ function writeCandidatesPanel(root: string, outDir: string): void {
       join(dir, 'index.html'),
       panelPage(
         'Past candidates',
-        `<p class="empty">${folders.length} folders under ${relative(root, evidenceDir)}/ and none carries a draft-and-pick arm capture. The archival capture step has not run since it shipped.</p>`,
+        `<p class="empty">${folders.length} folders under ${relative(root, picksDir)}/ and none carries a draft-and-pick arm capture. The archival capture step has not run since it shipped.</p>`,
       ),
     )
     return
@@ -462,7 +469,7 @@ function writeReferencesPanel(root: string, outDir: string): void {
   const dir = join(outDir, 'references')
   mkdirSync(dir, { recursive: true })
 
-  const referencesDir = recordDir(root, 'review', 'references')
+  const referencesDir = recordDir(root, 'picks', REFERENCES_FOLDER)
   if (!existsSync(referencesDir)) {
     writeFileSync(
       join(dir, 'index.html'),

package/src/migrate/evidence-ordinal.ts

@@ -0,0 +1,79 @@
+/**
+ * How a folder under `.canon/evidence/` is numbered, shared by the two
+ * migrations that land folders there.
+ *
+ * A folder takes `<nn>-<slug>` in the order folders first appeared, and a new
+ * one continues past the highest ordinal already present. No record folder is
+ * tracked in git, so file modification times are the only history a target
+ * holds to order by.
+ */
+
+import { existsSync, readdirSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import { extractOrdinal } from '@/intake/folder'
+
+const ORDINAL_WIDTH = 2
+
+/**
+ * When a folder first appeared, read as the oldest modification time of any
+ * file under it. A folder holding no file falls back to its own.
+ */
+export function firstAppearance(dir: string): number {
+  let oldest = Number.POSITIVE_INFINITY
+
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const path = join(dir, entry.name)
+    const time = entry.isDirectory()
+      ? firstAppearance(path)
+      : statSync(path).mtimeMs
+    oldest = Math.min(oldest, time)
+  }
+
+  return Number.isFinite(oldest) ? oldest : statSync(dir).mtimeMs
+}
+
+/** The folder names directly inside `dir`, sorted, or none when it is absent. */
+export function folderNames(dir: string): string[] {
+  if (!existsSync(dir)) return []
+
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort()
+}
+
+/** A folder name with any leading ordinal removed. */
+export function slugOf(name: string): string {
+  const ordinal = extractOrdinal(name)
+  return ordinal === '' ? name : name.slice(ordinal.length + 1)
+}
+
+/** The ordinal a new folder takes after every name already present. */
+export function nextOrdinal(existing: readonly string[]): number {
+  return (
+    existing
+      .map((name) => Number(extractOrdinal(name) || 0))
+      .reduce((carry, ordinal) => Math.max(carry, ordinal), 0) + 1
+  )
+}
+
+/** The folder name an ordinal and a slug make together. */
+export function numberedName(ordinal: number, slug: string): string {
+  return `${String(ordinal).padStart(ORDINAL_WIDTH, '0')}-${slug}`
+}
+
+/**
+ * Orders candidate folders by first appearance, breaking an exact tie on the
+ * name so two runs over one tree number it the same way.
+ */
+export function byFirstAppearance<T extends { name: string; dir: string }>(
+  folders: readonly T[],
+): T[] {
+  return folders
+    .map((folder) => ({ folder, appeared: firstAppearance(folder.dir) }))
+    .sort(
+      (a, b) =>
+        a.appeared - b.appeared || a.folder.name.localeCompare(b.folder.name),
+    )
+    .map(({ folder }) => folder)
+}