futura-scion 0.2.8 → 0.3.0

package/README.md

@@ -903,6 +903,66 @@ machinery:
   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.
+
+- **Swarm auto-decomposition** (`src/kernel/auto-decompose.js`): a task
+  enqueued with `kind: 'decompose', payload: { large: true }` opens a
+  delegation run under a manager template and enqueues its declared
+  `subtasks` (plain objectives or `{ text, file }` targets) as child tasks —
+  chained sequentially by default, independent on request. Every child's
+  gate verdict ROLLS UP to its delegation node: accepted children advance
+  the tree; gate-failed or escalated children reject it. Fire-and-forget
+  parents complete on enqueue; awaiting parents escalate with the run id
+  so the reviewer reads the tree (`scion decompose tree <run>`). Verified
+  end-to-end: two file-targeted children patched two files through real
+  `node --check` oracles and rolled up `accepted, accepted`.
+
+- **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

@@ -785,6 +785,50 @@ switch (cmd || '') {
     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.8",
+  "version": "0.3.0",
   "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

@@ -29,6 +29,8 @@ export const DEFAULTS = Object.freeze({
   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/auto-decompose.js

@@ -0,0 +1,172 @@
+/**
+ * kernel/auto-decompose.js — SWARM AUTO-DECOMPOSITION (EvoX Genesis
+ * lineage, wired into runSwarm).
+ *
+ * The gap: decompose.js provides the delegation spine, but nothing AUTOMATIC
+ * routed large objectives into it. Here the swarm itself gains the Genesis
+ * behavior: a task flagged `large: true` (explicit, never inferred — the
+ * doctrine demands declared knobs) opens a delegation run under a MANAGER
+ * template; the decomposition plan (declared `subtasks` in the payload —
+ * the plan is data) enqueues CHILD TASKS on the same queue; every child's
+ * gate verdict ROLLS UP to its delegation node; the parent task completes
+ * only when all children are accepted.
+ *
+ * Rollup is the acceptance machinery: a child that gate-fails or escalates
+ * marks its node rejected, and the parent — visible to the reviewer through
+ * the delegation tree — carries the failure upward instead of completing.
+ * Transient agents, persistent world, only accepted results advance.
+ *
+ *   maybeAutoDecompose(task, opts)   → { run, parent, children } | null
+ *   rollupChild(nodeId, childResult) → { run, allAccepted, accepted, total }
+ *   runDecompositionTask(task, opts) → the swarm's handler for kind 'decompose'
+ *
+ * @module kernel/auto-decompose
+ */
+
+'use strict';
+
+import * as queue from './queue.js';
+import * as decompose from './decompose.js';
+import { getDb } from '../brain/db.js';
+import { journal as trailJournal } from './trail.js';
+import { get as getConfig } from '../config.js';
+
+/** The manager template used when a task doesn't name one (shipped default). */
+export function managerTemplateFor(task) {
+  return task?.payload?.manager_template
+    ?? (() => { try { return getConfig()?.decomposition?.manager_template; } catch { return undefined; } })()
+    ?? 'constructor';
+}
+
+function rowOf(nodeId) {
+  return getDb().prepare('SELECT * FROM delegations WHERE node_id = ?').get(nodeId);
+}
+
+function flatten(tree) {
+  const out = [];
+  const walk = (n) => { out.push(n); for (const c of n.children) walk(c); };
+  for (const r of tree.roots) walk(r);
+  return out;
+}
+
+/**
+ * Open a delegation run for a large task and enqueue its children.
+ * The decomposition plan comes from the task payload: `subtasks: [objective,
+ * ...]` (declared by the caller/enqueuer — the plan is data). Children
+ * enqueue onto the SAME queue (the swarm's existing workers drain them)
+ * with `delegation_node` stamped into their payloads for rollup.
+ *
+ * @returns {{ run, parent, children: Array<{ node, task }>} | null}
+ *   null when the task is not flagged large.
+ */
+export function maybeAutoDecompose(task, opts = {}) {
+  if (!task?.payload?.large) return null; // explicit flag only — never inferred
+  const managerTemplate = opts.managerTemplate ?? managerTemplateFor(task);
+  const subtasks = Array.isArray(task.payload.subtasks) && task.payload.subtasks.length > 0
+    ? task.payload.subtasks
+    : [String(task.payload.text ?? task.id)]; // single-leaf fallback: the objective itself
+
+  const root = decompose.decompose({
+    text: String(task.payload.text ?? task.id),
+    rootTemplate: managerTemplate,
+    repo: task.payload.repo ?? process.cwd(),
+  });
+
+  const children = [];
+  let prevTaskId = null;
+  for (const sub of subtasks) {
+    // A subtask is either a plain string objective or a declared object
+    // { text, file? } — a file-targeted child lets the analyzer rung derive
+    // a concrete patch; a text-only child researches and escalates.
+    const objective = typeof sub === 'string' ? { text: sub } : sub;
+    const node = decompose.delegate(root, opts.childTemplate ?? 'verifier', String(objective.text), {
+      repo: task.payload.repo ?? process.cwd(),
+      // Children work the PRIMARY repo — foreign writes stay root-only.
+    });
+    const t = queue.enqueue({
+      kind: task.payload.child_kind ?? 'fix',
+      payload: {
+        text: objective.text,
+        ...(objective.file ? { file: objective.file } : {}),
+        // File-targeted children get the analyzer's fresh-truth path; the
+        // earned-research rung would burn web budget on a subtask the tree
+        // already scopes. Text-only children keep research (opt-out is the
+        // operator's call, declared per task via payload.child_research).
+        ...(objective.file && task.payload.child_research !== true ? { research: false } : {}),
+        delegation_node: node.id,
+        delegation_run: root.id,
+        parent_task: task.id,
+      },
+      // Children chain sequentially by default (Genesis: writes to one repo
+      // are a manager's job, one at a time); `sequential: false` trusts the
+      // caller's declaration of independent subtasks.
+      ...(prevTaskId && task.payload.sequential !== false ? { depends_on: [prevTaskId] } : {}),
+      ...(task.payload.child_capabilities ? { capabilities: task.payload.child_capabilities } : {}),
+    });
+    children.push({ node, task: t });
+    prevTaskId = t.id;
+  }
+  trailJournal('autodecompose.opened', {
+    task: task.id, run: root.id, manager: managerTemplate,
+    children: children.length, sequential: task.payload.sequential !== false,
+  });
+  return { run: root.id, parent: root, children };
+}
+
+/**
+ * Roll a child's terminal verdict up to its delegation node.
+ * @param {string} nodeId — the child's delegation_node
+ * @param {{ ok: boolean, rung?: string, error?: string }} childResult
+ * @returns {{ run, allAccepted: boolean, accepted: number, total: number }}
+ */
+export function rollupChild(nodeId, childResult) {
+  const row = rowOf(nodeId);
+  if (!row) throw new Error(`auto-decompose.rollup: unknown delegation node ${JSON.stringify(nodeId)}`);
+  const accepted = childResult?.ok === true;
+  decompose.completeDelegation(nodeId, {
+    ok: accepted,
+    ...(childResult?.error ? { error: String(childResult.error).slice(0, 300) } : {}),
+    ...(childResult?.rung ? { rung: childResult.rung } : {}),
+  });
+  const tree = decompose.delegationTree(row.task_id);
+  const nodes = flatten(tree);
+  const childNodes = nodes.filter(n => n.status !== 'root');
+  const acceptedCount = childNodes.filter(n => n.status === 'accepted').length;
+  const allAccepted = childNodes.length > 0 && acceptedCount === childNodes.length;
+  trailJournal('autodecompose.rollup', { node: nodeId, ok: accepted, accepted: acceptedCount, total: childNodes.length, allAccepted });
+  return { run: row.task_id, allAccepted, accepted: acceptedCount, total: childNodes.length };
+}
+
+/** Whether every child of a run is terminal (accepted/rejected/closed). */
+export function runComplete(runId) {
+  const nodes = flatten(decompose.delegationTree(runId)).filter(n => n.status !== 'root');
+  return nodes.length > 0 && nodes.every(n => n.status !== 'pending');
+}
+
+/**
+ * The swarm's handler for a `decompose` task: open the run, enqueue
+ * children, and park THIS task on the children's completion — the parent
+ * task's own lifecycle closes when the last child rolls up. Implemented as:
+ * enqueue children with depends_on the parent is released by; the parent
+ * fails-soft as 'awaiting-children' (an escalation-shaped verdict so the
+ * review lane can see the tree) OR, when opts.awaitParent is false, the
+ * parent completes immediately after enqueueing (fire-and-forget mode).
+ */
+export async function runDecompositionTask(task, opts = {}) {
+  const opened = maybeAutoDecompose(task, opts);
+  if (!opened) {
+    // Flagged decompose but not large: loud misconfiguration.
+    throw new Error(`auto-decompose: task ${task.id} has kind 'decompose' but payload.large is not set — the trigger is explicit, never inferred`);
+  }
+  // awaitParent is the TASK's declaration first (payload.awaitParent), with
+  // the caller's opts as the operator override. Fire-and-forget: the parent
+  // completes when the children are enqueued — the delegation tree carries
+  // the outcomes, and the reviewer reads it (scion decompose tree).
+  const awaitParent = task.payload?.awaitParent ?? opts.awaitParent ?? true;
+  if (awaitParent === false) {
+    return { ok: true, rung: 'decompose', decision: { rung: 'decompose', candidate: { description: `delegated ${opened.children.length} subtask(s)`, run: opened.run } } };
+  }
+  // Default: the parent waits — fail-soft with the run visible in the tree.
+  const failResult = queue.fail(task.id, `awaiting children of run ${opened.run} (see: scion decompose tree ${opened.run})`, { escalate: true });
+  return { ok: false, escalated: true, rung: 'decompose', awaitingRun: opened.run, ...failResult };
+}

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