@north-light/crouter 0.3.227 → 0.3.228

package/dist/commands/memory/history.js

@@ -1,23 +1,23 @@
-import { join } from 'node:path';
 import { defineLeaf } from '../../core/command.js';
 import { CrtrError, notFound, usage } from '../../core/errors.js';
-import { nativeMemoryStoresInPrecedence, resolveHistoryLogPath, resolveMemoryDoc } from '../../core/memory-resolver.js';
+import { nativeMemoryStoresInPrecedence, resolveMemoryDoc, resolveMemoryDocInStore, } from '../../core/memory-resolver.js';
 import { renderResult } from '../../core/render.js';
-import { parseSkillQualifier } from '../../core/resolver.js';
-import { HISTORY_DIR, historyLogPathFor, readHistoryRecords, summarizeChange, unifiedDiff, } from '../../core/memory/history.js';
-import { MEMORY_SCOPES } from './shared.js';
-/** Locate a document's revision log. A live doc resolves through the normal
- *  document precedence walk; a DELETED one has no file to resolve, so its log
- *  is resolved by name against each native store's `.history` tree in the same
- *  order, under the same normalization the doc had — history outlives the
- *  document it describes, answering to the name that document answered to. */
-function resolveLog(nameRaw, scopeArg) {
+import { historyLogPathForDoc, readHistoryRecords, resolveDeletedHistoryLogPath, summarizeChange, unifiedDiff, } from '../../core/memory/history.js';
+import { requireCanonicalName, requireLocalNameInStore, requireMountedStore, resolveReadSelector, selectorParam, } from './shared.js';
+import { stripNamespace } from '../../core/memory/identity.js';
+/** Locate a document's revision log. A live doc is resolved to its physical
+ * descriptor first; a deleted doc is looked up in the selected store(s) by the
+ * exact canonical name, stripping only that store's declared project namespace.
+ * There is no scope-prefix or leaf fallback. */
+function resolveLog(nameRaw, selectorInput) {
+    const selector = resolveReadSelector(selectorInput);
+    if (selector.store !== null)
+        requireMountedStore(selector.store);
     let doc;
     try {
-        doc = resolveMemoryDoc(nameRaw, {
-            includeDescendants: true,
-            ...(scopeArg !== undefined ? { scope: scopeArg } : {}),
-        });
+        doc = selector.store !== null
+            ? resolveMemoryDocInStore(nameRaw, selector.store)
+            : resolveMemoryDoc(nameRaw, { includeDescendants: true, ...(selector.scope ? { scope: selector.scope } : {}) });
     }
     catch (e) {
         if (!(e instanceof CrtrError && e.code === 'not_found'))
@@ -36,17 +36,20 @@ function resolveLog(nameRaw, scopeArg) {
                 scope: 'builtin',
             });
         }
-        return { name: doc.name, scope: doc.scope, logPath: historyLogPathFor(doc.root, doc.path) };
+        return { name: doc.name, scope: doc.scope, logPath: historyLogPathForDoc(doc) };
     }
-    const parsed = parseSkillQualifier(nameRaw);
-    const name = parsed.segments.join('/');
-    if (name === '')
-        throw usage('memory document name required');
-    const scope = scopeArg ?? parsed.scope;
-    for (const store of nativeMemoryStoresInPrecedence(scope, true)) {
-        const logPath = resolveHistoryLogPath(join(store.memoryDir, HISTORY_DIR), parsed.segments);
-        if (logPath !== null)
-            return { name, scope: store.scope, logPath };
+    const canonicalName = requireCanonicalName(nameRaw);
+    const stores = selector.store !== null
+        ? [{ scope: selector.store.scope, memoryDir: selector.store.storeRoot, store: selector.store }]
+        : nativeMemoryStoresInPrecedence(selector.scope, true);
+    for (const store of stores) {
+        if (selector.store === null && store.store.namespace !== '' && stripNamespace(canonicalName, store.store.namespace) === null)
+            continue;
+        const localName = requireLocalNameInStore(store.store, canonicalName);
+        const deleted = resolveDeletedHistoryLogPath(store.memoryDir, localName);
+        if (deleted !== null) {
+            return { name: canonicalName, scope: store.scope, logPath: deleted.logPath, deleted };
+        }
     }
     throw notFound(`no memory document or revision history found: ${nameRaw}`, {
         memory: nameRaw,
@@ -64,20 +67,25 @@ export const historyLeaf = defineLeaf({
             'A record whose `before` differs from the previous record\u2019s `after` is the evidence of an out-of-band direct file edit; nothing prevents those, and nothing detects them beyond this.\n\n' +
             'The log is a plain JSONL file at `log_path`, one JSON object per line \u2014 an external consumer reads it directly rather than through this command.',
         params: [
-            { kind: 'positional', name: 'name', required: true, constraint: 'Path-derived memory identifier (e.g. `topic` or `area/topic`), resolved as `read` resolves it. When no such document exists, the same resolution runs against each writable store\u2019s history tree in precedence order \u2014 which is how a deleted document\u2019s history still answers to the name that document answered to. Builtin and installed-plugin docs are read-only corpora and carry no history.' },
+            { kind: 'positional', name: 'name', required: true, constraint: 'Full canonical memory name (a project document includes its namespace), resolved exactly. Deleted history uses the same canonical name and the selected store\u2019s physical sidecars; there is no leaf or scope-prefix fallback. Builtin and installed-plugin docs are read-only corpora and carry no history.' },
+            selectorParam('scope-read'),
+            selectorParam('dir'),
+            selectorParam('profile'),
             { kind: 'flag', name: 'limit', type: 'int', required: false, default: 10, constraint: 'How many revisions to return, newest first. Default 10.' },
             { kind: 'flag', name: 'diff', type: 'bool', required: false, constraint: 'Include a unified diff per listed revision, computed from that record\u2019s own before/after texts.' },
             { kind: 'flag', name: 'revision', type: 'int', required: false, constraint: 'Show ONE revision in full \u2014 its metadata plus the complete before and after document texts. 1-based position in the log: the number `crtr memory edit` reports. Overrides --limit and --diff.' },
-            { kind: 'flag', name: 'scope', type: 'enum', choices: [...MEMORY_SCOPES], required: false, constraint: 'Restrict resolution to this scope. A disambiguation filter for a name present at several scopes.' },
+            // Scope, --dir, and --profile are shared selector contracts above.
         ],
         output: [
             { name: 'name', type: 'string', required: true, constraint: 'Resolved document name.' },
             { name: 'scope', type: 'string', required: true, constraint: 'Scope whose store holds the log: node, project, profile, or user.' },
             { name: 'log_path', type: 'string', required: true, constraint: 'Absolute path to the append-only JSONL log \u2014 the direct-consumption pointer, one self-contained record per line.' },
+            { name: 'history_candidates', type: 'object[]', required: false, constraint: 'Deleted-history physical candidates: {path, representation, winner}. The directory-index form is listed first and wins deterministically.' },
+            { name: 'history_collision', type: 'object', required: false, constraint: 'Present when deleted history has both physical forms: {paths, winner}.' },
             { name: 'total', type: 'number', required: true, constraint: 'Total revisions in the log.' },
             { name: 'revisions', type: 'object[]', required: false, constraint: 'Newest-first, capped by --limit. Each: {revision, op, at, node, rationale, body_changed, frontmatter_changed, diff}. `node` and `rationale` are present only when recorded; `diff` only with --diff. Absent when --revision selects one record.' },
             { name: 'record', type: 'object', required: false, constraint: 'Present only with --revision: {revision, op, at, node, cwd, rationale, verbatim, before, after} \u2014 the full record including both complete document texts.' },
-            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands \u2014 the flag variants and the doc read.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands \u2014 the flag variants and the doc read, or, for a deleted document, the revision carrying its retained final text.' },
         ],
         outputKind: 'object',
         effects: ['None. Read-only.'],
@@ -123,10 +131,16 @@ export const historyLeaf = defineLeaf({
     run: async (input) => {
         const nameRaw = input['name'];
         const scopeArg = input['scope'];
+        const dirArg = input['dir'];
+        const profileArg = input['profile'];
         const limit = input['limit'] ?? 10;
         const wantDiff = input['diff'] === true;
         const revisionArg = input['revision'];
-        const { name, scope, logPath } = resolveLog(nameRaw, scopeArg);
+        const { name, scope, logPath, deleted } = resolveLog(nameRaw, { scope: scopeArg, dir: dirArg, profile: profileArg });
+        const historyMeta = deleted === undefined ? {} : {
+            history_candidates: deleted.candidates,
+            ...(deleted.collision === undefined ? {} : { history_collision: deleted.collision }),
+        };
         const records = readHistoryRecords(logPath);
         if (records.length === 0) {
             throw notFound(`no revision history recorded for ${name}`, {
@@ -146,9 +160,12 @@ export const historyLeaf = defineLeaf({
                 name,
                 scope,
                 log_path: logPath,
+                ...historyMeta,
                 total: records.length,
                 record: { revision: revisionArg, ...r },
-                follow_up: `Read the document as it stands with \`crtr memory read ${name}\`, or list the revisions with \`crtr memory history ${name} --diff\`.`,
+                follow_up: deleted === undefined
+                    ? `Read the document as it stands with \`crtr memory read ${name}\`, or list the revisions with \`crtr memory history ${name} --diff\`.`
+                    : `${name} is deleted — no read answers to it. This record's \`before\` is its text at that revision; the last revision (${records.length}) carries the text it was deleted with. List the revisions with \`crtr memory history ${name} --diff\`.`,
             };
         }
         const revisions = records
@@ -171,9 +188,12 @@ export const historyLeaf = defineLeaf({
             name,
             scope,
             log_path: logPath,
+            ...historyMeta,
             total: records.length,
             revisions,
-            follow_up: `Add --diff for per-revision unified diffs, --revision N for one record's full before/after text, or read the document as it stands with \`crtr memory read ${name}\`.`,
+            follow_up: deleted === undefined
+                ? `Add --diff for per-revision unified diffs, --revision N for one record's full before/after text, or read the document as it stands with \`crtr memory read ${name}\`.`
+                : `${name} is deleted and only this log survives — no read answers to it. Add --diff for per-revision unified diffs, or recover its final text with \`crtr memory history ${name} --revision ${records.length}\`, whose \`before\` is the document as it stood when deleted.`,
         };
     },
 });

package/dist/commands/memory/lint.d.ts

@@ -1,10 +1 @@
-export { lintSubstrateFrontmatter as lintSubstrateSchema } from '../../core/substrate/frontmatter-validation.js';
-/** Warn when a body short enough to inline still pays a routing line. */
-export declare function lintShortPreviewBody(fm: Record<string, unknown>, body: string): string | null;
-/** The length rule. Caps are computed from the parsed entries — an invalid
- *  entry already fails the schema check, so it simply matches no cap here.
- *  `docName` is the doc's canonical resolver identity (explicit frontmatter
- *  `name`, else the normalized path-derived name) — persona layers under
- *  `kinds/` are recognized by it and never capped. */
-export declare function lintBodyLength(fm: Record<string, unknown>, body: string, docName: string): string | null;
 export declare const lintLeaf: import("../../core/command.js").LeafDef;

package/dist/commands/memory/lint.js

@@ -1,341 +1,97 @@
-// `crtr memory lint` — the permanent valid-YAML gate over the bounded corpus
-// (the CTO green-checkpoint: zero frontmatter parse errors at authoring time,
-// so an invalid doc fails HERE instead of being silently isolated at runtime).
-// Bounded corpus = the substrate memory dirs (ancestor projects/user/builtin).
-// Never a filesystem-wide scan.
-import { basename, join, relative, sep } from 'node:path';
+// `crtr memory lint` — the selector/help wrapper over the memory lint engine
+// (`core/memory/lint.ts`). Every rule lives in the engine, which migration
+// verification, the plugin candidate gate, and the build's builtin gate consume
+// too; this leaf only picks WHAT to lint (a target view, or one exact store
+// with --dir) and shapes the findings for the CLI.
 import { defineLeaf } from '../../core/command.js';
-import { general } from '../../core/errors.js';
 import { warn } from '../../core/output.js';
-import { pathExists, readText, walkFiles } from '../../core/fs-utils.js';
-import { parseFrontmatterGeneric } from '../../core/frontmatter.js';
-import { listInstalledPlugins, listInstalledPluginsInRoot } from '../../core/resolver.js';
-import { pluginMemoryDir, projectScopeRoots, scopeMemoryDir } from '../../core/scope.js';
-import { loadProfileManifest, profileMemoryDir } from '../../core/profiles/manifest.js';
-import { getDefaultProfileId } from '../../core/profiles/default-binding.js';
-import { normalizeDocName, parseSubstrateFrontmatter, resolveDocName, } from '../../core/substrate/schema.js';
-import { lintSubstrateFrontmatter } from '../../core/substrate/frontmatter-validation.js';
-export { lintSubstrateFrontmatter as lintSubstrateSchema } from '../../core/substrate/frontmatter-validation.js';
-import { memoryExtensionValidationCatalog, validateMemoryExtensionValues } from '../../core/memory/extensions.js';
-import { docLinkNames } from '../../core/memory/doc-link-grammar.js';
-import { listAllMemoryDocs } from '../../core/memory-resolver.js';
-import { descendantStoreRoots } from '../../core/nested-stores.js';
-/** Rung-scaled body-length caps, measured in WORDS (frontmatter excluded).
- *  Words, not lines: house style writes each paragraph as ONE logical line
- *  and lets the editor soft-wrap, so a line count measures wrapping style
- *  rather than context cost — words track what the reader actually pays.
- *
- *  A `boot` entry at `content` inlines the whole body into every agent's
- *  system prompt; a `content` entry on any other event (workspace-open, read,
- *  memory-read, command) surfaces the whole body whenever the entry fires —
- *  both cap at 1000 words. A `boot` entry at `preview` routes a deliberate
- *  reader into the whole body, so its cap is the longest doc worth reading
- *  end-to-end (calibrated to the humanizer doc, 2936 words). `name` entries
- *  and surface-less docs never cap: such a doc is only reached deliberately
- *  (a listing, browse, or a [[link]]), so its length is the reader's choice.
- *  The strictest applicable cap wins.
- *
- *  Persona layers — canonical names under `kinds/`, the docs the prompt
- *  render composes into an agent's persona — are structurally exempt: an
- *  agent reads its whole persona by construction, so persona length is a
- *  persona-design choice, not an authoring smell. Suppression elsewhere is
- *  deliberate and per-doc: `lint-ignore: length` in the frontmatter,
- *  surfaced ONLY by the finding itself — never advertised in authoring
- *  help. */
-const BOOT_CONTENT_MAX_WORDS = 1000;
-const EVENT_CONTENT_MAX_WORDS = 1000;
-const BOOT_PREVIEW_MAX_WORDS = 3000;
-/** A routing line costs more than it saves for a short rule or fact. */
-const PREVIEW_TO_CONTENT_MAX_WORDS = 30;
-function ignoresRule(fm, rule) {
-    const v = fm['lint-ignore'];
-    return v === rule || (Array.isArray(v) && v.includes(rule));
+import { ExitCode } from '../../types.js';
+import { lintMemoryStore, lintMemoryTarget, resolvableCanonicalNames, } from '../../core/memory/lint.js';
+import { loadMemoryTargetView } from '../../core/memory-resolver.js';
+import { resolveReadSelector, selectorParam } from './shared.js';
+function findingRow(finding) {
+    return {
+        rule: finding.rule,
+        path: finding.path,
+        message: finding.message,
+        ...(finding.name === undefined ? {} : { name: finding.name }),
+        ...(finding.scope === undefined ? {} : { scope: finding.scope }),
+        ...(finding.storeRoot === undefined ? {} : { store_root: finding.storeRoot }),
+        ...(finding.paths === undefined ? {} : { paths: [...finding.paths] }),
+    };
 }
-function countBodyWords(body) {
-    const trimmed = body.trim();
-    return trimmed === '' ? 0 : trimmed.split(/\s+/).length;
+/** The canonical names a `--dir` store's own links and routes must resolve in:
+ *  the target view an agent standing in that project sees. Never the store in
+ *  isolation — a project doc legitimately links a user or builtin doc. */
+function resolvableNamesForStore(store) {
+    const view = loadMemoryTargetView({
+        cwd: store.ownerDir ?? store.storeRoot,
+        profileId: process.env['CRTR_PROFILE_ID'] || null,
+        nodeId: null,
+    }, { quiet: true, includeDescendants: true });
+    return resolvableCanonicalNames(view.docs);
 }
-/** The doc's surfaces entries as the runtime will read them. Used by the cap
- *  checks AFTER the strict schema check has run — for a doc that passes it,
- *  the tolerant parse and the strict contract agree. */
-function parsedSurfaces(fm) {
-    return parseSubstrateFrontmatter(fm)?.surfaces ?? [];
-}
-/** Warn when a body short enough to inline still pays a routing line. */
-export function lintShortPreviewBody(fm, body) {
-    const words = countBodyWords(body);
-    if (words >= PREVIEW_TO_CONTENT_MAX_WORDS)
-        return null;
-    const previewEvents = [...new Set(parsedSurfaces(fm).filter((e) => e.at === 'preview').map((e) => e.on))];
-    if (previewEvents.length === 0)
-        return null;
-    const noun = previewEvents.length === 1 ? 'entry delivers' : 'entries deliver';
-    return `body is ${words} words but the ${previewEvents.join('/')} ${noun} \`preview\`; use \`at: content\` so agents receive the whole rule without a separate memory read`;
-}
-/** The length rule. Caps are computed from the parsed entries — an invalid
- *  entry already fails the schema check, so it simply matches no cap here.
- *  `docName` is the doc's canonical resolver identity (explicit frontmatter
- *  `name`, else the normalized path-derived name) — persona layers under
- *  `kinds/` are recognized by it and never capped. */
-export function lintBodyLength(fm, body, docName) {
-    if (ignoresRule(fm, 'length'))
-        return null;
-    // Persona exemption: render composes an agent's persona from the docs
-    // resolving under `kinds/...`, and an agent reads its whole persona by
-    // construction — persona length is persona design, never an authoring smell.
-    if (docName === 'kinds' || docName.startsWith('kinds/'))
-        return null;
-    const entries = parsedSurfaces(fm);
-    const words = countBodyWords(body);
-    const remedy = 'Keep the load-bearing core here and split the depth into [[linked]] reference docs carrying no surfaces at all (the listing and the link are how they are found, so they cost nothing until followed). Split by subject: each leaf covers a different subject a task might need on its own; never split off “further evidence”, examples, or references — a references leaf is never followed, so supporting material stays next to the point it supports or gets cut. Keep it whole — `lint-ignore: length` in the frontmatter — only when every reader who surfaces this doc genuinely benefits from reading 100% of it, or it is one indivisible body of knowledge; then splitting just adds hops.';
-    if (entries.some((e) => e.on === 'boot' && e.at === 'content') && words > BOOT_CONTENT_MAX_WORDS) {
-        return `body is ${words} words but a boot entry at \`content\` inlines every word into every agent's system prompt — capped at ${BOOT_CONTENT_MAX_WORDS} words (boot preview gets ${BOOT_PREVIEW_MAX_WORDS}; name entries are never capped). ${remedy}`;
-    }
-    const contentEvents = [...new Set(entries.filter((e) => e.on !== 'boot' && e.at === 'content').map((e) => e.on))];
-    if (contentEvents.length > 0 && words > EVENT_CONTENT_MAX_WORDS) {
-        return `body is ${words} words, over the ${EVENT_CONTENT_MAX_WORDS}-word cap for a \`content\` entry on ${contentEvents.join('/')} (the whole body delivers every time the entry fires; name entries are never capped). ${remedy}`;
-    }
-    if (entries.some((e) => e.on === 'boot' && e.at === 'preview') && words > BOOT_PREVIEW_MAX_WORDS) {
-        return `body is ${words} words, over the ${BOOT_PREVIEW_MAX_WORDS}-word cap for boot preview (the routing line invites every reader into the whole body, so the cap is the longest doc worth reading end-to-end; boot content is capped at ${BOOT_CONTENT_MAX_WORDS} words; name entries are never capped). ${remedy}`;
-    }
-    return null;
-}
-/** Strict-parse one file; push a finding on a YAML error, then run the
- *  schema check when the file lives in a substrate store, then validate every
- *  `[[canonical/name]]` doc link in the body against the exact resolvable
- *  corpus. A dangling link is an authoring error caught HERE, never silently
- *  carried; leaf-name fallback is deliberately excluded so links stay stable
- *  as the graph grows and another document acquires the same leaf name. */
-function lintFile(file, substrateStore, findings, warnings, corpusNames, fallbackName, scope) {
-    let fm;
-    let body;
-    try {
-        ({ data: fm, body } = parseFrontmatterGeneric(readText(file)));
-    }
-    catch (e) {
-        const msg = (e instanceof Error ? e.message : String(e)).split('\n')[0];
-        findings.push({ path: file, error: `invalid YAML frontmatter: ${msg}` });
-        return;
-    }
-    if (!substrateStore)
-        return;
-    const schemaError = lintSubstrateFrontmatter(fm);
-    if (schemaError !== null)
-        findings.push({ path: file, error: schemaError });
-    if (fm !== null) {
-        for (const issue of validateMemoryExtensionValues(fm['extensions'], memoryExtensionValidationCatalog({ scope, path: file }))) {
-            findings.push({ path: file, error: `${issue.path}: ${issue.message}` });
-        }
-        const lengthError = lintBodyLength(fm, body, resolveDocName(fm, fallbackName));
-        if (lengthError !== null)
-            findings.push({ path: file, error: lengthError });
-        const shortPreviewWarning = lintShortPreviewBody(fm, body);
-        if (shortPreviewWarning !== null)
-            warnings.push(`${file}: ${shortPreviewWarning}`);
-        // An over-broad memory-read glob fires on EVERY memory read — almost
-        // always an authoring accident, so flag it without failing the corpus.
-        for (const entry of parsedSurfaces(fm)) {
-            if (entry.on !== 'memory-read')
-                continue;
-            for (const glob of entry.match ?? []) {
-                if ((glob === '**' || glob === '*') && !ignoresRule(fm, 'broad-memory-read')) {
-                    warnings.push(`${file}: memory-read glob \`${glob}\` fires on every memory read — scope it to a name subtree`);
-                }
-            }
-        }
-    }
-    for (const name of docLinkNames(body)) {
-        if (!corpusNames.has(name)) {
-            findings.push({
-                path: file,
-                error: `dangling doc link [[${name}]]: no memory document or directory has that exact canonical name — retarget the link (\`crtr memory find ${name.split('/').pop()}\`) or drop it`,
-            });
-        }
-    }
-}
-/** The files in a project store carrying a workspace front-door entry
- *  ({on: workspace-open, at: content}). Raw fm scan; a missing store or an
- *  unparseable doc contributes zero (the YAML failure is its own finding). */
-function frontDoorDocs(storeDir) {
-    const hits = [];
-    if (!pathExists(storeDir))
-        return hits;
-    for (const file of walkFiles(storeDir, (n) => n.endsWith('.md'), (d) => d.startsWith('.'))) {
-        if (basename(file) === 'MEMORY.md')
-            continue;
-        let fm;
-        try {
-            fm = parseFrontmatterGeneric(readText(file)).data;
-        }
-        catch {
-            continue;
-        }
-        if (fm === null)
-            continue;
-        const entries = parsedSurfaces(fm);
-        if (entries.some((e) => e.on === 'workspace-open' && e.at === 'content'))
-            hits.push(file);
-    }
-    return hits;
-}
-const FRONT_DOOR_REMEDY = 'author the project\'s operating guide as an ordinary doc with `surfaces: [{on: workspace-open, at: content}, {on: read, match: "./**", at: content}]`; run `crtr memory write -h` first';
 export const lintLeaf = defineLeaf({
     name: 'lint',
-    description: 'validate frontmatter and body length across the whole bounded document corpus',
-    whenToUse: 'you authored or migrated documents and want the authoring-time gate: strict-parse every doc in the bounded corpus (the substrate memory stores) and fail loudly on any invalid YAML, substrate schema violation (including retired visibility fields and malformed `surfaces` entries), body longer than its delivery entries earn, or dangling `[[canonical/name]]` doc link; also validates that every project managed by the selected profile has exactly one workspace front door and warns when an unprofiled working directory has none. Run it before shipping doc changes; CI-friendly (non-zero exit on findings, warnings remain non-fatal).',
+    description: 'validate memory identity, frontmatter, and references across a target view or one exact store',
+    whenToUse: 'you authored, moved, or migrated documents and want the authoring-time gate before shipping them. It strict-parses every doc the selection covers and fails on: invalid YAML or substrate schema, a repository whose root store declares no valid `namespace:` (so the runtime refuses to mount it), a `namespace:` outside the repository-root store\u2019s root INDEX.md, two directories in one repository whose paths normalize to the same prefix, a `name:` on a root INDEX.md or a non-root `name:` that is not a valid store-LOCAL name, two files in one store owning one canonical identity, a `[[link]]` or literal `memory-read` route naming no document or directory in the view (a directory\u2019s own document answers at the directory name, never at `<dir>/INDEX`), a body longer than its delivery entries earn, and a repository whose root store’s workspace front door is missing or sits anywhere but its root INDEX.md. One canonical identity held by SEVERAL stores is legitimate (a linked worktree sharing its main checkout\u2019s namespace), so it is reported as a notice with the view\u2019s winner and every candidate, never failed. CI-friendly: non-zero exit on any error, warnings and notices stay non-fatal.',
     help: {
         name: 'memory lint',
-        summary: 'strict-parse the bounded memory corpus and validate project workspace front doors',
-        params: [],
+        summary: 'validate canonical identity, frontmatter, and references across the memory corpus',
+        params: [
+            selectorParam('scope-read', {}, 'Lints only that source class. Cross-store candidate notices and project front-door coverage need the unfiltered view, so a scope filter suppresses them.'),
+            selectorParam('dir', {}, 'Lints that one store even when the runtime refuses to mount it — the only way to check a project store before its repository namespace is declared. Its links and routes are resolved against the target view that project\u2019s own directory sees, and an unmounted store defers those reference checks (its identities are undetermined until the namespace exists).'),
+        ],
         output: [
-            { name: 'checked', type: 'number', required: true, constraint: 'Files linted across all corpora.' },
-            { name: 'corpora', type: 'object', required: true, constraint: 'Per-corpus counts: {memory_stores (files), profile_projects (managed dirs checked for a workspace front door)}.' },
-            { name: 'findings', type: 'object[]', required: true, constraint: 'One row per failure: {path, error}. Empty when green.' },
-            { name: 'warnings', type: 'string[]', required: true, constraint: 'Non-fatal authoring gaps detected for the directory where lint ran.' },
+            { name: 'checked', type: 'number', required: true, constraint: 'Markdown files examined.' },
+            { name: 'stores', type: 'number', required: true, constraint: 'Physical memory stores linted.' },
+            { name: 'profile_projects', type: 'number', required: false, constraint: 'Projects the selected profile manages that were checked for a workspace front door — zero under a scope filter excluding project stores. Absent under --dir.' },
+            { name: 'findings', type: 'object[]', required: true, constraint: 'One row per ERROR: {rule, path, message, name?, scope?, store_root?, paths?}. `rule` names the violated rule (yaml, schema, extension, length, store-namespace, namespace-placement, root-name, root-index-unaddressable, local-name, canonical-collision, dangling-link, memory-read-route, front-door, owner-path-collision). `paths` carries every file sharing a collided identity, read winner first. Empty when green.' },
+            { name: 'warnings', type: 'object[]', required: true, constraint: 'Same row shape, non-fatal authoring smells: short-preview, broad-memory-read, nested-store-boot, an advisory missing front door, a wildcard memory-read glob matching nothing.' },
+            { name: 'notices', type: 'object[]', required: true, constraint: 'Same row shape, inspection data rather than faults: cross-store-candidates (one canonical name held by several stores, winner first) and reference-check-deferred.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next command.' },
         ],
         outputKind: 'object',
-        effects: ['None. Read-only. Exits non-zero when any finding exists.'],
+        effects: ['None. Read-only. Exits non-zero when any error finding exists.'],
     },
-    run: async () => {
-        const findings = [];
-        const warnings = [];
-        let memoryCount = 0;
-        const workingDirectory = process.cwd();
-        // Substrate memory stores (ancestor projects/user/builtin), schema-aware.
-        // A source's corpus is its NATIVE memory dir plus each enabled plugin's memory dir —
-        // plugin docs are substrate docs and lint through the same schema gate.
-        //    MEMORY.md index files are not substrate docs — YAML-parse only.
-        //    Hidden dirs are skipped to mirror doc enumeration (a dot-segment
-        //    path never yields a doc name, so e.g. the maintainer store shipped
-        //    at builtin-memory/.crouter can never register) — lint must not
-        //    flag files the substrate can never load.
-        // The resolvable link targets: exact doc names, plus every proper name
-        // prefix — a bare-dir [[ref]] is a legal listing link (`crtr memory read
-        // <dir>` answers with the directory listing).
-        const corpusNames = new Set();
-        for (const doc of listAllMemoryDocs(undefined, true, true)) {
-            if (doc.name === '')
-                continue;
-            corpusNames.add(doc.name);
-            const segs = doc.name.split('/');
-            for (let i = 1; i < segs.length; i++)
-                corpusNames.add(segs.slice(0, i).join('/'));
-        }
-        const lintDir = (dir, scope) => {
-            if (!dir || !pathExists(dir))
-                return;
-            for (const file of walkFiles(dir, (n) => n.endsWith('.md'), (d) => d.startsWith('.'))) {
-                const relPath = relative(dir, file).split(sep).join('/');
-                if (!relPath)
-                    continue;
-                memoryCount += 1;
-                const fallbackName = normalizeDocName(relPath.replace(/\.md$/, ''));
-                lintFile(file, basename(file) !== 'MEMORY.md', findings, warnings, corpusNames, fallbackName, scope);
-            }
+    run: async (input) => {
+        const selector = resolveReadSelector({
+            scope: input['scope'],
+            dir: input['dir'],
+        });
+        const result = selector.store !== null
+            ? lintMemoryStore(selector.store, {
+                resolvable: resolvableNamesForStore(selector.store),
+                // Asked about directly, not as a profile-managed project: a missing
+                // front door is a gap to report, not a failed gate.
+                frontDoor: 'advisory',
+            })
+            : lintMemoryTarget({ ...(selector.scope === undefined ? {} : { scope: selector.scope }) });
+        const errors = result.errors.map(findingRow);
+        const warnings = result.warnings.map(findingRow);
+        const notices = result.notices.map(findingRow);
+        const counts = {
+            checked: result.checked,
+            stores: result.storesLinted,
+            ...('profileProjects' in result ? { profile_projects: result.profileProjects } : {}),
         };
-        for (const root of projectScopeRoots()) {
-            lintDir(join(root, 'memory'), 'project');
-            for (const plugin of listInstalledPluginsInRoot('project', root)) {
-                if (plugin.enabled)
-                    lintDir(pluginMemoryDir(plugin), 'project');
-            }
-        }
-        // Nested descendant stores: same schema gate, plus a boot-entry warning —
-        // the boot catalog deliberately never includes nested stores, so a boot
-        // surfaces entry there is inert.
-        for (const root of descendantStoreRoots(projectScopeRoots())) {
-            const dir = join(root, 'memory');
-            lintDir(dir, 'project');
-            if (!pathExists(dir))
-                continue;
-            for (const file of walkFiles(dir, (n) => n.endsWith('.md'), (d) => d.startsWith('.'))) {
-                if (basename(file) === 'MEMORY.md')
-                    continue;
-                let fm;
-                try {
-                    fm = parseFrontmatterGeneric(readText(file)).data;
-                }
-                catch {
-                    continue; // invalid YAML is already a finding from lintDir
-                }
-                if (fm !== null && parsedSurfaces(fm).some((e) => e.on === 'boot')) {
-                    warnings.push(`${file}: nested-store docs never ride the boot catalog, so its boot surfaces entries are inert — drop them`);
-                }
-            }
-        }
-        for (const scope of ['user', 'builtin']) {
-            lintDir(scopeMemoryDir(scope), scope);
-            for (const plugin of listInstalledPlugins(scope)) {
-                if (plugin.enabled)
-                    lintDir(pluginMemoryDir(plugin), scope);
-            }
-        }
-        // Profile coverage: each managed project has exactly ONE workspace front
-        // door — a doc carrying {on: workspace-open, at: content}, the guide that
-        // enters first-message context when cwd/profile mounts the store. Zero
-        // means agents open the workspace blind; two means both deliver whole at
-        // every open, and the store needs consolidating.
-        let profileProjects = 0;
-        let profileResolved = false;
-        const profileIdOrName = process.env['CRTR_PROFILE_ID'] || getDefaultProfileId(process.cwd());
-        if (profileIdOrName) {
-            try {
-                const { profileId, manifest } = loadProfileManifest(profileIdOrName);
-                profileResolved = true;
-                lintDir(profileMemoryDir(profileId), 'user');
-                for (const project of manifest.projects) {
-                    profileProjects += 1;
-                    const dir = project.path;
-                    const doors = frontDoorDocs(join(dir, '.crouter', 'memory'));
-                    if (doors.length === 0) {
-                        findings.push({
-                            path: dir,
-                            error: `profile "${manifest.name}" manages this dir but no doc in its .crouter/memory carries a {on: workspace-open, at: content} surfaces entry — ${FRONT_DOOR_REMEDY}`,
-                        });
-                    }
-                    else if (doors.length > 1) {
-                        findings.push({
-                            path: dir,
-                            error: `multiple workspace front doors (${doors.length}): ${doors.join(', ')} — exactly one doc per project store may carry {on: workspace-open, at: content}; consolidate the others into it or lower their entries`,
-                        });
-                    }
-                }
-            }
-            catch {
-                // Unresolvable profile: profile coverage does not apply. Treat cwd as
-                // unprofiled for the advisory front-door warning below.
-            }
-        }
-        // Without a selected, resolvable profile there is no managed-project
-        // finding to carry this signal, so keep a non-fatal cwd adoption warning.
-        if (!profileResolved) {
-            if (frontDoorDocs(join(workingDirectory, '.crouter', 'memory')).length === 0) {
-                warnings.push(`${workingDirectory}: no workspace front door — ${FRONT_DOOR_REMEDY}`);
-            }
-        }
-        const checked = memoryCount;
-        // Warnings are surfaced on stderr and returned structurally, but never
-        // convert a green corpus into a failed authoring gate.
-        for (const warning of warnings)
-            warn(`memory lint: warning: ${warning}`);
-        if (findings.length > 0) {
-            // Human/agent path renders only the message — surface every offender as
-            // a scoped stderr notice (the --json path carries them in details too).
-            for (const f of findings)
-                warn(`memory lint: ${f.path}: ${f.error}`);
-            throw general(`memory lint: ${findings.length} finding(s) across ${checked} files`, {
-                checked,
-                findings: findings.map((f) => ({ path: f.path, error: f.error })),
-                warnings,
-                next: 'Fix each doc (quote YAML values containing `: `; use a valid kind; run `crtr sys migrate` for retired visibility fields; give each surfaces entry a valid on/at and the match its event requires; retarget or drop dangling [[links]]; split an over-length body into [[linked]] surface-less reference docs); give every profile-managed project exactly one workspace front door; then re-run `crtr memory lint`.',
-            });
+        for (const finding of [...result.warnings, ...result.errors]) {
+            warn(`memory lint: ${finding.rule}: ${finding.path}: ${finding.message}`);
         }
+        // A failing lint still owes its declared rows — the findings ARE the
+        // result. It fails by exit code, not by throwing them away.
+        if (errors.length > 0)
+            process.exitCode = ExitCode.GENERAL;
         return {
-            checked,
-            corpora: { memory_stores: memoryCount, profile_projects: profileProjects },
-            findings: [],
+            ...counts,
+            findings: errors,
             warnings,
-            follow_up: warnings.length > 0 ? 'Corpus green — review the warnings above for non-fatal authoring improvements.' : 'Corpus green — zero invalid frontmatter docs.',
+            notices,
+            follow_up: errors.length > 0
+                ? `${errors.length} error(s) across ${result.checked} files in ${result.storesLinted} store(s) — fix each, then re-run. A repository store that does not mount is repaired with \`crtr sys migrate --dir <repository-root>\`; an owner-path collision is fixed by renaming one of the directories named in the finding; a canonical collision is recovered with \`crtr memory move <name> --to <new-free-name>\` (it selects the first physical path in stable lexical order); a dangling link or route is retargeted with the name \`crtr memory find <leaf>\` reports, or dropped; an over-length body splits into [[linked]] surface-less reference docs.`
+                : warnings.length > 0
+                    ? 'No errors — review the warnings above, then revise with `crtr memory edit <name> --rationale "<why>"`.'
+                    : 'No errors. Notices are inspection data, not faults: a canonical name held by several stores is reachable per-store with `crtr memory read <name> --dir <project>`.',
         };
     },
 });

package/dist/commands/memory/list.d.ts

@@ -1,15 +1,23 @@
 import type { MemoryDoc, MemoryScope } from '../../core/memory-resolver.js';
-/** A fully-resolved memory inventory before command pagination/output shaping.
- * Shared in-process consumers retain `memory list`'s scope ordering and
- * identity behavior without rescanning the corpus once per output page. */
+/** One inventory row before pagination/output shaping. */
 export interface ListedMemoryDoc {
     name: string;
     kind: string;
     scope: MemoryScope;
     path: string;
+    storeRoot: string;
+    physicalRelativePath: string;
     shortForm: string;
     slash: boolean;
     extensions: Record<string, Record<string, string | boolean | number>>;
+    /** Every physical document sharing this canonical name in the same corpus,
+     *  in source order — the winner first. */
+    candidates: readonly MemoryDoc[];
 }
-export declare function listMemoryDocs(kindFilter?: string, scopeFilter?: MemoryScope, quiet?: boolean, docs?: readonly MemoryDoc[]): ListedMemoryDoc[];
+/** The inventory over one corpus. A target view is winner-only: one row per
+ *  canonical identity, first in source order, because that is the document a
+ *  read of the name returns. An exact store (`--dir`) is not deduped — the
+ *  point of naming a store is to see what it physically holds, including a pair
+ *  that shares one identity. */
+export declare function listMemoryDocs(kindFilter: string | undefined, docs: readonly MemoryDoc[], dedup: boolean): ListedMemoryDoc[];
 export declare const listLeaf: import("../../core/command.js").LeafDef;