@erclx/canon 4.6.1 → 4.7.0

package/src/sync/layout.ts

@@ -1,6 +1,7 @@
 import { existsSync, statSync } from 'node:fs'
 import { basename, join } from 'node:path'
 import { SUBDIRS } from '@/claude/seeds'
+import { creationRel, isRecordEntry } from '@/record-root'
 import type { StampDomain } from '@/sync/stamp'
 
 const CLAUDE_DIR = '.claude'
@@ -52,7 +53,7 @@ export interface UnmigratedDomain {
 /**
  * Pairs each seed subdirectory against an uppercase-stem sibling in the target,
  * so a project still holding `.claude/TASKS.md` is reported against the
- * `.claude/tasks/` folder that replaced it.
+ * `.canon/tasks/` folder that replaced it.
  *
  * Deriving from the seed tree rather than from a fixed list means a folder
  * added later is covered without editing this file. The cost is that only an
@@ -66,7 +67,15 @@ export function collectSuperseded(target: string): SupersededEntry[] {
     const rel = join(CLAUDE_DIR, `${subdir.toUpperCase()}.md`)
     if (!isFile(join(target, rel))) continue
 
-    entries.push({ rel, replacedBy: join(CLAUDE_DIR, subdir) })
+    // A record subdir now lives under the record root, so the replacement this
+    // names is resolved against the target rather than fixed at `.claude/`.
+    // Naming a folder the target does not have sends a person to migrate their
+    // legacy file into a path nothing reads.
+    const replacedBy = isRecordEntry(subdir)
+      ? creationRel(target, subdir)
+      : join(CLAUDE_DIR, subdir)
+
+    entries.push({ rel, replacedBy })
   }
 
   return entries

package/src/tasks/answers.ts

@@ -56,7 +56,7 @@ export type AnswersOutcome = PlanAnswers | AnswersRefused
  * project root and against the board directory both.
  *
  * The second base is the one a dispatcher actually has to hand. A board row
- * writes its `Plan:` link relative to `.claude/tasks/`, so the href reads
+ * writes its `Plan:` link relative to `.canon/tasks/`, so the href reads
  * `../plans/feature-<slug>.md`, and resolving that against the root alone lands
  * a directory above the repository and refuses a plan that exists.
  *

package/src/tasks/archive.ts

@@ -184,7 +184,7 @@ function isRowFor(line: string, target: string): boolean {
 /**
  * Resolves the `Plan:` target against the board and against the project root
  * both, which is how `claude-docs` reads the same line. It accepts `../plans/x.md`
- * and `.claude/plans/x.md` as one file, so a gate reading only the first form
+ * and `.canon/plans/x.md` as one file, so a gate reading only the first form
  * would pass the second and strand the plan this exists to protect.
  *
  * The resolved path is returned rather than a boolean, because the citation
@@ -213,11 +213,28 @@ export function resolveLivePlan(
   const fromBoard = resolve(dir, target)
   const fromRoot = resolve(root, target)
 
-  if (live(fromBoard)) return fromBoard
-  if (live(fromRoot)) return fromRoot
+  if (live(fromBoard)) return atOneRoot(fromBoard, plans, root)
+  if (live(fromRoot)) return atOneRoot(fromRoot, plans, root)
   return undefined
 }
 
+/**
+ * Restates a live plan path at the root this tree actually resolves, so two
+ * tasks naming one plan through different roots compare equal.
+ *
+ * Callers compare the return of `resolveLivePlan` by string. Both roots are
+ * accepted above, so without this a task citing `.canon/plans/x.md` and one
+ * citing `.canon/plans/x.md` name one file and read as two, which counts a
+ * sibling's citation as absent and refuses the archive it should allow.
+ */
+function atOneRoot(path: string, plans: string[], root: string): string {
+  const at = plans.find((dir) => isUnder(path, dir))
+
+  return at === undefined
+    ? path
+    : join(recordDir(root, PLANS), relative(at, path))
+}
+
 /**
  * Names the other live tasks whose `Plan:` line lands on the same file. This is
  * the rule `claude-docs` applies before it archives a plan, held here so one

package/standards/diagrams.md

@@ -1,17 +1,17 @@
 ---
 title: Diagram reference
-description: Shape and content rules for .claude/diagrams/<kind>.md files
+description: Shape and content rules for .canon/diagrams/<kind>.md files
 ---
 
 # Diagram reference
 
-Applies to per-kind entries under `.claude/diagrams/`. Skip for `index.md`, which is regenerated by `canon indexes regen`.
+Applies to per-kind entries under `.canon/diagrams/`. Skip for `index.md`, which is regenerated by `canon indexes regen`.
 
 A diagram entry answers one question about the system with one or more Mermaid diagrams and the prose that makes them readable. It is not a rendering of the file tree. The check for any single line: does it tell a reader something the code layout would not have told them? If not, it belongs in `.claude/context/`.
 
 ## Scope
 
-Governs per-kind diagram entries under `.claude/diagrams/`: which question each answers, the Mermaid source, the accessibility fields, and the explanation prose beneath. It states the voice for that prose, which is the yield the `write-human` skill grants a surface whose own standard sets one.
+Governs per-kind diagram entries under `.canon/diagrams/`: which question each answers, the Mermaid source, the accessibility fields, and the explanation prose beneath. It states the voice for that prose, which is the yield the `write-human` skill grants a surface whose own standard sets one.
 
 Does not govern:
 
@@ -39,7 +39,7 @@ An entry that fails these is non-conforming regardless of whether it satisfies e
 - `verified` (required): the short commit SHA an entry was last checked against and the ISO date of that check, separated by a space (`73e9a3f8 2026-08-02`). A stub nobody has drawn yet carries the literal `TODO: never verified` instead, which is the one other accepted value.
 - `stale` (optional): one line naming what changed under the entry since that check. Nothing writes it on its own, so it sits on an entry because a reader put it there and is absent everywhere else.
 
-The first three feed `.claude/diagrams/index.md` when regenerated. The catalog sorts categories alphabetically rather than in narrative order, so an entry cannot rely on its position to introduce another. Each entry names its own starting point, and the catalog's subtitle routes a first-time reader to the system context entry.
+The first three feed `.canon/diagrams/index.md` when regenerated. The catalog sorts categories alphabetically rather than in narrative order, so an entry cannot rely on its position to introduce another. Each entry names its own starting point, and the catalog's subtitle routes a first-time reader to the system context entry.
 
 The marker fields reach the catalog through neither route. `canon indexes regen` reads `title`, `description`, and `category` and ignores every other key, so a marker changes no generated file. A reader picks it up by opening the entry, which is where it sits above the diagram and where anyone deciding whether to trust the picture is already standing.
 

package/standards/glossary.md

@@ -9,7 +9,7 @@ Applies to a glossary, the file holding one entry per term a body of material de
 
 ## Scope
 
-Governs a glossary at `.claude/teach/<nn>-<topic>/GLOSSARY.md` and at whatever path a surface fixes for one it holds: its frontmatter, entry shape, ordering, grouping, and the rules deciding which terms it carries.
+Governs a glossary at `.canon/teach/<nn>-<topic>/GLOSSARY.md` and at whatever path a surface fixes for one it holds: its frontmatter, entry shape, ordering, grouping, and the rules deciding which terms it carries.
 
 Does not govern:
 

package/standards/groundwork.md

@@ -5,13 +5,13 @@ description: Folder layout, ordinal naming, reserved numbering, frontmatter and
 
 # Groundwork reference
 
-Applies to a groundwork track at `.claude/groundwork/<nn>-<slug>/`. A track measures one question that has to be settled before anyone can plan against it. The numbering inside the folder is the table of contents, so a reader opens the folder and knows where to start and what follows without an index maintained inside each file.
+Applies to a groundwork track at `.canon/groundwork/<nn>-<slug>/`. A track measures one question that has to be settled before anyone can plan against it. The numbering inside the folder is the table of contents, so a reader opens the folder and knows where to start and what follows without an index maintained inside each file.
 
 The folder is gitignored and unbacked. No check reaches its contents and no history recovers a deleted one, so every rule here holds only while a session reads it, and the handoff file has to be self-contained.
 
 ## Scope
 
-Governs a groundwork track under `.claude/groundwork/<nn>-<slug>/`: folder layout, ordinal naming, reserved numbering, frontmatter and dating, what each required file holds, and the conventions a track keeps.
+Governs a groundwork track under `.canon/groundwork/<nn>-<slug>/`: folder layout, ordinal naming, reserved numbering, frontmatter and dating, what each required file holds, and the conventions a track keeps.
 
 Does not govern:
 
@@ -25,7 +25,7 @@ Does not govern:
 ## Folder name
 
 - Name the folder `<nn>-<slug>`, a two-digit zero-padded ordinal followed by a kebab-case slug.
-- Take the ordinal from the highest one already present across both `.claude/groundwork/` and `.claude/intake/`, incremented. A listing then sorts by when each folder opened rather than alphabetically, and the count includes both kinds because the two share one creation-order line.
+- Take the ordinal from the highest one already present across both `.canon/groundwork/` and `.canon/intake/`, incremented. A listing then sorts by when each folder opened rather than alphabetically, and the count includes both kinds because the two share one creation-order line.
 - With neither folder holding an entry, the first one opened takes `01`. Do not read this off the numbering inside a track, which starts at `00` on a large one and disagrees with intake's own first file.
 - Never renumber an existing folder. The ordinal is the order it opened, and a later reader cites it by that name.
 

package/standards/index.md

@@ -12,7 +12,7 @@ Reference docs for consistent authoring across the toolkit and target projects.
 - [Commit reference](commit.md): Commit message format and type conventions
 - [Context entry reference](context.md): Shape and content rules for .claude/context/<domain>.md entries
 - [Design reference](design.md): Shape and content rules for .claude/DESIGN.md
-- [Diagram reference](diagrams.md): Shape and content rules for .claude/diagrams/<kind>.md files
+- [Diagram reference](diagrams.md): Shape and content rules for .canon/diagrams/<kind>.md files
 - [Glossary reference](glossary.md): Frontmatter, entry shape, ordering, and the rules deciding which terms a glossary carries
 - [Groundwork reference](groundwork.md): Folder layout, ordinal naming, reserved numbering, frontmatter and dating, required file contents, and conventions for a measurement track
 - [Intake reference](intake.md): Folder layout, ordinal naming, reserved index number, frontmatter and dating, the item template, the answer contract, and retrieval
@@ -30,7 +30,7 @@ Reference docs for consistent authoring across the toolkit and target projects.
 - [Slug reference](slug.md): Transform from a git branch name to a slug, and the three responses to an empty result
 - [Snippet reference](snippets.md): Snippet reference and authoring conventions
 - [Standard reference](standard.md): Shape and content rules for authoring a standard
-- [Tasks reference](tasks.md): Folder layout, filename convention, readiness groups, and content rules for .claude/tasks/
+- [Tasks reference](tasks.md): Folder layout, filename convention, readiness groups, and content rules for .canon/tasks/
 - [Teach reference](teach.md): Workspace layout, ordinal naming, frontmatter, and the mission and learning-record formats for a learning workspace
 - [Versioning reference](versioning.md): Phase label vs semver discipline across tasks, PRs, reviews, issues, commits, and tags
 - [Wireframe reference](wireframes.md): Shape and content rules for .claude/wireframes/<surface>.md files

package/standards/intake.md

@@ -5,13 +5,13 @@ description: Folder layout, ordinal naming, reserved index number, frontmatter a
 
 # Intake reference
 
-Applies to an intake folder at `.claude/intake/<nn>-<slug>/`. One folder holds one dump, filed by domain, and every finding in it is an item carrying a measured problem, one proposed fix, and a verdict.
+Applies to an intake folder at `.canon/intake/<nn>-<slug>/`. One folder holds one dump, filed by domain, and every finding in it is an item carrying a measured problem, one proposed fix, and a verdict.
 
 The folder is gitignored and unbacked. No check reaches its contents, so the shape below survives only by being read.
 
 ## Scope
 
-Governs an intake folder under `.claude/intake/<nn>-<slug>/`: folder layout, ordinal naming, the reserved index number, frontmatter and dating, the item format, the answer contract, and retrieval.
+Governs an intake folder under `.canon/intake/<nn>-<slug>/`: folder layout, ordinal naming, the reserved index number, frontmatter and dating, the item format, the answer contract, and retrieval.
 
 Does not govern:
 
@@ -25,7 +25,7 @@ Does not govern:
 ## Folder name
 
 - Name the folder `<nn>-<slug>`, a two-digit zero-padded ordinal followed by a kebab-case slug. This is the folder's own ordinal, distinct from the `NN-<domain>.md` numbering a cluster file carries inside it.
-- Take the ordinal from the highest one already present across both `.claude/intake/` and `.claude/groundwork/`, incremented. A listing then sorts by when each folder opened rather than alphabetically, and the count includes both kinds because the two share one creation-order line.
+- Take the ordinal from the highest one already present across both `.canon/intake/` and `.canon/groundwork/`, incremented. A listing then sorts by when each folder opened rather than alphabetically, and the count includes both kinds because the two share one creation-order line.
 - With neither folder holding an entry, the first one opened takes `01`. Do not read this off the numbering inside a dump, which starts at `00` and disagrees with groundwork's own first required file.
 - Never renumber an existing folder. The ordinal is the order it opened, and a later reader cites it by that name.
 

package/standards/memory.md

@@ -5,13 +5,13 @@ description: Filename and type prefix, frontmatter, the body shape per type, lin
 
 # Memory reference
 
-Applies to a memory entry at `.claude/memory/<type>-<slug>.md`. One file holds one rule or one fact, written at the end of the session that produced it and read by a session that holds none of it. Which surface owns a given fact is settled before an entry is written at all, and that routing is project policy rather than a shape rule.
+Applies to a memory entry at `.canon/memory/<type>-<slug>.md`. One file holds one rule or one fact, written at the end of the session that produced it and read by a session that holds none of it. Which surface owns a given fact is settled before an entry is written at all, and that routing is project policy rather than a shape rule.
 
 The folder is gitignored and unbacked. Nothing recovers a deleted entry, which is why the retire step below is a move rather than a cleanup.
 
 ## Scope
 
-Governs a memory entry under `.claude/memory/<type>-<slug>.md`: the filename and its type prefix, the frontmatter, the body shape each type carries, links between entries, and the lifecycle from the first write to retirement.
+Governs a memory entry under `.canon/memory/<type>-<slug>.md`: the filename and its type prefix, the frontmatter, the body shape each type carries, links between entries, and the lifecycle from the first write to retirement.
 
 Does not govern:
 

package/standards/plan.md

@@ -5,13 +5,13 @@ description: Filename and slug, required sections, the suggested-and-answer cont
 
 # Plan reference
 
-Applies to a feature plan at `.claude/plans/feature-<slug>.md`. One file holds one concern, written before implementation starts and read by whatever executes it, so it has to carry the scope without the conversation that produced it.
+Applies to a feature plan at `.canon/plans/feature-<slug>.md`. One file holds one concern, written before implementation starts and read by whatever executes it, so it has to carry the scope without the conversation that produced it.
 
 The folder is gitignored and unbacked. Nothing recovers a deleted plan, which is why the archive step below is a move rather than a cleanup.
 
 ## Scope
 
-Governs a feature plan under `.claude/plans/feature-<slug>.md`: the filename, the required sections, what each holds, the suggested-and-answer contract, and the lifecycle from the live folder to the archive.
+Governs a feature plan under `.canon/plans/feature-<slug>.md`: the filename, the required sections, what each holds, the suggested-and-answer contract, and the lifecycle from the live folder to the archive.
 
 Does not govern:
 
@@ -124,7 +124,7 @@ This contract inverts the one an intake folder keeps, where an empty slot means
 - Write the plan before implementation starts, and treat it as the scope of the run that executes it.
 - Keep every plan at one root. A plan copied into each parallel working tree forks, and the copies answer the same question differently.
 - Amend the plan in place when a decision changes mid-flight. Do not append a second passage narrating the change, which leaves a reader to work out which of two answers is current. An execution-time deviation from a suggestion is one such amendment, and the contract above fixes which line takes it.
-- Move the plan to `.claude/plans/archive/` when the work it describes ships. Never delete it, because the plan is where the rejected alternative is written down and nothing else records it. The archive nests inside `.claude/plans/` rather than sitting beside it as `.claude/plans-archive/`, so an older layout is a flat sibling by that name and a current one is not.
+- Move the plan to `.canon/plans/archive/` when the work it describes ships. Never delete it, because the plan is where the rejected alternative is written down and nothing else records it. The archive nests inside `.canon/plans/` rather than sitting beside it as `.claude/plans-archive/`, so an older layout is a flat sibling by that name and a current one is not.
 - Write the plan in the same session that opens the task it serves. The session executing it later inherits reasoning it would otherwise re-derive.
 
 ## Anti-patterns

package/standards/session.md

@@ -5,13 +5,13 @@ description: Filename and location, the sections a handoff carries, the write an
 
 # Session map reference
 
-Applies to `.claude/tasks/session-<slug>.md`. A session writes one before a compaction, because a compaction keeps conclusions and drops the reasoning that produced them. It is rewritten whenever the session that owns it learns something the next session would otherwise re-derive, and it is optional: a project whose sessions never approach a compaction carries none.
+Applies to `.canon/tasks/session-<slug>.md`. A session writes one before a compaction, because a compaction keeps conclusions and drops the reasoning that produced them. It is rewritten whenever the session that owns it learns something the next session would otherwise re-derive, and it is optional: a project whose sessions never approach a compaction carries none.
 
 Any session writes one. The role a session holds decides which sections it adds on top of the core, never whether it may write at all.
 
 ## Scope
 
-Governs the pre-compaction handoff at `.claude/tasks/session-<slug>.md`: its filename, its sections, what a writer puts in each, and how a reader picks one up.
+Governs the pre-compaction handoff at `.canon/tasks/session-<slug>.md`: its filename, its sections, what a writer puts in each, and how a reader picks one up.
 
 Does not govern:
 

package/standards/standard.md

@@ -48,7 +48,7 @@ A standard failing these questions is non-conforming even when it satisfies ever
 
 ### Naming the file
 
-- Name the file for the artifact the scope statement governs, taking the word from the deepest path segment that names the artifact rather than the folder holding it. `plan.md` over `.claude/plans/feature-<slug>.md` and `session.md` over `.claude/tasks/session-<slug>.md` both follow it.
+- Name the file for the artifact the scope statement governs, taking the word from the deepest path segment that names the artifact rather than the folder holding it. `plan.md` over `.canon/plans/feature-<slug>.md` and `session.md` over `.canon/tasks/session-<slug>.md` both follow it.
 - Take the singular or the plural of that word, whichever reads as the artifact. A standard over one document takes the singular, and one over a set may take either.
 - Name an attribute standard for the attribute itself, since it governs no path to derive a word from.
 - Write the derived word alone. A standard installs as a sibling and is cited by bare filename, so a qualifier makes an outlier that every later citation has to carry.

package/standards/tasks.md

@@ -1,11 +1,11 @@
 ---
 title: Tasks reference
-description: Folder layout, filename convention, readiness groups, and content rules for .claude/tasks/
+description: Folder layout, filename convention, readiness groups, and content rules for .canon/tasks/
 ---
 
 # Tasks reference
 
-Applies to `.claude/tasks/`. Tracks what is being built and why, at the level of features and outcomes. One file per task.
+Applies to `.canon/tasks/`. Tracks what is being built and why, at the level of features and outcomes. One file per task.
 
 Update when a task starts, completes, or changes scope. When to open a task at all is project policy, not a shape rule, and lives in `CLAUDE.md`.
 
@@ -13,7 +13,7 @@ The folder is gitignored. Board state changes when work ships rather than when a
 
 ## Scope
 
-Governs the task board under `.claude/tasks/`: folder layout, filenames, frontmatter, file format, origin lines, execution ordering, the backlog beside it, and archiving.
+Governs the task board under `.canon/tasks/`: folder layout, filenames, frontmatter, file format, origin lines, execution ordering, the backlog beside it, and archiving.
 
 Does not govern:
 
@@ -26,7 +26,7 @@ Does not govern:
 ## Layout
 
 ```plaintext
-.claude/tasks/
+.canon/tasks/
 ├── index.md              ← generated, never hand-edited
 ├── priority.md           ← hand-maintained execution order
 ├── backlog.md            ← unordered, what is not being scheduled
@@ -205,13 +205,13 @@ A task with no origin is either lost context or work nobody decided to do. The i
 
 An intake folder answers that direction at folder scope rather than item scope, since one dump dispositions many items and most close without ever becoming a task. What names a folder is every item answered and no task citing it, on the board or in the archive. That is a dump nobody acted on. Counting the archive beside the board is what separates it from one already promoted and shipped, and a check reading the board alone calls every finished folder abandoned.
 
-`Plan:`, `Groundwork:`, and `Intake:` name their target as a markdown link whose text is the file or folder stem, so the line resolves on a ctrl-click the way `priority.md` rows already do. Write the path relative to `.claude/tasks/`, which makes it `../plans/`, `../groundwork/`, and `../intake/`. A path written from the project root renders as a link and resolves to nothing in an editor rooted at the project. `Issue:` stays a bare `#NNN`, since an issue number is not a path and a full URL would write the remote into a gitignored file.
+`Plan:`, `Groundwork:`, and `Intake:` name their target as a markdown link whose text is the file or folder stem, so the line resolves on a ctrl-click the way `priority.md` rows already do. Write the path relative to `.canon/tasks/`, which makes it `../plans/`, `../groundwork/`, and `../intake/`. A path written from the project root renders as a link and resolves to nothing in an editor rooted at the project. `Issue:` stays a bare `#NNN`, since an issue number is not a path and a full URL would write the remote into a gitignored file.
 
 Phase-label format and where labels may appear are governed by `standards/versioning.md`.
 
 `Plan:` points at `../plans/feature-<slug>.md` while the task is open. Once the task ships and the plan is archived, it points at `../plans/archive/feature-<slug>.md`, and at `../../plans/archive/feature-<slug>.md` once the task itself is archived a folder deeper. Retarget both halves of the link rather than dropping it, so a completed task still leads to the reasoning behind it.
 
-A project that archived plans before the folder nested under `.claude/plans/` holds closed tasks pointing at `../plans-archive/`, or at `../.tmp/plans-archive/` from before the durable records left the scratch tree. Each form resolves against the files it names, so leave those pointers where they are. A named route now moves the folder and retargets its pointers together, but no automation runs it, so an unmigrated project keeps holding the old spelling until someone does, and a task retargeted without its plan moving leads nowhere.
+A project that archived plans before the folder nested under `.canon/plans/` holds closed tasks pointing at `../plans-archive/`, or at `../.tmp/plans-archive/` from before the durable records left the scratch tree. Each form resolves against the files it names, so leave those pointers where they are. A named route now moves the folder and retargets its pointers together, but no automation runs it, so an unmigrated project keeps holding the old spelling until someone does, and a task retargeted without its plan moving leads nowhere.
 
 One plan per task. A plan cited by two tasks is a misfile rather than a shape to design for, which is why the sweep counts citations before archiving: the count is a guard against the misfile stranding a pointer, not support for the shape.
 
@@ -241,11 +241,11 @@ The line is what lets a merge close its own task. Every merge on `main` is a squ
 
 ## Archiving
 
-Never delete a task file. A shipped task moves to `.claude/tasks/archive/` under its own name, and the live index regenerates without it. `canon tasks archive` owns that move, and what it does and what it refuses on are at `docs/agents/tasks.md`.
+Never delete a task file. A shipped task moves to `.canon/tasks/archive/` under its own name, and the live index regenerates without it. `canon tasks archive` owns that move, and what it does and what it refuses on are at `docs/agents/tasks.md`.
 
-The archive nests inside `.claude/tasks/` rather than sitting beside it as a flat `.claude/task-archive/`. Nesting is what lets a reader tell the two shapes apart on sight: the flat sibling is what a binary predating this convention still writes, so meeting one names an older checkout rather than a second archive to reconcile against this one.
+The archive nests inside `.canon/tasks/` rather than sitting beside it as a flat `.claude/task-archive/`. Nesting is what lets a reader tell the two shapes apart on sight: the flat sibling is what a binary predating this convention still writes, so meeting one names an older checkout rather than a second archive to reconcile against this one.
 
-One destination rather than a per-project choice is what lets the move happen without asking. It mirrors the plans archive at `.claude/plans/archive/`, sitting inside the folder it archives the same way, and it inherits the board's own ignore entry rather than needing one of its own. The cost is that an archived task does not appear in diffs, which is the cost the live board already carries.
+One destination rather than a per-project choice is what lets the move happen without asking. It mirrors the plans archive at `.canon/plans/archive/`, sitting inside the folder it archives the same way, and it inherits the board's own ignore entry rather than needing one of its own. The cost is that an archived task does not appear in diffs, which is the cost the live board already carries.
 
 Archiving a task does not archive its plan. `claude-docs` owns the plans sweep and moves a plan only when the closing task is its last live citation, so the sweep runs before the archive rather than after it. The sweep finds its work by scanning the live folder, and a task archived first is beyond its reach for good, leaving the plan with no live task citing it and an archived task pointing at a path nothing will retarget.
 

package/standards/teach.md

@@ -5,13 +5,13 @@ description: Workspace layout, ordinal naming, frontmatter, and the mission and
 
 # Teach reference
 
-Applies to a learning workspace at `.claude/teach/<nn>-<topic>/`. One workspace holds one subject studied across sessions, and it carries both halves of what studying produces: the durable reference material a reader consults later, and the disposable lessons a learner works through once.
+Applies to a learning workspace at `.canon/teach/<nn>-<topic>/`. One workspace holds one subject studied across sessions, and it carries both halves of what studying produces: the durable reference material a reader consults later, and the disposable lessons a learner works through once.
 
 The folder is gitignored. Its markdown half is written in a format the authoring gates read, so a page promoted out of it later needs no conversion.
 
 ## Scope
 
-Governs a learning workspace under `.claude/teach/<nn>-<topic>/`: folder layout, ordinal naming, frontmatter, and the mission and learning-record formats.
+Governs a learning workspace under `.canon/teach/<nn>-<topic>/`: folder layout, ordinal naming, frontmatter, and the mission and learning-record formats.
 
 Does not govern:
 

package/standards/versioning.md

@@ -40,7 +40,7 @@ External release identity used in git tags and release notes. Independent of pha
 
 | Surface                   | Phase labels | Semver tags                         |
 | ------------------------- | ------------ | ----------------------------------- |
-| `.claude/tasks/`          | yes          | no                                  |
+| `.canon/tasks/`           | yes          | no                                  |
 | Chat with the operator    | yes          | no                                  |
 | PR titles                 | no           | only when the PR cuts a release     |
 | PR bodies                 | no           | only when the PR cuts a release     |

package/tooling/base/configs/.husky/post-merge

@@ -27,7 +27,7 @@ root=$(git worktree list --porcelain 2>/dev/null | grep -m 1 '^worktree ' | cut
 # The board is shared scratch at the main worktree root, and `git worktree
 # list` puts that root first. A pull inside a linked worktree fires this same
 # hook, so trusting the working directory would read a board that is not there.
-board="$root/.claude/tasks"
+board="$root/.canon/tasks"
 [ -d "$board" ] || exit 0
 
 closed=""

package/tooling/base/reference.md

@@ -50,7 +50,7 @@ Seeds live in `tooling/base/seeds/`. Sync drops each once on first install and n
 - `pre-commit` runs `bunx lint-staged`.
 - `commit-msg` runs `bunx commitlint --edit "$1"`.
 - `pre-push` runs `bun run check`.
-- `post-merge` names `.claude/tasks/` archive candidates, staying silent otherwise and when the board is absent.
+- `post-merge` names `.canon/tasks/` archive candidates, staying silent otherwise and when the board is absent.
 - `post-rewrite` delegates to `post-merge` on `rebase`, so a `pull.rebase=true` machine still gets the check.
 
 ## lint-staged

package/tooling/claude/manifest.toml

@@ -8,7 +8,17 @@ runtime = ""
 scaffold = ""
 
 # Checked against this repository's own `.gitignore` by
-# scripts/core/check-ignore-parity.sh, which also holds the two `.claude/` paths
-# this array deliberately omits and the reason each stays out.
+# scripts/core/check-ignore-parity.sh, which carries no sanctioned divergence
+# now that both sides ship the same two entries.
+#
+# One root entry rather than a folder apiece, so a target that gains a record
+# folder later receives no manifest edit and no sync. `.claude/worktrees/` is
+# the carve-out, since the harness requires a worktree to sit there.
+#
+# The cost is recorded rather than mitigated, and the operator took it on
+# 2026-09-01 against the two alternatives. A target that syncs and never runs
+# `canon migrate records` still holds its records under `.claude/`, and this
+# array no longer tells it to ignore them, so the first sign is a memory file or
+# a task board appearing in someone's commit.
 [gitignore]
-"# Claude" = [".canon/", ".claude/.records.git/", ".claude/.tmp/", ".claude/groundwork/", ".claude/intake/", ".claude/memory/", ".claude/plans/", ".claude/proposals/", ".claude/review/", ".claude/worktrees/", ".claude/tasks/", ".claude/teach/"]
+"# Claude" = [".canon/", ".claude/worktrees/"]

package/tooling/claude/reference.md

@@ -9,49 +9,62 @@ The claude stack installs the `.claude/` workflow directory into a project. Stat
 ```plaintext
 .claude/
 ├── CLAUDE.md          ← seeded. Project context and rules, auto-loaded by Claude Code each session
-├── tasks/             ← seeded then gitignored. One file per task plus a generated index.md, local scratch only. `archive/` holds the tasks that shipped.
 ├── REQUIREMENTS.md    ← seeded. Project goals, non-goals, MVP scope
 ├── ARCHITECTURE.md    ← seeded. Technical design decisions and open questions
 ├── DESIGN.md          ← seeded. Visual intent and the decisions behind it
 ├── wireframes/        ← seeded. Per-surface ASCII layouts. `index.md` is the discovery anchor; `<surface>.md` files hold the sketches and behavior bullets.
-├── diagrams/          ← seeded. Per-kind Mermaid views. `index.md` is the discovery anchor. `<kind>.md` files hold one diagram each, grouped by the `category` frontmatter field.
 ├── GOV.md             ← retired. Removed by `canon gov sync` if present from a prior install
 ├── settings.json      ← seeded. Project-level Claude Code config (PreToolUse and PostToolUse hooks). User-level config installed separately via `canon claude setup`.
-├── plans/             ← execution detail for multi-step tasks, gitignored. `feature-*.md` entries swept by claude-docs into `archive/`.
-├── review/            ← gitignored, one subfolder per producer. `branch/` for claude-review, `feedback/` for canon feedback, `memory/` for claude-memory-review with its own `archive/`, `design/` for canon design render.
-├── .tmp/              ← ephemeral scratch space, gitignored
-└── memory/            ← session facts no context entry owns, gitignored. `index.md` regenerated by a hook.
+└── worktrees/         ← gitignored. Where EnterWorktree creates a linked worktree, which is why it did not move.
+
+.canon/
+├── tasks/             ← seeded. One file per task plus a generated index.md, local scratch only. `archive/` holds the tasks that shipped.
+├── diagrams/          ← seeded. Per-kind Mermaid views. `index.md` is the discovery anchor. `<kind>.md` files hold one diagram each, grouped by the `category` frontmatter field.
+├── plans/             ← execution detail for multi-step tasks. `feature-*.md` entries swept by claude-docs into `archive/`.
+├── review/            ← one subfolder per producer. `branch/` for claude-review, `feedback/` for canon feedback, `memory/` for claude-memory-review with its own `archive/`, `design/` for canon design render.
+├── tmp/               ← ephemeral scratch space, safe to delete without loss
+└── memory/            ← session facts no context entry owns. `index.md` regenerated by a hook.
 ```
 
+One ignore entry covers `.canon/` whole, so nothing under it is named separately and nothing tracked may ever land there. A project scaffolded before the move keeps its records under `.claude/`, and every command reads either root.
+
+## Moving the records to `.canon/`
+
+A project installed before the split still holds its records under `.claude/`. `canon migrate records` moves them and repoints every tracked file that cites one, reporting the plan until `--write` is passed.
+
+Run `canon tooling sync claude . --write` first. The verb refuses while the project does not ignore `.canon/`, because every folder it relocates is ignored where it stands and landing one under a tracked root commits the memory pen. Until the move runs, this project's records sit at a root the shipped ignore set no longer names, so a `git add -A` in that window picks them up.
+
+The verb ships with the change that split the roots and is not in a published release yet, so an installed binary answers `unknown command` until one carries it. Run it out of a canon checkout in the meantime, as `bun src/cli.ts migrate records --root <project> --write`, and read the `ok` field out of `--json` rather than the exit code, which a shell wrapper around `canon` can flatten.
+
 ## Upgrading from a single-file board
 
-A project installed before the board became a folder still holds `.claude/TASKS.md`. Nothing migrates it. `canon claude init` seeds an empty `.claude/tasks/index.md` beside it and leaves the old file untouched, so every skill reads the empty catalog while the real board sits unreferenced.
+A project installed before the board became a folder still holds `.claude/TASKS.md`. Nothing migrates it. `canon claude init` seeds an empty `.canon/tasks/index.md` beside it and leaves the old file untouched, so every skill reads the empty catalog while the real board sits unreferenced.
 
 Convert by hand, once per project:
 
-1. Split each `###` block into `.claude/tasks/vXX.Y-<slug>.md`, adding the `title` and `description` frontmatter the tasks standard requires, which `canon standards tasks` prints. Compare each new file against the block it came from rather than checking that every block landed somewhere.
-2. Run `canon indexes regen --no-stage --root . .claude/tasks/<any-task>.md` to build the catalog.
-3. Delete `.claude/TASKS.md`, and swap its `.gitignore` entry for `.claude/tasks/`.
+1. Split each `###` block into `.canon/tasks/vXX.Y-<slug>.md`, adding the `title` and `description` frontmatter the tasks standard requires, which `canon standards tasks` prints. Compare each new file against the block it came from rather than checking that every block landed somewhere.
+2. Run `canon indexes regen --no-stage --root . .canon/tasks/<any-task>.md` to build the catalog.
+3. Delete `.claude/TASKS.md`, and swap its `.gitignore` entry for `.canon/tasks/`.
 
 ## Upgrading a hand-appended memory index
 
-A project installed before the memory folder gained a generated index still holds `.claude/memory/MEMORY.md`, and its entries still carry `name` and `type` frontmatter. Nothing migrates it. `claude-memory-capture` stops appending rows once the new seed lands, so the old file freezes at whatever it held while the folder keeps growing past it.
+A project installed before the memory folder gained a generated index still holds `.canon/memory/MEMORY.md`, and its entries still carry `name` and `type` frontmatter. Nothing migrates it. `claude-memory-capture` stops appending rows once the new seed lands, so the old file freezes at whatever it held while the folder keeps growing past it.
 
 Convert by hand, once per project:
 
 1. Rewrite each entry's `name` key to `title` and its `type` key to a sentence-case `category`, quoting any `description` that opens with a backtick or a colon so the frontmatter parses.
 2. Replace `MEMORY.md` with an `index.md` carrying `title` and `subtitle` frontmatter and nothing else.
-3. Run `canon indexes regen --no-stage --root . .claude/memory/index.md` to build the catalog, and compare its entry count against the file count before deleting anything.
+3. Run `canon indexes regen --no-stage --root . .canon/memory/index.md` to build the catalog, and compare its entry count against the file count before deleting anything.
 
 ## Upgrading from a single-file diagram set
 
-A project installed before the diagram surface became a folder still holds `.claude/DIAGRAMS.md`. Unlike the board, this one migrates itself. The `claude-diagram` skill reads the flat file when `.claude/diagrams/` holds no entries, splits it by kind into the folder, and reports what it wrote. The old file stays on disk so the split can be compared against its source, and deleting it is a manual step once that check passes.
+A project installed before the diagram surface became a folder still holds `.claude/DIAGRAMS.md`. Unlike the board, this one migrates itself. The `claude-diagram` skill reads the flat file when `.canon/diagrams/` holds no entries, splits it by kind into the folder, and reports what it wrote. The old file stays on disk so the split can be compared against its source, and deleting it is a manual step once that check passes.
 
 ## Gitignore
 
-- `# Claude`: `.claude/.records.git/`, `.claude/.tmp/`, `.claude/groundwork/`, `.claude/intake/`, `.claude/memory/`, `.claude/plans/`, `.claude/review/`, `.claude/worktrees/`, `.claude/tasks/`, `.claude/teach/`
+- `# Claude`: `.canon/`, `.claude/worktrees/`
 
-Each entry is a top-level record folder, and an archive sits inside the folder it archives, so one line covers a record and everything it retires.
+The first entry covers the whole record root, so a record folder added later needs no line here and no sync. The second is the carve-out, since the harness creates a worktree under `.claude/` and requires its target to sit there.
 
 ## CLI
 

package/tooling/claude/seeds/.claude/hooks/scratch-guard.sh

@@ -27,19 +27,19 @@ case "$file_path" in
 esac
 
 # A project whose own root sits under a path carrying a tmp segment is not
-# writing to system temp, and the bare pattern below trips the guard on every
-# source file it holds. Anchor on the project root before the pattern match.
-#
-# This gives up one case on purpose: a write to <project>/tmp/ is a genuine
-# scratch violation that no longer warns. The false positive fires on every
-# source write in an affected project, so the trade favors the anchor.
+# writing to system temp, and the bare pattern below would trip on every source
+# file it holds. The project root is stripped before the match rather than
+# exiting on it, so the segments the patterns look for are the ones the write
+# adds. Exiting on any path under the project gives up <project>/tmp/ as well,
+# which is a genuine violation this still warns on.
+matched=$file_path
 if [ -n "${CLAUDE_PROJECT_DIR:-}" ]; then
   case "$file_path" in
-  "$CLAUDE_PROJECT_DIR"/*) exit 0 ;;
+  "$CLAUDE_PROJECT_DIR"/*) matched=${file_path#"$CLAUDE_PROJECT_DIR"} ;;
   esac
 fi
 
-case "$file_path" in
+case "$matched" in
 */tmp/* | *\\tmp\\* | */Temp/* | *\\Temp\\* | */var/folders/*) ;;
 *) exit 0 ;;
 esac