@erclx/aitk 0.45.0 → 0.46.1

package/README.md

@@ -21,7 +21,7 @@ claude plugin install aitk@aitk
 
 ![Adding the aitk marketplace and installing the plugin in Claude Code](assets/install.png)
 
-The skills land as `/aitk:<name>`. If your session was already open, run `/reload-plugins` to pick them up. Updates arrive on release, so a push to this repo won't reach your installed copy.
+The skills land as `/aitk:<name>`. If your session was already open, run `/reload-plugins` to pick them up.
 
 Several skills call the `aitk` CLI to read catalogs and run installs, and the plugin doesn't put it on your path. Install it from the registry.
 
@@ -31,6 +31,20 @@ bun install --global @erclx/aitk
 
 [Bun](https://bun.sh) is the CLI runtime and has to be on your path first. Confirm the install by resolving `aitk --help`.
 
+## Update
+
+Nothing refreshes on its own. Claude Code ships auto-update off for third-party marketplaces, so an installed copy serves whatever version it was installed at until you refresh it.
+
+```bash
+claude plugin marketplace update aitk
+claude plugin update aitk@aitk
+bun install --global @erclx/aitk
+```
+
+The first two update the skills, the third updates the CLI, and they move independently. Restart Claude Code, or run `/reload-plugins`, to pick the skills up.
+
+To stop doing this by hand, turn auto-update on once under `/plugin` in the Marketplaces tab. Confirm what you are running with `aitk --version` and `claude plugin list`.
+
 ## Why
 
 Every AI coding setup accumulates the same assets. Prompts to reuse, rules agents should follow, slash commands, skills, seed docs, sync scripts. Once you have enough projects, your copies drift and your agents stop getting consistent signals.

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

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

package/claude/skills/claude-seed-sync/REQUIREMENT.md

@@ -17,7 +17,9 @@ Two failures belong to the audit rather than to the diff. A decision taken in ch
 
 - Read seed and standard content from the CLI rather than holding a copy, so the audit and the install cannot disagree
 - Diff per section, treating the preamble as a section of its own
-- Separate a customized section from a stale one, and default the customized one to no action
+- Separate a customized section from a stale one by reading the attribution the drift report records, not by how the section looks, and default the customized one to no action
+- Fall back to appearance only when attribution is unavailable, and mark every verdict reached that way as unverified
+- Leave a file the report proves untouched to the bulk sync that owns it, rather than auditing what carries no edits
 - Persist the proposal and every decision to a review file that stays the source of truth across re-pings
 - Apply one section at a time, never by rewriting a file
 

package/claude/skills/claude-seed-sync/SKILL.md

@@ -12,19 +12,30 @@ Surfaces drift between the toolkit's current seed docs and what was installed in
 - If the `aitk` CLI is not on PATH, stop: `❌ aitk CLI not found. Install the toolkit first.`
 - If no `.claude/` directory exists at the project root, stop: `❌ No .claude/ directory found. Run aitk claude init first.`
 
-## Step 1: read toolkit sources
+## Step 1: read toolkit sources and the drift report
 
-Run both in parallel from the project root:
+Run all three in parallel from the project root:
 
 ```bash
 aitk claude seeds list --json 2>/dev/null
 aitk standards list --json 2>/dev/null
+aitk sync --check . --json 2>/dev/null
 ```
 
 Seeds emit an array of `{name, source, target, content}`. Standards emit `{standards: [{name, description, target, content}]}`. In both cases `target` is the path relative to the project root where the file installs. Merge the two into one list of entries tagged by source (`seed` or `standard`).
 
 If the target project has no `.claude/standards/` directory, skip the standards stage silently.
 
+### Narrow the set by attribution
+
+The report is what separates a file the project edited from one the toolkit moved on without it. Read `seeds.entries` for seed paths and `domains[].entries` for standards, then drop from the merged list every entry the report attributes as `stale`. A stale file matches a version the toolkit published, so it carries no edits to lose and `aitk standards sync` takes it whole. Section-merging it is work with no decision behind it.
+
+Keep every seed regardless of state. `CLAUDE.md` is the file a project edits most, and its `drifted` verdict is the case this skill exists for.
+
+Record the dropped standards as one line in the scope table rather than as rows: `<n> standards stale, taken by aitk standards sync`.
+
+Fall back to the appearance heuristic in step 3 when the report cannot attribute, which is `historyUnavailable` set on the relevant section or the command failing outright. Say so in the summary block, because a fallback audit reports guesses rather than facts.
+
 ## Step 2: read installed copies
 
 For each entry in the merged list, read the file at its `target` path from the project root. Run reads in parallel. Mark missing files for **Add** treatment. Skip non-text seeds (`.json`) for section diffing. Record a one-line note in the scope table that the user can compare manually.
@@ -41,8 +52,9 @@ For each seed file present in both sides, parse the body into a preamble (everyt
 - **Toolkit-only section** (present in source, absent in target): candidate to **Add**.
 - **Target-only section** (present in target, absent in source): preserve, never propose removal. These are user customizations.
 - **Drifted section** (present in both, content differs): candidate to **Update**.
-  - If the target version looks customized (extra bullets, project-specific paths, filled-in placeholders), call it out as **Customized**. Default action: skip, record in the scope table only, never numbered.
-  - If the target version looks like the original toolkit version with the toolkit having moved on, call it out as **Stale**. Default action: propose update.
+  - Read the file's verdict from the report rather than judging it by eye. `drifted` means the content matches no version the toolkit ever published, so the project wrote it: call it **Customized**, default to skip, record in the scope table only, never numbered.
+  - `stale` at the file level means the toolkit moved and the project did not, so any section differing inside it is **Stale**. Default action: propose update.
+  - Only when the report could not attribute the file, judge by appearance: a version carrying extra bullets, project-specific paths, or filled-in placeholders reads as **Customized**, and one reading like the original toolkit text reads as **Stale**. Mark every verdict reached this way as unverified in the proposal.
 
 The user judges intent. The skill makes the judgment legible.
 

package/claude/skills/toolkit-operator/SKILL.md

@@ -18,9 +18,26 @@ Run these from the target project root, in parallel, before acting:
 
 Load a domain doc with `aitk docs <topic>` only when the intent touches that domain. Read the live catalog for any domain you act on with `aitk <domain> list --json`. Never hardcode stack, rule, snippet, or standards names.
 
+## Diagnose
+
+Run `aitk sync --check . --json` before routing. It reports what a target is behind on across every surface, so the intent comes from the project state rather than from the user having to know it already. Skip only when the user named a single operation to run.
+
+Read five fields off the report and carry each to `## Route`:
+
+- `unmigrated`: a domain sitting at the root layout with nothing under `.claude/`. The most urgent finding, because that domain reports no drift of its own while being entirely behind
+- `superseded`: a file a newer seed folder replaced. Report it and stop. No command moves it, since the content is the project's own
+- `seeds`: entries are `matching`, `stale`, `drifted`, or `missing`. Anything but `matching` needs the seed handoff
+- `domains[].entries`: per-file `stale`, `customized`, `stranded`, and `orphaned` as before
+- `historyUnavailable` on a domain or on `seeds`: attribution failed, so treat every difference as unverified and say so rather than reporting a file as untouched
+
+State what the report found in one line per finding before acting on any of it.
+
 ## Route
 
-Map the stated intent to one lifecycle phase, then act:
+Map the stated intent, or what `## Diagnose` found, to one lifecycle phase, then act:
+
+- A domain in `unmigrated`: hand off to `migration-standards`
+- Anything in `superseded`: tell the user which files and what replaced them. Do not move or delete them
 
 - First-time scaffold of a fresh project: hand off to `setup-init`
 - Governance rules for the project stack: hand off to `setup-gov`

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

@@ -117,6 +117,52 @@ commits touching its own source path. The `covers` field names the domains a
 target has actually stamped, so a domain that was never stamped is legible
 rather than reading as a clean one.
 
+### Surfaces reported beside the domains
+
+Three sections sit outside the per-domain scan, because each names something
+that walk cannot see. None of them produces a change, and no sync command
+applies any of them.
+
+All three report only against a toolkit-managed target, which is one carrying a
+`.claude/` directory, a `CLAUDE.md`, or a domain still at the root layout. The
+report says so through `managed` in the JSON and routes an unmanaged directory to
+`aitk init`. Seeds are why the gate exists, since they enumerate from the toolkit
+source rather than from what a target installed, so an unmanaged directory would
+otherwise report every seed as `missing`.
+
+A root-layout domain counts as a marker on its own, because the detection fires
+only on root files the toolkit ships and a project in the old layout is one the
+toolkit installed. When `managed` is false every section comes back empty rather
+than the render alone going quiet, so a consumer reading `--json` never acts on a
+finding the rendered half withheld.
+
+`seeds` classifies every seed the toolkit ships against the target's copy, as
+`matching`, `stale`, `drifted`, or `missing`. `missing` has no per-domain
+equivalent, since the domain walk lists what a target installed and cannot see a
+file that never arrived. There is no `customized` verdict here, because that one
+needs a stamp and seeds carry none, so a file history cannot attribute stays
+`drifted`. Reconcile the section with `claude-seed-sync`, which merges one
+section at a time rather than replacing a file the project edits.
+
+`superseded` names a file a newer seed folder replaced, such as `.claude/TASKS.md`
+against the `.claude/tasks/` that now ships. The entry carries `replacedBy` and
+nothing else, and the file is never deleted, since the content belongs to the
+project and only its author can decide where it moves. The list derives from the
+seed tree rather than from a fixed set of filenames, so a folder added later is
+covered without a code change. Only an exact stem matches, which leaves a
+suffixed variant such as `TASKS-ARCHIVE.md` unreported.
+
+`unmigrated` names a domain sitting at the root layout an older toolkit installed
+to, with nothing at the path the current one reads. It carries `rootPath`,
+`installPath`, and a file count. Without it a project holding `standards/` at its
+root reports zero entries for that domain and reads as clean, which is the most
+misleading state the report can produce. Route it to `migration-standards`.
+
+`unmigrated` counts toward `--exit-code`, since running the relocation closes it.
+`superseded` and every seed state are excluded, for the reason `orphaned` already
+is: only the user can move content they wrote, so failing a job on it leaves the
+job red with no mechanical remedy.
+
 ## Bootstrap
 
 `aitk init` installs up to six core domains and reports each one independently. A

package/docs/target-projects.md

@@ -12,7 +12,7 @@ This doc stays at the narrative layer. For command flags and JSON shapes, see [a
 
 ## Getting the skills
 
-The skills reach a session through a marketplace install, once per machine. Every session on that machine carries them afterward, and updates arrive on release, so an upstream push does not reach an installed copy.
+The skills reach a session through a marketplace install, once per machine. Every session on that machine carries them afterward, and the installed copy stays at the version it was installed at. Claude Code ships auto-update off for third-party marketplaces, so neither a push nor a release reaches that copy until someone refreshes it with `claude plugin marketplace update aitk` followed by `claude plugin update aitk@aitk`, or turns auto-update on once under `/plugin`. The `aitk` CLI moves on its own schedule through the registry, so a machine can hold current skills against a stale CLI or the reverse.
 
 ```bash
 claude plugin marketplace add https://github.com/erclx/aitk
@@ -104,7 +104,11 @@ That attribution comes from `.claude/aitk.json`, a stamp every install and sync
 
 A project that has never synced under a toolkit new enough to write a stamp falls back to the toolkit's own git history. Installed content matching any version that history published proves the file untouched, so it reports `stale` naming the commit it came from, and content matching no published version stays `drifted`. That fallback needs the toolkit as a git checkout. Installed from the registry it ships source without history, and the report says attribution was unavailable rather than reading every file as a local edit.
 
-Add `--json` for the machine-readable report, and `--exit-code` to fail a CI job when a target falls behind. Files the project authored itself never count toward that exit code.
+Three further causes sit outside the per-domain scan, each naming something that walk cannot see. A seed the project edited is reported under `seeds` and reconciled with `aitk:claude-seed-sync`, since no sync command touches a seed. A file a newer seed folder replaced is reported under `superseded`, such as `.claude/TASKS.md` against the `.claude/tasks/` that now ships, and nothing moves it because the content is the project's own. A domain sitting at the root layout with nothing under `.claude/` is reported under `unmigrated` and handed to `aitk:migration-standards`.
+
+That last one matters most on an older project. Before it existed, a target holding `standards/` at its root reported zero entries for that domain, so a project that had never migrated was indistinguishable from one that was fully current.
+
+Add `--json` for the machine-readable report, and `--exit-code` to fail a CI job when a target falls behind. Files the project authored itself never count toward that exit code, and neither do superseded artifacts or seed drift, since both need the user to move content only they can place. An unmigrated domain does count, because running the relocation closes it.
 
 Tooling is not covered by the stamp. Reconcile those configs with `aitk tooling <stack> <path>`.
 

package/package.json

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

package/src/claude/seeds.ts

@@ -7,7 +7,12 @@ const SEEDS_DIR = join('tooling', 'claude', 'seeds')
 const CLAUDE_DIR = '.claude'
 const CLAUDE_MD = 'CLAUDE.md'
 const HOOKS = 'hooks'
-const SUBDIRS: readonly string[] = [
+/**
+ * Seed subdirectories under `.claude/`. Exported because each one replaced a
+ * single file of the same stem in an older layout, which is what
+ * `@/sync/layout` pairs a target against to find a superseded artifact.
+ */
+export const SUBDIRS: readonly string[] = [
   HOOKS,
   'context',
   'diagrams',

package/src/cli.ts

@@ -1,5 +1,7 @@
 #!/usr/bin/env bun
 
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
 import { Command } from 'commander'
 import { register as init } from '@/commands/init'
 import { register as sandbox } from '@/commands/sandbox'
@@ -20,6 +22,7 @@ import { register as transcripts } from '@/commands/transcripts'
 import { register as tasks } from '@/commands/tasks'
 import { register as comments } from '@/commands/comments'
 import { register as context } from '@/commands/context'
+import { PROJECT_ROOT } from '@/exec'
 
 const GREY = '\x1b[0;90m'
 const WHITE = '\x1b[1;37m'
@@ -87,10 +90,26 @@ function showHelp(): void {
   console.log(lines.join('\n'))
 }
 
+/**
+ * Read at runtime rather than inlined, because a literal here is a second place
+ * the version lives and it stopped tracking `package.json` at `0.1.0`. The
+ * release tool writes one file and this follows it. `package.json` ships in
+ * every npm tarball regardless of the `files` list, so the read resolves from a
+ * registry install as well as from a clone.
+ */
+function readVersion(): string {
+  try {
+    const raw = readFileSync(join(PROJECT_ROOT, 'package.json'), 'utf8')
+    return (JSON.parse(raw) as { version?: string }).version ?? 'unknown'
+  } catch {
+    return 'unknown'
+  }
+}
+
 const program = new Command()
 program
   .name('aitk')
-  .version('0.1.0')
+  .version(readVersion())
   .enablePositionalOptions()
   .helpOption(false)
 program.action(() => showHelp())

package/src/commands/sync.ts

@@ -95,6 +95,16 @@ async function runCheck(target: string, options: SyncOptions): Promise<number> {
 function renderCheck(report: CheckReport): void {
   intro('aitk sync --check')
 
+  if (!report.managed) {
+    logStep('Not a toolkit project')
+    logWarn('No .claude/ directory and no CLAUDE.md at the target.')
+    logInfo(
+      'Run `aitk init` to install, or /aitk:setup-init to resolve a stack.',
+    )
+    outro()
+    return
+  }
+
   for (const domain of report.domains) {
     logStep(domain.domain)
 
@@ -123,14 +133,33 @@ function renderCheck(report: CheckReport): void {
     }
   }
 
+  for (const entry of report.unmigrated) {
+    logStep(`${entry.domain} (not migrated)`)
+    logWarn(
+      `${entry.files} files at ${entry.rootPath}/, nothing at ${entry.installPath}/`,
+    )
+    logInfo('Run /aitk:migration-standards to relocate them.')
+  }
+
+  renderSeeds(report)
+
+  if (report.superseded.length > 0) {
+    logStep('Superseded by a newer layout')
+    for (const entry of report.superseded) {
+      logWarn(`${entry.rel} (replaced by ${entry.replacedBy}/)`)
+    }
+    logInfo('Move the content yourself. No sync command touches these.')
+  }
+
   if (report.newSkills.length > 0) {
     logStep('New skills, no sync needed')
     for (const name of report.newSkills) logInfo(name)
   }
 
   outro()
+  const unmigrated = report.unmigrated.map((entry) => entry.domain)
   const uncovered = STAMP_DOMAINS.filter(
-    (domain) => !report.covers.includes(domain),
+    (domain) => !report.covers.includes(domain) && !unmigrated.includes(domain),
   )
   const unstamped =
     uncovered.length === 0 ? '' : `Unstamped: ${uncovered.join(', ')}. `
@@ -139,6 +168,30 @@ function renderCheck(report: CheckReport): void {
   )
 }
 
+/**
+ * Seeds print their own section because no sync command applies them. A `stale`
+ * seed is safe to take whole and a `drifted` one holds edits, which is the split
+ * `claude-seed-sync` reads to decide what needs a section-level merge.
+ */
+function renderSeeds(report: CheckReport): void {
+  const notable = report.seeds.entries.filter(
+    (entry) => entry.state !== 'matching',
+  )
+
+  if (notable.length === 0) return
+
+  logStep('seeds')
+  if (report.seeds.historyUnavailable) {
+    logWarn('This toolkit has no git history. Drift below is unattributed.')
+  }
+
+  for (const entry of notable) {
+    logWarn(`${entry.rel} (${entry.state})`)
+  }
+
+  logInfo('Run /aitk:claude-seed-sync to reconcile these section by section.')
+}
+
 async function runSync(target: string): Promise<number> {
   intro('aitk sync')
 

package/src/sync/check.ts

@@ -1,8 +1,16 @@
+import { existsSync } from 'node:fs'
 import { join } from 'node:path'
 import { execa } from 'execa'
 import { createGovAdapter } from '@/gov/adapter'
 import { createSnippetsAdapter } from '@/snippets/adapter'
 import { planSync, type ScanEntry, type SyncAdapter } from '@/sync/engine'
+import {
+  collectSuperseded,
+  detectUnmigrated,
+  type SupersededEntry,
+  type UnmigratedDomain,
+} from '@/sync/layout'
+import { buildSeedsReport, type SeedsReport } from '@/sync/seeds-report'
 import {
   readStamp,
   STAMP_DOMAINS,
@@ -68,7 +76,16 @@ export interface UpstreamCommit {
 
 export interface CheckReport {
   readonly covers: readonly StampDomain[]
+  /** False when the target is not a toolkit project, so every section stays empty. */
+  readonly managed: boolean
   readonly domains: readonly DomainReport[]
+  /**
+   * Reported beside the domains rather than as one of them, because seeds carry
+   * no stamp and produce no change. See `@/sync/seeds-report`.
+   */
+  readonly seeds: SeedsReport
+  readonly superseded: readonly SupersededEntry[]
+  readonly unmigrated: readonly UnmigratedDomain[]
   readonly newSkills: readonly string[]
 }
 
@@ -78,6 +95,33 @@ export function installedStampDomains(target: string): StampDomain[] {
   )
 }
 
+/**
+ * Whether the target is a toolkit-managed project at all. Seeds are enumerated
+ * from the source rather than from what a target installed, so without this gate
+ * a directory the toolkit has never touched reports every seed as `missing` and
+ * routes to a skill that reconciles section by section. `installedStampDomains`
+ * gates the three scanned domains the same way, which is why they stay quiet on
+ * the same directory.
+ *
+ * An unmigrated domain counts as a marker in its own right. `detectUnmigrated`
+ * fires only on root files whose basename the toolkit ships, so it firing proves
+ * the toolkit installed here before the layout moved under `.claude/`. Reading
+ * only the markers would report such a target as unmanaged while the same report
+ * carried its unmigrated domain, and a consumer reading the JSON would route to
+ * the relocation while the rendered half routed to install.
+ */
+export function isManagedTarget(
+  target: string,
+  unmigrated: readonly UnmigratedDomain[],
+): boolean {
+  if (unmigrated.length > 0) return true
+
+  return (
+    isDirectory(join(target, '.claude')) ||
+    existsSync(join(target, 'CLAUDE.md'))
+  )
+}
+
 export function countStates(entries: readonly ScanEntry[]): StateCounts {
   return {
     matching: count(entries, 'matching'),
@@ -93,8 +137,16 @@ export function countStates(entries: readonly ScanEntry[]): StateCounts {
  * Whether the target has diverged from the toolkit in a way a sync could close.
  * Orphaned files are excluded: a project-authored rule never converges, and
  * counting it would leave `--exit-code` failing forever with no remedy.
+ *
+ * An unmigrated domain counts, because running the relocation closes it. A
+ * superseded artifact does not, for the same reason orphaned files do not: only
+ * the user can move content they wrote, so failing a job on it leaves the job
+ * red with no mechanical remedy. Seeds are excluded on the same grounds, since
+ * every seed a project edits would otherwise fail the check forever.
  */
 export function hasDrift(report: CheckReport): boolean {
+  if (report.unmigrated.length > 0) return true
+
   return report.domains.some(
     (domain) =>
       domain.counts.stale +
@@ -126,9 +178,28 @@ export async function buildCheckReport(
     .map((domain) => domain.commit)
     .filter((commit): commit is string => commit !== undefined)
 
+  const unmigrated = detectUnmigrated(toolkitRoot, target)
+  const managed = isManagedTarget(target, unmigrated)
+
+  if (!managed) {
+    return {
+      covers: [],
+      managed,
+      domains: [],
+      seeds: { entries: [], historyUnavailable: false },
+      superseded: [],
+      unmigrated: [],
+      newSkills: [],
+    }
+  }
+
   return {
     covers: stamp?.covers ?? [],
+    managed,
     domains,
+    seeds: buildSeedsReport(toolkitRoot, target),
+    superseded: collectSuperseded(target),
+    unmigrated,
     newSkills: await readNewSkills(toolkitRoot, anchors),
   }
 }

package/src/sync/layout.ts

@@ -0,0 +1,139 @@
+import { existsSync, statSync } from 'node:fs'
+import { basename, join } from 'node:path'
+import { SUBDIRS } from '@/claude/seeds'
+import { snippetsSourceDir } from '@/snippets/categories'
+import { standardsSourceDir } from '@/standards/adapter'
+import type { StampDomain } from '@/sync/stamp'
+
+const CLAUDE_DIR = '.claude'
+
+/**
+ * Domains an older toolkit installed at the project root, each with the source
+ * folder naming what it owns. Governance is absent because its rules have always
+ * landed under `.claude/rules/`, so there is no earlier location to be stranded
+ * at.
+ *
+ * A tuple array rather than a partial record, so the domain key stays typed
+ * without asserting an `Object.entries` result back into the union.
+ */
+const ROOT_LAYOUTS: readonly (readonly [
+  StampDomain,
+  string,
+  (root: string) => string,
+])[] = [
+  ['standards', 'standards', standardsSourceDir],
+  ['snippets', 'snippets', snippetsSourceDir],
+]
+
+/**
+ * A target file that a shipped seed folder replaced. Carries no source and
+ * queues no change, because the file holds content the project wrote and only
+ * the user can decide where it moves.
+ */
+export interface SupersededEntry {
+  readonly rel: string
+  readonly replacedBy: string
+}
+
+/**
+ * A domain whose files sit at the root layout an older toolkit installed to,
+ * with nothing at the path the current one reads. Distinct from a domain that
+ * was never installed, which has neither.
+ */
+export interface UnmigratedDomain {
+  readonly domain: StampDomain
+  readonly rootPath: string
+  readonly installPath: string
+  /** Root files the toolkit ships under this domain, not every file present. */
+  readonly files: number
+}
+
+/**
+ * Pairs each seed subdirectory against an uppercase-stem sibling in the target,
+ * so a project still holding `.claude/TASKS.md` is reported against the
+ * `.claude/tasks/` folder that replaced it.
+ *
+ * Deriving from the seed tree rather than from a fixed list means a folder
+ * added later is covered without editing this file. The cost is that only an
+ * exact stem matches, so a suffixed variant such as `TASKS-ARCHIVE.md` is not
+ * reported.
+ */
+export function collectSuperseded(target: string): SupersededEntry[] {
+  const entries: SupersededEntry[] = []
+
+  for (const subdir of SUBDIRS) {
+    const rel = join(CLAUDE_DIR, `${subdir.toUpperCase()}.md`)
+    if (!isFile(join(target, rel))) continue
+
+    entries.push({ rel, replacedBy: join(CLAUDE_DIR, subdir) })
+  }
+
+  return entries
+}
+
+/**
+ * Domains the target holds at the root rather than under `.claude/`. Reported
+ * separately from the per-domain scan because that scan lists only domains it
+ * finds installed, so an unmigrated project would otherwise read as one that
+ * never installed the domain at all.
+ *
+ * A root folder is claimed only when it holds a file the toolkit ships under
+ * that domain. Presence of the folder alone is not evidence: a project can
+ * carry its own `standards/` of project docs and never have installed the
+ * domain, and calling that unmigrated would fail `--exit-code` with no action
+ * that clears it.
+ */
+export function detectUnmigrated(
+  toolkitRoot: string,
+  target: string,
+): UnmigratedDomain[] {
+  const found: UnmigratedDomain[] = []
+
+  for (const [domain, rootPath, sourceDir] of ROOT_LAYOUTS) {
+    const installPath = join(CLAUDE_DIR, rootPath)
+    if (isDirectoryWithFiles(join(target, installPath))) continue
+
+    const files = countToolkitOwned(
+      join(target, rootPath),
+      sourceDir(toolkitRoot),
+    )
+    if (files === 0) continue
+
+    found.push({ domain, rootPath, installPath, files })
+  }
+
+  return found
+}
+
+/**
+ * Root files whose basename matches something the toolkit ships for this domain.
+ * Basenames rather than relative paths, because standards install flat while
+ * snippets nest by category, and the question here is only whether any file is
+ * toolkit-owned rather than which source each one came from.
+ */
+function countToolkitOwned(dir: string, sourceDir: string): number {
+  const owned = new Set(listMarkdown(sourceDir).map((rel) => basename(rel)))
+  if (owned.size === 0) return 0
+
+  return listMarkdown(dir).filter((rel) => owned.has(basename(rel))).length
+}
+
+function isFile(path: string): boolean {
+  return existsSync(path) && statSync(path).isFile()
+}
+
+function isDirectoryWithFiles(path: string): boolean {
+  return listMarkdown(path).length > 0
+}
+
+function listMarkdown(dir: string): string[] {
+  if (!existsSync(dir) || !statSync(dir).isDirectory()) return []
+
+  return [
+    ...new Bun.Glob('**/*.md').scanSync({
+      cwd: dir,
+      onlyFiles: true,
+      dot: true,
+    }),
+  ]
+}

package/src/sync/seeds-report.ts

@@ -0,0 +1,111 @@
+import { readFileSync } from 'node:fs'
+import { relative } from 'node:path'
+import { planSeeds, type Seed } from '@/claude/seeds'
+import { findInstalledOrigin, readHistoryIndex } from '@/sync/history'
+
+/**
+ * How an installed seed compares to the seed the toolkit currently ships.
+ *
+ * `missing` has no counterpart in the domain scan, which walks what a target
+ * installed and so cannot see a file that never arrived. Seeds are enumerated
+ * from the source instead, which is what makes the absence legible.
+ *
+ * There is no `customized` here. That verdict needs a stamp, and seeds carry
+ * none, so a file history cannot attribute stays `drifted` and a consumer reads
+ * it as the local edit it almost always is.
+ */
+export type SeedState = 'matching' | 'stale' | 'drifted' | 'missing'
+
+export interface SeedReportEntry {
+  readonly state: SeedState
+  readonly rel: string
+  /** Toolkit revision this file's content came from, when history proved it. */
+  readonly since?: string
+}
+
+export interface SeedsReport {
+  readonly entries: readonly SeedReportEntry[]
+  /** Set when a file needed history to attribute it and this toolkit has none. */
+  readonly historyUnavailable: boolean
+}
+
+/**
+ * Classifies every seed the toolkit ships against the target's copy, and never
+ * returns a change. Seeds are copy-once files a project is expected to edit, so
+ * the engine's copy path would overwrite `CLAUDE.md` wholesale. Reporting alone
+ * is what lets `claude-seed-sync` merge one section at a time instead.
+ *
+ * Attribution reuses the history reader rather than the engine's own recovery
+ * pass, which is private and takes a `SyncAdapter` seeds have no way to supply.
+ */
+export function buildSeedsReport(
+  toolkitRoot: string,
+  target: string,
+): SeedsReport {
+  const differing: DifferingSeed[] = []
+  const entries: SeedReportEntry[] = []
+
+  for (const { seed, present } of planSeeds(toolkitRoot, target)) {
+    const rel = relative(target, seed.dest)
+
+    if (!present) {
+      entries.push({ state: 'missing', rel })
+      continue
+    }
+
+    if (sameContent(seed.src, seed.dest)) {
+      entries.push({ state: 'matching', rel })
+      continue
+    }
+
+    differing.push({ index: entries.length, seed })
+    entries.push({ state: 'drifted', rel })
+  }
+
+  const historyUnavailable = attribute(toolkitRoot, entries, differing)
+
+  return { entries, historyUnavailable }
+}
+
+interface DifferingSeed {
+  readonly index: number
+  readonly seed: Seed
+}
+
+/**
+ * Second pass over the seeds that differ, matching installed content against
+ * every version the toolkit ever published. A match proves the file is
+ * untouched since it landed, so the toolkit is what moved and the entry becomes
+ * `stale`. Runs as one git call for the whole set rather than one per file.
+ */
+function attribute(
+  toolkitRoot: string,
+  entries: SeedReportEntry[],
+  differing: readonly DifferingSeed[],
+): boolean {
+  if (differing.length === 0) return false
+
+  const index = readHistoryIndex(
+    toolkitRoot,
+    differing.map((file) => relative(toolkitRoot, file.seed.src)),
+  )
+
+  if (index === undefined) return true
+
+  for (const file of differing) {
+    const since = findInstalledOrigin(
+      index,
+      relative(toolkitRoot, file.seed.src),
+      file.seed.dest,
+    )
+
+    if (since === undefined) continue
+    entries[file.index] = { ...entries[file.index], state: 'stale', since }
+  }
+
+  return false
+}
+
+function sameContent(source: string, dest: string): boolean {
+  return readFileSync(source).equals(readFileSync(dest))
+}