futura-scion 0.2.7 → 0.2.9

package/README.md

@@ -858,6 +858,99 @@ 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.
+
+### The recursive software world — EvoX Genesis adoption organs (v0.2.9)
+
+From studying EvoX Genesis (`EMI-Group/genesis`, the recursive software-
+evolution system), eight patterns were adopted — the same "transient agents,
+persistent world" doctrine FS already holds, taken further:
+
+- **Recursive decomposition** (`src/kernel/decompose.js`, `scion decompose`):
+  large objectives become a delegation tree — managers decompose, executors
+  implement, read-only investigators recurse. Depth is bounded
+  (`decomposition.max_depth`, default 5); a child may only spawn templates
+  its parent declares in `spawnable_agents` — the spawn graph IS authority.
+
+- **Foreign-repo write authority**: read-only access to any repo is
+  unrestricted; WRITABLE access to a non-primary repo is ROOT-ONLY (depth 0)
+  and SERIALIZED (one open writable delegation per repo — parallel writes
+  create merge conflicts the spawner cannot control). Violations fail loud.
+
+- **Skill distillation** (`distillSkill`, wired to verified outcomes): a
+  gate-verified task is distilled into a durable SKILL.md procedure pack —
+  the approach plus the oracle commands that proved it. Idempotent: the
+  same problem shape updates its skill in place.
+
+- **Executable skills** (`src/mind/skill-exec.js`): skills may declare
+  `parameters:` frontmatter and a bash body with `{{param}}` placeholders.
+  Missing params and unfilled holes refuse loud; execution crosses the
+  Gate's blocklist rails — a skill that executes is a tool.
+
+- **Context contracts** (`src/mind/contracts.js`): every directory may
+  carry a `CONTEXT.md` (Genesis-compatible) declaring its intent; tasks
+  targeting a file inherit the chain root→node at THINK time
+  ("current state, not history"). Containment is enforced — a contract
+  walk never escapes the tree.
+
+- **Security-leveled commands** (`src/kernel/levels.js`): level 1
+  read-only (runs without ceremony), level 2 attention (reviewable state
+  change — unclassified commands are NEVER trusted), level 3 side-effect
+  (irreversible; the Gate's blocklist floor). Worst class wins.
+
+- **The evolution DAG** (`scion history`, `src/mind/phylogeny.js`):
+  accepted verdicts form a phylogenetic tree — same signature reinforces
+  its node; a new problem shape ≥ 0.5 Jaccard-similar to an accepted
+  ancestor becomes its descendant. The codebase's evolution is navigable.
+
+- **Operational hygiene** (`src/kernel/ops.js`, `scion ops`): per-task
+  scratch dirs reclaimed EVENT-DRIVEN at terminal status (containment-
+  guarded), and peak/off-peak concurrency windows (`ops.peak_windows`)
+  scale the swarm down during shared-machine hours.
+
 ### 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,157 @@ 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 'decompose': {
+    // Recursive decomposition (Genesis lineage):
+    //   scion decompose open <templateId> "<objective>" [--repo path]
+    //   scion decompose tree <runId>    the delegation tree
+    const dc = await import('../src/kernel/decompose.js');
+    const sub = arg;
+    if (sub === 'open') {
+      const templateId = restArgs[0];
+      const objective = restArgs.slice(1).join(' ');
+      if (!templateId || !objective) { console.error('usage: scion decompose open <templateId> "<objective>" [--repo path]'); process.exitCode = 2; break; }
+      const repo = restArgs.find(a => a.startsWith('--repo='))?.split('=')[1];
+      const root = dc.decompose({ text: objective, rootTemplate: templateId, repo });
+      console.log(JSON.stringify({ ok: true, run: root.id, template: templateId, repo: repo ?? null }, null, 2));
+      break;
+    }
+    if (sub === 'tree') {
+      if (!restArgs[0]) { console.error('usage: scion decompose tree <runId>'); process.exitCode = 2; break; }
+      const t = dc.delegationTree(restArgs[0]);
+      const render = (n, d) => {
+        console.log(`${'  '.repeat(d)}• [${n.template_id}] ${String(n.objective || n.task_id).slice(0, 70)}  (${n.status})`);
+        for (const c of n.children) render(c, d + 1);
+      };
+      for (const r0 of t.roots) render(r0, 0);
+      console.log(`— ${t.count} node(s)`);
+      break;
+    }
+    console.error('usage: scion decompose [open|tree]');
+    process.exitCode = 2;
+    break;
+  }
+  case 'history': {
+    // The evolution DAG (phylogeny): accepted verdicts as a tree.
+    const ph = await import('../src/mind/phylogeny.js');
+    console.log(ph.renderEvolution());
+    break;
+  }
+  case 'ops': {
+    // Operational hygiene status: scratch dirs + peak windows.
+    const ops = await import('../src/kernel/ops.js');
+    const st = ops.opsStatus();
+    console.log(`task scratch dirs: ${st.task_dirs} (${st.root})`);
+    console.log(`in peak window: ${ops.inPeak()}`);
+    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,12 +11,8 @@ ladder:
   min_insight_confidence: 0.55  # reasoner rung admission floor
 
 llm:
-  daily_tokens: 500
+  daily_tokens: 0               # 0 = LLM rung off (zero-LLM doctrine)
 
-  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.7",
+  "version": "0.2.9",
   "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,9 @@ 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
+  decomposition: { max_depth: 5 },   // recursive decomposition depth cap (Genesis lineage) — kernel/decompose.js
+  ops: { peak_windows: [], peak_concurrency: null },   // peak windows ("HH:MM-HH:MM" list) scale swarm concurrency down (Genesis PeakHours lineage)
   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/kernel/decompose.js

@@ -0,0 +1,214 @@
+/**
+ * kernel/decompose.js — RECURSIVE DECOMPOSITION + FOREIGN-REPO WRITE
+ * AUTHORITY (EvoX Genesis lineage, rebuilt on the kernel's own rails).
+ *
+ * Genesis's insight: large objectives are not one queue task — they are a
+ * RECURSIVE hierarchy. A manager decomposes; executors implement at the
+ * leaves; investigators analyze read-only and may recurse. Every agent is
+ * finite-lived; only accepted work advances the world. FS already has the
+ * acceptance machinery (the Gate) and the role machinery (kernel/roles);
+ * what it lacked is the DELEGATION SPINE.
+ *
+ * Delegation contracts, enforced by THIS module (not by any agent's
+ * judgment — there is no agent judgment here):
+ *
+ *   - depth is bounded (config decomposition.max_depth, default 5);
+ *   - a child may only spawn templates its parent's template declares in
+ *     spawnable_agents (the spawn graph from mind/agent-templates.js);
+ *   - FOREIGN-REPO WRITE AUTHORITY: read-only access to any repo is
+ *     unrestricted; WRITABLE access to a repo that is not the task's
+ *     primary repo is ROOT-ONLY (depth 0) and SERIALIZED (one at a time —
+ *     parallel writes to a foreign repo create merge conflicts the
+ *     spawner cannot control). Violations fail loud at delegate() time.
+ *   - every delegation and every terminal child outcome journals.
+ *
+ *   decompose(taskId, { text, rootTemplate, repo }) → the recursion tree
+ *   delegate(parent, templateId, objective, opts)    → spawn a child task
+ *   completeDelegation(taskId, outcome)              → record + roll up
+ *   delegationTree(taskId)                           → inspect a run
+ *
+ * @module kernel/decompose
+ */
+
+'use strict';
+
+import { getDb } from '../brain/db.js';
+import * as roles from './roles.js';
+import { getTemplate } from '../mind/agent-templates.js';
+import { journal as trailJournal } from './trail.js';
+import { get as getConfig } from '../config.js';
+
+function ensureTables(db) {
+  db.exec(`CREATE TABLE IF NOT EXISTS delegations (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    node_id TEXT NOT NULL UNIQUE,
+    task_id TEXT NOT NULL,
+    parent_id TEXT,
+    template_id TEXT NOT NULL,
+    objective TEXT NOT NULL,
+    depth INTEGER NOT NULL,
+    repo TEXT,
+    write INTEGER NOT NULL DEFAULT 0,
+    status TEXT NOT NULL DEFAULT 'pending',
+    outcome TEXT,
+    created_at TEXT NOT NULL,
+    closed_at TEXT
+  )`);
+  db.prepare('CREATE INDEX IF NOT EXISTS idx_delegations_task ON delegations (task_id)').run();
+}
+
+/** Max recursion depth — declared, loud, never vibes. */
+function maxDepth() {
+  try {
+    const d = getConfig()?.decomposition?.max_depth;
+    if (d !== undefined) return Math.max(1, Math.floor(Number(d)));
+  } catch { /* config not loaded (tests) — shipped default */ }
+  return 5;
+}
+
+function childId(parentId) {
+  // Deterministic, finite, sortable: depth is embedded in the id.
+  return `${parentId}.${Date.now().toString(36)}${Math.floor(Math.random() * 1e4).toString(36)}`;
+}
+
+/* ------------------------------------------------------------------ *
+ * Delegation — the ONLY way a decomposition spawns.
+ * ------------------------------------------------------------------ */
+
+/**
+ * Spawn a child task under a parent's authority.
+ * @param {object} parent — the delegating node: { id, depth, template_id, repo, root? }
+ * @param {string} templateId — the child's agent-template id (must be in the
+ *   parent's spawnable_agents, or the parent must BE the root request)
+ * @param {string} objective — what the child must accomplish
+ * @param {{ repo?: string, write?: boolean }} [opts] — repo targets the work;
+ *   write:true requests WRITABLE access (subject to foreign-repo authority)
+ * @returns {{ id, template_id, depth, repo, write }}
+ */
+export function delegate(parent, templateId, objective, opts = {}) {
+  if (!parent?.id || !Number.isFinite(parent.depth)) {
+    throw new Error('decompose.delegate: parent must be a delegation node { id, depth, template_id, repo }');
+  }
+  if (typeof objective !== 'string' || !objective.trim()) {
+    throw new Error('decompose.delegate: objective must be a non-empty string');
+  }
+  const at = maxDepth();
+  if (parent.depth + 1 > at) {
+    throw new Error(`decompose.delegate: depth ${parent.depth + 1} exceeds the declared max_depth ${at} — decompose smaller, or raise decomposition.max_depth`);
+  }
+
+  // Spawn-graph authority: the parent template must declare the child.
+  assertSpawnAllowed(parent.template_id, templateId);
+
+  // Foreign-repo write authority: root-only + serialized.
+  const repo = opts.repo ?? parent.repo ?? null;
+  const write = opts.write === true;
+  const db = getDb();
+  ensureTables(db);
+  let holdsWriteLock = false;
+  if (write && repo && repo !== (parent.root?.repo ?? parent.repo)) {
+    if (parent.depth !== 0) {
+      throw new Error(`decompose.delegate: WRITABLE access to foreign repo ${JSON.stringify(repo)} is ROOT-ONLY — node ${parent.id} is at depth ${parent.depth}; nested agents report the need upward (Genesis authority model)`);
+    }
+    const wlockKey = `wlock:${repo}`;
+    if (_writeLocks.get(wlockKey)) {
+      throw new Error(`decompose.delegate: foreign repo ${JSON.stringify(repo)} already has an open writable delegation (${_writeLocks.get(wlockKey)}) — writes to a foreign repo are SERIALIZED; delegate the next one after this completes`);
+    }
+    holdsWriteLock = true;
+  }
+
+  const id = childId(parent.id);
+  const now = new Date().toISOString();
+  db.prepare(
+    `INSERT INTO delegations (node_id, task_id, parent_id, template_id, objective, depth, repo, write, status, created_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, 'pending', ?)`
+  ).run(id, parent.root?.id ?? parent.id, parent.id, templateId, objective.slice(0, 2000), parent.depth + 1, repo, write ? 1 : 0, now);
+  trailJournal('decompose.delegated', { id, parent: parent.id, template: templateId, depth: parent.depth + 1, repo, write });
+  if (holdsWriteLock) _writeLocks.set(`wlock:${repo}`, id);
+  return { id, parent_id: parent.id, template_id: templateId, depth: parent.depth + 1, repo, write };
+}
+
+// Write-lock registry (in-process; cross-process serialization rides the
+// queue's own lease — a foreign-repo writer is an ordinary bounded task).
+const _writeLocks = new Map();
+
+/**
+ * The spawn-graph authority check — the runner calls this BEFORE executing
+ * a delegated child. Fail loud, never guess.
+ */
+export function assertSpawnAllowed(parentTemplateId, childTemplateId) {
+  const parent = getTemplate(parentTemplateId);
+  if (!parent) throw new Error(`decompose: unknown parent template ${JSON.stringify(parentTemplateId)}`);
+  const allowed = parent.spawnable_agents ?? [];
+  if (!allowed.includes(childTemplateId)) {
+    throw new Error(`decompose: template ${JSON.stringify(parentTemplateId)} does not declare ${JSON.stringify(childTemplateId)} in spawnable_agents — the spawn graph is authority, extend the parent's declaration to delegate deeper`);
+  }
+}
+
+/* ------------------------------------------------------------------ *
+ * Completion — outcomes roll up; the write lock releases.
+ * ------------------------------------------------------------------ */
+
+export function completeDelegation(id, outcome = {}) {
+  const db = getDb();
+  ensureTables(db);
+  const row = db.prepare('SELECT * FROM delegations WHERE node_id = ?').get(id);
+  if (!row) throw new Error(`decompose.complete: unknown delegation ${JSON.stringify(id)}`);
+  const status = outcome.ok === true ? 'accepted' : outcome.ok === false ? 'rejected' : 'closed';
+  db.prepare(
+    `UPDATE delegations SET status = ?, outcome = ?, closed_at = ? WHERE node_id = ?`
+  ).run(status, JSON.stringify(outcome ?? {}), new Date().toISOString(), id);
+  // Release the foreign write lock only if THIS node held it.
+  if (row.write === 1 && row.repo) _writeLocks.delete(`wlock:${row.repo}`);
+  trailJournal('decompose.completed', { id, status, depth: row.depth });
+  return { id, status };
+}
+
+/* ------------------------------------------------------------------ *
+ * Decompose — the root entry: one objective → a delegation tree.
+ * The MANAGER template drives recursion; this module records and gates.
+ * ------------------------------------------------------------------ */
+
+/**
+ * Open a decomposition run: validate the root template, record the root
+ * node, and return the handle the runner (or a template implementation)
+ * recurses through.
+ * @param {{ text, rootTemplate, repo? }} req
+ */
+export function decompose(req) {
+  const text = String(req?.text ?? '').trim();
+  if (!text) throw new Error('decompose.decompose: req.text is required (the objective)');
+  if (!req.rootTemplate) throw new Error('decompose.decompose: req.rootTemplate is required (the manager template id)');
+  const db = getDb();
+  ensureTables(db);
+  const id = `d${Date.now().toString(36)}${Math.floor(Math.random() * 1e4).toString(36)}`;
+  db.prepare(
+    `INSERT INTO delegations (node_id, task_id, parent_id, template_id, objective, depth, repo, write, status, created_at)
+     VALUES (?, ?, NULL, ?, ?, 0, ?, 0, 'root', ?)`
+  ).run(id, id, req.rootTemplate, text.slice(0, 2000), req.repo ?? null, new Date().toISOString());
+  const root = { id, root: { id, repo: req.repo ?? null }, parent_id: null, template_id: req.rootTemplate, depth: 0, repo: req.repo ?? null };
+  trailJournal('decompose.opened', { id, template: req.rootTemplate, repo: req.repo ?? null });
+  return root;
+}
+
+/** The full delegation tree of a run (audit + the dashboard view). */
+export function delegationTree(taskId) {
+  const db = getDb();
+  ensureTables(db);
+  const rows = db.prepare('SELECT * FROM delegations WHERE task_id = ? ORDER BY id').all(taskId);
+  const byId = new Map(rows.map(r => [r.node_id, { ...r, write: r.write === 1, outcome: r.outcome ? JSON.parse(r.outcome) : null, children: [] }]));
+  const roots = [];
+  for (const node of byId.values()) {
+    const parent = node.parent_id ? byId.get(node.parent_id) : null;
+    if (parent) parent.children.push(node);
+    else roots.push(node);
+  }
+  return { task_id: taskId, roots, count: rows.length };
+}
+
+export function reset() {
+  const db = getDb();
+  ensureTables(db);
+  db.prepare('DELETE FROM delegations').run();
+  _writeLocks.clear();
+}

package/src/kernel/levels.js

@@ -0,0 +1,105 @@
+/**
+ * kernel/levels.js — SECURITY-LEVELED COMMANDS (EvoX Genesis CommandShell
+ * lineage).
+ *
+ * FS's safety posture was binary: read-only vs mutating. Genesis's command
+ * shell carries three levels with distinct UX semantics, and the distinction
+ * is genuinely useful — it lets a reviewer see AT A GLANCE which actions
+ * need eyes and which need a signature:
+ *
+ *   level 1  read-only   — observes; runs without ceremony (ls, git status,
+ *                          grep, cat, node --check)
+ *   level 2  attention   — changes state the human cares about but that is
+ *                          reviewable/reversible (npm install, file writes);
+ *                          the senior-review lane wants these NAMED
+ *   level 3  side-effect — destructive or irreversible (rm -rf, force push,
+ *                          drop table, mkfs); approval-gated, fail-closed
+ *
+ * Classification is deterministic: pattern tables, shape-based, no model.
+ * The immovable floor is level 3's blocklist — identical to the Gate's.
+ * The most dangerous class wins when a command matches several.
+ *
+ *   classifyCommand(cmd) → { level: 1|2|3, reason }
+ *   levelOfSteps(steps)  → aggregate for a workflow/plan
+ *
+ * @module kernel/levels
+ */
+
+'use strict';
+
+import { redact } from './safety.js';
+
+/** Level 3 — irreversible. The Gate's blocklist, restated here as the floor. */
+const L3_PATTERNS = [
+  ['recursive-delete', /\brm\s+(-[a-z]*r[a-z]*f|-[a-z]*f[a-z]*r)\b/i],
+  ['delete-root', /\b(del|rmdir)\s+\/[sq]\b/i],
+  ['force-push', /\bgit\s+push\s+(--force|-f)\b/i],
+  ['hard-reset', /\bgit\s+reset\s+--hard\b/i],
+  ['drop-table', /\bdrop\s+table\b/i],
+  ['disk-destroy', /\b(mkfs|format\s+[a-z]:|diskpart)\b/i],
+];
+
+/** Level 2 — state-changing but reviewable. */
+const L2_PATTERNS = [
+  ['pkg-mutate', /\b(npm|yarn|pnpm)\s+(install|i|ci|uninstall|update|link)\b/],
+  ['pkg-install-alt', /\b(pip3?\s+install|cargo\s+(install|add)|apt(-get)?\s+install|brew\s+install|gem\s+install)\b/],
+  ['git-write', /\bgit\s+(add|commit|push|pull|merge|rebase|checkout|restore|clean|cherry-pick)\b/],
+  ['file-delete', /\b(rm|rmdir|unlink|del)\b/i],
+  ['file-move', /\b(mv|move|rename)\b/i],
+  ['db-write', /\b(DROP|DELETE\s+FROM|INSERT\s+INTO|UPDATE\s+\w+\s+SET)\b/],
+];
+
+/** Level 1 — observation. Explicit allowlist; everything not matching any
+ *  table is level 2 by default (UNSAFE default: unclassified ≠ trusted). */
+const L1_PATTERNS = [
+  /\bgit\s+(status|log|diff|show|branch|remote|blame|shortlog|describe|rev-parse)\b/,
+  /\b(ls|dir|cat|head|tail|wc|find|grep|rg|tree|stat|file|which|where|whoami|pwd|env)\b/,
+  /\b(node|python3?|go|cargo|dotnet|java|mvn|gradle)\s+(-[a-zA-Z-]+\s+)*--?(check|version|--help|-h)\b/,
+  /\bnode\s+--check\b/,
+  /\b(npm|yarn|pnpm|cargo|go|dotnet|mvn|gradle)\s+(test|run\s+test|check|lint|vet|audit|outdated|list)\b/,
+  /\bnpm\s+view\b/,
+  /\bcurl\s+(-[a-zA-Z-]+\s+)*https?:\/\//, // GET-shaped curl (no -X POST/-d)
+  /\bwget\b/,
+  /\bscion\s+[a-z-]+\b/,
+];
+
+/**
+ * Classify one command string.
+ * @param {string} cmd
+ * @returns {{ level: 1|2|3, reason: string|null }}
+ */
+export function classifyCommand(cmd) {
+  const text = String(cmd || '');
+  for (const [name, re] of L3_PATTERNS) {
+    if (re.test(text)) return { level: 3, reason: name };
+  }
+  for (const [name, re] of L2_PATTERNS) {
+    if (re.test(text)) return { level: 2, reason: name };
+  }
+  for (const re of L1_PATTERNS) {
+    if (re.test(text)) return { level: 1, reason: null };
+  }
+  return { level: 2, reason: 'unclassified' }; // unclassified is NEVER trusted
+}
+
+/** Aggregate a step list (workflow manifests, plans, skill batches). */
+export function levelOfSteps(steps) {
+  let worst = 1, reason = null;
+  for (const s of steps) {
+    const cmd = typeof s === 'string' ? s : (s?.cmd ?? s?.command ?? '');
+    const { level, reason: r } = classifyCommand(cmd);
+    if (level > worst) { worst = level; reason = r; }
+  }
+  return { level: worst, reason };
+}
+
+/** Human-readable rendering for review surfaces. */
+export function levelLabel(level) {
+  return level === 1 ? 'read-only' : level === 2 ? 'attention' : 'side-effect';
+}
+
+/** A review-surface row: redacted command + its level. */
+export function reviewRow(cmd) {
+  const { level, reason } = classifyCommand(cmd);
+  return { command: redact(String(cmd)).text, level, label: levelLabel(level), reason };
+}