@erclx/canon 4.9.0 → 4.9.1

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "4.9.0",
+  "version": "4.9.1",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/docs/agents/commands.md

@@ -142,7 +142,9 @@ Common patterns:
 
 `migrate rename` moves a project off the retired `aitk` name. It reports until `--write` is passed, and `--scope target` rewrites the toolkit-owned folders alone, reporting every other citation as one the project owns rather than editing prose somebody wrote. A project installing `canon` fresh never needs it.
 
-`migrate records` moves a project's session records from `.claude/` to `.canon/` and rewrites every tracked file that cites one. It reports until `--write` is passed, and refuses outright when the project does not already ignore `.canon/`, since every folder it relocates is ignored where it stands and landing one under a tracked root commits the memory pen. Take the ignore entry with `canon tooling sync --write` first. A record folder already present at the destination is a refusal rather than a merge, and a line carrying `canon-keep-record-root`, or the line below it, keeps the old spelling for prose that dates a decision. Running it twice rewrites nothing, which is the check that the exclusions and the markers fired.
+`migrate records` moves a project's session records from `.claude/` to `.canon/` and rewrites every tracked file that cites one. It reports until `--write` is passed, and refuses outright when the project does not already ignore `.canon/`, since every folder it relocates is ignored where it stands and landing one under a tracked root commits the memory pen. Take the ignore entry with `canon tooling sync --write` first.
+
+A record folder already present at the destination is a refusal rather than a merge, and a line carrying `canon-keep-record-root`, or the line below it, keeps the old spelling for prose that dates a decision. The records themselves are never swept: everything under `.canon/` and every `.claude/` record folder is passed over and reported as a count on its own line, which is what keeps the run that follows the ignore collapse touching the same files as one before it. Running it twice rewrites nothing, which is the check that the exclusions, the markers, and that skip all fired.
 
 ## Version skew
 

package/docs/target-projects.md

@@ -128,15 +128,17 @@ When the toolkit updates, target projects pull changes per domain. There is one
 
 Session records moved out of `.claude/` and into a root of their own. What is committed stays where it is, and everything gitignored, being the task board, the plans, the memory pen, the review reports, and the scratch folder, now lives under `.canon/`, which a single ignore entry covers.
 
-**`canon migrate records` is not in a published release yet.** It ships with the change that split the roots, so an installed binary answers `unknown command` until the next release carries it. Until then, run it out of a canon checkout against the project by path:
+`4.7.0` carries `canon migrate records`, so run these three lines from inside the project. Run `canon upgrade` first regardless of what you hold, since the sweep learned to pass over the records themselves after that release and a `4.7.0` binary rewrites them.
 
 ```bash
 canon tooling sync claude . --write
-bun src/cli.ts migrate records --root /path/to/project --json
-bun src/cli.ts migrate records --root /path/to/project --write --json
+canon migrate records --json
+canon migrate records --write --json
 ```
 
-Once the release lands, the same three lines read `canon migrate records` from inside the project. Either way the first line takes the `.canon/` ignore entry, and the verb refuses until the project has it, since every folder it relocates is ignored where it stands and landing one under a tracked root commits the memory pen. The second reports the plan and the third applies it, moving the folders and repointing every tracked file that cites one.
+The first line takes the `.canon/` ignore entry, and the verb refuses until the project has it, since every folder it relocates is ignored where it stands and landing one under a tracked root commits the memory pen. The second reports the plan and the third applies it, moving the folders and repointing every tracked file that cites one.
+
+Order matters between the first line and the two under it. The sync prunes the twelve old `.claude/` ignore entries down to the one `.canon/` line, which leaves every record still at the old root visible to git and therefore to the verb. The sweep passes over them on purpose, reporting a count of what it left alone rather than reading the memory pen and the groundwork trails as source.
 
 Read the `ok` field out of the `--json` record rather than the exit code. A shell profile that wraps `canon` in a function takes its status from whatever the function runs last, so an absent subcommand and a clean run can both exit 0, and a reader watching the exit alone concludes the move happened.
 

package/package.json

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

package/src/commands/migrate.ts

@@ -6,6 +6,7 @@ import { applyRecordsMove, applyRename, readSources } from '@/migrate/apply'
 import { isToolkitOwned, planRename, type RenamePlan } from '@/migrate/plan'
 import {
   ignoresDestination,
+  isRecordArtifact,
   planRecordsMove,
   type RecordsPlan,
 } from '@/migrate/records'
@@ -176,17 +177,24 @@ async function runRecords(opts: RecordsOptions): Promise<number> {
     return 1
   }
 
-  const plan = planRecordsMove(root, await readSources(root, files))
+  // Filtered before the read rather than inside the planner, because the
+  // records are the largest thing in the tree and `readSources` awaits one file
+  // at a time. This repository's own record tree is 9,744 files at 83M, and the
+  // backup history under it is object files read whole and discarded as binary.
+  const toSweep = files.filter((path) => !isRecordArtifact(path))
+  const records = files.length - toSweep.length
+
+  const plan = planRecordsMove(root, await readSources(root, toSweep))
 
   // stdout, so the record pipes clean. `pipeOutput` frames to stderr, which is
   // where this command's report belongs and where a JSON record does not.
   if (opts.json) {
     process.stdout.write(
-      `${JSON.stringify(toRecordsRecord(plan, opts.write))}\n`,
+      `${JSON.stringify(toRecordsRecord(plan, records, opts.write))}\n`,
     )
   }
 
-  reportRecords(plan)
+  reportRecords(plan, records)
 
   if (plan.collisions.length > 0) {
     logError(
@@ -229,7 +237,7 @@ function readGitignore(root: string): string | undefined {
   }
 }
 
-function reportRecords(plan: RecordsPlan): void {
+function reportRecords(plan: RecordsPlan, records: number): void {
   logInfo(`${plural(plan.moves.length, 'folder')} to move.`)
   for (const move of plan.moves) logInfo(`  ${move.from} -> ${move.to}`)
   logInfo(
@@ -237,6 +245,14 @@ function reportRecords(plan: RecordsPlan): void {
   )
   logInfo(`${plural(plan.kept, 'citation')} marked to keep the old root.`)
 
+  // A count rather than a list, and its own line rather than a place in
+  // `excluded`. That field exists so a reader can go and check a handful by
+  // hand, and a record tree would bury them. The count is what answers the
+  // question a target actually has, which is where the rest of the files went.
+  if (records > 0) {
+    logInfo(`${plural(records, 'file')} under a record root, left alone.`)
+  }
+
   if (plan.excluded.length > 0) {
     logInfo(`${plural(plan.excluded.length, 'file')} excluded from the sweep.`)
   }
@@ -244,6 +260,7 @@ function reportRecords(plan: RecordsPlan): void {
 
 function toRecordsRecord(
   plan: RecordsPlan,
+  records: number,
   wrote: boolean | undefined,
 ): unknown {
   return {
@@ -255,6 +272,7 @@ function toRecordsRecord(
     rewritten: plan.rewritten,
     kept: plan.kept,
     excluded: plan.excluded.length,
+    records,
     paths: plan.entries.map((entry) => ({
       path: entry.path,
       rewritten: entry.rewritten,
@@ -294,6 +312,11 @@ export function register(program: Command): void {
         'A line carrying canon-keep-record-root, or the line below it, keeps the',
         'old root. Prose that dates a decision needs it; a live path does not.',
         '',
+        'The records themselves are never swept. Everything under .canon/ and',
+        'every .claude/ record folder is left alone and reported as a count, so',
+        'a run after the ignore entries collapse touches the same files as one',
+        'before it.',
+        '',
         'Examples:',
         '  canon migrate records',
         '  canon migrate records --write',

package/src/migrate/records.ts

@@ -10,7 +10,12 @@
 
 import { existsSync } from 'node:fs'
 import { join } from 'node:path'
-import { type RecordRoot, RECORD_ENTRIES, spell } from '@/record-root'
+import {
+  type RecordRoot,
+  RECORD_ENTRIES,
+  RECORD_ROOTS,
+  spell,
+} from '@/record-root'
 
 /** The root the entries below leave, exported so the writer can prune it. */
 export const FROM_ROOT: RecordRoot = '.claude'
@@ -104,6 +109,66 @@ export function isExcludedPath(path: string): boolean {
   return EXCLUDED_SUFFIXES.some((suffix) => path.endsWith(suffix))
 }
 
+/**
+ * The roots holding nothing but records, so a path under one is a record
+ * whatever it is named.
+ *
+ * `.canon/` qualifies by construction. `.claude/ARCHITECTURE.md` fixes the rule
+ * that every gitignored session record moves there and nothing tracked ever
+ * lands there, which covers a record folder `RECORD_ENTRIES` has yet to learn
+ * about. The old root is the one that cannot take a whole-root reading, and it
+ * is derived by exclusion rather than named, so a third root added later reads
+ * as records-only unless someone says otherwise.
+ */
+const RECORD_ONLY_ROOTS: readonly RecordRoot[] = RECORD_ROOTS.filter(
+  (root) => root !== FROM_ROOT,
+)
+
+/**
+ * Every prefix under which a path is a record rather than a file to sweep.
+ *
+ * The asymmetry is the point. A whole-root prefix is correct for the new root
+ * and wrong for the old one, which is mixed: this repository tracks 163 files
+ * under `.claude/`, and a target's installed `.claude/rules/core/035-tasks.md`
+ * is the file the sweep exists to repoint, so a bare `.claude/` prefix strands
+ * it silently. The old root is therefore entry-scoped, through `spell` so the
+ * one naming variant stays decided in `record-root.ts`.
+ *
+ * Joined with a literal separator rather than through `join`, the way
+ * `EXCLUDED_PREFIXES` already is. These are matched against what `git ls-files`
+ * returns, which is forward-slashed on every platform, where `join` would spell
+ * a backslash on Windows and match nothing.
+ */
+const RECORD_PREFIXES: readonly string[] = [
+  ...RECORD_ONLY_ROOTS,
+  ...RECORD_ENTRIES.map((entry) => `${FROM_ROOT}/${spell(FROM_ROOT, entry)}`),
+]
+
+/**
+ * Whether a path is a record artifact, which the sweep passes over entirely.
+ *
+ * Separate from `isExcludedPath`, which reports what it skips because a reader
+ * has to check those by hand. A record artifact is never something to check,
+ * and a target's record tree is large enough that reporting each one would bury
+ * the handful of exclusions that matter.
+ *
+ * A record folder becomes visible to the sweep at the moment `canon tooling
+ * sync claude` prunes the twelve old ignore entries down to one `.canon/` line,
+ * which is the step the documented first-run order puts immediately before this
+ * verb. Without this predicate the run that follows reads the memory pen and
+ * the groundwork trails as source and rewrites them.
+ *
+ * The three retired flat archives stay outside this, the way `CITATION` already
+ * leaves them alone: `.claude/plans-archive/x.md` does not start with
+ * `.claude/plans/`, and widening the entry list to catch it would change what
+ * `MOVED_ENTRIES` means for the folder half of the verb.
+ */
+export function isRecordArtifact(path: string): boolean {
+  return RECORD_PREFIXES.some(
+    (prefix) => path === prefix || path.startsWith(`${prefix}/`),
+  )
+}
+
 /**
  * Marks a line naming the old root on purpose.
  *
@@ -244,6 +309,11 @@ export function planRecordsMove(
   let kept = 0
 
   for (const source of sources) {
+    // Silently, and ahead of the exclusion test. The command boundary filters
+    // these out before it reads them, so this is what keeps the pure function
+    // correct under a direct call rather than what the verb relies on.
+    if (isRecordArtifact(source.path)) continue
+
     if (isExcludedPath(source.path)) {
       // Only an excluded file that actually carries a citation is reported. The
       // predicate covers every test file in the tree, so counting them all would