futura-scion 0.2.6 → 0.2.8

package/README.md

@@ -592,6 +592,40 @@ with the violation evidence attached — the human chooses refactor, move,
 or amend the declaration, via the same `scion review` loop as every other
 escalation.
 
+#### Hub rules — shape, not just edges (`architecture.hubs`)
+
+Edges police direction; HUBS police concentration, checked against the
+schematic's measured fan-in/fan-out (`scion map` design data — curator
+models derive the same numbers from edges, so no map build is required):
+
+```yaml
+architecture:
+  hubs:
+    max_fan_in: 100        # no file imported by more than N (change magnets)
+    max_fan_out: 20        # no file importing more than N (God modules)
+    max_layer_fan_in: 300  # no layer funneling more inbound edges than N
+    ignore: [vendor, gen]  # path prefixes exempt from hub accounting
+```
+
+Hub violations are analyzer-shaped **warnings** (`arch-hub-fan-in`,
+`arch-hub-fan-out`, `arch-hub-layer-fan-in`) carrying the measured number,
+the declared ceiling, and the file — a design smell escalates to the human
+arch lane, never machine-patched. All thresholds are opt-in (empty = not
+checked); malformed or typo'd keys fail loud. Live on FS's own source at
+diagnostic thresholds: `kernel/trail.js` flagged at 173 inbound edges
+(change magnet), `daemon.js` at 22 imports (God module).
+
+#### Map-first THINK (`schematic.enabled`)
+
+Every ladder decision attaches the schematic digest — layers, entries,
+hubs, exported surface — as context for all downstream rungs (generator
+prompts, analyzer reasoning, research queries). Served from a warm cache
+(`schematic.digest_ttl_ms`, default 30000) so latency-bounded scans are
+never starved: one refresh per TTL window, amortized across every worker
+and daemon scan. `taskId` and `mapContext` are ambient keys — stripped
+before signature hashing, so identical problems replay identically across
+task ids and map refreshes.
+
 ### Command over tools — the research rung (`scion tools`)
 
 FS's rungs answer from what it knows. The RESEARCH rung gives it hands:
@@ -824,6 +858,51 @@ the current task needs, retain only what compounds.
   rung's action threshold — so only REPETITION makes them actionable.
   One occurrence is an observation; repetition is knowledge.
 
+### FS as the learner of its own harness — Codebuff adoption organs (v0.2.8)
+
+From studying the open-source Codebuff/Freebuff harnesses, six patterns were
+adopted — each rebuilt to fit the zero-LLM doctrine, none copied as LLM
+machinery:
+
+- **Agent templates as data** (`agent-templates/`, `scion templates`): an
+  agent is a YAML contract — `spawner_prompt` (how a parent chooses it),
+  `input_schema`/`output_schema` (validated at the spawn boundary),
+  `tool_allowlist` (least privilege), `capabilities` (routed into the
+  kernel's role registry), `bounds`, and `spawnable_agents` — a spawn graph
+  that is cycle-checked at load and depth-bounded at spawn. Six templates
+  ship (fixer, researcher, mapper, librarian, constructor→verifier,
+  verifier). Routing is scored keyword matching, deterministic and journaled:
+
+  ```bash
+  scion templates load|list|route "fix the bug"|spawn <id>
+  ```
+
+- **Skills — procedural knowledge packs** (`skills/`, `scion skills`):
+  `SKILL.md` files with a small frontmatter block (name, description,
+  triggers). Parsed loud, name/filename discipline enforced, trigger match
+  exact. Wired into ladder THINK: a task mentioning "ship a release"
+  absorbs the release-checklist skill into its ephemeral working set
+  automatically; swept at task end. New procedures = drop a file in
+  `skills/`, zero code.
+
+- **The trust gate** (`scion trust`): content-addressed trust for every
+  loaded pack. `unseen` → observed; `pin` → checksum-pinned; a PINNED pack
+  that changes refuses loudly (with both hashes) until explicitly re-pinned.
+
+- **The repo librarian** (`scion librarian <owner/repo> "<question>"`):
+  shallow-clone an external repo, run the codebase schematics over it, and
+  answer from the map with ranked relevant files — one deterministic pass
+  over a foreign codebase (Codebuff's librarian, no LLM).
+
+- **Commit-reconstruction benchmark** (`src/mind/commitbench.js`): BuffBench's
+  honest methodology with the judge replaced by arithmetic — reconstruct
+  real commits against ground-truth diffs, scored on file recall/precision
+  + token-level F1, hard subset reported. Oracle = 1.0, empty = 0, proven.
+
+- **Declared brief budgets** (`config.brief`): the task working-set's
+  TTL/budget/read-limit are config policy (Codebuff CompactionPolicy
+  lineage), not module constants.
+
 ### FS Desktop — the standalone UI (chat / agent / plan / architect)
 
 FS ships a real UI in two forms, both zero-build:

package/bin/scion.js

@@ -678,6 +678,113 @@ switch (cmd || '') {
     }
     break;
   }
+  case 'templates': {
+    // Declarative agent templates (Codebuff agents-as-data lineage):
+    //   scion templates load [dir]    load every template yaml (default: agent-templates/)
+    //   scion templates list          the registry, with capabilities + spawn graph
+    //   scion templates route <text>  deterministic routing: which template for this problem
+    //   scion templates spawn <id>    bind the template's role (printed, not bound to a live worker)
+    const at = await import('../src/mind/agent-templates.js');
+    const sub = arg || 'list';
+    if (sub === 'load') {
+      const dir = restArgs[0] || 'agent-templates';
+      const loaded = at.loadTemplates(dir);
+      at.checkSpawnGraph();
+      console.log(JSON.stringify({ ok: true, dir, loaded }, null, 2));
+      break;
+    }
+    if (sub === 'list') {
+      for (const t of at.listTemplates()) {
+        console.log(`${t.id.padEnd(14)} ${t.display_name.padEnd(14)} caps: ${t.capabilities.join(',')}${t.spawnable_agents?.length ? `  spawns: ${t.spawnable_agents.join(',')}` : ''}`);
+      }
+      break;
+    }
+    if (sub === 'route') {
+      const text = restArgs.join(' ');
+      if (!text) { console.error('usage: scion templates route <problem text>'); process.exitCode = 2; break; }
+      const ranked = at.routeToTemplate(text);
+      for (const r of ranked) console.log(`${r.score}  ${r.id.padEnd(14)} hits: ${r.hits.join(',') || '(capabilities)'}`);
+      if (ranked.length === 0) console.log('(no template matches — the ladder routes to the generalist)');
+      break;
+    }
+    if (sub === 'spawn') {
+      if (!restArgs[0]) { console.error('usage: scion templates spawn <id>'); process.exitCode = 2; break; }
+      const r = at.spawnTemplate(restArgs[0]);
+      console.log(JSON.stringify({ ok: true, template: r.template.id, role: r.role.id, capabilities: r.role.capabilities }, null, 2));
+      break;
+    }
+    console.error('usage: scion templates [load|list|route|spawn]');
+    process.exitCode = 2;
+    break;
+  }
+  case 'skills': {
+    // Procedural knowledge packs (Codebuff SKILL.md lineage):
+    //   scion skills load [dir...]    load every SKILL.md / *.skill.md under the dirs
+    //   scion skills list             name + description of every loaded skill
+    //   scion skills match <text>     deterministic trigger match, scored
+    //   scion skills show <name>      the full body
+    const sk = await import('../src/mind/skills.js');
+    const sub = arg || 'list';
+    if (sub === 'load') {
+      const dirs = restArgs.length ? restArgs : ['skills'];
+      const loaded = sk.loadSkills(dirs);
+      console.log(JSON.stringify({ ok: true, loaded }, null, 2));
+      break;
+    }
+    if (sub === 'match') {
+      const text = restArgs.join(' ');
+      if (!text) { console.error('usage: scion skills match <task text>'); process.exitCode = 2; break; }
+      for (const m of sk.matchSkills(text)) console.log(`${m.score}  ${m.name.padEnd(24)} ${m.description}`);
+      if (sk.matchSkills(text).length === 0) console.log('(no skill matches)');
+      break;
+    }
+    if (sub === 'show') {
+      const s = sk.getSkill(restArgs[0]);
+      if (!s) { console.error(`skills: unknown skill ${JSON.stringify(restArgs[0])} — known: ${sk.listSkills().map(x => x.name).join(', ') || '(none loaded)'}`); process.exitCode = 1; break; }
+      console.log(`# ${s.name} — ${s.description}\n(source: ${s.source})\n\n${s.body}`);
+      break;
+    }
+    for (const s of sk.listSkills()) console.log(`${s.name.padEnd(24)} ${s.description}`);
+    break;
+  }
+  case 'trust': {
+    // The trust gate for loaded packs (checksum pins, loud refusals):
+    //   scion trust status <file>    state: unseen | quarantine | pinned | changed
+    //   scion trust pin <file>       pin current content (operator action)
+    //   scion trust unpin <file>     remove the pin
+    //   scion trust list             every pin
+    const tr = await import('../src/mind/trust.js');
+    const sub = arg || 'list';
+    if (sub === 'pin') {
+      if (!restArgs[0]) { console.error('usage: scion trust pin <file>'); process.exitCode = 2; break; }
+      console.log(JSON.stringify(tr.pin(restArgs[0]), null, 2));
+      break;
+    }
+    if (sub === 'unpin') {
+      if (!restArgs[0]) { console.error('usage: scion trust unpin <file>'); process.exitCode = 2; break; }
+      console.log(JSON.stringify(tr.unpin(restArgs[0]), null, 2));
+      break;
+    }
+    if (sub === 'status') {
+      if (!restArgs[0]) { console.error('usage: scion trust status <file>'); process.exitCode = 2; break; }
+      console.log(JSON.stringify(tr.trustStatus(restArgs[0]), null, 2));
+      break;
+    }
+    for (const p of tr.listTrusted()) console.log(`${p.sha256.slice(0, 12)}  ${p.path}  pinned ${p.pinned_at}`);
+    break;
+  }
+  case 'librarian': {
+    // External repo comprehension: clone → schematic → structured answer.
+    //   scion librarian <owner/repo|url> "<question>"
+    const lib = await import('../src/mind/librarian.js');
+    if (!arg || restArgs.length === 0) { console.error('usage: scion librarian <owner/repo> "<question>"'); process.exitCode = 2; break; }
+    const r = lib.askRepo(arg, restArgs.join(' '));
+    console.log(r.digest);
+    console.log(`\nrelevant files:`);
+    for (const f of r.relevant_files) console.log(`  ${f}`);
+    console.log(`\nclone (kept for inspection): ${r.clone_dir}   [files=${r.stats.files} symbols=${r.stats.symbols} ${r.stats.ms}ms]`);
+    break;
+  }
   case 'evolve': {
     // The nightly harness-evolution pass (A4): mine weaknesses → propose
     // harness edits → gate them (SICA utility) → apply the accepted. Bounded

package/config/scion.config.yaml

@@ -11,8 +11,12 @@ ladder:
   min_insight_confidence: 0.55  # reasoner rung admission floor
 
 llm:
-  daily_tokens: 0               # 0 = LLM rung off (zero-LLM doctrine)
+  daily_tokens: 500
 
+  apiKey: null
+  model: "qwen2.5-coder:7b"
+  baseUrl: "http://localhost:11434/v1"
+  provider: "ollama"
 bounds:
   max_turns: 25
   timeout_ms: 300000

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "futura-scion",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "description": "The fused scion of cortex-os-agent + persona: one zero-LLM-dependent agent stack — Mind proposes, Muscle executes, Gate disposes.",
   "type": "module",
   "main": "src/index.js",

package/src/config.js

@@ -27,7 +27,9 @@ export const DEFAULTS = Object.freeze({
   forge: { min_support: 3, min_precision: 0.7, max_trigger_terms: 3, max_seeds_per_run: 5 },
   queue: { max_attempts: 3 },
   analyzer: { enabled: true },
-  architecture: { rules: [] },     // declared layer/dependency-direction rules (mind/architecture.js)
+  schematic: { enabled: true, digest_ttl_ms: 30000 },   // map-first THINK: inject the codebase digest into every ladder decide (warm-cache TTL)
+  brief: { ttl_s: 3600, budget_bytes: 64000, read_limit: 24, max_item_bytes: 8000 },   // the working-set policy, declared (Codebuff CompactionPolicy lineage) — task-brief defaults defer to this
+  architecture: { rules: [], hubs: { max_fan_in: null, max_fan_out: null, max_layer_fan_in: null, ignore: [] } },     // declared layer rules (mind/architecture.js); hubs thresholds are the schematic's measured shape (null = not checked)
   daemon: { auto_fix: false, max_fixes_per_scan: 10 },
   muscle: { path_deny: [], path_allow: [] },   // empty deny = shipped defaults
   api: { token: null, port: 5107, host: '127.0.0.1' },

package/src/ladder.js

@@ -27,7 +27,12 @@ import * as replay from './mind/replay.js';
 import * as seeds from './mind/seeds.js';
 import * as brainReasoner from './brain/reasoner.js';
 import * as memory from './brain/memory.js';
-import * as trail from './kernel/trail.js';
+
+// The warm map: one digest, refreshed at most once per TTL window (see the
+// MAP-FIRST THINK block in decide()). Module-level so a hot daemon's scans
+// and every worker's THINK share the same amortized cost.
+let warmMap = null;
+const MAP_CONTEXT_TTL_MS = 30_000;import * as trail from './kernel/trail.js';
 import { forge } from './mind/forge.js';
 import { load as loadConfig } from './config.js';
 import { analyzeSource, readTargetSource } from './mind/analyzer-rung.js';
@@ -154,6 +159,56 @@ export async function decide(problem, opts = {}) {
   const memoryScope = opts.memoryScope ?? cfg.memory.scope ?? 'auto';
   const minInsightConfidence = opts.minInsightConfidence ?? cfg.ladder.min_insight_confidence;
 
+  // MAP-FIRST THINK (the schematics contract): every task starts from the
+  // codebase map, not from re-reading source. The digest is the one-screen
+  // briefing — layers, entries, hubs, surface — attached to the input as
+  // `mapContext` for every downstream rung (analyzer reasoning, generator
+  // prompts, research queries).
+  // COST CONTRACT: mapFor() re-parses only changed files, but even its
+  // hash-only pass reads+hashes every file — per-decide that is real money
+  // on large trees and it starves latency-bounded scans. THINK context
+  // tolerates seconds of staleness, so the digest is served from a WARM
+  // cache (default 30s TTL, config schematic.digest_ttl_ms): at most one
+  // refresh per TTL window. Anything that needs fresh truth (the analyzer
+  // rung, the Gate) reads the real source as always — context never
+  // misleads: a map built for a different root, or disabled in config,
+  // is skipped silently.
+  if (cfg.schematic?.enabled !== false && !input.mapContext) {
+    try {
+      const ttl = Number(cfg.schematic?.digest_ttl_ms ?? MAP_CONTEXT_TTL_MS);
+      const stale = !warmMap || warmMap.root !== project || (Date.now() - warmMap.at > ttl);
+      if (stale) {
+        const sch = await import('./mind/schematic.js');
+        const prev = sch.loadModel();
+        const mapRoot = prev?.root ?? project;
+        const { model } = sch.mapFor(mapRoot);
+        warmMap = model && model.totalSymbols > 0
+          ? { root: model.root, at: Date.now(), digest: sch.digest(model) }
+          : null;
+      }
+      if (warmMap?.digest) {
+        input.mapContext = warmMap.digest;
+        // SKILL MATCH (procedural context, same THINK pass): matched skills
+        // inject into the task's working set (ephemeral brief) — a skill
+        // for THIS task is fuel, not furniture. No match, no injection.
+        if (_routingTaskId) {
+          try {
+            const sk = await import('./mind/skills.js');
+            const { injected } = await sk.injectSkills(_routingTaskId, String(input.text || ''), { limit: 2 });
+            if (injected.length) trail.journal('ladder.skills-injected', { task: _routingTaskId, skills: injected.map(i => i.name) });
+          } catch (err) {
+            trail.journal('ladder.skills-skipped', { error: String(err?.message || err).slice(0, 120) });
+          }
+        }
+        trail.journal('ladder.map-context', {
+          root: warmMap.root, cachedMs: Date.now() - warmMap.at,
+        });
+      }
+    } catch (err) {
+      trail.journal('ladder.map-context-skipped', { error: String(err?.message || err).slice(0, 120) });
+    }
+  }
+
   // Rung 1 — replay (TEXT-ONLY problems): the zero-generation fast path.
   // For problems carrying a concrete file the analyzer (below) runs FIRST:
   // a replay verdict for a file task is an OUTCOME RECORD ("this was fixed

package/src/mind/agent-templates.js

@@ -0,0 +1,287 @@
+/**
+ * mind/agent-templates.js — DECLARATIVE AGENT TEMPLATES (Codebuff
+ * agents-as-data lineage).
+ *
+ * The gap it closes: FS's swarm registers one hardcoded `swarm-generalist`
+ * role and every worker is identical. Codebuff's insight — the same doctrine
+ * as FS's rules/recipes/templates — is that AGENTS are data too: a template
+ * declares a display name, what problems it solves (so a parent can choose),
+ * the input/output schemas at its spawn boundary, the tool allowlist (least
+ * privilege), the capabilities it can claim, its bounds, and WHICH OTHER
+ * TEMPLATES it may spawn (the spawn graph).
+ *
+ * Zero-LLM: templates carry no model, no prompts-as-code, no handleSteps —
+ * a template is a CONTRACT for a kernel worker. Validation is loud at load
+ * (the offending path in every error), unknown template references fail at
+ * LOAD time, not spawn time, and everything journals to the trail.
+ *
+ *   loadTemplates(dir)          → load all *.yaml templates (loud, idempotent)
+ *   registerTemplate(def)       → register one (validated)
+ *   getTemplate(id) / listTemplates()
+ *   routeToTemplate(problem, opts) → deterministic capability routing:
+ *                                   score templates against a task's text +
+ *                                   capabilities; returns ranked candidates
+ *   spawnTemplate(id, { taskId }) → bind a worker to the template's role
+ *                                   contract (role registry integration)
+ *
+ * @module mind/agent-templates
+ */
+
+'use strict';
+
+import { readdirSync, readFileSync, existsSync } from 'node:fs';
+import { join, basename, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseYaml } from '../config.js';
+import * as roles from '../kernel/roles.js';
+import { journal as trailJournal } from '../kernel/trail.js';
+
+const _templates = new Map();
+
+/** The shipped defaults ship with the package — data, always available. */
+const SHIPPED_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'agent-templates');
+let _bootstrapped = false;
+
+/** Idempotent: every registry reader sees the shipped templates (load-once). */
+function bootstrap() {
+  if (_bootstrapped) return;
+  _bootstrapped = true;
+  if (existsSync(SHIPPED_DIR)) loadTemplates(SHIPPED_DIR);
+}
+
+/** Spawn graph guard: an agent that spawns everything, spawns itself. */
+const MAX_SPAWN_DEPTH = 8;
+
+/* ------------------------------------------------------------------ *
+ * Validation — loud, with the offending path in every message.
+ * ------------------------------------------------------------------ */
+
+const VALID_CAPABILITY = /^[a-z0-9:*._-]+$/;
+
+export function validateTemplate(def, source = '<inline>') {
+  const where = `agent-templates[${def?.id || basename(String(source))}]`;
+  if (!def || typeof def !== 'object') {
+    throw new Error(`${where}: template must be an object`);
+  }
+  if (!def.id || typeof def.id !== 'string' || !/^[a-z0-9][a-z0-9._-]*$/.test(def.id)) {
+    throw new Error(`${where}: id must be a lowercase dotted/hyphenated slug (got ${JSON.stringify(def.id)})`);
+  }
+  if (!def.display_name || typeof def.display_name !== 'string') {
+    throw new Error(`${where}: display_name is required (what reports show)`);
+  }
+  if (!def.spawner_prompt || typeof def.spawner_prompt !== 'string' || def.spawner_prompt.length < 8) {
+    throw new Error(`${where}: spawner_prompt is required — a parent must be able to CHOOSE this template from its description`);
+  }
+  if (!Array.isArray(def.capabilities) || def.capabilities.length === 0 ||
+      def.capabilities.some(c => typeof c !== 'string' || !VALID_CAPABILITY.test(c))) {
+    throw new Error(`${where}: capabilities must be a non-empty array of slug strings (codebuff lineage: capability routing starts in the template)`);
+  }
+  // Schemas: declared as field-type maps — deterministic, no zod-style magic.
+  for (const key of ['input_schema', 'output_schema']) {
+    const schema = def[key];
+    if (schema === undefined) continue;
+    if (typeof schema !== 'object' || schema === null || Array.isArray(schema)) {
+      throw new Error(`${where}: ${key} must be an object mapping field → type`);
+    }
+    for (const [field, type] of Object.entries(schema)) {
+      if (!/^[a-z_][a-z0-9_]*$/.test(field)) {
+        throw new Error(`${where}: ${key} field ${JSON.stringify(field)} is not a slug`);
+      }
+      if (!['string', 'number', 'boolean', 'array', 'object', 'any'].includes(type)) {
+        throw new Error(`${where}: ${key}.${field} has unknown type ${JSON.stringify(type)} (string|number|boolean|array|object|any)`);
+      }
+    }
+  }
+  if (def.tool_allowlist !== undefined) {
+    if (!Array.isArray(def.tool_allowlist) || def.tool_allowlist.some(t => typeof t !== 'string' || !t)) {
+      throw new Error(`${where}: tool_allowlist must be an array of tool-name strings`);
+    }
+  }
+  if (def.spawnable_agents !== undefined) {
+    if (!Array.isArray(def.spawnable_agents) ||
+        def.spawnable_agents.some(a => typeof a !== 'string' || !a)) {
+      throw new Error(`${where}: spawnable_agents must be an array of template ids`);
+    }
+    if (def.spawnable_agents.includes(def.id)) {
+      throw new Error(`${where}: a template cannot spawn itself (spawn graph must be acyclic by construction)`);
+    }
+  }
+  if (def.bounds !== undefined && (typeof def.bounds !== 'object' || def.bounds === null || Array.isArray(def.bounds))) {
+    throw new Error(`${where}: bounds must be an object (max_turns | timeout_ms | ...)`);
+  }
+  if (def.max_concurrency !== undefined && (!Number.isFinite(def.max_concurrency) || def.max_concurrency < 1)) {
+    throw new Error(`${where}: max_concurrency must be a positive number`);
+  }
+  if (def.triggers !== undefined) {
+    if (!Array.isArray(def.triggers) || def.triggers.some(t => typeof t !== 'string' || !t)) {
+      throw new Error(`${where}: triggers must be an array of lowercase keyword strings (deterministic routing)`);
+    }
+  }
+  return def;
+}
+
+/* ------------------------------------------------------------------ *
+ * Registry.
+ * ------------------------------------------------------------------ */
+
+export function registerTemplate(def, opts = {}) {
+  validateTemplate(def, opts.source);
+  const prev = _templates.get(def.id);
+  _templates.set(def.id, {
+    id: def.id,
+    display_name: def.display_name,
+    spawner_prompt: def.spawner_prompt,
+    capabilities: [...new Set(def.capabilities)],
+    ...(def.input_schema ? { input_schema: { ...def.input_schema } } : {}),
+    ...(def.output_schema ? { output_schema: { ...def.output_schema } } : {}),
+    ...(def.tool_allowlist ? { tool_allowlist: [...def.tool_allowlist] } : {}),
+    ...(def.spawnable_agents ? { spawnable_agents: [...def.spawnable_agents] } : {}),
+    ...(def.triggers ? { triggers: [...new Set(def.triggers)] } : {}),
+    ...(def.bounds ? { bounds: { ...def.bounds } } : {}),
+    ...(Number.isFinite(def.max_concurrency) ? { max_concurrency: def.max_concurrency } : {}),
+    ...(def.source ? { source: def.source } : {}),
+  });
+  trailJournal('template.registered', { id: def.id, updated: !!prev });
+  return _templates.get(def.id);
+}
+
+/** Load every *.yaml template from a directory (and the shipped defaults). */
+export function loadTemplates(dir) {
+  const loaded = [];
+  if (dir) {
+    if (!existsSync(dir)) throw new Error(`agent-templates: directory not found: ${dir}`);
+    for (const name of readdirSync(dir).filter(n => n.endsWith('.yaml') || n.endsWith('.yml')).sort()) {
+      const path = join(dir, name);
+      const doc = parseYaml(readFileSync(path, 'utf8'), path);
+      const defs = Array.isArray(doc?.templates) ? doc.templates : [doc];
+      for (const def of defs) {
+        registerTemplate({ ...def, source: path });
+        loaded.push({ id: def.id, path });
+      }
+    }
+  }
+  trailJournal('templates.loaded', { dir: dir || null, count: loaded.length });
+  return loaded;
+}
+
+export function getTemplate(id) {
+  bootstrap();
+  return _templates.get(id) ?? null;
+}
+
+export function listTemplates() {
+  bootstrap();
+  return [..._templates.values()].sort((a, b) => a.id < b.id ? -1 : 1);
+}
+
+/* ------------------------------------------------------------------ *
+ * Spawn-graph integrity — load-time cycle detection over spawnable_agents.
+ * Codebuff trusts its publishers; FS trusts no graph it hasn't checked.
+ * ------------------------------------------------------------------ */
+
+export function checkSpawnGraph() {
+  const cycles = [];
+  const visiting = new Set();
+  const done = new Set();
+  const walk = (id, path) => {
+    if (done.has(id)) return;
+    if (visiting.has(id)) {
+      cycles.push([...path.slice(path.indexOf(id)), id]);
+      return;
+    }
+    visiting.add(id);
+    const t = _templates.get(id);
+    for (const child of (t?.spawnable_agents || [])) {
+      if (_templates.has(child)) walk(child, [...path, id]);
+    }
+    visiting.delete(id);
+    done.add(id);
+  };
+  for (const id of _templates.keys()) walk(id, []);
+  if (cycles.length > 0) {
+    throw new Error(`agent-templates: spawn graph has cycles: ${cycles.map(c => c.join(' → ')).join('; ')}`);
+  }
+  return { cycles: [] };
+}
+
+/** Depth-limited spawn closure — a spawn request beyond this is refused. */
+export function spawnClosure(id) {
+  bootstrap();
+  if (!_templates.has(id)) {
+    throw new Error(`agent-templates.spawnClosure: unknown template ${JSON.stringify(id)} — known: ${[..._templates.keys()].join(', ') || '(none)'}`);
+  }
+  const seen = new Set();
+  let frontier = [id];
+  let depth = 0;
+  while (frontier.length && depth < MAX_SPAWN_DEPTH) {
+    const next = [];
+    for (const cur of frontier) {
+      if (seen.has(cur)) continue;
+      seen.add(cur);
+      for (const child of (_templates.get(cur)?.spawnable_agents || [])) next.push(child);
+    }
+    frontier = next;
+    depth++;
+  }
+  return { templates: [...seen].sort(), depth };
+}
+
+/* ------------------------------------------------------------------ *
+ * Deterministic routing — WHICH template for THIS problem?
+ * Codebuff's spawnerPrompt is an LLM choice; FS's is a scored match:
+ * trigger keyword hits + capability coverage, deterministic and journaled.
+ * ------------------------------------------------------------------ */
+
+export function routeToTemplate(problem, opts = {}) {
+  bootstrap();
+  const text = String(problem || '').toLowerCase();
+  const needCaps = new Set(opts.capabilities || []);
+  const scored = [];
+  for (const t of listTemplates()) {
+    let score = 0;
+    const hits = [];
+    for (const trig of (t.triggers || [])) {
+      if (text.includes(trig)) { score += 2; hits.push(trig); }
+    }
+    if (needCaps.size > 0) {
+      const covered = [...needCaps].filter(c =>
+        t.capabilities.includes(c) || t.capabilities.includes('*'));
+      if (covered.length < needCaps.size) continue; // hard capability gate
+      score += covered.length;
+    }
+    if (score > 0) scored.push({ id: t.id, display_name: t.display_name, score, hits });
+  }
+  scored.sort((a, b) => b.score - a.score || (a.id < b.id ? -1 : 1));
+  trailJournal('template.route', { problem: String(problem || '').slice(0, 80), routed: scored[0]?.id ?? null, candidates: scored.length });
+  return scored;
+}
+
+/* ------------------------------------------------------------------ *
+ * Spawn — a template becomes a ROLE (the kernel's claim gate is the
+ * only execution authority; templates never execute anything).
+ * ------------------------------------------------------------------ */
+
+export function spawnTemplate(id, { workerId } = {}) {
+  bootstrap();
+  const t = _templates.get(id);
+  if (!t) {
+    throw new Error(`agent-templates.spawn: unknown template ${JSON.stringify(id)} — known: ${[..._templates.keys()].join(', ') || '(none)'}`);
+  }
+  const roleId = `agent-template:${id}`;
+  if (!roles.getRole(roleId)) {
+    roles.registerRole({
+      id: roleId,
+      capabilities: t.capabilities,
+      ...(t.bounds ? { bounds: t.bounds } : {}),
+      ...(Number.isFinite(t.max_concurrency) ? { max_concurrency: t.max_concurrency } : {}),
+    });
+  }
+  let bound = null;
+  if (workerId) bound = roles.bindWorker(workerId, roleId);
+  trailJournal('template.spawned', { id, worker: workerId ?? null, role: roleId });
+  return { template: t, role: roles.getRole(roleId), bound };
+}
+
+export function reset() {
+  _templates.clear();
+}