@crouton-kit/crouter 0.3.48 → 0.3.50

package/dist/commands/sys/__tests__/sync-import.test.js

@@ -8,25 +8,46 @@
 // Run: node --import tsx/esm --test src/commands/sys/__tests__/sync-import.test.ts
 import { afterEach, beforeEach, test } from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtempSync, mkdirSync, rmSync, writeFileSync, readFileSync, existsSync } from 'node:fs';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, readFileSync, existsSync, realpathSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { sysSyncLeaf } from '../sync.js';
+import { createNode } from '../../../core/canvas/canvas.js';
+import { closeDb } from '../../../core/canvas/db.js';
+import { resolveMemoryDoc } from '../../../core/memory-resolver.js';
 import { parseFrontmatterGeneric } from '../../../core/frontmatter.js';
 import { gitSync } from '../../../core/git.js';
+import { renderKnowledgeBlock } from '../../../core/substrate/render.js';
+import { clearSessionCache } from '../../../core/substrate/session-cache.js';
+import { sysSyncLeaf } from '../sync.js';
 function git(args, cwd) {
     const res = gitSync(args, cwd);
     if (res.status !== 0)
         throw new Error(`git ${args.join(' ')} failed in ${cwd}: ${res.stderr || res.stdout}`);
 }
+function node(id, cwd) {
+    return {
+        node_id: id,
+        name: id,
+        created: new Date().toISOString(),
+        cwd,
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+    };
+}
 let home;
 let prevHome;
 beforeEach(() => {
+    closeDb();
+    clearSessionCache();
     prevHome = process.env.HOME;
     home = mkdtempSync(join(tmpdir(), 'crtr-sys-sync-'));
     process.env.HOME = home;
 });
 afterEach(() => {
+    closeDb();
+    clearSessionCache();
     if (prevHome === undefined)
         delete process.env.HOME;
     else
@@ -49,6 +70,21 @@ test('imports a SKILL.md bundle as a plain crouter memory doc', async () => {
     assert.equal(parsed.data?.['when-and-why-to-read'], 'When demo work appears, this knowledge should be read because handles demos.');
     assert.match(parsed.body, /Do the demo\./);
 });
+test('skips SKILL.md files vendored under node_modules while still importing a top-level authored SKILL.md', async () => {
+    const sourceRoot = join(home, 'repo');
+    const vendored = join(sourceRoot, 'node_modules', '@tanstack', 'some-pkg');
+    mkdirSync(vendored, { recursive: true });
+    writeFileSync(join(vendored, 'SKILL.md'), '---\nname: Vendored Skill\ndescription: Should never be imported.\n---\n\n# Vendored\n', 'utf8');
+    const authored = join(sourceRoot, 'my-skill');
+    mkdirSync(authored, { recursive: true });
+    writeFileSync(join(authored, 'SKILL.md'), '---\nname: My Skill\ndescription: Handles the real thing. Use when real work appears.\n---\n\n# Real\n\nDo the real thing.\n', 'utf8');
+    const result = await sysSyncLeaf.run({ source: sourceRoot, scope: 'user' });
+    assert.equal(result?.imported, 1);
+    assert.equal(existsSync(join(home, '.crouter', 'memory', 'vendored-skill.md')), false);
+    assert.equal(existsSync(join(home, '.crouter', 'memory', 'my-skill.md')), true);
+    const rows = (result?.results).map((r) => r.source);
+    assert.ok(!rows.some((s) => s.includes('node_modules')));
+});
 test('skips generated crtr boot skills instead of importing them', async () => {
     const bundle = join(home, '.pi', 'agent', 'skills', 'crtr-skills');
     mkdirSync(bundle, { recursive: true });
@@ -97,9 +133,19 @@ test('migrates CLAUDE.md and a .claude/rules file into that dir\'s own .crouter/
     assert.equal(existsSync(ruleTarget), true);
     const agentsDoc = parseFrontmatterGeneric(readFileSync(agentsTarget, 'utf8'));
     assert.equal(agentsDoc.data?.kind, 'knowledge');
+    assert.equal(agentsDoc.data?.name, 'demo-project');
     assert.equal(agentsDoc.data?.['system-prompt-visibility'], 'content');
     assert.equal(agentsDoc.data?.['file-read-visibility'], 'content');
     assert.match(agentsDoc.body, /Build then commit\./);
+    const prevCwd = process.cwd();
+    process.chdir(source);
+    try {
+        assert.equal(resolveMemoryDoc('demo-project').path, realpathSync(agentsTarget));
+        assert.equal(resolveMemoryDoc('demo-project').name, 'demo-project');
+    }
+    finally {
+        process.chdir(prevCwd);
+    }
     const ruleDoc = parseFrontmatterGeneric(readFileSync(ruleTarget, 'utf8'));
     assert.equal(ruleDoc.data?.kind, 'knowledge');
     assert.equal(ruleDoc.data?.['system-prompt-visibility'], 'none');
@@ -148,6 +194,113 @@ test('routes the walk-root AGENTS.md doc by the real git repo name, not a worktr
     git(['worktree', 'remove', '--force', linkedWorktree], mainRepo);
     rmSync(base, { recursive: true, force: true });
 });
+test('sibling purview roots keep distinct AGENTS names so boot render does not dedupe them away', async () => {
+    const base = mkdtempSync(join(tmpdir(), 'crtr-sys-sync-purview-'));
+    const rootA = join(base, 'alpha-root');
+    const rootB = join(base, 'beta-root');
+    mkdirSync(rootA, { recursive: true });
+    mkdirSync(rootB, { recursive: true });
+    writeFileSync(join(rootA, 'CLAUDE.md'), '# Alpha Root\n\nAlpha body.\n', 'utf8');
+    writeFileSync(join(rootB, 'CLAUDE.md'), '# Beta Root\n\nBeta body.\n', 'utf8');
+    await sysSyncLeaf.run({ source: rootA });
+    await sysSyncLeaf.run({ source: rootB });
+    const profileId = 'purview-b7a4d1f0';
+    const profileDir = join(home, '.crouter', 'profiles', profileId);
+    mkdirSync(profileDir, { recursive: true });
+    writeFileSync(join(profileDir, 'profile.json'), JSON.stringify({ name: 'purview-pair', projects: [rootA, rootB], created_at: new Date().toISOString() }, null, 2) + '\n', 'utf8');
+    const runDir = join(base, 'run');
+    mkdirSync(runDir, { recursive: true });
+    const prevCwd = process.cwd();
+    const prevProfileId = process.env.CRTR_PROFILE_ID;
+    try {
+        process.env.CRTR_PROFILE_ID = profileId;
+        process.chdir(runDir);
+        clearSessionCache();
+        const alphaDoc = resolveMemoryDoc('alpha-root');
+        assert.equal(alphaDoc.path, join(rootA, '.crouter', 'memory', 'AGENTS.md'));
+        assert.equal(alphaDoc.name, 'alpha-root');
+        const betaDoc = resolveMemoryDoc('beta-root');
+        assert.equal(betaDoc.path, join(rootB, '.crouter', 'memory', 'AGENTS.md'));
+        assert.equal(betaDoc.name, 'beta-root');
+        createNode(node('bootcheck', runDir));
+        const block = renderKnowledgeBlock('bootcheck');
+        assert.match(block, /Alpha body\./, 'first purview root survives the boot render');
+        assert.match(block, /Beta body\./, 'second purview root survives the boot render');
+    }
+    finally {
+        process.chdir(prevCwd);
+        if (prevProfileId === undefined)
+            delete process.env.CRTR_PROFILE_ID;
+        else
+            process.env.CRTR_PROFILE_ID = prevProfileId;
+    }
+    rmSync(base, { recursive: true, force: true });
+});
+test('a nested project-subdir AGENTS/CLAUDE doc migrates to its OWN <nested>/.crouter/memory/AGENTS.md with a deterministic, non-colliding explicit name', async () => {
+    const source = mkdtempSync(join(tmpdir(), 'crtr-sys-sync-nested-'));
+    writeFileSync(join(source, 'CLAUDE.md'), '# Nested Demo\n\nRoot guidance.\n', 'utf8');
+    const nestedDir = join(source, 'packages', 'widgets');
+    mkdirSync(nestedDir, { recursive: true });
+    writeFileSync(join(nestedDir, 'AGENTS.md'), '# Widgets Package\n\nNested guidance.\n', 'utf8');
+    const result = await sysSyncLeaf.run({ source });
+    const projectRows = (result?.results).filter((row) => row.target.includes('.crouter/memory'));
+    assert.equal(projectRows.length, 2, 'both the root and nested docs are candidates');
+    assert.ok(projectRows.every((r) => r.status === 'imported'));
+    const rootTarget = join(source, '.crouter', 'memory', 'AGENTS.md');
+    const nestedTarget = join(nestedDir, '.crouter', 'memory', 'AGENTS.md');
+    assert.equal(existsSync(rootTarget), true, 'root doc writes to the root\'s OWN .crouter/memory/AGENTS.md');
+    assert.equal(existsSync(nestedTarget), true, 'nested doc writes to the NESTED dir\'s OWN .crouter/memory/AGENTS.md, not the root store');
+    const rootDoc = parseFrontmatterGeneric(readFileSync(rootTarget, 'utf8'));
+    const nestedDoc = parseFrontmatterGeneric(readFileSync(nestedTarget, 'utf8'));
+    assert.equal(rootDoc.data?.name, 'nested-demo');
+    assert.equal(nestedDoc.data?.name, 'nested-demo/packages/widgets');
+    assert.notEqual(rootDoc.data?.name, nestedDoc.data?.name, 'root and nested identities never collide');
+    assert.match(rootDoc.body, /Root guidance\./);
+    assert.match(nestedDoc.body, /Nested guidance\./);
+    const prevCwd = process.cwd();
+    try {
+        process.chdir(nestedDir);
+        clearSessionCache();
+        const resolved = resolveMemoryDoc('nested-demo/packages/widgets');
+        assert.equal(resolved.path, realpathSync(nestedTarget), 'resolveMemoryDoc finds a migrated nested doc by its explicit slashed identity');
+        assert.equal(resolved.name, 'nested-demo/packages/widgets');
+        assert.match(resolved.body, /Nested guidance\./);
+    }
+    finally {
+        process.chdir(prevCwd);
+    }
+    rmSync(source, { recursive: true, force: true });
+});
+test('a nested project-subdir doc migrated when --source POINTS AT THE NESTED DIR ITSELF still gets a suffix-qualified, non-colliding name', async () => {
+    // A nested doc's name suffix is computed against the git worktree top-level,
+    // not the supplied walk root, so `--source <nested-dir>` still yields a
+    // qualified, non-colliding name even when the walk starts at the nested dir.
+    const base = mkdtempSync(join(tmpdir(), 'crtr-sys-sync-nested-source-'));
+    const repoRoot = join(base, 'demo-repo');
+    mkdirSync(repoRoot, { recursive: true });
+    git(['init', '-b', 'main'], repoRoot);
+    git(['config', 'user.email', 'test@example.com'], repoRoot);
+    git(['config', 'user.name', 'Test'], repoRoot);
+    writeFileSync(join(repoRoot, 'CLAUDE.md'), '# Demo Repo\n\nRoot guidance.\n', 'utf8');
+    const nestedDir = join(repoRoot, 'packages', 'widgets');
+    mkdirSync(nestedDir, { recursive: true });
+    writeFileSync(join(nestedDir, 'AGENTS.md'), '# Widgets Package\n\nNested guidance.\n', 'utf8');
+    git(['add', '.'], repoRoot);
+    git(['commit', '-m', 'init'], repoRoot);
+    // --source pinned directly at the nested dir, with the root project doc left
+    // unmigrated, so the nested doc's name must stay qualified on its own.
+    const nestedResult = await sysSyncLeaf.run({ source: nestedDir });
+    assert.equal(nestedResult?.imported, 1);
+    const nestedTarget = join(nestedDir, '.crouter', 'memory', 'AGENTS.md');
+    assert.equal(existsSync(nestedTarget), true);
+    const nestedDoc = parseFrontmatterGeneric(readFileSync(nestedTarget, 'utf8'));
+    assert.equal(nestedDoc.data?.name, 'demo-repo/packages/widgets', 'nested doc name is suffix-qualified even though --source pinned the nested dir directly');
+    assert.notEqual(nestedDoc.data?.name, 'demo-repo', 'nested identity never collapses to the bare root project label it would collide with');
+    assert.match(nestedDoc.body, /Nested guidance\./);
+    const projectRows = (nestedResult?.results).filter((row) => row.target.includes('.crouter/memory'));
+    assert.ok(projectRows.some((r) => r.status === 'imported' && r.target === nestedTarget));
+    rmSync(base, { recursive: true, force: true });
+});
 test('falls back to the doc H1 title when the walk root is not inside a git repo', async () => {
     const source = mkdtempSync(join(tmpdir(), 'crtr-sys-sync-nogit-'));
     writeFileSync(join(source, 'CLAUDE.md'), '# Standalone Docs Project\n\nDo the thing.\n', 'utf8');
@@ -155,6 +308,6 @@ test('falls back to the doc H1 title when the walk root is not inside a git repo
     assert.equal(result?.imported, 1);
     const target = join(source, '.crouter', 'memory', 'AGENTS.md');
     const doc = parseFrontmatterGeneric(readFileSync(target, 'utf8'));
-    assert.equal(doc.data?.['when-and-why-to-read'], 'When working in Standalone Docs Project, this knowledge should be read because it is the project\'s operating guide.');
+    assert.equal(doc.data?.['when-and-why-to-read'], 'When working in standalone-docs-project, this knowledge should be read because it is the project\'s operating guide.');
     rmSync(source, { recursive: true, force: true });
 });

package/dist/commands/sys/sync.js

@@ -1,7 +1,7 @@
 // `crtr sys sync` — explicit migration from legacy host Agent Skill bundles into
 // crouter memory documents. It is NOT a bidirectional SKILL.md sync surface: the
 // crouter side after a sync is a plain memory/<name>.md document.
-import { existsSync, readdirSync, statSync } from 'node:fs';
+import { existsSync, readdirSync, realpathSync, statSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { basename, dirname, join, relative, resolve, sep } from 'node:path';
 import { defineLeaf } from '../../core/command.js';
@@ -17,8 +17,7 @@ const LEGACY_BOOT_SKILL_MARKER_PREFIX = '<!-- crtr-boot-skill v';
 const HOST_SKILL_FILE = 'SKILL.md';
 const IGNORE_FILE = 'skill-import-ignore.json';
 // Directories a project-doc walk never descends into — build/dependency trees
-// plus crouter's own state dir (mirrors nested-context's JUNK_DIRS, the
-// now-deleted extension this migration replaces).
+// plus crouter's own state dir.
 const PROJECT_DOC_JUNK_DIRS = new Set([
     'node_modules', '.git', '.venv', 'venv', 'dist', 'build', '.next', '.cache', '.yalc', '.sisyphus', CRTR_DIR_NAME,
 ]);
@@ -67,7 +66,7 @@ function collectCandidates(rootDef) {
         candidates.push({ path: directSkill, root: dirname(statRoot), source: rootDef.label, defaultScope: rootDef.defaultScope });
         return candidates;
     }
-    for (const file of walkFiles(statRoot, (name) => name === HOST_SKILL_FILE)) {
+    for (const file of walkFiles(statRoot, (name) => name === HOST_SKILL_FILE, (name) => PROJECT_DOC_JUNK_DIRS.has(name))) {
         candidates.push({ path: file, root: statRoot, source: rootDef.label, defaultScope: rootDef.defaultScope });
     }
     return candidates;
@@ -163,18 +162,17 @@ function collectProjectDocCandidates(root) {
     const stack = [rootResolved];
     while (stack.length > 0) {
         const dir = stack.pop();
-        const isWalkRoot = dir === rootResolved;
         for (const name of PROJECT_DOC_FILENAMES) {
             const p = join(dir, name);
             if (existsSync(p) && statSync(p).isFile()) {
-                out.push({ kind: 'agents', path: p, sourceDir: dir, isWalkRoot });
+                out.push({ kind: 'agents', path: p, sourceDir: dir, walkRoot: rootResolved });
                 break;
             }
         }
         const rulesDir = join(dir, '.claude', 'rules');
         if (existsSync(rulesDir)) {
             for (const file of walkFiles(rulesDir, (n) => n.endsWith('.md'))) {
-                out.push({ kind: 'rule', path: file, sourceDir: dir, isWalkRoot });
+                out.push({ kind: 'rule', path: file, sourceDir: dir, walkRoot: rootResolved });
             }
         }
         let entries;
@@ -226,6 +224,33 @@ function gitRepoRootName(dir) {
         return undefined;
     return basename(dirname(gitCommonDir));
 }
+/** The current git worktree's OWN top-level directory (`git rev-parse
+ *  --show-toplevel`) — unlike `--git-common-dir` above, this does NOT resolve
+ *  through a linked worktree to the shared repo storage; it is the actual
+ *  checked-out tree containing `dir`. This is the stable root to compute a
+ *  doc's subdir suffix against, even when the discovery walk itself started
+ *  strictly inside that tree — e.g. `--source` pointed directly at a nested
+ *  package dir, so the walk root and the source dir are the same directory
+ *  and a walk-root-relative suffix would be empty. Returns undefined when
+ *  `dir` isn't inside a git working tree at all (the non-git fallback keeps
+ *  using the walk root itself). */
+function gitWorktreeRoot(dir) {
+    const res = gitSync(['rev-parse', '--path-format=absolute', '--show-toplevel'], dir);
+    if (res.status !== 0)
+        return undefined;
+    const top = res.stdout.trim();
+    return top === '' ? undefined : resolve(top);
+}
+/** `realpathSync`, tolerant of a path that doesn't exist or can't be resolved
+ *  (falls back to the path as given). */
+function realpathOrSelf(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return p;
+    }
+}
 /** First Markdown H1 heading in the doc body, heading marker stripped. */
 function h1Title(body) {
     for (const raw of body.split('\n')) {
@@ -238,35 +263,69 @@ function h1Title(body) {
     }
     return undefined;
 }
-/** Routing-text label for the WALK-ROOT project doc: the raw basename of that
- *  directory is unreliable (a worktree/canvas checkout's basename is a node
- *  id, not the project name), so prefer the actual git repo's root dirname,
- *  falling back to the doc's own H1 title, falling back to the raw basename
- *  only as a last resort. Nested-dir docs don't need this — their own
- *  subdirectory basename already names them correctly. */
-function projectRootLabel(dir, body) {
-    return gitRepoRootName(dir) ?? h1Title(body) ?? basename(dir) ?? dir;
+/** Namespace label for a walk root: the raw basename of that directory is
+ *  unreliable (a worktree/canvas checkout's basename is a node id, not the
+ *  project name), so prefer the actual git repo's root dirname, then the root
+ *  doc's own H1 title if one exists there, then the raw basename. */
+function projectRootLabel(root) {
+    const gitLabel = gitRepoRootName(root);
+    if (gitLabel !== undefined)
+        return normalizedName(gitLabel);
+    for (const name of PROJECT_DOC_FILENAMES) {
+        const p = join(root, name);
+        if (existsSync(p) && statSync(p).isFile()) {
+            const title = h1Title(parseFrontmatterGeneric(readText(p)).body);
+            if (title !== undefined)
+                return normalizedName(title);
+        }
+    }
+    return normalizedName(basename(root) || root);
+}
+/** Explicit substrate identity for one migrated project doc: the root label
+ *  from the walk root (repo name/H1/basename), plus any relative subdir under
+ *  the STABLE SUFFIX ROOT. That suffix root is the git worktree top-level
+ *  when the source is git-backed, NOT the supplied walk root — so a
+ *  `--source` pointed directly at a nested subdir (walk root === source dir,
+ *  a walk-root-relative suffix would be empty) still gets a suffix relative
+ *  to the real project root and cannot collide with that root's own doc
+ *  identity. Non-git sources have no stable project root to prefer, so they
+ *  keep the walk-root fallback unchanged. Root AGENTS.md docs become
+ *  `crouter`/`hearth`-shaped identities while nested AGENTS.md docs get a
+ *  deterministic `root/subdir` name — regardless of whether the walk started
+ *  at that root or at the nested dir itself. */
+function projectDocLabel(candidate) {
+    const rootLabel = projectRootLabel(candidate.walkRoot);
+    const suffixRoot = gitWorktreeRoot(candidate.walkRoot) ?? candidate.walkRoot;
+    // `git rev-parse --show-toplevel` resolves through symlinks (e.g. macOS's
+    // /tmp -> /private/tmp); realpath BOTH sides before diffing so a symlinked
+    // walk root doesn't produce a bogus `../../..` suffix against the git-
+    // resolved top-level.
+    const relDir = relative(realpathOrSelf(suffixRoot), realpathOrSelf(candidate.sourceDir))
+        .split(sep)
+        .join('/')
+        .replace(/^\.$/, '');
+    return relDir === '' ? rootLabel : normalizedName(`${rootLabel}/${relDir}`);
 }
 /** AGENTS.md/CLAUDE.md → `<sourceDir>/.crouter/memory/AGENTS.md` at
  *  content/content (the CTO's ruling, 2026-07-06: an AGENTS.md-style doc is
  *  always-relevant AND wholly-important, so full-body at `content` is
- *  sanctioned — see `taste/document-substrate`). Doc name is fixed `AGENTS`
- *  (never `INDEX`, which carries ceiling/subtree-capping semantics here). */
+ *  sanctioned — see `taste/document-substrate`). The on-disk filename stays
+ *  `AGENTS.md`, but the substrate identity is the explicit project label so
+ *  sibling roots do not collapse on a shared `AGENTS` leaf. */
 function prepareAgentsCandidate(candidate) {
     const body = parseFrontmatterGeneric(readText(candidate.path)).body;
-    const dirLabel = candidate.isWalkRoot
-        ? projectRootLabel(candidate.sourceDir, body)
-        : basename(candidate.sourceDir) || candidate.sourceDir;
+    const docLabel = projectDocLabel(candidate);
     const frontmatter = {
         kind: 'knowledge',
-        'when-and-why-to-read': `When working in ${dirLabel}, this knowledge should be read because it is the project's operating guide.`,
+        name: docLabel,
+        'when-and-why-to-read': `When working in ${docLabel}, this knowledge should be read because it is the project's operating guide.`,
         'short-form': synthesizeShortForm(body),
         'system-prompt-visibility': 'content',
         'file-read-visibility': 'content',
     };
     return {
         candidate,
-        name: 'AGENTS',
+        name: docLabel,
         target: memoryFilePath(join(candidate.sourceDir, CRTR_DIR_NAME, 'memory'), 'AGENTS'),
         frontmatter,
         body,
@@ -282,9 +341,7 @@ function prepareRuleCandidate(candidate) {
     const fm = parsed.data ?? {};
     const name = normalizedName(basename(candidate.path));
     const description = scalarString(fm['description']) ?? '';
-    const dirLabel = candidate.isWalkRoot
-        ? projectRootLabel(candidate.sourceDir, parsed.body)
-        : basename(candidate.sourceDir) || candidate.sourceDir;
+    const dirLabel = projectDocLabel(candidate);
     const frontmatter = {
         kind: 'knowledge',
         'when-and-why-to-read': description !== ''

package/dist/core/__tests__/broker-sdk-wiring.test.js

@@ -83,13 +83,10 @@ test('C3b — broker splits model thinking suffix before SDK registry lookup', a
         rmSync(cwd, { recursive: true, force: true });
     }
 });
-// (C4 — project AGENTS.md/CLAUDE.md injection — was removed: crouter sets
-// `noContextFiles: true` in buildBrokerSession unconditionally (broker.ts) and
-// no longer re-renders those files into the bearings either (hard cut,
-// 2026-07-06) — project guidance now comes from the document substrate
-// (`crtr sys sync` migrates CLAUDE.md/AGENTS.md into a memory doc). Covered by
-// context-intro.test.ts's "a CLAUDE.md in the node's cwd no longer rides the
-// bearings" test.)
+// (C4 — project guidance now comes from the document substrate: crouter keeps
+// `noContextFiles: true` in buildBrokerSession, and buildContextIntro's
+// `<project_context>` block is environment-only. Covered by
+// context-intro.test.ts's environment-only regression.)
 // ===========================================================================
 // C2 — zero-viewer dialogs resolve to deny/cancel IMMEDIATELY (noOp), never
 // hanging the turn and never waiting on a per-dialog timeout. Drives the REAL

package/dist/core/__tests__/context-intro.test.js

@@ -69,13 +69,21 @@ test('worker bearings: base framing + <knowledge> block, NO across-cycles framin
     assert.doesNotMatch(block, /refresh cycles/, 'no across-cycles framing for a terminal worker');
     assert.match(block, /<\/crtr-bearings>/);
 });
-test('a CLAUDE.md in the node\'s cwd no longer rides the bearings; only the <environment> snapshot does (hard cut, 2026-07-06)', () => {
-    // buildProjectContextBlock used to re-render the node's AGENTS.md/CLAUDE.md
-    // into a <project_instructions> block (pi's own copy stays suppressed via
-    // broker.ts noContextFiles). That machinery is gone: project guidance now
-    // comes from the document substrate (a migrated AGENTS.md doc rides the
-    // <memory kind="knowledge"> block instead — see `crtr sys sync`), so a bare
-    // on-disk CLAUDE.md is simply never read by crtr at boot any more.
+test('node-local doc identity honors explicit frontmatter `name`, not the physical filename', () => {
+    // node-local docs follow the one substrate identity rule (resolveDocName):
+    // an explicit `name:` renders and dedups under that name, not the filename.
+    const meta = spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null });
+    const dir = memoryDir(meta.node_id);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, 'physical-filename.md'), '---\nkind: knowledge\nname: explicit-identity\nwhen-and-why-to-read: When testing, this reference should be read because it is a regression fixture\nsystem-prompt-visibility: preview\n---\nTest body.\n');
+    const block = buildContextIntro(meta.node_id);
+    assert.match(block, /\u2500 explicit-identity {2}# read when:/, 'tree entry renders under the explicit frontmatter name');
+    assert.ok(!block.includes('physical-filename'), 'the physical filename never surfaces once an explicit name is set');
+});
+test('a CLAUDE.md in the node\'s cwd does not enter the bearings; only the <environment> snapshot remains', () => {
+    // buildProjectContextBlock now emits only the cwd/git environment snapshot.
+    // Project guidance lives in the document substrate instead, so a bare on-disk
+    // CLAUDE.md stays out of the bearings entirely.
     const proj = mkdtempSync(join(tmpdir(), 'crtr-proj-'));
     writeFileSync(join(proj, 'CLAUDE.md'), 'PROJECT_MARKER: build then commit.\n');
     const meta = spawnNode({ kind: 'general', cwd: proj, parent: null });

package/dist/core/__tests__/memory-resolver-precedence.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/__tests__/memory-resolver-precedence.test.js

@@ -0,0 +1,144 @@
+// Regression matrix for `resolveMemoryDoc`'s precedence rule: scopes/sources
+// are visited NEAREST-FIRST, and the first source with ANY hit — by identity,
+// direct physical path, or bare-leaf fallback — wins outright. A farther
+// source's match, even an EXACT identity match, must never be consulted once
+// a nearer source has answered by any means. This locks in the fix for the
+// regression where a global identity-first scan let a farther-scope doc named
+// exactly `AGENTS` shadow a nearer worktree's own `AGENTS.md` (whose explicit
+// frontmatter `name` had since diverged from the physical filename).
+//
+// Fixture shape: two nested project scopes on disk —
+//   root/.crouter/memory/...       (farther project scope)
+//   root/child/.crouter/memory/... (nearer project scope; cwd lives here)
+// `findProjectScopeRoots` walks every ancestor `.crouter/` from cwd upward, so
+// from `root/child` the resolved stack is exactly [child, root], nearest first
+// — no profile indirection needed to exercise multi-scope precedence.
+//
+// Run: node --import tsx/esm --test src/core/__tests__/memory-resolver-precedence.test.ts
+import { test, before, beforeEach, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, realpathSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { resetScopeCache } from '../scope.js';
+import { resolveMemoryDoc } from '../memory-resolver.js';
+let home;
+let base;
+let root;
+let child;
+let grandchild;
+let prevCwd;
+let prevHome;
+function writeDoc(path, body, frontmatterName) {
+    mkdirSync(join(path, '..'), { recursive: true });
+    const fm = frontmatterName ? `---\nname: ${frontmatterName}\n---\n` : '';
+    writeFileSync(path, `${fm}${body}\n`, 'utf8');
+}
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-resolver-precedence-home-'));
+    prevHome = process.env.HOME;
+    process.env.HOME = home;
+});
+beforeEach(() => {
+    resetScopeCache();
+    base = realpathSync(mkdtempSync(join(tmpdir(), 'crtr-resolver-precedence-')));
+    root = join(base, 'root');
+    child = join(root, 'child');
+    grandchild = join(child, 'grandchild');
+    mkdirSync(root, { recursive: true });
+    mkdirSync(child, { recursive: true });
+    mkdirSync(grandchild, { recursive: true });
+    // --- root (FARTHER project scope) ---
+    writeDoc(join(root, '.crouter', 'memory', 'AGENTS.md'), 'ROOT AGENTS BODY'); // derived name "AGENTS"
+    writeDoc(join(root, '.crouter', 'memory', 'shared.md'), 'ROOT SHARED BODY'); // derived name "shared"
+    writeDoc(join(root, '.crouter', 'memory', 'taste', 'document-substrate.md'), 'ROOT TASTE BODY'); // derived "taste/document-substrate"
+    writeDoc(join(root, '.crouter', 'memory', 'taste', 'INDEX.md'), 'ROOT TASTE INDEX'); // derived "taste/INDEX"
+    // --- child (NEARER project scope; cwd resolves here) ---
+    writeDoc(join(child, '.crouter', 'memory', 'AGENTS.md'), 'CHILD AGENTS BODY', 'crouter'); // physical AGENTS.md, identity diverged to "crouter"
+    writeDoc(join(child, '.crouter', 'memory', 'sub', 'shared.md'), 'CHILD SUB SHARED BODY'); // derived "sub/shared" — leaf "shared"
+    writeDoc(join(child, '.crouter', 'memory', 'taste', 'document-substrate.md'), 'CHILD TASTE BODY'); // derived "taste/document-substrate"
+    writeDoc(join(child, '.crouter', 'memory', 'taste', 'INDEX.md'), 'CHILD TASTE INDEX'); // derived "taste/INDEX"
+    // --- grandchild (nearest still; own migrated slashed identity) ---
+    writeDoc(join(grandchild, '.crouter', 'memory', 'AGENTS.md'), 'GRANDCHILD SUBDIR BODY', 'root/subdir');
+    prevCwd = process.cwd();
+});
+after(() => {
+    process.chdir(prevCwd);
+    resetScopeCache();
+    rmSync(base, { recursive: true, force: true });
+    rmSync(home, { recursive: true, force: true });
+    if (prevHome === undefined)
+        delete process.env.HOME;
+    else
+        process.env.HOME = prevHome;
+});
+test('a physical-path query whose nearest match diverged in identity from a farther same-derived-name doc resolves to the NEAREST physical file (the AGENTS shadowing case)', () => {
+    process.chdir(child);
+    resetScopeCache();
+    try {
+        const byPhysicalName = resolveMemoryDoc('AGENTS');
+        assert.equal(byPhysicalName.path, join(child, '.crouter', 'memory', 'AGENTS.md'));
+        assert.match(byPhysicalName.body, /CHILD AGENTS BODY/);
+        const byExplicitIdentity = resolveMemoryDoc('crouter');
+        assert.equal(byExplicitIdentity.path, join(child, '.crouter', 'memory', 'AGENTS.md'));
+        assert.match(byExplicitIdentity.body, /CHILD AGENTS BODY/);
+    }
+    finally {
+        process.chdir(prevCwd);
+    }
+});
+test('a migrated nested doc resolves by its explicit slashed identity', () => {
+    process.chdir(grandchild);
+    resetScopeCache();
+    try {
+        const doc = resolveMemoryDoc('root/subdir');
+        assert.equal(doc.path, join(grandchild, '.crouter', 'memory', 'AGENTS.md'));
+        assert.equal(doc.name, 'root/subdir');
+        assert.match(doc.body, /GRANDCHILD SUBDIR BODY/);
+    }
+    finally {
+        process.chdir(prevCwd);
+    }
+});
+test('a plain path-named doc with no explicit name resolves to the nearest copy', () => {
+    process.chdir(child);
+    resetScopeCache();
+    try {
+        const doc = resolveMemoryDoc('taste/document-substrate');
+        assert.equal(doc.path, join(child, '.crouter', 'memory', 'taste', 'document-substrate.md'));
+        assert.match(doc.body, /CHILD TASTE BODY/);
+    }
+    finally {
+        process.chdir(prevCwd);
+    }
+});
+test('a bare-directory query resolves to that dir\'s INDEX.md, nearest copy first', () => {
+    process.chdir(child);
+    resetScopeCache();
+    try {
+        const doc = resolveMemoryDoc('taste');
+        assert.equal(doc.path, join(child, '.crouter', 'memory', 'taste', 'INDEX.md'));
+        assert.match(doc.body, /CHILD TASTE INDEX/);
+    }
+    finally {
+        process.chdir(prevCwd);
+    }
+});
+test('two docs sharing a path-derived leaf name across scopes: nearest wins even over a farther EXACT identity match', () => {
+    process.chdir(child);
+    resetScopeCache();
+    try {
+        // Nearest scope's doc lives at "sub/shared.md" (derived name "sub/shared",
+        // leaf "shared"); the farther scope's doc lives at top-level "shared.md"
+        // (derived name "shared", an EXACT identity match for the bare query).
+        // Precedence-as-outer-loop means the nearer source's mere leaf-fallback
+        // hit must still beat the farther source's exact identity hit.
+        const doc = resolveMemoryDoc('shared');
+        assert.equal(doc.path, join(child, '.crouter', 'memory', 'sub', 'shared.md'));
+        assert.equal(doc.name, 'sub/shared');
+        assert.match(doc.body, /CHILD SUB SHARED BODY/);
+    }
+    finally {
+        process.chdir(prevCwd);
+    }
+});

package/dist/core/__tests__/on-read-identity.test.d.ts

@@ -0,0 +1 @@
+export {};