@erclx/canon 4.4.0 → 4.5.0

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

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

package/claude/skills/claude-markdown-propose/REQUIREMENT.md

@@ -23,7 +23,6 @@ A second failure compounds the first. A claim copied across several files is cor
 - Carry three labelled variants on a change whose replacement was invented, and one on a change that corrects text to a recorded fact
 - Write one proposal file per source file under `.claude/proposals/<slug>/` and stop, leaving `You:` empty on every change
 - Apply only a change carrying an answer, one file at a time, and re-grep its anchor before applying it
-- Name a folder that does not collide with `.claude/audits/`, which holds generated data rather than decision state
 - Report what each file leaves alone, so a proposal cannot be read as finding everything wanting
 
 ## Must not

package/docs/agents/audits.md

@@ -14,11 +14,11 @@ canon audits run --record
 canon audits list --json
 ```
 
-| Option          | Behavior                                                          |
-| --------------- | ----------------------------------------------------------------- |
-| `--json`        | Add a machine-readable record on stdout, keeping the frame        |
-| `--root <path>` | Measure this tree instead of the current worktree                 |
-| `--record`      | Write this run's tracked counts to `.claude/audits/baseline.json` |
+| Option          | Behavior                                                         |
+| --------------- | ---------------------------------------------------------------- |
+| `--json`        | Add a machine-readable record on stdout, keeping the frame       |
+| `--root <path>` | Measure this tree instead of the current worktree                |
+| `--record`      | Write this run's tracked counts to `.claude/canon/baseline.json` |
 
 ## What it runs
 
@@ -73,7 +73,7 @@ Every run states how many corpora it measured against how many it skipped, inclu
 
 ## The retained baseline
 
-`.claude/audits/baseline.json` holds the counts from the last run recorded with `--record`, alongside the day it was taken and the commit it was read at. Each later run reports which counts moved and by how much.
+`.claude/canon/baseline.json` holds the counts from the last run recorded with `--record`, alongside the day it was taken and the commit it was read at. Each later run reports which counts moved and by how much.
 
 The file is committed. A per-machine record cannot answer the question this half exists for, which is whether a number grew since anyone last looked, and a fresh checkout has to inherit that answer rather than start over. The cost is that a branch moving a count either fixes it or re-records it and says why, which is the shape the consumed-copy assertion already carries.
 

package/docs/agents/context-audit.md

@@ -31,7 +31,7 @@ canon context audit tooling/base/seeds --gate
 
 Scope defaults to `context`, `diagrams`, and `wireframes`, and a folder the project does not carry is skipped rather than reported. A domain that outgrew one file and split into `<domain>/` is audited as its own folder, so a split entry measures at the same grain as a flat one.
 
-A name passed to `--folder` resolves under `.claude/` first and at the project root second, which is what puts `docs/` and any later corpus in reach of the same engine. The root base is reached only by a name the caller passes, so the default list still resolves under `.claude/` alone and a project holding a root `wireframes/` is not audited against a standard it never adopted. The scope line prints the resolved path, so a project carrying both spellings reads which one was taken. The JSON record carries the base per folder as `folders[].base`.
+A name passed to `--folder` resolves under the record roots first, `.canon/` ahead of `.claude/`, and at the project root last, which is what puts `docs/` and any later corpus in reach of the same engine. The root base is reached only by a name the caller passes, so the default list still resolves under a record root alone and a project holding a root `wireframes/` is not audited against a standard it never adopted. `diagrams` is the one default name that is a session record and moves with them, which is why both record roots are in the list rather than one, and `docs/agents/records.md` states the read order every verb shares. The scope line prints the resolved path, so a project carrying both spellings reads which one was taken. The JSON record carries the base per folder as `folders[].base`.
 
 A run where no requested name resolves refuses, whichever list it read. Naming the absent ones narrows to `--folder`, since a project carrying one of the three default folders is the ordinary case and a name it never asked for is not a typo. The JSON record carries those names as `unresolvedFolders`.
 
@@ -80,4 +80,4 @@ Append `<!-- audit-ignore-citations: <path> -->` to the source line in either ca
 
 The marker itself stays out of anything that installs. A seed, a plugin skill body, and a stack reference all reach a target, so a marker there lands as toolkit bookkeeping in someone else's tree. Reword those lines to drop the path instead, and where a stop message has to spell it, move that message into a fenced block, which this check already skips.
 
-The pattern spells the `.claude/` prefix, so a folder resolved at the project root is measured by every other check and contributes nothing here. Widening it to a bare `docs/x.md` would match prose that references nothing, which is a separate decision from where entries come from. A run whose folders all resolved at the root says the check is out of scope rather than reporting that zero paths resolved, and the same run under `--citations-only` refuses, because a gate exiting clean on a scope it could not build is the failure the gate exists to catch.
+The pattern spells both record-root prefixes, so a citation into a folder that has moved still resolves and a folder resolved at the project root is measured by every other check while contributing nothing here. A pattern fixed at one root matches nothing after a move and reports nothing, which is a stale reference passing the check written to find it. Widening it to a bare `docs/x.md` would match prose that references nothing, which is a separate decision from where entries come from. A run whose folders all resolved at the root says the check is out of scope rather than reporting that zero paths resolved, and the same run under `--citations-only` refuses, because a gate exiting clean on a scope it could not build is the failure the gate exists to catch.

package/docs/agents/index.md

@@ -27,7 +27,7 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Markdown audit](markdown-audit.md): Running the audit over any markdown path, where its bans and checkpoints are read from, what each check reports, and why the ban half gates while the structural half reports
 - [Output shape](output-shape.md): Two framed shapes every command renders into, how JSON and --names modes keep stdout clean, and the exit discipline that lets piped output drain
 - [Overview](overview.md): What this folder covers, the invocation rules every command inherits, and where domain behavior is documented instead
-- [Records](records.md): Validating the session records under .claude/ and the standards corpus, the per-kind checks, the refusal reasons, migrating a record a frontmatter change orphaned, reading each folder's size and growth, backing the folders to a private remote, and which root each kind defaults to
+- [Records](records.md): The two roots a record folder resolves at, validating the session records and the standards corpus, the per-kind checks, the refusal reasons, migrating a record a frontmatter change orphaned, reading each folder's size and growth, backing the folders to a private remote, and which root each kind defaults to
 - [Restated instructions](restated.md): Counting the instructions the always-loaded file and every path-scoped rule share with the seed, the shipped skill bodies, and each other, how a match is decided, the three classes, which surface a later edit starts from, and why the sweep reports rather than gates
 - [Review classification](review-classification.md): Deciding whether a changed set needs the review pass, the two tests it runs, why an empty set refuses rather than skipping, and the written fallback a target on an older binary falls back to
 - [Routing report](routing.md): Reading per CLAUDE.md section how many bullets name a path, what counts as naming one, when a rule counts as covering it, the two refusals, and why the verb reports rather than gates

package/docs/agents/records.md

@@ -1,10 +1,20 @@
 ---
 title: Records
-description: Validating the session records under .claude/ and the standards corpus, the per-kind checks, the refusal reasons, migrating a record a frontmatter change orphaned, reading each folder's size and growth, backing the folders to a private remote, and which root each kind defaults to
+description: The two roots a record folder resolves at, validating the session records and the standards corpus, the per-kind checks, the refusal reasons, migrating a record a frontmatter change orphaned, reading each folder's size and growth, backing the folders to a private remote, and which root each kind defaults to
 ---
 
 # Records
 
+## Record roots
+
+Every verb here resolves a record folder at two roots rather than one. `.canon/<folder>` is read first, `.claude/<folder>` second, and a folder neither root carries resolves to the creation default, which is `.claude/`. The scratch folder is the one name that differs by root, spelled `.claude/.tmp` and `.canon/tmp`, since inside a dotted root the leading dot hides nothing already hidden.
+
+The read order and the creation default disagree deliberately. The gitignored record folders are moving to a root of their own, and the CLI learns to read both roots in a release that ships ahead of the move, so the binary a session already holds knows where to look by the time a tree relocates. Creating under the new root before then would write records to a root whose ignore line may not have reached a project yet, and it would split one project's records across two roots with no verb able to reconcile them. The move flips the default and nothing else.
+
+A caller never spells a record root by hand for the same reason. A path written as `.claude/plans/...` resolves against one root and reports nothing when it is wrong, which is the quiet failure this ordering exists to prevent: a stale binary meeting a moved layout, writing to the old path, and reporting success. Read a folder through the verb that owns it, and where a skill needs the path itself, take it from that verb's record rather than composing one.
+
+A refusal names every root it looked at, so a message reading `no-folder` says where a write would land as well as where the read failed.
+
 ## Validate
 
 `canon records validate <kind>` reports where a file and the standard governing it disagree. Five kinds are gitignored folders under `.claude/`: `plans`, `groundwork`, `intake`, `memory`, and `teach`. The sixth is `standards`, the authoring corpus, which is tracked and installed rather than scratch.
@@ -56,7 +66,7 @@ A section runs to the next marker-shaped line whatever it names, so a plan carry
 
 ### Exit codes and refusals
 
-Exit codes: `0` every check passed, `1` refused, `2` at least one record carries a finding. A `reason` field carries which gate fired: `no-folder` when none of the kind's directories exist, and `unknown-kind` when the argument names no published kind. A `no-folder` message names every candidate, so the `standards` refusal names both roots.
+Exit codes: `0` every check passed, `1` refused, `2` at least one record carries a finding. A `reason` field carries which gate fired: `no-folder` when none of the kind's directories exist, and `unknown-kind` when the argument names no published kind. A `no-folder` message names every candidate, so a record kind's refusal names both record roots and the `standards` refusal names the authoring root and the installed copy.
 
 An exit code says nothing about a call made from a session, since a shell profile may wrap the binary in a function taking its status from a later command. Read the record's `findings` array and its `reason` rather than the exit when a skill consumes this.
 
@@ -96,7 +106,7 @@ Exit codes: `0` nothing carried a known transform, or `--write` repaired everyth
 
 ## Size
 
-`canon records size` reports what each record folder holds and how much of it is recent. It reads the ten backed folders named under Push and pull, plus `.claude/.tmp`, and it gates nothing.
+`canon records size` reports what each record folder holds and how much of it is recent. It reads the ten backed folders named under Push and pull, plus the scratch folder, and it gates nothing.
 
 ```bash
 canon records size
@@ -116,11 +126,11 @@ The reading carries two windows rather than one, at 7 and 30 days. A single wind
 
 Nothing fails on a number here. A record folder has no correct size, so the reading is a number to notice rather than a threshold to gate, and the point of the verb is that the next reading is taken by a command instead of by someone remembering to count the folder. The memory pen went from 44 entries to 236 between two readings taken by hand two weeks apart, which is the measurement this replaces.
 
-`.claude/.tmp` is read here and skipped by a backup, because deletable without loss is not the same as empty. The routing handoffs and the memory archive both sit there and both accumulate. `.claude/.records.git` stays out because it is the backup history rather than a record, and `.claude/worktrees/` stays out because each entry is a checkout of the project with its own removal verb, and one of them outweighs every record folder combined.
+The scratch folder is read here and skipped by a backup, because deletable without loss is not the same as empty. The routing handoffs and the memory archive both sit there and both accumulate. `.claude/.records.git` stays out because it is the backup history rather than a record, and `.claude/worktrees/` stays out because each entry is a checkout of the project with its own removal verb, and one of them outweighs every record folder combined.
 
 The window counts read `mtime`, so what they report is a file written inside the window rather than one created there. An entry edited long after it landed reads as recent, which overstates growth and never understates it, and these folders are append-mostly so the two readings agree on nearly every file. The one reading that is wrong rather than early is a machine restored by `canon records pull`, which resets the work tree hard and re-dates every file it writes, so a window taken there counts the restore. Nothing on the filesystem separates the two, since a restored file is new by every stamp it carries.
 
-Exit codes: `0` the reading completed, `1` refused. The one refusal is `no-folder`, raised when the root holds no `.claude` directory at all.
+Exit codes: `0` the reading completed, `1` refused. The one refusal is `no-folder`, raised when the project holds neither record root. A project holding a root and no records is empty rather than absent, and each folder's own `present` flag already says which of the ten it carries.
 
 ## Push and pull
 
@@ -132,9 +142,9 @@ canon records push --json
 canon records pull
 ```
 
-The backed folders are `diagrams`, `groundwork`, `intake`, `memory`, `plans`, `proposals`, `review`, `tasks`, and `teach`, all under `.claude/`. Eight of them are the Claude ignore group the claude manifest ships, minus three entries: `.claude/.tmp`, which is deletable without loss, `.claude/worktrees/`, whose contents belong to the project repository already, and `.claude/.records.git/`, which is the history the rest are pushed into. `diagrams` is the one that group does not carry at all, since a target still tracks its own copies, which is why the list is spelled out rather than derived. Each name is a top-level record folder and every archive sits inside the one it archives, so the list stays at one entry per surface however many archives appear. It is a constant rather than configuration, and it deliberately does not match the six record kinds `validate` hardcodes.
+The backed folders are `diagrams`, `groundwork`, `intake`, `memory`, `plans`, `proposals`, `review`, `tasks`, and `teach`, all under whichever record root the project carries. Eight of them are the Claude ignore group the claude manifest ships, minus three entries: `.claude/.tmp`, which is deletable without loss, `.claude/worktrees/`, whose contents belong to the project repository already, and `.claude/.records.git/`, which is the history the rest are pushed into. `diagrams` is the one that group does not carry at all, since a target still tracks its own copies, which is why the list is spelled out rather than derived. Each name is a top-level record folder and every archive sits inside the one it archives, so the list stays at one entry per surface however many archives appear. It is a constant rather than configuration, and it deliberately does not match the six record kinds `validate` hardcodes.
 
-Records are gitignored by design, so the history lives in a second git directory at `.claude/.records.git` with `.claude/` as its work tree. Every path stays where it is, which is what a separate checkout could not do. The verbs stage the nine folders by explicit pathspec with `--force`, so nothing outside them can enter the index however the ignore rules read, and the project working tree and its index are never touched. Each pathspec is a bare folder name and git reads it against the current directory rather than against the work tree the same call names, so the invocation carries `-C` at the work tree beside the other two flags. That is what lets either verb run from a linked worktree under `.claude/worktrees/`, which sits inside the records work tree and would otherwise prefix every name with its own path.
+Records are gitignored by design, so the history lives in a second git directory at `.records.git` inside the record root, with that root as its work tree. Both resolve off the root together rather than folder by folder, since a history opened at one root beside a work tree at the other would stage the deletion of every folder a move relocated. Every path stays where it is, which is what a separate checkout could not do. The verbs stage the nine folders by explicit pathspec with `--force`, so nothing outside them can enter the index however the ignore rules read, and the project working tree and its index are never touched. Each pathspec is a bare folder name and git reads it against the current directory rather than against the work tree the same call names, so the invocation carries `-C` at the work tree beside the other two flags. That is what lets either verb run from a linked worktree under `.claude/worktrees/`, which sits inside the records work tree and would otherwise prefix every name with its own path.
 
 ### Setup
 

package/docs/agents/tasks.md

@@ -51,7 +51,7 @@ canon tasks archive --pull-request 673 --json | jq -r 'if .ok then .task else .r
 
 The record carries `location`, one of `unstated`, `live`, `archived`, or `outside`, and `citedBy`, the other live tasks whose `Plan:` line lands on the same file. Exit codes: `0` read, `1` refused with `no-board` or `no-match`.
 
-The target resolves against `.claude/tasks/` and against the project root both, so `../plans/x.md` and `.claude/plans/x.md` land on the same file and one plan two tasks spelled differently counts once.
+The target resolves against the board folder and against the project root both, so `../plans/x.md` and `.claude/plans/x.md` land on the same file and one plan two tasks spelled differently counts once. Containment is tested at both record roots rather than at the one this tree resolves at, since a line somebody wrote against a root the tree has since left is still a path into the plans folder, and reading it as outside would report a shipped plan as still live. `docs/agents/records.md` states the read order.
 
 `canon tasks archive` gates on this same answer, so a caller wanting the count reads it here rather than scanning the board. The `claude-docs` plans sweep is the exception and still states the rule in its own body, because a plugin skill reaches a target on merge while the CLI reaches one on release, so a sweep calling a verb the installed `canon` predates gets no record back and archives nothing.
 

package/package.json

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

package/scripts/core/check-ignore-parity.sh

@@ -117,11 +117,17 @@ for entry in "${shipped[@]}"; do
 done
 
 # Claude-scoped patterns this repository ignores that the manifest does not
-# ship. Scoped to `.claude/` because the manifest is the claude stack and says
-# nothing about `node_modules/` or `.env`.
+# ship. Scoped to the two record roots because the manifest is the claude stack
+# and says nothing about `node_modules/` or `.env`.
+#
+# `.canon` is read as a bare root as well as a prefix, since it is one line
+# covering a whole tree where `.claude/` is thirteen lines naming folders inside
+# a root that also holds tracked content. Leaving it out is what would let a new
+# entry sit outside the only stage comparing the two lists, which is the
+# direction that goes silently blind.
 for pattern in "${ignored[@]}"; do
   case "$pattern" in
-  .claude/*) ;;
+  .claude/* | .canon | .canon/*) ;;
   *) continue ;;
   esac
   contains "$pattern" "${shipped[@]}" && continue

package/src/audits/baseline.ts

@@ -15,7 +15,7 @@ import type { AuditResult } from '@/audits/catalog'
  * that installs the CLI. A baseline in the package would hand a target this
  * repository's counts to measure its own tree against.
  */
-export const BASELINE_REL = join('.claude', 'audits', 'baseline.json')
+export const BASELINE_REL = join('.claude', 'canon', 'baseline.json')
 
 export interface Baseline {
   /** The day the record was taken, as `YYYY-MM-DD`. */

package/src/commands/claude.ts

@@ -51,6 +51,7 @@ import {
 import { copyPreservingMode } from '@/copy'
 import { execScript } from '@/exec'
 import { PROJECT_ROOT } from '@/project-root'
+import { recordDir } from '@/record-root'
 import { isDirectory, resolveTarget } from '@/target'
 import { injectGitignore, pruneGitignore } from '@/tooling/inject'
 import {
@@ -491,13 +492,18 @@ async function runSync(target: string): Promise<number> {
   const resolved = resolveTarget(target, PROJECT_ROOT)
   if (typeof resolved === 'number') return resolved
 
+  // A record folder resolves at either root, so a migrated target is reported as
+  // seeded rather than sent to `canon claude init` to re-create records it
+  // already holds. The three seeded files and `wireframes` are tracked and stay
+  // at `.claude/`, which the resolver answers for them anyway, since nothing
+  // ever creates a second root copy for a name that does not move.
   logStep('Seeded')
   for (const name of SEEDED_FILES) {
     if (existsSync(join(resolved, '.claude', name))) logInfo(name)
     else logWarn(`${name} missing. Run \`canon claude init\``)
   }
   for (const name of SEEDED_DIRS) {
-    if (isDirectory(join(resolved, '.claude', name))) logInfo(`${name}/`)
+    if (isDirectory(recordDir(resolved, name))) logInfo(`${name}/`)
     else logWarn(`${name}/ missing. Run \`canon claude init\``)
   }
 

package/src/commands/context.ts

@@ -180,7 +180,7 @@ async function runAudit(
   if (folders.length === 0) {
     return refuse(
       'no-folders',
-      `No audited folder found ${named ? 'under .claude/ or the project root' : 'under .claude/'}, since resolving one needs its own index.md file. Looked for: ${names.join(', ')}.`,
+      `No audited folder found ${named ? 'under a record root or the project root' : 'under a record root'}, since resolving one needs its own index.md file. Looked for: ${names.join(', ')}.`,
       gateOnly,
       root,
       opts.json ?? false,
@@ -200,7 +200,7 @@ async function runAudit(
   if (gateOnly && cited.length === 0) {
     return refuse(
       'no-citation-scope',
-      `The citation check spells the .claude/ prefix and no audited folder resolved there. Looked for: ${names.join(', ')}.`,
+      `The citation check spells the record-root prefixes and no audited folder resolved under one. Looked for: ${names.join(', ')}.`,
       gateOnly,
       root,
       opts.json ?? false,
@@ -414,7 +414,7 @@ function reportCitations(
 
   if (cited.length === 0) {
     logInfo(
-      'Out of scope. The pattern spells the .claude/ prefix, and no audited folder resolved there.',
+      'Out of scope. The pattern spells the record-root prefixes, and no audited folder resolved under one.',
     )
     return
   }

package/src/commands/design.ts

@@ -1,6 +1,7 @@
 import { existsSync } from 'node:fs'
 import { resolve } from 'node:path'
 import type { Command } from 'commander'
+import { creationRel } from '@/record-root'
 import { renderDesignDoc } from '@/design/render'
 import { palette } from '@/ui'
 
@@ -13,7 +14,11 @@ export function register(program: Command): void {
     .command('render')
     .description('Render DESIGN.md tokens to HTML and CSS preview')
     .option('-s, --source <path>', 'Source DESIGN.md path', '.claude/DESIGN.md')
-    .option('-o, --out <path>', 'Output directory', '.claude/review/design')
+    .option(
+      '-o, --out <path>',
+      'Output directory',
+      creationRel('review', 'design'),
+    )
     .action((opts: { source: string; out: string }) => {
       const sourcePath = resolve(process.cwd(), opts.source)
       const outDir = resolve(process.cwd(), opts.out)

package/src/commands/feedback.ts

@@ -3,6 +3,7 @@ import { join } from 'node:path'
 import type { Command } from 'commander'
 import { deriveSlug, deriveTitle } from '@/commands/feedback-format'
 import { PROJECT_ROOT } from '@/project-root'
+import { creationRel } from '@/record-root'
 import { createGithubIssue } from '@/github'
 import { frameError, frameSuccess, palette } from '@/ui'
 
@@ -39,7 +40,10 @@ function isToolkitSource(): boolean {
  * single ignore entry and the single backed-folder entry it already had.
  */
 function writeLocal(body: string): string {
-  const relativeDir = join('.claude', 'review', 'feedback')
+  // Creation, so the destination is the creation default rather than the
+  // resolved read root. A toolkit checkout that has migrated its records already
+  // carries the folder and resolves the same path either way.
+  const relativeDir = creationRel('review', 'feedback')
   const reviewDir = join(PROJECT_ROOT, relativeDir)
   mkdirSync(reviewDir, { recursive: true })
   const filename = `feedback-${deriveSlug(body)}-${timestamp()}.md`

package/src/commands/gov.ts

@@ -9,6 +9,7 @@ import {
   scanCounts,
 } from '@/counts/scan'
 import { PROJECT_ROOT } from '@/project-root'
+import { creationRel, SCRATCH } from '@/record-root'
 import { createGovAdapter } from '@/gov/adapter'
 import { regenConsumedRules } from '@/gov/consumed'
 import { installRules, lookupRules } from '@/gov/install'
@@ -65,7 +66,7 @@ import {
   select,
 } from '@/ui'
 
-const PAYLOAD_REL = join('.claude', '.tmp', 'gov', 'rules.md')
+const PAYLOAD_REL = creationRel(SCRATCH, 'gov', 'rules.md')
 const RULES_REL = join('.claude', 'rules')
 
 interface InstallOptions {

package/src/commands/slides.ts

@@ -1,6 +1,7 @@
 import { existsSync } from 'node:fs'
 import { resolve } from 'node:path'
 import type { Command } from 'commander'
+import { creationRel } from '@/record-root'
 import { LAYOUTS } from '@/slides/layouts'
 import { openDeck } from '@/slides/open'
 import { renderSlidesDoc } from '@/slides/render'
@@ -16,7 +17,11 @@ export function register(program: Command): void {
     .command('render')
     .description('Render a SLIDES.md source into a PowerPoint deck')
     .option('-s, --source <path>', 'Source SLIDES.md path', '.claude/SLIDES.md')
-    .option('-o, --out <path>', 'Output directory', '.claude/review/slides')
+    .option(
+      '-o, --out <path>',
+      'Output directory',
+      creationRel('review', 'slides'),
+    )
     .option('-v, --variant <variant>', 'Override variant (light or dark)')
     .option(
       '-m, --mirror <path>',

package/src/context/citations.ts

@@ -2,6 +2,7 @@ import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { resolve } from 'node:path'
 import { listRepositoryFiles } from '@/git-files'
+import { RECORD_ROOTS } from '@/record-root'
 
 /**
  * Suppresses citation checking for the source line carrying it.
@@ -76,21 +77,31 @@ export function isFixture(rel: string): boolean {
   return rel.split('/').some((segment) => FIXTURE_SEGMENTS.includes(segment))
 }
 
+/**
+ * Both record roots are spelled, so a citation into a folder that has moved is
+ * still resolved. A pattern fixed at one root matches nothing after the move and
+ * reports nothing, which is a stale reference passing the check that exists to
+ * find it rather than a check that fails.
+ */
 export function citationPattern(folders: readonly string[]): RegExp {
-  const names = folders.map((name) =>
-    name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'),
-  )
+  const names = folders.map((name) => escape(name))
+  const roots = RECORD_ROOTS.map((name) => escape(name))
+
   return new RegExp(
-    `\\.claude/(?:${names.join('|')})/[A-Za-z0-9._/-]+\\.md`,
+    `(?:${roots.join('|')})/(?:${names.join('|')})/[A-Za-z0-9._/-]+\\.md`,
     'g',
   )
 }
 
+function escape(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
 /**
  * A backticked filename carrying no folder, the form a reference takes when it
  * names a sibling rather than a path.
  *
- * `citationPattern` spells the `.claude/` prefix and cannot see this shape at
+ * `citationPattern` spells a record-root prefix and cannot see this shape at
  * all, which is the reason the form rule exists. Widening that expression to
  * admit a bare name was the alternative and it puts one match in the position of
  * answering two questions, since a spelled path is a reference by construction

package/src/context/folders.ts

@@ -1,9 +1,10 @@
 import { existsSync } from 'node:fs'
 import { dirname, relative, resolve } from 'node:path'
 import { INDEX_FILE, listIndexes } from '@/indexes/walk'
+import { RECORD_ROOTS } from '@/record-root'
 
 /**
- * Folder names under `.claude/` audited by default.
+ * Folder names under a record root audited by default.
  *
  * A named list rather than the index-plus-entry contract read off disk, so a
  * generated tree satisfying that contract is never measured against a rule
@@ -12,8 +13,8 @@ import { INDEX_FILE, listIndexes } from '@/indexes/walk'
  * here.
  *
  * It doubles as the citation check's scope, since `citationPattern` spells only
- * these names. A `.claude/` folder left off the list is never resolved, so a
- * path into one goes stale silently rather than failing a push.
+ * these names. A folder left off the list is never resolved, so a path into one
+ * goes stale silently rather than failing a push.
  */
 export const DEFAULT_FOLDERS: readonly string[] = [
   'context',
@@ -21,8 +22,17 @@ export const DEFAULT_FOLDERS: readonly string[] = [
   'wireframes',
 ]
 
-/** The base every folder in the default list sits under. */
-const CLAUDE_BASE = '.claude'
+/**
+ * The bases every folder in the default list is looked for under, in the record
+ * roots' own precedence order.
+ *
+ * `diagrams` is the one name here that is a session record and moves with them,
+ * so the list has to carry the root it moves to. `context` and `wireframes` are
+ * tracked and stay, which leaves them resolvable at a root nothing will ever put
+ * them under. That costs one `existsSync` apiece and is cheaper than a per-name
+ * base map that would state the same split twice.
+ */
+const CLAUDE_BASES: readonly string[] = RECORD_ROOTS
 
 /** The project root, reached only by a name the caller asked for. */
 const ROOT_BASE = '.'
@@ -58,7 +68,7 @@ export interface AuditedFolder {
 }
 
 /**
- * Names the requested `.claude/` folders that actually exist, which is the
+ * Names the requested record-root folders that actually exist, which is the
  * citation check's scope.
  *
  * A skill or seed pointing into `.claude/wireframes/` is a live instruction for
@@ -76,7 +86,7 @@ export function presentNames(folders: readonly AuditedFolder[]): string[] {
   return [
     ...new Set(
       folders
-        .filter((folder) => folder.base === CLAUDE_BASE)
+        .filter((folder) => CLAUDE_BASES.includes(folder.base))
         .map((folder) => folder.name),
     ),
   ]
@@ -157,7 +167,7 @@ export async function resolveFolders(
   names: readonly string[] = DEFAULT_FOLDERS,
   { canResolveAtRoot = false }: ResolveOptions = {},
 ): Promise<FolderResolution> {
-  const bases = canResolveAtRoot ? [CLAUDE_BASE, ROOT_BASE] : [CLAUDE_BASE]
+  const bases = canResolveAtRoot ? [...CLAUDE_BASES, ROOT_BASE] : CLAUDE_BASES
   const folders: AuditedFolder[] = []
   const missing: string[] = []
 

package/src/gate/measures.ts

@@ -97,7 +97,7 @@ export const SANDBOX_UNDECLARED_CEILING = 47
  * rather than derived, because this stage only ever names the file in a remedy
  * a reader has to be able to open, and `canon audits run` owns writing it.
  */
-export const AUDITS_BASELINE = '.claude/audits/baseline.json'
+export const AUDITS_BASELINE = '.claude/canon/baseline.json'
 
 export const HERO_STAMP_FAILURE =
   'The hero set disagrees with the stamp written when the image was captured. Run canon capture assets/hero.html and commit all three files together.'

package/src/intake/folder.ts

@@ -9,6 +9,7 @@ import {
   readItems,
   writeAnswerLine,
 } from '@/intake/items'
+import { recordDir } from '@/record-root'
 
 export const INTAKE_REFUSALS = [
   'no-intake',
@@ -80,7 +81,7 @@ function refuse(
 }
 
 export function intakeDir(root: string): string {
-  return join(root, '.claude', 'intake')
+  return recordDir(root, 'intake')
 }
 
 /**

package/src/record-root.ts

@@ -0,0 +1,134 @@
+import { existsSync } from 'node:fs'
+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.
+ *
+ * The shape is `readStamp`'s: order the spellings, take the first that exists,
+ * and stand the creation default in when none does.
+ */
+export const RECORD_ROOTS = ['.canon', '.claude'] as const
+
+export type RecordRoot = (typeof RECORD_ROOTS)[number]
+
+/**
+ * The root a record folder is created at.
+ *
+ * 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.
+ */
+export const CREATION_ROOT: RecordRoot = '.claude'
+
+/**
+ * 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.
+ */
+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 {
+  return root === '.canon' && folder === SCRATCH ? CANON_SCRATCH : folder
+}
+
+/**
+ * The root a folder resolves at: the first that carries it, and the creation
+ * default when neither does.
+ *
+ * Presence is read on the record folder itself rather than on the full path, so
+ * an archive or a payload that does not exist yet still resolves beside the
+ * records it belongs to rather than at the creation default.
+ */
+function rootOf(root: string, folder: string): RecordRoot {
+  return (
+    RECORD_ROOTS.find((candidate) =>
+      existsSync(join(root, candidate, spell(candidate, folder))),
+    ) ?? CREATION_ROOT
+  )
+}
+
+/**
+ * Where a record folder is read.
+ *
+ * `folder` is the record folder itself and `rest` is whatever sits inside it,
+ * so a caller spells no root and no folder-name variant of its own. A caller
+ * that spells `.claude` by hand is the one thing the move has to find, and one
+ * that calls this is one the move never has to open again.
+ */
+export function recordDir(
+  root: string,
+  folder: string,
+  ...rest: string[]
+): string {
+  const at = rootOf(root, folder)
+
+  return join(root, at, spell(at, folder), ...rest)
+}
+
+/**
+ * Every root a record folder would be read at, in precedence order, whether or
+ * not it is on disk.
+ *
+ * Containment tests take this rather than `recordDir`, since a path written
+ * against the root a tree no longer uses is still a path into that folder and
+ * reading it as outside would report a shipped plan as still live.
+ */
+export function recordDirs(
+  root: string,
+  folder: string,
+  ...rest: string[]
+): string[] {
+  return RECORD_ROOTS.map((candidate) =>
+    join(root, candidate, spell(candidate, folder), ...rest),
+  )
+}
+
+/** Where a record folder is created, which is the creation default always. */
+export function creationDir(
+  root: string,
+  folder: string,
+  ...rest: string[]
+): string {
+  return join(root, CREATION_ROOT, spell(CREATION_ROOT, folder), ...rest)
+}
+
+/**
+ * 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)
+}
+
+/**
+ * The record root itself, for a caller whose subject is the root rather than a
+ * folder inside it.
+ *
+ * A half-migrated tree resolves here on the root that exists rather than on the
+ * folders under it, which is what makes the backup history and its work tree
+ * one answer. Splitting them would let a push resolve a history at one root and
+ * stage a work tree at the other, which stages the deletion of every folder the
+ * move relocated.
+ */
+export function recordRoot(root: string): string {
+  return join(
+    root,
+    RECORD_ROOTS.find((candidate) => existsSync(join(root, candidate))) ??
+      CREATION_ROOT,
+  )
+}