@erclx/canon 4.6.1 → 4.8.0

package/src/records/backup.ts

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

package/src/records/validate.ts

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

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/"]