@crouton-kit/crouter 0.3.49 → 0.3.51

package/dist/core/__tests__/on-read-identity.test.js

@@ -0,0 +1,68 @@
+// The on-read POSITIONAL loader resolves a doc's identity with the SAME
+// explicit-name-then-path-fallback rule the boot resolver uses (schema.ts's
+// resolveDocName), never deriving `name` from the physical path alone.
+//
+// A migrated AGENTS.md doc (`crtr sys sync`'s CLAUDE.md/AGENTS.md conversion)
+// is written at `file-read-visibility: content` with an explicit frontmatter
+// `name` (the project label, e.g. `crouter`) so sibling project roots do not
+// collapse onto the shared `AGENTS` leaf. `loadPositionalDoc` must inject the
+// doc under that explicit name, not the path-derived `AGENTS`.
+//
+// Run: node --import tsx/esm --test src/core/__tests__/on-read-identity.test.ts
+import { test, before, beforeEach, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { closeDb } from '../canvas/db.js';
+import { resetScopeCache } from '../scope.js';
+import { spawnNode } from '../runtime/nodes.js';
+import { renderOnReadDocs } from '../substrate/on-read.js';
+let home;
+let work;
+let prevHomeEnv;
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-onread-identity-home-'));
+    process.env['CRTR_HOME'] = home;
+    prevHomeEnv = process.env['HOME'];
+});
+beforeEach(() => {
+    closeDb();
+    resetScopeCache();
+    rmSync(home, { recursive: true, force: true });
+    if (prevHomeEnv === undefined)
+        delete process.env['HOME'];
+    else
+        process.env['HOME'] = prevHomeEnv;
+    work = mkdtempSync(join(tmpdir(), 'crtr-onread-identity-work-'));
+});
+after(() => {
+    closeDb();
+    resetScopeCache();
+    rmSync(home, { recursive: true, force: true });
+    rmSync(work, { recursive: true, force: true });
+    delete process.env['CRTR_HOME'];
+    if (prevHomeEnv === undefined)
+        delete process.env['HOME'];
+    else
+        process.env['HOME'] = prevHomeEnv;
+});
+test('a migrated AGENTS doc injects on-read under its explicit frontmatter name, not the path-derived one', () => {
+    const node = spawnNode({ kind: 'general', cwd: work, parent: null }).node_id;
+    // Shape of a `crtr sys sync` CLAUDE.md/AGENTS.md migration: physical filename
+    // stays AGENTS.md, but frontmatter carries the project's explicit identity.
+    const memDir = join(work, '.crouter', 'memory');
+    mkdirSync(memDir, { recursive: true });
+    writeFileSync(join(memDir, 'AGENTS.md'), '---\nkind: knowledge\n' +
+        'name: acme-project\n' +
+        'when-and-why-to-read: When working in acme-project, this knowledge should be read because it is the project\'s operating guide.\n' +
+        'file-read-visibility: content\n---\n' +
+        'ACME PROJECT OPERATING GUIDE\n');
+    const readFile = join(work, 'src', 'file.ts');
+    mkdirSync(join(work, 'src'), { recursive: true });
+    writeFileSync(readFile, 'export const x = 1;\n');
+    const rendered = renderOnReadDocs(node, readFile, new Set());
+    assert.ok(rendered.includes('ACME PROJECT OPERATING GUIDE'), 'the migrated doc fires positionally');
+    assert.ok(rendered.includes('<memory kind="knowledge" name="acme-project"'), `expected explicit frontmatter name "acme-project" in the injected envelope, got: ${rendered}`);
+    assert.ok(!rendered.includes('name="AGENTS"'), 'must not fall back to the path-derived name when frontmatter sets one');
+});

package/dist/core/fs-utils.d.ts

@@ -15,5 +15,5 @@ export declare function linkOrCopy(target: string, linkPath: string, opts?: {
     noSymlink?: boolean;
 }): 'symlink' | 'copy';
 export declare function readSymlinkTarget(path: string): string | null;
-export declare function walkFiles(root: string, predicate?: (name: string) => boolean): string[];
+export declare function walkFiles(root: string, predicate?: (name: string) => boolean, skipDir?: (name: string) => boolean): string[];
 export declare function nowIso(): string;

package/dist/core/fs-utils.js

@@ -90,7 +90,7 @@ export function readSymlinkTarget(path) {
         return null;
     }
 }
-export function walkFiles(root, predicate = () => true) {
+export function walkFiles(root, predicate = () => true, skipDir = () => false) {
     const out = [];
     if (!existsSync(root))
         return out;
@@ -106,8 +106,10 @@ export function walkFiles(root, predicate = () => true) {
         }
         for (const e of entries) {
             const full = join(dir, e.name);
-            if (e.isDirectory())
-                stack.push(full);
+            if (e.isDirectory()) {
+                if (!skipDir(e.name))
+                    stack.push(full);
+            }
             else if (e.isFile() && predicate(e.name))
                 out.push(full);
         }

package/dist/core/memory-resolver.d.ts

@@ -1,10 +1,17 @@
 import type { InstalledPlugin, Scope } from '../types.js';
 /**
- * Thin memory-document resolver for the document substrate. Resolution is scope
- * + leaf/path only: qualifier parse → scope precedence → direct path lookup →
- * leaf-name fallback. The memory scopes resolve in precedence order project
- * stack > profile > user > builtin. It returns the raw parsed frontmatter +
- * body; it does NOT interpret the schema, kind, gate, or rungs — that is the
+ * Thin memory-document resolver for the document substrate. Precedence is the
+ * OUTER loop, not a global scan: scopes/sources are tried NEAREST-FIRST
+ * (project stack nearest > ... > profile > user > builtin), and WITHIN each
+ * source, in order: (1) exact substrate-identity match (`doc.name === query`
+ * — the explicit frontmatter `name`, or its path-derived fallback), (2) direct
+ * `memory/<name>.md` physical-path lookup (plus the bare-dir/bare-plugin-name
+ * → `INDEX.md` convenience neither identity nor a literal path expresses),
+ * (3) bare leaf-name fallback (final path segment only). The first hit wins,
+ * so a nearer source's match of ANY kind always beats a farther source's
+ * match of any kind — a farther-scope identity can never shadow a
+ * nearer-scope physical file. It returns the raw parsed frontmatter + body;
+ * it does NOT interpret the schema, kind, gate, or rungs — that is the
  * schema/gate layer's job (callers filter by `frontmatter.kind`). Project
  * resolution is a nearest-first stack of every ancestor `.crouter/` (widened by
  * a selected profile's `projects` manifest entries — see `findProjectScopeRoots`
@@ -12,8 +19,9 @@ import type { InstalledPlugin, Scope } from '../types.js';
  * (from `CRTR_PROFILE_ID`), and user/builtin remain singleton scopes.
  */
 export interface MemoryDoc {
-    /** Path-derived identity: the doc's path under the scope's memory/ root, no
-     *  extension, slash-separated — e.g. memory/taste/foo.md → "taste/foo". */
+    /** Resolver identity: the doc's explicit frontmatter `name` when present,
+     *  otherwise its normalized path under the scope's memory/ root — e.g.
+     *  memory/taste/foo.md → "taste/foo". */
     name: string;
     scope: MemoryScope;
     /** Absolute path to the resolved .md file. */
@@ -59,15 +67,23 @@ export declare function listPluginMemoryDocs(plugin: InstalledPlugin, scope: Mem
  *  caller's first-wins dedup. */
 export declare function listAllMemoryDocs(scope?: MemoryScope, quiet?: boolean): MemoryDoc[];
 /**
- * Resolve a path-derived name to a single memory document.
+ * Resolve a memory document name to a single memory document.
  *
  * Accepted identifier forms:
  *   <name>            — bare name; resolved by scope precedence project>user>builtin
  *   <scope>/<name>    — pinned to one scope (user|project)
  * `<name>` may carry topical subdirs (`taste/foo`); a bare leaf (`foo`) falls
- * back to a last-segment match across the resolved scopes.
+ * back to a last-segment match within the resolved scopes.
  *
- * Resolution order: parse qualifier → direct memory/<name>.md lookup
- * (precedence-first) → leaf-name fallback (ambiguity error listing candidates).
+ * Precedence is the outer loop: sources are visited nearest-first, and the
+ * FIRST source with any hit wins outright — a farther source is never even
+ * consulted once a nearer one matches. Within each source, in order: (1)
+ * exact substrate-identity match (`doc.name === query` — the explicit
+ * frontmatter `name`, else its normalized path-derived fallback, the SAME
+ * identity `listAllMemoryDocs` reports); (2) direct `memory/<name>.md`
+ * physical-path lookup (the bare-dir → INDEX.md and bare-plugin-name → plugin
+ * root INDEX.md conveniences neither identity nor a literal path expresses);
+ * (3) bare leaf-name fallback (final path segment), ambiguous only when two
+ * DIFFERENT identities in the SAME source share a leaf.
  */
 export declare function resolveMemoryDoc(rawName: string, opts?: MemoryResolutionOpts): MemoryDoc;

package/dist/core/memory-resolver.js

@@ -6,7 +6,7 @@ import { listInstalledPlugins, listInstalledPluginsInRoot, parseSkillQualifier }
 import { ambiguous, notFound, usage } from './errors.js';
 import { warn } from './output.js';
 import { pluginMemoryDir, projectScopeRoot, projectScopeRoots, scopeMemoryDir } from './scope.js';
-import { normalizeDocName, normalizeNameSegment } from './substrate/schema.js';
+import { normalizeDocName, normalizeNameSegment, resolveDocName } from './substrate/schema.js';
 import { loadProfileManifest, profileMemoryDir } from './profiles/manifest.js';
 /** Canonical, unambiguous identifier for a memory document: `<scope>/<name>`. */
 export function memoryDocId(doc) {
@@ -75,14 +75,14 @@ function memorySourcesInPrecedence(scope) {
     }
     return out;
 }
-function loadMemoryDoc(name, scope, path) {
+function loadMemoryDoc(scope, path, fallbackName) {
     const { data, body } = parseFrontmatterGeneric(readText(path));
-    return { name, scope, path, frontmatter: data, body };
+    return { name: resolveDocName(data, fallbackName), scope, path, frontmatter: data, body };
 }
 /** All memory docs in one memory/ dir, scanned recursively for *.md (topical
- *  subdirs supported), sorted by path-derived name. SKILL.md bundles are legacy
- *  Agent Skills and are ignored; crouter memory docs are plain .md files under
- *  memory/. */
+ *  subdirs supported), sorted by resolver identity (explicit frontmatter name
+ *  when present, else path-derived). SKILL.md bundles are legacy Agent Skills
+ *  and are ignored; crouter memory docs are plain .md files under memory/. */
 function listMemoryDocsInDir(scope, dir, quiet = false) {
     if (!dir || !pathExists(dir))
         return [];
@@ -117,7 +117,7 @@ function listMemoryDocsInDir(scope, dir, quiet = false) {
         // `quiet` suppresses the notice for a targeted resolve (a leaf-name read),
         // where another doc's health is irrelevant noise before the result.
         try {
-            docs.push(loadMemoryDoc(name, scope, path));
+            docs.push(loadMemoryDoc(scope, path, name));
         }
         catch (e) {
             const msg = (e instanceof Error ? e.message : String(e)).split('\n')[0];
@@ -164,7 +164,7 @@ export function listPluginMemoryDocs(plugin, scope, quiet = false) {
             continue;
         const name = `${plugin.name}/${derived}`;
         try {
-            docs.push({ ...loadMemoryDoc(name, scope, file), plugin: plugin.name });
+            docs.push({ ...loadMemoryDoc(scope, file, name), plugin: plugin.name });
         }
         catch (e) {
             const msg = (e instanceof Error ? e.message : String(e)).split('\n')[0];
@@ -174,16 +174,23 @@ export function listPluginMemoryDocs(plugin, scope, quiet = false) {
     }
     return docs.sort((a, b) => a.name.localeCompare(b.name));
 }
+/** All docs belonging to a single resolved source: native docs first, then
+ *  enabled-plugin docs — native wins on a first-wins dedup within the source.
+ *  Shared by `listAllMemoryDocs` (flattens every source) and `resolveMemoryDoc`
+ *  (consults one source's docs at a time, nearest source first). */
+function sourceMemoryDocs(source, quiet = false) {
+    return [
+        ...listMemoryDocsInDir(source.scope, source.memoryDir, quiet),
+        ...source.plugins.flatMap((p) => listPluginMemoryDocs(p, source.scope, quiet)),
+    ];
+}
 /** All memory docs across the resolved sources, in precedence order: each
  *  ancestor project `.crouter/` from nearest to farthest, then the selected
  *  profile's memory (if any), then user, then builtin. Within each source,
  *  native docs are emitted before enabled-plugin docs, so native wins on the
  *  caller's first-wins dedup. */
 export function listAllMemoryDocs(scope, quiet = false) {
-    return memorySourcesInPrecedence(scope).flatMap((source) => [
-        ...listMemoryDocsInDir(source.scope, source.memoryDir, quiet),
-        ...source.plugins.flatMap((p) => listPluginMemoryDocs(p, source.scope, quiet)),
-    ]);
+    return memorySourcesInPrecedence(scope).flatMap((source) => sourceMemoryDocs(source, quiet));
 }
 /** Find the direct child of `dir` — a `.md` file (matched on name minus
  *  extension) or a directory — whose NORMALIZED display name equals
@@ -246,9 +253,10 @@ function resolveNormalizedPath(baseDir, segments) {
         dirPath: matchNormalizedChild(curDir, last, 'dir'),
     };
 }
-/** Direct full-path lookup of memory/<name>.md across scopes, precedence-first.
- *  Returns every scope's hit in precedence order; the resolver takes the first
- *  (highest-precedence) one — a fully-specified name is never ambiguous.
+/** Direct full-path lookup of memory/<name>.md within ONE source. Returns that
+ *  source's single hit, or undefined — a source can produce at most one direct
+ *  match (native wins over plugin within the source, and at most one plugin's
+ *  name can match).
  *
  *  A directory INDEX is the cleaner contract: when `<name>.md` is absent but
  *  `<name>/INDEX.md` exists, the bare dir name (`taste`) resolves to the dir's
@@ -259,94 +267,72 @@ function resolveNormalizedPath(baseDir, segments) {
  *  never authored with a numeric prefix); resolution against the physical tree
  *  is prefix-blind via `resolveNormalizedPath` so a normalized name finds an
  *  `NN-`-pinned physical file/dir. */
-function findMemoryMatches(name, scope) {
-    const matches = [];
-    const segments = name.split('/');
+function findMemoryMatchInSource(name, segments, source) {
     const isLegacySkillDoc = segments.at(-1) === 'SKILL';
-    for (const source of memorySourcesInPrecedence(scope)) {
-        // Native memory dir first inside this source (native-before-plugin
-        // precedence), then its enabled plugins. The next source is the next
-        // ancestor `.crouter/`, then user, then builtin.
-        const dir = source.memoryDir;
-        if (dir) {
-            const { filePath, dirPath } = resolveNormalizedPath(dir, segments);
-            if (!isLegacySkillDoc && filePath !== null) {
-                matches.push(loadMemoryDoc(name, source.scope, filePath));
-                continue;
-            }
-            if (dirPath !== null) {
-                const indexPath = join(dirPath, 'INDEX.md');
-                if (pathExists(indexPath)) {
-                    matches.push(loadMemoryDoc(name, source.scope, indexPath));
-                    continue;
-                }
-            }
-        }
-        // Plugin memory dir: a `<plugin>/<rest>` name resolves against that enabled
-        // plugin's memory/ tree (the `<pluginName>/` mount that listAllMemoryDocs
-        // enumerates — `read` must resolve what `list` shows). A BARE plugin name
-        // (no slash) resolves the plugin-root INDEX.md, mirroring the native
-        // bare-dir-name -> INDEX.md contract for the plugin mount root.
-        const slash = name.indexOf('/');
-        const pluginName = slash > 0 ? name.slice(0, slash) : name;
-        const rest = slash > 0 ? name.slice(slash + 1) : '';
-        for (const p of source.plugins) {
-            if (p.name !== pluginName)
-                continue;
-            const pdir = pluginMemoryDir(p);
-            const restSegments = rest ? rest.split('/') : [];
-            if (rest) {
-                const { filePath } = resolveNormalizedPath(pdir, restSegments);
-                if (restSegments.at(-1) !== 'SKILL' && filePath !== null) {
-                    matches.push(loadMemoryDoc(name, source.scope, filePath));
-                    break;
-                }
-            }
-            // Bare name -> <plugin>/memory/INDEX.md; slashed name -> dir INDEX.
-            const pIndexDir = rest ? resolveNormalizedPath(pdir, restSegments).dirPath : pdir;
-            if (pIndexDir !== null) {
-                const pindex = join(pIndexDir, 'INDEX.md');
-                if (pathExists(pindex)) {
-                    matches.push(loadMemoryDoc(name, source.scope, pindex));
-                    break;
-                }
-            }
+    // Native memory dir first inside this source (native-before-plugin
+    // precedence), then its enabled plugins.
+    const dir = source.memoryDir;
+    if (dir) {
+        const { filePath, dirPath } = resolveNormalizedPath(dir, segments);
+        if (!isLegacySkillDoc && filePath !== null)
+            return loadMemoryDoc(source.scope, filePath, name);
+        if (dirPath !== null) {
+            const indexPath = join(dirPath, 'INDEX.md');
+            if (pathExists(indexPath))
+                return loadMemoryDoc(source.scope, indexPath, name);
         }
     }
-    return matches;
-}
-/** Leaf-name fallback: match docs whose final path segment equals `leaf`.
- *  Only meaningful for a bare segment (a slashed query can never equal a single
- *  segment). Returns matches precedence-ordered. */
-function findMemoryByLeaf(leaf, scope) {
-    if (leaf.includes('/'))
-        return [];
-    let all;
-    try {
-        // Quiet: a targeted read must not spew other docs' frontmatter warnings
-        // before its own result (esp. a not_found) — corpus health is `lint`'s job.
-        all = listAllMemoryDocs(scope, true);
-    }
-    catch {
-        return [];
+    // Plugin memory dir: a `<plugin>/<rest>` name resolves against that enabled
+    // plugin's memory/ tree (the `<pluginName>/` mount that listAllMemoryDocs
+    // enumerates — `read` must resolve what `list` shows). A BARE plugin name
+    // (no slash) resolves the plugin-root INDEX.md, mirroring the native
+    // bare-dir-name -> INDEX.md contract for the plugin mount root.
+    const slash = name.indexOf('/');
+    const pluginName = slash > 0 ? name.slice(0, slash) : name;
+    const rest = slash > 0 ? name.slice(slash + 1) : '';
+    for (const p of source.plugins) {
+        if (p.name !== pluginName)
+            continue;
+        const pdir = pluginMemoryDir(p);
+        const restSegments = rest ? rest.split('/') : [];
+        if (rest) {
+            const { filePath } = resolveNormalizedPath(pdir, restSegments);
+            if (restSegments.at(-1) !== 'SKILL' && filePath !== null)
+                return loadMemoryDoc(source.scope, filePath, name);
+        }
+        // Bare name -> <plugin>/memory/INDEX.md; slashed name -> dir INDEX.
+        const pIndexDir = rest ? resolveNormalizedPath(pdir, restSegments).dirPath : pdir;
+        if (pIndexDir !== null) {
+            const pindex = join(pIndexDir, 'INDEX.md');
+            if (pathExists(pindex))
+                return loadMemoryDoc(source.scope, pindex, name);
+        }
     }
-    return all.filter((d) => (d.name.split('/').pop() ?? d.name) === leaf);
+    return undefined;
 }
 function formatLeafAmbiguous(leaf, matches) {
     const ids = matches.map(memoryDocId).join(', ');
     return `ambiguous memory document: ${leaf} matches multiple documents: ${ids}`;
 }
 /**
- * Resolve a path-derived name to a single memory document.
+ * Resolve a memory document name to a single memory document.
  *
  * Accepted identifier forms:
  *   <name>            — bare name; resolved by scope precedence project>user>builtin
  *   <scope>/<name>    — pinned to one scope (user|project)
  * `<name>` may carry topical subdirs (`taste/foo`); a bare leaf (`foo`) falls
- * back to a last-segment match across the resolved scopes.
+ * back to a last-segment match within the resolved scopes.
  *
- * Resolution order: parse qualifier → direct memory/<name>.md lookup
- * (precedence-first) → leaf-name fallback (ambiguity error listing candidates).
+ * Precedence is the outer loop: sources are visited nearest-first, and the
+ * FIRST source with any hit wins outright — a farther source is never even
+ * consulted once a nearer one matches. Within each source, in order: (1)
+ * exact substrate-identity match (`doc.name === query` — the explicit
+ * frontmatter `name`, else its normalized path-derived fallback, the SAME
+ * identity `listAllMemoryDocs` reports); (2) direct `memory/<name>.md`
+ * physical-path lookup (the bare-dir → INDEX.md and bare-plugin-name → plugin
+ * root INDEX.md conveniences neither identity nor a literal path expresses);
+ * (3) bare leaf-name fallback (final path segment), ambiguous only when two
+ * DIFFERENT identities in the SAME source share a leaf.
  */
 export function resolveMemoryDoc(rawName, opts = {}) {
     const parsed = parseSkillQualifier(rawName);
@@ -357,28 +343,38 @@ export function resolveMemoryDoc(rawName, opts = {}) {
     const name = parsed.segments.join('/');
     if (name === '')
         throw usage(`memory document name required`);
-    // Direct full-path lookup: a fully-specified name resolves by scope precedence.
-    const direct = findMemoryMatches(name, effectiveScope);
-    if (direct.length > 0)
-        return direct[0];
-    // Leaf-name fallback: the caller gave only the final segment (e.g. "foo" for
-    // "taste/foo"). Match by last segment across the resolved scope dirs.
-    const byLeaf = findMemoryByLeaf(name, effectiveScope);
-    if (byLeaf.length > 0) {
-        // Same path-derived name across scopes → precedence wins (return first);
-        // genuinely different docs sharing a leaf → ambiguous.
-        const distinctNames = new Set(byLeaf.map((d) => d.name));
-        if (distinctNames.size === 1)
-            return byLeaf[0];
-        throw ambiguous(formatLeafAmbiguous(name, byLeaf), {
-            memory: name,
-            candidates: byLeaf.map((d) => ({
-                id: memoryDocId(d),
-                scope: d.scope,
-                path: d.path,
-            })),
-            next: 'Multiple documents share this leaf name. Re-run with one of the full names in candidates.',
-        });
+    const segments = name.split('/');
+    const isLeafQuery = !name.includes('/');
+    for (const source of memorySourcesInPrecedence(effectiveScope)) {
+        // Quiet: a targeted read must not spew other docs' frontmatter warnings
+        // before its own result (esp. a not_found) — corpus health is `lint`'s job.
+        const docs = sourceMemoryDocs(source, true);
+        const identity = docs.find((d) => d.name === name);
+        if (identity)
+            return identity;
+        const direct = findMemoryMatchInSource(name, segments, source);
+        if (direct)
+            return direct;
+        if (isLeafQuery) {
+            const leafMatches = docs.filter((d) => (d.name.split('/').pop() ?? d.name) === name);
+            if (leafMatches.length > 0) {
+                // Same path-derived name within this source → precedence wins (return
+                // first); genuinely different docs sharing a leaf → ambiguous. Either
+                // way this source has an answer — a farther source is never checked.
+                const distinctNames = new Set(leafMatches.map((d) => d.name));
+                if (distinctNames.size === 1)
+                    return leafMatches[0];
+                throw ambiguous(formatLeafAmbiguous(name, leafMatches), {
+                    memory: name,
+                    candidates: leafMatches.map((d) => ({
+                        id: memoryDocId(d),
+                        scope: d.scope,
+                        path: d.path,
+                    })),
+                    next: 'Multiple documents share this leaf name. Re-run with one of the full names in candidates.',
+                });
+            }
+        }
     }
     throw notFound(`memory document not found: ${rawName}`, {
         memory: name,

package/dist/core/runtime/bearings.d.ts

@@ -1,13 +1,8 @@
 import { type Trigger } from '../canvas/index.js';
-/** The `<project_context>` block — now just the cwd/git `<environment>`
- *  snapshot (dir listing + git status/worktrees). This USED to also carry a
- *  `<project_instructions>` block re-rendering the node's AGENTS.md/CLAUDE.md;
- *  that machinery is gone (hard cut, 2026-07-06) — project guidance now lives
- *  in the document substrate (`crtr sys sync` migrates each CLAUDE.md/AGENTS.md
- *  into that dir's own `.crouter/memory/AGENTS.md` at content/content, so it
- *  surfaces via the `<memory kind="knowledge">` block instead). Always emits
- *  the wrapper because the environment snapshot is always present. Exported
- *  for testing. */
+/** The `<project_context>` block — cwd/git `<environment>` snapshot only
+ *  (dir listing + git status/worktrees). Project guidance lives in the document
+ *  substrate, so this wrapper stays environment-only. It always emits because
+ *  the environment snapshot is always present. Exported for testing. */
 export declare function buildProjectContextBlock(cwd: string): string;
 /** The context-directory note — names the path INLINE (no XML attribute, so it
  *  never scopes a sibling block) and frames the dir as durable, shared scratch.

package/dist/core/runtime/bearings.js

@@ -13,15 +13,13 @@
 //     the source's whole conversation and then impersonates it. A non-fork
 //     node's bearings are its FIRST entry, so there is nothing earlier to
 //     disown; it gets only the declarative identity line. The message also
-//     carries the <project_context> block (buildProjectContextBlock) — now just
-//     the cwd/git <environment> snapshot. Project instructions (what used to be
-//     a re-rendered AGENTS.md/CLAUDE.md here) come from the document substrate
-//     instead: `crtr sys sync` migrates each CLAUDE.md/AGENTS.md into that
-//     dir's own `.crouter/memory/AGENTS.md` at content/content, so it rides the
+//     carries the <project_context> block (buildProjectContextBlock), which is
+//     now only the cwd/git <environment> snapshot. Project guidance rides the
+//     document substrate instead: migrated CLAUDE.md/AGENTS.md docs live in the
+//     source dir's own `.crouter/memory/AGENTS.md` and surface through the
 //     <memory kind="knowledge"> block below (renderKnowledgeBlock) via the
-//     profile-widened boot render, exactly like any other substrate doc — no
-//     parallel re-implementation of pi's project-context loader lives here
-//     anymore (see `crtr memory read taste/document-substrate`);
+//     profile-widened boot render — no parallel project-context loader lives
+//     here anymore (see `crtr memory read taste/document-substrate`);
 //   • promote.ts folds orchestratorContextNote() into the promotion guidance
 //     dump, so a node that becomes an orchestrator MID-LIFE gets the
 //     orchestrator framing it never received at spawn — it spawned as a base
@@ -112,15 +110,10 @@ function parseWorktrees(lines) {
     }
     return worktrees;
 }
-/** The `<project_context>` block — now just the cwd/git `<environment>`
- *  snapshot (dir listing + git status/worktrees). This USED to also carry a
- *  `<project_instructions>` block re-rendering the node's AGENTS.md/CLAUDE.md;
- *  that machinery is gone (hard cut, 2026-07-06) — project guidance now lives
- *  in the document substrate (`crtr sys sync` migrates each CLAUDE.md/AGENTS.md
- *  into that dir's own `.crouter/memory/AGENTS.md` at content/content, so it
- *  surfaces via the `<memory kind="knowledge">` block instead). Always emits
- *  the wrapper because the environment snapshot is always present. Exported
- *  for testing. */
+/** The `<project_context>` block — cwd/git `<environment>` snapshot only
+ *  (dir listing + git status/worktrees). Project guidance lives in the document
+ *  substrate, so this wrapper stays environment-only. It always emits because
+ *  the environment snapshot is always present. Exported for testing. */
 export function buildProjectContextBlock(cwd) {
     const envLines = directoryListingLines(cwd);
     const git = gitSnapshot(cwd);

package/dist/core/substrate/index.d.ts

@@ -1,4 +1,4 @@
-export { KINDS, isDocKind, RUNGS, rungRank, rungAtLeast, FALLBACK_RUNG, parseSubstrateFrontmatter, parseSubstrateDoc, previewLine, normalizeNameSegment, normalizeDocName, } from './schema.js';
+export { KINDS, isDocKind, RUNGS, rungRank, rungAtLeast, FALLBACK_RUNG, parseSubstrateFrontmatter, parseSubstrateDoc, previewLine, normalizeNameSegment, normalizeDocName, resolveDocName, } from './schema.js';
 export type { DocKind, Rung, GatePredicate, SubstrateSchema, SubstrateDoc } from './schema.js';
 export { scopeForCwd, spineDepth, assembleNodeSubject, profileNameFor } from './subject.js';
 export type { NodeConfigSubject } from './subject.js';

package/dist/core/substrate/index.js

@@ -13,7 +13,9 @@ FALLBACK_RUNG,
 // parse + render-shared helpers
 parseSubstrateFrontmatter, parseSubstrateDoc, previewLine, 
 // display-name normalization
-normalizeNameSegment, normalizeDocName, } from './schema.js';
+normalizeNameSegment, normalizeDocName, 
+// substrate identity (explicit-name-then-path-fallback)
+resolveDocName, } from './schema.js';
 export { scopeForCwd, spineDepth, assembleNodeSubject, profileNameFor } from './subject.js';
 export { gatePasses } from './gate.js';
 export { INDEX_NAME, isIndexName, indexDirOf, displayName, buildCeilingIndex, effectiveRung, } from './ceiling.js';

package/dist/core/substrate/on-read.js

@@ -10,9 +10,9 @@
 //     ancestor PROJECT `.crouter/memory/` surfaces (a doc surfaces when a file
 //     beside/under its own project scope dir is read), UNLESS it carries an
 //     explicit read-trigger (see D5 below). This is the substrate's own
-//     ancestor walk keyed on `.crouter/memory/` — the same shape the retired
-//     nested-context pi-extension used for `.claude/rules` before that path
-//     was migrated into substrate docs (`crtr sys sync`). The user-global
+//     ancestor walk keyed on `.crouter/memory/` — project guidance that starts
+//     in CLAUDE.md/AGENTS.md or `.claude/rules` now lives here after
+//     `crtr sys sync` migrates it. The user-global
 //     `~/.crouter/memory/` store is NOT positional; user docs only fire on
 //     reads through explicit `applies-to` / `read-when` triggers.
 //   • applies-to GLOB — any RESOLVED substrate doc (user/project/builtin scope)
@@ -58,16 +58,16 @@ import { pathExists, readText, walkFiles } from '../fs-utils.js';
 import { parseFrontmatterGeneric } from '../frontmatter.js';
 import { evalCondition } from '../predicate.js';
 import { listAllMemoryDocs } from '../memory-resolver.js';
-import { assembleNodeSubject, buildCeilingIndex, displayName, effectiveRung, gatePasses, normalizeDocName, parseSubstrateDoc, parseSubstrateFrontmatter, previewLine, } from './index.js';
+import { assembleNodeSubject, buildCeilingIndex, displayName, effectiveRung, gatePasses, normalizeDocName, parseSubstrateDoc, parseSubstrateFrontmatter, previewLine, resolveDocName, } from './index.js';
 import { cachedSubstrateDocs } from './session-cache.js';
 // Ancestor dirs we never look inside for a `.crouter/memory/` store (the read
 // file may live under a build/dependency tree; `.crouter` is NOT junk here — it
 // is the segment we explicitly join onto each surviving ancestor).
 const JUNK_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.next', '.cache', '.yalc']);
 // ---------------------------------------------------------------------------
-// Small path helpers (mirror the on-read precedent — frontmatter-rules, and
-// the retired nested-context extension — so the injected envelope matches
-// their faithful shape).
+// Small path helpers (mirror the on-read precedent established by
+// frontmatter-rules so the injected envelope keeps the faithful substrate
+// shape).
 // ---------------------------------------------------------------------------
 function realpathOrSelf(p) {
     try {
@@ -120,13 +120,18 @@ function loadPositionalDoc(file, memDir, scope) {
             .replace(/\.md$/i, '')
             .split(sep)
             .join('/');
-        const name = normalizeDocName(raw);
-        if (name === '')
+        const fallbackName = normalizeDocName(raw);
+        if (fallbackName === '')
             return null;
         const { data, body } = parseFrontmatterGeneric(readText(file));
         const schema = parseSubstrateFrontmatter(data);
         if (schema === null)
             return null;
+        // ONE substrate-identity rule (schema.ts's resolveDocName), shared with the
+        // resolver's loadMemoryDoc: an explicit frontmatter `name` wins over the
+        // path-derived fallback, so a positionally-discovered doc surfaces on-read
+        // under the SAME identity the boot resolver would give it.
+        const name = resolveDocName(data, fallbackName);
         return { ...schema, name, scope, path: file, body };
     }
     catch {