@erclx/canon 4.78.0 → 4.80.0

package/src/commands/migrate.ts

@@ -1,4 +1,4 @@
-import { readFileSync } from 'node:fs'
+import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
 import type { Command } from 'commander'
 import { listRepositoryFiles } from '@/git-files'
@@ -26,6 +26,10 @@ import {
   walkFlatRules,
 } from '@/migrate/rule-layout'
 import { SKILL_NAME_MAP, SKILL_NAME_RULES } from '@/migrate/skill-names'
+import {
+  planSurfaceRootsMove,
+  type SurfaceRootsPlan,
+} from '@/migrate/surface-roots'
 import {
   applyScratchEvidence,
   planScratchEvidence,
@@ -396,6 +400,143 @@ function toRecordsRecord(
   }
 }
 
+/**
+ * Moves the tracked toolkit surfaces to `canon/` and repoints what cites them.
+ *
+ * Every path here is tracked, so the write goes through `applyRename`'s
+ * `git mv` rather than the records move's plain rename, and the history
+ * follows each file. A destination already on disk refuses the whole plan,
+ * since `git mv` onto an existing path fails per file and leaves a tree split
+ * across both roots.
+ */
+async function runSurfaceRoots(opts: SweepOptions): Promise<number> {
+  const root = opts.root ?? process.cwd()
+
+  const files = await listRepositoryFiles(root)
+  if (files === undefined) {
+    logError(`Could not list files under ${root}. Is it a git repository?`)
+    return 1
+  }
+
+  const toSweep = files.filter((path) => !isRecordArtifact(path))
+  const plan = planSurfaceRootsMove(await readSources(root, toSweep))
+  const taken = plan.entries
+    .map((entry) => entry.movesTo)
+    .filter((to): to is string => to !== undefined)
+    .filter((to) => existsSync(join(root, to)))
+
+  if (opts.json) {
+    process.stdout.write(
+      `${JSON.stringify(toSurfaceRootsRecord(plan, taken, opts.write))}\n`,
+    )
+  }
+
+  reportSurfaceRoots(plan)
+
+  if (taken.length > 0) {
+    logError(
+      `${plural(taken.length, 'destination')} already exist under canon/. Merging two copies of a surface is not a call this verb takes.`,
+    )
+    for (const path of taken) logError(`  ${path}`)
+    return 1
+  }
+
+  if (plan.entries.length === 0) return 0
+
+  if (!opts.write) {
+    logWarn('Nothing was written. Pass --write to apply this plan.')
+    return 2
+  }
+
+  const applied = await applyRename(root, {
+    entries: plan.entries.map((entry) => ({
+      path: entry.path,
+      ...(entry.movesTo === undefined ? {} : { movesTo: entry.movesTo }),
+      ...(entry.text === undefined ? {} : { text: entry.text }),
+      renamed: entry.rewritten,
+      protectedCount: entry.kept,
+    })),
+    excluded: plan.excluded,
+    renamed: plan.rewritten,
+    protectedCount: plan.kept,
+    moves: plan.moves,
+  })
+  logStep(
+    `Rewrote ${plural(applied.written, 'file')} and moved ${plural(applied.moved, 'file')}.`,
+  )
+
+  if (applied.failed.length > 0) {
+    logError(`Could not move ${plural(applied.failed.length, 'path')}.`)
+    for (const path of applied.failed) logError(`  ${path}`)
+    return 1
+  }
+
+  return 0
+}
+
+function reportSurfaceRoots(plan: SurfaceRootsPlan): void {
+  logInfo(`${plural(plan.moves, 'file')} to move.`)
+  logInfo(
+    `${plural(plan.entries.filter((entry) => entry.text !== undefined).length, 'file')} to change, ${plural(plan.rewritten, 'citation')} to rewrite.`,
+  )
+  logInfo(`${plural(plan.kept, 'citation')} marked to keep the old root.`)
+
+  if (plan.excluded.length > 0) {
+    logInfo(`${plural(plan.excluded.length, 'file')} excluded from the sweep:`)
+    for (const path of plan.excluded) logInfo(`  ${path}`)
+  }
+
+  if (plan.coupled.length > 0) {
+    logInfo(
+      `${plural(plan.coupled.length, 'file')} couple to an excluded path:`,
+    )
+    for (const path of plan.coupled) logInfo(`  ${path}`)
+  }
+
+  for (const [label, held] of [
+    ['a frontmatter paths: glob', plan.frontmatterGlobs],
+    ['a citation into another repository', plan.crossRepoCitations],
+    ['a dated citation', plan.datedCitations],
+  ] as const) {
+    if (held.length === 0) continue
+    logInfo(`${plural(held.length, 'file')} carry ${label}, left alone:`)
+    for (const entry of held) {
+      for (const line of entry.lines) {
+        logInfo(`  ${entry.path}:${line.line}  ${excerpt(line.text)}`)
+      }
+    }
+  }
+}
+
+function toSurfaceRootsRecord(
+  plan: SurfaceRootsPlan,
+  collisions: readonly string[],
+  wrote: boolean | undefined,
+): unknown {
+  return {
+    ok: collisions.length === 0,
+    wrote: wrote === true,
+    moves: plan.moves,
+    collisions,
+    files: plan.entries.length,
+    rewritten: plan.rewritten,
+    kept: plan.kept,
+    excluded: plan.excluded,
+    coupled: plan.coupled,
+    frontmatterGlobs: plan.frontmatterGlobs,
+    crossRepoCitations: plan.crossRepoCitations,
+    datedCitations: plan.datedCitations,
+    globs: plan.globs,
+    crossRepo: plan.crossRepo,
+    dated: plan.dated,
+    paths: plan.entries.map((entry) => ({
+      path: entry.path,
+      ...(entry.movesTo === undefined ? {} : { movesTo: entry.movesTo }),
+      rewritten: entry.rewritten,
+    })),
+  }
+}
+
 interface RecordTreeOptions {
   readonly json?: boolean
   readonly write?: boolean
@@ -763,6 +904,46 @@ export function register(program: Command): void {
       process.exitCode = await runRecords(opts)
     })
 
+  migrate
+    .command('surface-roots')
+    .description('Move the tracked toolkit surfaces to canon/')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .option('--write', 'Apply the plan rather than reporting it')
+    .option(
+      '--root <path>',
+      'Project root, defaulting to the working directory',
+    )
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Exit codes:',
+        '  0  nothing to move, or --write applied the whole plan',
+        '  1  refused, or a move failed',
+        '  2  a plan exists and --write was not passed',
+        '',
+        'Moves canon/context/, canon/wireframes/, and the ARCHITECTURE.md,',
+        'REQUIREMENTS.md, and DESIGN.md documents to canon/ with git mv, and',
+        'rewrites every tracked citation of them. .claude/canon/, rules/,',
+        'skills/, hooks/, and settings.json stay where the vendor reads them.',
+        '',
+        'A line carrying canon-keep-surface-root, or the nearest non-blank line',
+        'above it, keeps the old root. A frontmatter paths: glob, a citation',
+        'into another repository, and one inside a dated paragraph are reported',
+        'and left alone rather than rewritten.',
+        '',
+        'Examples:',
+        '  canon migrate surface-roots',
+        '  canon migrate surface-roots --write',
+        '  canon migrate surface-roots --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: SweepOptions) => {
+      process.exitCode = await runSurfaceRoots(opts)
+    })
+
   migrate
     .command('record-tree')
     .description('Repoint old-root citations inside the records themselves')

package/src/commands/sync.ts

@@ -101,7 +101,7 @@ function renderCheck(report: CheckReport): void {
 
   if (report.stampAtLegacyPath) {
     logWarn(
-      'Stamp found at a retired path. Move it to .claude/canon/config.json.',
+      'Stamp found at a retired path. Move it to canon/config/config.json.',
     )
   }
 

package/src/context/audit.ts

@@ -19,7 +19,7 @@ import { isStubSeed } from '@/seed-marker'
  * Every reason `canon context audit` refuses for.
  *
  * `no-folders` is the one ordinary absence: a project that never adopted
- * `.claude/context/`, `.canon/diagrams/`, or `.claude/wireframes/` names no
+ * `canon/context/`, `.canon/diagrams/`, or `canon/wireframes/` names no
  * corpus this audit can measure, the same state `no-skills` reads for the
  * skill corpora. The other four are a malformed invocation or a checkout git
  * cannot read, which stay a break rather than an absence.

package/src/context/citations.ts

@@ -84,13 +84,15 @@ export function isFixture(rel: string): boolean {
  * A dotted root cannot be a suffix of a path segment, since a segment boundary
  * is a slash and a slash can never sit inside the dot itself, so a preceding
  * slash is not a false match to guard against and the boundary admits it. That
- * is what a relative link needs, since `../.claude/context/<entry>.md` carries
- * a slash immediately before `.claude`. A bare root has no such protection: it
- * is a suffix of a dotted root's own name and of any `/<root>/` path segment,
- * so its boundary rejects a slash along with a name character or a dot.
+ * is what a relative link into a dotted root needs. A bare root has no such
+ * protection: it is a suffix of a dotted root's own name and of any
+ * `/<root>/` path segment, such as a seed tree's own `canon/` folder, so its
+ * boundary rejects a name character, a dot, and a slash, except a slash that
+ * closes a `..` segment. That one exception is a relative link climbing out of
+ * a folder into the bare root, which is the form a moved docs page writes.
  */
 function rootBoundary(root: string): string {
-  return root.startsWith('.') ? '(?<![\\w.])' : '(?<![\\w./])'
+  return root.startsWith('.') ? '(?<![\\w.])' : '(?<![\\w.])(?<!(?<!\\.\\.)/)'
 }
 
 /**

package/src/context/folders.ts

@@ -61,7 +61,7 @@ export interface AuditedFolder {
    * The requested folder name this was resolved under, which is what says
    * which standard governs the entries. A nested split folder carries the name
    * of the folder it sits beneath rather than its own, so
-   * `.claude/context/claude-plugin` is governed as `context`.
+   * `canon/context/claude-plugin` is governed as `context`.
    */
   readonly name: string
   /**
@@ -90,7 +90,7 @@ export interface AuditedFolder {
  * Names the requested record-root folders that actually exist, which is the
  * citation check's scope.
  *
- * A skill or seed pointing into `.claude/wireframes/` is a live instruction for
+ * A skill or seed pointing into `canon/wireframes/` is a live instruction for
  * a project that carries the folder and says nothing about one that does not.
  * Checking a path into an absent folder would fail eight shipped references
  * here for the sole reason that this repository has no wireframes.

package/src/counts/scan.ts

@@ -35,7 +35,7 @@ export type CountsReport =
 
 /**
  * A calendar date, which reads a sentence as a historical record rather than
- * a live claim about the tree. `.claude/ARCHITECTURE.md` and the context
+ * a live claim about the tree. `canon/ARCHITECTURE.md` and the context
  * entries carry a figure this way deliberately, and every one of them stays
  * correct forever, so a sentence carrying one is read past rather than
  * matched.
@@ -80,7 +80,7 @@ function sentencesOf(line: string): string[] {
  * the 290 showed removing all of them while keeping that one.
  *
  * `authors` joined the list on a corpus measurement rather than on the shape
- * argument above. `.claude/context/development/regeneration.md` states `the
+ * argument above. `canon/context/development/regeneration.md` states `the
  * toolkit authors 69 rules under governance/rules/`, which is the assertion
  * shape this list was built for with a verb the list did not carry, and the
  * word costs one further sentence across the whole corpus and no finding.
@@ -129,7 +129,7 @@ const QUANTIFIERS = ['all']
  * of the number.
  *
  * Found on this module's own first review, against a live instance the verb
- * gate alone reported clean: `.claude/context/development/gates.md` stated
+ * gate alone reported clean: `canon/context/development/gates.md` stated
  * `the twelve audits` while the tree held 20, sitting inside the plausibility
  * bound this design already carries, so nothing but the missing shape kept it
  * from reporting.
@@ -142,7 +142,7 @@ const QUANTIFIERS = ['all']
  * match at all. No syntactic rule tells a qualifier that narrows a catalog
  * from one that only restates it, and the sentence was true when written, so
  * the fix was not a narrower matcher: the clause was dated as a past state,
- * the way `.claude/ARCHITECTURE.md` dates its own figures, which is the class
+ * the way `canon/ARCHITECTURE.md` dates its own figures, which is the class
  * the date exclusion below already reads past.
  */
 const ARTICLES = ['the', 'a', 'an']

package/src/design/board.ts

@@ -14,12 +14,12 @@ import { colorValue } from '@/design/tokens'
 import { recordDir } from '@/record-root'
 
 /**
- * The one named site for this repository's wireframe corpus. `standards/`
- * moves it to `canon/wireframes/` under the answered
- * `.canon/intake/88-surface-roots-and-corpus-debt/` item 1, and that move
- * retargets this constant alone rather than a literal repeated per panel.
+ * The one named site for this repository's wireframe corpus, so the surface
+ * move retargets a single constant rather than a literal repeated per panel.
+ * The board reads this checkout alone, which has moved, so the new root is
+ * spelled directly rather than resolved.
  */
-export const WIREFRAME_DIR = join('.claude', 'wireframes')
+export const WIREFRAME_DIR = join('canon', 'wireframes')
 
 /** Landing page for the built site the surfaces panel iframes when present. */
 const WEB_DIST = join('web', 'dist')

package/src/design/components.ts

@@ -15,7 +15,7 @@
  * `buildDesignCss`'s `components` option, which is what widening that option
  * from a boolean to `boolean | readonly Component[]` bought.
  *
- * It does not live in `.claude/DESIGN.md`. `standards/design.md` keeps CSS class
+ * It does not live in `canon/DESIGN.md`. `standards/design.md` keeps CSS class
  * names out of that record and says they live in code, which is here.
  */
 
@@ -207,7 +207,7 @@ const TEACH_CHROME: Component = {
     'navigation shared by every teach page. Recovered from two gitignored',
     'course.css files that predate a regression that dropped this layer from the',
     "generator, and rewritten onto this module's tokens rather than the",
-    'incompatible palette they carried. See .claude/wireframes/teach/chrome.md for',
+    'incompatible palette they carried. See canon/wireframes/teach/chrome.md for',
     'the shape.',
   ].join('\n   '),
   reads: [

package/src/design/css.ts

@@ -12,7 +12,7 @@ import { TOKENS } from '@/design/tokens'
  *
  * The property names match the ones `@/design/render` already emits from a
  * parsed document, so the toolkit's own source and a target's hand-authored
- * `.claude/DESIGN.md` produce one vocabulary rather than two.
+ * `canon/DESIGN.md` produce one vocabulary rather than two.
  */
 
 /** A role name as it appears in a custom property. */

package/src/design/document.ts

@@ -8,7 +8,7 @@ import type {
 import { TOKENS } from '@/design/tokens'
 
 /**
- * Renders `.claude/DESIGN.md` from the token source.
+ * Renders `canon/DESIGN.md` from the token source.
  *
  * The document is the view and `@/design/tokens` is the fact, which is the one
  * thing that changed when this record stopped being a transcript of two other

package/src/design/regen.ts

@@ -15,7 +15,7 @@ import { renderDesignDocument } from '@/design/document'
  */
 
 /** The rendered record, at the path `standards/design.md` fixes for it. */
-export const DESIGN_DOCUMENT = join('.claude', 'DESIGN.md')
+export const DESIGN_DOCUMENT = join('canon', 'DESIGN.md')
 
 /**
  * The base stylesheet a target installs. It sits inside `src/` because that is

package/src/design/render.ts

@@ -219,7 +219,7 @@ ${previewChrome()}
 </head>
 <body>
 <h1>Design tokens</h1>
-<p class="note">Generated from <code>.claude/DESIGN.md</code> by <code>canon design render</code>. Token preview only, not a screen mock.</p>${summary}
+<p class="note">Generated from <code>canon/DESIGN.md</code> by <code>canon design render</code>. Token preview only, not a screen mock.</p>${summary}
 ${sections.join('\n')}
 </body>
 </html>

package/src/design/tokens.ts

@@ -1,7 +1,7 @@
 /**
  * The design system's one source of values.
  *
- * `.claude/DESIGN.md` is rendered from this module rather than read by it, so
+ * `canon/DESIGN.md` is rendered from this module rather than read by it, so
  * the document a person opens is a view and this file is the fact. Every
  * rendering surface reads from here in the form it can take: a CSS surface
  * takes custom properties through `@/design/css`, and the slide renderer takes
@@ -94,7 +94,7 @@ export const TOKENS: DesignTokens = {
     '',
     'The two rendered captures read it as well. `scripts/core/regen-hero.sh` fills `assets/captures/hero.html.tmpl` and `assets/captures/install.html.tmpl` with what `canon design css --no-components` emits, so both frames now carry the custom properties rather than their own copies of the hex, and a value moved here moves what the next capture renders.',
     '',
-    'The terminal framing is the one surface left holding its own values, and that is a decision rather than a gap. `scripts/lib/ui.sh` and `src/ui.ts` each spell six escape constants, and `.claude/ARCHITECTURE.md` records one color source per language with a check behind each, so generating a third spelling from here would break the rule those two checks enforce. What the record is still incomplete about is the other half of those six: `WHITE` and `GREY` name no role below, so the terminal palette is described here in part rather than in whole.',
+    'The terminal framing is the one surface left holding its own values, and that is a decision rather than a gap. `scripts/lib/ui.sh` and `src/ui.ts` each spell six escape constants, and `canon/ARCHITECTURE.md` records one color source per language with a check behind each, so generating a third spelling from here would break the rule those two checks enforce. What the record is still incomplete about is the other half of those six: `WHITE` and `GREY` name no role below, so the terminal palette is described here in part rather than in whole.',
   ].join('\n'),
 
   personality: [

package/src/docs/read.ts

@@ -1,15 +1,21 @@
 import { existsSync, readFileSync, readdirSync } from 'node:fs'
 import { basename, join } from 'node:path'
 import { stripFrontmatter } from '@/frontmatter'
+import { SURFACE_ROOTS } from '@/surface-root'
 
 const INDEX_TOPIC = 'index'
 
 /**
- * The two roots a topic resolves against, in precedence order. `docs/` holds
- * consumer-facing reference and `.claude/context/` holds per-domain internal
+ * The roots a topic resolves against, in precedence order. `docs/` holds
+ * consumer-facing reference and the context folder holds per-domain internal
  * narrative, so a name present in both resolves to the consumer-facing copy.
+ * The context folder is read at every surface root, so a checkout the surface
+ * move has not reached still resolves its own entries.
  */
-const ROOTS: readonly string[] = ['docs', join('.claude', 'context')]
+const ROOTS: readonly string[] = [
+  'docs',
+  ...SURFACE_ROOTS.map((root) => join(root, 'context')),
+]
 
 export interface ResolvedTopic {
   readonly path: string

package/src/gate/measures.ts

@@ -126,11 +126,11 @@ export const SANDBOX_ASSERTED_FLOOR = 26
  * Where the retained counts the audit stage compares each run against are
  * read, relative to `root`.
  *
- * A function rather than a spelled constant, since the read now resolves at
+ * A function rather than a spelled constant, since the read resolves at
  * either surface root and a constant naming one of them would be believed of
- * a project that has moved. `canon audits run` owns writing it, and the write
- * stays at the creation default for this batch, so the two can disagree for
- * exactly the release window `src/surface-root.ts` documents.
+ * a project that has moved. `canon audits run` owns writing it, at
+ * `canon/config/baseline.json` now that the write has flipped, falling back to
+ * `.claude/canon/baseline.json` for a target that has not moved.
  */
 export function auditsBaselineRel(root: string): string {
   return relative(root, surfaceDir(root, 'canon', 'baseline.json'))
@@ -369,7 +369,8 @@ export const seedStandards: Measure = async (ctx) => {
   if (seedRoots.length === 0) {
     return {
       emissions: [],
-      unmeasured: 'No seed root carries .claude/, so nothing was measured.',
+      unmeasured:
+        'No seed root carries .claude/ or canon/, so nothing was measured.',
     }
   }
 
@@ -387,11 +388,13 @@ export const seedStandards: Measure = async (ctx) => {
 
     // The audit separates 1 from 2 and they mean opposite things. 2 is a seed
     // breaking the standard it seeds. 1 is the audit refusing, which a seed
-    // root carrying a `.claude/` but no audited folder produces, and reporting
-    // that as a violation sends a reader hunting one that does not exist.
+    // root carrying a root but no audited folder produces, and reporting that
+    // as a violation sends a reader hunting one that does not exist.
     if (run.exitCode === 1) {
       emissions.push(
-        warn(`${seedRoot}: no audited folder under .claude/, nothing measured`),
+        warn(
+          `${seedRoot}: no audited folder under either root, nothing measured`,
+        ),
       )
       continue
     }
@@ -581,8 +584,8 @@ export const shippedReferences: Measure = async (ctx) => {
     ),
     failure:
       found.length === 1
-        ? `One reference in the shipped corpora resolves wrong for a reader in a target. Qualify a cross-repository citation as owner/repo#123 or owner/repo@abc1234, cite a docs page through canon docs <name>, rewrite a bare standards/ path under claude/skills/ as \${CLAUDE_SKILL_DIR}/../../standards/<name>.md, state a same-repository citation or a phase label as a fact instead and relocate the evidence to the owning .claude/context/ entry, state the fact a shipped skill body's cited rule enforces instead of its path, or mark the line ${REFERENCE_MARKER}: <reason> where the bare form is the point.`
-        : `${found.length} references in the shipped corpora resolve wrong for a reader in a target. Qualify a cross-repository citation as owner/repo#123 or owner/repo@abc1234, cite a docs page through canon docs <name>, rewrite a bare standards/ path under claude/skills/ as \${CLAUDE_SKILL_DIR}/../../standards/<name>.md, state a same-repository citation or a phase label as a fact instead and relocate the evidence to the owning .claude/context/ entry, state the fact a shipped skill body's cited rule enforces instead of its path, or mark each line ${REFERENCE_MARKER}: <reason> where the bare form is the point.`,
+        ? `One reference in the shipped corpora resolves wrong for a reader in a target. Qualify a cross-repository citation as owner/repo#123 or owner/repo@abc1234, cite a docs page through canon docs <name>, rewrite a bare standards/ path under claude/skills/ as \${CLAUDE_SKILL_DIR}/../../standards/<name>.md, state a same-repository citation or a phase label as a fact instead and relocate the evidence to the owning canon/context/ entry, state the fact a shipped skill body's cited rule enforces instead of its path, or mark the line ${REFERENCE_MARKER}: <reason> where the bare form is the point.`
+        : `${found.length} references in the shipped corpora resolve wrong for a reader in a target. Qualify a cross-repository citation as owner/repo#123 or owner/repo@abc1234, cite a docs page through canon docs <name>, rewrite a bare standards/ path under claude/skills/ as \${CLAUDE_SKILL_DIR}/../../standards/<name>.md, state a same-repository citation or a phase label as a fact instead and relocate the evidence to the owning canon/context/ entry, state the fact a shipped skill body's cited rule enforces instead of its path, or mark each line ${REFERENCE_MARKER}: <reason> where the bare form is the point.`,
   }
 }
 
@@ -1011,7 +1014,7 @@ export const pluginManifests: Measure = async (ctx) => {
     return {
       emissions: [],
       unmeasured:
-        'claude is on PATH and claude --version fails, so the install brought down no platform-native binary and no manifest was read. Raise or lower the pinned version at the Install Plugin CLI step in .github/workflows/verify.yml, and record the move in .claude/context/ci.md.',
+        'claude is on PATH and claude --version fails, so the install brought down no platform-native binary and no manifest was read. Raise or lower the pinned version at the Install Plugin CLI step in .github/workflows/verify.yml, and record the move in canon/context/ci.md.',
     }
   }
 

package/src/gate/stages.ts

@@ -79,7 +79,7 @@ export interface Stage {
 
 /**
  * Corpora a `src/` test asserts over from outside `src/`, censused in
- * `.claude/context/development/verification.md`. This list and that census are
+ * `canon/context/development/verification.md`. This list and that census are
  * two copies of one set with nothing comparing them, so a corpus joining the
  * census joins this list in the same change. The first four are directory
  * prefixes because their tests walk the tree whole, which is what reaches a
@@ -221,7 +221,7 @@ export const STAGES: readonly Stage[] = [
     success: 'Tooling paths clean',
   },
   {
-    // `.claude/DESIGN.md`, the base stylesheet, the web stylesheet, and the
+    // `canon/DESIGN.md`, the base stylesheet, the web stylesheet, and the
     // tab icon are all written from `src/design/tokens.ts` and none is edited
     // by hand. Four artifacts from one source is the cost of the token move,
     // and a render step that has to run is only safe while something fails
@@ -236,9 +236,9 @@ export const STAGES: readonly Stage[] = [
       },
       {
         kind: 'drift',
-        pathspec: '.claude/DESIGN.md',
+        pathspec: 'canon/DESIGN.md',
         failure:
-          'The design record drifted from the token source. Run bun run check and commit .claude/DESIGN.md.',
+          'The design record drifted from the token source. Run bun run check and commit canon/DESIGN.md.',
       },
       {
         kind: 'drift',

package/src/labels/map.ts

@@ -1,14 +1,23 @@
 import { readFileSync } from 'node:fs'
 import { join } from 'node:path'
+import { resolveExisting } from '@/legacy-path'
 
 /**
- * Where a project declares its pull request label map, spelled once.
+ * Where a project declares its pull request label map.
  *
  * The file has already moved once, and that relocation rewrote every mention
- * across four surfaces. Nothing in code spells it anywhere else, so the next
- * move is one edit here rather than a sweep.
+ * across four surfaces. `LEGACY_MAP_REL` below is the one other place code
+ * spells it, kept only as a read fallback, so the next move is still one edit
+ * to the write path rather than a sweep.
  */
-export const MAP_REL = join('.claude', 'canon', 'pr-labels.toml')
+export const MAP_REL = join('canon', 'config', 'pr-labels.toml')
+
+/**
+ * Where the map lived before this move, `.claude/canon/pr-labels.toml`.
+ * `readLabelMap` falls back to it so a project that has not moved still reads
+ * its declared map.
+ */
+const LEGACY_MAP_REL = join('.claude', 'canon', 'pr-labels.toml')
 
 /** A label name and the path prefixes that earn it, in the map's own order. */
 export interface DomainRow {
@@ -90,9 +99,14 @@ export function parseLabelMap(source: string): LabelMap {
 
 /** Reads the map a project declares at `root`, or says why it could not. */
 export function readLabelMap(root: string): LabelMap {
+  const path = resolveExisting([
+    join(root, MAP_REL),
+    join(root, LEGACY_MAP_REL),
+  ])
+
   let source: string
   try {
-    source = readFileSync(join(root, MAP_REL), 'utf8')
+    source = readFileSync(path, 'utf8')
   } catch {
     return { kind: 'refused', reason: 'no-map' }
   }

package/src/legacy-path.ts

@@ -0,0 +1,15 @@
+import { existsSync } from 'node:fs'
+
+/**
+ * Where a fallback chain resolves for reading: the first path that exists,
+ * current first, or the first candidate when none exists yet, which is
+ * always the write target.
+ *
+ * `src/audits/baseline.ts`, `src/labels/map.ts`, and `src/sync/stamp.ts` each
+ * trail a file that moved, and each used to reason about its own chain
+ * separately. The tuple type keeps a caller from passing an empty list, since
+ * every chain here has a write target to fall back to.
+ */
+export function resolveExisting(paths: readonly [string, ...string[]]): string {
+  return paths.find((path) => existsSync(path)) ?? paths[0]
+}

package/src/markdown/scan.ts

@@ -206,7 +206,7 @@ export function maskDisplayed(text: string): string {
  * A code span is walked around rather than through, since keeping it counted
  * and then dropping spans from inside it takes back the decision. The
  * placeholders this repository writes are the case: a reader is shown all of
- * `.claude/context/<domain>.md` and the autolink pattern reaches the angle
+ * `canon/context/<domain>.md` and the autolink pattern reaches the angle
  * brackets in the middle of it.
  */
 export function visibleText(text: string): string {

package/src/migrate/plan.ts

@@ -44,6 +44,7 @@ export interface RenamePlan {
 const TOOLKIT_OWNED: readonly string[] = [
   '.claude/aitk/',
   '.claude/canon/',
+  'canon/config/',
   '.claude/hooks/',
   '.claude/rules/',
   '.claude/tooling/',