@erclx/canon 4.60.0 → 4.62.0

package/docs/workflow/ai-workflow.md

@@ -193,16 +193,17 @@ This section is the corpus the coverage claim is measured against: every name `c
 
 ### Set up a project
 
-| Skill                         | When to use                                                                             |
-| ----------------------------- | --------------------------------------------------------------------------------------- |
-| `canon:setup-init`            | On a fresh scaffold, to detect the stack and run the whole install chain in one pass    |
-| `canon:canon-operator`        | On a project that already exists, to read what it carries before an install is picked   |
-| `canon:setup-gov`             | When the governance rules are wanted without the tooling chain                          |
-| `canon:setup-indexes`         | When a markdown-heavy folder needs an `index.md` a session can browse                   |
-| `canon:setup-plugins`         | On a new machine, to install the community and official plugins user-scoped             |
-| `canon:setup-verify`          | After the agent generates configs, to run the installed scripts and report pass or fail |
-| `canon:claude-design-extract` | Before the first UI feature, to draft `.claude/DESIGN.md`                               |
-| `canon:claude-diagram`        | Once the architecture is written, to draft per-kind entries under `.canon/diagrams/`    |
+| Skill                         | When to use                                                                                                     |
+| ----------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `canon:setup-init`            | On a fresh scaffold, to detect the stack and run the whole install chain in one pass                            |
+| `canon:canon-operator`        | On a project that already exists, to read what it carries before an install is picked                           |
+| `canon:setup-gov`             | When the governance rules are wanted without the tooling chain                                                  |
+| `canon:setup-indexes`         | When a markdown-heavy folder needs an `index.md` a session can browse                                           |
+| `canon:setup-plugins`         | On a new machine, to install the community and official plugins user-scoped                                     |
+| `canon:setup-verify`          | After the agent generates configs, to run the installed scripts and report pass or fail                         |
+| `canon:setup-smoke`           | After `setup-verify` passes, to check the dev and preview servers, end-to-end tests, and the screenshot harness |
+| `canon:claude-design-extract` | Before the first UI feature, to draft `.claude/DESIGN.md`                                                       |
+| `canon:claude-diagram`        | Once the architecture is written, to draft per-kind entries under `.canon/diagrams/`                            |
 
 ### Decide what to build
 

package/governance/rules/ui/440-surface-capture.md

@@ -30,5 +30,7 @@ paths:
 
 ## Sharing a capture
 
-- Attach a capture to the pull request by hand when a reviewer needs to see it.
-- Do not commit a capture. Do not remove the capture folder from `.gitignore`.
+- Do not commit the sweep. It stays ignored.
+- Commit a flagged case's evidence output so the pull request carries the comparison, rather than attaching it by hand.
+- Commit an evidence case for the first time only after running the capture twice with no code change between the runs and confirming the two outputs are byte-identical.
+- Recommitting an unbounded sweep on every run reaches a gigabyte of repository history inside a hundred merges. A small, committed evidence set is what a reviewer needs and what lets GitHub draw its own before-and-after comparison on the pull request.

package/package.json

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

package/src/claude/cases/setup.ts

@@ -30,6 +30,11 @@ export const SETUP_CASES: readonly SkillCase[] = [
       "Run through the generated scaffold's scripts and confirm each one passes.",
     expect: 'setup-verify',
   },
+  {
+    prompt:
+      'Check that the dev server actually starts and the end-to-end suite passes against the scaffold.',
+    expect: 'setup-smoke',
+  },
   {
     prompt:
       'This CLAUDE.md file has grown huge, break it apart into the tiered context model.',

package/src/commands/migrate.ts

@@ -24,6 +24,13 @@ import {
   type RuleLayoutPlan,
   walkFlatRules,
 } from '@/migrate/rule-layout'
+import {
+  applyScratchEvidence,
+  planScratchEvidence,
+  readScratchEvidenceCorpus,
+  type ScratchEvidencePlan,
+  walkScratchEvidenceCorpus,
+} from '@/migrate/scratch-evidence'
 import { PROJECT_ROOT } from '@/project-root'
 import { readStamp, stampedHashes } from '@/sync/stamp'
 import { logError, logInfo, logStep, logWarn, pipeOutput, plural } from '@/ui'
@@ -470,6 +477,96 @@ function toRecordTreeRecord(
   }
 }
 
+interface ScratchEvidenceOptions {
+  readonly json?: boolean
+  readonly write?: boolean
+  readonly root?: string
+}
+
+/**
+ * Moves the nine cited-and-unwritten folders under `.canon/tmp/` to
+ * `.canon/review/evidence/`, and repoints the citations that name them,
+ * archives included.
+ */
+async function runScratchEvidence(
+  opts: ScratchEvidenceOptions,
+): Promise<number> {
+  const root = opts.root ?? process.cwd()
+
+  const files = await walkScratchEvidenceCorpus(root)
+  const sources = await readScratchEvidenceCorpus(files)
+  const plan = planScratchEvidence(root, sources)
+
+  if (opts.json) {
+    process.stdout.write(
+      `${JSON.stringify(toScratchEvidenceRecord(plan, opts.write))}\n`,
+    )
+  }
+
+  reportScratchEvidence(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 applyScratchEvidence(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 reportScratchEvidence(plan: ScratchEvidencePlan): 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')}`)
+  }
+}
+
+function toScratchEvidenceRecord(
+  plan: ScratchEvidencePlan,
+  wrote: boolean | undefined,
+): unknown {
+  return {
+    ok: true,
+    wrote: wrote === true,
+    moves: plan.moves,
+    collisions: plan.collisions,
+    files: plan.entries.length,
+    rewritten: plan.rewritten,
+    paths: plan.entries.map((entry) => ({
+      path: entry.path,
+      rewritten: entry.rewritten,
+    })),
+  }
+}
+
 interface RuleLayoutOptions {
   readonly json?: boolean
   readonly write?: boolean
@@ -673,6 +770,45 @@ export function register(program: Command): void {
       process.exitCode = await runRecordTree(opts)
     })
 
+  migrate
+    .command('scratch-evidence')
+    .description('Promote cited measurement folders out of tmp into review')
+    .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 nine folders cited as measurement evidence from .canon/tmp/ to',
+        '.canon/review/evidence/, which canon records push already backs, and',
+        'repoints every citation that names one, live or archived.',
+        '',
+        'A promoted folder is one a durable record cites and no source file',
+        'under claude/, scripts/, src/, governance/, or standards/ names by',
+        'path. A folder a script still writes into stays in scratch, since',
+        'moving it needs a code change first.',
+        '',
+        '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 scratch-evidence',
+        '  canon migrate scratch-evidence --write',
+        '  canon migrate scratch-evidence --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: ScratchEvidenceOptions) => {
+      process.exitCode = await runScratchEvidence(opts)
+    })
+
   migrate
     .command('rename')
     .description('Rewrite every unprotected aitk token to canon')

package/src/commands/tasks.ts

@@ -9,6 +9,7 @@ import {
   type PlanCitations,
   planCitations,
 } from '@/tasks/archive'
+import { type LabelOutcome, nextLabel } from '@/tasks/label'
 import {
   type CloseOutcome,
   closeOutcomes,
@@ -87,6 +88,11 @@ interface OutcomeCommandOptions {
   readonly root?: string
 }
 
+interface NextLabelCommandOptions {
+  readonly json?: boolean
+  readonly root?: string
+}
+
 export function register(program: Command): void {
   const tasks = program
     .command('tasks')
@@ -379,6 +385,40 @@ export function register(program: Command): void {
     .action(async (task: string | undefined, opts: OutcomeCommandOptions) => {
       process.exitCode = await runOutcome(task, opts)
     })
+
+  tasks
+    .command('next-label')
+    .description(
+      'Report the next unused phase label across the board and its archive',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Emit a machine-readable record on stdout')
+    .option('--root <path>', 'Board root, defaulting to the main worktree')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Reads .canon/tasks/ and its archive/ sibling together, since the',
+        'archive holds labels the live board no longer shows and a scan',
+        'confined to the board hands out one already spent.',
+        '',
+        'Exit codes:',
+        '  0  the label is derived',
+        '  1  refused with no-board',
+        '',
+        'It reports and never writes. Two sessions calling it in the same',
+        'second can still take the same answer, since the board is',
+        'gitignored files rather than a store with a lock.',
+        '',
+        'Examples:',
+        '  canon tasks next-label',
+        '  canon tasks next-label --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: NextLabelCommandOptions) => {
+      process.exitCode = await runNextLabel(opts)
+    })
 }
 
 function collectPosition(value: string, previous: string[]): string[] {
@@ -649,6 +689,50 @@ function reportOutcome(
   return 0
 }
 
+async function runNextLabel(opts: NextLabelCommandOptions): Promise<number> {
+  const root = opts.root ?? (await mainWorktreeRoot())
+  const outcome = await nextLabel(root)
+
+  return reportNextLabel(outcome, opts.json ?? false, root)
+}
+
+function reportNextLabel(
+  outcome: LabelOutcome,
+  emitJson: boolean,
+  root: string,
+): number {
+  if (!outcome.ok) {
+    if (emitJson) {
+      process.stdout.write(
+        `${JSON.stringify({ ok: false, reason: outcome.reason, message: outcome.message })}\n`,
+      )
+      return 1
+    }
+
+    intro('canon tasks next-label')
+    logStep('Refused')
+    logError(outcome.message)
+    outro()
+    return 1
+  }
+
+  if (emitJson) {
+    process.stdout.write(`${JSON.stringify({ ...outcome, root })}\n`)
+    return 0
+  }
+
+  intro('canon tasks next-label')
+  logStep(outcome.label)
+  logInfo(
+    outcome.highest
+      ? `next after ${outcome.highest}.`
+      : 'the board and its archive hold no label yet.',
+  )
+  outro()
+
+  return 0
+}
+
 async function runValidate(opts: ValidateCommandOptions): Promise<number> {
   const root = opts.root ?? (await mainWorktreeRoot())
   const outcome = await validateBoard(root)

package/src/migrate/scratch-evidence.ts

@@ -0,0 +1,319 @@
+/**
+ * The promotion of nine cited measurement folders out of `.canon/tmp/` into
+ * `.canon/review/evidence/`, which `canon records push` already backs.
+ *
+ * The scratch root is the one record root a disk loss takes with it, and a
+ * durable record naming a folder under it as its evidence is a citation into
+ * something the backup never covers. The nine promoted here are every folder
+ * under scratch that a live or archived record cites and no source file under
+ * `claude/`, `scripts/`, `src/`, `governance/`, or `standards/` names by path,
+ * which is what separates them from a folder a script still writes into on its
+ * own schedule.
+ *
+ * Distinct from `record-tree.ts`, which repoints a citation of the `.claude/`
+ * to `.canon/` root move and prunes every `archive` segment on the way in,
+ * since an archived record describes work that already closed. This move
+ * reaches into an archive on purpose: `tasks/archive/`, `plans/archive/`, and
+ * `groundwork/` are where most of the citations broken here already sit, and
+ * a folder promoted out from under them stays gone whether the citing record
+ * is open or closed.
+ *
+ * Honors the same `canon-keep-record-root` marker `records.ts` reads, since a
+ * sentence describing what no target holds is not a live pointer this checkout
+ * has to keep resolving.
+ */
+
+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 { recordDir, SCRATCH } from '@/record-root'
+
+/**
+ * Every folder this promotion moves, at the name it carries under scratch.
+ *
+ * Derived by the two-clause test `canon migrate scratch-evidence` exists to
+ * apply mechanically: a durable record under a `BACKED_FOLDERS` entry, live
+ * or archived, names the folder as its evidence, and no file under `claude/`,
+ * `scripts/`, `src/`, `governance/`, or `standards/` names that path. Measured
+ * 2026-09-06 against nine folders holding thirteen files.
+ *
+ * `verify-astro` and `verify-vite-react` pass the same test and are excluded
+ * by name: both are scaffolds a command generates rather than records a
+ * session wrote, and each is 100+ MB, which the review remote is not sized
+ * for. `ablation`, `eval-runs`, `sandbox-runs`, `memory-archive`,
+ * `groundwork-fixtures`, `precompact-handoff`, `pr-poll`, `pr`,
+ * `address-review`, and `memory-routing` fail the second clause: a script or
+ * a skill body names each of those paths, so moving one needs a code change
+ * first rather than a promotion.
+ */
+export const PROMOTED_FOLDERS: readonly string[] = [
+  'hero-probe',
+  'markdown-corpus-sweep',
+  'orchestrator-output',
+  'orchestrator-watch',
+  'review-calibration',
+  'sandbox-drift',
+  'skill-requirement-pass',
+  'system-map',
+  'target-survey',
+]
+
+const EVIDENCE_ROOT = ['review', 'evidence'] as const
+
+/** Where a promoted folder sits before the move. */
+export function sourcePath(root: string, folder: string): string {
+  return recordDir(root, SCRATCH, folder)
+}
+
+/** Where it lands after, always under whichever root `review/` resolves at. */
+export function destinationPath(root: string, folder: string): string {
+  return recordDir(root, ...EVIDENCE_ROOT, folder)
+}
+
+function escape(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+/**
+ * The prefixes a citation of a promoted folder is spelled with, absolute at
+ * either record root and relative from one directory below it. A tail
+ * rejecting a following name character is what keeps `target-survey` from
+ * swallowing a sibling folder whose name extends it.
+ */
+const OLD_PREFIXES = [
+  '.claude/.tmp/',
+  '.canon/tmp/',
+  '../.tmp/',
+  '../tmp/',
+  '../../.tmp/',
+  '../../tmp/',
+] as const
+
+function citationPattern(folder: string): RegExp {
+  const alternation = OLD_PREFIXES.map(escape).join('|')
+  return new RegExp(
+    `(?:${alternation})${escape(folder)}(?![A-Za-z0-9._-])`,
+    'g',
+  )
+}
+
+/** One promoted folder's citation pattern, paired with its replacement. */
+const REWRITES: readonly {
+  readonly pattern: RegExp
+  readonly folder: string
+}[] = PROMOTED_FOLDERS.map((folder) => ({
+  pattern: citationPattern(folder),
+  folder,
+}))
+
+/**
+ * Marks a line naming a promoted folder's old path on purpose, the same
+ * marker `records.ts` reads: on the line itself or on the nearest non-blank
+ * line above it. A sentence describing what no target holds, rather than
+ * pointing a reader at this checkout's own evidence, needs the old spelling
+ * kept, and a mechanical rewrite cannot tell that apart from a live citation.
+ */
+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): string {
+  return REWRITES.reduce(
+    (current, { pattern, folder }) =>
+      current.replace(pattern, `.canon/review/evidence/${folder}`),
+    line,
+  )
+}
+
+/**
+ * Rewrites every unmarked citation of a promoted folder into its destination
+ * under `.canon/review/evidence/`, absolute regardless of how the source
+ * citation was spelled. A file naming no promoted folder returns
+ * byte-identical, and a marked line is returned unchanged.
+ */
+export function rewriteScratchEvidence(text: string): string {
+  const lines = text.split('\n')
+  return lines
+    .map((line, index) => (isKept(lines, index) ? line : rewriteLine(line)))
+    .join('\n')
+}
+
+/** How many unmarked citations `rewriteScratchEvidence` would change. */
+export function countScratchEvidenceCitations(text: string): number {
+  const lines = text.split('\n')
+  let count = 0
+
+  for (const [index, line] of lines.entries()) {
+    if (isKept(lines, index)) continue
+    for (const { pattern } of REWRITES) {
+      count += [...line.matchAll(pattern)].length
+    }
+  }
+
+  return count
+}
+
+/** The files under every `BACKED_FOLDERS` entry, archives included. */
+export async function walkScratchEvidenceCorpus(
+  root: string,
+): Promise<string[]> {
+  const files: string[] = []
+
+  for (const folder of BACKED_FOLDERS) {
+    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 ScratchEvidenceSource {
+  readonly path: string
+  readonly text: string
+}
+
+/** Reads every file the walk found, skipping one that carries a NUL byte. */
+export async function readScratchEvidenceCorpus(
+  paths: readonly string[],
+): Promise<ScratchEvidenceSource[]> {
+  const sources: ScratchEvidenceSource[] = []
+
+  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 folder: string
+  readonly from: string
+  readonly to: string
+}
+
+export interface CitationEntry {
+  readonly path: string
+  readonly text: string
+  readonly rewritten: number
+}
+
+export interface ScratchEvidencePlan {
+  readonly moves: readonly FolderMove[]
+  readonly collisions: readonly string[]
+  readonly entries: readonly CitationEntry[]
+  readonly rewritten: number
+}
+
+/**
+ * Every promoted folder found on disk, with its destination, refusing a
+ * folder 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 folder of PROMOTED_FOLDERS) {
+    const from = sourcePath(root, folder)
+    if (!existsSync(from)) continue
+
+    const to = destinationPath(root, folder)
+    if (existsSync(to)) {
+      collisions.push(to)
+      continue
+    }
+
+    moves.push({ folder, from, to })
+  }
+
+  return { moves, collisions }
+}
+
+/**
+ * What the promotion would do, without doing it. Pure over the sources it is
+ * handed, the way `planRecordTree` is, so a caller reports and applies from
+ * the same value. A file whose text does not change is dropped.
+ */
+export function planScratchEvidence(
+  root: string,
+  sources: readonly ScratchEvidenceSource[],
+): ScratchEvidencePlan {
+  const { moves, collisions } = planFolderMoves(root)
+  const entries: CitationEntry[] = []
+
+  for (const source of sources) {
+    const rewritten = countScratchEvidenceCitations(source.text)
+    if (rewritten === 0) continue
+
+    entries.push({
+      path: source.path,
+      text: rewriteScratchEvidence(source.text),
+      rewritten,
+    })
+  }
+
+  return {
+    moves,
+    collisions,
+    entries,
+    rewritten: entries.reduce((sum, entry) => sum + entry.rewritten, 0),
+  }
+}
+
+export interface ScratchEvidenceResult {
+  readonly moved: number
+  readonly written: number
+  readonly failed: readonly string[]
+}
+
+/** Writes the plan: every folder move, then every citation rewrite. */
+export async function applyScratchEvidence(
+  plan: ScratchEvidencePlan,
+): Promise<ScratchEvidenceResult> {
+  let moved = 0
+  let written = 0
+  const failed: string[] = []
+
+  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)
+  }
+
+  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)
+  }
+
+  return { moved, written, failed }
+}