@ngockhoale/ukit 3.3.1 → 3.3.2

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to UKit are documented here.
 
+## 3.3.2 - 2026-09-27
+
+**Agent VM driver + self-improve code lane.**  CLI (list/show/status/shadow-run/evidence),  driver producing promotion evidence into , self-improve  step (one shadow run per reference plan per pass), and  step (AUTO-<id>.md handoff task files mined from recurring failure patterns — whitelist fix classes, denylist protected lanes, ≤3/pass, never commits code). See docs/plans/AGENT_VM_DRIVER_PLAN.md + SELF_IMPROVE_CODE_LANE.md.
+
+
+## Unreleased
+- **Self-improve `codeProposals` step — the code lane (SELF_IMPROVE_CODE_LANE plan).** After telemetry, each rate-limited pass turns mined, recurring failure patterns into **AUTO handoff task files** (`docs/AI_HANDOFF/tasks/AUTO-<seq>.md`) on the standard `_TEMPLATE.md` skeleton — frozen pattern evidence, `ready`/`S`, executor + reviewer + tests stay the quality gate. Whitelist fix classes only (timeout/hang, missing-fallback, empty-output, stale-doc); denylist targets (`src/decision/`, `src/core/agentRuntime/`, runtimeConfig, auth/security code) are skipped, never proposed; ≤3 AUTO tasks per pass; signatures already carried by `tasks/` or `archive/` files dedupe to `duplicate`. `learning.selfImprove.codeProposals` (default `true`) gates the step; `learning.selfImprove.codeProposalsCommit` is hard-false — writing a task file is the ceiling, self-improve never writes code or commits. `ukit self-improve --proposals` prints the proposal list; `--dry-run` lists would-be AUTO tasks without writing.
+- **`ukit vm` driver surface + shadow-run + evidence (agent-VM driver D-01..D-03).** New `src/cli/commands/vm.js` exposes `list`/`show <planId>`/`status`/`shadow-run <planId>`/`evidence <key>` over the plan library; all subcommands refuse `stage_off` (exit 2, zero writes) when `decisionRuntime.vm` is `'off'`. New `src/core/agentRuntime/shadowRun.js` `runShadowPlan(planId, {projectRoot, config, plansDir?, engineDir?, evidence?})` replays a pinned plan through a real `createVmEngine` rooted at `.ukit/storage/agent-runtime/shadow/<planId>/` with a stub `startFn` — deterministic synthetic events (RUN/WAIT_EVENT → `operation.completed`, BRANCH → first declared choice) until terminal, never throws, returns `{transitions, nodeStates, wallMs, irHash, planVersion}`. Each run appends one record to `evidence/vm.jsonl` (256 KiB rotation; `qualityDelta`/`wallP95Ratio`/`costRatio` stay `null` so shadow evidence can never self-promote); `ukit vm evidence vm` prints the `promote()` verdict verbatim without writing config.
+
+- **Self-improve `vmShadow` step (agent-VM driver D-04).** After diagnostics, each rate-limited `runSelfImprove` pass now runs one shadow-run per `planLibrary` reference plan via `agentRuntime/shadowRun.js` when `decisionRuntime.vm.stage` is `'shadow'` or higher — the first live-path caller that accumulates evidence for `PROMOTION_CRITERIA`. `off` → step `skipped` (`stage_off`), zero writes under `.ukit/storage/agent-runtime/`; driver missing, refusing, or throwing → step status `error`, the pass never throws and later steps still run.
+
 ## 3.3.1 - 2026-09-27
 
 - **Republish of 3.3.0, content-identical.** npm staged 3.3.0 then returned E409 "previously staged version" on retry — same staged-limbo pattern as 3.0.11→3.0.12. Version bump only; parity verified below.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "3.3.1",
+  "version": "3.3.2",
   "description": "Install/update an index-first AI workspace for Claude Code, OpenAI Codex and omp (Oh My Pi).",
   "license": "MIT",
   "type": "module",

package/src/cli/commands/selfImprove.js

@@ -6,17 +6,19 @@
 import { runSelfImprove } from '../../learning/selfImprove.js';
 
 const HELP_FLAGS = new Set(['--help', '-h', 'help']);
-const KNOWN_FLAGS = new Set(['--if-due', '--json', '--quiet']);
+const KNOWN_FLAGS = new Set(['--if-due', '--json', '--quiet', '--proposals', '--dry-run']);
 
 function printUsage() {
-  console.log('Usage: ukit self-improve [--if-due] [--json] [--quiet]');
+  console.log('Usage: ukit self-improve [--if-due] [--proposals] [--dry-run] [--json] [--quiet]');
   console.log('');
   console.log('Runs one self-improve pass: episode backfill, diagnostics, auto-tuning,');
-  console.log('pattern proposals, telemetry collect. Hooks run it automatically.');
+  console.log('pattern proposals, telemetry collect, code proposals. Hooks run it automatically.');
   console.log('');
-  console.log('  --if-due   Skip when the last pass ran < 10 minutes ago (hook mode)');
-  console.log('  --json     JSON output');
-  console.log('  --quiet    No output (hook mode)');
+  console.log('  --if-due      Skip when the last pass ran < 10 minutes ago (hook mode)');
+  console.log('  --proposals   Print the AUTO handoff-task proposals from the codeProposals step');
+  console.log('  --dry-run     List would-be AUTO tasks without writing files');
+  console.log('  --json        JSON output');
+  console.log('  --quiet       No output (hook mode)');
 }
 
 function describeStep(stepResult) {
@@ -40,7 +42,11 @@ export async function runSelfImproveCommand({ projectRoot, argv = [] }) {
     process.exitCode = 1;
     return;
   }
-  const result = await runSelfImprove(projectRoot, { force: !argv.includes('--if-due') });
+  const dryRun = argv.includes('--dry-run');
+  const result = await runSelfImprove(projectRoot, {
+    force: !argv.includes('--if-due'),
+    codeProposalsOpts: { dryRun },
+  });
   if (argv.includes('--quiet')) return;
   if (argv.includes('--json')) {
     console.log(JSON.stringify(result, null, 2));
@@ -52,4 +58,15 @@ export async function runSelfImproveCommand({ projectRoot, argv = [] }) {
   }
   console.log('[UKit] self-improve: ran');
   for (const stepResult of result.steps) console.log(describeStep(stepResult));
+  if (argv.includes('--proposals') || dryRun) {
+    const codeStep = result.steps.find((s) => s.name === 'codeProposals');
+    const entries = Array.isArray(codeStep?.results) ? codeStep.results : [];
+    console.log(`[UKit] code proposals${dryRun ? ' (dry-run — no files written)' : ''}:`);
+    for (const entry of entries) {
+      const target = entry.taskFile ?? '-';
+      const detail = entry.reason ? ` (${entry.reason})` : '';
+      console.log(`  ${entry.status}: ${entry.signature} → ${target}${detail}`);
+    }
+    if (entries.length === 0) console.log('  (no mined patterns)');
+  }
 }

package/src/cli/commands/vm.js

@@ -0,0 +1,242 @@
+// `ukit vm` — agent-VM live-path driver surface (AGENT_VM_DRIVER_PLAN D-01,
+// D-02, D-03). Discovery + shadow-evidence commands over the
+// language-compiled runtime; nothing here executes real operations
+// (shadow startFn is a stub) and nothing mutates config.
+//
+//   list                    Reference plans (planId, planVersion, irHash)
+//   show <planId>           One plan's compiled node ledger
+//   status                  Stage + evidence counts + shadow dir
+//   shadow-run <planId>     Deterministic replay through a real VmEngine;
+//                           appends one evidence record per run (D-03)
+//   evidence <key>          Read .ukit/storage/agent-runtime/evidence/<key>.jsonl
+//                           and print the promote() verdict verbatim (G-D3)
+//
+// Every subcommand is stage-gated on `decisionRuntime.vm`: 'off' → typed
+// refuse `stage_off`, exit 2, zero writes under
+// .ukit/storage/agent-runtime/ (G-D1). Exit codes: 0 success,
+// 2 typed failure, 1 usage error.
+
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import {
+  inspectRuntimeConfig,
+  resolveDecisionRuntimeStage,
+} from '../../core/runtimeConfig.js';
+import { loadPlan, loadPlanLibrary } from '../../core/agentRuntime/planLibrary.js';
+import { promote, promotionCriteriaFor } from '../../core/agentRuntime/promotion.js';
+import {
+  runShadowPlan,
+  readEvidence,
+} from '../../core/agentRuntime/shadowRun.js';
+
+const HELP_FLAGS = new Set(['--help', '-h', 'help']);
+const SUBCOMMANDS = new Set(['list', 'show', 'status', 'shadow-run', 'evidence']);
+const OPERAND_SUBCOMMANDS = new Set(['show', 'shadow-run', 'evidence']);
+
+const RUNTIME_REL = path.join('.ukit', 'storage', 'agent-runtime');
+
+function printUsage() {
+  console.log('Usage: ukit vm <command> [options]');
+  console.log('');
+  console.log('Commands:');
+  console.log('  list                 List pinned reference plans');
+  console.log('  show <planId>        Show one plan\'s compiled node ledger');
+  console.log('  status               Show decisionRuntime.vm stage + evidence summary');
+  console.log('  shadow-run <planId>  Run one deterministic shadow pass (stub startFn)');
+  console.log('  evidence <key>       Print the promote() verdict over stored runs');
+  console.log('');
+  console.log('Options:');
+  console.log('  --json               JSON output (status, evidence)');
+  console.log('  -h, --help           Show this help');
+  console.log('');
+  console.log('All commands require decisionRuntime.vm.stage != "off" (G-D1).');
+}
+
+// Same fail-safe posture as telemetry: unreadable config resolves {} → 'off'.
+async function loadConfig(projectRoot) {
+  try {
+    const inspection = await inspectRuntimeConfig(projectRoot, { homeDir: os.homedir() });
+    return inspection && inspection.config && typeof inspection.config === 'object'
+      ? inspection.config
+      : {};
+  } catch {
+    return {};
+  }
+}
+
+function refuseStageOff() {
+  console.error('[UKit] vm: refused — decisionRuntime.vm.stage is off (stage_off).');
+  console.error('[UKit] Set decisionRuntime.vm.stage to "shadow" (or higher) in .ukit/storage/config.json to enable.');
+  process.exitCode = 2;
+}
+
+// --- list -----------------------------------------------------------------
+
+async function listCommand({ config }) {
+  const catalog = loadPlanLibrary({ config });
+  const ids = Object.keys(catalog).sort();
+  if (ids.length === 0) {
+    console.log('vm: no plans in library');
+    return;
+  }
+  for (const id of ids) {
+    const entry = catalog[id];
+    if (entry.ok) {
+      console.log(`${id}  planVersion=${entry.planVersion}  irHash=${entry.irHash}`);
+      if (entry.description) console.log(`    ${entry.description}`);
+    } else {
+      const code = entry.errors?.[0]?.code ?? 'load_error';
+      console.log(`${id}  ERROR ${code}`);
+    }
+  }
+}
+
+// --- show -----------------------------------------------------------------
+
+function showCommand({ config, planId }) {
+  const loaded = loadPlan(planId, { config });
+  if (!loaded.ok) {
+    for (const err of loaded.errors ?? []) {
+      console.error(`[UKit] vm show: ${err.code ?? 'load_error'} ${err.planId ?? planId}`);
+    }
+    process.exitCode = 2;
+    return;
+  }
+  console.log(`plan ${loaded.planId}`);
+  console.log(`  planVersion ${loaded.planVersion}  irHash ${loaded.irHash}`);
+  if (loaded.description) console.log(`  ${loaded.description}`);
+  for (const id of loaded.plan.order) {
+    const node = loaded.plan.nodes.get(id);
+    const deps = node.deps.length > 0 ? ` deps=[${node.deps.join(',')}]` : '';
+    const sel = node.selector?.eventType ? ` selector=${node.selector.eventType}` : '';
+    const branches = node.op === 'BRANCH'
+      ? ` branches=[${Object.keys(node.branches ?? {}).join(',')}]`
+      : '';
+    const timeout = node.timeoutMs != null ? ` timeoutMs=${node.timeoutMs}` : '';
+    console.log(`  ${id}: ${node.op}${deps}${sel}${branches}${timeout}`);
+  }
+}
+
+// --- status ---------------------------------------------------------------
+
+async function statusCommand({ projectRoot, config, json }) {
+  const stage = resolveDecisionRuntimeStage(config, 'vm');
+  const catalog = loadPlanLibrary({ config });
+  const planIds = Object.keys(catalog).sort();
+  const brokenPlans = planIds.filter((id) => !catalog[id].ok);
+  const evidence = await readEvidence(projectRoot, { key: 'vm' });
+  const runs = evidence.ok ? evidence.runs.length : null;
+  let shadowDirs = 0;
+  try {
+    shadowDirs = (await fs.readdir(path.join(projectRoot, RUNTIME_REL, 'shadow'), { withFileTypes: true }))
+      .filter((e) => e.isDirectory()).length;
+  } catch { /* no shadow dir yet */ }
+  if (json) {
+    console.log(JSON.stringify({
+      stage,
+      plans: planIds,
+      brokenPlans,
+      evidenceRuns: runs,
+      shadowDirs,
+    }));
+    return;
+  }
+  console.log(`vm stage: ${stage}`);
+  console.log(`plans: ${planIds.length} (${planIds.join(', ') || 'none'})`);
+  if (brokenPlans.length > 0) console.log(`broken plans: ${brokenPlans.join(', ')}`);
+  console.log(`evidence runs: ${runs === null ? 'unknown' : runs}`);
+  console.log(`shadow instances: ${shadowDirs} plan dir(s)`);
+}
+
+// --- shadow-run -----------------------------------------------------------
+
+async function shadowRunCommand({ projectRoot, config, planId }) {
+  const res = await runShadowPlan(planId, { projectRoot, config });
+  if (!res.ok) {
+    console.error(`[UKit] vm shadow-run: ${res.code} — ${res.reason}`);
+    process.exitCode = 2;
+    return;
+  }
+  console.log(`shadow-run ${res.planId}: ${res.status} (${res.code})`);
+  console.log(`  planInstance ${res.planInstanceId}`);
+  console.log(`  planVersion ${res.planVersion}  irHash ${res.irHash}`);
+  console.log(`  transitions ${res.transitions.length}  wallMs ${res.wallMs}`);
+  for (const t of res.transitions) {
+    console.log(`    ${t.node} -> ${t.to}${t.branch !== undefined ? ` (${t.branch})` : ''}`);
+  }
+}
+
+// --- evidence -------------------------------------------------------------
+
+async function evidenceCommand({ projectRoot, config, key, json }) {
+  const res = await readEvidence(projectRoot, { key });
+  if (!res.ok) {
+    console.error(`[UKit] vm evidence: ${res.code} — ${res.reason}`);
+    process.exitCode = 2;
+    return;
+  }
+  const verdict = promote(config, { key, runs: res.runs });
+  const criteria = promotionCriteriaFor(key);
+  if (json) {
+    console.log(JSON.stringify({ key, runs: res.runs.length, dropped: res.dropped, criteria, verdict }));
+    return;
+  }
+  console.log(`evidence ${key}: ${res.runs.length} run(s)${res.dropped > 0 ? ` (${res.dropped} malformed dropped)` : ''}`);
+  // G-D3: verdict is advisory — printed verbatim, never written back.
+  console.log(`promote ${key}: stage=${verdict.stage} promoted=${verdict.promoted} reason=${verdict.reason}`);
+}
+
+// --- dispatch -------------------------------------------------------------
+
+export async function runVm({ projectRoot, argv = [] }) {
+  const args = Array.isArray(argv) ? argv : [];
+  const sub = (args[0] ?? '').toLowerCase();
+
+  if (args.length === 0 || HELP_FLAGS.has(sub)) {
+    printUsage();
+    return;
+  }
+  if (!SUBCOMMANDS.has(sub)) {
+    console.error(`[UKit] Unknown vm subcommand: ${sub}`);
+    printUsage();
+    process.exitCode = 1;
+    return;
+  }
+
+  const rest = args.slice(1);
+  if (rest.some((a) => HELP_FLAGS.has(a))) {
+    printUsage();
+    return;
+  }
+  const positional = rest.filter((a) => !a.startsWith('-'));
+  const flags = rest.filter((a) => a.startsWith('-'));
+  const allowed = (sub === 'status' || sub === 'evidence') ? new Set(['--json']) : new Set();
+  const unknownFlags = flags.filter((f) => !allowed.has(f));
+  if (unknownFlags.length > 0) {
+    console.error(`[UKit] Unknown vm flag(s): ${unknownFlags.join(', ')}`);
+    printUsage();
+    process.exitCode = 1;
+    return;
+  }
+  if (positional.length > 1 || (OPERAND_SUBCOMMANDS.has(sub) && positional.length === 0)) {
+    printUsage();
+    process.exitCode = 1;
+    return;
+  }
+
+  // G-D1 gate: 'off' refuses every subcommand with zero writes.
+  const config = await loadConfig(projectRoot);
+  if (resolveDecisionRuntimeStage(config, 'vm') === 'off') {
+    refuseStageOff();
+    return;
+  }
+
+  const operand = positional[0];
+  if (sub === 'list') return listCommand({ config });
+  if (sub === 'show') return showCommand({ config, planId: operand });
+  if (sub === 'status') return statusCommand({ projectRoot, config, json: flags.includes('--json') });
+  if (sub === 'shadow-run') return shadowRunCommand({ projectRoot, config, planId: operand });
+  return evidenceCommand({ projectRoot, config, key: operand, json: flags.includes('--json') });
+}

package/src/cli/index.js

@@ -13,6 +13,7 @@ import { runFeedback } from './commands/feedback.js';
 import { runPlaybook } from './commands/playbook.js';
 import { runDecision } from './commands/decision.js';
 import { runSelfImproveCommand } from './commands/selfImprove.js';
+import { runVm } from './commands/vm.js';
 const GLOBAL_FLAGS = new Set(['--help', '-h', '--version', '-v']);
 
 export async function runCli({ argv, packageRoot, projectRoot, packageVersion }) {
@@ -105,6 +106,11 @@ export async function runCli({ argv, packageRoot, projectRoot, packageVersion })
     return;
   }
 
+  if (command === 'vm') {
+    await runVm({ projectRoot, argv: commandArgv });
+    return;
+  }
+
   if (command === 'build' && (commandArgv[0] ?? '').toLowerCase() === 'index') {
     await runIndexTools({ projectRoot, argv: ['build', ...commandArgv.slice(1)] });
     return;
@@ -138,6 +144,7 @@ export async function runCli({ argv, packageRoot, projectRoot, packageVersion })
     console.log('  telemetry          Flight recorder (collect/status/digest/export-support/import/evaluate)');
     console.log('  feedback           Record or list wrong-route feedback labels');
     console.log('  self-improve       Run the automatic learn/tune/collect pass now (hooks run it)');
+    console.log('  vm                 Agent VM driver (list/show/status/shadow-run/evidence)');
     console.log('  update             Upgrade the global UKit CLI to the latest version');
     console.log('  version            Show UKit version');
     console.log('');

package/src/core/agentRuntime/shadowRun.js

@@ -0,0 +1,384 @@
+/**
+ * agentRuntime/shadowRun.js — agent-VM live-path driver (D-02/D-03).
+ *
+ * The shadow driver makes `decisionRuntime.vm` ≥ 'shadow' actually produce
+ * evidence: it loads a pinned reference plan via `planLibrary.loadPlan`,
+ * runs it inside a real `createVmEngine` rooted at
+ * `.ukit/storage/agent-runtime/shadow/<planId>/`, and feeds each activated
+ * node a deterministic synthetic event:
+ *
+ *   RUN / WAIT_EVENT  → <node.selector.eventType> (default
+ *                       'operation.completed') with
+ *                       safePayload { outcome:'completed', ...selector.fields }
+ *   BRANCH            → <node.selector.eventType> (default 'branch.selected')
+ *                       with safePayload { [selector.field]: <first declared
+ *                       choice> }
+ *   COMPLETE          → resolved by the engine itself (no external event)
+ *
+ * `startFn` is a noop — shadow runs measure VM/decision-plane behaviour
+ * (journals, continuations, classify verdicts on unclassifiable events),
+ * never real operation side effects. The run is deterministic modulo the
+ * decision model: selector-matched events never call classifyFn; an
+ * unroutable node degrades to the deterministic escalation lane
+ * (recovery_required) exactly as the V-05 contract requires.
+ *
+ * Never throws: every failure resolves to a typed
+ * `{ ok:false, code, reason }` — `stage_off` (decisionRuntime.vm 'off' →
+ * zero filesystem writes, G-D1), plan-load error codes verbatim from
+ * loadPlan, `malformed_plan`, `unknown_plan_id`, `engine_error`,
+ * `unterminated` (bounded-loop guard tripped).
+ *
+ * Evidence (D-03): each run appends one JSONL record to
+ * `.ukit/storage/agent-runtime/evidence/<key>.jsonl`
+ * `{planId, irHash, planVersion, planInstanceId, status, transitions,
+ *   wallMs, qualityDelta, wallP95Ratio, costRatio, forbidden, at}` —
+ * qualityDelta/wallP95Ratio/costRatio stay `null` until a measured
+ * baseline exists (promotion.js treats missing metrics as non-passing,
+ * so shadow evidence can never self-promote). The file rotates to
+ * `<key>.jsonl.1` at 256 KiB (single generation, bounded). Callers may
+ * pass `evidence:false` to skip the append (tests, dry probing).
+ */
+
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+
+import { resolveDecisionRuntimeStage } from '../runtimeConfig.js';
+import { isTerminal, CONTRACT_VERSION } from './contract.js';
+import { createVmEngine } from './vmEngine.js';
+import { loadPlan } from './planLibrary.js';
+
+const RUNTIME_REL = path.join('.ukit', 'storage', 'agent-runtime');
+const EVIDENCE_REL = path.join('evidence');
+const EVIDENCE_MAX_BYTES = 256 * 1024;
+
+/** Bounded driver loop: every step delivers ≥1 event, so a correct engine
+ * always terminates well inside this bound — tripping it means a driver or
+ * engine fault, surfaced as `unterminated` rather than an infinite await. */
+const maxSteps = (nodeCount) => nodeCount * 8 + 16;
+
+const KEY_RE = /^[a-z0-9][a-z0-9-]*$/;
+
+function refuse(code, reason) {
+  return Object.freeze({ ok: false, code, reason });
+}
+
+function runtimeDir(projectRoot) {
+  return path.join(projectRoot, RUNTIME_REL);
+}
+
+export function evidenceFilePath(projectRoot, key = 'vm') {
+  return path.join(runtimeDir(projectRoot), EVIDENCE_REL, `${key}.jsonl`);
+}
+
+/**
+ * Append one evidence record (single JSON line) to the bounded store.
+ * Rotation: one generation (`<key>.jsonl.1`), renamed aside before append
+ * when the file would exceed EVIDENCE_MAX_BYTES. Never throws.
+ *
+ * @param {string} projectRoot
+ * @param {object} record JSON-serializable run record
+ * @param {{key?: string}} [opts]
+ * @returns {Promise<{ok:true, bytes:number}|{ok:false, code:string, reason:string}>}
+ */
+export async function appendEvidence(projectRoot, record, { key = 'vm' } = {}) {
+  if (typeof projectRoot !== 'string' || projectRoot === '') {
+    return refuse('invalid_root', 'projectRoot required');
+  }
+  if (!KEY_RE.test(key)) return refuse('invalid_key', `evidence key ${JSON.stringify(key)}`);
+  if (record === null || typeof record !== 'object') {
+    return refuse('malformed_record', 'record must be an object');
+  }
+  let line;
+  try {
+    line = `${JSON.stringify(record)}\n`;
+  } catch {
+    return refuse('malformed_record', 'record is not JSON-serializable');
+  }
+  const file = evidenceFilePath(projectRoot, key);
+  try {
+    let size = 0;
+    try {
+      size = (await fs.stat(file)).size;
+    } catch (err) {
+      if (err?.code !== 'ENOENT') throw err;
+    }
+    if (size > 0 && size + Buffer.byteLength(line, 'utf8') > EVIDENCE_MAX_BYTES) {
+      await fs.rename(file, `${file}.1`).catch((err) => {
+        if (err?.code !== 'ENOENT') throw err;
+      });
+    }
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    const fh = await fs.open(file, 'a');
+    try {
+      await fh.writeFile(line, 'utf8');
+      await fh.sync();
+    } finally {
+      await fh.close();
+    }
+    return { ok: true, bytes: Buffer.byteLength(line, 'utf8') };
+  } catch (err) {
+    return refuse('evidence_write_error', err?.code ?? String(err));
+  }
+}
+
+/**
+ * Read evidence runs for one family key. Missing file → zero runs; a
+ * crash-torn final line is dropped; malformed mid-file lines are dropped
+ * too (evidence is advisory — one bad row must not break the read).
+ *
+ * @param {string} projectRoot
+ * @param {{key?: string}} [opts]
+ * @returns {Promise<{ok:true, key:string, runs:object[], dropped:number}
+ *   |{ok:false, code:string, reason:string}>}
+ */
+export async function readEvidence(projectRoot, { key = 'vm' } = {}) {
+  if (typeof projectRoot !== 'string' || projectRoot === '') {
+    return refuse('invalid_root', 'projectRoot required');
+  }
+  if (!KEY_RE.test(key)) return refuse('invalid_key', `evidence key ${JSON.stringify(key)}`);
+  const file = evidenceFilePath(projectRoot, key);
+  let raw;
+  try {
+    raw = await fs.readFile(file, 'utf8');
+  } catch (err) {
+    if (err?.code === 'ENOENT') return { ok: true, key, runs: [], dropped: 0 };
+    return refuse('evidence_read_error', err?.code ?? String(err));
+  }
+  const runs = [];
+  let dropped = 0;
+  for (const line of raw.split('\n')) {
+    if (line === '') continue;
+    try {
+      const parsed = JSON.parse(line);
+      if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        runs.push(parsed);
+      } else {
+        dropped += 1;
+      }
+    } catch {
+      dropped += 1;
+    }
+  }
+  return { ok: true, key, runs, dropped };
+}
+
+/** Synthetic SemanticEvent for one running node (deterministic payload). */
+function syntheticEvent(planInstanceId, node, seq, observedAt) {
+  // selector.fields is validated as a name-list by the compiler; only a
+  // caller-supplied object (test fixtures) is merged into the payload.
+  const payload = (node.selector?.fields !== null && typeof node.selector?.fields === 'object'
+    && !Array.isArray(node.selector.fields)) ? { ...node.selector.fields } : {};
+  let eventType = node.selector?.eventType;
+  if (node.op === 'BRANCH') {
+    const choice = Object.keys(node.branches ?? {})[0];
+    const field = node.selector?.field ?? 'branch';
+    payload[field] = choice;
+    eventType = eventType ?? 'branch.selected';
+    return {
+      choice: { field, value: choice, target: node.branches?.[choice] },
+      record: {
+        eventId: `shadow-${planInstanceId}-${node.id}-${seq}`,
+        operationId: `${planInstanceId}:${node.id}`,
+        seq,
+        eventType,
+        observedAt,
+        producerVersion: 'ukit-vm-shadow',
+        contractVersion: CONTRACT_VERSION,
+        privacyClass: 'internal',
+        artifactRefs: [],
+        safePayload: payload,
+      },
+    };
+  }
+  payload.outcome = 'completed';
+  eventType = eventType ?? 'operation.completed';
+  return {
+    choice: null,
+    record: {
+      eventId: `shadow-${planInstanceId}-${node.id}-${seq}`,
+      operationId: `${planInstanceId}:${node.id}`,
+      seq,
+      eventType,
+      observedAt,
+      producerVersion: 'ukit-vm-shadow',
+      contractVersion: CONTRACT_VERSION,
+      privacyClass: 'internal',
+      artifactRefs: [],
+      safePayload: payload,
+    },
+  };
+}
+
+/**
+ * Run one reference plan under a shadow engine and return its transition
+ * ledger. Deterministic: RUN/WAIT_EVENT resolve 'completed' on their first
+ * delivery; BRANCH takes its first declared choice; the loop stops as soon
+ * as the plan reaches a terminal status.
+ *
+ * @param {string} planId
+ * @param {{projectRoot?: string, config?: object, plansDir?: string,
+ *   engineDir?: string, now?: () => Date, classifyFn?: Function,
+ *   decisionClient?: object, decider?: object, evidence?: boolean,
+ *   maxTransitions?: number}} [opts]
+ *   `plansDir`/`engineDir` exist for tests and non-repo fixtures; the CLI
+ *   never passes them. `classifyFn`/`decisionClient`/`decider` are
+ *   forwarded to createVmEngine (test fault injection — the live path
+ *   leaves them unset so the V-05 stage-gated adapter applies).
+ * @returns {Promise<object>} frozen result — see module header.
+ */
+export async function runShadowPlan(planId, opts = {}) {
+  const { projectRoot, config = null } = opts;
+  try {
+    if (resolveDecisionRuntimeStage(config, 'vm') === 'off') {
+      return refuse('stage_off', 'decisionRuntime.vm.stage is off — zero writes');
+    }
+
+    const loaded = loadPlan(planId, {
+      ...(opts.plansDir ? { plansDir: opts.plansDir } : {}),
+      config,
+    });
+    if (!loaded.ok) {
+      const first = loaded.errors?.[0] ?? {};
+      return refuse(
+        typeof first.code === 'string' ? first.code : 'plan_not_found',
+        `${planId}: ${JSON.stringify(first)}`,
+      );
+    }
+    const plan = loaded.plan;
+    if (!plan || !(plan.nodes instanceof Map) || plan.nodes.size === 0) {
+      return refuse('malformed_plan', `${planId}: compiled plan has no nodes`);
+    }
+
+    const dir = typeof opts.engineDir === 'string' && opts.engineDir !== ''
+      ? opts.engineDir
+      : (typeof projectRoot === 'string' && projectRoot !== ''
+        ? path.join(runtimeDir(projectRoot), 'shadow', planId)
+        : null);
+    if (dir == null) return refuse('invalid_root', 'projectRoot or engineDir required');
+
+    const started = Date.now();
+    const engine = createVmEngine({
+      dir,
+      ...(typeof opts.now === 'function' ? { now: opts.now } : {}),
+      ...(typeof opts.classifyFn === 'function' ? { classifyFn: opts.classifyFn } : {}),
+      ...(opts.decisionClient != null ? { decisionClient: opts.decisionClient } : {}),
+      ...(opts.decider != null ? { decider: opts.decider } : {}),
+      startFn: async () => {}, // stub: shadow runs measure the VM, not real ops
+      config,
+    });
+
+    let startRes;
+    try {
+      startRes = await engine.start(plan);
+    } catch (err) {
+      return refuse('engine_error', err?.code ?? String(err));
+    }
+    if (!startRes || startRes.unsupported || typeof startRes.planInstanceId !== 'string') {
+      return refuse('malformed_plan', `${planId}: engine refused start (${startRes?.code ?? 'no instance'})`);
+    }
+    const pi = startRes.planInstanceId;
+
+    const transitions = [];
+    let status = 'running';
+    let steps = 0;
+    try {
+      const bound = maxSteps(plan.nodes.size);
+      while (steps < bound) {
+        const snapshot = await engine.state(pi);
+        status = snapshot.status;
+        if (isTerminal(status)) break;
+        const nodeId = plan.order.find(
+          (id) => snapshot.nodes[id]?.state === 'running'
+            && ['RUN', 'WAIT_EVENT', 'BRANCH'].includes(plan.nodes.get(id)?.op),
+        );
+        if (nodeId == null) {
+          // Nothing the driver can feed (e.g. only wrapper/non-terminal
+          // leftovers) — report honestly rather than spinning.
+          break;
+        }
+        const node = plan.nodes.get(nodeId);
+        const seq = (snapshot.cursor?.[nodeId] ?? 0) + 1;
+        const { record, choice } = syntheticEvent(
+          pi, node, seq, (typeof opts.now === 'function' ? opts.now() : new Date()).toISOString(),
+        );
+        const res = await engine.deliver(record);
+        steps += 1;
+        for (const t of res.transitions ?? []) {
+          transitions.push(
+            choice != null && t.node === nodeId && t.branch !== undefined
+              ? { node: t.node, to: t.to, branch: t.branch }
+              : { node: t.node, to: t.to },
+          );
+        }
+        if (!res.consumed) {
+          return refuse('event_not_consumed',
+            `${planId}/${nodeId}: deliver rejected (${res.code ?? 'unknown'})`);
+        }
+      }
+    } catch (err) {
+      return refuse('engine_error', err?.code ?? String(err));
+    } finally {
+      try { await engine.close(); } catch { /* persist-best-effort; run result stands */ }
+    }
+
+    const final = await engineStateSafe(engine, pi);
+    if (final) status = final.status;
+    const wallMs = Date.now() - started;
+    if (!isTerminal(status)) {
+      return refuse('unterminated', `${planId}: no terminal status after ${steps} deliveries`);
+    }
+
+    const nodeStates = {};
+    for (const [id, n] of Object.entries(final?.nodes ?? {})) {
+      nodeStates[id] = { state: n.state, attempt: n.attempt };
+    }
+    const result = Object.freeze({
+      ok: true,
+      code: status,
+      planId,
+      planInstanceId: pi,
+      status,
+      transitions: Object.freeze(transitions),
+      nodeStates: Object.freeze(nodeStates),
+      wallMs,
+      irHash: loaded.irHash,
+      planVersion: loaded.planVersion,
+    });
+
+    // D-03 evidence append (caller may opt out with evidence:false).
+    if (opts.evidence !== false && typeof projectRoot === 'string' && projectRoot !== '') {
+      const append = await appendEvidence(projectRoot, {
+        planId,
+        irHash: loaded.irHash,
+        planVersion: loaded.planVersion,
+        planInstanceId: pi,
+        status,
+        transitions: transitions.length,
+        wallMs,
+        qualityDelta: null,
+        wallP95Ratio: null,
+        costRatio: null,
+        // 'cancelled' is a normal terminal for plans whose untaken BRANCH
+        // path cancels dependents — only real failure lanes are forbidden.
+        forbidden: status === 'failed',
+        at: new Date().toISOString(),
+      }, { key: 'vm' });
+      if (!append.ok) {
+        return refuse('evidence_write_error', `${planId}: ${append.reason}`);
+      }
+    }
+    return result;
+  } catch (err) {
+    // Outer never-throws guard: an unexpected fault (e.g. engine internals
+    // throwing a non-typed error) still resolves to a typed refuse.
+    return refuse('engine_error', err?.code ?? String(err?.message ?? err));
+  }
+}
+
+async function engineStateSafe(engine, pi) {
+  try {
+    return await engine.state(pi);
+  } catch {
+    return null;
+  }
+}

package/src/core/runtimeConfig.js

@@ -229,7 +229,7 @@ function pushStageError(errors, node, label) {
 export function buildDefaultRuntimeConfig(overrides = {}) {
   const safeOverrides = isPlainObject(overrides) ? overrides : {};
 
-  return mergeObjects({
+  const config = mergeObjects({
     version: PACKAGE_VERSION,
     agent: 'claude-code',
     autonomy: {
@@ -451,7 +451,10 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
       episodes: { autoWrite: true },
       tuning: { enabled: true, applyMode: 'auto' },
       // 3.3.0: automatic collect → learn → apply pass (src/learning/selfImprove.js).
-      selfImprove: { enabled: true },
+      // codeProposals: AUTO task-file lane (SELF_IMPROVE_CODE_LANE plan).
+      // codeProposalsCommit is a reserved hard-false — writing a task file is
+      // the ceiling; self-improve never commits code (clamped below).
+      selfImprove: { enabled: true, codeProposals: true, codeProposalsCommit: false },
       // C52 M04.2 stage keys (SPEC §5 FR-016–FR-018). candidates: repeated
       // corrections/suppressions/escalations promote to a LearningCandidate
       // only after minOccurrences + cross-session evidence (status
@@ -575,6 +578,15 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
       },
     },
   }, safeOverrides);
+
+  // learning.selfImprove.codeProposalsCommit is hard-false forever: writing an
+  // AUTO task file is the ceiling of the code lane — applying/committing a
+  // patch is always the executor's job under test + review. A user-provided
+  // `true` is silently clamped, never honored.
+  if (isPlainObject(config.learning?.selfImprove)) {
+    config.learning.selfImprove.codeProposalsCommit = false;
+  }
+  return config;
 }
 
 export function validateRuntimeConfig(config) {
@@ -1114,6 +1126,8 @@ export function validateRuntimeConfig(config) {
           errors.push('learning.selfImprove must be an object.');
         } else {
           pushBooleanError(errors, learning.selfImprove.enabled, 'learning.selfImprove.enabled');
+          pushBooleanError(errors, learning.selfImprove.codeProposals, 'learning.selfImprove.codeProposals');
+          pushBooleanError(errors, learning.selfImprove.codeProposalsCommit, 'learning.selfImprove.codeProposalsCommit');
         }
       }
       // C52 M04.2 stage keys — same optional-present contract as routing.*.

package/src/learning/codeProposals.js

@@ -0,0 +1,349 @@
+// codeProposals.js — self-improve code lane (SELF_IMPROVE_CODE_LANE plan).
+//
+// Turns mined, recurring failure patterns into HANDOFF TASK FILES
+// (`docs/AI_HANDOFF/tasks/AUTO-<seq>.md`) — proposals for the normal
+// executor + reviewer + tests chain, never code writes or commits from
+// self-improve itself. Whitelist-only fix classes; anything outside the
+// deterministic mapping is `skipped`.
+//
+// Contracts:
+//   * NEVER THROWS — missing dirs, unreadable files, write failures →
+//     partial result, no exception escapes.
+//   * Eligible: count >= minCount (default 3) AND sessions >= 2.
+//   * Whitelist fix classes only (timeout/hang, missing-fallback,
+//     empty-output, stale-doc); unknown shapes → status 'skipped'.
+//   * Denylist: targets under src/decision/, src/core/agentRuntime/,
+//     runtimeConfig, auth/security/secret/credential/token code are never
+//     proposed.
+//   * Dedupe: a signature already carried by any `.md` in
+//     docs/AI_HANDOFF/tasks/ or docs/AI_HANDOFF/archive/ → 'duplicate'.
+//   * Cap: at most maxTasks (default 3) AUTO files per pass.
+//   * Writes are confined to docs/AI_HANDOFF/tasks/AUTO-<seq>.md via
+//     exclusive-create (`wx`); `dryRun` writes nothing.
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+const TASKS_DIR_REL = path.join('docs', 'AI_HANDOFF', 'tasks');
+const ARCHIVE_DIR_REL = path.join('docs', 'AI_HANDOFF', 'archive');
+const ARTIFACT_REL = path.join('.ukit', 'storage', 'cache', 'failure-patterns.json');
+const PLAN_REL = 'docs/plans/SELF_IMPROVE_CODE_LANE.md';
+const SIGNATURE_FIELD_RE = /signature["']?\s*:\s*["'`]?([^\n"'`,}]+)/gi;
+const MIN_SESSIONS = 2;
+const AUTO_NAME_RE = /^AUTO-(\d+)\.md$/;
+
+// Protected lanes — the same areas keepMainModelFor guards. A mined pattern
+// pointing here is skipped, never proposed.
+const DENIED_TARGET_RES = [
+  /^src\/decision\//,
+  /^src\/core\/agentRuntime\//,
+  /^src\/core\/runtimeConfig\.js$/,
+  /^src\/security\//,
+  /(^|\/)auth/i,
+  /secret|credential|token/i,
+];
+
+// Whitelist fix classes — bounded deterministic mapping only.
+const FIX_CLASSES = [
+  {
+    id: 'timeout-hang',
+    matches: (hay) => /timeout|timed?\s*out|hang|hung/.test(hay),
+    change: 'Increase the timeout, add an explicit deadline, and retry once before giving up.',
+  },
+  {
+    id: 'missing-fallback',
+    matches: (hay) => /missing-fallback/.test(hay)
+      || (/fallback/.test(hay) && /decision|decisionruntime/.test(hay)),
+    change: 'Add a `fallbackCode` path plus a deterministic default so the caller never blocks on the decision call.',
+  },
+  {
+    id: 'empty-output',
+    matches: (hay) => /empty[-_ ]?output|no output|empty stdout/.test(hay),
+    change: 'Keep the chain alive on empty output (`|| true` or equivalent) and log stderr for diagnosis.',
+  },
+  {
+    id: 'stale-doc',
+    matches: (hay) => /stale[-_ ]?doc|doc drift|docs?\s+drift|out[- ]?of[- ]?date\s+doc/.test(hay),
+    change: 'Re-render or refresh the flagged documentation file to match current source.',
+  },
+];
+
+function isObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+// Evidence haystack: signature + example commands + files, lowercased.
+function haystack(pattern) {
+  return [
+    pattern.signature,
+    ...(Array.isArray(pattern.commands) ? pattern.commands : []),
+    ...(Array.isArray(pattern.files) ? pattern.files : []),
+  ].join(' ').toLowerCase();
+}
+
+/**
+ * Map a mined pattern to a whitelisted fix class.
+ * @returns {{id: string, change: string}|null}
+ */
+export function mapPatternToFixTarget(pattern) {
+  if (!isObject(pattern)) return null;
+  const hay = haystack(pattern);
+  for (const fixClass of FIX_CLASSES) {
+    if (fixClass.matches(hay)) return { id: fixClass.id, change: fixClass.change };
+  }
+  return null;
+}
+
+function normalizeTargets(pattern) {
+  const files = Array.isArray(pattern?.files)
+    ? pattern.files.filter((f) => typeof f === 'string' && f.trim())
+    : [];
+  return files.map((f) => f.replace(/\\/g, '/'));
+}
+
+async function loadPatterns(projectRoot) {
+  try {
+    const raw = await fs.readFile(path.join(projectRoot, ARTIFACT_REL), 'utf8');
+    const parsed = JSON.parse(raw);
+    if (parsed && Array.isArray(parsed.patterns)) return parsed.patterns;
+  } catch {
+    // Artifact absent/corrupt → lazy re-mine below.
+  }
+  try {
+    const mod = await import('../diagnostics/failurePatterns.js');
+    if (typeof mod?.mineFailurePatterns !== 'function') return [];
+    const mined = await mod.mineFailurePatterns(projectRoot, { minCount: 1 });
+    return Array.isArray(mined?.patterns) ? mined.patterns : [];
+  } catch {
+    return [];
+  }
+}
+
+// Bounded recursive .md listing; missing dirs → [].
+async function listMarkdownFiles(dir, depth = 0) {
+  if (depth > 4) return [];
+  let entries;
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const files = [];
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...await listMarkdownFiles(full, depth + 1));
+    } else if (entry.isFile() && entry.name.endsWith('.md')) {
+      files.push(full);
+    }
+  }
+  return files;
+}
+
+// Signatures already claimed by a task/archived file + highest AUTO seq.
+async function scanHandoffDirs(projectRoot) {
+  const signatures = new Set();
+  let maxSeq = 0;
+  for (const rel of [TASKS_DIR_REL, ARCHIVE_DIR_REL]) {
+    const dir = path.join(projectRoot, rel);
+    for (const file of await listMarkdownFiles(dir)) {
+      const seqMatch = AUTO_NAME_RE.exec(path.basename(file));
+      if (seqMatch) maxSeq = Math.max(maxSeq, Number(seqMatch[1]));
+      let text;
+      try {
+        text = await fs.readFile(file, 'utf8');
+      } catch {
+        continue;
+      }
+      SIGNATURE_FIELD_RE.lastIndex = 0;
+      for (const match of text.matchAll(SIGNATURE_FIELD_RE)) {
+        const sig = match[1].trim();
+        if (sig) signatures.add(sig);
+      }
+    }
+  }
+  return { signatures, maxSeq };
+}
+
+function renderTaskFile({ seq, pattern, fixClass, targets, now }) {
+  const id = `AUTO-${String(seq).padStart(3, '0')}`;
+  const signature = pattern.signature;
+  const files = targets.length > 0 ? targets : ['(determine from evidence block)'];
+  const evidence = JSON.stringify(pattern, null, 2);
+  return `# ${id} — self-improve: ${fixClass.id} fix for "${signature}"
+
+- Status: \`ready\`
+- Size: \`S\`
+- Owner: \`-\`
+- Reviewer: \`-\`
+- Parent plan: \`${PLAN_REL}\`
+- Spec references: \`docs/AI_HANDOFF/SPEC.md\` §self-improve
+- Supersedes: \`(none)\`
+- Superseded by: \`(none)\`
+
+## Goal
+
+Recurring verification failure pattern \`"${signature}"\` — signature: \`${signature}\` —
+seen ${pattern.count}× across ${pattern.sessions} sessions. Apply the whitelisted
+**${fixClass.id}** fix: ${fixClass.change}
+
+## Target Files
+
+${files.map((f) => `- \`${f}\` — apply the ${fixClass.id} fix`).join('\n')}
+
+## Evidence (frozen — do not re-derive)
+
+\`\`\`json
+${evidence}
+\`\`\`
+
+## Progress
+
+## Test Cases (REQUIRED — TDD)
+
+| # | Loại | Tên test | Expected | Pre-state / Fixture |
+|---|------|----------|----------|---------------------|
+| 1 | unit | pattern signature "${signature}" repro | failing path exercised | fixture from Evidence block |
+| 2 | regression | fix holds | GREEN after patch | same fixture |
+
+## Test Files
+
+- (executor picks the closest existing test file for the target)
+
+## Verification Commands
+
+\`\`\`bash
+yarn test <targeted test file>
+\`\`\`
+
+## Acceptance Criteria
+
+- [ ] Targeted test green (RED → GREEN evidence in Executor Report).
+- [ ] No regression in the related suite.
+- [ ] Reviewer verdict APPROVED or APPROVED-WITH-MINOR.
+
+## Dependencies
+
+- (none)
+
+## Interfaces
+
+- Consumes: (none)
+- Produces: (none)
+
+---
+
+## Discussion
+
+### ${new Date(now).toISOString()} · planner · ukit self-improve
+Auto-generated by \`ukit self-improve\` at ${new Date(now).toISOString()} from mined failure-patterns artifact.
+
+<!-- auto-proposal: do-not-approve-without-human-review -->
+`;
+}
+
+/**
+ * Propose AUTO handoff task files from mined failure patterns.
+ *
+ * @param {string} projectRoot
+ * @param {{ minCount?: number, maxTasks?: number, dryRun?: boolean,
+ *   now?: number }} [options]
+ * @returns {Promise<{generatedAt: string, dryRun: boolean,
+ *   patternsScanned: number, eligible: number, created: number,
+ *   results: Array<{signature: string, fixClass: string|null,
+ *     status: 'proposed'|'duplicate'|'skipped', reason?: string,
+ *     taskFile: string|null, written: boolean}>, error?: string}>}
+ */
+export async function proposeCodeFixTasks(projectRoot, {
+  minCount = 3,
+  maxTasks = 3,
+  dryRun = true,
+  now = Date.now(),
+} = {}) {
+  const result = {
+    generatedAt: new Date(now).toISOString(),
+    dryRun,
+    patternsScanned: 0,
+    eligible: 0,
+    created: 0,
+    results: [],
+  };
+
+  try {
+    const patterns = await loadPatterns(projectRoot);
+    result.patternsScanned = patterns.length;
+    const known = await scanHandoffDirs(projectRoot);
+    let seq = known.maxSeq;
+    let emitted = 0;
+
+    for (const pattern of patterns) {
+      const signature = typeof pattern?.signature === 'string' ? pattern.signature : null;
+      if (!signature) continue;
+      const entry = {
+        signature, fixClass: null, status: 'skipped', taskFile: null, written: false,
+      };
+      result.results.push(entry);
+
+      const count = Number(pattern?.count) || 0;
+      const sessions = Number(pattern?.sessions) || 0;
+      if (count < minCount || sessions < MIN_SESSIONS) {
+        entry.reason = 'ineligible';
+        continue;
+      }
+      result.eligible += 1;
+
+      const fixClass = mapPatternToFixTarget(pattern);
+      if (!fixClass) {
+        entry.reason = 'no-fix-class';
+        continue;
+      }
+      entry.fixClass = fixClass.id;
+
+      const targets = normalizeTargets(pattern);
+      if (targets.some((f) => DENIED_TARGET_RES.some((re) => re.test(f)))) {
+        entry.reason = 'denied-target';
+        continue;
+      }
+
+      if (known.signatures.has(signature)) {
+        entry.status = 'duplicate';
+        continue;
+      }
+
+      if (emitted >= maxTasks) {
+        entry.reason = 'cap';
+        continue;
+      }
+
+      seq += 1;
+      const fileName = `AUTO-${String(seq).padStart(3, '0')}.md`;
+      entry.taskFile = path.join(TASKS_DIR_REL, fileName);
+      entry.status = 'proposed';
+      emitted += 1;
+      result.created += 1;
+      known.signatures.add(signature);
+
+      if (dryRun) continue;
+
+      try {
+        await fs.mkdir(path.join(projectRoot, TASKS_DIR_REL), { recursive: true });
+        await fs.writeFile(
+          path.join(projectRoot, TASKS_DIR_REL, fileName),
+          renderTaskFile({ seq, pattern, fixClass, targets, now }),
+          { flag: 'wx' },
+        );
+        entry.written = true;
+      } catch (err) {
+        entry.status = 'skipped';
+        entry.reason = `write-failed: ${err?.message ?? String(err)}`;
+        entry.written = false;
+        result.created -= 1;
+        emitted -= 1;
+      }
+    }
+  } catch (err) {
+    result.error = err?.message ?? String(err);
+  }
+
+  return result;
+}

package/src/learning/selfImprove.js

@@ -9,14 +9,22 @@
 // Steps (each isolated: one failing step never skips the others):
 //   1. episodes   — backfill an episode record for every idle exec-ledger
 //   2. diagnostics — failure patterns, feedback events, skill accuracy
-//   3. tuning     — compute suggestions; applyMode 'auto' applies them as
+//   3. vmShadow   — when decisionRuntime.vm stage ≥ 'shadow', one shadow-run
+//                   per reference plan via the agent-VM driver (D-04); off →
+//                   skipped, any failure → status 'error', never throws
+//   4. tuning     — compute suggestions; applyMode 'auto' applies them as
 //                   clamped one-step changes in learning/tuned.json, with a
 //                   per-key cooldown so one noisy window cannot ratchet a
 //                   value across its whole range
-//   4. proposals  — repeated failure patterns become PENDING memory
+//   5. proposals  — repeated failure patterns become PENDING memory
 //                   candidates (rules still need `ukit memory approve`)
-//   5. telemetry  — ingest stored hook/ledger telemetry, flush, refresh the
+//   6. telemetry  — ingest stored hook/ledger telemetry, flush, refresh the
 //                   support view
+//   7. codeProposals — eligible mined patterns become AUTO-<seq> handoff task
+//                      files (docs/AI_HANDOFF/tasks/); whitelist fix classes
+//                      only, ≤3/pass, signature-deduped, denylisted targets
+//                      skipped. Proposals are task FILES — self-improve never
+//                      writes code or commits (SELF_IMPROVE_CODE_LANE plan)
 //
 // Guards: `.ukit/storage/learning/self-improve.json` stamp rate-limits the
 // pass (minIntervalMs, default 10 min) and a file lock keeps two triggers from
@@ -26,7 +34,7 @@ import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 
-import { inspectRuntimeConfig } from '../core/runtimeConfig.js';
+import { inspectRuntimeConfig, resolveDecisionRuntimeStage } from '../core/runtimeConfig.js';
 import { withFileLock } from '../core/fileOps.js';
 import { detectProjectContext } from '../context/detectProjectContext.js';
 import { backfillEpisodes } from '../core/memory/episodes.js';
@@ -35,6 +43,7 @@ import { collectFeedbackEvents } from '../diagnostics/feedbackEvents.js';
 import { collectSkillAccuracy } from '../diagnostics/skillAccuracy.js';
 import { computeTuningSuggestions } from './tuning.js';
 import { proposeFromPatterns } from './patternProposals.js';
+import { proposeCodeFixTasks } from './codeProposals.js';
 import {
   TUNABLE_KEYS,
   clampTunable,
@@ -133,7 +142,12 @@ async function collectTelemetry(projectRoot, config) {
 /**
  * Run one self-improve pass.
  * @param {string} projectRoot
- * @param {{ force?: boolean, homeDir?: string, now?: number, minIntervalMs?: number }} [opts]
+ * @param {{ force?: boolean, homeDir?: string, now?: number, minIntervalMs?: number,
+ *   runShadowPlan?: Function, codeProposalsOpts?: { dryRun?: boolean } }} [opts] —
+ *   runShadowPlan overrides the agentRuntime shadow-run driver (tests); absent →
+ *   dynamic import of agentRuntime/shadowRun.js (import failure → vmShadow step
+ *   'error'). codeProposalsOpts.dryRun:false lets the codeProposals step write
+ *   AUTO task files; anything else keeps it dry-run.
  * @returns {Promise<{status: 'ran'|'skipped', reason?: string, steps?: object[]}>}
  */
 export async function runSelfImprove(projectRoot, {
@@ -141,6 +155,8 @@ export async function runSelfImprove(projectRoot, {
   homeDir = os.homedir(),
   now = Date.now(),
   minIntervalMs = DEFAULT_MIN_INTERVAL_MS,
+  runShadowPlan,
+  codeProposalsOpts,
 } = {}) {
   const root = path.resolve(projectRoot);
   const stampPath = path.join(root, STAMP_REL);
@@ -172,6 +188,43 @@ export async function runSelfImprove(projectRoot, {
           skills: Object.keys(skills?.skills ?? {}).length,
         };
       }));
+      steps.push(await step('vmShadow', async () => {
+        if (resolveDecisionRuntimeStage(config, 'vm') === 'off') {
+          return { status: 'skipped', reason: 'stage_off' };
+        }
+        try {
+          const runner = runShadowPlan
+            ?? (await import('../core/agentRuntime/shadowRun.js')).runShadowPlan;
+          const { listPlanIds } = await import('../core/agentRuntime/planLibrary.js');
+          const runs = [];
+          for (const planId of listPlanIds()) {
+            let res;
+            try {
+              res = await runner(planId, { projectRoot: root, config });
+            } catch (error) {
+              res = { ok: false, code: 'driver_threw', reason: error?.message ?? String(error) };
+            }
+            runs.push({
+              planId,
+              ok: res?.ok === true,
+              code: res?.code ?? null,
+              transitions: Array.isArray(res?.transitions) ? res.transitions.length : 0,
+              wallMs: res?.wallMs ?? null,
+              irHash: res?.irHash ?? null,
+            });
+          }
+          const failed = runs.filter((r) => !r.ok).length;
+          return {
+            status: failed === 0 ? 'ok' : 'error',
+            ran: runs.length - failed,
+            failed,
+            runs,
+          };
+        } catch (error) {
+          // Driver not built yet or plansDir unreadable: report, never throw.
+          return { status: 'error', reason: error?.message ?? String(error) };
+        }
+      }));
       steps.push(await step('tuning', async () => {
         const result = await computeTuningSuggestions(root);
         const mode = resolveApplyMode(rawConfig ?? {});
@@ -188,7 +241,20 @@ export async function runSelfImprove(projectRoot, {
           reason: res.error,
         };
       }));
+
       steps.push(await step('telemetry', () => collectTelemetry(root, config)));
+      steps.push(await step('codeProposals', async () => {
+        if (config?.learning?.selfImprove?.codeProposals === false) {
+          return { status: 'skipped', reason: 'disabled' };
+        }
+        const res = await proposeCodeFixTasks(root, { dryRun: codeProposalsOpts?.dryRun !== false });
+        return {
+          status: res.error ? 'failed' : 'ok',
+          created: res.created,
+          results: res.results,
+          reason: res.error,
+        };
+      }));
 
       await writeJsonAtomic(stampPath, {
         lastRunAt: new Date(now).toISOString(),