@erclx/canon 4.77.0 → 4.79.0

package/src/migrate/surface-roots.ts

@@ -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,
+  }
+}

package/src/record-root.ts

@@ -52,10 +52,12 @@ const CANON_SCRATCH = 'tmp'
  * writes back. `worktrees` is absent because the harness creates a worktree
  * under `.claude/` and requires its target to sit there.
  *
- * Everything absent from this list is committed and stays where it is, which is
- * the rule the move ran on. `context`, `rules`, `skills`, `hooks`, `wireframes`,
- * and the loose documents at the root are all in that set, which is why a seed
- * and a superseded-layout report each ask this rather than assuming a root.
+ * Everything absent from this list is committed and never lands under the
+ * record root, which is the rule the move ran on. `rules`, `skills`, and
+ * `hooks` stay under `.claude/` because the vendor reads them there, while
+ * `context`, `wireframes`, and the loose documents are tracked surfaces that
+ * `surface-root.ts` resolves under `canon/` instead. A seed and a
+ * superseded-layout report each ask this rather than assuming a root.
  */
 export const RECORD_ENTRIES: readonly string[] = [
   '.records.git',

package/src/sandbox/census.ts

@@ -69,7 +69,7 @@ export function listSkills(root: string): string[] {
 /**
  * Maps a scenario to the skill it drives, trying two spellings in order.
  *
- * `<category>-<command>` is the rule `.claude/context/sandbox/coverage.md` states, and it
+ * `<category>-<command>` is the rule `canon/context/sandbox/coverage.md` states, and it
  * alone pairs 29 of 54 skills. The bare `<command>` fallback is what reaches the
  * rest: `claude/setup-init.sh` drives the `setup-init` skill, not a
  * `claude-setup-init` that does not exist. Stating one spelling and shipping two

package/src/shipped/references.ts

@@ -139,10 +139,10 @@ const SAME_REPOSITORY =
  * named a target's own tree, measured on 2026-09-03. Resolving against `root`
  * is what turns that 124-hit pattern into the four-hit gate.
  *
- * `.claude/context/` carries no equivalent pattern. The same resolution test
+ * `canon/context/` carries no equivalent pattern. The same resolution test
  * cannot separate a path every scaffolded project holds, such as
- * `.claude/context/index.md`, from this repository's own domain entry, such
- * as `.claude/context/indexes.md`, since both resolve here and only the
+ * `canon/context/index.md`, from this repository's own domain entry, such
+ * as `canon/context/indexes.md`, since both resolve here and only the
  * second is a defect. That is a semantic read no pattern makes, so it stays
  * with the rule and the review checklist rather than joining this reader.
  */

package/src/surface-root.ts

@@ -23,13 +23,13 @@ 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.
+ * It agrees with the head of the read precedence. While the two disagreed,
+ * creation stayed at `.claude/` so nothing wrote a fresh tracked file under a
+ * root a target's installed binary could not resolve. A release carries the
+ * read side now, so a fresh project scaffolds one root and an unmoved one keeps
+ * resolving its own surfaces through the fallback above.
  */
-export const CREATION_ROOT: SurfaceRoot = '.claude'
+export const CREATION_ROOT: SurfaceRoot = 'canon'
 
 /**
  * Every tracked surface this module resolves, at the name `.claude/` gives it.
@@ -55,6 +55,18 @@ export function spell(root: SurfaceRoot, entry: string): string {
   return root === 'canon' && entry === 'canon' ? 'config' : entry
 }
 
+/**
+ * The creation default for one entry.
+ *
+ * The stamp folder keeps creating under `.claude/` until its own move lands,
+ * since the install stamp and the audits baseline still write there by a
+ * fixed path. A read resolving to `canon/config/` in a fresh project would
+ * answer from a folder nothing writes.
+ */
+function creationRootFor(entry: string): SurfaceRoot {
+  return entry === 'canon' ? '.claude' : CREATION_ROOT
+}
+
 /**
  * The root a surface resolves at: the first that carries it, and the creation
  * default when neither does.
@@ -63,7 +75,7 @@ function rootOf(root: string, entry: string): SurfaceRoot {
   return (
     SURFACE_ROOTS.find((candidate) =>
       existsSync(join(root, candidate, spell(candidate, entry))),
-    ) ?? CREATION_ROOT
+    ) ?? creationRootFor(entry)
   )
 }
 
@@ -82,6 +94,26 @@ export function surfaceDir(
   return join(root, at, spell(at, entry), ...rest)
 }
 
+/**
+ * Where a path authored at the `canon/` spelling lands under `root`.
+ *
+ * A seed tree authors every surface once, at the new root, while a target may
+ * still hold that surface under `.claude/`. Writing the literal path there
+ * would open a `canon/` copy that wins read precedence and hides every entry
+ * the target already wrote, so the entry resolves the way a read does. A path
+ * naming no surface entry is joined as written.
+ */
+export function resolveSurfacePath(root: string, rel: string): string {
+  const [head, entry, ...rest] = rel.split(/[\\/]/)
+
+  if (head !== 'canon' || entry === undefined || entry === 'canon') {
+    return join(root, rel)
+  }
+  if (!SURFACE_ENTRIES.includes(entry)) return join(root, rel)
+
+  return surfaceDir(root, entry, ...rest)
+}
+
 /**
  * Every root a surface would be read at, in precedence order, whether or not
  * it is on disk.

package/src/sync/layout.ts

@@ -1,7 +1,8 @@
 import { existsSync, statSync } from 'node:fs'
-import { basename, join } from 'node:path'
+import { basename, join, relative } from 'node:path'
 import { SUBDIRS } from '@/claude/seeds'
 import { creationRel, isRecordEntry } from '@/record-root'
+import { SURFACE_ENTRIES, surfaceDir } from '@/surface-root'
 import type { StampDomain } from '@/sync/stamp'
 
 const CLAUDE_DIR = '.claude'
@@ -70,13 +71,16 @@ export function collectSuperseded(target: string): SupersededEntry[] {
     const rel = join(CLAUDE_DIR, `${subdir.toUpperCase()}.md`)
     if (!isFile(join(target, rel))) continue
 
-    // A record subdir now lives under the record root, so the replacement this
-    // names is resolved against the target rather than fixed at `.claude/`.
-    // Naming a folder the target does not have sends a person to migrate their
-    // legacy file into a path nothing reads.
+    // A record subdir lives under the record root and a tracked surface under
+    // the surface root, so the replacement this names is resolved against the
+    // target rather than fixed at `.claude/`. Naming a folder the target does
+    // not have sends a person to migrate their legacy file into a path nothing
+    // reads.
     const replacedBy = isRecordEntry(subdir)
       ? creationRel(target, subdir)
-      : join(CLAUDE_DIR, subdir)
+      : SURFACE_ENTRIES.includes(subdir)
+        ? relative(target, surfaceDir(target, subdir))
+        : join(CLAUDE_DIR, subdir)
 
     entries.push({ rel, replacedBy })
   }

package/src/sync/reverse.ts

@@ -234,7 +234,7 @@ export function detectMigrations(target: string): MigrationCandidate[] {
   if (docs > 0 && context === 0) {
     found.push({
       skill: 'migration-context',
-      reason: `${docs} markdown files under docs/ with no .claude/context/ tier`,
+      reason: `${docs} markdown files under docs/ with no canon/context/ tier`,
     })
   }
 

package/src/tooling/inject.ts

@@ -1,9 +1,10 @@
 import { existsSync } from 'node:fs'
 import { copyFile, mkdir, readFile, writeFile } from 'node:fs/promises'
-import { dirname, join } from 'node:path'
+import { dirname, join, relative } from 'node:path'
 import { $ } from 'bun'
 import { copyPreservingMode } from '@/copy'
 import { rewritesOnInstall, stripSeedMarker } from '@/seed-marker'
+import { resolveSurfacePath } from '@/surface-root'
 import { mergeSections, pruneSections } from '@/tooling/gitignore'
 import { ancestorsFirst, listFiles, type Manifest } from '@/tooling/manifest'
 import {
@@ -92,8 +93,9 @@ export async function injectSeeds(
 
     logStep(`Applying ${manifest.name} seeds`)
     for (const rel of files) {
-      await mergeSeedFile(join(manifest.seedsDir, rel), join(target, rel))
-      logAdd(rel)
+      const dest = resolveSurfacePath(target, rel)
+      await mergeSeedFile(join(manifest.seedsDir, rel), dest)
+      logAdd(relative(target, dest))
       applied.push(rel)
     }
   }

package/src/tooling/scan.ts

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
+import { resolveSurfacePath } from '@/surface-root'
 import { mergeSections } from '@/tooling/gitignore'
 import { ancestorsFirst, listFiles, type Manifest } from '@/tooling/manifest'
 import {
@@ -79,7 +80,9 @@ export function scan(chain: readonly Manifest[], target: string): ScanResult {
 
       seeds.push({
         rel,
-        state: existsSync(join(target, rel)) ? 'present' : 'missing',
+        state: existsSync(resolveSurfacePath(target, rel))
+          ? 'present'
+          : 'missing',
       })
     }
   }