npm - @erclx/canon - Versions diffs - 4.78.0 → 4.79.0 - Mend

@erclx/canon 4.78.0 → 4.79.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (140) hide show

package/README.md +9 -9
package/claude/.claude-plugin/plugin.json +1 -1
package/claude/skills/canon-operator/SKILL.md +1 -1
package/claude/skills/create-standard/SKILL.md +1 -1
package/claude/skills/design-extract/REQUIREMENT.md +4 -4
package/claude/skills/design-extract/SKILL.md +11 -11
package/claude/skills/docs-fold/SKILL.md +14 -14
package/claude/skills/docs-fold/references/anchor-sweep.md +1 -1
package/claude/skills/docs-fold/references/wireframe-sweep.md +4 -4
package/claude/skills/draft-context/REQUIREMENT.md +6 -6
package/claude/skills/draft-context/SKILL.md +8 -6
package/claude/skills/draft-diagram/SKILL.md +5 -5
package/claude/skills/draft-identity/SKILL.md +3 -3
package/claude/skills/draft-readme/REQUIREMENT.md +1 -1
package/claude/skills/draft-screencast/SKILL.md +1 -1
package/claude/skills/draft-wireframes/REQUIREMENT.md +7 -7
package/claude/skills/draft-wireframes/SKILL.md +7 -5
package/claude/skills/memory-capture/REQUIREMENT.md +1 -1
package/claude/skills/memory-capture/SKILL.md +6 -6
package/claude/skills/memory-review/SKILL.md +1 -1
package/claude/skills/migration-claude-md/REQUIREMENT.md +3 -3
package/claude/skills/migration-claude-md/SKILL.md +7 -5
package/claude/skills/migration-context/REQUIREMENT.md +3 -3
package/claude/skills/migration-context/SKILL.md +11 -9
package/claude/skills/plan-feature/SKILL.md +4 -4
package/claude/skills/plan-groundwork/SKILL.md +2 -2
package/claude/skills/plan-intake/SKILL.md +2 -2
package/claude/skills/project-commands/SKILL.md +2 -2
package/claude/skills/review-branch/SKILL.md +3 -3
package/claude/skills/review-pr/SKILL.md +2 -2
package/claude/skills/role-orchestrator/SKILL.md +1 -1
package/claude/skills/role-planner/SKILL.md +1 -1
package/claude/skills/session-relay/REQUIREMENT.md +1 -1
package/claude/skills/session-resume/SKILL.md +1 -1
package/claude/skills/setup-gov/SKILL.md +1 -1
package/claude/skills/setup-init/SKILL.md +1 -1
package/claude/skills/teach-workspace/references/promotion.md +5 -5
package/claude/skills/ux-audit/SKILL.md +5 -5
package/claude/skills/ux-measure/SKILL.md +1 -1
package/docs/agents/commands.md +7 -2
package/docs/agents/context-audit-checks.md +3 -3
package/docs/agents/context-audit.md +2 -2
package/docs/agents/counts.md +3 -3
package/docs/agents/design-board.md +3 -3
package/docs/agents/docs.md +3 -3
package/docs/agents/indexes.md +1 -1
package/docs/agents/install-and-sync.md +1 -1
package/docs/agents/review-classification.md +1 -1
package/docs/agents/routing.md +2 -2
package/docs/agents/rule-citations.md +1 -1
package/docs/agents/sandbox.md +1 -1
package/docs/agents/scripting.md +1 -1
package/docs/agents/skills-audit.md +1 -1
package/docs/agents/skills-reach.md +4 -4
package/docs/target-projects.md +10 -10
package/docs/workflow/ai-workflow.md +15 -13
package/docs/workflow/operating-model.md +2 -2
package/docs/workflow/visual-design-workflow.md +8 -8
package/governance/rules/claude/510-context.md +3 -2
package/governance/rules/claude/520-wireframes.md +3 -2
package/governance/rules/claude/530-requirements.md +2 -1
package/governance/rules/claude/540-architecture.md +2 -1
package/governance/rules/claude/550-design.md +2 -1
package/governance/rules/core/025-indexes.md +1 -1
package/governance/rules/core/045-memory.md +1 -1
package/package.json +1 -1
package/scripts/core/check-ignore-parity.sh +1 -1
package/scripts/core/check-seed-independence.sh +5 -2
package/scripts/core/install-check.sh +1 -1
package/scripts/core/list-seed-roots.sh +3 -3
package/scripts/core/regen-hero.sh +1 -1
package/scripts/docs/list.sh +3 -3
package/scripts/lib/sandbox-git.sh +1 -1
package/scripts/lib/tooling.sh +6 -4
package/snippets/claude/figma-steps.md +1 -1
package/src/audits/catalog.ts +2 -2
package/src/autoship/paths.ts +1 -1
package/src/claude/cases/authoring.ts +2 -2
package/src/claude/cases/setup.ts +1 -1
package/src/claude/routing.ts +1 -1
package/src/claude/seeds-list.ts +1 -1
package/src/claude/seeds.ts +62 -28
package/src/claude/skills-reach.ts +3 -3
package/src/commands/claude.ts +1 -1
package/src/commands/context.ts +8 -8
package/src/commands/design.ts +1 -1
package/src/commands/gov.ts +1 -1
package/src/commands/migrate.ts +182 -1
package/src/context/audit.ts +1 -1
package/src/context/citations.ts +7 -5
package/src/context/folders.ts +2 -2
package/src/counts/scan.ts +4 -4
package/src/design/board.ts +5 -5
package/src/design/components.ts +2 -2
package/src/design/css.ts +1 -1
package/src/design/document.ts +1 -1
package/src/design/regen.ts +1 -1
package/src/design/render.ts +1 -1
package/src/design/tokens.ts +2 -2
package/src/docs/read.ts +9 -3
package/src/gate/measures.ts +10 -7
package/src/gate/stages.ts +4 -4
package/src/markdown/scan.ts +1 -1
package/src/migrate/surface-roots.ts +458 -0
package/src/record-root.ts +6 -4
package/src/sandbox/census.ts +1 -1
package/src/shipped/references.ts +3 -3
package/src/surface-root.ts +39 -7
package/src/sync/layout.ts +10 -6
package/src/sync/reverse.ts +1 -1
package/src/tooling/inject.ts +5 -3
package/src/tooling/scan.ts +4 -1
package/standards/architecture.md +4 -4
package/standards/context.md +7 -7
package/standards/design.md +3 -3
package/standards/diagrams.md +6 -6
package/standards/index.md +5 -5
package/standards/markdown.md +2 -2
package/standards/publish.md +3 -3
package/standards/readme.md +1 -1
package/standards/requirements.md +4 -4
package/standards/skill.md +2 -2
package/standards/tasks.md +1 -1
package/standards/wiki.md +1 -1
package/standards/wireframes.md +8 -8
package/tooling/astro/reference.md +3 -3
package/tooling/base/reference.md +3 -3
package/tooling/claude/reference.md +7 -3
package/tooling/claude/seeds/CLAUDE.md +9 -9
package/tooling/nextjs/reference.md +2 -2
package/tooling/python/reference.md +1 -1
package/tooling/vite-react/reference.md +2 -2
package/tooling/web/reference.md +2 -2
/package/tooling/base/seeds/{.claude → canon}/context/ci.md +0 -0
/package/tooling/base/seeds/{.claude → canon}/context/development.md +0 -0
/package/tooling/base/seeds/{.claude → canon}/context/index.md +0 -0
/package/tooling/claude/seeds/{.claude → canon}/ARCHITECTURE.md +0 -0
/package/tooling/claude/seeds/{.claude → canon}/DESIGN.md +0 -0
/package/tooling/claude/seeds/{.claude → canon}/REQUIREMENTS.md +0 -0
/package/tooling/claude/seeds/{.claude → canon}/wireframes/index.md +0 -0

package/src/design/board.ts CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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/markdown/scan.ts CHANGED Viewed

@@ -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/surface-roots.ts ADDED Viewed

@@ -0,0 +1,458 @@
+/**
+ * The move of the tracked toolkit surfaces from `.claude/` to `canon/`.
+ *
+ * Unlike the records move, every entry here is tracked, so a folder relocating
+ * is itself a citation-shaped event: the file's own path is a string every
+ * other file may quote. One planner therefore judges both halves per source
+ * file rather than moving folders and rewriting citations as two passes, so a
+ * file that both moves and cites another moved entry is decided once.
+ */
+import { join } from 'node:path'
+import { SURFACE_ENTRIES, spell, type SurfaceRoot } from '@/surface-root'
+/** The root the entries below leave. */
+export const FROM_ROOT: SurfaceRoot = '.claude'
+/** The root they arrive at. */
+const TO_ROOT: SurfaceRoot = 'canon'
+/**
+ * Every entry this move relocates, at the name `.claude/` gives it.
+ *
+ * Read from `SURFACE_ENTRIES` rather than restated, less the one entry that
+ * stays: `canon` names the install stamp folder, which batch 3 owns and which
+ * `.claude/canon/` continues to hold until that batch lands.
+ */
+export const MOVED_ENTRIES: readonly string[] = SURFACE_ENTRIES.filter(
+  (entry) => entry !== 'canon',
+)
+function sourcePrefix(entry: string): string {
+  return join(FROM_ROOT, spell(FROM_ROOT, entry))
+}
+function destinationPrefix(entry: string): string {
+  return join(TO_ROOT, spell(TO_ROOT, entry))
+}
+/**
+ * Where a moved entry's own path lands, or `undefined` when `path` sits
+ * outside every moved entry.
+ *
+ * Tested against the file's own path rather than its content, so a context
+ * entry moves regardless of what it cites.
+ */
+export function movedPath(path: string): string | undefined {
+  for (const entry of MOVED_ENTRIES) {
+    const prefix = sourcePrefix(entry)
+    if (path === prefix) return destinationPrefix(entry)
+    if (path.startsWith(`${prefix}/`)) {
+      return destinationPrefix(entry) + path.slice(prefix.length)
+    }
+  }
+  return undefined
+}
+/**
+ * A citation into a moved entry.
+ *
+ * The tail rejects a following name character rather than asking for a word
+ * boundary, which is what keeps `.claude/context` bare and `.claude/context/`
+ * both matching while `.claude/contexts/` does not. The alternation is ordered
+ * longest first so `ARCHITECTURE.md` is decided before any shorter entry could
+ * claim its prefix, and each entry is escaped because two of them carry a dot.
+ */
+const CITATION = new RegExp(
+  `${escape(FROM_ROOT)}/(${[...MOVED_ENTRIES]
+    .sort((left, right) => right.length - left.length)
+    .map(escape)
+    .join('|')})(?![A-Za-z0-9._-])`,
+  'g',
+)
+function escape(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+/**
+ * Files whose content is left alone entirely.
+ *
+ * The changelog is release history, and an eval result is a transcript of
+ * paths a session actually opened; rewriting either makes it testify to
+ * something that never happened. `src/surface-root.ts` and
+ * `src/record-root.ts` are the two sources that spell the old root as data on
+ * purpose, so sweeping either would turn the very literals this verb reads
+ * into their own replacement. A hook is the third such source, guarding on a
+ * `case` carrying an arm per root, so `.claude/hooks/` and the seed's copy of
+ * it are excluded for the same reason `records.ts` excludes them.
+ *
+ * No suffix-wide test exclusion. Most of the `src/` test files naming these
+ * paths use them as fixture data proving the fallback still resolves, not to
+ * pin one particular assertion, so a wholesale ban would leave the majority
+ * silently unswept. The two files that do pin a fallback carry `KEEP_MARKER`
+ * on the line that needs it instead.
+ */
+const EXCLUDED_PREFIXES: readonly string[] = [
+  'src/migrate/',
+  'scripts/eval/result-',
+  '.claude/hooks/',
+  'tooling/claude/seeds/.claude/hooks/',
+]
+const EXCLUDED_PATHS: readonly string[] = [
+  'CHANGELOG.md',
+  'src/surface-root.ts',
+  'src/record-root.ts',
+]
+export function isExcludedPath(path: string): boolean {
+  if (EXCLUDED_PATHS.includes(path)) return true
+  return EXCLUDED_PREFIXES.some((prefix) => path.startsWith(prefix))
+}
+/**
+ * Whether `text` names an `EXCLUDED_PREFIXES` or `EXCLUDED_PATHS` entry as
+ * literal substring text, which is how a rewritten file can couple to one
+ * this module leaves alone.
+ */
+export function referencesExcluded(text: string): boolean {
+  return (
+    EXCLUDED_PATHS.some((path) => text.includes(path)) ||
+    EXCLUDED_PREFIXES.some((prefix) => text.includes(prefix))
+  )
+}
+/**
+ * Marks a line naming the old root on purpose.
+ *
+ * The marker sits on the line itself or on the nearest non-blank line above
+ * it, walking past a run of blank markdown lines to reach a marker written on
+ * its own line above the paragraph it protects.
+ */
+const KEEP_MARKER = 'canon-keep-surface-root'
+function isKept(lines: readonly string[], index: number): boolean {
+  if (lines[index]?.includes(KEEP_MARKER)) return true
+  let above = index - 1
+  while (above >= 0 && lines[above]?.trim() === '') above -= 1
+  return above >= 0 && (lines[above]?.includes(KEEP_MARKER) ?? false)
+}
+/**
+ * The line index where a leading YAML frontmatter block closes, or
+ * `undefined` when the file does not open with a bare `---` on line one.
+ */
+function frontmatterEnd(lines: readonly string[]): number | undefined {
+  if (lines[0] !== '---') return undefined
+  const end = lines.indexOf('---', 1)
+  return end === -1 ? undefined : end
+}
+/**
+ * Marks a line inside a rule's frontmatter `paths:` key: the key line itself,
+ * or an indented `- 'glob'` list item under it.
+ */
+function isFrontmatterPathsLine(
+  lines: readonly string[],
+  index: number,
+  frontmatterEndIndex: number | undefined,
+): boolean {
+  if (frontmatterEndIndex === undefined) return false
+  if (index <= 0 || index >= frontmatterEndIndex) return false
+  let top = index
+  while (top > 0 && /^\s/.test(lines[top] ?? '')) top -= 1
+  return lines[top]?.trim().startsWith('paths:') ?? false
+}
+/**
+ * A path segment immediately before a citation match, shaped like another
+ * repository's own name: it carries a dot or it is itself preceded by a
+ * further `/`.
+ */
+const CROSS_REPO_PREFIX = /(?:[\w.-]+\.[\w.-]+|[\w.-]+\/[\w.-]+)\/$/
+function isCrossRepoPrefix(lines: readonly string[], index: number): boolean {
+  const line = lines[index] ?? ''
+  const match = [...line.matchAll(CITATION)][0]
+  if (match === undefined) return false
+  return CROSS_REPO_PREFIX.test(line.slice(0, match.index ?? 0))
+}
+/** An ISO date, marking a paragraph as recording what was true on that day. */
+const ISO_DATE = /\b\d{4}-\d{2}-\d{2}\b/
+/**
+ * Whether the line's citation sits inside a blank-line-delimited paragraph
+ * that also carries an ISO date, read as dated prose rather than a live path.
+ *
+ * `.claude/ARCHITECTURE.md` is itself a moved entry and carries dozens of
+ * `Measured at <sha> on <date>` paragraphs naming the old root as what was
+ * true that day. Those stay as written rather than being rewritten into a
+ * root that did not exist yet on the date being recorded.
+ */
+function isDatedParagraph(lines: readonly string[], index: number): boolean {
+  let start = index
+  while (start > 0 && lines[start - 1]?.trim() !== '') start -= 1
+  let end = index
+  while (end < lines.length - 1 && lines[end + 1]?.trim() !== '') end += 1
+  for (let cursor = start; cursor <= end; cursor += 1) {
+    if (ISO_DATE.test(lines[cursor] ?? '')) return true
+  }
+  return false
+}
+type LineClass = 'live' | 'kept' | 'glob' | 'crossRepo' | 'dated'
+function classifyLine(
+  lines: readonly string[],
+  index: number,
+  frontmatterEndIndex: number | undefined,
+): LineClass {
+  if (isFrontmatterPathsLine(lines, index, frontmatterEndIndex)) return 'glob'
+  if (isKept(lines, index)) return 'kept'
+  if (isCrossRepoPrefix(lines, index)) return 'crossRepo'
+  if (isDatedParagraph(lines, index)) return 'dated'
+  return 'live'
+}
+/** Rewrites every unmarked, non-glob citation into a moved entry. */
+export function rewriteText(text: string): string {
+  const lines = text.split('\n')
+  const frontmatterEndIndex = frontmatterEnd(lines)
+  return lines
+    .map((line, index) =>
+      classifyLine(lines, index, frontmatterEndIndex) === 'live'
+        ? line.replace(CITATION, (_match, entry: string) =>
+            destinationPrefix(entry),
+          )
+        : line,
+    )
+    .join('\n')
+}
+/**
+ * How many citations `rewriteText` would rewrite, how many marked lines it
+ * left alone, how many sat inside a frontmatter `paths:` glob, how many sat
+ * behind a cross-repository-shaped prefix, and how many sat inside a dated
+ * paragraph.
+ */
+export function scanText(text: string): {
+  readonly rewritten: number
+  readonly kept: number
+  readonly globs: number
+  readonly crossRepo: number
+  readonly dated: number
+} {
+  const lines = text.split('\n')
+  const frontmatterEndIndex = frontmatterEnd(lines)
+  let rewritten = 0
+  let kept = 0
+  let globs = 0
+  let crossRepo = 0
+  let dated = 0
+  for (const [index, line] of lines.entries()) {
+    const matches = [...line.matchAll(CITATION)].length
+    if (matches === 0) continue
+    const kind = classifyLine(lines, index, frontmatterEndIndex)
+    if (kind === 'glob') globs += matches
+    else if (kind === 'kept') kept += matches
+    else if (kind === 'crossRepo') crossRepo += matches
+    else if (kind === 'dated') dated += matches
+    else rewritten += matches
+  }
+  return { rewritten, kept, globs, crossRepo, dated }
+}
+/** Where a citation sits, so a reader can judge it before `--write` runs. */
+export interface CitationLine {
+  readonly line: number
+  readonly text: string
+}
+function frontmatterGlobLines(text: string): CitationLine[] {
+  const lines = text.split('\n')
+  const frontmatterEndIndex = frontmatterEnd(lines)
+  const held: CitationLine[] = []
+  for (const [index, line] of lines.entries()) {
+    if (!isFrontmatterPathsLine(lines, index, frontmatterEndIndex)) continue
+    if ([...line.matchAll(CITATION)].length === 0) continue
+    held.push({ line: index + 1, text: line.trim() })
+  }
+  return held
+}
+function crossRepoLines(text: string): CitationLine[] {
+  const lines = text.split('\n')
+  const frontmatterEndIndex = frontmatterEnd(lines)
+  const held: CitationLine[] = []
+  for (const [index, line] of lines.entries()) {
+    if ([...line.matchAll(CITATION)].length === 0) continue
+    if (classifyLine(lines, index, frontmatterEndIndex) !== 'crossRepo')
+      continue
+    held.push({ line: index + 1, text: line.trim() })
+  }
+  return held
+}
+function datedLines(text: string): CitationLine[] {
+  const lines = text.split('\n')
+  const frontmatterEndIndex = frontmatterEnd(lines)
+  const held: CitationLine[] = []
+  for (const [index, line] of lines.entries()) {
+    if ([...line.matchAll(CITATION)].length === 0) continue
+    if (classifyLine(lines, index, frontmatterEndIndex) !== 'dated') continue
+    held.push({ line: index + 1, text: line.trim() })
+  }
+  return held
+}
+/** One tracked file, as the planner reads it. */
+export interface SurfaceRootsSource {
+  readonly path: string
+  readonly text: string
+}
+/** One file the sweep touches, whether by moving, rewriting, or both. */
+export interface SurfaceRootsEntry {
+  readonly path: string
+  readonly movesTo?: string
+  readonly text?: string
+  readonly rewritten: number
+  readonly kept: number
+}
+export interface FrontmatterGlobEntry {
+  readonly path: string
+  readonly lines: readonly CitationLine[]
+}
+export interface CrossRepoCitationEntry {
+  readonly path: string
+  readonly lines: readonly CitationLine[]
+}
+export interface DatedCitationEntry {
+  readonly path: string
+  readonly lines: readonly CitationLine[]
+}
+export interface SurfaceRootsPlan {
+  readonly entries: readonly SurfaceRootsEntry[]
+  readonly excluded: readonly string[]
+  readonly coupled: readonly string[]
+  readonly frontmatterGlobs: readonly FrontmatterGlobEntry[]
+  readonly crossRepoCitations: readonly CrossRepoCitationEntry[]
+  readonly datedCitations: readonly DatedCitationEntry[]
+  readonly rewritten: number
+  readonly kept: number
+  readonly globs: number
+  readonly crossRepo: number
+  readonly dated: number
+  readonly moves: number
+}
+/**
+ * What the move would do, without doing it.
+ *
+ * A file is judged once for both halves: whether its own path sits under a
+ * moved entry, and whether its content cites one. Either alone is enough to
+ * produce an entry, and a file excluded from the citation rewrite still moves
+ * when its path itself is inside a moved entry, since the two entries excluded
+ * today, `src/surface-root.ts` and `src/record-root.ts`, both sit outside
+ * every moved entry and never take that branch in practice.
+ */
+export function planSurfaceRootsMove(
+  sources: readonly SurfaceRootsSource[],
+): SurfaceRootsPlan {
+  const entries: SurfaceRootsEntry[] = []
+  const excluded: string[] = []
+  const coupled: string[] = []
+  const frontmatterGlobs: FrontmatterGlobEntry[] = []
+  const crossRepoCitations: CrossRepoCitationEntry[] = []
+  const datedCitations: DatedCitationEntry[] = []
+  let kept = 0
+  let globs = 0
+  let crossRepo = 0
+  let dated = 0
+  for (const source of sources) {
+    const movesTo = movedPath(source.path)
+    if (isExcludedPath(source.path)) {
+      if (scanText(source.text).rewritten > 0) excluded.push(source.path)
+      if (movesTo !== undefined) {
+        entries.push({ path: source.path, movesTo, rewritten: 0, kept: 0 })
+      }
+      continue
+    }
+    const counts = scanText(source.text)
+    kept += counts.kept
+    globs += counts.globs
+    crossRepo += counts.crossRepo
+    dated += counts.dated
+    const held = frontmatterGlobLines(source.text)
+    if (held.length > 0)
+      frontmatterGlobs.push({ path: source.path, lines: held })
+    const foreign = crossRepoLines(source.text)
+    if (foreign.length > 0)
+      crossRepoCitations.push({ path: source.path, lines: foreign })
+    const dates = datedLines(source.text)
+    if (dates.length > 0)
+      datedCitations.push({ path: source.path, lines: dates })
+    const changed = counts.rewritten > 0
+    if (!changed && movesTo === undefined) continue
+    if (changed && referencesExcluded(source.text)) coupled.push(source.path)
+    entries.push({
+      path: source.path,
+      ...(movesTo !== undefined ? { movesTo } : {}),
+      ...(changed ? { text: rewriteText(source.text) } : {}),
+      rewritten: counts.rewritten,
+      kept: counts.kept,
+    })
+  }
+  return {
+    entries,
+    excluded,
+    coupled,
+    frontmatterGlobs,
+    crossRepoCitations,
+    datedCitations,
+    rewritten: entries.reduce((sum, entry) => sum + entry.rewritten, 0),
+    kept,
+    globs,
+    crossRepo,
+    dated,
+    moves: entries.filter((entry) => entry.movesTo !== undefined).length,
+  }
+}