@crouton-kit/crouter 0.3.17 → 0.3.19

package/dist/core/canvas/wakeups.js

@@ -0,0 +1,185 @@
+// wakeups.ts — the WAKEUPS table data-access layer (canvas.db, migration v7).
+//
+// One-module-per-table (the focuses.ts precedent): ALL SQL that touches the
+// `wakeups` table lives HERE and nowhere else — never appended to canvas.ts,
+// which keeps the node/edge model. A WAKEUP is one durable row = "do <kind> at
+// fire_at [every recur]", carrying a fire time, a kind, an optional payload, an
+// optional recurrence cadence, a nullable TARGET node_id, and the owner_id of
+// the node that ARMED it.
+//
+// Two anchors, two reap rules (design D1/D2):
+//   - node_id  → the revive target AND the node-anchored cancel anchor; it
+//     carries the `ON DELETE CASCADE` FK, so a pruned node's node-anchored wakes
+//     are reaped FOR FREE in pruneNodes' same `DELETE FROM nodes` (canvas.ts is
+//     UNTOUCHED — the cascade does it; there is no pruneNodes wakeups code).
+//     NULL = canvas-detached (a deferred spawn / spawn-cron).
+//   - owner_id → the armer; a PLAIN indexed column with NO FK, so a crashed-
+//     then-pruned armer's detached cron is NOT cascade-dropped (Invariant E).
+//     Reaped only by the explicit cancelWakesFor DELETE on deliberate close.
+//
+// Each function is a single-statement query mirroring the canvas.ts atomic-setter
+// pattern (setStatus/setIntent/setPresence) — no read-modify-write, serialized by
+// WAL. The data-access layer OWNS payload serialization: armWake JSON.stringifies
+// the typed per-kind union on write; dueWakes/listWakes JSON.parse it back on read
+// (Maj-1), so callers consume `payload.body` / `payload as SpawnChildOpts` directly.
+//
+// `wakeup_id` is CALLER-SUPPLIED (the command surface mints `wk-${newNodeId()}`):
+// the canvas layer never imports newNodeId from runtime/nodes.ts — that would
+// force a canvas → runtime → canvas import cycle (Min-1).
+import { openDb } from './db.js';
+/** A thrown integrity-backstop error from armWake. `code` is the AC-N3 code the
+ *  command surface (the ONLY sanctioned caller of armWake) maps to a rendered
+ *  error block — armWake carries integrity backstops only (empty body / recur-on-
+ *  deadline / unknown kind); target-resolvability + recoverable-state + the
+ *  per-owner cap live in the surface (Min-6), so a non-surface armer could insert
+ *  a dangling wake — every armer MUST route through the surface. */
+export class WakeArmError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'WakeArmError';
+    }
+}
+/** Hydrate a raw row into a Wakeup, JSON.parsing `payload` back into the typed
+ *  per-kind union (NULL column → null). */
+function wakeupFrom(r) {
+    const raw = r['payload'];
+    return {
+        wakeup_id: r['wakeup_id'],
+        node_id: r['node_id'] ?? null,
+        owner_id: r['owner_id'],
+        fire_at: r['fire_at'],
+        kind: r['kind'],
+        recur: r['recur'] ?? null,
+        payload: raw == null ? null : JSON.parse(raw),
+        created: r['created'],
+    };
+}
+// ---------------------------------------------------------------------------
+// Writes — each a single-statement INSERT/UPDATE/DELETE.
+// ---------------------------------------------------------------------------
+/** INSERT one wakeup row from the pinned spec, returning its (caller-supplied)
+ *  `wakeup_id`. JSON.stringifies the typed `payload` union into the TEXT column
+ *  and stamps `created`.
+ *
+ *  Deadline upsert (design Q3, "≤1 deadline per node"): for `kind === 'deadline'`
+ *  the node's existing deadline is canceled first, then the new one inserted — the
+ *  partial unique index `idx_wakeups_deadline` is the schema-level backstop.
+ *
+ *  Integrity backstops (throw WakeArmError; the surface maps the code to AC-N3):
+ *   - empty/whitespace note `body` for `noted`/`deadline` → `empty_note`.
+ *   - non-NULL `recur` on a `deadline`                    → `deadline_cannot_recur`.
+ *   - unknown `kind`                                      → `bad_kind`.
+ *  NO target-resolvability / recoverable-state / cap backstop here (Min-6). */
+export function armWake(spec) {
+    const { kind } = spec;
+    if (kind !== 'bare' && kind !== 'noted' && kind !== 'deadline' && kind !== 'spawn') {
+        throw new WakeArmError('bad_kind', `unknown wake kind: ${String(kind)}`);
+    }
+    if (kind === 'noted' || kind === 'deadline') {
+        const body = spec.payload?.body;
+        if (typeof body !== 'string' || body.trim() === '') {
+            throw new WakeArmError('empty_note', `a ${kind} wake requires a non-empty note body.`);
+        }
+    }
+    if (kind === 'deadline' && spec.recur != null) {
+        throw new WakeArmError('deadline_cannot_recur', 'a deadline wake cannot recur.');
+    }
+    // Deadline upsert: clear the node's existing deadline before inserting the new one.
+    if (kind === 'deadline' && spec.node_id != null) {
+        cancelDeadlinesFor(spec.node_id);
+    }
+    const payloadText = spec.payload == null ? null : JSON.stringify(spec.payload);
+    openDb()
+        .prepare(`INSERT INTO wakeups (wakeup_id, node_id, owner_id, fire_at, kind, recur, payload, created)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`)
+        .run(spec.wakeup_id, spec.node_id ?? null, spec.owner_id, spec.fire_at, kind, spec.recur ?? null, payloadText, new Date().toISOString());
+    return spec.wakeup_id;
+}
+/** UPDATE the next fire time — recurrence advancement (the daemon settles a
+ *  recurring row to its next slot BEFORE enacting, crash-safe; design D4). */
+export function advanceWake(wakeup_id, nextFireIso) {
+    openDb().prepare('UPDATE wakeups SET fire_at = ? WHERE wakeup_id = ?').run(nextFireIso, wakeup_id);
+}
+/** DELETE one wakeup by id — one-shot consumption (the daemon settles a one-shot
+ *  row BEFORE enacting, crash-safe; design D4). */
+export function consumeWake(wakeup_id) {
+    openDb().prepare('DELETE FROM wakeups WHERE wakeup_id = ?').run(wakeup_id);
+}
+/** DELETE one wakeup by id — the explicit user/surface cancel. Idempotent:
+ *  0 rows ⇒ no error (AC-C2). */
+export function cancelWake(wakeup_id) {
+    openDb().prepare('DELETE FROM wakeups WHERE wakeup_id = ?').run(wakeup_id);
+}
+/** DELETE every wake anchored to this node AND every detached wake it ARMED —
+ *  deliberate close/reap (ruling A). Hooked at transition('cancel'). */
+export function cancelWakesFor(node_id) {
+    openDb()
+        .prepare('DELETE FROM wakeups WHERE node_id = ? OR owner_id = ?')
+        .run(node_id, node_id);
+}
+/** DELETE this node's one-shot self-alarms (recur IS NULL); node-anchored crons
+ *  SURVIVE — finalize is the instance finishing, not a teardown of standing
+ *  schedules (design Q1). Hooked at transition('finalize'). */
+export function cancelSelfAlarms(node_id) {
+    openDb().prepare('DELETE FROM wakeups WHERE node_id = ? AND recur IS NULL').run(node_id);
+}
+/** DELETE this node's pending deadline(s) — cancel-on-wake (design §6.4).
+ *  Hooked at reviveNode, so the deadline always belongs to the dormancy left. */
+export function cancelDeadlinesFor(node_id) {
+    openDb().prepare("DELETE FROM wakeups WHERE node_id = ? AND kind = 'deadline'").run(node_id);
+}
+// ---------------------------------------------------------------------------
+// Reads.
+// ---------------------------------------------------------------------------
+/** The daemon's per-tick due query: every row whose fire_at has arrived, in
+ *  fire_at order, with `payload` parsed into the typed union. Returns exactly ONE
+ *  row per recurring wake regardless of missed slots — coalescing is structural
+ *  (AC-E2). */
+export function dueWakes(nowIso) {
+    return openDb()
+        .prepare('SELECT * FROM wakeups WHERE fire_at <= ? ORDER BY fire_at')
+        .all(nowIso).map(wakeupFrom);
+}
+/** List wakes for a scope (node / owner / subtree / due / canvas), `payload`
+ *  parsed as in dueWakes. The subtree variant binds the id set with `?`
+ *  placeholders (mirroring listNodes — the codebase's one safe dynamic-IN spot);
+ *  ids are NEVER string-concatenated (Min-10). */
+export function listWakes(scope) {
+    const db = openDb();
+    let rows;
+    if ('node' in scope) {
+        rows = db
+            .prepare('SELECT * FROM wakeups WHERE node_id = ? ORDER BY fire_at')
+            .all(scope.node);
+    }
+    else if ('owner' in scope) {
+        rows = db
+            .prepare('SELECT * FROM wakeups WHERE owner_id = ? ORDER BY fire_at')
+            .all(scope.owner);
+    }
+    else if ('subtree' in scope) {
+        if (scope.subtree.length === 0)
+            return [];
+        const placeholders = scope.subtree.map(() => '?').join(',');
+        rows = db
+            .prepare(`SELECT * FROM wakeups WHERE node_id IN (${placeholders}) ORDER BY fire_at`)
+            .all(...scope.subtree);
+    }
+    else if ('due' in scope) {
+        rows = db
+            .prepare('SELECT * FROM wakeups WHERE fire_at <= ? ORDER BY fire_at')
+            .all(scope.due);
+    }
+    else {
+        rows = db.prepare('SELECT * FROM wakeups ORDER BY fire_at').all();
+    }
+    return rows.map(wakeupFrom);
+}
+/** True if the node has ANY pending self-anchored wake (of any kind). Consumed by
+ *  the stop-guard self-wake seam so a no-child poll node releases dormant after
+ *  arming instead of being nagged to finish (AC-X3/AC-R1). */
+export function hasPendingSelfWake(node_id) {
+    return (openDb().prepare('SELECT 1 FROM wakeups WHERE node_id = ? LIMIT 1').get(node_id) !== undefined);
+}

package/dist/core/config.js

@@ -137,7 +137,10 @@ function mergeConfig(partial) {
         ? Math.floor(rawMaxPanes)
         : defaults.max_panes_per_window;
     const canvasNav = mergeCanvasNav(partial.canvasNav);
-    return { schema_version, marketplaces, plugins, skills, auto_update, max_panes_per_window, canvasNav };
+    // The merge drops unknown keys, so `headless` must be carried explicitly or it
+    // is lost on every read-modify-write of config.json.
+    const headless = typeof partial.headless === 'boolean' ? partial.headless : defaults.headless;
+    return { schema_version, marketplaces, plugins, skills, auto_update, max_panes_per_window, canvasNav, headless };
 }
 export function updateConfig(scope, mutate) {
     const cfg = readConfig(scope);

package/dist/core/frontmatter.js

@@ -1,3 +1,4 @@
+import { parse as parseYaml } from 'yaml';
 import { isSkillType } from '../types.js';
 const FRONTMATTER_RE = /^---\s*\r?\n([\s\S]*?)\r?\n---\s*\r?\n?/;
 export function parseFrontmatter(source) {
@@ -7,7 +8,7 @@ export function parseFrontmatter(source) {
     }
     const raw = match[1];
     const body = source.slice(match[0].length);
-    return { data: toSkillFrontmatter(parseYamlRecord(raw)), body, raw };
+    return { data: toSkillFrontmatter(parseYamlBlock(raw)), body, raw };
 }
 /** Like parseFrontmatter but returns the raw key/value record instead of
  *  coercing to SkillFrontmatter. Used by consumers (e.g. subagents) that read
@@ -19,138 +20,50 @@ export function parseFrontmatterGeneric(source) {
     }
     const raw = match[1];
     const body = source.slice(match[0].length);
-    return { data: parseYamlRecord(raw), body, raw };
+    return { data: parseYamlBlock(raw), body, raw };
 }
 function toSkillFrontmatter(out) {
     const fm = {
-        name: typeof out.name === 'string' ? out.name : '',
-        description: typeof out.description === 'string' ? out.description : undefined,
-        keywords: Array.isArray(out.keywords) ? out.keywords : undefined,
+        name: scalarToString(out.name) ?? '',
+        description: scalarToString(out.description),
+        keywords: Array.isArray(out.keywords) ? out.keywords.map((k) => String(k)) : undefined,
         type: isSkillType(out.type) ? out.type : undefined,
     };
     return fm;
 }
-function parseYamlRecord(yaml) {
-    const lines = yaml.split(/\r?\n/);
-    const out = {};
-    let i = 0;
-    while (i < lines.length) {
-        const raw = lines[i];
-        if (!raw.trim()) {
-            i++;
-            continue;
-        }
-        const idx = raw.indexOf(':');
-        if (idx === -1) {
-            i++;
-            continue;
-        }
-        const key = raw.slice(0, idx).trim();
-        const rest = raw.slice(idx + 1).trim();
-        // Block scalar: `key: |` or `key: >` with optional chomp indicator (-/+)
-        const blockMatch = rest.match(/^([|>])([-+]?)\s*$/);
-        if (blockMatch) {
-            const style = blockMatch[1];
-            const chomp = blockMatch[2];
-            const collected = [];
-            let blockIndent = null;
-            let j = i + 1;
-            while (j < lines.length) {
-                const r = lines[j];
-                if (r.trim() === '') {
-                    collected.push('');
-                    j++;
-                    continue;
-                }
-                const ind = r.match(/^(\s*)/)?.[1].length ?? 0;
-                if (blockIndent === null) {
-                    if (ind === 0)
-                        break;
-                    blockIndent = ind;
-                }
-                if (ind < blockIndent)
-                    break;
-                collected.push(r.slice(blockIndent));
-                j++;
-            }
-            while (collected.length > 0 && collected[collected.length - 1] === '')
-                collected.pop();
-            let value;
-            if (style === '|') {
-                value = collected.join('\n');
-            }
-            else {
-                const parts = [];
-                let para = [];
-                for (const ln of collected) {
-                    if (ln === '') {
-                        if (para.length > 0) {
-                            parts.push(para.join(' '));
-                            para = [];
-                        }
-                        parts.push('');
-                    }
-                    else {
-                        para.push(ln);
-                    }
-                }
-                if (para.length > 0)
-                    parts.push(para.join(' '));
-                const folded = [];
-                for (let k = 0; k < parts.length; k++) {
-                    if (parts[k] === '' && (k === 0 || parts[k - 1] === ''))
-                        continue;
-                    folded.push(parts[k]);
-                }
-                value = folded.join('\n').replace(/\n+$/, '');
-            }
-            if (chomp !== '+')
-                value = value.replace(/\n+$/, '');
-            out[key] = value;
-            i = j;
-            continue;
-        }
-        // Empty value: could be a list on subsequent lines
-        if (rest === '') {
-            const buf = [];
-            let j = i + 1;
-            while (j < lines.length) {
-                const r = lines[j];
-                if (r.trim() === '') {
-                    j++;
-                    continue;
-                }
-                if (/^\s*-\s+/.test(r)) {
-                    buf.push(stripQuotes(r.replace(/^\s*-\s+/, '').trim()));
-                    j++;
-                    continue;
-                }
-                break;
-            }
-            if (buf.length > 0)
-                out[key] = buf;
-            i = j;
-            continue;
-        }
-        if (rest.startsWith('[') && rest.endsWith(']')) {
-            out[key] = rest
-                .slice(1, -1)
-                .split(',')
-                .map((s) => stripQuotes(s.trim()))
-                .filter(Boolean);
-            i++;
-            continue;
-        }
-        out[key] = stripQuotes(rest);
-        i++;
-    }
-    return out;
+/** Coerce a YAML scalar (string/number/boolean) to its string form. A skill's
+ *  `name`/`description` are always strings to consumers; native non-string
+ *  scalars (a numeric/boolean value) render as their string form, and
+ *  non-scalars (null/undefined/array/object) yield undefined. */
+function scalarToString(v) {
+    if (typeof v === 'string')
+        return v;
+    if (typeof v === 'number' || typeof v === 'boolean')
+        return String(v);
+    return undefined;
+}
+/** Parse the inner YAML of a frontmatter block into a key/value record.
+ *
+ *  ONE strict parser, no fallback. The frontmatter contract IS "valid YAML":
+ *  the single `yaml`-package path handles the substrate's nested `gate:` maps,
+ *  inline `{…}` objects, and native scalar typing — and a doc whose frontmatter
+ *  is NOT valid YAML THROWS, by design. There is deliberately no second lenient
+ *  parser; a dual parsing strategy is the hedge we reject. Callers that iterate
+ *  MANY docs isolate a per-doc throw at the COLLECTION layer (a clear scoped
+ *  notice naming the bad file, then continue); single-doc callers let the error
+ *  surface so the user learns their one requested doc is malformed.
+ *
+ *  A VALID non-object document (a bare scalar, a top-level list, or an empty
+ *  block) normalizes to an empty record, preserving the contract that callers
+ *  always receive a Record for well-formed-but-non-mapping frontmatter. */
+function parseYamlBlock(raw) {
+    return normalizeToRecord(parseYaml(raw));
 }
-function stripQuotes(s) {
-    if ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'"))) {
-        return s.slice(1, -1);
+function normalizeToRecord(parsed) {
+    if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        return parsed;
     }
-    return s;
+    return {};
 }
 export function serializeFrontmatter(data) {
     const lines = ['---'];

package/dist/core/help.d.ts

@@ -162,6 +162,12 @@ export interface LeafHelp {
     /** Every persistent change the command makes to the world. For read-only
      *  leaves use exactly: ["None. Read-only."] */
     effects: string[];
+    /** Bounded runtime aggregate as a complete self-named state element (build it
+     *  with stateBlock), e.g. `<kinds count="7">…</kinds>`. Lazily evaluated at
+     *  render time so it reflects the caller's cwd/project scope; appended after
+     *  the schema. Renderer soft-fails to omission if it returns null or throws.
+     *  Mirrors BranchHelp.dynamicState. */
+    dynamicState?: () => string | null;
 }
 /** Build a self-named runtime-state element: `<tag attr="v">body</tag>`. The
  *  subtree that owns the state authors it through this, so the tag name and any

package/dist/core/help.js

@@ -238,5 +238,12 @@ export function renderLeafArgv(h) {
     for (const e of h.effects) {
         lines.push(`  ${e}`);
     }
+    // Optional bounded runtime-state block (e.g. the live <kinds> list), appended
+    // after the schema. Soft-fails to omission on null/throw, mirroring renderBranch.
+    const state = evalDynamic(h.dynamicState);
+    if (state !== null) {
+        lines.push('');
+        lines.push(state);
+    }
     return lines.join('\n');
 }

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

@@ -0,0 +1,49 @@
+import type { Scope } from '../types.js';
+/**
+ * Thin memory-document resolver for the document substrate. Mirrors the SHAPE
+ * of the skill resolver (qualifier parse → scope precedence → direct path
+ * lookup → leaf-name fallback) but drops ALL plugin machinery: memory
+ * resolution is scope + leaf/path ONLY. The three memory scopes resolve in
+ * precedence order project > user > builtin (the same precedence concept as
+ * orderPluginsByResolution, minus plugins). 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`).
+ */
+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". */
+    name: string;
+    scope: Scope;
+    /** Absolute path to the resolved .md file. */
+    path: string;
+    /** Raw, uncoerced frontmatter record (null when the doc has no frontmatter). */
+    frontmatter: Record<string, unknown> | null;
+    /** Document body, with the frontmatter block stripped. */
+    body: string;
+}
+export interface MemoryResolutionOpts {
+    /** Restrict resolution to a single scope. Conflicts with a scope prefix on
+     *  the identifier (e.g. `user/foo` with scope=project) throw. */
+    scope?: Scope;
+}
+/** Canonical, unambiguous identifier for a memory document: `<scope>/<name>`. */
+export declare function memoryDocId(doc: MemoryDoc): string;
+/** All memory docs in one scope's memory/ dir, scanned recursively for *.md
+ *  (topical subdirs supported), sorted by path-derived name. */
+export declare function listMemoryDocs(scope: Scope): MemoryDoc[];
+/** All memory docs across the resolved scopes, in precedence order
+ *  (project, then user, then builtin), each scope's docs name-sorted within. */
+export declare function listAllMemoryDocs(scope?: Scope): MemoryDoc[];
+/**
+ * Resolve a path-derived name to a single memory document.
+ *
+ * Accepted identifier forms (mirroring parseSkillQualifier, no plugins):
+ *   <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.
+ *
+ * Resolution order: parse qualifier → direct memory/<name>.md lookup
+ * (precedence-first) → leaf-name fallback (ambiguity error listing candidates).
+ */
+export declare function resolveMemoryDoc(rawName: string, opts?: MemoryResolutionOpts): MemoryDoc;

package/dist/core/memory-resolver.js

@@ -0,0 +1,141 @@
+import { join, relative, sep } from 'node:path';
+import { pathExists, readText, walkFiles } from './fs-utils.js';
+import { parseFrontmatterGeneric } from './frontmatter.js';
+import { parseSkillQualifier } from './resolver.js';
+import { ambiguous, notFound, usage } from './errors.js';
+import { warn } from './output.js';
+import { projectScopeRoot, scopeMemoryDir } from './scope.js';
+/** Canonical, unambiguous identifier for a memory document: `<scope>/<name>`. */
+export function memoryDocId(doc) {
+    return `${doc.scope}/${doc.name}`;
+}
+/** The memory scopes in resolution precedence: project > user > builtin.
+ *  Project is included only when a project scope exists for the cwd. A single
+ *  `scope` narrows to just that scope. */
+function scopesInPrecedence(scope) {
+    if (scope)
+        return [scope];
+    const out = [];
+    if (projectScopeRoot())
+        out.push('project');
+    out.push('user');
+    out.push('builtin');
+    return out;
+}
+function loadMemoryDoc(name, scope, path) {
+    const { data, body } = parseFrontmatterGeneric(readText(path));
+    return { name, scope, path, frontmatter: data, body };
+}
+/** All memory docs in one scope's memory/ dir, scanned recursively for *.md
+ *  (topical subdirs supported), sorted by path-derived name. */
+export function listMemoryDocs(scope) {
+    const dir = scopeMemoryDir(scope);
+    if (!dir || !pathExists(dir))
+        return [];
+    const docs = [];
+    for (const file of walkFiles(dir, (n) => n.endsWith('.md'))) {
+        const name = relative(dir, file).replace(/\.md$/i, '').split(sep).join('/');
+        if (!name)
+            continue;
+        // COLLECTION layer: the strict frontmatter parser throws on invalid YAML.
+        // Isolate one malformed doc with a clear scoped notice + skip, so a single
+        // bad file can't brick `memory list`/`find` or the substrate boot render.
+        try {
+            docs.push(loadMemoryDoc(name, scope, file));
+        }
+        catch (e) {
+            const msg = (e instanceof Error ? e.message : String(e)).split('\n')[0];
+            warn(`invalid frontmatter in ${file}: ${msg}`);
+        }
+    }
+    return docs.sort((a, b) => a.name.localeCompare(b.name));
+}
+/** All memory docs across the resolved scopes, in precedence order
+ *  (project, then user, then builtin), each scope's docs name-sorted within. */
+export function listAllMemoryDocs(scope) {
+    return scopesInPrecedence(scope).flatMap(listMemoryDocs);
+}
+/** 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. */
+function findMemoryMatches(name, scope) {
+    const matches = [];
+    for (const s of scopesInPrecedence(scope)) {
+        const dir = scopeMemoryDir(s);
+        if (!dir)
+            continue;
+        const path = join(dir, ...name.split('/')) + '.md';
+        if (!pathExists(path))
+            continue;
+        matches.push(loadMemoryDoc(name, s, path));
+    }
+    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), mirroring findSkillsByLeaf. Returns matches precedence-ordered. */
+function findMemoryByLeaf(leaf, scope) {
+    if (leaf.includes('/'))
+        return [];
+    let all;
+    try {
+        all = listAllMemoryDocs(scope);
+    }
+    catch {
+        return [];
+    }
+    return all.filter((d) => (d.name.split('/').pop() ?? d.name) === leaf);
+}
+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.
+ *
+ * Accepted identifier forms (mirroring parseSkillQualifier, no plugins):
+ *   <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.
+ *
+ * Resolution order: parse qualifier → direct memory/<name>.md lookup
+ * (precedence-first) → leaf-name fallback (ambiguity error listing candidates).
+ */
+export function resolveMemoryDoc(rawName, opts = {}) {
+    const parsed = parseSkillQualifier(rawName);
+    if (parsed.scope && opts.scope && parsed.scope !== opts.scope) {
+        throw usage(`scope conflict: identifier "${rawName}" uses scope "${parsed.scope}" but --scope is "${opts.scope}"`);
+    }
+    const effectiveScope = opts.scope ?? parsed.scope;
+    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.',
+        });
+    }
+    throw notFound(`memory document not found: ${rawName}`, {
+        memory: name,
+        scope: parsed.scope,
+    });
+}

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

@@ -2,11 +2,12 @@
  * Persona composer public surface.
  *
  * Re-exports:
- *   - loadPersona / loadKernel / availableKinds   (loader — raw file access)
+ *   - loadPersona / loadKernel / availableKinds / kindWhenToUse / subPersonasFor
+ *                                (loader — raw file access)
  *   - resolve                    (high-level composer)
  *   - ResolvedPersona            (return type of resolve)
  */
-export { loadPersona, loadKernel, availableKinds, loadLifecycleFragment, loadSpineFragment } from './loader.js';
-export type { LoadedPersona } from './loader.js';
+export { loadPersona, loadKernel, availableKinds, kindWhenToUse, subPersonasFor, loadLifecycleFragment, loadSpineFragment } from './loader.js';
+export type { LoadedPersona, SubPersona } from './loader.js';
 export { resolve } from './resolve.js';
 export type { ResolvedPersona } from './resolve.js';

package/dist/core/personas/index.js

@@ -2,9 +2,10 @@
  * Persona composer public surface.
  *
  * Re-exports:
- *   - loadPersona / loadKernel / availableKinds   (loader — raw file access)
+ *   - loadPersona / loadKernel / availableKinds / kindWhenToUse / subPersonasFor
+ *                                (loader — raw file access)
  *   - resolve                    (high-level composer)
  *   - ResolvedPersona            (return type of resolve)
  */
-export { loadPersona, loadKernel, availableKinds, loadLifecycleFragment, loadSpineFragment } from './loader.js';
+export { loadPersona, loadKernel, availableKinds, kindWhenToUse, subPersonasFor, loadLifecycleFragment, loadSpineFragment } from './loader.js';
 export { resolve } from './resolve.js';