@erclx/canon 4.6.1 → 4.7.0

package/src/migrate/apply.ts

@@ -1,8 +1,9 @@
 import { $ } from 'bun'
-import { readFile, mkdir, rmdir, writeFile } from 'node:fs/promises'
+import { readFile, mkdir, rename, rmdir, writeFile } from 'node:fs/promises'
 import { dirname, join, relative } from 'node:path'
 import { gitEnv } from '@/git-env'
 import type { RenamePlan, RenameSource } from '@/migrate/plan'
+import { FROM_ROOT as OLD_ROOT, type RecordsPlan } from '@/migrate/records'
 
 /**
  * A file whose bytes carry a NUL is read as binary and its content is left
@@ -33,6 +34,71 @@ export interface ApplyResult {
   readonly failed: readonly string[]
 }
 
+/**
+ * Writes the records move: the citations first, then the folders.
+ *
+ * The order is the reverse of `applyRename`'s reasoning and lands in the same
+ * place. Every folder here is untracked, so a failed move leaves the records
+ * where they were and the rewritten citations point at a root nothing has
+ * reached yet, which reads as pending. Moving first and failing the rewrite
+ * strands the records at a root nothing points at, which reads as lost.
+ *
+ * A plain rename rather than `git mv`, since none of these paths is tracked and
+ * git has no history to carry. The destination root is created once; a rename
+ * across filesystems is not handled, because both paths sit inside one project.
+ *
+ * The folder loop stops on the first failure rather than carrying on. Each move
+ * that lands makes the tree more split, and a split tree is what `pushRecords`
+ * refuses on, so continuing turns one unmovable folder into a longer list of
+ * folders to put back by hand. Stopping does not undo what already moved,
+ * which is why the refusal on the push side exists as well.
+ */
+export async function applyRecordsMove(
+  root: string,
+  plan: RecordsPlan,
+): Promise<ApplyResult> {
+  let written = 0
+  let moved = 0
+  const failed: string[] = []
+
+  for (const entry of plan.entries) {
+    // A rejected write leaves the tree half-rewritten with nothing said, since
+    // this runs inside a commander action that would unwind past the report.
+    // Reads still resolve through the root fallback, so the recorded failure is
+    // what a caller needs rather than a stop.
+    const done = await writeFile(join(root, 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(join(root, move.to)), { recursive: true })
+    const done = await rename(join(root, move.from), join(root, move.to))
+      .then(() => true)
+      .catch(() => false)
+
+    if (!done) {
+      failed.push(move.from)
+      break
+    }
+
+    moved += 1
+  }
+
+  // The old root survives the moves as an empty directory when it held records
+  // and nothing else. `rmdir` refuses a directory that still holds anything, so
+  // a project keeping its rules, skills, and settings there is untouched and the
+  // refusal is ignored rather than reported.
+  if (moved > 0) {
+    await rmdir(join(root, OLD_ROOT)).catch(() => undefined)
+  }
+
+  return { written, moved, failed }
+}
+
 /**
  * Writes the plan. Content lands first and the move follows, so a failed move
  * leaves the rewrite on a path that still exists rather than stranding content

package/src/migrate/records.ts

@@ -0,0 +1,276 @@
+/**
+ * The move of the gitignored session records from `.claude/` to `.canon/`.
+ *
+ * Two halves that share one list. The folders themselves are untracked, so
+ * relocating them is a filesystem act no commit records, while every tracked
+ * file naming one of their paths is a citation that goes stale the moment they
+ * land. Running one half without the other leaves a tree whose records are at a
+ * root nothing points at, which is why the same verb performs both.
+ */
+
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { type RecordRoot, RECORD_ENTRIES, spell } from '@/record-root'
+
+/** The root the entries below leave, exported so the writer can prune it. */
+export const FROM_ROOT: RecordRoot = '.claude'
+
+/** The root they arrive at. */
+const TO_ROOT: RecordRoot = '.canon'
+
+/**
+ * Every entry the move relocates, at the name `.claude/` gave it.
+ *
+ * The list is `RECORD_ENTRIES`, which `record-root.ts` owns because a seed
+ * destination and a superseded-layout report ask the same question. Restating
+ * it here would let the sweep and the resolver disagree about what moved.
+ */
+export const MOVED_ENTRIES = RECORD_ENTRIES
+
+/** Where an entry sits before the move, relative to the project root. */
+export function sourcePath(entry: string): string {
+  return join(FROM_ROOT, entry)
+}
+
+/** Where it sits after, which is the only place the scratch folder is renamed. */
+export function destinationPath(entry: string): string {
+  return join(TO_ROOT, spell(TO_ROOT, entry))
+}
+
+/**
+ * A citation into a moved entry.
+ *
+ * The tail rejects a following name character rather than asking for a word
+ * boundary, and that is what protects the three retired flat archives without
+ * an exception list: `.claude/plans-archive` continues into a `-` and never
+ * matches, where `.claude/plans/` and a bare `.claude/plans` both do. A
+ * boundary would treat the hyphen as a break and rewrite the archive to a root
+ * it never sat under.
+ *
+ * The alternation is ordered longest first so `README.md` is decided before any
+ * shorter entry can claim its prefix, and each entry is escaped because two of
+ * them carry a dot.
+ */
+const CITATION = new RegExp(
+  `${escape(FROM_ROOT)}/(${[...MOVED_ENTRIES]
+    .sort((left, right) => right.length - left.length)
+    .map(escape)
+    .join('|')})(?![A-Za-z0-9._-])`,
+  'g',
+)
+
+function escape(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+/**
+ * Files whose content is left alone entirely.
+ *
+ * The changelog is release history, whose entries record what shipped while the
+ * records were still under the old root. An eval result is a transcript of the
+ * paths a session actually opened. Rewriting either makes it testify to
+ * something that never happened.
+ *
+ * This module and `src/record-root.ts` are the two sources that state the old
+ * root on purpose. Sweeping them turns every citation this expression is built
+ * from into its own replacement, leaving a rewriter that maps `.canon/` to
+ * `.canon/` and matches nothing.
+ *
+ * A test file is excluded because the fixtures that prove the old root still
+ * resolves have to keep building it. Rewriting one is worse than a failing
+ * test: the old-root case collapses into a copy of the new-root case beside it
+ * and keeps passing, reporting coverage for a fallback nothing exercises.
+ *
+ * A hook is the third source that states both roots on purpose. Each one guards
+ * on a `case` carrying an arm per root, so rewriting the old arm collapses the
+ * pair into two copies of the new one and shellcheck reports a pattern that can
+ * never match. The guard then stops firing in a project the move has not
+ * reached, which is silent: the index goes stale while every save succeeds.
+ */
+const EXCLUDED_PREFIXES: readonly string[] = [
+  'src/migrate/',
+  'scripts/eval/result-',
+  '.claude/hooks/',
+  'tooling/claude/seeds/.claude/hooks/',
+]
+
+const EXCLUDED_PATHS: readonly string[] = ['CHANGELOG.md', 'src/record-root.ts']
+
+const EXCLUDED_SUFFIXES: readonly string[] = ['.test.ts']
+
+export function isExcludedPath(path: string): boolean {
+  if (EXCLUDED_PATHS.includes(path)) return true
+  if (EXCLUDED_PREFIXES.some((prefix) => path.startsWith(prefix))) return true
+  return EXCLUDED_SUFFIXES.some((suffix) => path.endsWith(suffix))
+}
+
+/**
+ * Marks a line naming the old root on purpose.
+ *
+ * Prose that dates a decision, records where a defect landed, or names the
+ * fallback a target still resolves through all have to keep saying `.claude/`,
+ * and a sweep cannot tell those from a live path. The marker sits on the line
+ * itself or on the one above it, which is the placement `canon-keep-retired`
+ * and `canon-allow-superseded` already use here.
+ */
+const KEEP_MARKER = 'canon-keep-record-root'
+
+function isKept(lines: readonly string[], index: number): boolean {
+  if (lines[index]?.includes(KEEP_MARKER)) return true
+  return index > 0 && (lines[index - 1]?.includes(KEEP_MARKER) ?? false)
+}
+
+/** Rewrites every unmarked citation into a moved entry. */
+export function rewriteText(text: string): string {
+  const lines = text.split('\n')
+
+  return lines
+    .map((line, index) =>
+      isKept(lines, index)
+        ? line
+        : line.replace(CITATION, (_match, entry: string) =>
+            destinationPath(entry),
+          ),
+    )
+    .join('\n')
+}
+
+/**
+ * How many citations `rewriteText` would rewrite, and how many marked lines it
+ * left alone. The second number is what says the markers fired at all, which a
+ * diff cannot show because a protected line does not appear in one.
+ */
+export function scanText(text: string): {
+  readonly rewritten: number
+  readonly kept: number
+} {
+  const lines = text.split('\n')
+  let rewritten = 0
+  let kept = 0
+
+  for (const [index, line] of lines.entries()) {
+    const matches = [...line.matchAll(CITATION)].length
+    if (matches === 0) continue
+
+    if (isKept(lines, index)) kept += matches
+    else rewritten += matches
+  }
+
+  return { rewritten, kept }
+}
+
+export interface FolderMove {
+  readonly from: string
+  readonly to: string
+}
+
+/**
+ * The entries actually on disk under the old root, with where each lands.
+ *
+ * An entry already present at the destination is reported as a collision by the
+ * caller rather than filtered out here, since merging two record folders is a
+ * judgment no verb should take on a memory pen.
+ */
+export function planFolderMoves(root: string): FolderMove[] {
+  return MOVED_ENTRIES.filter((entry) =>
+    existsSync(join(root, sourcePath(entry))),
+  ).map((entry) => ({ from: sourcePath(entry), to: destinationPath(entry) }))
+}
+
+/** Moves whose destination is already taken, which the verb refuses on. */
+export function collisions(
+  root: string,
+  moves: readonly FolderMove[],
+): string[] {
+  return moves
+    .filter((move) => existsSync(join(root, move.to)))
+    .map((move) => move.to)
+}
+
+/**
+ * Whether a project's ignore rules already cover the new root.
+ *
+ * The gate exists because every entry being moved is ignored where it stands.
+ * Landing them under a root the project does not ignore publishes the memory
+ * pen and the groundwork trails into the next commit, which is the same harm
+ * the records remote gate refuses for the same payload. Reading the file rather
+ * than asking git keeps the answer available in a project with no commits yet.
+ */
+export function ignoresDestination(gitignore: string): boolean {
+  return gitignore
+    .split('\n')
+    .map((line) => line.trim())
+    .some((line) => line === TO_ROOT || line === `${TO_ROOT}/`)
+}
+
+/** One tracked file, as the planner reads it. */
+export interface RecordsSource {
+  readonly path: string
+  readonly text: string
+}
+
+/** One file whose citations move, carried with the text to write back. */
+export interface CitationEntry {
+  readonly path: string
+  readonly text: string
+  readonly rewritten: number
+  readonly kept: number
+}
+
+export interface RecordsPlan {
+  readonly moves: readonly FolderMove[]
+  readonly collisions: readonly string[]
+  readonly entries: readonly CitationEntry[]
+  readonly excluded: readonly string[]
+  readonly rewritten: number
+  readonly kept: number
+}
+
+/**
+ * What the move would do, without doing it.
+ *
+ * The folder half reads disk and the citation half is pure over the sources it
+ * is handed, so a caller can report the whole plan and apply it from the same
+ * value. A file whose text does not change is dropped rather than carried as a
+ * no-op, which keeps the reported file count equal to what the sweep writes.
+ */
+export function planRecordsMove(
+  root: string,
+  sources: readonly RecordsSource[],
+): RecordsPlan {
+  const moves = planFolderMoves(root)
+  const entries: CitationEntry[] = []
+  const excluded: string[] = []
+  let kept = 0
+
+  for (const source of sources) {
+    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
+      // report hundreds of exclusions the sweep was never going to touch and
+      // bury the handful a reader has to go and check by hand.
+      if (scanText(source.text).rewritten > 0) excluded.push(source.path)
+      continue
+    }
+
+    const counts = scanText(source.text)
+    kept += counts.kept
+    if (counts.rewritten === 0) continue
+
+    entries.push({
+      path: source.path,
+      text: rewriteText(source.text),
+      rewritten: counts.rewritten,
+      kept: counts.kept,
+    })
+  }
+
+  return {
+    moves,
+    collisions: collisions(root, moves),
+    entries,
+    excluded,
+    rewritten: entries.reduce((sum, entry) => sum + entry.rewritten, 0),
+    kept,
+  }
+}

package/src/paths.ts

@@ -3,7 +3,7 @@ import { sep } from 'node:path'
 /**
  * Whether a resolved path is the directory itself or sits inside it. The
  * separator guard is the whole of it: a bare prefix test reads
- * `.claude/plans-archive` as living under `.claude/plans`, which is a sibling
+ * `.claude/plans-archive` as living under `.canon/plans`, which is a sibling
  * rather than a child and is exactly the pair the plan folders spell.
  *
  * It lives at the root rather than beside either caller because both resolve

package/src/pr/paths.ts

@@ -66,7 +66,7 @@ const LINE_SUFFIX = /:\d+(?:-\d+)?$/
  * Whitespace separates a backticked command from a backticked path, and it is
  * the whole answer to one of the four observed false-positive classes:
  * `canon markdown audit .claude/rules --json` carries a slash and names no file.
- * Angle brackets answer a second, since `.claude/plans/feature-<slug>.md`
+ * Angle brackets answer a second, since `.canon/plans/feature-<slug>.md`
  * describes a shape rather than naming a file. A glob and a caret describe a
  * shape too, `^src/` being a grep pattern one body spelled in Key Changes, and
  * a leading anchor names something outside this repository.

package/src/record-root.ts

@@ -5,44 +5,86 @@ import { join } from 'node:path'
  * The roots a session record folder is read at, in precedence order.
  *
  * `.canon/` wins because a tree that carries it has been migrated, and reading
- * `.claude/` there would answer from the copy the move left behind. A tree that
- * carries neither is every tree today, which is what keeps this branch a no-op
- * until the move lands.
+ * `.claude/` there would answer from the copy the move left behind. The second
+ * spelling is what an unmigrated project still resolves through, so it stays
+ * until no target reaches one, which nothing measures.
  *
  * The shape is `readStamp`'s: order the spellings, take the first that exists,
  * and stand the creation default in when none does.
  */
+// canon-keep-record-root
 export const RECORD_ROOTS = ['.canon', '.claude'] as const
 
 export type RecordRoot = (typeof RECORD_ROOTS)[number]
 
 /**
- * The root a record folder is created at.
+ * The root a record folder is created at when no root carries it yet.
  *
- * It disagrees with the read precedence above on purpose, and the disagreement
- * is the whole of this branch. Creating under `.canon/` before the move would
- * write records to a root whose ignore line may not have reached a target yet,
- * and it would split one project's records across two roots with no verb able
- * to reconcile them. The move flips this line and nothing else.
+ * It agrees with the head of the read precedence, which is what the move
+ * changed. While the two disagreed, creation stayed at `.claude/` so a record
+ * could not land under a root whose ignore line had yet to reach the project.
+ * The ignore line ships now, so a fresh project scaffolds one root and an
+ * unmigrated one keeps resolving its own through the fallback above.
  */
-export const CREATION_ROOT: RecordRoot = '.claude'
+export const CREATION_ROOT: RecordRoot = '.canon'
 
 /**
  * The deletable scratch folder, named at the spelling `.claude/` gives it.
  *
- * It is the one folder whose name differs by root. Inside a dotted root the
- * leading dot hides nothing already hidden and costs a bare `ls` that omits the
- * folder, so the move drops it. Every other record folder keeps its name,
- * `.records.git` included, where the dot marks the mechanism apart from a
- * payload rather than hiding it.
+ * It is the one folder whose name differs by root, and callers name it at the
+ * old spelling because `spell` is the only place the variant is decided. Inside
+ * a dotted root the leading dot hides nothing already hidden and costs a bare
+ * `ls` that omits the folder, so the move dropped it. Every other record folder
+ * keeps its name, `.records.git` included, where the dot marks the mechanism
+ * apart from a payload rather than hiding it.
  */
 export const SCRATCH = '.tmp'
 
 /** The scratch folder's name under `.canon/`. */
 const CANON_SCRATCH = 'tmp'
 
-/** How a root spells a folder name. Only the scratch folder differs. */
-function spell(root: RecordRoot, folder: string): string {
+/**
+ * Every entry that lives under the record root, at the name `.claude/` gave it.
+ *
+ * These are the twelve ignore patterns the move to `.canon/` collapsed into one,
+ * so the list counts entries rather than record folders: `.records.git` is the
+ * backup history rather than a record, and `README.md` is a file a records pull
+ * writes back. `worktrees` is absent because the harness creates a worktree
+ * under `.claude/` and requires its target to sit there.
+ *
+ * Everything absent from this list is committed and stays where it is, which is
+ * the rule the move ran on. `context`, `rules`, `skills`, `hooks`, `wireframes`,
+ * and the loose documents at the root are all in that set, which is why a seed
+ * and a superseded-layout report each ask this rather than assuming a root.
+ */
+export const RECORD_ENTRIES: readonly string[] = [
+  '.records.git',
+  SCRATCH,
+  'README.md',
+  'diagrams',
+  'groundwork',
+  'intake',
+  'memory',
+  'plans',
+  'proposals',
+  'review',
+  'tasks',
+  'teach',
+]
+
+/** Whether a name under `.claude/` is one the record root owns. */
+export function isRecordEntry(name: string): boolean {
+  return RECORD_ENTRIES.includes(name)
+}
+
+/**
+ * How a root spells a folder name. Only the scratch folder differs.
+ *
+ * Exported because the migration verb has to name a folder's destination and
+ * deriving it there would state the one naming variant in a second place, where
+ * a tree half-moved by one rule and read by the other resolves nothing.
+ */
+export function spell(root: RecordRoot, folder: string): string {
   return root === '.canon' && folder === SCRATCH ? CANON_SCRATCH : folder
 }
 
@@ -98,21 +140,29 @@ export function recordDirs(
   )
 }
 
-/** Where a record folder is created, which is the creation default always. */
-export function creationDir(
+/**
+ * The creation destination relative to the project root, which is the form a
+ * message displays and an option default carries.
+ *
+ * It resolves the root the same way a read does rather than pinning the
+ * creation default, because the two stopped disagreeing when the move flipped
+ * `CREATION_ROOT`. Pinning it now would write a new record to `.canon/` in a
+ * project whose board is still `.claude/`, which splits one project's records
+ * across two roots and leaves every reader answering from the half the writer
+ * did not use.
+ *
+ * The root is a parameter rather than the working directory, because two of the
+ * callers spell a path they later join onto a target root. Resolving against
+ * the working directory there would read one project to answer about another.
+ */
+export function creationRel(
   root: string,
   folder: string,
   ...rest: string[]
 ): string {
-  return join(root, CREATION_ROOT, spell(CREATION_ROOT, folder), ...rest)
-}
+  const at = rootOf(root, folder)
 
-/**
- * The creation destination relative to the project root, which is the form a
- * message displays and an option default carries.
- */
-export function creationRel(folder: string, ...rest: string[]): string {
-  return join(CREATION_ROOT, spell(CREATION_ROOT, folder), ...rest)
+  return join(at, spell(at, folder), ...rest)
 }
 
 /**

package/src/records/backup.ts

@@ -2,28 +2,29 @@ import { existsSync } from 'node:fs'
 import { join, relative, resolve } from 'node:path'
 import { $ } from 'bun'
 import { gitEnv } from '@/git-env'
-import { recordRoot } from '@/record-root'
+import { RECORD_ROOTS, recordRoot } from '@/record-root'
 
 /**
  * The folders a backup carries, relative to the record root `workTree` resolves
- * rather than to `.claude/` specifically, since the same nine names sit under
- * whichever root a tree holds. Most of them are the `# Claude` group the claude
- * manifest ships, minus three: the scratch folder, which is defined as deletable
- * without loss, `worktrees/`, whose contents belong to the enclosing repository
- * already, and `.records.git/`, which is the history the rest are pushed into.
- * The list is spelled out rather than read off that group so adding an ignore
- * entry cannot silently enlarge the payload.
+ * rather than to either root specifically, since the same nine names sit under
+ * whichever one a tree holds.
  *
- * `diagrams` is the one name the manifest group does not carry, so a target
- * tracks it where this repository ignores it. That is the second reason to
- * spell the list out: the manifest bounds it rather than producing it, and no
- * count taken off that group matches this one. `scripts/core/check-ignore-parity.sh`
- * compares the two lists and holds the reason `diagrams` stays apart, so the
- * one difference is enforced rather than assumed.
+ * Nothing bounds this list any more, and the move is what took the bound away.
+ * The claude manifest used to ship a folder apiece, so the `# Claude` group
+ * named a superset this could be read against; it ships one `.canon/` root
+ * entry now and names no folder at all. Spelling the list out is therefore the
+ * whole of the protection rather than half of it, since a record folder added
+ * under `.canon/` is ignored the moment it exists and enters no payload until
+ * a name is written here.
  *
- * The manifest group is the one this reads rather than the enclosing
- * repository's own `.gitignore`, which spreads the same entries across two
- * headers and carries `.claude/README.md` that no target receives.
+ * Three counts describe this surface and each is right about a different
+ * question, so they are stated apart rather than reconciled. Nine is what a
+ * disk loss would take, which is this list. Eleven is what sat under `.claude/`
+ * as an ignored folder before the move, which adds the scratch folder that is
+ * deletable without loss and `worktrees/`, whose contents belong to the
+ * enclosing repository already. Twelve is what the move relocated, which counts
+ * ignore entries rather than folders: the eleven less `worktrees/`, which stayed,
+ * plus `.records.git/` and the `README.md` a records pull writes back.
  *
  * Each entry is a top-level record folder and every archive sits inside the one
  * it archives, so the three former archive entries are covered by their parents
@@ -103,6 +104,7 @@ const COMMIT_IDENTITY = [
 ]
 
 export const BACKUP_REFUSALS = [
+  'split-roots',
   'no-repository',
   'no-remote',
   'remote-unreadable',
@@ -297,6 +299,52 @@ async function resolveRemote(root: string): Promise<string | BackupRefused> {
   return url
 }
 
+/**
+ * Backed folders sitting at a record root other than the one `workTree` chose.
+ *
+ * A half-migrated tree is the case this reads. `recordRoot` answers for the
+ * whole tree on the first root that exists, so one folder left behind by a move
+ * that failed partway is absent from the work tree while the records index
+ * still names it. `scopedFolders` puts it in the pathspec on the index side,
+ * `add -A` stages its deletion, and the push drops it from the remote, which is
+ * the harm `RETIRED_FOLDERS` documents reached by a different route.
+ *
+ * Both verbs refuse on it rather than only `push`. A `pull` resets the resolved
+ * work tree hard and leaves the stranded copy beside it, which is not a loss but
+ * is a tree where two roots disagree and neither is wrong.
+ *
+ * Only `BACKED_FOLDERS` is read. The scratch folder is deletable by definition
+ * and `worktrees/` belongs to the enclosing repository, so neither stranded
+ * anywhere costs a record.
+ */
+function strandedFolders(root: string): string[] {
+  const resolved = resolve(workTree(root))
+
+  return RECORD_ROOTS.flatMap((candidate) => {
+    const dir = join(root, candidate)
+    if (resolve(dir) === resolved) return []
+
+    return BACKED_FOLDERS.filter((folder) => existsSync(join(dir, folder))).map(
+      (folder) => join(candidate, folder),
+    )
+  })
+}
+
+/** Refuses a tree whose records sit under both roots, naming what to move. */
+function refuseSplitRoots(root: string): BackupRefused | undefined {
+  const stranded = strandedFolders(root)
+  if (stranded.length === 0) return undefined
+
+  return refuse(
+    'split-roots',
+    [
+      `Records sit under both roots, so ${relative(root, workTree(root))} is not the whole set and a push would stage the rest as deleted:`,
+      ...stranded.map((path) => `  ${path}`),
+      'Finish the move with canon migrate records --write, or put these back beside the others by hand.',
+    ].join('\n'),
+  )
+}
+
 /**
  * The subset of the backed and retired names a pathspec can name: on disk, or
  * already in the records index.
@@ -345,6 +393,9 @@ function countLines(text: string): number {
  * that commit on one disk, which is the state the whole verb exists to end.
  */
 export async function pushRecords(root: string): Promise<PushOutcome> {
+  const split = refuseSplitRoots(root)
+  if (split) return split
+
   const remote = await resolveRemote(root)
   if (typeof remote !== 'string') return remote
 
@@ -406,6 +457,9 @@ export async function pushRecords(root: string): Promise<PushOutcome> {
  * resolves by pushing first or by moving the local folders aside.
  */
 export async function pullRecords(root: string): Promise<PullOutcome> {
+  const split = refuseSplitRoots(root)
+  if (split) return split
+
   const remote = await resolveRemote(root)
   if (typeof remote !== 'string') return remote
 

package/src/records/validate.ts

@@ -977,7 +977,7 @@ export function governedPaths(statement: string): string[] {
 /**
  * The words a governed path offers a filename. Each segment gives its own word
  * and, where it carries a prefix or a placeholder, the parts either side of a
- * hyphen, so `.claude/tasks/session-<slug>.md` offers `tasks` and `session`.
+ * hyphen, so `.canon/tasks/session-<slug>.md` offers `tasks` and `session`.
  *
  * A dotted segment gives nothing. It names the folder holding the artifact
  * rather than the artifact, and a standard named for it would pass this check