@erclx/canon 4.6.1 → 4.8.0

package/src/gov/restated.ts

@@ -43,7 +43,7 @@ const MIRRORS: readonly (readonly [string, string])[] = [
  *
  * Under one percent of the 2750 statements this repository offers. Tuned
  * against that corpus rather than reasoned to, which is what the plan asked of
- * the first run: `.claude/plans/` sits at 14 and is the anchor the motivating
+ * the first run: `.canon/plans/` sits at 14 and is the anchor the motivating
  * case turns on, while `file` sits at 371 and matches most of the tree.
  */
 export const COMMON_CEILING = 20
@@ -55,7 +55,7 @@ export const ANCHOR_FLOOR = 3
  * What a backticked token is worth against a plain word.
  *
  * An author marking a span as code named an identifier rather than describing
- * one, so `.claude/plans/archive/` says more about what a statement governs
+ * one, so `.canon/plans/archive/` says more about what a statement governs
  * than any two prose words do. Weighting it is what lets the floor rise high
  * enough to drop a coincidental word pair without losing a rule two surfaces
  * spelled entirely differently around one shared path.
@@ -267,7 +267,7 @@ interface Indexed<T extends Statement> {
 /**
  * Splits text into the tokens an anchor can be drawn from.
  *
- * A code span keeps its inner text whole, since `.claude/plans/archive/` is the
+ * A code span keeps its inner text whole, since `.canon/plans/archive/` is the
  * strongest anchor this corpus offers and splitting it on the punctuation would
  * leave three words every second bullet also carries.
  */

package/src/inventory/walk.ts

@@ -15,9 +15,9 @@ import type { Subject } from '@/inventory/subjects'
  * and `src/commands/inventory.ts` reaches it through a dynamic import so no
  * other command resolves the engine at startup.
  *
- * Like `@/demo/drive` and unlike `@/capture/render`, this module ships, because
- * a command whose whole purpose is running inside someone else's project cannot
- * stay toolkit-only.
+ * Like `@/demo/drive`, `@/driver/drive`, and `@/capture/render`, this module
+ * ships, because a command whose whole purpose is running inside someone else's
+ * project cannot stay toolkit-only.
  */
 
 /**

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)
 }
 
 /**