@north-light/crouter 0.3.227 → 0.3.229

package/dist/commands/sys/__tests__/sync-project-guidance.test.js

@@ -0,0 +1,218 @@
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdtempSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import test from 'node:test';
+import { lintMemoryStore } from '../../../core/memory/lint.js';
+import { openProjectMemoryStore } from '../../../core/memory-resolver.js';
+const HERE = dirname(fileURLToPath(import.meta.url));
+const CLI = join(HERE, '../../../cli.ts');
+const TSX_LOADER = import.meta.resolve('tsx/esm');
+function write(path, content) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, content);
+}
+/** Store keys and target ids are realpaths, so the fixture must be one too:
+ *  macOS hands `mkdtemp` a `/var/folders` path whose realpath is `/private/...`. */
+function fixtureHome(prefix) {
+    return realpathSync(mkdtempSync(join(tmpdir(), prefix)));
+}
+/** A home the ambient node's own CRTR_* environment cannot leak into. */
+function syncEnv(home) {
+    const env = { ...process.env, HOME: home };
+    for (const key of Object.keys(env)) {
+        if (key.startsWith('CRTR_'))
+            delete env[key];
+    }
+    env['CRTR_NO_AUTO_INIT'] = '1';
+    env['CRTR_NO_AUTO_UPDATE'] = '1';
+    return env;
+}
+function runSyncRaw(home, opts = {}) {
+    const env = syncEnv(home);
+    if (opts.profileId !== undefined)
+        env['CRTR_PROFILE_ID'] = opts.profileId;
+    return spawnSync(process.execPath, [
+        '--conditions=crtr-src',
+        '--import',
+        TSX_LOADER,
+        CLI,
+        'sys',
+        'sync',
+        'project-guidance',
+        ...(opts.source === undefined ? [] : ['--source', opts.source]),
+        '--json',
+        ...(opts.overwrite === true ? ['--overwrite'] : []),
+    ], { cwd: opts.cwd ?? home, env, encoding: 'utf8' });
+}
+function runSync(home, opts = {}) {
+    const result = runSyncRaw(home, opts);
+    assert.equal(result.status, 0, `${result.stdout}\n${result.stderr}`);
+    return JSON.parse(result.stdout);
+}
+function initializeRepository(path) {
+    mkdirSync(path, { recursive: true });
+    const result = spawnSync('git', ['init', '--quiet', path], { encoding: 'utf8' });
+    assert.equal(result.status, 0, result.stderr);
+}
+function writeProfile(home, profileId, project) {
+    write(join(home, '.crouter', 'profiles', profileId, 'profile.json'), JSON.stringify({
+        schema_version: 4,
+        name: 'sync fixture',
+        projects: [{ path: realpathSync(project), memory: 'content' }],
+        home: realpathSync(project),
+        paused_at: null,
+        created_at: '2026-01-01T00:00:00.000Z',
+        last_used_at: null,
+    }));
+}
+test('sync project-guidance --overwrite preserves an authored root and still imports rules', () => {
+    const home = fixtureHome('crtr-sync-project-guidance-');
+    const project = join(home, 'my-project');
+    initializeRepository(project);
+    const authoredRoot = `---
+kind: knowledge
+namespace: my-project
+when-and-why-to-read: When working in my-project, this knowledge should be read because it holds hand-authored operating guidance.
+short-form: Hand-authored project guide, not migrated.
+surfaces:
+  - on: workspace-open
+    at: content
+  - on: read
+    match: ./**
+    at: content
+---
+# My Project
+
+This is the real, hand-written operating guide. It must survive a rules-only sync.
+`;
+    write(join(project, '.crouter', 'memory', 'INDEX.md'), authoredRoot);
+    write(join(project, '.claude', 'rules', 'lint.md'), `---
+description: Lint rules
+paths: "src/**/*.ts"
+---
+# Lint
+
+Run the linter before committing.
+`);
+    const before = readFileSync(join(project, '.crouter', 'memory', 'INDEX.md'), 'utf8');
+    const output = runSync(home, { source: project, overwrite: true });
+    const after = readFileSync(join(project, '.crouter', 'memory', 'INDEX.md'), 'utf8');
+    assert.equal(after, before, 'authored root must not be replaced by the synthetic placeholder');
+    const rootRow = output.results.find((r) => r.target.endsWith(join('.crouter', 'memory', 'INDEX.md')));
+    assert.equal(rootRow, undefined, 'an already-authored root must not appear as an import/skip row');
+    const ruleRow = output.results.find((r) => r.source.endsWith(join('.claude', 'rules', 'lint.md')));
+    assert.ok(ruleRow, 'the rule must still be imported');
+    assert.equal(ruleRow?.status, 'imported');
+    const ruleDoc = readFileSync(ruleRow.target, 'utf8');
+    assert.match(ruleDoc, /Run the linter before committing\./);
+});
+test('sync project-guidance writes one repository-root declaration for each repository', () => {
+    const home = fixtureHome('crtr-sync-project-guidance-');
+    const workspace = join(home, 'workspace');
+    const alpha = join(workspace, 'alpha-repository');
+    const beta = join(workspace, 'beta-repository');
+    initializeRepository(alpha);
+    initializeRepository(beta);
+    write(join(alpha, 'CLAUDE.md'), '# Alpha Repository\n');
+    write(join(beta, 'AGENTS.md'), '# Beta Repository\n');
+    const output = runSync(home, { source: workspace });
+    for (const [repository, namespace] of [[alpha, 'alpha-repository'], [beta, 'beta-repository']]) {
+        const declaration = join(repository, '.crouter', 'memory', 'INDEX.md');
+        assert.equal(existsSync(declaration), true, `the repository root owns ${namespace}'s declaration`);
+        assert.match(readFileSync(declaration, 'utf8'), new RegExp(`namespace: ${namespace}`));
+        assert.ok(output.results.some((row) => row.target === declaration && row.name === namespace));
+    }
+    assert.equal(output.results.filter((row) => row.target.endsWith(join('.crouter', 'memory', 'INDEX.md'))).length, 2);
+});
+test('sync project-guidance converts a nested guide without repository-root metadata', () => {
+    const home = fixtureHome('crtr-sync-project-guidance-');
+    const repository = join(home, 'nested-guide-repository');
+    const nested = join(repository, 'packages', 'tool');
+    initializeRepository(repository);
+    write(join(repository, 'CLAUDE.md'), '# Repository Guide\n');
+    write(join(nested, 'AGENTS.md'), `---
+surfaces:
+  - on: workspace-open
+    at: content
+  - on: read
+    match: ./**
+    at: content
+  - on: read
+    match: ./packages/tool/**/*.ts
+    at: content
+---
+# Nested Guide
+
+Nested operating guidance.
+`);
+    runSync(home, { source: repository });
+    const nestedIndex = readFileSync(join(nested, '.crouter', 'memory', 'INDEX.md'), 'utf8');
+    assert.match(nestedIndex, /kind: knowledge/);
+    assert.doesNotMatch(nestedIndex, /^namespace:/m);
+    assert.doesNotMatch(nestedIndex, /^name:/m);
+    assert.doesNotMatch(nestedIndex, /on: workspace-open/);
+    assert.match(nestedIndex, /when-and-why-to-read:/);
+    assert.match(nestedIndex, /on: read/);
+    assert.match(nestedIndex, /packages\/tool\/\*\*\/\*\.ts/);
+    assert.match(nestedIndex, /Nested operating guidance\./);
+    const lint = lintMemoryStore(openProjectMemoryStore(nested));
+    assert.equal(lint.ok, true, JSON.stringify(lint.findings));
+});
+test('sync project-guidance imports nested rules as leaves without a synthetic nested index', () => {
+    const home = fixtureHome('crtr-sync-project-guidance-');
+    const repository = join(home, 'nested-rules-repository');
+    const nested = join(repository, 'packages', 'tool');
+    initializeRepository(repository);
+    write(join(nested, '.claude', 'rules', 'lint.md'), `---
+description: Nested lint rules
+paths: "src/**/*.ts"
+---
+# Lint
+
+Run nested linting.
+`);
+    const output = runSync(home, { source: repository });
+    const nestedStore = join(nested, '.crouter', 'memory');
+    const rule = join(nestedStore, 'lint.md');
+    assert.equal(existsSync(join(repository, '.crouter', 'memory', 'INDEX.md')), true, 'the repository declaration is synthesized');
+    assert.equal(existsSync(rule), true);
+    assert.equal(existsSync(join(nestedStore, 'INDEX.md')), false, 'rules never synthesize a nested store root');
+    assert.ok(output.results.some((row) => row.target === rule && row.name === 'nested-rules-repository/packages/tool/lint'));
+});
+test('sync project-guidance rejects a nested authored namespace at the repository declaration path', () => {
+    const home = fixtureHome('crtr-sync-project-guidance-');
+    const repository = join(home, 'namespace-rejection-repository');
+    const nestedGuide = join(repository, 'packages', 'tool', 'AGENTS.md');
+    initializeRepository(repository);
+    write(join(repository, 'CLAUDE.md'), '# Repository Guide\n');
+    write(nestedGuide, '---\nnamespace: forbidden\n---\n# Nested Guide\n');
+    const result = runSyncRaw(home, { source: repository });
+    assert.notEqual(result.status, 0);
+    assert.match(result.stdout, new RegExp(`project guidance at ${nestedGuide} declares a namespace`));
+    assert.match(result.stdout, new RegExp(`${join(repository, '.crouter', 'memory', 'INDEX.md')} is the only declaration for this repository`));
+});
+test('sync project-guidance keeps canonical names stable across cwd, profile widening, and explicit source discovery', () => {
+    const names = [];
+    for (const context of ['cwd', 'profile', 'source']) {
+        const home = fixtureHome(`crtr-sync-project-guidance-${context}-`);
+        const repository = join(home, 'canonical-repository');
+        initializeRepository(repository);
+        write(join(repository, 'CLAUDE.md'), '# Canonical Repository\n');
+        const output = context === 'cwd'
+            ? runSync(home, { cwd: repository })
+            : context === 'profile'
+                ? (() => {
+                    const profileId = 'sync-fixture-12345678';
+                    writeProfile(home, profileId, repository);
+                    return runSync(home, { profileId });
+                })()
+                : runSync(home, { source: repository });
+        const root = output.results.find((row) => row.target === join(repository, '.crouter', 'memory', 'INDEX.md'));
+        assert.ok(root, `${context} discovers the repository root guide`);
+        names.push(root.name);
+    }
+    assert.deepEqual(names, ['canonical-repository', 'canonical-repository', 'canonical-repository']);
+});

package/dist/commands/sys/migrate.js

@@ -1,172 +1,158 @@
-// `crtr sys migrate` — the on-disk state-migration runner: converge every
-// stored profile manifest to the current manifest format, then every writable
-// memory store's documents to the current document format. (Journaled
-// canvas-db migrations run in the db's own ordered chain when the daemon opens
-// it; this leaf owns only the on-disk state.)
-//
-// Manifests come FIRST and are read as raw bytes under the profile lock: the
-// current reader treats a pre-migration manifest exactly like corrupt JSON, so
-// `listProfiles()` sees nothing until this lane has run. Store discovery below
-// therefore works from the lane's post-migration snapshots — which are equally
-// coherent under `--dry-run`, where the same fold ran and nothing was written.
-import { dirname, join } from 'node:path';
+// `crtr sys migrate` formats the shared on-disk migration runner's result.
+// Journaled canvas-db migrations remain in the database's ordered chain.
 import { defineLeaf } from '../../core/command.js';
-import { pathExists, realpathOrSelf } from '../../core/fs-utils.js';
-import { createMemoryDocSnapshot } from '../../core/memory-resolver.js';
-import { listInstalledPlugins, listInstalledPluginsInRoot } from '../../core/resolver.js';
-import { pluginMemoryDir, projectScopeRoots, scopeMemoryDir } from '../../core/scope.js';
-import { profileMemoryDir, profilesRoot, withProfileManifestLock } from '../../core/profiles/manifest.js';
-import { descendantStoreRootsExhaustive } from '../../core/nested-stores.js';
-import { memoryDir as nodeMemoryDir } from '../../core/runtime/memory.js';
-import { runConvergentMigrations } from '../../migrations/convergent.js';
-import { runProfileManifestMigrations } from '../../migrations/profile-manifests.js';
-function targetKey(target) {
-    return `${realpathOrSelf(target.cwd)}\u0000${target.profileId ?? ''}\u0000${target.nodeId ?? ''}`;
-}
-/** Every writable memory store — the lint corpus minus builtin (package-owned,
- *  regenerated on every install, so migrating it would fight the package).
- *  Physical stores dedupe once while retaining every owning target corpus. */
-function migratableStores(profiles) {
-    const stores = new Map();
-    const add = (dir, target) => {
-        if (dir === null || dir === '' || !pathExists(dir))
-            return;
-        const real = realpathOrSelf(dir);
-        let store = stores.get(real);
-        if (store === undefined) {
-            store = { dir: real, targets: [] };
-            stores.set(real, store);
-        }
-        const key = targetKey(target);
-        if (!store.targets.some((candidate) => targetKey(candidate) === key))
-            store.targets.push(target);
-    };
-    const addProjectRoots = (roots, profileId) => {
-        const addRoot = (projectRoot) => {
-            const target = { cwd: dirname(projectRoot), profileId, nodeId: null };
-            add(join(projectRoot, 'memory'), target);
-            for (const plugin of listInstalledPluginsInRoot('project', projectRoot)) {
-                if (plugin.enabled)
-                    add(pluginMemoryDir(plugin), target);
-            }
-        };
-        for (const root of roots)
-            addRoot(root);
-        for (const descendant of descendantStoreRootsExhaustive(roots))
-            addRoot(descendant);
-    };
-    const selectedProfileId = process.env['CRTR_PROFILE_ID'] || null;
-    addProjectRoots(projectScopeRoots(process.cwd(), null), selectedProfileId);
-    const profileTargets = [];
-    for (const { profileId, manifest } of profiles) {
-        const home = manifest.home !== null && manifest.home !== '' ? manifest.home : null;
-        const profileTarget = {
-            cwd: home ?? manifest.projects[0]?.path ?? process.cwd(),
-            profileId,
-            nodeId: null,
-        };
-        profileTargets.push(profileTarget);
-        add(profileMemoryDir(profileId), profileTarget);
-        const roots = [
-            ...new Set(manifest.projects.flatMap((project) => [join(project.path, '.crouter'), ...projectScopeRoots(project.path, null)])),
-        ];
-        addProjectRoots(roots, profileId);
-    }
-    const ambientTarget = { cwd: process.cwd(), profileId: selectedProfileId, nodeId: null };
-    const globalTargets = [ambientTarget, ...profileTargets];
-    const userDir = scopeMemoryDir('user');
-    for (const target of globalTargets)
-        add(userDir, target);
-    for (const plugin of listInstalledPlugins('user')) {
-        if (!plugin.enabled)
-            continue;
-        for (const target of globalTargets)
-            add(pluginMemoryDir(plugin), target);
-    }
-    const nodeId = process.env['CRTR_NODE_ID'] ?? '';
-    if (nodeId !== '')
-        add(nodeMemoryDir(nodeId), { cwd: process.cwd(), profileId: selectedProfileId, nodeId });
-    return [...stores.values()];
-}
+import { general, usage } from '../../core/errors.js';
+import { pathExists } from '../../core/fs-utils.js';
+import { runForcedOnDiskMigrations } from '../../migrations/activation.js';
 export const sysMigrateLeaf = defineLeaf({
     name: 'migrate',
     description: 'converge every profile manifest and writable memory store to the current on-disk format',
     whenToUse: 'after a crtr update whose release notes name a state migration, when profiles stop resolving on a home that predates the update, or when old-format docs resurface (a restore, a sync, a hand-authored file). Convergent and idempotent: re-running over current state changes nothing, so use --dry-run first only when you want to review the rewrite.',
     help: {
         name: 'sys migrate',
-        summary: 'run the registered state migrations over every profile manifest and writable memory store',
+        summary: 'run the registered state migrations over every profile manifest and discovered memory store',
+        guide: 'Discovery decides what is migrated: the profiles and the projects they name, the ancestors of this directory, every nested store below any project root it reaches (a node\'s recorded cwd included), every installed plugin (disabled included), the node stores holding documents, and builtin as read-only input. A store outside that frontier is invisible to the run — add it with --dir; discovery_roots reports the frontier the run actually searched. A migration that changes a canonical identity plans across the whole corpus at once and applies in two phases, every reference rewrite before any identity rewrite, so one blocker writes nothing anywhere.',
         params: [
             { kind: 'flag', name: 'dry-run', type: 'bool', required: false, constraint: 'Plan and report every rewrite without writing any file.' },
+            { kind: 'flag', name: 'dir', type: 'path', required: false, repeatable: true, constraint: 'Project directory (the one containing `.crouter/`, not the memory dir) to add to discovery, once per occurrence. For a store no profile names and this directory does not sit under. The path must exist.' },
         ],
         output: [
             { name: 'profiles', type: 'number', required: true, constraint: 'Profile manifests scanned.' },
-            { name: 'stores', type: 'number', required: true, constraint: 'Memory stores scanned.' },
-            { name: 'changed', type: 'number', required: true, constraint: 'Files rewritten (or, under --dry-run, that would be) — manifests and documents together.' },
-            { name: 'applied', type: 'object[]', required: true, constraint: 'One row per migration that changed files: {store, lane, migration, files}, lane one of profile-manifest, convergent. Empty when the state is already current.' },
+            { name: 'stores', type: 'number', required: true, constraint: 'Memory stores discovered, deduped by realpath. Builtin is counted: it is read-only corpus input.' },
+            { name: 'changed', type: 'number', required: true, constraint: 'Files rewritten (or, under --dry-run, that would be) — manifests, per-store documents, and corpus phases together.' },
+            { name: 'applied', type: 'object[]', required: true, constraint: 'One row per migration that changed files: {store, lane, migration, files}, lane one of profile-manifest, convergent, corpus. Empty when the state is already current.' },
             { name: 'skipped', type: 'object[]', required: true, constraint: 'Files left untouched because they could not be parsed — a doc whose frontmatter is not valid YAML, or a manifest that is not valid JSON: {store, relPath, error}. Fix the file, then re-run.' },
+            { name: 'blockers', type: 'object[]', required: true, constraint: 'Why the corpus lane may not write: {kind, message, store?, target?, path?, name?, paths?}. kind is inaccessible-root, inaccessible-target, parse-failure, namespace, association, front-door, divergent-reference, unsafe-route, collision, package-owned-corpus, or verification. A non-empty list with a corpus migration registered fails the run, and `received` carries this whole report plus {corpus_phase, wrote} — corpus_phase is not-started (the corpus is untouched), planned (--dry-run), or written (both phases landed and verification then failed, so `wrote` is the inventory on disk).' },
+            { name: 'discovery_roots', type: 'object[]', required: true, constraint: 'The frontier searched: {reason, root, boundary, detail?}. reason is user, profile, profile-project, cwd-ancestor, descendant, node, plugin, builtin, or explicit-dir; boundary is store, ancestors, descendants, plugins, or nodes.' },
+            { name: 'discovered_stores', type: 'object[]', required: true, constraint: 'One row per physical store: {store, scope, namespace, mount_status, writable, reasons, targets, docs}. reasons holds every way the store was reached; targets the target ids that mount it; docs its parseable document count.' },
+            { name: 'discovered_targets', type: 'object[]', required: true, constraint: 'One row per resolution view: {id, kind, origin, cwd, profile_id, node_id, stores}. stores lists store keys in that target\'s precedence order.' },
+            { name: 'node_metadata', type: 'object', required: true, constraint: '{available, nodes, error?} — whether cwd/profile metadata was readable from every durable meta.json whose node store holds documents. Missing or corrupt metadata blocks corpus writes.' },
+            { name: 'repository_namespaces', type: 'object[]', required: true, constraint: 'Repository-root namespace decisions this run makes: {repository_root, repository_key, declaration_path, namespace, source, action}. A nested store inherits this declaration; its reported effective prefix is not a declaration.' },
+            { name: 'store_prefixes', type: 'object[]', required: true, constraint: 'Effective prefix facts for each project store: {store_root, owner_dir, repository_root, owner_relative_path, old_prefix, old_rule, effective_prefix, nested_declaration_action, front_door_action}. A nonempty owner_relative_path always reports front_door_action `none`; a nested effective_prefix is derived, not a declaration.' },
+            { name: 'renames', type: 'object[]', required: true, constraint: 'Canonical identity changes: {store_root, path, from, to}.' },
+            { name: 'references', type: 'object[]', required: true, constraint: 'Rewritten pointers at a changed identity: {store_root, path, kind, from, to}, kind link or memory-read.' },
             { name: 'dryRun', type: 'boolean', required: true, constraint: 'True when nothing was written (preview only).' },
         ],
         outputKind: 'object',
         effects: [
             'Rewrites old-format `profile.json` manifests in place (atomic, under the same per-profile lock `profile project add/remove` take). A manifest whose structure cannot be converted fails the whole run — no project setting is ever guessed.',
-            'Rewrites old-format memory documents in place (atomic per-file writes) across the writable stores: every profile and every profile-owned project (plus nested descendant stores and installed plugin stores), the current project, user, and this node\'s store. Builtin docs are package-owned and never touched.',
+            'Rewrites old-format memory documents in place (atomic per-file writes) across every writable discovered store: profiles, profile-owned projects, this directory\'s ancestors, nested descendant stores, installed plugin stores, and node stores. Builtin docs are package-owned and never touched.',
+            'Applies corpus-wide identity changes in two ordered phases across every writable store, after the global plan comes back blocker-free; a post-write pass re-reads the corpus from disk and verifies it.',
             'Under --dry-run: read-only, writes nothing.',
         ],
     },
     run: async (input) => {
         const dryRun = input.dryRun === true;
-        const applied = [];
-        const skipped = [];
-        const profilesDir = profilesRoot();
-        const profileRun = runProfileManifestMigrations(profilesDir, { dryRun, withLock: withProfileManifestLock });
-        for (const row of profileRun.applied) {
-            applied.push({ store: profilesDir, lane: 'profile-manifest', migration: row.migration, files: [row.path] });
-        }
-        for (const row of profileRun.skipped) {
-            skipped.push({ store: profilesDir, relPath: `${row.profileId}/profile.json`, error: row.error });
-        }
-        const stores = migratableStores(profileRun.snapshots);
-        const snapshots = new Map();
-        for (const store of stores) {
-            const resolvers = store.targets.map((target) => (name) => {
-                const key = targetKey(target);
-                let snapshot = snapshots.get(key);
-                if (snapshot === undefined) {
-                    snapshot = createMemoryDocSnapshot(target);
-                    snapshots.set(key, snapshot);
-                }
-                return snapshot.legacyDirectoryIndex(name);
-            });
-            const result = runConvergentMigrations(store.dir, {
-                dryRun,
-                context: {
-                    legacyDirectoryIndex: (name) => {
-                        let replacement = null;
-                        for (const resolve of resolvers) {
-                            const candidate = resolve(name);
-                            if (candidate === null)
-                                return null;
-                            if (replacement !== null && replacement !== candidate)
-                                return null;
-                            replacement = candidate;
-                        }
-                        return replacement;
-                    },
-                },
+        const explicitDirs = input['dir'] ?? [];
+        const missingDirs = explicitDirs.filter((dir) => !pathExists(dir));
+        if (missingDirs.length > 0) {
+            throw usage(`--dir path does not exist: ${missingDirs.join(', ')}`, {
+                received: missingDirs,
+                field: 'dir',
+                next: 'Pass the project directory that contains `.crouter/`, or omit --dir to migrate the discovered frontier only.',
             });
-            for (const row of result.applied)
-                applied.push({ store: store.dir, lane: 'convergent', migration: row.migration, files: row.files });
-            for (const s of result.skipped)
-                skipped.push({ store: store.dir, relPath: s.relPath, error: s.error });
         }
-        const changed = applied.reduce((n, row) => n + row.files.length, 0);
-        return {
-            profiles: profileRun.profiles,
-            stores: stores.length,
+        const result = await runForcedOnDiskMigrations({ dryRun, explicitDirs });
+        const { applied, changed, discovery, skipped, snapshots } = result;
+        const blockers = result.blockers.map((blocker) => ({
+            kind: blocker.kind,
+            message: blocker.message,
+            ...(blocker.storeRoot === undefined ? {} : { store: blocker.storeRoot }),
+            ...(blocker.targetId === undefined ? {} : { target: blocker.targetId }),
+            ...(blocker.path === undefined ? {} : { path: blocker.path }),
+            ...(blocker.name === undefined ? {} : { name: blocker.name }),
+            ...(blocker.paths === undefined ? {} : { paths: blocker.paths }),
+        }));
+        // One report body, whether the run converged or blocked: a blocked planner
+        // stays as inspectable as a successful one, and the failure payload adds only
+        // the phase and the write inventory that a success cannot have.
+        const report = {
+            profiles: result.profiles,
+            stores: discovery.stores.length,
             changed,
             applied,
             skipped,
+            blockers,
+            discovery_roots: discovery.roots.map((row) => ({
+                reason: row.reason,
+                root: row.root,
+                boundary: row.boundary,
+                ...(row.detail === undefined ? {} : { detail: row.detail }),
+            })),
+            discovered_stores: discovery.stores.map((store) => ({
+                store: store.key,
+                scope: store.descriptor.scope,
+                namespace: store.descriptor.namespace,
+                mount_status: store.descriptor.mountStatus,
+                writable: store.writable,
+                reasons: [...new Set(store.discovery.map((row) => row.reason))],
+                targets: store.targets,
+                docs: snapshots.get(store.key)?.docs.length ?? 0,
+            })),
+            discovered_targets: discovery.targets.map((target) => ({
+                id: target.id,
+                kind: target.kind,
+                origin: target.origin,
+                cwd: target.target.cwd,
+                profile_id: target.target.profileId,
+                node_id: target.target.nodeId,
+                stores: target.storeKeys,
+            })),
+            node_metadata: discovery.nodeMetadata,
+            repository_namespaces: result.repositories.map((row) => ({
+                repository_root: row.repositoryRoot,
+                repository_key: row.repositoryKey,
+                declaration_path: row.declarationPath,
+                namespace: row.namespace,
+                source: row.source,
+                action: row.action,
+            })),
+            store_prefixes: result.storePrefixes.map((row) => ({
+                store_root: row.storeRoot,
+                owner_dir: row.ownerDir,
+                repository_root: row.repositoryRoot,
+                owner_relative_path: row.ownerRelativePath,
+                old_prefix: row.oldPrefix,
+                old_rule: row.oldRule,
+                effective_prefix: row.effectivePrefix,
+                nested_declaration_action: row.nestedDeclarationAction,
+                front_door_action: row.frontDoorAction,
+            })),
+            renames: result.renames.map((row) => ({ store_root: row.storeRoot, path: row.path, from: row.from, to: row.to })),
+            references: result.references.map((row) => ({
+                store_root: row.storeRoot,
+                path: row.path,
+                kind: row.kind,
+                from: row.from,
+                to: row.to,
+            })),
             dryRun,
+        };
+        if (result.blocked) {
+            const earlier = applied.filter((row) => row.lane !== 'corpus').flatMap((row) => row.files);
+            const corpusPhase = result.corpusPhase;
+            const wrote = {
+                profile_manifests: result.wrote.profileManifests,
+                documents: result.wrote.documents,
+                corpus_consumers: result.wrote.corpusConsumers,
+                corpus_identities: result.wrote.corpusIdentities,
+            };
+            const wroteSummary = dryRun
+                ? '— this was a --dry-run; nothing was written'
+                : corpusPhase === 'written'
+                    ? `after both write phases — ${wrote.corpus_consumers.length} reference and ${wrote.corpus_identities.length} identity rewrite(s) are on disk and are NOT rolled back`
+                    : earlier.length > 0
+                        ? `before any corpus write — the corpus is unchanged, but ${earlier.length} earlier manifest/document rewrite(s) are already on disk`
+                        : '— nothing was written';
+            throw general(`corpus migration ${corpusPhase === 'written' ? 'verification failed with' : 'blocked by'} ${blockers.length} finding(s) ${wroteSummary}`, {
+                received: { ...report, corpus_phase: corpusPhase, wrote },
+                next: corpusPhase === 'written'
+                    ? 'Resolve every verification finding against the files listed in received.wrote.corpus_identities and .corpus_consumers, then re-run `crtr sys migrate` — the lane converges from file truth.'
+                    : 'Resolve every blocker, then re-run `crtr sys migrate` — the earlier lanes are convergent and re-running them is a no-op.',
+            });
+        }
+        return {
+            ...report,
             follow_up: skipped.length > 0
                 ? 'Some files could not be parsed and were left untouched — fix each named file, then re-run `crtr sys migrate`.'
                 : changed === 0

package/dist/commands/sys/panels/profiles-panel.d.ts

@@ -0,0 +1,66 @@
+import { type SetupPanel } from "../../../core/tui/panel.js";
+export declare class ProfilesPanel implements SetupPanel {
+    private readonly cwd;
+    private readonly onChange;
+    private readonly nameInput;
+    private readonly dirInput;
+    private entries;
+    private listIndex;
+    private dirIndex;
+    private mode;
+    /** Profile the detail level / a confirm is about. */
+    private openId;
+    private notice;
+    private noticeTone;
+    private mutating;
+    constructor(cwd: string, onChange: () => void);
+    badge(): string;
+    /** A live text field or a confirm keeps EVERY key, so a name containing `q`
+     *  can never close the page. The detail level claims only Escape and ← — they
+     *  mean "back to the profile list" here rather than "jump to the settings
+     *  rail" — and leaves the page's own navigation and cancel keys alone. */
+    ownsInput(data: string): boolean;
+    /** Profiles covering cwd first (most recently used within), then the rest by
+     *  recency, with root last — the ones a startup pick is deciding between sit
+     *  at the top, where the eye starts. */
+    private reload;
+    private selected;
+    private open;
+    private currentDir;
+    private pinnedHere;
+    private say;
+    /** Run a manifest mutation, turning its structured failure into the panel's
+     *  notice line rather than tearing the page down. */
+    private attempt;
+    handleInput(data: string, matches?: (id: string, input: string) => boolean): boolean;
+    private route;
+    private routeText;
+    private routeConfirm;
+    private routeList;
+    private routeDetail;
+    /** Seed a field with the value the user most likely wants, cursor at its end
+     *  (`\x05` — the field is an edit-or-accept, never a blank you must retype). */
+    private edit;
+    private leaveField;
+    private move;
+    private moveDir;
+    private addCwdTo;
+    private togglePin;
+    private submitName;
+    private submitDir;
+    private cycleMemory;
+    private setHome;
+    private askRemoveDir;
+    private removeDir;
+    private togglePause;
+    private askDelete;
+    private deleteOpen;
+    footerHint(): string;
+    render(width: number, height: number): string[];
+    private header;
+    private renderList;
+    private renderDetail;
+    /** A labelled single-line text field, used by every prompt in the panel. */
+    private field;
+    private deletePrompt;
+}