@spexcode/spec-core 0.6.2 → 0.6.3

package/dist/specs.js

@@ -0,0 +1,489 @@
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { readFile, readdir } from 'node:fs/promises';
+import { join, relative, basename } from 'node:path';
+import { repoRoot, historyIndex, rowsFor, historyStats, pathsStats, driftIndex, driftFor, fileDiffAt, sourceIndexes, treeTextFiles, primeAncestorClosures, ancestorsOf, inAncestors } from './git.js';
+import { parseCodeEntry, parseRelation, relationClaimsPath } from './anchors.js';
+// a node is any directory under .spec holding a spec.md; its parent is the nearest ancestor that also holds one.
+const ROOT = repoRoot();
+const SPEC_DIR = join(ROOT, '.spec');
+// line-based frontmatter: scalars are `key: value`; an empty key followed by `- item` lines is a list (e.g. `code:`).
+export function parseFrontmatter(src) {
+    const fm = {};
+    let body = src;
+    const m = src.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+    if (m) {
+        let key = null;
+        for (const line of m[1].split('\n')) {
+            const item = line.match(/^\s*-\s+(.*)$/);
+            if (item && key) {
+                if (!Array.isArray(fm[key]))
+                    fm[key] = fm[key] ? [fm[key]] : [];
+                fm[key].push(item[1].trim());
+                continue;
+            }
+            const i = line.indexOf(':');
+            if (i > 0) {
+                key = line.slice(0, i).trim();
+                fm[key] = line.slice(i + 1).trim();
+            }
+        }
+        body = m[2];
+    }
+    return { fm, body };
+}
+const str = (v, d = '') => (Array.isArray(v) ? v.join(', ') : v ?? d);
+const list = (v) => (Array.isArray(v) ? v : v ? [v] : []);
+const PART_ALIASES = {
+    'raw source': 'rawSource',
+    'expanded spec': 'expandedSpec',
+};
+function parseParts(body) {
+    const acc = { rawSource: [], expandedSpec: [] };
+    let cur = null;
+    let inFence = false;
+    let any = false;
+    for (const line of body.split('\n')) {
+        const fence = /^\s*```/.test(line);
+        if (!inFence && !fence) {
+            const h2 = line.match(/^##\s+(.+?)\s*$/); // exactly two hashes — `###` won't match
+            if (h2) {
+                const key = PART_ALIASES[h2[1].trim().toLowerCase()];
+                if (key) {
+                    cur = key;
+                    any = true;
+                    continue;
+                }
+                // an unrecognized `## …` heading is just content of the current part — fall through.
+            }
+        }
+        if (fence)
+            inFence = !inFence;
+        if (cur === 'rawSource')
+            acc.rawSource.push(line);
+        else if (cur === 'expandedSpec')
+            acc.expandedSpec.push(line);
+    }
+    if (!any)
+        return null;
+    const t = (a) => a.join('\n').trim();
+    return { rawSource: t(acc.rawSource), expandedSpec: t(acc.expandedSpec) };
+}
+export function deriveStatus(d) {
+    if (d.fmStatus === 'pending' && !d.hasCode && d.drift === 0)
+        return 'pending';
+    if (d.hasOverlay)
+        return 'active';
+    if (d.drift > 0)
+        return 'drift';
+    if (d.version > 0)
+        return 'merged';
+    const fb = d.fmStatus;
+    if (fb === 'active' || fb === 'merged' || fb === 'drift')
+        return fb;
+    return 'pending';
+}
+function walk(dir, parent, acc) {
+    let myId = parent;
+    if (existsSync(join(dir, 'spec.md'))) {
+        myId = basename(dir);
+        const relPath = relative(ROOT, join(dir, 'spec.md'));
+        const { fm, body } = parseFrontmatter(readFileSync(join(dir, 'spec.md'), 'utf8'));
+        acc.push({ id: myId, parent, relPath, fm, body });
+    }
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+        if (e.isDirectory())
+            walk(join(dir, e.name), myId, acc);
+    }
+}
+// the id MINT ([[id-url-safe]]): key each node — given its path segments under .spec — to its leaf dir
+// name, or on a leaf collision the shortest globally-unique trailing path-suffix. A node id is a URL-safe
+// single token — never a '/'-joined path, which would break every `:id` route and fetch that treats an id
+// as one path segment. So the disambiguation separator is '_': like '/' it never occurs inside a dir
+// basename (so the join stays unambiguous), but unlike '/' it is a URL/wikilink/DOM-safe unreserved char,
+// so a collision-qualified id (e.g. `.plugins_<id>`) stays a single token everywhere it is resolved.
+// Exported as the ONE mint every id producer shares: spec-eval mints its node ids through this same
+// function over this same universe (every spec node), so a colliding leaf carries one canonical id
+// system-wide instead of a second, diverging bare-leaf scheme.
+export function mintIds(segs) {
+    // NFC pins one canonical byte form for a non-ASCII dir name (macOS hands out NFD basenames), so a typed
+    // `[[中文节点]]` (NFC, what an IME emits) string-matches the minted id on every platform.
+    const suffix = (s, k) => s.slice(s.length - k).join('_').normalize('NFC');
+    return segs.map((s, i) => {
+        let k = 1;
+        while (k < s.length && segs.some((o, j) => j !== i && o.length >= k && suffix(o, k) === suffix(s, k)))
+            k++;
+        return suffix(s, k);
+    });
+}
+// re-key each node via the mint (overrides walk's placeholder basename id/parent); the second loop
+// recomputes parent by path-ancestry.
+function reId(acc) {
+    const segs = acc.map((r) => r.relPath.split(/[/\\]/).slice(1, -1)); // path under .spec, minus 'spec.md'
+    const ids = mintIds(segs);
+    for (let i = 0; i < acc.length; i++)
+        acc[i].id = ids[i];
+    for (let i = 0; i < acc.length; i++) {
+        let best = -1;
+        for (let j = 0; j < acc.length; j++) {
+            const o = segs[j], s = segs[i];
+            if (j !== i && o.length < s.length && o.every((seg, x) => seg === s[x]) && (best < 0 || o.length > segs[best].length))
+                best = j;
+        }
+        acc[i].parent = best >= 0 ? acc[best].id : null;
+    }
+}
+function raws() {
+    const acc = [];
+    if (existsSync(SPEC_DIR))
+        walk(SPEC_DIR, null, acc);
+    reId(acc);
+    return acc;
+}
+// async twin of walk/raws for the HOT board build ([[graph-cache]]): reading each spec.md through
+// fs/promises YIELDS the event loop between files, so a build never stalls a `/health` liveness probe the
+// way the sync walk (one ~450ms uninterrupted stretch) did. Same output as raws() — identical push order
+// (pre-order DFS, dir before children) and the same reId — so every caller reads the same nodes; only
+// loadSpecs (already async, on the hot path) uses it, the light one-shot callers keep the sync raws().
+async function walkAsync(dir, parent, acc, root) {
+    let myId = parent;
+    if (existsSync(join(dir, 'spec.md'))) {
+        myId = basename(dir);
+        const relPath = relative(root, join(dir, 'spec.md'));
+        const { fm, body } = parseFrontmatter(await readFile(join(dir, 'spec.md'), 'utf8'));
+        acc.push({ id: myId, parent, relPath, fm, body });
+    }
+    for (const e of await readdir(dir, { withFileTypes: true })) {
+        if (e.isDirectory())
+            await walkAsync(join(dir, e.name), myId, acc, root);
+    }
+}
+async function rawsAsync(root, tip = 'HEAD', snapshot) {
+    if (snapshot || tip !== 'HEAD') {
+        const acc = [];
+        const files = snapshot?.files ?? treeTextFiles(root, tip, '.spec');
+        for (const [relPath, source] of [...files].sort(([a], [b]) => a.localeCompare(b))) {
+            if (!relPath.endsWith('/spec.md'))
+                continue;
+            const segs = relPath.split('/');
+            const { fm, body } = parseFrontmatter(source);
+            acc.push({ id: segs[segs.length - 2], parent: null, relPath, fm, body });
+        }
+        reId(acc);
+        return acc;
+    }
+    const acc = [];
+    const specDir = join(root, '.spec');
+    if (existsSync(specDir))
+        await walkAsync(specDir, null, acc, root);
+    reId(acc);
+    return acc;
+}
+// the claim rule shared by both relations (exact path, dir-prefix, or *-glob). See [[governed-related]].
+function claimMatcher(file) {
+    const rel = file.startsWith('/') ? relative(ROOT, file) : file;
+    return (claim) => relationClaimsPath(claim, rel);
+}
+// spec node(s) that GOVERN a file (frontmatter `code:` — source of truth, drives drift + eval freshness); reads only
+// frontmatter (cheap, no git) so a per-edit hook can call it. `scoped` = every claiming entry carries a
+// `#selector` — such a governor still displays, but does not count toward the owners bound ([[code-anchor]]).
+export function specOwners(file) {
+    const claims = claimMatcher(file);
+    return raws().flatMap((r) => {
+        const entries = list(r.fm.code).map(parseCodeEntry).filter((e) => claims(e.path));
+        return entries.length ? [{ id: r.id, desc: str(r.fm.desc), scoped: entries.every((e) => e.anchor !== null) }] : [];
+    });
+}
+// spec node(s) that REFERENCE a file (frontmatter `related:` — carries coverage, never drift, never eval freshness):
+// [[governed-related]]'s other half, same claim rule, same cheap frontmatter-only read.
+export function specRelated(file) {
+    const claims = claimMatcher(file);
+    return raws().filter((r) => list(r.fm.related).some((e) => claims(parseCodeEntry(e).path))).map((r) => ({ id: r.id, desc: str(r.fm.desc) }));
+}
+// memo fileDiffAt by (version sha + spec.md path) — a commit's patch is immutable. Keyed by path too: one
+// commit can patch several nodes' spec.md. `{hash:'',patch:''}` for an unversioned node (no git call).
+const diffCache = new Map();
+async function latestDiff(relPath, hash) {
+    if (!hash)
+        return { hash: '', patch: '' };
+    const key = `${hash}\0${relPath}`;
+    const hit = diffCache.get(key);
+    if (hit)
+        return hit;
+    const val = { hash, patch: await fileDiffAt(ROOT, relPath, hash) };
+    diffCache.set(key, val);
+    return val;
+}
+export function loadSpecsLite() {
+    return raws().map((r) => ({
+        id: r.id,
+        title: str(r.fm.title, r.id),
+        path: r.relPath,
+        desc: str(r.fm.desc),
+        body: r.body.trim(),
+    }));
+}
+// one node's body + parsed parts, filesystem-only (no git). The board omits both to stay lean
+// ([[graph-lean]]); the detail view fetches them here when a node opens. null when the id isn't a node.
+export function specContent(id) {
+    const r = raws().find((x) => x.id === id);
+    return r ? { body: r.body.trim(), parts: parseParts(r.body) } : null;
+}
+export async function loadSpecs(root = ROOT, options = {}) {
+    // The default pair shares one immutable-event snapshot; explicit sides let callers skip or supply either
+    // projection. Every node below is then a pure in-memory lookup.
+    const tip = options.tip ?? 'HEAD';
+    if (options.snapshot && options.snapshot.tip !== tip) {
+        throw new Error(`loadSpecs snapshot tip '${options.snapshot.tip}' does not match requested tip '${tip}'`);
+    }
+    const indexes = options.history === undefined && options.drift === undefined
+        ? sourceIndexes(root, tip)
+        : Promise.all([
+            options.history === null ? Promise.resolve(null) : options.history ?? historyIndex(root, tip),
+            options.drift === null ? Promise.resolve(null) : options.drift ?? driftIndex(root, tip),
+        ]);
+    const [[idx, didx], allRaws] = await Promise.all([indexes, rawsAsync(root, tip, options.snapshot)]);
+    const prepared = allRaws.map((r) => ({
+        r,
+        h: idx ? rowsFor(idx, r.relPath) : [],
+        codeRel: parseRelation(list(r.fm.code), 'code'),
+        relatedRel: parseRelation(list(r.fm.related), 'related'),
+    }));
+    if (didx) {
+        const queries = [];
+        for (const { r, h, codeRel, relatedRel } of prepared) {
+            if (!h[0]?.hash || (!codeRel.entries.length && !relatedRel.entries.some((entry) => !entry.selectors.length)))
+                continue;
+            queries.push({ hash: h[0].hash, node: r.id });
+        }
+        primeAncestorClosures(didx, queries.map(({ hash }) => hash));
+        // Only an ack named for this node and outside its version's ancestry becomes a cover. Discover that
+        // exact roster from the now-primed bases instead of retaining closures for older, non-covering acks.
+        const covers = [];
+        for (const [hash, nodes] of didx.acks)
+            if (queries.some(({ hash: baseHash, node }) => {
+                const base = ancestorsOf(didx, baseHash);
+                return !!base && nodes.has(node) && !inAncestors(didx, base, hash);
+            }))
+                covers.push(hash);
+        primeAncestorClosures(didx, covers);
+    }
+    const loaded = [];
+    for (const { r, h, codeRel, relatedRel } of prepared) {
+        // session = the Session: trailer of the node's latest version; frontmatter `session:` is the fallback.
+        const fmSession = str(r.fm.session);
+        const session = h[0]?.session || (fmSession && fmSession !== 'null' ? fmSession : null);
+        // a code:/related: row may pin symbols (`path#fn` — [[code-anchor]]): parseRelation groups each
+        // relation per BASE path, so `code`/`related` carry the distinct PATHS (what every path consumer —
+        // drift, claims, eval attribution — expects, file-level as before), the scoped entries (path +
+        // selectors) ride separately for lint's anchor engine, and structural problems (duplicates,
+        // bare/scoped mixing, glob selectors, the code cap) surface as lint integrity errors.
+        const codeEntries = codeRel.entries;
+        const code = codeEntries.map((e) => e.path);
+        const codeScoped = codeEntries.filter((e) => e.selectors.length > 0);
+        const relatedEntries = relatedRel.entries;
+        const related = relatedEntries.map((e) => e.path);
+        const relatedScoped = relatedEntries.filter((e) => e.selectors.length > 0);
+        const relationProblems = [...codeRel.problems, ...relatedRel.problems];
+        const S = h[0]?.hash || '';
+        const driftFiles = [];
+        for (const f of code) {
+            const d = didx ? { file: f, behind: driftFor(didx, S, f, r.id) } : { file: f, behind: 0 };
+            if (d.behind > 0)
+                driftFiles.push(d);
+        }
+        const drift = driftFiles.reduce((a, d) => a + d.behind, 0);
+        // related drift is the SOFT tier ([[governed-related]]): same ancestry basis, but it stays OUT of
+        // `drift` — it never feeds status, the commit gate, or eval freshness. It surfaces only as a lint warn nudge.
+        // A SCOPED related entry is excluded here: its file-level movement is silent by design — only a
+        // selector HIT warns, and that verdict needs the anchor engine, so lint derives it, not the loader.
+        const relatedDriftFiles = [];
+        for (const e of relatedEntries) {
+            if (e.selectors.length)
+                continue;
+            const d = didx ? { file: e.path, behind: driftFor(didx, S, e.path, r.id) } : { file: e.path, behind: 0 };
+            if (d.behind > 0)
+                relatedDriftFiles.push(d);
+        }
+        const fmStatus = str(r.fm.status, '') || null;
+        loaded.push({
+            id: r.id,
+            parent: r.parent,
+            path: r.relPath,
+            title: str(r.fm.title, r.id),
+            status: deriveStatus({ version: h.length, drift, hasCode: code.length > 0, fmStatus: fmStatus ?? undefined }),
+            fmStatus,
+            session,
+            hue: Number(str(r.fm.hue, '210')),
+            desc: str(r.fm.desc),
+            code,
+            codeEntries,
+            codeScoped,
+            related,
+            relatedEntries,
+            relatedScoped,
+            relationProblems,
+            version: h.length,
+            reason: h[0]?.reason || '',
+            // ISO date of the node's latest version commit (h is newest-first), or null if unversioned.
+            lastEdited: h[0]?.date || null,
+            drift,
+            driftFiles,
+            relatedDriftFiles,
+            // the latest version's spec.md patch is NOT precomputed here (it cost 2 git show forks per node on
+            // cold load); the history tab fetches it lazily via specDiffAt. See [[work-pane]].
+            body: r.body.trim(),
+            parts: parseParts(r.body),
+        });
+    }
+    return loaded;
+}
+// per-node version timeline; each row sums the node's spec.md stat (rename-followed, read on demand) and its
+// governed-code stat (pathsStats) — separate because spec.md needs rename-following a plain `git log -- path` can't do.
+export async function specHistory(id) {
+    const node = raws().find((r) => r.id === id);
+    if (!node)
+        return [];
+    const codePaths = [...new Set(list(node.fm.code).map((e) => parseCodeEntry(e).path))];
+    // index (cached) and the code-path walk are independent — run them in parallel, both async git.
+    const [idx, cStats] = await Promise.all([historyIndex(ROOT), pathsStats(ROOT, codePaths)]);
+    const sStats = await historyStats(ROOT, idx, node.relPath);
+    return rowsFor(idx, node.relPath).map((v) => {
+        const s = sStats.get(v.hash) ?? { additions: 0, deletions: 0, files: 0 };
+        const c = cStats.get(v.hash) ?? { additions: 0, deletions: 0, files: 0 };
+        return { ...v, additions: s.additions + c.additions, deletions: s.deletions + c.deletions, files: s.files + c.files };
+    });
+}
+// the line-diff a specific version introduced to a node's spec.md, by hash; fetched lazily when a history
+// item expands. fileDiffAt resolves the spec.md path AT that commit (reparents). `{hash:'',patch:''}` for
+// an empty hash, null for an unknown id.
+export async function specDiffAt(id, hash) {
+    const node = raws().find((r) => r.id === id);
+    if (!node)
+        return null;
+    if (!hash)
+        return { hash: '', patch: '' };
+    return latestDiff(node.relPath, hash);
+}
+// @@@ public instance root - cross-repository consumers import this identity instead of matching a folder
+// literal. `plugin-system` remains the separate root for this project's system spec.
+export const PLUGIN_INSTANCE_ROOT = '.plugins';
+// field-driven surface - a plugin is a spec node at ANY depth under a plugin root that carries a
+// `surface: system|command|hook|skill|agent|review` frontmatter field naming where it plugs in. There are no
+// `command/`/`system/`/`hook/`/`skill/`/`agent/` bucket dirs (those were graph-invisible grouping dirs with no spec.md, so
+// the spec graph skipped them — path != graph); the surface is a FIELD on the node, so the plugin is a real
+// graph child (a grouping parent like `.plugins/prompts` is itself a spec node, never a bare dir). BOTH plugin roots participate: `.plugins` (the instance — DIY dev-flow plugins) and
+// `plugin-system` (the project system spec). loadConfig gathers the `command` surface, loadSystemConfig the `system`
+// surface, loadHookConfig the `hook` surface, loadSkillConfig the `skill` surface, loadAgentConfig the `agent`
+// surface (sub-agent definitions); each scans the children under every root and filters by the field. The plugins also show on the board as ordinary spec nodes (via loadSpecs).
+// root node - the spec tree's single top-level node: the one directory directly under .spec/ that
+// holds a spec.md. The dogfood repo names it 'spexcode'; a repo scaffolded by `spex init` names it
+// 'project' (or whatever the adopter renames it to). Detected DYNAMICALLY so the config loaders resolve
+// the ACTUAL root's config dirs — never a hardcoded 'spexcode', which silently returned [] in an adopter
+// repo, so their .plugins/core contract never loaded and their launched agents got no system prompt.
+// Returns null when .spec holds no such directory. (resolveLayout's `main` is a checkout PATH, not the
+// root node NAME, so it can't serve this — a tiny filesystem probe is the right seam.)
+function rootNode() {
+    if (!existsSync(SPEC_DIR))
+        return null;
+    for (const e of readdirSync(SPEC_DIR, { withFileTypes: true })) {
+        if (e.isDirectory() && existsSync(join(SPEC_DIR, e.name, 'spec.md')))
+            return e.name;
+    }
+    return null;
+}
+// resolved at call time (not module-eval) so it tracks the live tree.
+// @@@ legacy-tree refusal - v0.3.0 renamed the plugin instance root `.config` → `.plugins`. A pre-0.3.0
+// tree would otherwise load an EMPTY plugin surface — no contract block, no hooks, no commands — and the
+// launched agents would silently run ungoverned. So refuse loudly: existence-only probe (never a dual
+// read of legacy content), pointing at the one-shot migrator. Delete this check in 0.4.0.
+function configRoots() {
+    const root = rootNode();
+    if (!root)
+        return [];
+    if (existsSync(join(SPEC_DIR, root, '.config')) && !existsSync(join(SPEC_DIR, root, PLUGIN_INSTANCE_ROOT))) {
+        throw new Error(`.spec/${root}/.config exists but .spec/${root}/${PLUGIN_INSTANCE_ROOT} does not — this spec tree predates the v0.3.0 ` +
+            `plugin rename (.config → ${PLUGIN_INSTANCE_ROOT}). Refusing to load an empty plugin surface (agents would launch ` +
+            `ungoverned). Run \`spex doctor --migrate\` to migrate the tree.`);
+    }
+    return [PLUGIN_INSTANCE_ROOT, 'plugin-system'].map((r) => join(SPEC_DIR, root, r));
+}
+// co-located bundle files = everything under the node folder except its spec.md, repo-relative, recursive.
+function bundleFiles(dir) {
+    const out = [];
+    const walk = (d) => {
+        for (const e of readdirSync(d, { withFileTypes: true })) {
+            const p = join(d, e.name);
+            if (e.isDirectory())
+                walk(p);
+            else if (e.name !== 'spec.md')
+                out.push(relative(ROOT, p));
+        }
+    };
+    walk(dir);
+    return out.sort();
+}
+// gather the preset nodes under a plugin root that declare `surface: <surface>`. The scan is RECURSIVE —
+// `surface` is a FIELD, not a path (the design's core tenet), so a plugin may live at ANY depth: under a
+// surface-less grouping shelf (the auxiliary `surface: system` contracts live under `.plugins/prompts/`),
+// or under a plugin that is itself a grouping parent (`.plugins/core` is a `surface: system` contract whose
+// CHILDREN are `surface: hook` nodes). The field filter keeps it safe: a node only gathers if it declares THIS
+// surface, so descending past a matched node never double-counts (children carry a different surface),
+// and the gather set is path-independent — regrouping a plugin never changes what materializes.
+function loadSurface(surface) {
+    const out = [];
+    const visit = (nodeDir, name) => {
+        if (existsSync(join(nodeDir, 'spec.md'))) {
+            const { fm, body } = parseFrontmatter(readFileSync(join(nodeDir, 'spec.md'), 'utf8'));
+            // @@@ skip pending - a `status: pending` plugin is DECLARED INTENT, not yet active. It renders on the
+            // board (via loadSpecs) but must NOT gather: neither a command preset, nor folded into a system prompt,
+            // nor a live hook. Only built/active plugins surface here, so pending stubs stay inert.
+            // the surface field may name SEVERAL surfaces (comma-separated or a YAML list) — the node plugs
+            // into every one it lists, so the match is membership, not equality.
+            const surfaces = list(fm.surface).flatMap((v) => String(v).split(',')).map((v) => v.trim()).filter(Boolean);
+            if (surfaces.includes(surface) && str(fm.status) !== 'pending') {
+                out.push({
+                    name,
+                    title: str(fm.title, name),
+                    desc: str(fm.desc),
+                    kind: str(fm.kind, 'mutating'),
+                    dir: relative(ROOT, nodeDir),
+                    files: bundleFiles(nodeDir),
+                    body: body.trim(),
+                    events: list(fm.events),
+                    order: Number(str(fm.order, '0')) || 0,
+                    block: str(fm.block) === 'true',
+                    tools: list(fm.tools),
+                });
+            }
+        }
+        for (const e of readdirSync(nodeDir, { withFileTypes: true })) {
+            if (e.isDirectory())
+                visit(join(nodeDir, e.name), e.name);
+        }
+    };
+    for (const root of configRoots()) {
+        if (!existsSync(root))
+            continue;
+        for (const e of readdirSync(root, { withFileTypes: true })) {
+            if (e.isDirectory())
+                visit(join(root, e.name), e.name);
+        }
+    }
+    return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+export function loadConfig() { return loadSurface('command'); }
+export function loadSystemConfig() { return loadSurface('system'); }
+// the hook handlers (compiled into the per-session hook manifest the dispatcher reads). Each carries its
+// `events`/`order`/`block` binding + co-located script `files`.
+export function loadHookConfig() { return loadSurface('hook'); }
+// the skill bundles (materialized into each harness's auto-discovered SKILL.md dir). Each node's `desc` is the
+// load-trigger and its `body` is the on-demand instructions; loadSurface passes the folder basename as `name`.
+export function loadSkillConfig() { return loadSurface('skill'); }
+// the sub-agent definitions (materialized into each harness's auto-discovered agent dir, e.g. claude's
+// .claude/agents/<name>.md). Like a skill, the node's `desc` is the on-demand load-trigger and its `body` is the
+// agent's system prompt; additionally its `tools` field is the harness tool allowlist for the spawned agent.
+export function loadAgentConfig() { return loadSurface('agent'); }
+// the review-track prose presets ([[review-commands]]): offered in the eval detail's remark-composer `/`
+// dropdown; picking one PREFILLS the composer with the node's `body` ({node}/{scenario}/{expected}
+// placeholders filled at insert time). Display+prefill only — the send stays the ordinary remark write.
+export function loadReviewConfig() { return loadSurface('review'); }

package/package.json

@@ -1,18 +1,29 @@
 {
   "name": "@spexcode/spec-core",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "type": "module",
   "description": "SpexCode's dependency-minimal spec graph core.",
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {},
   "files": [
-    "src",
+    "dist",
     "templates"
   ],
+  "types": "./dist/index.d.ts",
   "exports": {
-    ".": "./src/index.ts",
-    "./review": "./src/review/index.js",
-    "./identity": "./src/identity-presets.js"
-  },
-  "engines": {
-    "node": ">=22"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./review": {
+      "types": "./dist/review/index.d.ts",
+      "default": "./dist/review/index.js"
+    },
+    "./identity": {
+      "types": "./dist/identity-presets.d.ts",
+      "default": "./dist/identity-presets.js"
+    }
   }
 }