futura-scion 0.2.4 → 0.2.6

package/README.md

@@ -531,11 +531,14 @@ signature. Read-only plans need no ceremony.
 
 Gate verifier BUNDLES per stack ship in `recipes/` as pure data (YAML —
 description, required tools, verifier commands): **node** (node --check +
-npm test), **python** (py_compile + pytest), **docker** (image build),
-**terraform** (fmt -check + init + validate — deliberately read-only;
-plan/apply belong in senior-review-approved workflow steps, never a gate),
-**xcode** (xcodebuild, tuned by `SCION_XCODE_*` env), **gradle** (wrapper
-build + test). Enable with one line:
+npm test), **python** (py_compile + pytest), **go** (gofmt discipline +
+go vet + go test), **rust** (cargo check + clippy discipline + cargo test),
+**dotnet** (dotnet build + test), **jvm** (wrapper-aware Maven/Gradle test),
+**docker** (image build), **terraform** (fmt -check + init + validate —
+deliberately read-only; plan/apply belong in senior-review-approved workflow
+steps, never a gate), **xcode** (xcodebuild, tuned by `SCION_XCODE_*` env),
+**gradle** (wrapper build + test). POSIX-pipeline verifiers declare
+`shell: bash` and run under Git Bash on Windows. Enable with one line:
 
 ```yaml
 gate:
@@ -777,6 +780,50 @@ With `learn: { auto: true }` in config, `scion serve` runs a cycle every
 `learn.interval_ms` (default 6h) in-process — the harness improves itself
 while it works. Zero-LLM by construction.
 
+### Codebase schematics — single-pass understanding, incremental forever (`scion map`)
+
+FS converts a complex codebase into a complete machine-navigable map — every
+symbol (signature, kind, line, exported/async), file import edges AND
+symbol-level call edges, entry points (bin scripts, HTTP route
+registrations, handlers), the exported surface, per-layer fan-in/fan-out,
+and deterministic pattern observations (factories, handlers, repositories).
+Persisted in the brain with per-file content hashes.
+
+The token contract: `mapFor()` re-parses ONLY files whose hash changed and
+reuses persisted fragments for everything else — 89 files with 1 changed
+costs 1 re-parse. Queries answer from the map with zero file reads:
+impact (transitive blast radius of a symbol), who-imports/who-calls,
+surface, entries.
+
+```bash
+scion map src                     # build-or-refresh + the one-screen digest
+scion map src --impact=runTask    # what breaks if this symbol changes
+scion map src --who=enqueue       # importers + callers, from the map
+scion map src --entries           # every door into the system
+```
+
+`digest()` renders the briefing a worker reads INSTEAD of source files;
+subsequent passes re-read only what changed. First pass = understanding;
+every pass after = surgical.
+
+### The MoE retention discipline — ephemeral fuel, durable lessons
+
+FS's memory mirrors a Mixture-of-Experts model's discipline: activate what
+the current task needs, retain only what compounds.
+
+- **Task working-set** (`scion working-set <taskId>`): gathered research
+  lives in an EPHEMERAL per-task brief — 64 KiB budget enforced by
+  oldest-first eviction, 1-hour TTL, swept at task end. Fuel, not furniture.
+- **Earned research rung**: when every cheaper ladder rung abstains, the
+  worker researches the web (deterministic organ) into its working set and
+  escalates INFORMED — the reviewer sees findings and sources. Opt out
+  with `research: false`.
+- **Lesson distiller**: exactly ONE durable lesson per gate verdict
+  (success / failure with the failing command / escalation), dedup-
+  reinforced. Lessons start at confidence 82 — just under the memory
+  rung's action threshold — so only REPETITION makes them actionable.
+  One occurrence is an observation; repetition is knowledge.
+
 ### FS Desktop — the standalone UI (chat / agent / plan / architect)
 
 FS ships a real UI in two forms, both zero-build:

package/bin/scion.js

@@ -656,6 +656,28 @@ switch (cmd || '') {
     else console.log(JSON.stringify(loop.cycle(), null, 2));
     break;
   }
+  case 'working-set': {
+    // Task working-set introspection (the ephemeral brief):
+    //   scion working-set <taskId>   what a task gathered + its budget posture
+    //   scion working-set --sweep    janitor: expire all past-TTL sets now
+    const tb = await import('../src/mind/task-brief.js');
+    if (arg === '--sweep') {
+      console.log(JSON.stringify(tb.briefSweep(), null, 2));
+      break;
+    }
+    if (!arg) {
+      console.error('usage: scion working-set <taskId> | scion working-set --sweep');
+      process.exitCode = 2;
+      break;
+    }
+    const stats = tb.briefStats(arg);
+    const brief = tb.briefRead(arg, { limit: 12 });
+    console.log(`task ${arg}: ${stats.items} item(s), ${stats.bytes} bytes`);
+    for (const i of brief.items) {
+      console.log(`  · [${i.source ?? 'no source'}] ${i.text.replace(/\s+/g, ' ').slice(0, 150)}`);
+    }
+    break;
+  }
   case 'evolve': {
     // The nightly harness-evolution pass (A4): mine weaknesses → propose
     // harness edits → gate them (SICA utility) → apply the accepted. Bounded
@@ -769,6 +791,43 @@ switch (cmd || '') {
     if (arch.violations.length > 0) process.exitCode = 1; // CI-friendly
     break;
   }
+  case 'map': {
+    // THE CODEBASE SCHEMATICS (single-pass understanding, incremental after):
+    //   scion map [dir]              build-or-refresh + digest (one-screen briefing)
+    //   scion map <dir> --impact X   transitive blast radius of symbol X
+    //   scion map <dir> --who X      who imports/calls X
+    //   scion map <dir> --entries    every entry point
+    // All queries answer from the persisted map — zero file re-reads beyond
+    // the changed files' hashes.
+    const sch = await import('../src/mind/schematic.js');
+    const target = arg || 'src';
+    const r = sch.mapFor(target);
+    const m = r.model;
+    const rel = (p) => String(p).split('\\').join('/').replace(/^src\//, '');
+    if (restArgs.includes('--entries')) {
+      for (const e of m.entries) console.log(`${e.kind.padEnd(8)} ${rel(e.file)}${e.symbol ? '#' + e.symbol : ''}  (${e.detail})`);
+      break;
+    }
+    const impactOf = restArgs.find((a) => a.startsWith('--impact='))?.split('=')[1];
+    if (impactOf) {
+      const im = sch.impact(m, impactOf);
+      console.log(`impact of ${impactOf} (defined in ${rel(m.symbols.find((s) => s.name === impactOf)?.file ?? '?')}):`);
+      console.log(`  direct (${im.direct.length}): ${im.direct.map(rel).join(', ')}`);
+      console.log(`  transitive (${im.transitive.length}): ${im.transitive.map(rel).join(', ')}`);
+      break;
+    }
+    const whoOf = restArgs.find((a) => a.startsWith('--who='))?.split('=')[1];
+    if (whoOf) {
+      const uniq = (a) => [...new Set(a)];
+      console.log(`importers: ${uniq(sch.queries.whoImports(m, sch.queries.fileFor(m, whoOf) ?? whoOf)).map(rel).join(', ') || '(none)'}`);
+      console.log(`callers:   ${uniq(sch.queries.callersOf(m, whoOf)).map(rel).join(', ') || '(none)'}`);
+      break;
+    }
+    console.log(sch.digest(m));
+    console.log(`
+refresh: ${r.reused} reused, ${r.changed.length} changed, ${r.added.length} added, ${r.removed.length} removed`);
+    break;
+  }
   case 'curate': {
     // Build + persist the codebase model (cortex curator lineage).
     //   scion curate <dir>            build + persist + summary
@@ -805,10 +864,57 @@ switch (cmd || '') {
     const positional = restArgs.filter((a) => !a.startsWith('--'));
     const target = positional[0];   // output directory
     if (!target) {
-      console.error('usage: scion scaffold <template|list> <target-dir> [--name x] [--title y] [--port N] [--param k=v] [--no-verify]');
+      console.error('usage: scion scaffold <template|fullstack|list> <target-dir> [--name x] [--port N] [--concurrency N] [--no-verify] [--dry-run]');
       process.exitCode = 2;
       break;
     }
+    if (arg === 'fullstack') {
+      // COMPOSABLE CONSTRUCTION: a workflow DAG that scaffolds backend,
+      // frontend, and CLI in parallel, then wires them into one repo.
+      const { planFullstack } = await import('../src/mind/plan-fullstack.js');
+      const params = {};
+      for (const f of flags) {
+        const m = f.match(/^--([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
+        if (m) params[m[1]] = m[2];
+      }
+      const swarm = flags.includes('--swarm');
+      const manifest = planFullstack(resolve(target), {
+        name: params.name,
+        ...(params.port !== undefined ? { port: Number(params.port) } : {}),
+        ...(swarm ? { swarm: true } : {}),
+      });
+      if (flags.includes('--dry-run')) {
+        console.log(`fullstack plan for ${target}:`);
+        for (const t of manifest.tasks) console.log(`  ${t.id.padEnd(20)} deps: ${(t.depends_on ?? []).join(', ') || '(parallel)'}`);
+        console.log('\nrun with --approve-as <reviewer> to construct');
+        break;
+      }
+      const approveIdx = restArgs.indexOf('--approve-as');
+      const reviewer = approveIdx !== -1 ? restArgs[approveIdx + 1] : null;
+      if (!reviewer) {
+        console.error('fullstack construction is a mutating workflow — approve it: --approve-as <reviewer> (or inspect first with --dry-run)');
+        process.exitCode = 2;
+        break;
+      }
+      const { runWorkflow } = await import('../src/kernel/workflow.js');
+      const conc = Number(flags.find((f) => f.startsWith('--concurrency='))?.split('=')[1]) || 3;
+      // SWARM mode needs a builder worker: register the construct role and
+      // bind this process's worker so the claim transaction routes to it.
+      const swarmOpts = {};
+      if (swarm) {
+        const roles = await import('../src/kernel/roles.js');
+        roles.registerRole({ id: 'builder', capabilities: ['construct'] });
+        roles.bindWorker('cli-builder', 'builder');
+        swarmOpts.role = 'builder';
+      }
+      const r = await runWorkflow(manifest, { concurrency: conc, approval: { reviewer }, ...swarmOpts });
+      console.log(`fullstack ${r.status}: ${r.completed}/${r.total} steps (concurrency ${conc}${swarm ? ', swarm-routed' : ''})`);
+      for (const t of r.tasks ?? []) {
+        if (t.status !== 'completed') console.log(`  ${t.status.toUpperCase()}: ${t.manifestId ?? t.id} ${t.error ?? ''}`);
+      }
+      if (r.status !== 'completed') process.exitCode = 1;
+      break;
+    }
     const tpl = loadTemplate(arg);
     const params = {};
     for (const f of flags) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "futura-scion",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "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/recipes/dotnet.yaml

@@ -0,0 +1,8 @@
+# gate.verifiers — the REAL Gate oracle for .NET projects (dotnet CLI).
+description: .NET (C# / F#)
+requires: [dotnet]
+verifiers:
+  - cmd: "dotnet build --nologo -v q"
+    timeout_ms: 600000
+  - cmd: "dotnet test --nologo -v q"
+    timeout_ms: 600000

package/recipes/go.yaml

@@ -0,0 +1,13 @@
+# gate.verifiers — the REAL Gate oracle for Go projects (modules).
+# gofmt discipline (any unformatted file fails), go vet, go test — real
+# exit codes, fail-fast. Pipeline runs under bash (Git Bash on Windows).
+description: Go (modules)
+requires: [go]
+verifiers:
+  - cmd: "gofmt -l . | grep -q . && exit 1 || exit 0"
+    timeout_ms: 60000
+    shell: bash
+  - cmd: "go vet ./..."
+    timeout_ms: 300000
+  - cmd: "go test ./..."
+    timeout_ms: 600000

package/recipes/jvm.yaml

@@ -0,0 +1,10 @@
+# gate.verifiers — the REAL Gate oracle for JVM projects (Maven or Gradle,
+# whichever wrapper the project ships). Auto-detects the wrapper, falls
+# back to the global tool. POSIX test syntax runs under bash (Git Bash on
+# Windows).
+description: JVM (Java / Kotlin via Maven or Gradle)
+requires: [java]
+verifiers:
+  - cmd: "if [ -f mvnw ]; then ./mvnw -q test; elif [ -f gradlew ]; then ./gradlew -q test; else mvn -q test 2>/dev/null || gradle -q test; fi"
+    timeout_ms: 600000
+    shell: bash

package/recipes/rust.yaml

@@ -0,0 +1,13 @@
+# gate.verifiers — the REAL Gate oracle for Rust projects (cargo).
+# Clippy is discipline, cargo test is truth. All judged by exit code.
+# The clippy gate is a bash pipeline (Git Bash on Windows).
+description: Rust (cargo)
+requires: [cargo]
+verifiers:
+  - cmd: "cargo check --quiet"
+    timeout_ms: 600000
+  - cmd: "cargo clippy --quiet 2>&1 | grep -E '^(warning|error)' && exit 1 || exit 0"
+    timeout_ms: 600000
+    shell: bash
+  - cmd: "cargo test --quiet"
+    timeout_ms: 600000

package/src/brain/db.js

@@ -256,6 +256,25 @@ export function ensureSchema(db) {
     CREATE INDEX IF NOT EXISTS idx_req_status ON requirements(status);
   `);
 
+  // ── Mind: task working-set (the EPHEMERAL brief) — gathered research
+  // held per-task for the task's duration, swept on completion. The MoE
+  // discipline: activate what THIS task needs, retain only the lessons.
+  // TTL (expires_at) and a size budget are enforced mechanically.
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS task_working_set (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      task_id TEXT NOT NULL,
+      kind TEXT NOT NULL DEFAULT 'finding',
+      text TEXT NOT NULL,
+      source TEXT,
+      bytes INTEGER NOT NULL DEFAULT 0,
+      expires_at TEXT,
+      created_at TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+    CREATE INDEX IF NOT EXISTS idx_tws_task ON task_working_set(task_id);
+    CREATE INDEX IF NOT EXISTS idx_tws_expires ON task_working_set(expires_at);
+  `);
+
   // ── Mind: replay index (Tier-0 learned decisions, now persistent) ──
   db.exec(`
     CREATE TABLE IF NOT EXISTS replay_index (

package/src/config.js

@@ -75,6 +75,19 @@ function dedentBlockLine(line, blockScalar) {
   return line.slice(cut);
 }
 
+/**
+ * YAML clip semantics: a literal/folded block scalar's value ends with a
+ * SINGLE trailing newline. Templates embed whole files in these blocks —
+ * gofmt, py_compile, and most linters require the final newline, and the
+ * old parser silently dropped it (a latent correctness bug the Go recipe's
+ * gofmt oracle caught first). Folded blocks join with spaces as before.
+ */
+function finalizeBlock(blockScalar) {
+  const text = blockScalar.text;
+  if (blockScalar.folded) return text.join(' ');
+  return text.length > 0 ? text.join('\n') + '\n' : '';
+}
+
 /**
  * Minimal YAML-subset parser: nested maps by indentation, scalars, inline
  * arrays, `#` comments. Deliberately NOT full YAML — unsupported syntax
@@ -84,6 +97,10 @@ export function parseYaml(text, source = CONFIG_PATH) {
   const root = {};
   const stack = [{ indent: -1, obj: root }];
   const lines = text.split(/\r?\n/);
+  // A trailing newline is a line TERMINATOR, not a blank line — drop the
+  // phantom final empty element so block scalars don't swallow it as an
+  // extra blank content line (gofmt-grade oracles reject the result).
+  if (lines.length > 0 && lines[lines.length - 1] === '') lines.pop();
   let blockScalar = null; // open "key: >" / "key: |" scalar being collected
 
   for (let i = 0; i < lines.length; i++) {
@@ -103,8 +120,8 @@ export function parseYaml(text, source = CONFIG_PATH) {
         && line.match(/^\s*/)[0].length > (blockScalar.indent ?? 0);
       const isListItem = /^\s*-\s/.test(line);
       if (!isContinuation || isListItem) {
-        const { parent, key, folded, text } = blockScalar;
-        parent[key] = folded ? text.join(' ') : text.join('\n');
+        const { parent, key } = blockScalar;
+        parent[key] = finalizeBlock(blockScalar);
         blockScalar = null;
       }
     }
@@ -207,11 +224,10 @@ export function parseYaml(text, source = CONFIG_PATH) {
     } else {
       parent[key] = parseScalar(rest);
     }
-  }
-  // Close a block scalar still open at EOF.
+  }  // Close a block scalar still open at EOF.
   if (blockScalar !== null) {
-    const { parent, key, folded, text } = blockScalar;
-    parent[key] = folded ? text.join(' ') : text.join('\n');
+    const { parent, key } = blockScalar;
+    parent[key] = finalizeBlock(blockScalar);
   }
   return root;
 }

package/src/gate/recipes.js

@@ -129,8 +129,14 @@ export function probeRecipes(names = null) {
     if (toolCache.has(tool)) return toolCache.get(tool);
     let ok = false;
     try {
+      // Go prints its version to STDOUT via `go version` (`go --version` is
+      // a usage error); everything else speaks `--version`. Probe both.
       const r = spawnSync(`${tool} --version`, { shell: true, windowsHide: true, timeout: 10000 });
       ok = r.status === 0 || (r.error === undefined && typeof r.stdout === 'string' && r.stdout.length > 0);
+      if (!ok && tool === 'go') {
+        const g = spawnSync('go version', { shell: true, windowsHide: true, timeout: 10000 });
+        ok = g.status === 0;
+      }
     } catch { ok = false; }
     toolCache.set(tool, ok);
     return ok;

package/src/gate/verifier.js

@@ -29,6 +29,7 @@
 'use strict';
 
 import { spawn } from 'node:child_process';
+import { accessSync, constants } from 'node:fs';
 import { resolve, isAbsolute } from 'node:path';
 import { load as loadConfig } from '../config.js';
 import { redact, assertCommandAllowed } from '../kernel/safety.js';
@@ -59,6 +60,31 @@ export function parseCommand(cmd) {
   return argv;
 }
 
+/**
+ * Locate a bash executable for portable POSIX recipes (shell:'bash').
+ * Order: SCION_BASH env override, then the well-known Git Bash paths on
+ * Windows, then PATH. Cached — a probe per command would be waste.
+ */
+let _bashPath = undefined;
+function resolveBash() {
+  if (_bashPath !== undefined) return _bashPath;
+  const candidates = [
+    process.env.SCION_BASH,
+    'C:/Program Files/Git/bin/bash.exe',
+    'C:/Program Files (x86)/Git/bin/bash.exe',
+  ].filter(Boolean);
+  if (process.platform !== 'win32') candidates.unshift('/bin/bash', '/usr/bin/bash');
+  for (const c of candidates) {
+    try {
+      accessSync(c, constants.X_OK);
+      _bashPath = c;
+      return c;
+    } catch { /* try next */ }
+  }
+  _bashPath = null;
+  return null;
+}
+
 /**
  * Run one command and capture its outcome.
  * @param {object} spec — { cmd, shell?, timeout_ms?, cwd?, env? }
@@ -74,6 +100,14 @@ export function runCommand(spec) {
     const cfg = loadConfig();
     const timeoutMs = spec.timeout_ms ?? cfg.gate?.timeout_ms ?? 120000;
     const useShell = spec.shell === true;
+    // shell:'bash' — portable POSIX recipes (gofmt/clippy pipelines, [ -f ]
+    // tests). Windows resolves Git Bash; POSIX shells already speak this.
+    const useBash = spec.shell === 'bash';
+    const bash = useBash ? resolveBash() : null;
+    if (useBash && !bash) {
+      resolvePromise({ cmd: spec.cmd, exit_code: -1, verified: false, error: 'verifier: shell "bash" requested but no bash found (install Git Bash or set SCION_BASH)' });
+      return;
+    }
     const cwd = spec.cwd ? resolve(spec.cwd) : process.cwd();
 
     let argv;
@@ -85,10 +119,12 @@ export function runCommand(spec) {
       return;
     }
 
-    const file = useShell ? (process.platform === 'win32' ? process.env.ComSpec || 'cmd.exe' : '/bin/sh') : argv[0];
-    const args = useShell
-      ? (process.platform === 'win32' ? ['/d', '/s', '/c', spec.cmd] : ['-c', spec.cmd])
-      : argv.slice(1);
+    const file = useBash ? bash : useShell ? (process.platform === 'win32' ? process.env.ComSpec || 'cmd.exe' : '/bin/sh') : argv[0];
+    const args = useBash
+      ? ['-c', spec.cmd]
+      : useShell
+        ? (process.platform === 'win32' ? ['/d', '/s', '/c', spec.cmd] : ['-c', spec.cmd])
+        : argv.slice(1);
 
     let child;
     try {

package/src/kernel/policy.js

@@ -12,6 +12,7 @@
 const DEFAULT_RULES = [
   { re: /^(os|shell|exec|rm|del)\b/i, action: 'deny', reason: 'os-level tools require the curated-command path' },
   { re: /^(read|list|glob|analyze|reason|search)\b/i, action: 'allow' },
+  { re: /^construct\b/i, action: 'gate', reason: 'construction is a mutation: the transactional applier writes and the Gate verifies' },
   { re: /^(write|edit|fix|apply)\b/i, action: 'gate', reason: 'mutations pass through the evidence gate' },
 ];
 

package/src/kernel/roles.js

@@ -100,6 +100,9 @@ export function liveWorkers() {
  * - An UNBOUND worker (no role) may claim only capability-less tasks —
  *   legacy behavior survives only where it is safe.
  * - Otherwise: every required capability must be in the role's set.
+ * - The role capability '*' is the GENERALIST wildcard: it satisfies any
+ *   requirement (the swarm's default binding; explicit is better than
+ *   implicit unrestrictedness — a generalist role is a declared contract).
  * Pure predicate — the queue's claim transaction calls this.
  */
 export function canClaim(workerId, taskCapabilities) {
@@ -107,6 +110,7 @@ export function canClaim(workerId, taskCapabilities) {
   if (required.length === 0) return true; // open task
   const role = roleOf(workerId);
   if (!role) return false;
+  if (role.capabilities.includes('*')) return true; // generalist wildcard
   return required.every((c) => role.capabilities.includes(c));
 }
 

package/src/kernel/safety.js

@@ -86,8 +86,12 @@ export function assertPathAllowed(p) {
     throw new Error('safety: path must be a non-empty string');
   }
   const norm = p.replace(/\\/g, '/');
+  const base = norm.split('/').pop(); // final segment decides secrets, not substrings
   for (const d of denylist()) {
-    if (norm.includes(d)) {
+    // Segment-aware matching: `.env` denies the secrets file itself, not
+    // `.env.example` or `backend-service/` (substring matching blocked the
+    // scaffolded env CONTRACT — a template file, not a secret).
+    if (d === '.env' ? base === '.env' : norm.includes(d)) {
       throw new Error(`safety: path denied by muscle.path_deny ("${d}"): ${p}`);
     }
   }

package/src/kernel/workflow.js

@@ -231,11 +231,35 @@ async function kernelCallable(fn) {
   if (fn === 'ocrImage') {
     return (args) => ocrImage(args?.image, { ...(args?.engine ? { engine: args.engine } : {}) });
   }
+  if (fn === 'scaffold') {
+    return async (args) => {
+      const { scaffold } = await import('../mind/scaffold.js');
+      const r = await scaffold(args?.template, {
+        params: args?.params ?? {},
+        ...(args?.cwd !== undefined ? { cwd: args.cwd } : {}),
+        ...(args?.verify !== undefined ? { verify: args.verify } : {}),
+      });
+      if (!r.ok) throw new Error(r.error ?? `scaffold ${args?.template} failed (gate: ${r.gate?.verified})`);
+      return { template: r.template, files: r.files, gate: r.gate?.verified ?? null };
+    };
+  }
+  if (fn === 'scaffold.file') {
+    // Wiring step: write one glue file through the transactional applier
+    // (snapshot + rollback) with the same path guardrails as any mutation.
+    return async (args) => {
+      const { transactionalApplier } = await import('./apply.js');
+      const tx = transactionalApplier({
+        files: [{ file: args?.file, content: args?.content ?? '', description: args?.description ?? `wire ${args?.file}` }],
+      });
+      const description = tx.apply();
+      return { description, file: args?.file };
+    };
+  }
   return null;
 }
 
 function callableSurface() {
-  return 'boostConsensus, ocrImage';
+  return 'boostConsensus, ocrImage, scaffold, scaffold.file';
 }
 
 async function execShellStep(step) {

package/src/ladder.js

@@ -65,6 +65,12 @@ function rollBudgetIfNeeded() {
  */
 export async function decide(problem, opts = {}) {
   let input = typeof problem === 'string' ? { text: problem } : problem;
+  // taskId is ROUTING metadata (the earned-research rung keys the ephemeral
+  // working set to it) — it must never leak into problem signatures, replay
+  // keys, or memory text, or identical problems stop replaying (t2 vs t3).
+  const { taskId: _routingTaskId, ...problemInput } = input;
+  input = problemInput;
+  const routingTaskId = _routingTaskId ?? 'unassigned';
 
   // Rung A — ARCHITECTURE (declared-design violations): a task typed
   // `arch:*` carries a MACHINE-VERIFIED design violation (mind/architecture
@@ -83,6 +89,36 @@ export async function decide(problem, opts = {}) {
     });
   }
 
+  // Rung C — CONSTRUCT (the construction lineage): a task that CARRIES a
+  // scaffold directive composes a project skeleton instead of analyzing a
+  // file. The candidate is the transactional multi-file applier shape
+  // ({ files: [...] }) — the worker applies it and the Gate verifies with
+  // the stack's real verifier recipe. Deterministic: pure template
+  // substitution, no generation. Capabilities gate WHO may construct.
+  if (input.construct?.template) {
+    try {
+      const { scaffold } = await import('./mind/scaffold.js');
+      const run = await scaffold(input.construct.template, {
+        params: input.construct.params ?? {},
+        ...(input.construct.cwd !== undefined ? { cwd: input.construct.cwd } : {}),
+        composeOnly: true, // the WORKER applies + gates — the ladder only composes
+      });
+      if (run.ok) {
+        return journal('construct', {
+          description: `scaffold ${input.construct.template} → ${input.construct.cwd ?? 'cwd'}`,
+          files: run.fileCandidates,   // applier candidates: { file, content, description }
+          fileStack: run.stack,        // the gate recipe the verifier should run
+          postCommands: run.post,      // dependency install / build, as verifier specs
+          template: input.construct.template,
+        });
+      }
+      trail.journal('ladder.construct-failed', { error: run.error ?? 'composition failed' });
+    } catch (err) {
+      trail.journal('ladder.construct-failed', { error: String(err?.message || err).slice(0, 200) });
+    }
+    // construction failure → fall through (escalation owns it)
+  }
+
   // Rung 0 — IMAGE PRE-STEP (deterministic OCR, cortex perception lineage):
   // an image problem carries no text, so before any rung can see it, its
   // TEXT LAYER is extracted (tesseract CLI, exit-code judged). The extracted
@@ -213,15 +249,27 @@ export async function decide(problem, opts = {}) {
     }
   }
 
-  // Rung 4 — reasoner (full 6-mode brain inference). An image problem whose
-  // OCR was refused carries no text at all — skip the reasoner (an empty
-  // topic is not an insight request) and let escalation own it.
+  // Rung 4b — REASONER INTEGRITY: an insight is only as good as its
+  // evidence. A synthesis drawn from LESSONS about unrelated problems is
+  // noise, not insight: if none of the memories the reasoner consulted
+  // overlap the problem's own terms, the mode is abstaining loudly by
+  // returning nothing. Guard here as well so rung order never matters.
   const reasonTopic = input.topic || input.text || '';
   if (reasonTopic.trim() !== '') {
     const insights = brainReasoner.reason(reasonTopic, { project, scope: memoryScope });
-    if (insights.length && insights[0].confidence >= minInsightConfidence) {
-      const top = insights[0];
-      return journal('reasoner', { insight: top.insight, confidence: top.confidence, mode: top.mode });
+    const top = insights[0];
+    if (top && top.confidence >= minInsightConfidence) {
+      // Term-overlap check: at least one content word of the problem must
+      // appear in the insight's source context (the insight itself may be
+      // phrased differently). Pure lexical — no LLM anywhere.
+      const stop = new Set(['the','and','for','with','this','that','from','into','when','what','how','why','fix','make','add','resolve','explain','project','must','should']);
+      const topicWords = new Set(reasonTopic.toLowerCase().split(/\W+/).filter((w) => w.length > 3 && !stop.has(w)));
+      const sourceWords = new Set(String(top.sources ?? top.evidence ?? top.context ?? top.insight ?? '').toLowerCase().split(/\W+/));
+      const overlap = [...topicWords].some((w) => sourceWords.has(w));
+      if (topicWords.size === 0 || overlap) {
+        return journal('reasoner', { insight: top.insight, confidence: top.confidence, mode: top.mode });
+      }
+      trail.journal('ladder.reasoner-abstain', { reason: 'no term overlap between problem and insight evidence' });
     }
   }
 
@@ -280,6 +328,47 @@ export async function decide(problem, opts = {}) {
     }
   }
 
+  // Rung R2 — EARNED RESEARCH (the MoE discipline, the last rung before
+  // giving up): every cheaper rung abstained, so the generalist goes
+  // LOOKING — deterministic web research on the task text (webresearcher
+  // lineage). Findings land in the task's EPHEMERAL working set
+  // (mind/task-brief: TTL'd, budgeted, swept at task end) — never the
+  // brain; the brain keeps only lessons. The candidate is RESEARCH-SHAPED:
+  // the worker treats it as informed-escalation evidence, the operator
+  // sees what was found and from where. Explicitly opted-out tasks
+  // (research === false) skip straight to escalation — the operator said
+  // no, once is enough.
+  if (input.research !== false && String(input.text ?? '').trim() !== '') {
+    try {
+      const { runResearch } = await import('./mind/research/index.js');
+      const { briefAbsorb, briefRead } = await import('./mind/task-brief.js');
+      const taskId = routingTaskId;
+      const report = await runResearch(String(input.text).slice(0, 300), { persist: false });
+      const findings = (report.items ?? [])
+        .filter((it) => it.corroboration?.verdict !== 'CONFLICTING')
+        .map((it) => ({ text: `${it.text} [${it.source_url ?? 'unknown source'}]`, source: it.source_url ?? null }));
+      const absorb = briefAbsorb(taskId, findings, { source: 'research:' + report.recipe });
+      trail.journal('ladder.researched', {
+        task: taskId, question: String(input.text).slice(0, 120),
+        pages: report.pages, items: report.items?.length ?? 0, absorbed: absorb.absorbed,
+        gate: report.gate?.verdict ?? null,
+      });
+      const brief = briefRead(taskId, { limit: 12 });
+      return journal('research', {
+        description: `researched: ${report.pages} pages, ${report.items?.length ?? 0} items (${report.gate?.verdict ?? 'no gate'})`,
+        taskId,
+        findings: brief.items.map((i) => ({ text: i.text, source: i.source })),
+        pages: report.pages,
+        gate: report.gate,
+        summary: report.summary?.SYNTHESIS ?? null,
+      });
+    } catch (err) {
+      trail.journal('ladder.research-failed', { error: String(err?.message || err).slice(0, 200) });
+      // Research is a privilege, not a requirement — thin/failed research
+      // degrades to escalation, which still carries the attempt's evidence.
+    }
+  }
+
   // Rung 7 — escalate
   return journal('escalate', {
     reason: 'ladder exhausted',