futura-scion 0.2.7 → 0.2.8

package/README.md

@@ -858,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "futura-scion",
-  "version": "0.2.7",
+  "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

@@ -28,6 +28,7 @@ export const DEFAULTS = Object.freeze({
   queue: { max_attempts: 3 },
   analyzer: { enabled: true },
   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

package/src/ladder.js

@@ -188,6 +188,18 @@ export async function decide(problem, opts = {}) {
       }
       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,
         });

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();
+}

package/src/mind/commitbench.js

@@ -0,0 +1,194 @@
+/**
+ * mind/commitbench.js — COMMIT-RECONSTRUCTION EVAL (Codebuff BuffBench
+ * lineage, scored deterministically).
+ *
+ * BuffBench's insight: the honest benchmark for a coding agent is "rebuild
+ * a REAL commit" — ground truth is the actual diff, not a planted fixture.
+ * Its judge was an LLM; FS's doctrine doesn't allow that, and it doesn't
+ * need one: a diff is text, and diff similarity is arithmetic.
+ *
+ * The harness, for one fixture (a repo snapshot + a commit to reconstruct):
+ *   1. Check out the PARENT of the target commit into a scratch worktree.
+ *   2. Hand the problem statement (the commit message) to the solver — any
+ *      async (worktreePath, problem) => { files: [{file, content}] } —
+ *      injected, deterministic by construction, or the generator worker.
+ *   3. Score the attempt against the ground-truth diff WITHOUT any judge:
+ *        file_recall    — fraction of truly-changed files the solver touched
+ *        file_precision — fraction of touched files that were truly changed
+ *        line_f1        — token-level F1 between the union of changed lines
+ *                         and the solver's changed lines (order-free,
+ *                         whitespace-normalized)
+ *        gate           — did the repo still build/lint (exit-code oracle)
+ *      overall = 0.4*file_recall + 0.3*file_precision + 0.3*line_f1,
+ *      reported per-fixture and aggregated (mean, and the BuffBench-style
+ *      hard subset separately).
+ *
+ *   runBench(fixtures, solver, opts) → per-fixture + aggregate report
+ *
+ * @module mind/commitbench
+ */
+
+'use strict';
+
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, rmSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { journal as trailJournal } from '../kernel/trail.js';
+
+/* ------------------------------------------------------------------ *
+ * Ground truth — the real diff, straight from git.
+ * ------------------------------------------------------------------ */
+
+/** Parse `git diff --numstat` output into { file, added, removed }. */
+export function parseNumstat(text) {
+  const out = [];
+  for (const line of String(text || '').split('\n')) {
+    const m = line.match(/^(\d+|-)\t(\d+|-)\t(.+)$/);
+    if (!m) continue;
+    const [, a, r, file] = m;
+    out.push({ file: file.replace(/^"|"$/g, ''), added: a === '-' ? 0 : Number(a), removed: r === '-' ? 0 : Number(r) });
+  }
+  return out;
+}
+
+/** Extract added-or-removed line CONTENT (order-free token multiset basis). */
+export function changedLines(diffText) {
+  const lines = [];
+  for (const line of String(diffText || '').split('\n')) {
+    if ((line.startsWith('+') && !line.startsWith('+++')) || (line.startsWith('-') && !line.startsWith('---'))) {
+      lines.push(line.slice(1).trim());
+    }
+  }
+  return lines.filter(l => l.length > 0);
+}
+
+function tokenMultiset(lines) {
+  const counts = new Map();
+  for (const l of lines) {
+    for (const tok of l.toLowerCase().split(/[^a-z0-9_]+/).filter(t => t)) {
+      counts.set(tok, (counts.get(tok) || 0) + 1);
+    }
+  }
+  return counts;
+}
+
+/** Set-F1 between two line sets, tokenized and order-free. */
+export function lineF1(linesA, linesB) {
+  const A = tokenMultiset(linesA);
+  const B = tokenMultiset(linesB);
+  if (A.size === 0 && B.size === 0) return 1;
+  if (A.size === 0 || B.size === 0) return 0;
+  let overlap = 0;
+  for (const [tok, ca] of A) overlap += Math.min(ca, B.get(tok) || 0);
+  const totalA = [...A.values()].reduce((s, n) => s + n, 0);
+  const totalB = [...B.values()].reduce((s, n) => s + n, 0);
+  const p = overlap / totalA, r = overlap / totalB;
+  return (p + r) === 0 ? 0 : (2 * p * r) / (p + r);
+}
+
+/* ------------------------------------------------------------------ *
+ * Worktree plumbing.
+ * ------------------------------------------------------------------ */
+
+function git(repo, args, opts = {}) {
+  const r = spawnSync('git', args, { cwd: repo, encoding: 'utf8', timeout: opts.timeout_ms ?? 60_000 });
+  if (r.status !== 0 && !opts.allowFail) {
+    throw new Error(`commitbench: git ${args.join(' ')} failed: ${(r.stderr || `exit ${r.status}`).slice(0, 300)}`);
+  }
+  return r;
+}
+
+/**
+ * One fixture run: check out commit^ into a scratch worktree, collect the
+ * ground truth, invoke the solver, score it.
+ */
+export async function runFixture(fixture, solver, opts = {}) {
+  const { repo, commit, problem } = fixture;
+  const worktree = mkdtempSync(join(tmpdir(), 'scion-commitbench-'));
+  try {
+    // Ground truth from the REAL repo — the parent tree is the starting line.
+    git(repo, ['worktree', 'add', '--detach', worktree, `${commit}^`]);
+    const truth = git(repo, ['show', '--numstat', '--format=', commit]);
+    const truthFiles = parseNumstat(truth.stdout).map(n => n.file);
+    const truthDiff = git(repo, ['show', '--format=', commit]).stdout;
+    const truthLines = changedLines(truthDiff);
+
+    // The solver works in the worktree at the parent commit; it receives
+    // the fixture as a third argument (a per-fixture solver needs the commit).
+    const attempt = await solver(worktree, problem ?? git(repo, ['log', '-1', '--format=%B', commit]).stdout.trim(), fixture);
+    const touched = (attempt?.files || []).map(f => f.file);
+
+    // Deterministic scoring — no judge, arithmetic.
+    const truthSet = new Set(truthFiles);
+    const touchedSet = new Set(touched);
+    const hits = [...touchedSet].filter(f => truthSet.has(f));
+    const file_recall = truthSet.size === 0 ? 1 : hits.length / truthSet.size;
+    const file_precision = touchedSet.size === 0 ? 0 : hits.length / touchedSet.size;
+
+    // The attempt's changed lines come from the WORKTREE whenever the solver
+    // touched it (files: [] = "I edited in place — diff HEAD"), and from the
+    // returned file contents only when they carry content.
+    const solverReturnedContent = (attempt?.files || []).some(f => f.content != null);
+    let attemptLines = [];
+    if (solverReturnedContent) {
+      attemptLines = attempt.files.flatMap(f => changedLines(String(f.content ?? '')));
+    } else {
+      // HEAD (not the bare worktree diff): a solver that stages its work
+      // (git apply --index, cherry-pick --no-commit) must still be seen.
+      const after = git(worktree, ['diff', '-U0', 'HEAD', '--']).stdout;
+      attemptLines = changedLines(after);
+    }
+    const f1 = lineF1(truthLines, attemptLines);
+
+    // Exit-code oracle: optional gate command over the attempt (build/test).
+    let gate = null;
+    if (opts.gate_cmd) {
+      const g = spawnSync(opts.gate_cmd, { cwd: worktree, encoding: 'utf8', shell: true, timeout: opts.gate_timeout_ms ?? 300_000 });
+      gate = { cmd: opts.gate_cmd, ok: g.status === 0, exit: g.status };
+    }
+
+    const overall = 0.4 * file_recall + 0.3 * file_precision + 0.3 * f1;
+    return {
+      id: fixture.id ?? `${commit.slice(0, 10)}`,
+      file_recall, file_precision, line_f1: f1, overall,
+      touched_files: touched.length, truth_files: truthFiles.length,
+      ...(gate ? { gate } : {}),
+    };
+  } finally {
+    git(repo, ['worktree', 'remove', '--force', worktree], { allowFail: true });
+    try { rmSync(worktree, { recursive: true, force: true }); } catch { /* worktree remove already handled it */ }
+  }
+}
+
+/**
+ * Run a bench: fixtures × one solver. Aggregates mean scores; the top-quartile
+ * hardest fixtures (fewest truth files? no — lowest overall) form the HARD
+ * subset, reported separately like BuffBench's hard sets.
+ */
+export async function runBench(fixtures, solver, opts = {}) {
+  if (!Array.isArray(fixtures) || fixtures.length === 0) {
+    throw new Error('commitbench.runBench: fixtures must be a non-empty array');
+  }
+  if (typeof solver !== 'function') {
+    throw new Error('commitbench.runBench: solver must be async (worktreePath, problem) => { files }');
+  }
+  const results = [];
+  for (const f of fixtures) results.push(await runFixture(f, solver, opts));
+  const mean = (key) => results.reduce((s, r) => s + r[key], 0) / results.length;
+  const sorted = [...results].sort((a, b) => a.overall - b.overall);
+  const hardN = Math.max(1, Math.ceil(results.length / 4));
+  const report = {
+    fixtures: results.length,
+    mean: {
+      file_recall: mean('file_recall'),
+      file_precision: mean('file_precision'),
+      line_f1: mean('line_f1'),
+      overall: mean('overall'),
+    },
+    hard_subset: { count: hardN, mean_overall: sorted.slice(0, hardN).reduce((s, r) => s + r.overall, 0) / hardN },
+    results,
+  };
+  trailJournal('commitbench.ran', { fixtures: report.fixtures, overall: report.mean.overall, hard: report.hard_subset.mean_overall });
+  return report;
+}

package/src/mind/librarian.js

@@ -0,0 +1,109 @@
+/**
+ * mind/librarian.js — EXTERNAL REPO COMPREHENSION (Codebuff librarian
+ * lineage, rebuilt deterministically).
+ *
+ * Codebuff's librarian shallow-clones a repo into /tmp and answers
+ * questions with an LLM over the clone. FS's version answers with the
+ * SCHEMATIC: shallow-clone (depth 1), run the codebase map over the clone,
+ * and return a structured digest — layers, entries, hubs, exported surface
+ * — plus the files relevant to the question (deterministic symbol-name
+ * match over the map). No model anywhere: the map IS the understanding.
+ *
+ * Safety: clones land in a temp dir under the OS tmpdir, the answer cites
+ * paths INSIDE the clone, and cleanup is explicit (or opts.keep for
+ * follow-up inspection). A repo that fails to clone fails loud with the
+ * command and its stderr — never a silent null.
+ *
+ *   askRepo(repoUrl, question, opts) → { digest, relevant_files, clone_dir, stats }
+ *   cleanup(cloneDir)                → rm -rf the clone
+ *
+ * @module mind/librarian
+ */
+
+'use strict';
+
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import * as schematic from './schematic.js';
+import { journal as trailJournal } from '../kernel/trail.js';
+
+const REPO_URL_RE = /^(https:\/\/[^\s]+|[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+)$/;
+
+function shallowClone(repoUrl, opts) {
+  const dir = mkdtempSync(join(tmpdir(), 'scion-librarian-'));
+  const url = /^https:/.test(repoUrl)
+    ? repoUrl
+    : `https://github.com/${repoUrl}.git`;
+  const r = spawnSync('git', ['clone', '--depth', '1', '--quiet', url, dir], {
+    encoding: 'utf8',
+    timeout: opts.timeout_ms ?? 120_000,
+  });
+  if (r.status !== 0) {
+    try { rmSync(dir, { recursive: true, force: true }); } catch { /* nothing to clean */ }
+    throw new Error(`librarian: git clone failed for ${url}: ${(r.stderr || r.error?.message || `exit ${r.status}`).slice(0, 400)}`);
+  }
+  return dir;
+}
+
+/** Deterministic relevance: symbol/token names from the question, scored over the map. */
+function relevantFiles(model, question, limit) {
+  const tokens = String(question || '')
+    .toLowerCase()
+    .split(/[^a-z0-9_]+/)
+    .filter(t => t.length >= 4);
+  if (tokens.length === 0) return [];
+  const scored = [];
+  for (const f of model.files) {
+    const hay = `${f.file} ${(model.exports[f.file] || []).join(' ').toLowerCase()}`;
+    const symbolsInFile = model.symbols.filter(s => s.file === f.file).map(s => s.name.toLowerCase());
+    let score = 0;
+    for (const tok of tokens) {
+      if (hay.includes(tok)) score += 2;
+      if (symbolsInFile.some(s => s.includes(tok))) score += 3;
+    }
+    if (score > 0) scored.push({ file: f.file, score });
+  }
+  scored.sort((a, b) => b.score - a.score || (a.file < b.file ? -1 : 1));
+  return scored.slice(0, limit).map(s => s.file);
+}
+
+/**
+ * Shallow-clone an external repository and answer a question about it from
+ * its schematic — one full read of a foreign codebase, zero file re-reads
+ * afterwards (the map answers; only cited files need opening).
+ * @param {string} repoUrl  https URL or `owner/repo` shorthand
+ * @param {string} question what to answer — drives relevance ranking
+ * @returns {{ digest: string, relevant_files: string[], clone_dir: string,
+ *              stats: { files, symbols, edges } }}
+ */
+export function askRepo(repoUrl, question, opts = {}) {
+  if (!REPO_URL_RE.test(repoUrl || '')) {
+    throw new Error(`librarian: repoUrl must be an https URL or owner/repo (got ${JSON.stringify(repoUrl)})`);
+  }
+  const started = Date.now();
+  const cloneDir = shallowClone(repoUrl, opts);
+  try {
+    const { model } = schematic.mapFor(cloneDir);
+    const digest = schematic.digest(model);
+    const relevant = relevantFiles(model, question, opts.limit ?? 8);
+    const stats = {
+      files: model.files.length,
+      symbols: model.symbols.length,
+      edges: model.edges.length,
+      ms: Date.now() - started,
+    };
+    trailJournal('librarian.asked', { repo: repoUrl, question: String(question).slice(0, 120), files: stats.files, symbols: stats.symbols, ms: stats.ms });
+    return { digest, relevant_files: relevant, clone_dir: cloneDir, stats };
+  } catch (err) {
+    if (!opts.keep) { try { rmSync(cloneDir, { recursive: true, force: true }); } catch { /* best-effort */ } }
+    throw err;
+  }
+}
+
+/** Remove a kept clone (the caller's cleanup duty — Codebuff's `rm -rf cloneDir`). */
+export function cleanup(cloneDir) {
+  rmSync(cloneDir, { recursive: true, force: true });
+  trailJournal('librarian.cleaned', { dir: cloneDir });
+}

package/src/mind/skills.js

@@ -0,0 +1,210 @@
+/**
+ * mind/skills.js — PROCEDURAL KNOWLEDGE PACKS (Codebuff SKILL.md lineage).
+ *
+ * The gap it closes: FS's knowledge packs are FACTS and PRINCIPLES; nothing
+ * carried PROCEDURES — the how-to for a situation ("how to release this
+ * project", "how to write a migration here", "how this repo runs tests").
+ * Skills are markdown files with a small frontmatter block:
+ *
+ *     ---
+ *     name: run-tests
+ *     description: How to run and interpret this repo's test suites
+ *     triggers: [test, suite, verify]
+ *     ---
+ *     # body — the actual procedure …
+ *
+ * Loading is deterministic: frontmatter is parsed loud (bad frontmatter is
+ * a thrown error naming the file), the body is stored verbatim, and a
+ * skill's trigger match against a task's text is exact keyword inclusion —
+ * never a model's judgment. A matched skill is injected into the task's
+ * working set (the ephemeral brief), NOT the durable brain: procedures are
+ * fuel for the task, and the lesson distiller keeps only what the outcome
+ * teaches.
+ *
+ *   loadSkills(dirs)              → load every SKILL.md under dirs
+ *   getSkill(name) / listSkills()
+ *   matchSkills(text, { limit })  → deterministic trigger scoring
+ *   injectSkills(taskId, text)    → match + absorb into the task brief
+ *
+ * @module mind/skills
+ */
+
+'use strict';
+
+import { readdirSync, readFileSync, existsSync, statSync } from 'node:fs';
+import { join, basename, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { journal as trailJournal } from '../kernel/trail.js';
+
+const _skills = new Map();
+
+/** The shipped skills live with the package — data, always available. */
+const SHIPPED_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'skills');
+let _bootstrapped = false;
+
+/** Idempotent: every registry reader sees the shipped skills (load-once). */
+function bootstrap() {
+  if (_bootstrapped) return;
+  _bootstrapped = true;
+  if (existsSync(SHIPPED_DIR)) loadSkills([SHIPPED_DIR]);
+}
+
+const NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
+
+/* ------------------------------------------------------------------ *
+ * Parsing — loud, file-naming errors.
+ * ------------------------------------------------------------------ */
+
+export function parseSkill(raw, source = '<inline>') {
+  const where = `skills[${source}]`;
+  if (typeof raw !== 'string') throw new Error(`${where}: skill source must be a string`);
+  const text = raw.replace(/\r\n/g, '\n');
+  if (!text.startsWith('---')) {
+    throw new Error(`${where}: missing frontmatter — a skill starts with a --- block (name, description)`);
+  }
+  const end = text.indexOf('\n---', 3);
+  if (end === -1) throw new Error(`${where}: unterminated frontmatter (no closing ---)`);
+
+  const fmLines = text.slice(4, end).split('\n');
+  const fm = {};
+  let currentKey = null;
+  for (const line of fmLines) {
+    if (!line.trim() || line.trim().startsWith('#')) continue;
+    const m = line.match(/^([a-z_-]+):\s*(.*)$/);
+    if (!m) throw new Error(`${where}: cannot parse frontmatter line ${JSON.stringify(line)}`);
+    const [, key, rest] = m;
+    if (rest.trim() !== '') {
+      fm[key] = rest.trim();
+      currentKey = key;
+    } else {
+      fm[key] = [];
+      currentKey = key;
+    }
+  }
+  // Inline arrays and list items both fold into an array value.
+  const listOf = (key) => {
+    const v = fm[key];
+    if (v === undefined) return [];
+    if (Array.isArray(v)) return v;
+    if (typeof v === 'string') {
+      const s = v.trim();
+      if (s.startsWith('[')) {
+        return s.replace(/^\[/, '').replace(/\]$/, '').split(',').map(x => x.trim().replace(/^["']|["']$/g, '')).filter(Boolean);
+      }
+      return [s];
+    }
+    return [];
+  };
+
+  const name = typeof fm.name === 'string' ? fm.name : '';
+  if (!NAME_RE.test(name)) {
+    throw new Error(`${where}: frontmatter name must be a lowercase hyphenated slug (got ${JSON.stringify(name)})`);
+  }
+  if (!fm.description || typeof fm.description !== 'string' || fm.description.length < 4) {
+    throw new Error(`${where}: frontmatter description is required (it is what a matcher shows before loading)`);
+  }
+  const body = text.slice(end + 4).replace(/^\n+/, '');
+  if (!body.trim()) throw new Error(`${where}: skill body is empty — a procedure with no steps is not a skill`);
+
+  return {
+    name,
+    description: fm.description,
+    triggers: listOf('triggers').map(t => t.toLowerCase()),
+    version: typeof fm.version === 'string' ? fm.version : null,
+    source,
+    body,
+  };
+}
+
+/* ------------------------------------------------------------------ *
+ * Loading.
+ * ------------------------------------------------------------------ */
+
+export function loadSkills(dirs) {
+  const loaded = [];
+  for (const dir of dirs) {
+    if (!existsSync(dir)) continue; // optional dirs skip silently; an EXPLICIT dir that exists but is unreadable still errors below
+    const walk = (d) => {
+      let entries;
+      try { entries = readdirSync(d); } catch { return; }
+      for (const name of entries.sort()) {
+        const p = join(d, name);
+        let st;
+        try { st = statSync(p); } catch { continue; }
+        if (st.isDirectory()) walk(p);
+        else if (name === 'SKILL.md' || name.endsWith('.skill.md')) {
+          const skill = parseSkill(readFileSync(p, 'utf8'), p);
+          // Filename discipline: SKILL.md's directory names it; *.skill.md names itself.
+          const derived = name === 'SKILL.md' ? basename(dirname(p)) : name.replace(/\.skill\.md$/, '');
+          if (derived !== skill.name) {
+            throw new Error(`skills: ${p} declares name ${JSON.stringify(skill.name)} but its ${name === 'SKILL.md' ? 'directory' : 'filename'} is ${JSON.stringify(derived)}`);
+          }
+          _skills.set(skill.name, skill);
+          loaded.push({ name: skill.name, path: p });
+        }
+      }
+    };
+    walk(dir);
+  }
+  trailJournal('skills.loaded', { dirs, count: loaded.length, names: loaded.map(l => l.name) });
+  return loaded;
+}
+
+export function getSkill(name) {
+  bootstrap();
+  return _skills.get(name) ?? null;
+}
+
+export function listSkills() {
+  bootstrap();
+  return [..._skills.values()].sort((a, b) => a.name < b.name ? -1 : 1);
+}
+
+/* ------------------------------------------------------------------ *
+ * Deterministic matching — exact keyword inclusion, scored, stable order.
+ * ------------------------------------------------------------------ */
+
+export function matchSkills(text, { limit = 3 } = {}) {
+  bootstrap();
+  const hay = String(text || '').toLowerCase();
+  const scored = [];
+  for (const s of listSkills()) {
+    let score = 0;
+    const hits = [];
+    for (const trig of s.triggers) {
+      if (hay.includes(trig)) { score += 2; hits.push(trig); }
+    }
+    // Name itself is a weak trigger ("use the run-tests skill").
+    if (hay.includes(s.name)) score += 3;
+    if (score > 0) scored.push({ name: s.name, description: s.description, score, hits });
+  }
+  scored.sort((a, b) => b.score - a.score || (a.name < b.name ? -1 : 1));
+  return scored.slice(0, limit);
+}
+
+/**
+ * Match skills against a task's text and absorb the bodies into the task's
+ * working set (the ephemeral brief — see mind/task-brief.js). Skills are
+ * fuel for THIS task, not durable knowledge.
+ */
+export async function injectSkills(taskId, text, { limit = 3 } = {}) {
+  bootstrap();
+  const matches = matchSkills(text, { limit });
+  if (matches.length === 0) return { injected: [] };
+  const { briefAbsorb } = await import('./task-brief.js');
+  const injected = [];
+  for (const m of matches) {
+    const skill = _skills.get(m.name);
+    const absorbed = briefAbsorb(taskId, [{
+      text: `SKILL ${skill.name} — ${skill.description}\n${skill.body}`,
+      source: `skill:${skill.name}`,
+    }]);
+    injected.push({ name: m.name, hits: m.hits, absorbed: absorbed.absorbed });
+    trailJournal('skill.injected', { task: taskId, skill: m.name, hits: m.hits });
+  }
+  return { injected };
+}
+
+export function reset() {
+  _skills.clear();
+}

package/src/mind/task-brief.js

@@ -27,8 +27,14 @@
 
 import { getDb } from '../brain/db.js';
 import { journal as trailJournal } from '../kernel/trail.js';
+import { get as getConfig } from '../config.js';
 
-/** Defaults: small on purpose. Overrides are loud constants, not vibes. */
+/**
+ * Defaults: small on purpose, and DECLARED, not hardcoded (Codebuff
+ * CompactionPolicy lineage): the shipped numbers mirror config.brief —
+ * the real source of truth is the config file, and briefOpen/briefRead
+ * consult it before falling back here. No hidden behavior knobs.
+ */
 export const DEFAULTS = Object.freeze({
   ttl_s: 3600,          // 1 hour — gathered material outlives the task barely
   budget_bytes: 64_000, // 64 KiB of working text — enough, and no more
@@ -36,6 +42,17 @@ export const DEFAULTS = Object.freeze({
   max_item_bytes: 8_000 // one finding larger than this is truncated to it
 });
 
+/** Config-declared policy wins over the shipped constants; opts win over both. */
+function policyFor(key, optsKey, opts) {
+  const fromOpts = opts[optsKey];
+  if (fromOpts !== undefined) return fromOpts;
+  try {
+    const declared = getConfig()?.brief?.[key];
+    if (declared !== undefined) return declared;
+  } catch { /* config not loaded (tests) — shipped default applies */ }
+  return DEFAULTS[key];
+}
+
 /**
  * Open (or resume) the working set for a task. Idempotent: an existing
  * live set is returned as-is (resume semantics), a swept/expired one is
@@ -51,8 +68,8 @@ export function briefOpen(taskId, opts = {}) {
   }
   const db = getDb();
   briefSweep(); // opportunistic global expiry — expired rows never accumulate
-  const ttl = Math.max(1, Number(opts.ttl_s ?? DEFAULTS.ttl_s));
-  const budget = Math.max(1024, Number(opts.budget_bytes ?? DEFAULTS.budget_bytes));
+  const ttl = Math.max(1, Number(policyFor('ttl_s', 'ttl_s', opts)));
+  const budget = Math.max(1024, Number(policyFor('budget_bytes', 'budget_bytes', opts)));
   const row = db.prepare(
     `SELECT COUNT(*) AS n, COALESCE(SUM(bytes), 0) AS b
      FROM task_working_set WHERE task_id = ?`
@@ -78,9 +95,9 @@ export function briefAbsorb(taskId, findings, opts = {}) {
   }
   const list = Array.isArray(findings) ? findings : (findings ? [findings] : []);
   const db = getDb();
-  const ttl = Math.max(1, Number(opts.ttl_s ?? DEFAULTS.ttl_s));
-  const budget = Math.max(1024, Number(opts.budget_bytes ?? DEFAULTS.budget_bytes));
-  const maxItem = Math.max(64, Number(opts.max_item_bytes ?? DEFAULTS.max_item_bytes));
+  const ttl = Math.max(1, Number(policyFor('ttl_s', 'ttl_s', opts)));
+  const budget = Math.max(1024, Number(policyFor('budget_bytes', 'budget_bytes', opts)));
+  const maxItem = Math.max(64, Number(policyFor('max_item_bytes', 'max_item_bytes', opts)));
   const expiresAt = new Date(Date.now() + ttl * 1000).toISOString();
   const source = opts.source ?? null;
 
@@ -128,7 +145,7 @@ export function briefAbsorb(taskId, findings, opts = {}) {
  */
 export function briefRead(taskId, opts = {}) {
   const db = getDb();
-  const limit = Math.max(1, Number(opts.limit ?? DEFAULTS.read_limit));
+  const limit = Math.max(1, Number(policyFor('read_limit', 'limit', opts)));
   const now = new Date().toISOString();
   // Lazy expiry: TTL past → gone. A read is a sweep for this task.
   db.prepare(

package/src/mind/trust.js

@@ -0,0 +1,118 @@
+/**
+ * mind/trust.js — THE TRUST GATE for loaded packs (Codebuff's publisher-trust
+ * lineage, rebuilt as evidence instead of identity).
+ *
+ * Codebuff gates registry agents by publisher identity. FS has no accounts —
+ * its doctrine is EVIDENCE — so trust here is content-addressed: a pack is
+ * trusted when its sha256 matches a pin recorded in the brain, or when the
+ * operator explicitly pins it. An unpinned external pack loads in
+ * `quarantine`: visible, listable, but never consulted by rungs until a
+ * human promotes it. Nothing is silently trusted, nothing is silently
+ * refused — every decision journals.
+ *
+ *   trustStatus(path)            → { state: 'pinned'|'quarantine'|'unseen', ... }
+ *   pin(path)                    → record the checksum pin (operator action)
+ *   unpin(path)                  → remove the pin
+ *   listTrusted()                → every pin
+ *   gate(path, { requirePinned })→ the load-time decision point
+ *
+ * @module mind/trust
+ */
+
+'use strict';
+
+import { createHash } from 'node:crypto';
+import { readFileSync, existsSync } from 'node:fs';
+import { getDb } from '../brain/db.js';
+import { journal as trailJournal } from '../kernel/trail.js';
+
+function ensureTable(db) {
+  db.exec(`CREATE TABLE IF NOT EXISTS trust_pins (
+    path TEXT PRIMARY KEY,
+    sha256 TEXT NOT NULL,
+    pinned_at TEXT NOT NULL,
+    note TEXT
+  )`);
+}
+
+export function sha256File(path) {
+  if (!existsSync(path)) throw new Error(`trust: file not found: ${path}`);
+  return createHash('sha256').update(readFileSync(path)).digest('hex');
+}
+
+/**
+ * The trust status of a pack file. `unseen` = never loaded before;
+ * `quarantine` = known content, never pinned; `pinned` = checksum matches
+ * the recorded pin; `changed` = PINNED ONCE but the content now differs —
+ * the loudest state there is (a pinned pack that mutated is either an
+ * update or a substitution, and a human decides which).
+ */
+export function trustStatus(path) {
+  const db = getDb();
+  ensureTable(db);
+  const digest = sha256File(path);
+  const row = db.prepare('SELECT * FROM trust_pins WHERE path = ?').get(path);
+  if (!row) return { path, sha256: digest, state: 'unseen' };
+  if (row.sha256 === digest) return { path, sha256: digest, state: 'pinned', pinned_at: row.pinned_at };
+  return { path, sha256: digest, state: 'changed', pinned_sha256: row.sha256, pinned_at: row.pinned_at };
+}
+
+/** Operator action: pin the current content of a pack. */
+export function pin(path, note = null) {
+  const db = getDb();
+  ensureTable(db);
+  const digest = sha256File(path);
+  db.prepare(
+    `INSERT INTO trust_pins (path, sha256, pinned_at, note) VALUES (?, ?, ?, ?)
+     ON CONFLICT(path) DO UPDATE SET sha256 = excluded.sha256, pinned_at = excluded.pinned_at, note = excluded.note`
+  ).run(path, digest, new Date().toISOString(), note);
+  trailJournal('trust.pinned', { path, sha256: digest });
+  return { path, sha256: digest, state: 'pinned' };
+}
+
+export function unpin(path) {
+  const db = getDb();
+  ensureTable(db);
+  const gone = db.prepare('DELETE FROM trust_pins WHERE path = ?').run(path);
+  trailJournal('trust.unpinned', { path, existed: gone.changes > 0 });
+  return { path, removed: gone.changes > 0 };
+}
+
+export function listTrusted() {
+  const db = getDb();
+  ensureTable(db);
+  return db.prepare('SELECT path, sha256, pinned_at, note FROM trust_pins ORDER BY path').all();
+}
+
+/**
+ * THE GATE. Called at pack-load time. Semantics:
+ *   pinned   → allowed.
+ *   unseen   → allowed ONCE in quarantine (the loader records it; the pack
+ *              is loadable but flagged — first contact is observation).
+ *   changed  → REFUSED unless opts.allowChanged (an explicit operator
+ *              re-pin) — a pinned pack that changed content must never
+ *              slide through on a routine load.
+ * @returns {{ allowed: boolean, state: string, quarantined?: boolean, reason?: string }}
+ */
+export function gate(path, opts = {}) {
+  const status = trustStatus(path);
+  if (status.state === 'pinned') return { allowed: true, state: status.state };
+  if (status.state === 'unseen') return { allowed: true, state: status.state, quarantined: true };
+  // changed
+  if (opts.allowChanged) {
+    trailJournal('trust.gate', { path, state: 'changed', decision: 'allowed-explicit' });
+    return { allowed: true, state: 'changed', quarantined: true };
+  }
+  trailJournal('trust.gate', { path, state: 'changed', decision: 'refused' });
+  return {
+    allowed: false,
+    state: 'changed',
+    reason: `trust: ${path} was pinned as ${status.pinned_sha256} but now hashes ${status.sha256} — re-pin it explicitly if this change is intended (scion trust pin)`,
+  };
+}
+
+export function reset() {
+  const db = getDb();
+  ensureTable(db);
+  db.prepare('DELETE FROM trust_pins').run();
+}