@erclx/canon 4.72.0 → 4.73.0

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

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

package/claude/skills/markdown-propose/references/format.md

@@ -88,7 +88,7 @@ A proposal outlives its own diff. The source moves under it, so an approved chan
 
 What remains is the record of what changed and why, which is the half no commit message holds. The folder stays where it is, beside every earlier pass, so a later one reads what an earlier one settled instead of asking it again.
 
-The folder is gitignored and unbacked. It carries decision state rather than generated data, which is why `src/records/backup.ts` names it in `BACKED_FOLDERS`, but nothing else about its contents is enforced.
+The folder is gitignored, and backed wherever a records remote is configured. It carries decision state rather than generated data, which is why `src/records/backup.ts` names it in `BACKED_FOLDERS` so `canon records push` and `canon records pull` carry it there, refusing with `no-remote` otherwise, but nothing else about its contents is enforced.
 
 ## Retrieval
 

package/claude/skills/plan-groundwork/REQUIREMENT.md

@@ -25,7 +25,7 @@ A track that closes with several separable findings writes only one task, and th
 - Place the closing task's row through `task-board` Step 4 rather than writing `priority.md` or `backlog.md` directly
 - Link every claim about a source outside the project, and list an unread source as a lead rather than citing it
 - Put a fixture a headless run is pointed at outside the repository
-- Write the next-session file self-contained, since the folder is unbacked and dies with the machine
+- Write the next-session file self-contained, since backing the folder through `canon records push` and `canon records pull` holds only where a records remote is configured, protects only against the machine being lost even there, and never against a compaction dropping this session's reasoning before it has pushed
 
 ## Must not
 

package/claude/skills/plan-groundwork/SKILL.md

@@ -26,7 +26,7 @@ Read `${CLAUDE_SKILL_DIR}/../../standards/groundwork.md` before writing any file
 - A `draft-and-pick` run invoked from inside a live track follows its own branch for this, writing to `evidence/` here rather than `.canon/tmp/<slug>/`.
 - Reading is not restricted. External research is in scope, so read documentation, comparable projects, and papers whenever a live question needs them.
 - Every claim about a source outside the project carries a link to it. A source found and not read is listed as a lead and is never cited.
-- Treat the folder as gitignored and unbacked. It dies with the machine, so `07-next-session.md` repeats what it needs instead of pointing at its siblings.
+- Treat the folder as gitignored, and backed only where a records remote is configured: `canon records push` and `canon records pull` protect it against the machine being lost there and refuse with `no-remote` otherwise, and neither protects against a compaction dropping this session's own reasoning before anyone has pushed, so `07-next-session.md` repeats what it needs instead of pointing at its siblings.
 
 ## Running a spike
 

package/claude/skills/plan-intake/SKILL.md

@@ -32,7 +32,7 @@ Using the wrong one fails in two shapes. Intake on a question that needs measuri
 - Write only inside `.canon/intake/<nn>-<slug>/`. A plan file, a task file, a source change, a standard, and a rule all live outside that folder, so this one rule forbids every one of them.
 - There is no exception. Promoting an item onto the board runs through `task-board` after the operator has answered, which is a separate invocation.
 - Reading is unrestricted inside the project. Measuring is the work.
-- Treat the folder as gitignored and unbacked. No check reaches its contents, so every rule stated here holds only while a session reads it.
+- Treat the folder as gitignored, and backed only where a records remote is configured: `canon records push` and `canon records pull` protect it against the machine being lost there and refuse with `no-remote` otherwise, and neither protects against a compaction dropping a session's reasoning before anyone has pushed. No check reaches its contents, so every rule stated here holds only while a session reads it.
 
 Nothing outside this body carries the write-scope floor, and no path-scoped rule can. A misrouted write lands on a path the folder's glob never matches, so the rule that ships beside the intake standard carries the item format and the answer contract instead, for a session editing the folder with this skill unloaded.
 
@@ -81,7 +81,7 @@ Write `00-overview.md` last, once the clusters are filed and the counts are real
 
 Each open question in the index is a labeled markdown link to its owning item's heading anchor. The index points and the item owns, so no answer slot appears in the index. One question in two answerable places has no rule for which wins, and retrieval walks item headings, so an answer typed into the index is found by nothing and lost silently.
 
-Add `99-next-session.md` only where the pass ends holding context no cluster file carries, such as a dump half filed or a measurement that has to be redone. Write it self-contained, since the folder is unbacked and the conversation behind it compacts away.
+Add `99-next-session.md` only where the pass ends holding context no cluster file carries, such as a dump half filed or a measurement that has to be redone. Write it self-contained, since a compaction drops the conversation behind it regardless of whether the folder is backed.
 
 ## Output
 

package/claude/skills/session-relay/REQUIREMENT.md

@@ -18,6 +18,7 @@ Neither attempt named who the relay is from. A message an operator relays by han
 ## Must
 
 - Fire from inside `role-worker` or `role-planner`'s own `## The channel` section, at the point that section finds no message-sending tool
+- Refuse a caller holding neither role, checked ahead of the tool-availability guard
 - Read the sender's own name off `canon sessions list --self --json` before composing anything, and degrade to naming itself from the environment when the installed CLI answers `--self` with an unknown option rather than a refusal carrying a reason
 - Resolve the addressee by running the calling role's own ladder rather than a second one
 - Carry the message body the calling role's bullet already names, verbatim
@@ -32,6 +33,7 @@ Neither attempt named who the relay is from. A message an operator relays by han
 
 ## Guards
 
+- The calling session holds neither role: refuse, and state the addressing and timing it owes instead, since the plugin skill it would otherwise defer to reaches a target the moment it merges while a governance rule reaches one only through a separate install. Checked first, since the tool guard read alone let the incident behind this row stop at "you have a tool" without ever learning steps 2 and 3 were unreachable regardless.
 - A message-sending tool is available: refuse, name it, and send through it instead
 
 ## Out of scope

package/claude/skills/session-relay/SKILL.md

@@ -11,6 +11,7 @@ Read the calling body's `## The channel` section for the message owed and the la
 
 ## Guards
 
+- Refuse to fire when the calling session holds neither `role-worker` nor `role-planner`. Say so, and state what it owes instead: resolve the addressee at send time through `canon sessions list --json`, never by name prefix, and send a block out as a message before it becomes an interactive prompt, leaving the message content to whatever dispatched it. Checked first, since a caller that never held either role never had a ladder here to run, and the tool guard below reads as the whole reason only once this one has cleared.
 - Refuse to fire when a message-sending tool is available. Say so, name the tool, and send through it. This skill exists for the gap, never as an alternative to the ordinary channel.
 
 ## Steps

package/docs/agents/install-and-sync.md

@@ -158,8 +158,9 @@ Use `--json` for the machine-readable report and `--exit-code` to fail a CI job.
 and missing files are both excluded from that exit code: a project-authored
 rule never converges, and a sync that added a missing one silently changes
 what the project is governed by, which stays a separate command an operator
-chooses to run. Attribution reads `.claude/canon/config.json`, which every
-install and sync writes.
+chooses to run. Attribution reads `canon/config/config.json` first and falls
+back to `.claude/canon/config.json`, which every install and sync still writes
+in this release.
 
 A target installed before stamping shipped has no such file, and neither does
 that fallback do anything to migrate it. A target stamped before the file

package/docs/target-projects.md

@@ -204,7 +204,7 @@ The report opens by naming the binary running it. The installed version reads ag
 
 A `stale` file still matches what the toolkit installed, so the update is mechanical. A `customized` file carries local edits, so taking the upstream version is a decision and `canon:seed-sync` is the tool for it. A `stranded` file sits where an older toolkit installed it and the toolkit has since moved, which is a relocation the report names but no command runs.
 
-That attribution comes from `.claude/canon/config.json`, a stamp every install and sync writes. A target stamped before that path shipped is read from the retired `.claude/canon.json` instead, reported rather than migrated. Governance records a hash per installed file, plus the stack `canon gov install` was given, and tooling records the stack chain it resolved instead of any file hash, since its install runs no per-file walk to attribute.
+That attribution comes from `canon/config/config.json` when a project carries it, falling back to `.claude/canon/config.json`, a stamp every install and sync still writes in this release. A target stamped before that path shipped is read from the retired `.claude/canon.json` instead, reported rather than migrated. Governance records a hash per installed file, plus the stack `canon gov install` was given, and tooling records the stack chain it resolved instead of any file hash, since its install runs no per-file walk to attribute.
 
 Each domain holds its own toolkit commit, so syncing governance today does not move the revision tooling measures against, and each domain reports the upstream commits touching its own source path. Running any sync stamps that domain, and the report names the ones still unstamped.
 

package/governance/rules/core/091-channel.md

@@ -0,0 +1,13 @@
+---
+description: The addressing and timing a session holding neither role-worker nor role-planner owes when it must message whoever dispatched it
+---
+
+# Channel standards
+
+## A session holding neither role
+
+- Resolve the addressee at send time through `canon sessions list --json`, keyed on the id or branch the dispatcher named at launch, never by name prefix. A name is derived from what a session turns out to be doing and goes stale before a build finishes.
+- Send a block out as a message before it becomes an interactive prompt. A session already waiting on input never reaches the tool round that drains an inbound message, so an answer relayed afterwards arrives under the open question and changes nothing.
+- Leave the message content, and which transition earns one, to whatever dispatched this session. Both are task-specific and already stated where they apply.
+- A session holding `canon:role-worker` or `canon:role-planner` follows that body's own addressee ladder instead, stated in its own `## The channel` section. This rule states what neither role leaves stated elsewhere, not a replacement for either ladder.
+- Report it rather than proceeding silently when neither skill resolves to check against. Both ship with the plugin and this rule ships with the CLI, so a project that installed governance alone does not have them.

package/package.json

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

package/src/claude/skills-reach.ts

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { resolveSkillsCorpus } from '@/claude/skills-list'
+import { SURFACE_ROOTS } from '@/surface-root'
 
 /**
  * The authoring roots this repository owns and no install channel delivers.
@@ -15,9 +16,14 @@ import { resolveSkillsCorpus } from '@/claude/skills-list'
  * report a correct citation on every run and bury the defect this measures.
  * `docs/agents/` is the exception, being the CLI contract pages that exist
  * here alone.
+ *
+ * `.claude/context/` carries both surface-root spellings, since this list
+ * decides whether a shipped body names this repository's own tree and a body
+ * naming either root is doing that regardless of which root a given checkout
+ * carries.
  */
 const AUTHORING_ROOTS = [
-  '.claude/context/',
+  ...SURFACE_ROOTS.map((root) => `${root}/context/`),
   'claude/',
   'docs/agents/',
   'governance/',
@@ -92,9 +98,13 @@ export function isQualified(line: string): boolean {
  * by corpus instead.
  */
 export function authoringRootsFor(corpus: string): readonly string[] {
-  if (!corpus.startsWith('.claude/')) return AUTHORING_ROOTS
+  if (!SURFACE_ROOTS.some((root) => corpus.startsWith(`${root}/`))) {
+    return AUTHORING_ROOTS
+  }
 
-  return AUTHORING_ROOTS.filter((root) => !root.startsWith('.claude/'))
+  return AUTHORING_ROOTS.filter(
+    (root) => !SURFACE_ROOTS.some((surface) => root.startsWith(`${surface}/`)),
+  )
 }
 
 /**

package/src/commands/context.ts

@@ -17,11 +17,11 @@ import {
   type SectionFinding,
 } from '@/context/audit'
 import {
+  architectureRel,
   type ArchitectureReport,
   coveredCount,
   isOverLength,
   measureArchitecture,
-  RECORD_REL,
   testableCount,
 } from '@/context/architecture'
 import { auditCitations, type CitationReport } from '@/context/citations'
@@ -251,7 +251,7 @@ async function runAudit(
     reportProvenance(entries, folders)
     reportNarration(entries, folders, narration)
     reportDrift(drift)
-    reportRecord(record)
+    reportRecord(record, root)
     outro()
   }
 
@@ -761,12 +761,15 @@ const CLAIM_LABEL: Record<string, string> = {
  * anchors it sits beside already do. Nothing is stored: every run reclassifies,
  * so an entry rewritten tomorrow is read as it stands then.
  */
-function reportRecord(report: ArchitectureReport | undefined): void {
+function reportRecord(
+  report: ArchitectureReport | undefined,
+  root: string,
+): void {
   logStep('Architecture record')
 
   if (report === undefined) {
     logInfo(
-      `Out of scope. The project carries no ${RECORD_REL}, so there was no record to measure.`,
+      `Out of scope. The project carries no ${architectureRel(root)}, so there was no record to measure.`,
     )
     return
   }

package/src/commands/design.ts

@@ -11,6 +11,7 @@ import { renderDesignDoc } from '@/design/render'
 import { DESIGN_BASE_CSS, DESIGN_DOCUMENT, regenDesign } from '@/design/regen'
 import { checkoutMismatchWarning, PROJECT_ROOT } from '@/project-root'
 import { creationRel } from '@/record-root'
+import { surfaceDir } from '@/surface-root'
 import { recordStamp, runDomainSync } from '@/sync/engine'
 import { resolveTarget } from '@/target'
 import { intro, logAdd, logError, logInfo, logWarn, outro, palette } from '@/ui'
@@ -88,7 +89,11 @@ export function register(program: Command): void {
   design
     .command('render')
     .description('Render DESIGN.md tokens to HTML and CSS preview')
-    .option('-s, --source <path>', 'Source DESIGN.md path', '.claude/DESIGN.md')
+    .option(
+      '-s, --source <path>',
+      'Source DESIGN.md path',
+      relative(process.cwd(), surfaceDir(process.cwd(), 'DESIGN.md')),
+    )
     .option(
       '-o, --out <path>',
       'Output directory',

package/src/context/architecture.ts

@@ -1,16 +1,22 @@
 import { access, readFile } from 'node:fs/promises'
-import { join } from 'node:path'
+import { join, relative } from 'node:path'
 import { AUDITS } from '@/audits/catalog'
 import { bodyLines } from '@/markdown/scan'
+import { surfaceDir } from '@/surface-root'
 
 /**
- * The record this measures, relative to the project root.
+ * The record this measures, relative to `root`.
  *
- * One fixed path rather than a folder walk, because the standard governing it
- * names one document, and the length rule this measures is stated by whichever
- * record sits there rather than by the standard or by this file.
+ * A function rather than a fixed constant, because the path now resolves at
+ * either surface root and a constant naming one of them would be believed to
+ * be true of a project that has moved. One fixed name rather than a folder
+ * walk otherwise, because the standard governing it names one document, and
+ * the length rule this measures is stated by whichever record sits there
+ * rather than by the standard or by this file.
  */
-export const RECORD_REL = '.claude/ARCHITECTURE.md'
+export function architectureRel(root: string): string {
+  return relative(root, surfaceDir(root, 'ARCHITECTURE.md'))
+}
 
 /**
  * The line allowances a record states for itself, absent when it states none.
@@ -299,7 +305,8 @@ export function ceilingFor(allowances: Allowances, decisions: number): number {
 export async function measureArchitecture(
   root: string,
 ): Promise<ArchitectureReport | undefined> {
-  const path = join(root, RECORD_REL)
+  const rel = architectureRel(root)
+  const path = join(root, rel)
 
   let source: string
   try {
@@ -330,7 +337,7 @@ export async function measureArchitecture(
   )
 
   return {
-    rel: RECORD_REL,
+    rel,
     lines: source.replace(/\n$/, '').split('\n').length,
     ...(allowances !== undefined && {
       allowances,

package/src/context/citations.ts

@@ -3,6 +3,7 @@ import { readFile } from 'node:fs/promises'
 import { resolve } from 'node:path'
 import { listRepositoryFiles } from '@/git-files'
 import { RECORD_ROOTS } from '@/record-root'
+import { SURFACE_ROOTS } from '@/surface-root'
 
 /**
  * Suppresses citation checking for the source line carrying it.
@@ -78,17 +79,41 @@ export function isFixture(rel: string): boolean {
 }
 
 /**
- * Both record roots are spelled, so a citation into a folder that has moved is
- * still resolved. A pattern fixed at one root matches nothing after the move and
- * reports nothing, which is a stale reference passing the check that exists to
- * find it rather than a check that fails.
+ * The boundary a root's own leading character rules out.
+ *
+ * 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.
+ */
+function rootBoundary(root: string): string {
+  return root.startsWith('.') ? '(?<![\\w.])' : '(?<![\\w./])'
+}
+
+/**
+ * Every record and surface root is spelled, so a citation into a folder that
+ * has moved is still resolved. A pattern fixed at one root matches nothing
+ * after the move and reports nothing, which is a stale reference passing the
+ * check that exists to find it rather than a check that fails.
+ *
+ * Each root carries its own boundary rather than one shared ahead of the whole
+ * alternation, per `rootBoundary`. A shared boundary rejecting a slash blocked
+ * every dotted root from a relative link, which is the same failure this
+ * function's own boundary exists to prevent, aimed at the roots that never
+ * needed it.
  */
 export function citationPattern(folders: readonly string[]): RegExp {
   const names = folders.map((name) => escape(name))
-  const roots = RECORD_ROOTS.map((name) => escape(name))
+  const roots = [...new Set([...RECORD_ROOTS, ...SURFACE_ROOTS])]
+  const alternatives = roots
+    .map((root) => `${rootBoundary(root)}${escape(root)}`)
+    .join('|')
 
   return new RegExp(
-    `(?:${roots.join('|')})/(?:${names.join('|')})/[A-Za-z0-9._/-]+\\.md`,
+    `(?:${alternatives})/(?:${names.join('|')})/[A-Za-z0-9._/-]+\\.md`,
     'g',
   )
 }

package/src/context/folders.ts

@@ -2,6 +2,7 @@ import { existsSync } from 'node:fs'
 import { dirname, relative, resolve } from 'node:path'
 import { INDEX_FILE, listIndexes } from '@/indexes/walk'
 import { RECORD_ROOTS } from '@/record-root'
+import { SURFACE_ROOTS } from '@/surface-root'
 
 /**
  * Folder names under a record root audited by default.
@@ -23,16 +24,34 @@ export const DEFAULT_FOLDERS: readonly string[] = [
 ]
 
 /**
- * The bases every folder in the default list is looked for under, in the record
- * roots' own precedence order.
+ * The bases every folder in the default list is looked for under.
  *
- * `diagrams` is the one name here that is a session record and moves with them,
- * so the list has to carry the root it moves to. `context` and `wireframes` are
- * tracked and stay, which leaves them resolvable at a root nothing will ever put
- * them under. That costs one `existsSync` apiece and is cheaper than a per-name
- * base map that would state the same split twice.
+ * `diagrams` is a session record and resolves under `RECORD_ROOTS`, while
+ * `context` and `wireframes` are tracked and resolve under `SURFACE_ROOTS`, so
+ * the split this comment used to describe as hypothetical is real: two
+ * folders on this list read from two different root lists. The base array is
+ * their union rather than a per-name map, since a name resolving at the wrong
+ * root costs one extra `existsSync` and nothing else, where a map states the
+ * split a second time next to the one each resolver module already carries.
+ *
+ * `.claude` is pushed last because both lists name it, and each list's own
+ * precedence otherwise survives: `canon` still precedes `.claude` for a
+ * `SURFACE_ROOTS` name, and `.canon` still precedes `.claude` for a
+ * `RECORD_ROOTS` one. Order between `canon` and `.canon` is unobserved, since
+ * no name on this list resolves under both.
+ *
+ * Adding `canon` here means a target holding a root-level `canon/` folder of
+ * its own now resolves it as the toolkit's, since a project writing about a
+ * product called canon is a plausible name collision `canResolveAtRoot`'s own
+ * project-root gate does not cover. The audit only reports, so the cost is a
+ * wrong scope line rather than a wrong edit.
  */
-const CLAUDE_BASES: readonly string[] = RECORD_ROOTS
+const CLAUDE_BASES: readonly string[] = [
+  ...new Set(
+    [...SURFACE_ROOTS, ...RECORD_ROOTS].filter((root) => root !== '.claude'),
+  ),
+  '.claude',
+]
 
 /** The project root, reached only by a name the caller asked for. */
 const ROOT_BASE = '.'

package/src/gate/measures.ts

@@ -1,6 +1,6 @@
 import { createHash } from 'node:crypto'
 import { existsSync, readdirSync, readFileSync } from 'node:fs'
-import { join } from 'node:path'
+import { join, relative } from 'node:path'
 import {
   CLIENT_COMMAND_MARKER,
   CLIENT_COMMANDS,
@@ -15,6 +15,7 @@ import {
   SHIPPED_CORPORA,
   type ShippedReference,
 } from '@/shipped/references'
+import { surfaceDir } from '@/surface-root'
 import {
   README_PARAPHRASE_MARKER,
   readmeCitationsIn,
@@ -122,11 +123,18 @@ export const SANDBOX_UNDECLARED_CEILING = 47
 export const SANDBOX_ASSERTED_FLOOR = 26
 
 /**
- * The retained counts the audit stage compares each run against. Spelled here
- * rather than derived, because this stage only ever names the file in a remedy
- * a reader has to be able to open, and `canon audits run` owns writing it.
+ * 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
+ * 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.
  */
-export const AUDITS_BASELINE = '.claude/canon/baseline.json'
+export function auditsBaselineRel(root: string): string {
+  return relative(root, surfaceDir(root, 'canon', 'baseline.json'))
+}
 
 export const CAPTURE_STAMP_FAILURE =
   'A capture set disagrees with the stamp written when its image was captured. Run canon capture assets/captures --selector .window --out assets and commit each frame with its image and its stamp.'
@@ -958,16 +966,17 @@ export const auditSet: Measure = async (ctx) => {
       ),
     )
   }
+  const baselineRel = auditsBaselineRel(ctx.root)
   emissions.push(
     summary.grown > 0
       ? warn(
-          `${summary.grown} measure(s) grew against ${AUDITS_BASELINE}. Run bun src/cli.ts audits run to see which, then fix them or re-record and say why.`,
+          `${summary.grown} measure(s) grew against ${baselineRel}. Run bun src/cli.ts audits run to see which, then fix them or re-record and say why.`,
         )
-      : info(`No measure grew against ${AUDITS_BASELINE}`),
+      : info(`No measure grew against ${baselineRel}`),
   )
   if (typeof summary.shrunk === 'number' && summary.shrunk > 0) {
     emissions.push(
-      info(`${summary.shrunk} measure(s) fell against ${AUDITS_BASELINE}`),
+      info(`${summary.shrunk} measure(s) fell against ${baselineRel}`),
     )
   }
 

package/src/migrate/records.ts

@@ -76,10 +76,14 @@ function escape(value: string): string {
  * paths a session actually opened. Rewriting either makes it testify to
  * something that never happened.
  *
- * This module and `src/record-root.ts` are the two sources that state the old
+ * This module and `src/record-root.ts` are two of the sources that state the old
  * root on purpose. Sweeping them turns every citation this expression is built
  * from into its own replacement, leaving a rewriter that maps `.canon/` to
- * `.canon/` and matches nothing.
+ * `.canon/` and matches nothing. `src/surface-root.ts` joins the list a release
+ * early, for the same reason: it spells `.claude` as data the moment it
+ * exists, and excluding it later would leave one release where a records
+ * migration in a target could rewrite the resolver that migration itself
+ * depends on.
  *
  * A test file is excluded because the fixtures that prove the old root still
  * resolves have to keep building it. Rewriting one is worse than a failing
@@ -106,7 +110,11 @@ const EXCLUDED_PREFIXES: readonly string[] = [
   'tooling/claude/seeds/.claude/hooks/',
 ]
 
-const EXCLUDED_PATHS: readonly string[] = ['CHANGELOG.md', 'src/record-root.ts']
+const EXCLUDED_PATHS: readonly string[] = [
+  'CHANGELOG.md',
+  'src/record-root.ts',
+  'src/surface-root.ts',
+]
 
 const EXCLUDED_SUFFIXES: readonly string[] = ['.test.ts']
 

package/src/surface-root.ts

@@ -0,0 +1,101 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+/**
+ * The roots a tracked toolkit surface is read at, in precedence order.
+ *
+ * These are not `RECORD_ROOTS`, and the difference is what each root is for
+ * rather than an oversight. A record folder moves into `.canon/` because it is
+ * gitignored, so nothing tracked ever lands there. A surface here is committed,
+ * so a single shared list would put a record folder under a root a tracked
+ * file also resolves against, which is a collision this list never has to
+ * consider on its own.
+ *
+ * `canon` wins because a tree that carries it has moved, and reading `.claude/`
+ * there would answer from the copy the move left behind. Read precedence
+ * agreeing with the eventual creation default means the flip a later batch
+ * takes changes one line rather than two.
+ */
+export const SURFACE_ROOTS = ['canon', '.claude'] as const
+
+export type SurfaceRoot = (typeof SURFACE_ROOTS)[number]
+
+/**
+ * The root a surface is created at when neither root carries it yet.
+ *
+ * Disagreeing with the head of the read order for exactly one release: read
+ * precedence is new-first so a tree that has moved is never answered from the
+ * copy left behind, while creation stays at the old root so nothing writes a
+ * fresh tracked file under a root a target's installed binary may not resolve
+ * yet. A later batch flips this once a release carries the read side.
+ */
+export const CREATION_ROOT: SurfaceRoot = '.claude'
+
+/**
+ * Every tracked surface this module resolves, at the name `.claude/` gives it.
+ *
+ * `canon` names the stamp folder rather than the CLI itself, which is the one
+ * entry `spell` respells per root.
+ */
+export const SURFACE_ENTRIES: readonly string[] = [
+  'ARCHITECTURE.md',
+  'REQUIREMENTS.md',
+  'DESIGN.md',
+  'context',
+  'wireframes',
+  'canon',
+]
+
+/**
+ * How a root spells an entry name. Only the stamp folder differs, since a
+ * project under `canon/` reserves the bare name for the CLI's own install
+ * rather than for its config.
+ */
+export function spell(root: SurfaceRoot, entry: string): string {
+  return root === 'canon' && entry === 'canon' ? 'config' : entry
+}
+
+/**
+ * The root a surface resolves at: the first that carries it, and the creation
+ * default when neither does.
+ */
+function rootOf(root: string, entry: string): SurfaceRoot {
+  return (
+    SURFACE_ROOTS.find((candidate) =>
+      existsSync(join(root, candidate, spell(candidate, entry))),
+    ) ?? CREATION_ROOT
+  )
+}
+
+/**
+ * Where a tracked surface is read.
+ *
+ * `entry` is the surface itself and `rest` is whatever sits inside it, so a
+ * caller spells no root and no per-root naming variant of its own.
+ */
+export function surfaceDir(
+  root: string,
+  entry: string,
+  ...rest: string[]
+): string {
+  const at = rootOf(root, entry)
+  return join(root, at, spell(at, entry), ...rest)
+}
+
+/**
+ * Every root a surface would be read at, in precedence order, whether or not
+ * it is on disk.
+ *
+ * Containment tests take this rather than `surfaceDir`, since a path written
+ * against the root a tree no longer uses is still a path into that surface,
+ * and reading it as outside would report a live reference as stale.
+ */
+export function surfaceDirs(
+  root: string,
+  entry: string,
+  ...rest: string[]
+): string[] {
+  return SURFACE_ROOTS.map((candidate) =>
+    join(root, candidate, spell(candidate, entry), ...rest),
+  )
+}

package/src/sync/stamp.ts

@@ -84,17 +84,30 @@ export function retiredNameStampPath(target: string): string {
   return join(target, '.claude', 'aitk', 'config.json')
 }
 
+/**
+ * The stamp path under the new surface root, `canon/config/config.json`.
+ *
+ * Read ahead of `stampPath`, extending the same mechanism rather than adding a
+ * new one: a target that has moved reads its config from the root it moved
+ * to, and one that has not falls through to the spellings below unchanged.
+ * The write destination does not move to it in this batch.
+ */
+function surfaceStampPath(target: string): string {
+  return join(target, 'canon', 'config', 'config.json')
+}
+
 /**
  * Every spelling a stamp has been written under, current first. The order is
  * the read order, so a target carrying more than one resolves to the newest.
  *
- * The fallback carries no end date. It costs two path reads on a command that
- * already touches the filesystem, and dropping it later is a second breaking
- * change aimed at exactly the targets that were slowest to migrate the first
- * time.
+ * The fallback carries no end date. It costs three path reads on a command
+ * that already touches the filesystem, and dropping any of them later is a
+ * second breaking change aimed at exactly the targets that were slowest to
+ * migrate the first time.
  */
 export function stampPaths(target: string): readonly string[] {
   return [
+    surfaceStampPath(target),
     stampPath(target),
     retiredNameStampPath(target),
     legacyStampPath(target),
@@ -107,7 +120,9 @@ export function stampPaths(target: string): readonly string[] {
  * there is nothing to migrate off of.
  */
 export function isLegacyStamped(target: string): boolean {
-  if (existsSync(stampPath(target))) return false
+  if (existsSync(surfaceStampPath(target)) || existsSync(stampPath(target))) {
+    return false
+  }
   return (
     existsSync(retiredNameStampPath(target)) ||
     existsSync(legacyStampPath(target))

package/standards/groundwork.md

@@ -7,7 +7,7 @@ description: Folder layout, ordinal naming, reserved numbering, frontmatter and
 
 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.
+The folder is gitignored, and backed wherever a records remote is configured: `canon records push` and `canon records pull` protect it against the machine being lost there, refusing with `no-remote` where no remote is set, and neither protects against a compaction dropping a session's reasoning before anyone has pushed. No check reaches its contents, so every rule here holds only while a session reads it, and the handoff file has to be self-contained.
 
 ## Scope
 

package/standards/intake.md

@@ -7,7 +7,7 @@ description: Folder layout, ordinal naming, reserved index number, frontmatter a
 
 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.
+The folder is gitignored, and backed wherever a records remote is configured: `canon records push` and `canon records pull` protect it against the machine being lost there, refuse with `no-remote` where it is not, and neither protects against a compaction dropping a session's reasoning before anyone has pushed. No check reaches its contents, so the shape below survives only by being read.
 
 ## Scope
 

package/standards/memory.md

@@ -7,7 +7,7 @@ description: Filename and type prefix, frontmatter, the body shape per type, lin
 
 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.
+The folder is gitignored, and backed wherever a records remote is configured: `canon records push` and `canon records pull` protect it against the machine being lost there, refuse with `no-remote` where it is not, and protect nothing against an entry deleted before anyone has pushed. That is why the retire step below is a move rather than a cleanup: a retired entry stays readable regardless of push timing, where a deleted one is gone the moment nothing has captured it yet.
 
 ## Scope
 
@@ -98,7 +98,7 @@ Link a related entry as `[[name]]`, where `name` is the target's filename stem w
 
 - Check the folder for an entry on the same topic before writing a new one, and update that entry in place when one exists. Two entries on one rule disagree the moment either is edited.
 - Rewrite an entry the tree has moved under rather than appending a second passage narrating the change. A reader cannot tell which of two claims is current.
-- Never delete an entry. Retire one by moving it to an archive under its own name, because the folder is unbacked and a bulk judgment has no undo behind it.
+- Never delete an entry. Retire one by moving it to an archive under its own name, because a bulk judgment made before the next push has no undo behind it, and moving keeps the record where deleting would not.
 - Treat the folder as a holding pen rather than a destination. An entry whose rule belongs on a durable surface is promoted there and retired here, and the rest is what the pen is for.
 
 The catalog is generated from sibling frontmatter rather than authored. Never hand-edit it, since the next regeneration discards whatever was added by hand.

package/standards/plan.md

@@ -7,7 +7,7 @@ description: Filename and slug, required sections, the suggested-and-answer cont
 
 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.
+The folder is gitignored, and backed wherever a records remote is configured: `canon records push` and `canon records pull` protect it against the machine being lost there, refuse with `no-remote` where it is not, and protect nothing against a plan deleted before anyone has pushed. That is why the archive step below is a move rather than a cleanup.
 
 ## Scope