@crouton-kit/crouter 0.3.32 → 0.3.34

package/dist/core/{skill-sync → host-exports}/export.js

@@ -1,10 +1,12 @@
 /**
  * One-way export of crtr-generated host artifacts — the sole writer of
- * generated content to `~/.claude/skills`, `~/.claude/commands`, and
- * `~/.pi/agent/prompts`. Replaces the two host-dir writers that lived in
- * bootstrap.ts (`ensureBootSkill` + `ensureSlashCommands`), collapsing their
- * two clobber-guards into one `writeIfOurs` and their two kill-switches
- * (`CRTR_NO_BOOT_SKILL` / `CRTR_NO_MODE_CMDS`) into one `CRTR_NO_EXPORTS`.
+ * generated slash-command templates to `~/.claude/commands` and
+ * `~/.pi/agent/prompts`.
+ *
+ * crouter no longer exports Agent Skills / SKILL.md bundles. The export pass
+ * still prunes old marker-bearing `crtr-skills` bundles so hosts stop surfacing
+ * pi/Claude native skills after the memory cutover. Markerless files are
+ * user-owned and never removed.
  *
  * Triggered per-run by cli.ts (argv-gated, exactly as the old writers were) so
  * first-run provisioning is preserved. Best-effort: a provisioning fault must
@@ -14,8 +16,8 @@
 import { writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
-import { ensureDir, pathExists, readText } from '../fs-utils.js';
-import { builtinExportPairs } from './builtins.js';
+import { ensureDir, pathExists, readText, removePath } from '../fs-utils.js';
+import { builtinExportPairs, legacyExportArtifacts } from './builtins.js';
 const SKIP_SUBCOMMANDS = new Set([
     'help',
     '--help',
@@ -23,12 +25,14 @@ const SKIP_SUBCOMMANDS = new Set([
     '--version',
     '-v',
 ]);
-/** Skip provisioning for help/version invocations — never write on `-h`. */
-function shouldSkipForArgv(argv) {
+/** Skip provisioning side effects entirely for help/version invocations. */
+function shouldSkipAllForArgv(argv) {
     const sub = argv[2];
-    if (sub === undefined)
-        return true;
-    return SKIP_SUBCOMMANDS.has(sub);
+    return sub !== undefined && SKIP_SUBCOMMANDS.has(sub);
+}
+/** Skip slash-command writes for bare front-door boot; pruning still runs. */
+function shouldSkipWritesForArgv(argv) {
+    return argv[2] === undefined;
 }
 /** Whether a host runtime is in use (its root dir exists). crtr writes into a
  *  host's dirs only when present and never creates `~/.claude` or `~/.pi`. */
@@ -59,14 +63,33 @@ export function writeIfOurs(path, content, markerPrefix) {
     ensureDir(dirname(path));
     writeFileSync(path, content, 'utf8');
 }
-/** Render and write every built-in export artifact to every present host.
+/** Remove a legacy artifact only when its marker proves crtr generated it. */
+function removeIfOurs(path, target, markerPrefix) {
+    if (!pathExists(path))
+        return;
+    const existing = readText(path);
+    if (!existing.includes(markerPrefix))
+        return;
+    removePath(target.layout === 'bundle' ? dirname(path) : path);
+}
+/** Render and write every built-in export artifact to every present host, while
+ *  pruning legacy generated artifacts that should no longer be surfaced.
  *  Best-effort: swallows errors (debug-logged) so a provisioning fault never
  *  breaks an unrelated `crtr` command. Kill switch: `CRTR_NO_EXPORTS=1`. */
 export function provisionExports(root, argv = process.argv) {
     try {
         if (process.env.CRTR_NO_EXPORTS === '1')
             return;
-        if (shouldSkipForArgv(argv))
+        if (shouldSkipAllForArgv(argv))
+            return;
+        for (const artifact of legacyExportArtifacts()) {
+            for (const target of artifact.targets) {
+                if (!hostRootExists(target.host))
+                    continue;
+                removeIfOurs(targetPath(target, artifact.name), target, artifact.markerPrefix);
+            }
+        }
+        if (shouldSkipWritesForArgv(argv))
             return;
         for (const pair of builtinExportPairs(root)) {
             const content = pair.render();

package/dist/core/io.js

@@ -2,7 +2,7 @@
 // agent-ready markdown/XML the caller acts on directly (the result rendered FOR
 // the model, not data it parses); structured errors; stderr is diagnostics only
 // and never carries the result. The raw JSON object is available behind the
-// `--json` global for tooling. See cli-design SKILL.md / reference.md.
+// `--json` global for tooling. See the cli-design reference.
 import { CrtrError } from './errors.js';
 import { ExitCode } from '../types.js';
 import { renderError } from './render.js';

package/dist/core/log.d.ts

@@ -0,0 +1,9 @@
+export type LogLevel = 'error' | 'warn' | 'info' | 'debug';
+export declare function formatLogLine(level: LogLevel, component: string, message: string, fields?: Record<string, unknown>): string;
+export declare function appendLogLine(path: string, line: string): void;
+export declare function logger(component: string): {
+    error: (message: string, fields?: Record<string, unknown>) => void;
+    warn: (message: string, fields?: Record<string, unknown>) => void;
+    info: (message: string, fields?: Record<string, unknown>) => void;
+    debug: (message: string, fields?: Record<string, unknown>) => void;
+};

package/dist/core/log.js

@@ -0,0 +1,113 @@
+import { appendFileSync, existsSync, mkdirSync, renameSync, rmSync, statSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { crtrHome } from './canvas/paths.js';
+const LEVEL_RANK = {
+    error: 1,
+    warn: 2,
+    info: 3,
+    debug: 4,
+};
+const MAX_BYTES = 5 * 1024 * 1024;
+const ROTATIONS = 2;
+function envLevel() {
+    const raw = String(process.env['CRTR_LOG'] ?? '').trim().toLowerCase();
+    return raw === 'warn' || raw === 'info' || raw === 'debug' ? raw : 'error';
+}
+function shouldLog(level) {
+    return LEVEL_RANK[level] <= LEVEL_RANK[envLevel()];
+}
+function escapeControlChars(value) {
+    return value.replace(/[\0-\x1f\x7f]/g, (ch) => {
+        switch (ch) {
+            case '\n': return '\\n';
+            case '\r': return '\\r';
+            case '\t': return '\\t';
+            default: return `\\u${ch.charCodeAt(0).toString(16).padStart(4, '0')}`;
+        }
+    });
+}
+function formatValue(value) {
+    if (typeof value === 'string') {
+        const escaped = escapeControlChars(value);
+        return /^[^\s"'=]+$/.test(escaped) ? escaped : JSON.stringify(escaped);
+    }
+    if (typeof value === 'number' || typeof value === 'bigint' || typeof value === 'boolean')
+        return String(value);
+    if (value === null)
+        return 'null';
+    if (value === undefined)
+        return 'undefined';
+    return JSON.stringify(value, (_key, nested) => (typeof nested === 'string' ? escapeControlChars(nested) : nested));
+}
+export function formatLogLine(level, component, message, fields) {
+    const parts = [`${new Date().toISOString()} ${level.toUpperCase()} [${component}] ${escapeControlChars(message)}`];
+    if (fields !== undefined) {
+        for (const [key, value] of Object.entries(fields)) {
+            parts.push(`${key}=${formatValue(value)}`);
+        }
+    }
+    return parts.join(' ');
+}
+function rotateIfNeeded(path, nextLineBytes) {
+    if (!existsSync(path))
+        return;
+    let size = 0;
+    try {
+        size = statSync(path).size;
+    }
+    catch {
+        return;
+    }
+    if (size + nextLineBytes < MAX_BYTES)
+        return;
+    const second = `${path}.2`;
+    const first = `${path}.1`;
+    try {
+        rmSync(second, { force: true });
+    }
+    catch { /* best-effort */ }
+    try {
+        if (existsSync(first))
+            renameSync(first, second);
+    }
+    catch { /* best-effort */ }
+    try {
+        renameSync(path, first);
+    }
+    catch { /* best-effort */ }
+}
+export function appendLogLine(path, line) {
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        appendFileSync(path, `${line}\n`, 'utf8');
+    }
+    catch {
+        /* best-effort */
+    }
+}
+function appendRotatingLogLine(path, line) {
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        rotateIfNeeded(path, Buffer.byteLength(`${line}\n`, 'utf8'));
+        appendFileSync(path, `${line}\n`, 'utf8');
+    }
+    catch {
+        /* best-effort */
+    }
+}
+export function logger(component) {
+    const sink = component === 'crtrd' ? join(crtrHome(), 'crtrd.log') : null;
+    const emit = (level, message, fields) => {
+        const line = formatLogLine(level, component, message, fields);
+        if (sink !== null && (level !== 'debug' || shouldLog(level)))
+            appendRotatingLogLine(sink, line);
+        if (shouldLog(level))
+            process.stderr.write(`${line}\n`);
+    };
+    return {
+        error: (message, fields) => emit('error', message, fields),
+        warn: (message, fields) => emit('warn', message, fields),
+        info: (message, fields) => emit('info', message, fields),
+        debug: (message, fields) => emit('debug', message, fields),
+    };
+}

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

@@ -1,13 +1,13 @@
 import type { InstalledPlugin, 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
+ * 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 three memory scopes resolve in precedence order
+ * project > user > builtin. 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/`,
+ * while user and builtin remain singleton scopes.
  */
 export interface MemoryDoc {
     /** Path-derived identity: the doc's path under the scope's memory/ root, no
@@ -28,23 +28,23 @@ export interface MemoryResolutionOpts {
 }
 /** 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. */
+/** All native memory docs for a scope. Project scope is a nearest-first stack of
+ *  every ancestor `.crouter/memory/`; user and builtin are singleton stores. */
 export declare function listMemoryDocs(scope: Scope): MemoryDoc[];
 /** All of one plugin's substrate docs, mounted under the virtual `<pluginName>/`
  *  namespace. Walks `pluginMemoryDir(plugin)` recursively for *.md, deriving each
  *  doc's name exactly as `listMemoryDocs` does (path-relative, no extension,
  *  slash-separated) then prefixing the plugin name. Builtin has no plugins. */
 export declare function listPluginMemoryDocs(plugin: InstalledPlugin, scope: Scope): MemoryDoc[];
-/** All memory docs across the resolved scopes, in precedence order
- *  (project, then user, then builtin). Within each scope, native docs are
- *  emitted FIRST, then that scope's enabled-plugin docs — so native wins on the
- *  caller's first-wins (scope,name) dedup. Each group is name-sorted within. */
+/** All memory docs across the resolved sources, in precedence order: each
+ *  ancestor project `.crouter/` from nearest to farthest, 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 declare function listAllMemoryDocs(scope?: Scope): MemoryDoc[];
 /**
  * Resolve a path-derived name to a single memory document.
  *
- * Accepted identifier forms (mirroring parseSkillQualifier, no plugins):
+ * 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

package/dist/core/memory-resolver.js

@@ -2,10 +2,10 @@ import { join, relative, sep } from 'node:path';
 import { readdirSync } from 'node:fs';
 import { pathExists, readText, walkFiles } from './fs-utils.js';
 import { parseFrontmatterGeneric } from './frontmatter.js';
-import { listInstalledPlugins, parseSkillQualifier } from './resolver.js';
+import { listInstalledPlugins, listInstalledPluginsInRoot, parseSkillQualifier } from './resolver.js';
 import { ambiguous, notFound, usage } from './errors.js';
 import { warn } from './output.js';
-import { pluginMemoryDir, projectScopeRoot, scopeMemoryDir } from './scope.js';
+import { pluginMemoryDir, projectScopeRoot, projectScopeRoots, scopeMemoryDir } from './scope.js';
 /** Canonical, unambiguous identifier for a memory document: `<scope>/<name>`. */
 export function memoryDocId(doc) {
     return `${doc.scope}/${doc.name}`;
@@ -23,21 +23,43 @@ function scopesInPrecedence(scope) {
     out.push('builtin');
     return out;
 }
+/** Memory loads project scopes as a stack, not a single nearest root: every
+ *  ancestor `.crouter/` from cwd upward contributes, nearest first. User and
+ *  builtin remain singleton scopes after that stack. */
+function memorySourcesInPrecedence(scope) {
+    const out = [];
+    for (const s of scopesInPrecedence(scope)) {
+        if (s === 'project') {
+            for (const root of projectScopeRoots()) {
+                out.push({
+                    scope: 'project',
+                    memoryDir: join(root, 'memory'),
+                    plugins: listInstalledPluginsInRoot('project', root).filter((p) => p.enabled),
+                });
+            }
+        }
+        else {
+            out.push({
+                scope: s,
+                memoryDir: scopeMemoryDir(s),
+                plugins: listInstalledPlugins(s).filter((p) => p.enabled),
+            });
+        }
+    }
+    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);
+/** 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/. */
+function listMemoryDocsInDir(scope, dir) {
     if (!dir || !pathExists(dir))
         return [];
     const docs = [];
-    // Walk: a dir containing SKILL.md is a single substrate bundle — emit ONE doc
-    // named by the dir's relative path, sourced from its SKILL.md, and STOP
-    // descending (deeper files are bundle assets, not docs). Every other dir
-    // yields its flat *.md files (topical subdirs / INDEX.md) as before.
     const found = [];
     const stack = [dir];
     while (stack.length) {
@@ -49,17 +71,10 @@ export function listMemoryDocs(scope) {
         catch {
             continue;
         }
-        const hasSkill = entries.some((e) => e.isFile() && e.name === 'SKILL.md');
-        if (hasSkill) {
-            const name = relative(dir, d).split(sep).join('/');
-            if (name)
-                found.push({ path: join(d, 'SKILL.md'), name });
-            continue; // stop descent — deeper dirs are assets
-        }
         for (const e of entries) {
             if (e.isDirectory())
                 stack.push(join(d, e.name));
-            else if (e.isFile() && e.name.endsWith('.md')) {
+            else if (e.isFile() && e.name.endsWith('.md') && e.name !== 'SKILL.md') {
                 const file = join(d, e.name);
                 const name = relative(dir, file).replace(/\.md$/i, '').split(sep).join('/');
                 if (name)
@@ -81,6 +96,14 @@ export function listMemoryDocs(scope) {
     }
     return docs.sort((a, b) => a.name.localeCompare(b.name));
 }
+/** All native memory docs for a scope. Project scope is a nearest-first stack of
+ *  every ancestor `.crouter/memory/`; user and builtin are singleton stores. */
+export function listMemoryDocs(scope) {
+    if (scope === 'project') {
+        return projectScopeRoots().flatMap((root) => listMemoryDocsInDir('project', join(root, 'memory')));
+    }
+    return listMemoryDocsInDir(scope, scopeMemoryDir(scope));
+}
 /** All of one plugin's substrate docs, mounted under the virtual `<pluginName>/`
  *  namespace. Walks `pluginMemoryDir(plugin)` recursively for *.md, deriving each
  *  doc's name exactly as `listMemoryDocs` does (path-relative, no extension,
@@ -90,7 +113,7 @@ export function listPluginMemoryDocs(plugin, scope) {
     if (!pathExists(dir))
         return [];
     const docs = [];
-    for (const file of walkFiles(dir, (n) => n.endsWith('.md'))) {
+    for (const file of walkFiles(dir, (n) => n.endsWith('.md') && n !== 'SKILL.md')) {
         const derived = relative(dir, file).replace(/\.md$/i, '').split(sep).join('/');
         if (!derived)
             continue;
@@ -105,16 +128,14 @@ export function listPluginMemoryDocs(plugin, scope) {
     }
     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). Within each scope, native docs are
- *  emitted FIRST, then that scope's enabled-plugin docs — so native wins on the
- *  caller's first-wins (scope,name) dedup. Each group is name-sorted within. */
+/** All memory docs across the resolved sources, in precedence order: each
+ *  ancestor project `.crouter/` from nearest to farthest, 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) {
-    return scopesInPrecedence(scope).flatMap((s) => [
-        ...listMemoryDocs(s),
-        ...listInstalledPlugins(s)
-            .filter((p) => p.enabled)
-            .flatMap((p) => listPluginMemoryDocs(p, s)),
+    return memorySourcesInPrecedence(scope).flatMap((source) => [
+        ...listMemoryDocsInDir(source.scope, source.memoryDir),
+        ...source.plugins.flatMap((p) => listPluginMemoryDocs(p, source.scope)),
     ]);
 }
 /** Direct full-path lookup of memory/<name>.md across scopes, precedence-first.
@@ -127,25 +148,22 @@ export function listAllMemoryDocs(scope) {
  *  resolves directly as the file path.) */
 function findMemoryMatches(name, scope) {
     const matches = [];
-    for (const s of scopesInPrecedence(scope)) {
-        // Native scope memory dir first (native-before-plugin precedence).
-        const dir = scopeMemoryDir(s);
+    const segments = name.split('/');
+    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 path = join(dir, ...name.split('/')) + '.md';
-            if (pathExists(path)) {
-                matches.push(loadMemoryDoc(name, s, path));
-                continue;
-            }
-            // Bundle marker is authoritative: a `<name>/SKILL.md` resolves the bare
-            // dir name to its bundle doc, and wins over INDEX.md if both exist.
-            const skillPath = join(dir, ...name.split('/'), 'SKILL.md');
-            if (pathExists(skillPath)) {
-                matches.push(loadMemoryDoc(name, s, skillPath));
+            const path = join(dir, ...segments) + '.md';
+            if (!isLegacySkillDoc && pathExists(path)) {
+                matches.push(loadMemoryDoc(name, source.scope, path));
                 continue;
             }
-            const indexPath = join(dir, ...name.split('/'), 'INDEX.md');
+            const indexPath = join(dir, ...segments, 'INDEX.md');
             if (pathExists(indexPath)) {
-                matches.push(loadMemoryDoc(name, s, indexPath));
+                matches.push(loadMemoryDoc(name, source.scope, indexPath));
                 continue;
             }
         }
@@ -157,14 +175,15 @@ function findMemoryMatches(name, scope) {
         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 listInstalledPlugins(s)) {
-            if (!p.enabled || p.name !== pluginName)
+        for (const p of source.plugins) {
+            if (p.name !== pluginName)
                 continue;
             const pdir = pluginMemoryDir(p);
             if (rest) {
-                const ppath = join(pdir, ...rest.split('/')) + '.md';
-                if (pathExists(ppath)) {
-                    matches.push(loadMemoryDoc(name, s, ppath));
+                const restSegments = rest.split('/');
+                const ppath = join(pdir, ...restSegments) + '.md';
+                if (restSegments.at(-1) !== 'SKILL' && pathExists(ppath)) {
+                    matches.push(loadMemoryDoc(name, source.scope, ppath));
                     break;
                 }
             }
@@ -173,7 +192,7 @@ function findMemoryMatches(name, scope) {
                 ? join(pdir, ...rest.split('/'), 'INDEX.md')
                 : join(pdir, 'INDEX.md');
             if (pathExists(pindex)) {
-                matches.push(loadMemoryDoc(name, s, pindex));
+                matches.push(loadMemoryDoc(name, source.scope, pindex));
                 break;
             }
         }
@@ -182,7 +201,7 @@ function findMemoryMatches(name, scope) {
 }
 /** 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. */
+ *  segment). Returns matches precedence-ordered. */
 function findMemoryByLeaf(leaf, scope) {
     if (leaf.includes('/'))
         return [];
@@ -202,7 +221,7 @@ function formatLeafAmbiguous(leaf, matches) {
 /**
  * Resolve a path-derived name to a single memory document.
  *
- * Accepted identifier forms (mirroring parseSkillQualifier, no plugins):
+ * 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

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

@@ -7,7 +7,7 @@
  *   - resolve                    (high-level composer)
  *   - ResolvedPersona            (return type of resolve)
  */
-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';
+export { loadPersona, loadPersonaSource, loadKernel, loadKernelSource, availableKinds, kindWhenToUse, subPersonasFor, loadLifecycleFragment, loadLifecycleFragmentSource, loadSpineFragment, loadSpineFragmentSource, loadRuntimeBase, loadRuntimeBaseSource, loadWaitingFragment, loadWaitingFragmentSource, loadScopedText, } from './loader.js';
+export type { LoadedPersona, LoadedPersonaSource, SubPersona } from './loader.js';
+export { resolve, resolveLayers, resolvePromptReview } from './resolve.js';
+export type { ResolvedPersona, PromptReviewData, PromptReviewConfig, PromptLayer, PromptSource } from './resolve.js';

package/dist/core/personas/index.js

@@ -7,5 +7,5 @@
  *   - resolve                    (high-level composer)
  *   - ResolvedPersona            (return type of resolve)
  */
-export { loadPersona, loadKernel, availableKinds, kindWhenToUse, subPersonasFor, loadLifecycleFragment, loadSpineFragment } from './loader.js';
-export { resolve } from './resolve.js';
+export { loadPersona, loadPersonaSource, loadKernel, loadKernelSource, availableKinds, kindWhenToUse, subPersonasFor, loadLifecycleFragment, loadLifecycleFragmentSource, loadSpineFragment, loadSpineFragmentSource, loadRuntimeBase, loadRuntimeBaseSource, loadWaitingFragment, loadWaitingFragmentSource, loadScopedText, } from './loader.js';
+export { resolve, resolveLayers, resolvePromptReview } from './resolve.js';

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

@@ -14,12 +14,36 @@
  * compiled build), resolved relative to this module — mirrors the pattern used
  * for STOPHOOK_PATH in spawn.ts.
  */
+import type { Scope } from '../../types.js';
+/**
+ * Find the first existing file across the scope roots.
+ * `relativePath` is relative to each root (e.g. 'general/PERSONA.md').
+ */
+export interface ResolvedPersonaSource {
+    path: string;
+    scope: Scope;
+}
+export declare function loadScopedText(relativePath: string): {
+    text: string;
+    sourcePath: string;
+    scope: Scope;
+} | null;
 export interface LoadedPersona {
     /** Raw, uncoerced frontmatter key/value record (null when no frontmatter). */
     frontmatter: Record<string, unknown> | null;
     /** Body text with any @include directives inlined. */
     body: string;
 }
+export interface LoadedPersonaSource extends LoadedPersona {
+    /** Raw body text before @include expansion. */
+    rawBody: string;
+    /** Absolute source path. */
+    sourcePath: string;
+    /** Scope the file was resolved from. */
+    scope: Scope;
+    /** Relative source path within the scope root, e.g. `personas/developer/PERSONA.md`. */
+    source: string;
+}
 /**
  * Load and parse a persona file for the given `kind` and `mode`.
  *
@@ -27,11 +51,18 @@ export interface LoadedPersona {
  * On success, `@include` directives in the body are resolved and inlined.
  */
 export declare function loadPersona(kind: string, mode: 'base' | 'orchestrator'): LoadedPersona | null;
+/** Load a persona file together with its provenance. */
+export declare function loadPersonaSource(kind: string, mode: 'base' | 'orchestrator'): LoadedPersonaSource | null;
 /**
  * Load the raw text of the orchestration kernel (no frontmatter, body only).
  * Returns an empty string if the kernel file cannot be found.
  */
 export declare function loadKernel(): string;
+export declare function loadKernelSource(): {
+    text: string;
+    sourcePath: string;
+    scope: Scope;
+} | null;
 /**
  * Load the base runtime prompt — the node operating protocol prepended to
  * EVERY persona (delegate/ask/promote). Returns '' if not found. The
@@ -39,6 +70,11 @@ export declare function loadKernel(): string;
  * live in their own fragments, loaded below.
  */
 export declare function loadRuntimeBase(): string;
+export declare function loadRuntimeBaseSource(): {
+    text: string;
+    sourcePath: string;
+    scope: Scope;
+} | null;
 /**
  * Load the waiting fragment — the cross-kind "waiting is a way to end a turn"
  * operating posture (arm a wake + go dormant instead of busy-looping or
@@ -46,6 +82,11 @@ export declare function loadRuntimeBase(): string;
  * the lifecycle fragment (resolve.ts). Returns '' if the fragment is missing.
  */
 export declare function loadWaitingFragment(): string;
+export declare function loadWaitingFragmentSource(): {
+    text: string;
+    sourcePath: string;
+    scope: Scope;
+} | null;
 /**
  * Load the lifecycle fragment — the "how you end" contract, keyed on the node's
  * lifecycle axis: `terminal` (drive to done + `push final`) or `resident`
@@ -54,6 +95,11 @@ export declare function loadWaitingFragment(): string;
  * Returns '' if the fragment file cannot be found.
  */
 export declare function loadLifecycleFragment(lifecycle: 'terminal' | 'resident'): string;
+export declare function loadLifecycleFragmentSource(lifecycle: 'terminal' | 'resident'): {
+    text: string;
+    sourcePath: string;
+    scope: Scope;
+} | null;
 /**
  * Load the spine fragment — the "who you report to" contract, keyed on whether
  * the node has a manager (anyone it reports up to). `has-manager` teaches the
@@ -62,6 +108,11 @@ export declare function loadLifecycleFragment(lifecycle: 'terminal' | 'resident'
  * Returns '' if the fragment file cannot be found.
  */
 export declare function loadSpineFragment(hasManager: boolean): string;
+export declare function loadSpineFragmentSource(hasManager: boolean): {
+    text: string;
+    sourcePath: string;
+    scope: Scope;
+} | null;
 /**
  * Enumerate the kinds with at least one persona file (PERSONA.md or
  * orchestrator.md) across all scope roots (project/user/builtin). Used to