@crouton-kit/crouter 0.3.31 → 0.3.33

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,11 +1,9 @@
 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`).
  */
@@ -29,7 +27,9 @@ 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. */
+ *  (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/. */
 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
@@ -44,7 +44,7 @@ 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

@@ -28,16 +28,14 @@ function loadMemoryDoc(name, scope, 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. */
+ *  (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/. */
 export function listMemoryDocs(scope) {
     const dir = scopeMemoryDir(scope);
     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 +47,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)
@@ -90,7 +81,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;
@@ -127,23 +118,18 @@ export function listAllMemoryDocs(scope) {
  *  resolves directly as the file path.) */
 function findMemoryMatches(name, scope) {
     const matches = [];
+    const segments = name.split('/');
+    const isLegacySkillDoc = segments.at(-1) === 'SKILL';
     for (const s of scopesInPrecedence(scope)) {
         // Native scope memory dir first (native-before-plugin precedence).
         const dir = scopeMemoryDir(s);
         if (dir) {
-            const path = join(dir, ...name.split('/')) + '.md';
-            if (pathExists(path)) {
+            const path = join(dir, ...segments) + '.md';
+            if (!isLegacySkillDoc && 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));
-                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));
                 continue;
@@ -162,8 +148,9 @@ function findMemoryMatches(name, scope) {
                 continue;
             const pdir = pluginMemoryDir(p);
             if (rest) {
-                const ppath = join(pdir, ...rest.split('/')) + '.md';
-                if (pathExists(ppath)) {
+                const restSegments = rest.split('/');
+                const ppath = join(pdir, ...restSegments) + '.md';
+                if (restSegments.at(-1) !== 'SKILL' && pathExists(ppath)) {
                     matches.push(loadMemoryDoc(name, s, ppath));
                     break;
                 }
@@ -182,7 +169,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 +189,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