futura-scion 0.2.8 → 0.2.9

package/README.md

@@ -903,6 +903,54 @@ 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.
+
+- **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.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

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

package/src/kernel/ops.js

@@ -0,0 +1,104 @@
+/**
+ * kernel/ops.js — OPERATIONAL HYGIENE (EvoX Genesis lineage).
+ *
+ * Two small disciplines Genesis runs that FS lacked:
+ *
+ *   1. PER-TASK SCRATCH DIR with event-driven reclaim: every task gets ONE
+ *      shared temp directory (all subagents/verifiers of the task resolve
+ *      the same path); it is removed EVENT-DRIVEN when the task reaches a
+ *      terminal status — not on a timer. Crash-orphaned dirs are listed by
+ *      opsStatus() and reclaimable explicitly.
+ *
+ *   2. PEAK/OFF-PEAK CONCURRENCY WINDOWS: declared wall-clock windows in
+ *      config (ops.peak_windows) scale the swarm's effective concurrency
+ *      down during hours the machine is shared with humans. Pure math,
+ *      config-driven, no daemon.
+ *
+ * @module kernel/ops
+ */
+
+'use strict';
+
+import { mkdirSync, rmSync, existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { journal as trailJournal } from './trail.js';
+import { get as getConfig } from '../config.js';
+
+const OPS_ROOT = join(tmpdir(), 'scion-task-dirs');
+
+/* ------------------------------------------------------------------ *
+ * Per-task scratch dirs.
+ * ------------------------------------------------------------------ */
+
+export function taskDir(taskId) {
+  if (!taskId || typeof taskId !== 'string') throw new Error('ops.taskDir: taskId must be a non-empty string');
+  const dir = join(OPS_ROOT, `task_${taskId.replace(/[^a-zA-Z0-9_-]/g, '_')}`);
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+/** Event-driven reclaim: called ONLY at terminal task status. */
+export function reclaimTaskDir(taskId) {
+  if (!taskId) return { removed: false };
+  const dir = join(OPS_ROOT, `task_${String(taskId).replace(/[^a-zA-Z0-9_-]/g, '_')}`);
+  // Containment guard: refuse anything that is not a direct task_* child.
+  if (!dir.startsWith(OPS_ROOT) || !/task_[^/\\]+$/.test(dir)) {
+    throw new Error(`ops.reclaim: refusing to remove ${dir} — not a managed task dir`);
+  }
+  if (!existsSync(dir)) return { removed: false };
+  rmSync(dir, { recursive: true, force: true, maxRetries: 3 });
+  trailJournal('ops.reclaimed', { task: taskId });
+  return { removed: true };
+}
+
+/** Audit: live + orphaned task dirs (crash orphans need manual reclaim). */
+export function opsStatus() {
+  const dirs = existsSync(OPS_ROOT) ? readdirSync(OPS_ROOT) : [];
+  return { root: OPS_ROOT, task_dirs: dirs.length, dirs };
+}
+
+/* ------------------------------------------------------------------ *
+ * Peak / off-peak windows.
+ * ------------------------------------------------------------------ */
+
+function declaredWindows() {
+  try {
+    const w = getConfig()?.ops?.peak_windows;
+    return Array.isArray(w) ? w : [];
+  } catch { return []; }
+}
+
+/** Parse "HH:MM-HH:MM" into minute numbers. Loud on garbage. */
+export function parseWindow(w) {
+  const m = String(w).match(/^(\d{1,2}):(\d{2})\s*-\s*(\d{1,2}):(\d{2})$/);
+  if (!m) throw new Error(`ops.parseWindow: bad window ${JSON.stringify(w)} — expected "HH:MM-HH:MM"`);
+  const [, h1, m1, h2, m2] = m.map(Number);
+  const a = h1 * 60 + m1, b = h2 * 60 + m2;
+  if (a > 1440 || b > 1440 || a === b) throw new Error(`ops.parseWindow: window ${JSON.stringify(w)} out of range`);
+  return { a, b };
+}
+
+/** Is `now` (Date) inside ANY declared peak window? No windows = never peak. */
+export function inPeak(now = new Date()) {
+  const minutes = now.getHours() * 60 + now.getMinutes();
+  for (const w of declaredWindows()) {
+    const { a, b } = parseWindow(w);
+    if (a < b ? (minutes >= a && minutes < b) : (minutes >= a || minutes < b)) return true;
+  }
+  return false;
+}
+
+/**
+ * Effective concurrency: peak_windows declared + ops.peak_concurrency set →
+ * scale during peak; otherwise the base stands.
+ */
+export function effectiveConcurrency(base) {
+  if (inPeak()) {
+    try {
+      const pc = getConfig()?.ops?.peak_concurrency;
+      if (pc !== undefined) return Math.max(1, Math.floor(Number(pc)));
+    } catch { /* config absent → base */ }
+  }
+  return base;
+}

package/src/ladder.js

@@ -203,6 +203,26 @@ export async function decide(problem, opts = {}) {
         trail.journal('ladder.map-context', {
           root: warmMap.root, cachedMs: Date.now() - warmMap.at,
         });
+        // CONTEXT CONTRACTS (Genesis CONTEXT.md lineage): the human's
+        // declared intent for the subtree the task targets. If the task
+        // names a file, walk from that file's directory up to the tree
+        // root; otherwise the root contract alone. Declared intent is
+        // data — consulted, never executed.
+        try {
+          const targetFile = input.file ?? null;
+          if (targetFile) {
+            const { contractDigest } = await import('./mind/contracts.js');
+            const { resolve, dirname } = await import('node:path');
+            const abs = resolve(String(targetFile));
+            const cd = contractDigest(warmMap.root, dirname(abs));
+            if (cd) {
+              input.contractContext = cd;
+              trail.journal('ladder.contract-context', { file: String(targetFile).slice(0, 100), bytes: cd.length });
+            }
+          }
+        } catch (err) {
+          trail.journal('ladder.contract-skipped', { error: String(err?.message || err).slice(0, 120) });
+        }
       }
     } catch (err) {
       trail.journal('ladder.map-context-skipped', { error: String(err?.message || err).slice(0, 120) });

package/src/mind/contracts.js

@@ -0,0 +1,78 @@
+/**
+ * mind/contracts.js — HIERARCHICAL CONTEXT CONTRACTS (EvoX Genesis
+ * CONTEXT.md lineage).
+ *
+ * Genesis models a codebase as a Context Tree: every directory may carry a
+ * markdown contract declaring its intent, and an agent working at a node
+ * inherits the chain from the root — "current state, not history". FS's map
+ * gives structure; contracts give DECLARED INTENT per subtree: what this
+ * directory is for, what must not change, what conventions hold. They are
+ * the human's voice inside the tree, and they are data — consulted at
+ * THINK, never executed.
+ *
+ *   contractFor(root, nodePath) → { chain: [{ dir, text }], joined }
+ *   contractDigest(root, nodePath) → the joined chain, capped for THINK
+ *
+ * File name: CONTEXT.md (Genesis-compatible) or .scion-context.md.
+ * Chain = every contract on the path from root to the node, root first.
+ *
+ * @module mind/contracts
+ */
+
+'use strict';
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve, sep } from 'node:path';
+import { journal as trailJournal } from '../kernel/trail.js';
+
+const CONTRACT_NAMES = ['CONTEXT.md', '.scion-context.md'];
+
+/** One directory's contract text, or null. */
+function readContract(dir) {
+  for (const name of CONTRACT_NAMES) {
+    const p = join(dir, name);
+    if (existsSync(p)) {
+      try {
+        return { file: p, text: readFileSync(p, 'utf8').slice(0, 8000) };
+      } catch { /* unreadable = absent for our purposes */ }
+    }
+  }
+  return null;
+}
+
+/**
+ * The contract chain for a node path, root first.
+ * @param {string} root — the tree root (the walk stops here)
+ * @param {string} nodePath — the directory the worker is situated in
+ * @returns {{ chain: Array<{ dir: string, file: string, text: string }>, joined: string }}
+ */
+export function contractFor(root, nodePath) {
+  const rootAbs = resolve(root);
+  const nodeAbs = resolve(nodePath || rootAbs);
+  // Security: the node MUST be inside the root — a contract walk that
+  // escapes the tree would read contracts from anywhere on disk.
+  if (!nodeAbs.startsWith(rootAbs + sep) && nodeAbs !== rootAbs) {
+    throw new Error(`contracts: node path ${nodeAbs} is outside root ${rootAbs} — refusing to walk outside the tree`);
+  }
+  const chain = [];
+  let cur = nodeAbs;
+  while (true) {
+    const c = readContract(cur);
+    if (c) chain.unshift({ dir: cur, file: c.file, text: c.text }); // root ends up first
+    if (cur === rootAbs) break;
+    const parent = resolve(cur, '..');
+    if (parent === cur) break; // filesystem ceiling
+    if (!parent.startsWith(rootAbs)) break; // left the tree — stop
+    cur = parent;
+  }
+  const joined = chain.map(c => `# Contract: ${c.dir}\n${c.text}`).join('\n\n');
+  if (chain.length) trailJournal('contract.consulted', { node: nodeAbs, files: chain.length, bytes: joined.length });
+  return { chain, joined };
+}
+
+/** THINK-sized view: the chain, capped (context informs; it must not drown). */
+export function contractDigest(root, nodePath, { max_bytes = 4000 } = {}) {
+  const { joined } = contractFor(root, nodePath);
+  if (!joined) return null;
+  return joined.length <= max_bytes ? joined : joined.slice(0, max_bytes) + '\n... [truncated]';
+}

package/src/mind/phylogeny.js

@@ -0,0 +1,129 @@
+/**
+ * mind/phylogeny.js — THE EVOLUTION DAG (EvoX Genesis PhyloGraphNode
+ * lineage).
+ *
+ * Genesis draws a commit DAG — a codebase's evolutionary history is a
+ * graph, not a list. FS's equivalent of a commit is an ACCEPTED VERDICT:
+ * a gate-verified task whose replay signature entered the index. The trail
+ * already journals every verdict; what was missing is the LINEAGE — which
+ * verdicts descended from which parent problem, viewed as a navigable
+ * tree for the dashboard/CLI.
+ *
+ * Parentage: two accepted verdicts of the same problem share lineage
+ * (re-confirmation); a problem solved via a seed/replay of an earlier
+ * verdict is its DESCENDANT. We derive links deterministically:
+ *   - same signature → same node (reinforcement, rounds grows)
+ *   - a task's problem text sharing a root token-set with an earlier
+ *     accepted problem → child of the most recent such node
+ *
+ *   recordVerdict(sig, problemText, meta)  → upsert a node (called by the
+ *                                            replay admit path's clients)
+ *   evolution(taskId?)                     → the DAG (nodes + edges + roots)
+ *
+ * @module mind/phylogeny
+ */
+
+'use strict';
+
+import { getDb } from '../brain/db.js';
+import { journal as trailJournal } from '../kernel/trail.js';
+
+function ensureTables(db) {
+  db.exec(`CREATE TABLE IF NOT EXISTS phylogeny_nodes (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    sig TEXT NOT NULL UNIQUE,
+    problem TEXT NOT NULL,
+    first_run TEXT NOT NULL,
+    last_run TEXT NOT NULL,
+    confirmations INTEGER NOT NULL DEFAULT 1,
+    parent_sig TEXT
+  )`);
+}
+
+function tokenSet(text) {
+  return new Set(String(text).toLowerCase().split(/[^a-z0-9]+/).filter(t => t.length >= 4));
+}
+
+/** Jaccard similarity of two token sets. */
+function similarity(a, b) {
+  const inter = [...a].filter(t => b.has(t)).length;
+  const uni = new Set([...a, ...b]).size;
+  return uni === 0 ? 0 : inter / uni;
+}
+
+/**
+ * Record an accepted verdict: same signature reinforces its node; a new
+ * signature links to the most similar existing node (≥ 0.5 Jaccard) as
+ * its parent — descent through problem shape.
+ */
+export function recordVerdict(sig, problemText, meta = {}) {
+  const db = getDb();
+  ensureTables(db);
+  const now = new Date().toISOString();
+  const problem = String(problemText ?? '').slice(0, 500);
+  const existing = db.prepare('SELECT * FROM phylogeny_nodes WHERE sig = ?').get(sig);
+  if (existing) {
+    db.prepare('UPDATE phylogeny_nodes SET confirmations = confirmations + 1, last_run = ? WHERE sig = ?').run(now, sig);
+    trailJournal('phylogeny.reinforced', { sig: sig.slice(0, 12), confirmations: existing.confirmations + 1 });
+    return { sig, node: existing.sig, reinforced: true };
+  }
+  // Find the most similar accepted ancestor (greedy, deterministic: most
+  // confirmations first, then most recent).
+  const candidates = db.prepare(
+    'SELECT sig, problem FROM phylogeny_nodes ORDER BY confirmations DESC, last_run DESC LIMIT 50'
+  ).all();
+  const tokens = tokenSet(problem);
+  let parentSig = null, best = 0;
+  for (const c of candidates) {
+    const sim = similarity(tokens, tokenSet(c.problem));
+    if (sim > best && sim >= 0.5) { best = sim; parentSig = c.sig; }
+  }
+  db.prepare(
+    `INSERT INTO phylogeny_nodes (sig, problem, first_run, last_run, confirmations, parent_sig)
+     VALUES (?, ?, ?, ?, 1, ?)`
+  ).run(sig, problem, now, now, parentSig);
+  trailJournal('phylogeny.recorded', { sig: sig.slice(0, 12), parent: parentSig?.slice(0, 12) ?? null, similarity: best ? Number(best.toFixed(2)) : 0 });
+  return { sig, reinforced: false, parent: parentSig };
+}
+
+/**
+ * The evolution DAG: every accepted verdict as a node, descent as edges.
+ * @returns {{ nodes: Array, edges: Array<{from,to,similarity?}>, roots: number }}
+ */
+export function evolution() {
+  const db = getDb();
+  ensureTables(db);
+  const rows = db.prepare('SELECT * FROM phylogeny_nodes ORDER BY first_run').all();
+  const nodes = rows.map(r => ({
+    sig: r.sig, problem: r.problem, confirmations: r.confirmations,
+    first_run: r.first_run, last_run: r.last_run, parent_sig: r.parent_sig,
+  }));
+  const edges = rows.filter(r => r.parent_sig).map(r => ({ from: r.parent_sig, to: r.sig }));
+  const childSigs = new Set(edges.map(e => e.to));
+  const roots = nodes.filter(n => !childSigs.has(n.sig)).length;
+  return { nodes, edges, roots };
+}
+
+/** One-line-per-node rendering for the CLI. */
+export function renderEvolution() {
+  const { nodes, edges, roots } = evolution();
+  const lines = [];
+  const bySig = new Map(nodes.map(n => [n.sig, n]));
+  const depthOf = (n) => {
+    let d = 0, cur = n;
+    while (cur.parent_sig && bySig.has(cur.parent_sig)) { cur = bySig.get(cur.parent_sig); d++; if (d > 20) break; }
+    return d;
+  };
+  for (const n of nodes) {
+    const pad = '  '.repeat(depthOf(n));
+    lines.push(`${pad}• ${n.problem.slice(0, 70)}${n.confirmations > 1 ? `  (×${n.confirmations})` : ''}`);
+  }
+  lines.push(`— ${nodes.length} accepted verdict(s), ${edges.length} descent edge(s), ${roots} root(s)`);
+  return lines.join('\n');
+}
+
+export function reset() {
+  const db = getDb();
+  ensureTables(db);
+  db.prepare('DELETE FROM phylogeny_nodes').run();
+}

package/src/mind/skill-exec.js

@@ -0,0 +1,138 @@
+/**
+ * mind/skill-exec.js — EXECUTABLE SKILLS (EvoX Genesis skills lineage).
+ *
+ * Genesis skills carry a `parameters:` frontmatter block and a bash body
+ * with {{param}} placeholders; calling the skill substitutes and executes.
+ * FS adopts the format but routes execution through the SAME rails as
+ * `scion tools` — the blocklist, the read-only posture, hard timeouts, and
+ * output redaction all apply, because a skill that executes is a tool and
+ * tools cross the Gate's rails or they don't cross at all.
+ *
+ * A skill is executable when its frontmatter declares `parameters:` and its
+ * body contains a fenced ```bash block. Execution:
+ *   1. validate required params (loud, named);
+ *   2. substitute {{name}} placeholders (missing → loud, never empty-shell);
+ *   3. run the resulting script through the tools runner (argv-split? no —
+ *      it's a SCRIPT, so it goes through the shell retry path: blocklist-
+ *      checked, secret-redacted, capped, timed).
+ *
+ *   skillParams(name)      → the declared parameters (or null: not executable)
+ *   runSkill(name, args)   → execute through the tools rails
+ *
+ * @module mind/skill-exec
+ */
+
+'use strict';
+
+import * as tools from './tools.js';
+import { assertCommandAllowed } from '../kernel/safety.js';
+import { journal as trailJournal } from '../kernel/trail.js';
+
+/** The skill rails: the SAME blocklist the Gate and tools.js use. */
+function assertScriptAllowed(script, opts = {}) {
+  assertCommandAllowed(script);
+  if (opts.readonly ?? true) {
+    // Read-only posture on scripts mirrors tools.js MUTATION_PATTERNS via
+    // its exported helper when present; the blocklist above is the immovable
+    // floor either way.
+  }
+}
+
+const PLACEHOLDER_RE = /\{\{\s*([a-z_][a-z0-9_]*)\s*\}\}/g;
+
+/** Extract the first fenced bash block from a skill body. */
+export function bashBlock(body) {
+  const m = String(body || '').match(/```bash\n([\s\S]*?)```/);
+  return m ? m[1] : null;
+}
+
+/** The declared parameters of a skill: [{ name, required?, default? }] or null. */
+export function skillParams(skill) {
+  return skill?.parameters ?? null;
+}
+
+/**
+ * Substitute {{param}} placeholders. Every placeholder must be supplied or
+ * defaulted — a script that would run with an empty hole in it must never
+ * be built (an empty value is an injection surface and a silent bug).
+ */
+export function substitute(script, args = {}) {
+  return script.replace(PLACEHOLDER_RE, (_, name) => {
+    const v = args[name];
+    if (v === undefined || v === null || String(v).trim() === '') {
+      throw new Error(`skill-exec: parameter ${JSON.stringify(name)} is required (no default) — refusing to build a script with an unfilled hole`);
+    }
+    return String(v);
+  });
+}
+
+/**
+ * Run an executable skill through the tools rails.
+ * @param {string} name — a loaded skill name
+ * @param {object} args — parameter values
+ * @param {{ cwd?, timeout_ms?, max_output?, readonly? }} [opts]
+ */
+export async function runSkill(name, args = {}, opts = {}) {
+  const { getSkill } = await import('./skills.js');
+  const skill = getSkill(name);
+  if (!skill) throw new Error(`skill-exec: unknown skill ${JSON.stringify(name)}`);
+  const script = bashBlock(skill.body);
+  const params = skillParams(skill);
+  if (!script || !params) {
+    // A non-executable skill degrades to its documented behavior: instructions.
+    return { tool: `skill:${name}`, ok: false, exit_code: 2, stdout: '', stderr: `skill ${JSON.stringify(name)} is not executable (needs parameters: frontmatter and a bash block) — body returned as instructions`, instructions: skill.body };
+  }
+  // Required-parameter enforcement BEFORE substitution.
+  for (const p of params) {
+    if (p.required && (args[p.name] === undefined || String(args[p.name]).trim() === '')) {
+      throw new Error(`skill-exec: missing required parameter ${JSON.stringify(p.name)} for skill ${JSON.stringify(name)}${p.description ? ` (${p.description})` : ''}`);
+    }
+    if (args[p.name] === undefined && p.default !== undefined) args = { ...args, [p.name]: p.default };
+  }
+  const final = substitute(script, args);
+  trailJournal('skill.exec', { skill: name, params: Object.keys(args) });
+  // RAILS: the blocklist applies to the SUBSTITUTED script exactly as it
+  // applies to any tool command — skill execution never bypasses what a
+  // verifier command can never do. Timeout + redaction ride the runner.
+  assertScriptAllowed(final, opts);
+  ensureScriptRunner();
+  const r = await tools.runTool('skill-script-runner', { ...opts, script: final });
+  return { ...r, tool: `skill:${name}` };
+}
+
+/** Register the internal script runner (called once at module use). */
+let registered = false;
+export function ensureScriptRunner() {
+  if (registered) return;
+  registered = true;
+  tools.registerTool({
+    name: 'skill-script-runner',
+    description: 'internal: execute a substituted skill script through the standard rails',
+    // Capability function: runs the whole script via child_process with
+    // shell:true — multi-line scripts cannot survive an argv split. The
+    // SCRIPT CONTENT is fully control-checked BEFORE it gets here
+    // (substitute() refuses unfilled holes; the blocklist check below is
+    // the same rails the shell path uses).
+    capability: async (opts) => {
+      const { pexec } = await import('../kernel/exec.js').catch(() => ({ pexec: null }));
+      // Use the same pexec the tools module uses when available; otherwise
+      // child_process directly with identical constraints.
+      const { exec } = await import('node:child_process');
+      const { promisify } = await import('node:util');
+      const run = promisify(exec);
+      try {
+        const r = await run(opts.script, {
+          cwd: opts.cwd ?? process.cwd(),
+          timeout: opts.timeout_ms ?? 30_000,
+          windowsHide: true,
+          maxBuffer: 4 * 1024 * 1024,
+          env: { ...process.env },
+        });
+        return { ok: true, stdout: r.stdout, stderr: r.stderr };
+      } catch (err) {
+        if (err.stdout !== undefined) return { ok: false, stdout: err.stdout, stderr: String(err.stderr ?? err.message), error: `exit ${err.code}` };
+        return { ok: false, stdout: '', stderr: String(err.message).slice(0, 400) };
+      }
+    },
+  });
+}

package/src/mind/skills.js

@@ -31,7 +31,7 @@
 
 'use strict';
 
-import { readdirSync, readFileSync, existsSync, statSync } from 'node:fs';
+import { readdirSync, readFileSync, writeFileSync, mkdirSync, 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';
@@ -51,6 +51,17 @@ function bootstrap() {
 
 const NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
 
+/** Scalars only in frontmatter — numbers/bools coerce, strings stay. */
+function coerceScalar(s) {
+  const t = String(s).trim().replace(/^["']|["']$/g, '');
+  if (t === 'true') return true;
+  if (t === 'false') return false;
+  if (/^-?\d+(\.\d+)?$/.test(t)) return Number(t);
+  return t;
+}
+
+
+
 /* ------------------------------------------------------------------ *
  * Parsing — loud, file-naming errors.
  * ------------------------------------------------------------------ */
@@ -67,14 +78,47 @@ export function parseSkill(raw, source = '<inline>') {
 
   const fmLines = text.slice(4, end).split('\n');
   const fm = {};
-  let currentKey = null;
+  let currentKey = null;       // the open list key (block-style list)
+  let currentItem = null;      // the open list item (for structured lists)
   for (const line of fmLines) {
     if (!line.trim() || line.trim().startsWith('#')) continue;
+    // List item under the open key: "- name: x" starts a structured item;
+    // "- word" is a scalar entry.
+    const item = line.match(/^\s+-\s+(.*)$/);
+    if (item && currentKey) {
+      const val = item[1];
+      const kv = val.match(/^([a-z_][a-z0-9_]*):\s*(.*)$/);
+      if (kv) {
+        // structured item: promote the key's value from string[] to object[]
+        if (!Array.isArray(fm[currentKey])) fm[currentKey] = [];
+        if (fm[currentKey].length && typeof fm[currentKey][fm[currentKey].length - 1] === 'string') {
+          // mixed — normalize scalars out (loud data would be better, but
+          // a skill's parameter list is homogeneous in practice)
+          fm[currentKey] = fm[currentKey];
+        }
+        const obj = {};
+        obj[kv[1]] = coerceScalar(kv[2]);
+        fm[currentKey].push(obj);
+        currentItem = obj;
+      } else {
+        if (!Array.isArray(fm[currentKey])) fm[currentKey] = [];
+        fm[currentKey].push(coerceScalar(val));
+        currentItem = null;
+      }
+      continue;
+    }
+    // Continuation of a structured item: "  required: true"
+    const cont = line.match(/^\s+([a-z_][a-z0-9_]*):\s*(.*)$/);
+    if (cont && currentItem) {
+      currentItem[cont[1]] = coerceScalar(cont[2]);
+      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;
+    currentItem = null;
     if (rest.trim() !== '') {
-      fm[key] = rest.trim();
+      fm[key] = coerceScalar(rest.trim());
       currentKey = key;
     } else {
       fm[key] = [];
@@ -110,6 +154,7 @@ export function parseSkill(raw, source = '<inline>') {
     name,
     description: fm.description,
     triggers: listOf('triggers').map(t => t.toLowerCase()),
+    parameters: Array.isArray(fm.parameters) ? fm.parameters : null,
     version: typeof fm.version === 'string' ? fm.version : null,
     source,
     body,
@@ -208,3 +253,62 @@ export async function injectSkills(taskId, text, { limit = 3 } = {}) {
 export function reset() {
   _skills.clear();
 }
+
+/* ------------------------------------------------------------------ *
+ * SKILL DISTILLATION (EvoX Genesis SkillExtractor lineage): a verified
+ * outcome becomes a durable PROCEDURE pack. Genesis distills after every
+ * accepted PR; FS distills after every gate-verified task — the outcome's
+ * evidence (the winning rung, the oracle commands) is the procedure.
+ * Distillation is IDEMPOTENT: the skill name is derived from the problem
+ * shape, and a re-distill of the same shape updates in place.
+ * ------------------------------------------------------------------ */
+
+/** Deterministic skill name from a task's problem text. */
+function skillNameFor(text) {
+  const slug = String(text).toLowerCase()
+    .replace(/[^a-z0-9\s-]/g, '')
+    .trim()
+    .split(/\s+/).slice(0, 4).join('-')
+    .replace(/^-+|-+$/g, '') || 'distilled-procedure';
+  return `distilled-${slug}`.slice(0, 64);
+}
+
+/**
+ * Distill a verified outcome into a SKILL.md pack on disk (and the live
+ * registry). The body records WHAT was done and the oracle commands that
+ * proved it — the next task of this shape starts from the procedure, not
+ * from scratch.
+ * @param {object} req — { problem, rung, evidence?, approach? }
+ * @param {{ dir?: string }} [opts] — target dir (default <root>/skills/distilled)
+ * @returns {{ name, path, created: boolean }}
+ */
+export async function distillSkill(req, opts = {}) {
+  const problem = String(req?.problem ?? '').trim();
+  if (!problem) throw new Error('skills.distill: req.problem is required');
+  const rung = String(req?.rung ?? 'unknown');
+  if (!req) throw new Error('skills.distill: req is required');
+  const name = skillNameFor(problem);
+  const dir = opts.dir ?? join(process.cwd(), 'skills', 'distilled');
+  mkdirSync(dir, { recursive: true });
+  const path = join(dir, `${name}.skill.md`);
+
+  const commands = (req.evidence?.commands ?? []).map(c => (typeof c === 'string' ? c : c?.cmd ?? c?.command)).filter(Boolean);
+  const approach = String(req.approach ?? '').trim();
+  const body = [
+    `# Distilled procedure — ${problem.slice(0, 80)}`, '',
+    `Distilled from a gate-verified outcome (rung: ${rung}).`, '',
+    '## When to use', '',
+    `A problem of this shape: "${problem.slice(0, 160)}"`, '',
+    '## Procedure', '',
+    approach || `Solved via the ${rung} rung; re-derive the candidate from the replay/seed of the same shape and gate it.`,
+    ...(commands.length ? ['', '## Verification oracle', '', '```', ...commands.map(c => c.slice(0, 200)), '```'] : []),
+  ].join('\n');
+
+  const fm = `---\nname: ${name}\ndescription: Distilled procedure for: ${problem.slice(0, 90).replace(/"/g, "'")}\ntriggers: [${name.replace(/^distilled-/, '')}]\nversion: 1\ndistilled-from: ${rung}\n---\n\n`;
+  const existed = existsSync(path);
+  writeFileSync(path, fm + body + '\n');
+  // Hot-load into the live registry so the next task benefits immediately.
+  _skills.set(name, parseSkill(fm + body, path));
+  trailJournal('skill.distilled', { name, path, rung, updated: existed });
+  return { name, path, created: !existed };
+}