@erclx/canon 4.6.1 → 4.7.0

package/docs/ai-workflow.md

@@ -12,7 +12,7 @@ A concise reference for when to reach for which tool, organized by what you're t
 
 ## Documents
 
-Project docs live in `.claude/` at the project root.
+Project docs split across two roots at the project root, on one mechanical line: what is committed lives in `.claude/`, and every gitignored session record lives in `.canon/`, which a single ignore entry covers.
 
 ```plaintext
 .claude/
@@ -20,12 +20,19 @@ Project docs live in `.claude/` at the project root.
 ├── ARCHITECTURE.md  ← technical design decisions
 ├── DESIGN.md        ← visual intent and token decisions (UI projects)
 ├── WIREFRAMES.md    ← ASCII wireframes: layout, UI copy, and interaction rules (UI projects)
-├── diagrams/        ← one Mermaid entry per diagram kind with a generated index.md, redrawn on demand
-├── tasks/           ← one file per task with a generated index.md, gitignored local scratch
 ├── context/         ← per-domain narrative loaded on demand via index.md
 └── rules/           ← path-scoped governance rules, written by canon gov install
+
+.canon/
+├── diagrams/        ← one Mermaid entry per diagram kind with a generated index.md, redrawn on demand
+├── tasks/           ← one file per task with a generated index.md, local scratch
+├── plans/           ← one plan per feature, archived inside itself once it ships
+├── memory/          ← durable session facts no context entry owns
+└── tmp/             ← deletable scratch, safe to remove without loss
 ```
 
+A project scaffolded before the move keeps its records under `.claude/`, and every command reads either root. `canon migrate records` moves one project across and repoints what cites it.
+
 Three tiers of context load with different cost: always-loaded (root `CLAUDE.md`, `.claude/REQUIREMENTS.md`, `.claude/ARCHITECTURE.md`), path-scoped lazy (`.claude/rules/<scope>.md` with `paths:` glob), and on-demand lookup (`.claude/context/<domain>.md`, or `.claude/context/<domain>/` once a domain outgrows one file, discovered via `.claude/context/index.md`). See [the context model](../.claude/context/context-model.md) for the full picture.
 
 Run `canon init` to seed the `.claude/` directory, a root `CLAUDE.md` file, and `.claude/rules/` in one pass. `canon init` chains claude init and governance install. Claude Code auto-loads every file in `.claude/rules/` at session start, applying always-on rules unconditionally and path-scoped rules to files matching their `paths:` glob.
@@ -44,8 +51,8 @@ One session works for most features. Prefer splitting across two sessions only w
 
 Work in Claude Code directly. It reads `CLAUDE.md` automatically and has full file access, no pasting needed.
 
-- When the input is a pile of findings rather than one feature, invoke `canon:claude-intake` first. It files the dump into `.claude/intake/<nn>-<slug>/`, one item per finding carrying a problem measured against the tree, a proposed fix, and a verdict, then names which items are plan-ready, which need measuring, and which are already settled.
-- When the current state is unmeasured and more than one approach is live, invoke `canon:claude-groundwork` first. It opens a track folder under `.claude/groundwork/<nn>-<slug>/` and ends in a decision, which may be to do nothing. Skip it when the approach is already settled.
+- When the input is a pile of findings rather than one feature, invoke `canon:claude-intake` first. It files the dump into `.canon/intake/<nn>-<slug>/`, one item per finding carrying a problem measured against the tree, a proposed fix, and a verdict, then names which items are plan-ready, which need measuring, and which are already settled.
+- When the current state is unmeasured and more than one approach is live, invoke `canon:claude-groundwork` first. It opens a track folder under `.canon/groundwork/<nn>-<slug>/` and ends in a decision, which may be to do nothing. Skip it when the approach is already settled.
 - Invoke `canon:claude-feature` to scan for code-level conflicts and ambiguities, confirm approach before proceeding
 - Implement the feature, then Claude Code runs the commands defined in `CLAUDE.md`, fixes failures, and iterates until all pass
 - For UI changes, invoke `canon:claude-ui-test` to generate and run Playwright e2e tests
@@ -53,7 +60,7 @@ Work in Claude Code directly. It reads `CLAUDE.md` automatically and has full fi
 
 The routing test is whether the repository can answer an item today. A session grepping handles the yes, and a groundwork track handles the no.
 
-A groundwork track may run experiments to settle a question, writing a fixture it reads itself under `.claude/.tmp/groundwork-fixtures/<slug>/` and spawning up to three billed headless runs before it asks. A fixture a headless run is pointed at sits outside the repository, since a session started under the project root inherits that project's `CLAUDE.md` and rules and would measure them instead of the arm.
+A groundwork track may run experiments to settle a question, writing a fixture it reads itself under `.canon/tmp/groundwork-fixtures/<slug>/` and spawning up to three billed headless runs before it asks. A fixture a headless run is pointed at sits outside the repository, since a session started under the project root inherits that project's `CLAUDE.md` and rules and would measure them instead of the arm.
 
 What a spike produces goes somewhere else again. An input the run reads is re-runnable and cited by nothing, so the scratch path above is the right lifetime for it, while a recording or a render the track cites as evidence for a finding is what a later reader opens to check the claim. Evidence therefore lives in `evidence/` inside the track beside the file citing it, since the scratch tree holds only what can be deleted without loss.
 
@@ -70,14 +77,14 @@ Start a fresh Claude Code session. The diff is sufficient context for both revie
 When features are independent, run them in parallel instead of sequentially. Use one git worktree per feature so each session has its own working tree and branch.
 
 - Create a worktree per feature, then start a Claude Code session in each
-- Invoke `canon:claude-feature` in each session. Plans land at the main worktree root as `.claude/plans/feature-<slug>.md`, one per feature, no collisions. Small features stay in chat and skip the file.
+- Invoke `canon:claude-feature` in each session. Plans land at the main worktree root as `.canon/plans/feature-<slug>.md`, one per feature, no collisions. Small features stay in chat and skip the file.
 - Implement, verify, and review each feature independently. `claude-review` and `claude-ui-test` write per-branch files at the main worktree root (`review/branch/review-<slug>.md`, `review/ui-checklist-<slug>.md`), so parallel sessions do not overwrite each other. The slug is the branch name with any leading type segment dropped, so `feat/jwt-expiration` and the plan at `feature-jwt-expiration.md` meet on one name
 - Ship each worktree separately with `canon:git-ship`
 - For full autonomy per worktree, invoke `canon:claude-autoship` instead of the manual chain. Approve the plan, walk away, come back to draft PRs.
 
 To run several worktrees as a coordinated flow rather than ad hoc, assert the orchestrator role in one warm session with `canon:claude-orchestrate`. It holds the cross-feature call, plans each feature itself or dispatches a cold planner under `canon:claude-planner` to write the plan, refills the ready queue so a free worker never waits, and reviews each worker's PR with `canon:claude-pr-review`, then tells the session holding that branch to run `canon:claude-address-review` whenever the pass posted a finding at any severity, which is the same threshold `canon:claude-pr-review` states and posts its open heading under. The human launches workers and merges. See [operating model](operating-model.md) for the full loop.
 
-Execution order comes off `.claude/tasks/priority.md` and nothing sequences work into versions. Scope stays in `.claude/REQUIREMENTS.md` as a statement of what is wanted, and it reaches the board as discrete tasks the orchestrator orders by readiness.
+Execution order comes off `.canon/tasks/priority.md` and nothing sequences work into versions. Scope stays in `.claude/REQUIREMENTS.md` as a statement of what is wanted, and it reaches the board as discrete tasks the orchestrator orders by readiness.
 
 Run one orchestrator at a time. The board is gitignored, so a second session reads none of the first one's writes and the two collide on labels and archives.
 
@@ -87,7 +94,7 @@ Before a handoff, the orchestrator checks the plan against the tree rather than
 
 A constraint naming a track in flight carries the same problem past the handoff, so the block opens with the commit it was measured against. A worker re-tests before honoring one, fetching and then logging that commit against `origin/main` over the paths the constraint names, and any merge there means the track landed and the constraint is dead. An unstamped block reads as unverified rather than as live, which covers every plan written before the rule.
 
-`.claude/plans/`, `.claude/review/`, and `.claude/memory/` all resolve at the main worktree root, so artifacts created in any session are visible from any sibling worktree. A session inside a worktree reads them directly, since the file-editing tools refuse a main-root path but `Read` resolves normally. It writes a whole file through the shell and makes a change inside an existing file through a `canon` verb, which resolves the main root in-process. See [Claude Code and git worktrees](../wiki/claude/claude-worktrees.md) for the full rule and the domain-level fan-out guidance.
+`.canon/plans/`, `.canon/review/`, and `.canon/memory/` all resolve at the main worktree root, so artifacts created in any session are visible from any sibling worktree. A session inside a worktree reads them directly, since the file-editing tools refuse a main-root path but `Read` resolves normally. It writes a whole file through the shell and makes a change inside an existing file through a `canon` verb, which resolves the main root in-process. See [Claude Code and git worktrees](../wiki/claude/claude-worktrees.md) for the full rule and the domain-level fan-out guidance.
 
 The plan's shape is fixed by `standards/plan.md`: the section list, the filename, the lifecycle, and the contract its questions keep. Every question carries a `- Suggested:` line and an empty `- Answer:` slot, and a blank answer accepts the suggestion at execution time. That default is what makes a plan decision-ready in one pass, and it is the opposite of the contract an intake folder keeps, where an empty slot means nobody reached the item.
 
@@ -95,29 +102,29 @@ An execution that picks other than the suggestion rewrites the `- Suggested:` li
 
 `canon records validate plans` reports where a plan and that standard disagree: a filename that is not `feature-<slug>.md`, a missing required section, a files-to-touch entry naming no file, and a question carrying a suggestion with no answer slot. The same verb takes `groundwork`, `intake`, `memory`, and `teach`, which are governed the same way and were unreachable for the same reason. Nothing fires it automatically, because all five folders are gitignored and every check the repository runs reads changed files from git. It reports and never writes, since the folders are per-machine scratch with no history to recover a wrong repair from.
 
-`canon records push` carries these folders off the disk they live on, and `canon records pull` brings them back. Nine of them are backed: `diagrams`, `groundwork`, `intake`, `memory`, `plans`, `proposals`, `review`, `tasks`, and `teach`, each carrying whatever it has archived inside it. The history lives in a second git directory at `.claude/.records.git` with `.claude/` as its work tree, so every path a task file cites stays where it is.
+`canon records push` carries these folders off the disk they live on, and `canon records pull` brings them back. Nine of them are backed: `diagrams`, `groundwork`, `intake`, `memory`, `plans`, `proposals`, `review`, `tasks`, and `teach`, each carrying whatever it has archived inside it. The history lives in a second git directory at `.canon/.records.git` with `.canon/` as its work tree, so every path a task file cites stays where it is.
 
 A person points it at a private repository once and both verbs refuse until they have, and `push` refuses when that origin is also a remote of the project, since the payload is the memory pen and the groundwork trails. `.husky/post-merge` runs the push after its archive loop, on every merge rather than only on one that closed a task. See [records](agents/records.md) for the refusal table.
 
-`canon records size` reports what each of these folders holds, heaviest first, along with `.claude/.tmp`. Each row carries the file count, the bytes, how many files were written in the last 7 and 30 days, and the dates of the least and most recently written one. Nothing fails on a number, because a record folder has no correct size. What the verb replaces is a reading somebody had to remember to take: the memory pen went from 44 entries to 236 between two counts made by hand a fortnight apart, and nothing reported the rate in between.
+`canon records size` reports what each of these folders holds, heaviest first, along with `.canon/tmp`. Each row carries the file count, the bytes, how many files were written in the last 7 and 30 days, and the dates of the least and most recently written one. Nothing fails on a number, because a record folder has no correct size. What the verb replaces is a reading somebody had to remember to take: the memory pen went from 44 entries to 236 between two counts made by hand a fortnight apart, and nothing reported the rate in between.
 
-A plan that ships is archived, never deleted. `canon:claude-docs` moves it to `.claude/plans/archive/` and retargets the task file's `Plan:` line at the new location, so a completed task still leads to the reasoning behind it. An archive sits inside the record folder it archives rather than beside it, so one ignore entry and one backed-folder entry cover a record and everything it has retired. The folder is gitignored, which is why a deleted plan had no recovery path. A plan cited by more than one task stays put until the last of them closes, since moving it early would strand every other pointer.
+A plan that ships is archived, never deleted. `canon:claude-docs` moves it to `.canon/plans/archive/` and retargets the task file's `Plan:` line at the new location, so a completed task still leads to the reasoning behind it. An archive sits inside the record folder it archives rather than beside it, so one ignore entry and one backed-folder entry cover a record and everything it has retired. The folder is gitignored, which is why a deleted plan had no recovery path. A plan cited by more than one task stays put until the last of them closes, since moving it early would strand every other pointer.
 
-A branch review report takes the other route and is swept rather than archived. `claude-review` writes it to `.claude/review/branch/`, the session addressing it reads it once, and the durable record of what a review found is the comment `claude-pr-review` posts on the pull request, so `claude-docs` deletes any report whose branch is gone. The body that writes a report owns how long it lives, which leaves the shipping branch's own report on disk through the run that cites it and collects it a branch later. What that loses is a local-only review on a branch that never opened a pull request, which is why the report says so where a reader meets it.
+A branch review report takes the other route and is swept rather than archived. `claude-review` writes it to `.canon/review/branch/`, the session addressing it reads it once, and the durable record of what a review found is the comment `claude-pr-review` posts on the pull request, so `claude-docs` deletes any report whose branch is gone. The body that writes a report owns how long it lives, which leaves the shipping branch's own report on disk through the run that cites it and collects it a branch later. What that loses is a local-only review on a branch that never opened a pull request, which is why the report says so where a reader meets it.
 
 The plans sweep reads the whole board rather than the tasks the session touched. It is the one place the skill reaches past its own rule against editing a task file the session did not change, because a task that closed while an earlier run missed its archive is exactly what the sweep exists to clear. Reaching it is safe: the archive moves the plan and retargets the pointer in the same pass, so an untouched task ends up with a working link rather than a broken one.
 
 `canon:claude-docs` decides which task closed by reading the diff rather than the conversation. It resolves a merge base against `origin/main`, unions the committed diff with the working tree and untracked files, then matches unchecked outcomes on the board against what shipped. A task that shipped without ever being discussed still gets marked. Requirements, architecture, and design stay session-sourced, because a diff cannot carry a judgment.
 
-`.claude/tasks/` is gitignored and resolves at the main worktree root, so every session shares one board. One file per task is what keeps concurrent sessions from overwriting each other, since a gitignored board has no history to recover a lost write from. Its `index.md` is generated by a hook rather than by `bun run check`, because the whole-repo index walk skips gitignored folders.
+`.canon/tasks/` is gitignored and resolves at the main worktree root, so every session shares one board. One file per task is what keeps concurrent sessions from overwriting each other, since a gitignored board has no history to recover a lost write from. Its `index.md` is generated by a hook rather than by `bun run check`, because the whole-repo index walk skips gitignored folders.
 
-`.claude/memory/` carries the same arrangement, its own hook regenerating `index.md` from each entry's `title`, `description`, and `category`. A hand-maintained `priority.md` sits beside it carrying execution order and what each task is waiting on, which the alphabetical index cannot express.
+`.canon/memory/` carries the same arrangement, its own hook regenerating `index.md` from each entry's `title`, `description`, and `category`. A hand-maintained `priority.md` sits beside it carrying execution order and what each task is waiting on, which the alphabetical index cannot express.
 
 `canon tasks validate` reads a row against its own table before it reads anything the row claims. A blank or prose line closes the table above it, so a row stranded there is checked against the line behind it rather than parsed as a continuation, and a row that clears that test still has its cell count checked against its header. A `## Needs a plan` row that states its own position, searched for `<ordinal> here` or the bare word `last` anywhere in the cell rather than at its start, is checked against where it actually sits, which is what catches a gap, a duplicate, and a sequence starting somewhere other than first alike.
 
 Past that shape, it checks what a surviving row claims against what the tree holds: every plan pointer resolves, every task file is named by a board row or a backlog line and never by both, no task sits in two groups, and no two rows marked ready touch the same file. One check across both surfaces is what lets a task move between the board and the backlog without the move reading as a dropped file. The collision check is the half a reader cannot run by eye, and it is what keeps two workers from being handed colliding work. Blockers re-takes what a parked row waits on, reporting one whose cited task reached the trunk and one whose cited file nothing running still holds. A cited task settles the row by being archived, or by closing every outcome and naming a pull request the trunk carries, since the checkbox alone is marked while the branch is still in review. Both halves read a citation out of the blocker cell, so a row citing neither is reported as untested rather than counted clean, and so is a cited task the trunk could not answer for. It reports and never writes, because a row is the orchestrator's claim and a validator repairing one would assert the claim it exists to test. Nothing fires it automatically, since the board is gitignored per-machine scratch with no shared moment to hang a hook on, so the orchestrator's sweep calls it at the point the readiness claim is made and follows it with the parked re-test.
 
-`canon:claude-tasks` owns the two operations that bracket a task's life. It creates the file, holding the filename convention and the frontmatter contract so a malformed write cannot break the index for every sibling, and it moves a shipped task to `.claude/tasks/archive/`. Creation is where the origin invariant is enforced: every task names a plan, a groundwork folder, an intake folder, or an issue, since a task with no origin is either lost context or work nobody decided to do.
+`canon:claude-tasks` owns the two operations that bracket a task's life. It creates the file, holding the filename convention and the frontmatter contract so a malformed write cannot break the index for every sibling, and it moves a shipped task to `.canon/tasks/archive/`. Creation is where the origin invariant is enforced: every task names a plan, a groundwork folder, an intake folder, or an issue, since a task with no origin is either lost context or work nobody decided to do.
 
 Archiving a task leaves its plan alone, because `canon:claude-docs` owns the plans sweep and already holds the last-live-citation rule. That makes the order load-bearing, so the archive verb refuses the last task pointing at a live plan. The sweep only reaches tasks still in the live folder, and archiving that task first would strand the plan there with nothing citing it. A task whose plan a sibling still cites archives freely, because the sweep is correct to leave that plan where it is and a gate reading the folder instead would park every task sharing one plan behind a sweep that will never move it.
 
@@ -152,13 +159,13 @@ The list stays written in the skill body as the fallback for a target whose inst
 
 #### Memory in the chain
 
-`git-ship` runs its verify gate and then opens on `claude-memory-capture`, which sends what the session learned to the surface that owns it. `autoship` reaches the same step by invoking that skill at its Step 7 rather than restating the order. A fact about a domain carrying an entry in `.claude/context/index.md` is routed to that entry, and `claude-docs` folds it in on the next step, so it ships in the same pull request. Anything no entry owns stays a file in `.claude/memory/`.
+`git-ship` runs its verify gate and then opens on `claude-memory-capture`, which sends what the session learned to the surface that owns it. `autoship` reaches the same step by invoking that skill at its Step 7 rather than restating the order. A fact about a domain carrying an entry in `.claude/context/index.md` is routed to that entry, and `claude-docs` folds it in on the next step, so it ships in the same pull request. Anything no entry owns stays a file in `.canon/memory/`.
 
 Capture leads rather than trails because a routed fact edits a tracked file, which has to reach the branch before the commit steps run.
 
 If capture wrote at least one memory file, `claude-memory-review` then proposes a decision-ready fix scoped to those entries while context is fresh, otherwise it is skipped. It stops at Propose. Review the receipt and run Apply yourself, on its own commit separate from the feature.
 
-Run `claude-memory-review` standalone to curate the whole pen. An entry it retires moves to `.claude/.tmp/memory-archive/` rather than being deleted, since the folder is gitignored and a bulk pass has no undo.
+Run `claude-memory-review` standalone to curate the whole pen. An entry it retires moves to `.canon/tmp/memory-archive/` rather than being deleted, since the folder is gitignored and a bulk pass has no undo.
 
 The receipt is collected once every item on it has been decided, and it survives untouched while any item is still pending. Whichever runs first takes it: Apply collects the receipt it has resolved, and `claude-docs` scans the folder on every shipped branch for one an earlier session left behind. Before the file goes, each declined item is folded into the entry it was about, since a promotion survives in its target and in git while a decline is recorded nowhere else. `canon standards memory` states what a fold writes and which entry types take one.
 
@@ -197,7 +204,7 @@ This section is the corpus the coverage claim is measured against: every name `c
 | `canon:setup-plugins`         | On a new machine, to install the community and official plugins user-scoped             |
 | `canon:setup-verify`          | After the agent generates configs, to run the installed scripts and report pass or fail |
 | `canon:claude-design-extract` | Before the first UI feature, to draft `.claude/DESIGN.md`                               |
-| `canon:claude-diagram`        | Once the architecture is written, to draft per-kind entries under `.claude/diagrams/`   |
+| `canon:claude-diagram`        | Once the architecture is written, to draft per-kind entries under `.canon/diagrams/`    |
 
 ### Decide what to build
 

package/docs/operating-model.md

@@ -53,7 +53,7 @@ halts on a plan question it may not answer, or argues back against an
 instruction the tree contradicts, is working correctly. The four measured halts
 to date each cost the dispatcher one reply and each was right.
 
-What the worker may not do is write `.claude/tasks/priority.md` or the backlog
+What the worker may not do is write `.canon/tasks/priority.md` or the backlog
 beside it. Those are gitignored, so an overwrite drops a row with no history to
 recover it from, and a worker cannot pick a free task label without reading
 every task file and every archive entry. It reports the row it needs and lets
@@ -69,7 +69,7 @@ and no later session recovers that vantage.
 
 One feature travels this path end to end.
 
-1. The next feature is planned with `claude-feature`, writing a plan to `.claude/plans/`. The orchestrator runs it warm when the row turns on a contract other features consume or a shared wiring seam, and dispatches a planner under `claude-planner` otherwise. A cold planner measures the row against the tree rather than trusting what the row claims, and it reads what is in flight from open pull requests rather than from branches and worktrees, which this repository leaves behind after a squash merge.
+1. The next feature is planned with `claude-feature`, writing a plan to `.canon/plans/`. The orchestrator runs it warm when the row turns on a contract other features consume or a shared wiring seam, and dispatches a planner under `claude-planner` otherwise. A cold planner measures the row against the tree rather than trusting what the row claims, and it reads what is in flight from open pull requests rather than from branches and worktrees, which this repository leaves behind after a squash merge.
 2. Orchestrator checks the plan waits on nobody, checks the branch is unclaimed, and checks the plan's file set is disjoint from every track in flight, then dispatches a background worker with `claude --bg` against the plan, naming the branch and the model on the launch rather than leaving the worker to derive either. No count caps how many run at once. The branch travels as the argument to the worker's own worktree call, which is the one place the name is read rather than inferred. It falls back to naming the invocation for a human to run through `claude-worktree` and `claude-autoship` when the plan still waits on an answer only the operator can give, the check refuses, the sets overlap, or a stated reason serializes the plan behind a track already in flight. Either way, the worker enters its own worktree, builds, self-checks, opens a PR, and stops at the PR boundary.
 3. Orchestrator reviews the PR with `claude-pr-review` and posts findings to it.
 4. Orchestrator tells the session holding that branch to run `claude-address-review` once the pass posted a finding at any severity, resolving the target then with `canon sessions list --branch` and reporting the invocation for the human when no live session holds it. The worker addresses the findings, rebases onto `origin/main` when a sibling landed first and left the branch unable to merge, then pushes a follow-up. A pass carrying only minor findings dispatches too, since the grade runs low often enough that a floor at should-fix loses fixes a worker would have made. `claude-pr-review` states that threshold and the heading follows it, so an open heading is itself the signal to send.
@@ -203,7 +203,7 @@ coordination costs more than the change it was too small.
 
 Two tiers hold work at different altitudes.
 
-- Tasks (`.claude/tasks/`): the active few pulled into the current turn, one file each. Gitignored, high churn. Shape governed by `standards/tasks.md`. `priority.md` beside them carries execution order, and `backlog.md` carries what nobody is scheduling.
+- Tasks (`.canon/tasks/`): the active few pulled into the current turn, one file each. Gitignored, high churn. Shape governed by `standards/tasks.md`. `priority.md` beside them carries execution order, and `backlog.md` carries what nobody is scheduling.
 - Edits: a few lines, done immediately with no ceremony.
 
 Nothing above these sequences work into versions. Scope is stated in

package/docs/target-projects.md

@@ -70,7 +70,7 @@ Scaffold installs tooling and seeds. It does not fill the planning docs or the d
 
 1. Fill `.claude/REQUIREMENTS.md` and `.claude/ARCHITECTURE.md`. The seed provides the files, the scope and decisions are yours to write.
 2. For a UI project, invoke `canon:claude-design-extract` to draft `.claude/DESIGN.md`. With no UI code yet it takes the greenfield path and proposes tokens from the requirements and a `## Personality` section. Skip for non-UI projects.
-3. Optionally invoke `canon:claude-diagram` to draft entries under `.claude/diagrams/` from the architecture and the requirements. One file per diagram kind, so a later refresh of one kind leaves the others untouched. It renders each diagram it writes to verify the layout, which downloads the Mermaid CLI on first use and takes about 15 seconds.
+3. Optionally invoke `canon:claude-diagram` to draft entries under `.canon/diagrams/` from the architecture and the requirements. One file per diagram kind, so a later refresh of one kind leaves the others untouched. It renders each diagram it writes to verify the layout, which downloads the Mermaid CLI on first use and takes about 15 seconds.
 4. Start the feature loop. See [AI workflow](ai-workflow.md) for the per-feature sequence.
 
 A machine without a renderer still gets the diagrams and is told which check was skipped.
@@ -124,6 +124,26 @@ Per-domain mechanics live in the corresponding `docs/<domain>.md`. The skill bod
 
 When the toolkit updates, target projects pull changes per domain. There is one catch-all and several targeted entry points.
 
+### Move the records first, once
+
+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:
+
+```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
+```
+
+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.
+
+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.
+
+A tracked file that names an old record path on purpose, such as prose dating a decision, keeps it by carrying `canon-keep-record-root` on that line or the one above. The report pass prints every file it would rewrite, which is where to catch one before `--write` runs.
+
+Until the move runs, the project is exposed. The shipped ignore set no longer names the old record paths, so a project holding records at `.claude/` stops ignoring them on its next `canon tooling sync`, and the first sign is a memory file or a task board appearing in a commit. Every command reads either root, so nothing else breaks in the meantime, and running the move is what closes it.
+
 ### Check first
 
 `canon sync --check <path>` reports what has drifted without writing anything. It splits each difference by cause, which is the question that decides what to do next.
@@ -142,7 +162,7 @@ Each domain holds its own toolkit commit, so syncing governance today does not m
 
 A project that has never synced under a toolkit new enough to write a stamp falls back to the toolkit's own git history. Installed content matching any version that history published proves the file untouched, so it reports `stale` naming the commit it came from, and content matching no published version stays `drifted`. That fallback needs the toolkit as a git checkout. Installed from the registry it ships source without history, and the report says attribution was unavailable rather than reading every file as a local edit.
 
-Further causes sit outside the per-domain scan, each naming something that walk cannot see. A seed the project edited is reported under `seeds` and reconciled with `canon:claude-seed-sync`, since no sync command touches a seed. A file a newer seed folder replaced is reported under `superseded`, such as `.claude/TASKS.md` against the `.claude/tasks/` that now ships, and nothing moves it because the content is the project's own. A domain sitting at the root layout with nothing under `.claude/` is reported under `unmigrated`, and no command moves it either. The project moves the content itself.
+Further causes sit outside the per-domain scan, each naming something that walk cannot see. A seed the project edited is reported under `seeds` and reconciled with `canon:claude-seed-sync`, since no sync command touches a seed. A file a newer seed folder replaced is reported under `superseded`, such as `.claude/TASKS.md` against the `.canon/tasks/` that now ships, and nothing moves it because the content is the project's own. A domain sitting at the root layout with nothing under `.claude/` is reported under `unmigrated`, and no command moves it either. The project moves the content itself.
 
 `unmigrated` currently names no domain, since standards and snippets are the two the toolkit ever installed at the project root and both closed their install channel. A target still holding a root `standards/` or `snippets/` folder from an older toolkit is carrying its own authoring surface now, not an unfinished install, and nothing proposes moving either.
 

package/docs/visual-design-workflow.md

@@ -22,7 +22,7 @@ Claude Code reads both and writes the implementation. Works for CLI tools, inter
 
 The toolkit seed in `tooling/claude/seeds/.claude/DESIGN.md` ships a token-table template with a starting set of roles, and `standards/design.md` carries the same tables under `## Template` with placeholder rows. The column headers are what the renderer parses, so they stay verbatim in either, while the rows and values are the project's own.
 
-The `canon:claude-design-extract` skill drafts the file, sourcing tokens from a project's existing prose and CLI UI surfaces, or proposing them from `.claude/REQUIREMENTS.md` and a `## Personality` paragraph when no UI code exists yet. `canon design render` writes an HTML plus CSS preview to `.claude/review/design/` for eyeballing the current system without leaving Claude Code. See `.claude/context/design.md`.
+The `canon:claude-design-extract` skill drafts the file, sourcing tokens from a project's existing prose and CLI UI surfaces, or proposing them from `.claude/REQUIREMENTS.md` and a `## Personality` paragraph when no UI code exists yet. `canon design render` writes an HTML plus CSS preview to `.canon/review/design/` for eyeballing the current system without leaving Claude Code. See `.claude/context/design.md`.
 
 A cell no source anchors ends in `? verify`, and the preview shows that marker beside the value rather than folding it in, so a swatch and a font sample stay built from the value alone. A confidence line above the sections names how many cells are anchored against how many are tagged, which is what tells a reader whether they are looking at a record of the code or a proposal about it. It reads the columns a source could anchor and leaves out the row names, so the ratio is not diluted by cells no tag could ever reach. The proposal path tags nearly all of them, so that count reads low on day one by design.
 

package/governance/rules/claude/555-tasks.md

@@ -1,7 +1,7 @@
 ---
-description: Route .claude/tasks/ edits to the tasks standard for filenames, frontmatter, and task file format
+description: Route .canon/tasks/ edits to the tasks standard for filenames, frontmatter, and task file format
 paths:
-  - '.claude/tasks/**'
+  - '.canon/tasks/**'
 ---
 
 # Tasks standards
@@ -9,4 +9,4 @@ paths:
 ## Authority
 
 - Follow the tasks standard for filenames, frontmatter, what belongs, and the task file format. It is the single source. Read it with `canon standards tasks`.
-- Never hand-edit `.claude/tasks/index.md`. A hook regenerates it from sibling frontmatter.
+- Never hand-edit `.canon/tasks/index.md`. A hook regenerates it from sibling frontmatter.

package/governance/rules/claude/556-groundwork.md

@@ -1,7 +1,7 @@
 ---
-description: Route .claude/groundwork/ edits to the groundwork standard for ordinal naming, numbering, frontmatter, and required file contents
+description: Route .canon/groundwork/ edits to the groundwork standard for ordinal naming, numbering, frontmatter, and required file contents
 paths:
-  - '.claude/groundwork/**'
+  - '.canon/groundwork/**'
 ---
 
 # Groundwork standards

package/governance/rules/claude/557-intake.md

@@ -1,7 +1,7 @@
 ---
-description: Route .claude/intake/ edits to the intake standard for the item format, the answer contract, and ordinal naming
+description: Route .canon/intake/ edits to the intake standard for the item format, the answer contract, and ordinal naming
 paths:
-  - '.claude/intake/**'
+  - '.canon/intake/**'
 ---
 
 # Intake standards

package/governance/rules/claude/558-plan.md

@@ -1,7 +1,7 @@
 ---
-description: Route .claude/plans/ edits to the plan standard for sections, the answer contract, and the archive move
+description: Route .canon/plans/ edits to the plan standard for sections, the answer contract, and the archive move
 paths:
-  - '.claude/plans/**'
+  - '.canon/plans/**'
 ---
 
 # Plan standards
@@ -14,7 +14,7 @@ paths:
 
 ## Archiving
 
-- Move a shipped plan to `.claude/plans/archive/`. Never delete one.
+- Move a shipped plan to `.canon/plans/archive/`. Never delete one.
 - Amend a plan in place when a decision changes. Do not append a second passage narrating the change.
 
 ## Authority

package/governance/rules/claude/559-memory.md

@@ -1,7 +1,7 @@
 ---
-description: Route .claude/memory/ edits to the memory standard for the filename, frontmatter, body shape, and lifecycle
+description: Route .canon/memory/ edits to the memory standard for the filename, frontmatter, body shape, and lifecycle
 paths:
-  - '.claude/memory/**'
+  - '.canon/memory/**'
 ---
 
 # Memory standards

package/governance/rules/claude/560-diagrams.md

@@ -1,7 +1,7 @@
 ---
-description: Route .claude/diagrams edits to the diagrams standard for Mermaid conventions
+description: Route .canon/diagrams edits to the diagrams standard for Mermaid conventions
 paths:
-  - '.claude/diagrams/**'
+  - '.canon/diagrams/**'
   - '.claude/DIAGRAMS.md'
 ---
 
@@ -14,5 +14,5 @@ paths:
 
 ## Scope
 
-- Write a new diagram to `.claude/diagrams/<kind>.md`, never to `.claude/DIAGRAMS.md`
+- Write a new diagram to `.canon/diagrams/<kind>.md`, never to `.claude/DIAGRAMS.md`
 - Convert a `.claude/DIAGRAMS.md` left by an older install into per-kind entries before editing it

package/governance/rules/claude/561-teach.md

@@ -1,7 +1,7 @@
 ---
-description: Route .claude/teach/ edits to the teach standard for layout, ordinal naming, and the mission and record formats, in the projects that open a learning workspace
+description: Route .canon/teach/ edits to the teach standard for layout, ordinal naming, and the mission and record formats, in the projects that open a learning workspace
 paths:
-  - '.claude/teach/**'
+  - '.canon/teach/**'
 ---
 
 # Teach standards

package/governance/rules/claude/562-session.md

@@ -1,7 +1,7 @@
 ---
-description: Route .claude/tasks/ session map edits to the session standard for the filename, the core sections, and what a handoff carries
+description: Route .canon/tasks/ session map edits to the session standard for the filename, the core sections, and what a handoff carries
 paths:
-  - '.claude/tasks/session-*.md'
+  - '.canon/tasks/session-*.md'
 ---
 
 # Session map standards

package/governance/rules/core/035-tasks.md

@@ -6,8 +6,8 @@ description: Scope, size, and link a task file correctly
 
 ## Task files
 
-- `.claude/tasks/` is gitignored local session scratch, one file per task. Edit freely. No staging or revert before commits.
+- `.canon/tasks/` is gitignored local session scratch, one file per task. Edit freely. No staging or revert before commits.
 - Only create a task for work that spans multiple sessions or has real dependencies. Handle small edits immediately without a task entry.
 - Do not add tasks retroactively for work already completed. Completed work is visible in git.
-- When a task needs execution detail beyond its own file, create a plan in `.claude/plans/` and link to it from the task's intro paragraph. When that task ships, move its plan file to `.claude/plans/archive/`. Never delete it.
+- When a task needs execution detail beyond its own file, create a plan in `.canon/plans/` and link to it from the task's intro paragraph. When that task ships, move its plan file to `.canon/plans/archive/`. Never delete it.
 - Write the plan in the same session as the task file. The session that executes the plan later inherits reasoning context it would otherwise have to re-derive.

package/governance/rules/core/045-memory.md

@@ -1,12 +1,12 @@
 ---
-description: Keep memory writes scoped to .claude/memory/ and out of context-owned domains
+description: Keep memory writes scoped to .canon/memory/ and out of context-owned domains
 ---
 
 # Memory standards
 
 ## Writing memory
 
-- Write all memory files to `.claude/memory/`, not `~/.claude/projects/`
+- Write all memory files to `.canon/memory/`, not `~/.claude/projects/`
 - A fact about a domain goes to that domain's `.claude/context/` entry, not to memory. `canon:claude-memory-capture` routes it there and `canon:claude-docs` folds it in. Memory keeps only what no context entry owns. Report it rather than proceeding silently when either skill does not resolve. Both ship with the plugin and this rule ships with the CLI, so a project that installed governance alone does not have them.
-- Never delete a memory entry. Retire one by moving it to `.claude/.tmp/memory-archive/`. A bulk retire runs through the shell, where no file edit fires a path-scoped rule, and the folder is gitignored with nothing to recover from.
+- Never delete a memory entry. Retire one by moving it to `.canon/tmp/memory-archive/`. A bulk retire runs through the shell, where no file edit fires a path-scoped rule, and the folder is gitignored with nothing to recover from.
 - Follow the memory standard for the filename and type prefix, the frontmatter, the body shape each type carries, and the lifecycle. Read it with `canon standards memory`. Check every entry in the pen against that standard and fix what breaks it, since nothing keeps the folder conforming on its own.

package/governance/rules/core/055-scratch.md

@@ -6,4 +6,5 @@ description: Write temporary files to the scratch folder structure
 
 ## Temporary files
 
-- Write temporary files to `.claude/.tmp/<slug>/<file>.md` in the project root, a nested `<slug>/` folder with a kebab-slug tied to the topic, not a flat `<slug>-<file>.md`. The scratch-guard hook enforces the location.
+- Write temporary files to `.canon/tmp/<slug>/<file>.md` in the project root, a nested `<slug>/` folder with a kebab-slug tied to the topic, not a flat `<slug>-<file>.md`. The scratch-guard hook enforces the location.
+- Write to `.claude/.tmp/<slug>/` instead in a project that carries no `.canon/` root, which is one the record move has not reached. The hook accepts either, and `canon migrate records` is what moves a project from the first spelling to the second. <!-- canon-keep-record-root -->

package/governance/rules/core/085-worktrees.md

@@ -10,7 +10,7 @@ description: Route tracked-file writes and shared session scratch correctly from
 
 ## Shared session scratch
 
-- Shared session scratch (`.claude/plans/`, `.claude/review/`, `.claude/memory/`, `.claude/tasks/`) lives at the main worktree root, not inside a linked worktree. From a linked worktree, resolve these paths against the main root via `git worktree list --porcelain | grep -m 1 '^worktree ' | cut -d' ' -f2-`. Fall back to `pwd` if not a git repo.
+- Shared session scratch (`.canon/plans/`, `.canon/review/`, `.canon/memory/`, `.canon/tasks/`) lives at the main worktree root, not inside a linked worktree. From a linked worktree, resolve these paths against the main root via `git worktree list --porcelain | grep -m 1 '^worktree ' | cut -d' ' -f2-`. Fall back to `pwd` if not a git repo.
 - From a linked worktree, every `Edit` or `Write` to a tracked file (source, docs) must use a path starting with `pwd`.
 - From a linked worktree, `Edit` and `Write` are refused for every main-root path, session scratch included. The refusal names session isolation and points at the worktree copy, which is a second gitignored file no later session reads, so never take that redirect.
 - `Read` resolves against the main root normally from a linked worktree. A main-root write reaches it only through `Bash`, as one plain command rather than a compound one, which is refused for complexity.

package/package.json

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

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

@@ -9,22 +9,22 @@ GITIGNORE="$PROJECT_ROOT/.gitignore"
 MANIFEST="$PROJECT_ROOT/tooling/claude/manifest.toml"
 SECTION="# Claude"
 
-# Divergences this repository has decided to keep, one `<entry>|<reason>` per
-# line, matched after the trailing slash is stripped. Each names a path the
-# enclosing repository ignores and the claude manifest deliberately does not
-# ship, so a target keeps tracking it.
+# Parity is exact, with no exception list behind it, and the move to `.canon/`
+# is what removed the one there was. Its two members each named a path inside
+# `.claude/` that this repository ignored and the manifest withheld, so a target
+# kept tracking it. A single root entry can withhold nothing inside itself: git
+# does not descend into an excluded directory, so a re-inclusion like
+# `!.canon/diagrams/` matches nothing. Retiring both is what buys the one line.
 #
-# This is the canonical list. `.gitignore` and the manifest carry a pointer
-# beside their own entries rather than a second copy of the reason, and
-# `.claude/context/tooling.md` carries the narrative behind both.
+# The diagrams divergence is the one that cost something. A target used to track
+# its diagrams and keep the context audit's default coverage of them, and it now
+# ignores them with the rest of its records, so that coverage is gone unless the
+# project names the folder itself. `.claude/context/tooling.md` carries the
+# narrative.
 #
-# A sanction that no longer describes a divergence fails the same as an
-# unsanctioned one. An exception outliving its reason is what teaches the next
-# reader to widen the list rather than to read it.
-SANCTIONED=(
-  ".claude/diagrams|a target that tracks its diagrams keeps the context audit's default coverage of them, which ignoring the folder for every target would take away. This repository backs the folder through its records remote instead."
-  ".claude/README.md|the landing page a records pull writes back into a repository that set up a records remote. A target has not, so it never receives the file."
-)
+# An exception mechanism is not kept against a future divergence, because an
+# empty one cannot be exercised and a check nobody can test is a check nobody
+# should trust. It comes back with its first real member or not at all.
 
 if [ ! -f "$GITIGNORE" ]; then
   echo "No .gitignore at ${GITIGNORE#"$PROJECT_ROOT/"}, ignore parity unverifiable." >&2
@@ -38,15 +38,15 @@ fi
 
 # A gitignore pattern and a manifest entry describe the same folder whether or
 # not either spells the trailing slash, so presence is compared with it dropped.
-# `.claude/.tmp` and `.claude/.tmp/` are the live instance of that pair.
+# No live pair differs that way now that both lists carry the same two entries,
+# and the normalization stays because either side may be written without one.
 normalize() {
   printf '%s\n' "${1%/}"
 }
 
 # Every pattern the file carries, comments and blank lines dropped. The whole
-# file rather than one header, because `.claude/teach/` sits under a header of
-# its own and reading the `# Claude` header alone would report it missing from a
-# list that carries it.
+# file rather than one header, since a claude-scoped entry filed under a header
+# of its own would otherwise read as missing from a list that carries it.
 gitignore_patterns() {
   awk '{ sub(/[[:space:]]+$/, "") } $0 ~ /^[[:space:]]*#/ || $0 == "" { next } { print }' "$GITIGNORE"
 }
@@ -106,7 +106,6 @@ if [ ${#shipped[@]} -eq 0 ]; then
 fi
 
 failures=""
-sanction_notes=""
 
 # Entries the manifest ships that this repository does not ignore. A target is
 # told to ignore a folder the toolkit itself tracks, which no decision sanctions,
@@ -121,48 +120,22 @@ done
 # 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.
+# covering a whole tree where `.claude/` names a folder 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/* | .canon | .canon/*) ;;
   *) continue ;;
   esac
   contains "$pattern" "${shipped[@]}" && continue
-
-  matched=false
-  for sanction in "${SANCTIONED[@]}"; do
-    [ "${sanction%%|*}" = "$pattern" ] || continue
-    matched=true
-    sanction_notes="$sanction_notes  $pattern stays out of the manifest: ${sanction#*|}"$'\n'
-    break
-  done
-
-  if [ "$matched" = false ]; then
-    failures="$failures  $pattern is ignored here and absent from the manifest"$'\n'
-  fi
-done
-
-# A sanction naming a path that is no longer divergent, either because the
-# manifest took it or because .gitignore dropped it.
-for sanction in "${SANCTIONED[@]}"; do
-  entry="${sanction%%|*}"
-  if contains "$entry" "${ignored[@]}" && ! contains "$entry" "${shipped[@]}"; then
-    continue
-  fi
-  failures="$failures  $entry is sanctioned as a divergence and is no longer one"$'\n'
+  failures="$failures  $pattern is ignored here and absent from the manifest"$'\n'
 done
 
 if [ -n "$failures" ]; then
   echo "The ignore set a target receives disagrees with this repository's own:" >&2
   printf '%s' "$failures" >&2
-  echo "Add the entry to the \"$SECTION\" array in ${MANIFEST#"$PROJECT_ROOT/"} and to .gitignore, or record it in SANCTIONED in scripts/core/check-ignore-parity.sh with the reason it stays apart." >&2
+  echo "Add the entry to the \"$SECTION\" array in ${MANIFEST#"$PROJECT_ROOT/"} and to .gitignore. The two lists are compared exactly, and nothing here records an exception." >&2
   exit 1
 fi
-
-if [ -n "$sanction_notes" ]; then
-  echo "Sanctioned divergences from the ignore set a target receives:"
-  printf '%s' "$sanction_notes"
-fi

package/scripts/core/install-check.sh

@@ -7,7 +7,7 @@ PROJECT_ROOT="${PROJECT_ROOT:-$(cd "$SCRIPT_DIR/../.." && pwd)}"
 
 source "$PROJECT_ROOT/scripts/lib/ui.sh"
 
-TMP_ROOT="$PROJECT_ROOT/.claude/.tmp/install-check"
+TMP_ROOT="$PROJECT_ROOT/.canon/tmp/install-check"
 CLONE_DIR="$TMP_ROOT/clone"
 TARGET_DIR="$TMP_ROOT/target"
 KEEP=0
@@ -20,10 +20,10 @@ for arg in "$@"; do
 Usage: scripts/core/install-check.sh [--keep]
 
 Verifies the README install path end to end:
-  1. Clones this repo into .claude/.tmp/install-check/clone
+  1. Clones this repo into .canon/tmp/install-check/clone
   2. Runs bun install in the clone
   3. Runs the CLI with --help to confirm it executes
-  4. Scaffolds a fresh project in .claude/.tmp/install-check/target
+  4. Scaffolds a fresh project in .canon/tmp/install-check/target
   5. Runs canon init and asserts a scaffold landed
 
 Flags:
@@ -83,7 +83,7 @@ log_step "Assert scaffold"
 # `@`-reference convention rule is the one snippets-domain file that still
 # installs, since `base` carries `governance/rules/snippets/` as a
 # folder-whole entry the same way it does `core` and `claude`.
-for path in "CLAUDE.md" ".claude/wiki/index.md" ".claude" ".claude/context/index.md" ".claude/wireframes/index.md" ".claude/diagrams/index.md" \
+for path in "CLAUDE.md" ".claude/wiki/index.md" ".claude" ".claude/context/index.md" ".claude/wireframes/index.md" ".canon/diagrams/index.md" \
   ".prettierrc" ".editorconfig" ".lintstagedrc" ".husky/pre-commit" ".github/workflows/verify.yml" "scripts/verify.sh" \
   ".claude/rules/core/000-constitution.md" ".claude/rules/snippets/505-at-references.md"; do
   if [ ! -e "$TARGET_DIR/$path" ]; then

package/scripts/core/snapshot.sh

@@ -10,7 +10,7 @@ source "$PROJECT_ROOT/scripts/lib/ui.sh"
 
 NESTED="${VERIFY_NESTED:-false}"
 
-OUTPUT_FILE=".claude/.tmp/project/PROJECT-SNAPSHOT.md"
+OUTPUT_FILE=".canon/tmp/project/PROJECT-SNAPSHOT.md"
 
 check_dependencies() {
   command -v find >/dev/null 2>&1 || log_error "find not installed"

package/scripts/manage-sandbox.sh

@@ -163,7 +163,7 @@ init_empty_sandbox() {
   mkdir -p "$SANDBOX"
 
   cat <<EOF >"$SANDBOX/.gitignore"
-.claude/.tmp/
+.canon/tmp/
 node_modules
 EOF
   (