@ngockhoale/ukit 3.2.0 → 3.3.1

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to UKit are documented here.
 
+## 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.
+
+## 3.3.0 - 2026-09-27
+
+**Zero-config self-improvement: every feature stage ships on, UKit collects and learns from its own data.** Fixes the gap where 2.6.8–3.2.0 built the machinery (flight recorder, memory v2, learning, decision plane) but nothing on the live hook path fed it — measured 1 telemetry record and 0 memory-v2 records after days of use.
+
+- **`ukit self-improve` — the automatic collect → learn → apply pass** (`src/learning/selfImprove.js`, `src/cli/commands/selfImprove.js`). One bounded, rate-limited (10 min), lock-guarded pass that runs after every session: (1) backfills an episode for every idle exec-ledger — engine-agnostic, fixes omp session-id mismatch and Codex having no lifecycle hooks; (2) refreshes diagnostics (failure patterns, feedback, skill accuracy); (3) computes tuning suggestions and **auto-applies** them under `learning.tuning.applyMode: 'auto'` (new default) as clamped one-step moves into `.ukit/storage/learning/tuned.json` with a 24h per-key cooldown; (4) writes repeated failure patterns as pending pattern candidates (promotion still needs `ukit memory approve`); (5) ingests stored hook/ledger telemetry, flushes, refreshes the support view. Never throws; each step isolated.
+- **`self-improve-trigger.mjs`** (`template_project/.claude/ukit/runtime/`): fire-and-forget launcher called from Claude `SessionEnd`/`session-episode.sh`, omp `session_stop` via the bridge, and Codex `route-task.mjs` (its only per-task entry). Detached child, returns in ms, silent no-op on any failure; opt out via `learning.selfImprove.enabled: false` or `UKIT_SELF_IMPROVE=0`.
+- **CLI locator** (`.ukit/storage/cli.json`, `writeCliLocator` in `metadata.js`, written by `ukit install`): absolute node + bin paths so hooks spawning the CLI work on GUI-launched hosts whose PATH lacks nvm/volta. `resolveCliLocator` validates node basename, `bin/ukit` shape and `@ngockhoale/ukit` package identity before trusting it; PATH lookup stays the fallback.
+- **All stage flags default on**: `routing.*` → `default`; `memoryV2.decision` → `default`; `learning.candidates`/`overlays` → `default`; `continuity.resumableRun` → `default`; `decisionRuntime.*` → `shadow` (diagnostics → `default`); `experiments.deliberation`/`dynamicWorkflow` → enabled; `observability.stage` added to code defaults (`default`). `learning.tuning.applyMode` accepts `'auto'`; tuned overlay merges via `inspectRuntimeConfig`. Rollback: per-key `stage: "off"`, `applyMode: 'manual'`, or delete `tuned.json`.
+- **`ukit memory episode` refactored** onto shared `src/core/memory/episodes.js` (`resolveLedger`, `episodeText`, `writeEpisode`, `backfillEpisodes`) — one owner for the record shape between the single-session command and the self-improve backfill.
+- Tests: 28 new (tunedOverlay clamp/merge/cooldown, episodes resolve/write/backfill dedupe, trigger locator validation + spawn contract); stale stage-default pins updated to the 3.3.0 contract.
+
+
+
 ## 3.2.0 - 2026-09-26
 
 **Agent VM / Language-Compiled Runtime phase 2 (V-01..V-06)** — IR v2 flag-gated opcodes, decisionRuntime.vm stage-promotion machinery, plan library pins, VM decision nodes via unic-decision, host parity adapters, sanitized support bundle. All new surfaces ship `off`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "3.2.0",
+  "version": "3.3.1",
   "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/memory.js

@@ -29,7 +29,7 @@ import { buildRuntimePaths } from '../../core/runtimePaths.js';
 import { buildUserPaths } from '../../core/userPaths.js';
 import { pathExists } from '../../core/fileOps.js';
 import { detectProjectContext } from '../../context/detectProjectContext.js';
-import { listLedgerFiles, LEDGER_DIR_REL } from '../../diagnostics/ledgerFiles.js';
+import { episodeText, resolveLedger, writeEpisode } from '../../core/memory/episodes.js';
 import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
@@ -520,53 +520,8 @@ async function runMemoryPromote(projectRoot, homeDir, args) {
 }
 
 // ---- `ukit memory episode` — session episode from exec-ledger (SPEC §7b) ----
-
-// Mirrors execution-ledger.mjs safeSegment — src/ cannot import the runtime
-// module, so the segment rule is duplicated deliberately.
-function safeSegment(value) {
-  return String(value || 'default')
-    .trim()
-    .replace(/[^a-zA-Z0-9._-]/g, '_')
-    .slice(0, 96) || 'default';
-}
-
-async function readJsonIfExists(filePath) {
-  try {
-    return JSON.parse(await fs.readFile(filePath, 'utf8'));
-  } catch {
-    return null;
-  }
-}
-
-// Resolution order: --session <id> → UKIT_SESSION_ID env → most-recent ledger.
-async function resolveLedger(projectRoot, sessionFlag) {
-  const dir = path.join(projectRoot, LEDGER_DIR_REL);
-  const candidate = sessionFlag ?? process.env.UKIT_SESSION_ID;
-  if (candidate) {
-    const file = `${safeSegment(candidate)}.json`;
-    const ledger = await readJsonIfExists(path.join(dir, file));
-    return ledger ? { ledger, ledgerKey: file } : { ledger: null, ledgerKey: file };
-  }
-  const [name] = await listLedgerFiles(dir, 1);
-  if (!name) return { ledger: null, ledgerKey: null };
-  const ledger = await readJsonIfExists(path.join(dir, name));
-  return ledger ? { ledger, ledgerKey: name } : { ledger: null, ledgerKey: name };
-}
-
-function episodeText(ledger, sessionId) {
-  const write = ledger.writeSucceeded === true ? 'writeOk' : 'writeFail';
-  const verify = ledger.verificationAttempted !== true
-    ? 'not-run'
-    : ledger.verificationSucceeded === true ? 'ok' : 'fail';
-  const receipts = Array.isArray(ledger.receipts) ? ledger.receipts : [];
-  const lastReceipt = receipts.length > 0 ? receipts[receipts.length - 1] : null;
-  const lastCommand = lastReceipt
-    ? String(lastReceipt?.command ?? '').split('\n')[0].trim() || 'n/a'
-    : 'n/a';
-  const text = `Session ${sessionId}: ${write}, verify=${verify}, `
-    + `${receipts.length} receipts, last command ${lastCommand}`;
-  return text.slice(0, 300);
-}
+// Record shape + dedupe live in core/memory/episodes.js (shared with the
+// self-improve backfill).
 
 async function runMemoryEpisode(projectRoot, homeDir, args) {
   const dryRun = args.includes('--dry-run');
@@ -578,62 +533,31 @@ async function runMemoryEpisode(projectRoot, homeDir, args) {
     return;
   }
 
-  const { ledger, ledgerKey } = await resolveLedger(projectRoot, sessionFlag);
+  const { ledger, ledgerKey } = await resolveLedger(projectRoot, sessionFlag ?? process.env.UKIT_SESSION_ID);
   if (!ledger) {
     console.log('[UKit] episode: nothing to record');
     return;
   }
 
-  const sessionId = ledger.sessionId ?? ledger.sessionKey
-    ?? (ledgerKey ? ledgerKey.replace(/\.json$/, '') : 'unknown');
-  const text = episodeText(ledger, sessionId);
-
   if (dryRun) {
-    console.log(`[UKit] episode (dry-run): ${text}`);
-    return;
-  }
-
-  const existing = await loadRecords(projectRoot, { homeDir });
-  if (existing.some((r) => r.meta?.ledgerKey === ledgerKey)) {
-    console.log('[UKit] episode: already recorded');
+    const sessionId = ledger.sessionId ?? ledger.sessionKey ?? ledgerKey.replace(/\.json$/, '');
+    console.log(`[UKit] episode (dry-run): ${episodeText(ledger, sessionId)}`);
     return;
   }
 
-  const ttlDays = Number(config?.memoryV2?.episodeTtlDays) || 90;
-  const projectId = (await detectProjectContext(projectRoot, { homeDir })).project.name;
-  // FR-023: the add goes through mutateMemory with the ledger key as the
-  // idempotency key — a hook-invoked rerun is a journal 'duplicate' even if
-  // the meta.ledgerKey fast-path above is bypassed.
-  const res = await mutateMemory(
-    { kind: 'project', projectRoot, homeDir },
-    {
-      op: 'add',
-      idempotencyKey: ledgerKey,
-      payload: {
-        type: 'episode',
-        scope: 'session',
-        text,
-        provenance: 'exec-ledger',
-        confidence: 0.6,
-        createdBy: 'episode-hook',
-        projectId,
-        validUntil: Date.now() + ttlDays * 24 * 60 * 60 * 1000,
-        meta: { sessionId, ledgerKey },
-      },
-    },
-  );
+  const res = await writeEpisode(projectRoot, { ledger, ledgerKey, config, homeDir });
   if (res.status === 'duplicate') {
     console.log('[UKit] episode: already recorded');
     return;
   }
   if (res.status === 'rejected') {
-    printGuardRejection(res);
+    printGuardRejection(res.result);
     return;
   }
-  if (res.status !== 'ok') {
-    throw new Error(`episode write failed: ${res.status}${res.reason ? ` — ${res.reason}` : ''}`);
+  if (res.status !== 'recorded') {
+    throw new Error(`episode write failed: ${res.reason}`);
   }
-  console.log(`[UKit] episode: recorded ${res.record.id} for session ${sessionId}`);
+  console.log(`[UKit] episode: recorded ${res.id} for session ${res.sessionId}`);
 }
 
 // ---- `ukit memory backup|restore|doctor` — operator lane (SPEC §9, FR-011) ----

package/src/cli/commands/selfImprove.js

@@ -0,0 +1,55 @@
+// `ukit self-improve` — run the automatic collect → learn → apply pass now.
+// Hooks trigger it detached (self-improve-trigger.mjs); this is the manual
+// and the trigger's own entry point. `--if-due` honors the rate-limit stamp
+// (what triggers pass); without it the pass is forced.
+
+import { runSelfImprove } from '../../learning/selfImprove.js';
+
+const HELP_FLAGS = new Set(['--help', '-h', 'help']);
+const KNOWN_FLAGS = new Set(['--if-due', '--json', '--quiet']);
+
+function printUsage() {
+  console.log('Usage: ukit self-improve [--if-due] [--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('');
+  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)');
+}
+
+function describeStep(stepResult) {
+  const { name, status, ...rest } = stepResult;
+  const details = Object.entries(rest)
+    .filter(([, value]) => value !== undefined && value !== null)
+    .map(([key, value]) => `${key}=${Array.isArray(value) ? value.length : value}`)
+    .join(' ');
+  return `  ${name}: ${status}${details ? ` ${details}` : ''}`;
+}
+
+export async function runSelfImproveCommand({ projectRoot, argv = [] }) {
+  if (argv.some((flag) => HELP_FLAGS.has(flag))) {
+    printUsage();
+    return;
+  }
+  const unknown = argv.filter((flag) => !KNOWN_FLAGS.has(flag));
+  if (unknown.length > 0) {
+    console.error(`[UKit] Unknown self-improve argument(s): ${unknown.join(', ')}`);
+    printUsage();
+    process.exitCode = 1;
+    return;
+  }
+  const result = await runSelfImprove(projectRoot, { force: !argv.includes('--if-due') });
+  if (argv.includes('--quiet')) return;
+  if (argv.includes('--json')) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  if (result.status !== 'ran') {
+    console.log(`[UKit] self-improve: skipped (${result.reason})`);
+    return;
+  }
+  console.log('[UKit] self-improve: ran');
+  for (const stepResult of result.steps) console.log(describeStep(stepResult));
+}

package/src/cli/index.js

@@ -12,6 +12,7 @@ import { runTelemetry } from './commands/telemetry.js';
 import { runFeedback } from './commands/feedback.js';
 import { runPlaybook } from './commands/playbook.js';
 import { runDecision } from './commands/decision.js';
+import { runSelfImproveCommand } from './commands/selfImprove.js';
 const GLOBAL_FLAGS = new Set(['--help', '-h', '--version', '-v']);
 
 export async function runCli({ argv, packageRoot, projectRoot, packageVersion }) {
@@ -89,6 +90,11 @@ export async function runCli({ argv, packageRoot, projectRoot, packageVersion })
     return;
   }
 
+  if (command === 'self-improve') {
+    await runSelfImproveCommand({ projectRoot, argv: commandArgv });
+    return;
+  }
+
   if (command === 'update') {
     await runUpdate({ packageVersion, argv: commandArgv });
     return;
@@ -131,6 +137,7 @@ export async function runCli({ argv, packageRoot, projectRoot, packageVersion })
     console.log('  metrics            Telemetry roll-up (route outcomes, failure patterns, memory)');
     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('  update             Upgrade the global UKit CLI to the latest version');
     console.log('  version            Show UKit version');
     console.log('');

package/src/core/memory/episodes.js

@@ -0,0 +1,168 @@
+// episodes.js — session episode records from exec-ledgers (SPEC §7b).
+//
+// One episode per exec-ledger file, keyed (and deduped) by the ledger file
+// name. Shared by `ukit memory episode` (single session) and the self-improve
+// cycle (backfill every idle ledger), so the record shape has one owner.
+//
+// Engine-agnostic by construction: the self-improve backfill walks the ledger
+// directory instead of trusting a stop event's session id — omp's
+// `session_stop` id and the session key its tool events write under can
+// differ, and Codex has no stop event at all.
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { loadRecords } from './storeV2.js';
+import { mutateMemory } from './mutateMemory.js';
+import { detectProjectContext } from '../../context/detectProjectContext.js';
+import { listLedgerFiles, LEDGER_DIR_REL } from '../../diagnostics/ledgerFiles.js';
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+// Mirrors execution-ledger.mjs safeSegment — src/ cannot import the runtime
+// module, so the segment rule is duplicated deliberately.
+export function safeSegment(value) {
+  return String(value || 'default')
+    .trim()
+    .replace(/[^a-zA-Z0-9._-]/g, '_')
+    .slice(0, 96) || 'default';
+}
+
+async function readJsonIfExists(filePath) {
+  try {
+    return JSON.parse(await fs.readFile(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+// Resolution order: explicit session id → most-recent ledger.
+export async function resolveLedger(projectRoot, sessionId) {
+  const dir = path.join(projectRoot, LEDGER_DIR_REL);
+  if (sessionId) {
+    const file = `${safeSegment(sessionId)}.json`;
+    const ledger = await readJsonIfExists(path.join(dir, file));
+    return { ledger, ledgerKey: file };
+  }
+  const [name] = await listLedgerFiles(dir, 1);
+  if (!name) return { ledger: null, ledgerKey: null };
+  return { ledger: await readJsonIfExists(path.join(dir, name)), ledgerKey: name };
+}
+
+export function episodeText(ledger, sessionId) {
+  const write = ledger.writeSucceeded === true ? 'writeOk' : 'writeFail';
+  const verify = ledger.verificationAttempted !== true
+    ? 'not-run'
+    : ledger.verificationSucceeded === true ? 'ok' : 'fail';
+  const receipts = Array.isArray(ledger.receipts) ? ledger.receipts : [];
+  const lastReceipt = receipts.length > 0 ? receipts[receipts.length - 1] : null;
+  const lastCommand = lastReceipt
+    ? String(lastReceipt?.command ?? '').split('\n')[0].trim() || 'n/a'
+    : 'n/a';
+  const text = `Session ${sessionId}: ${write}, verify=${verify}, `
+    + `${receipts.length} receipts, last command ${lastCommand}`;
+  return text.slice(0, 300);
+}
+
+function ledgerSessionId(ledger, ledgerKey) {
+  return ledger.sessionId ?? ledger.sessionKey
+    ?? (ledgerKey ? ledgerKey.replace(/\.json$/, '') : 'unknown');
+}
+
+// Writes one episode for `ledger`. Returns
+//   { status: 'recorded', id, sessionId } | { status: 'duplicate' }
+//   | { status: 'rejected', result } | { status: 'failed', reason }.
+// `existingKeys` (Set of ledgerKeys already recorded) skips the store read
+// when the caller batches.
+export async function writeEpisode(projectRoot, {
+  ledger,
+  ledgerKey,
+  config,
+  homeDir,
+  projectId,
+  existingKeys,
+} = {}) {
+  const sessionId = ledgerSessionId(ledger, ledgerKey);
+  const keys = existingKeys ?? new Set(
+    (await loadRecords(projectRoot, { homeDir })).map((r) => r.meta?.ledgerKey).filter(Boolean),
+  );
+  if (keys.has(ledgerKey)) return { status: 'duplicate' };
+
+  const ttlDays = Number(config?.memoryV2?.episodeTtlDays) || 90;
+  const resolvedProjectId = projectId
+    ?? (await detectProjectContext(projectRoot, { homeDir })).project.name;
+  // FR-023: the ledger key is the idempotency key — a rerun is a journal
+  // 'duplicate' even when the meta.ledgerKey fast path above is bypassed.
+  const res = await mutateMemory(
+    { kind: 'project', projectRoot, homeDir },
+    {
+      op: 'add',
+      idempotencyKey: ledgerKey,
+      payload: {
+        type: 'episode',
+        scope: 'session',
+        text: episodeText(ledger, sessionId),
+        provenance: 'exec-ledger',
+        confidence: 0.6,
+        createdBy: 'episode-hook',
+        projectId: resolvedProjectId,
+        validUntil: Date.now() + ttlDays * DAY_MS,
+        meta: { sessionId, ledgerKey },
+      },
+    },
+  );
+  if (res.status === 'duplicate') return { status: 'duplicate' };
+  if (res.status === 'rejected') return { status: 'rejected', result: res };
+  if (res.status !== 'ok') {
+    return { status: 'failed', reason: `${res.status}${res.reason ? ` — ${res.reason}` : ''}` };
+  }
+  keys.add(ledgerKey);
+  return { status: 'recorded', id: res.record.id, sessionId };
+}
+
+// Backfills an episode for every ledger that has been idle for `idleMs`
+// (so a live session is never summarized mid-flight) and has none yet.
+// Bounded by `limit` newest ledgers; never throws.
+export async function backfillEpisodes(projectRoot, {
+  config,
+  homeDir,
+  idleMs = 10 * 60 * 1000,
+  limit = 50,
+  now = Date.now(),
+} = {}) {
+  const summary = { scanned: 0, recorded: 0, skipped: 0, failed: 0 };
+  try {
+    if (config?.memoryV2?.enabled === false || config?.learning?.episodes?.autoWrite === false) {
+      return { ...summary, reason: 'disabled' };
+    }
+    const dir = path.join(projectRoot, LEDGER_DIR_REL);
+    const names = await listLedgerFiles(dir, limit);
+    if (names.length === 0) return summary;
+    const existingKeys = new Set(
+      (await loadRecords(projectRoot, { homeDir })).map((r) => r.meta?.ledgerKey).filter(Boolean),
+    );
+    const projectId = (await detectProjectContext(projectRoot, { homeDir })).project.name;
+    for (const name of names) {
+      summary.scanned += 1;
+      if (existingKeys.has(name)) { summary.skipped += 1; continue; }
+      let stat;
+      try { stat = await fs.stat(path.join(dir, name)); } catch { summary.skipped += 1; continue; }
+      if (now - stat.mtimeMs < idleMs) { summary.skipped += 1; continue; }
+      const ledger = await readJsonIfExists(path.join(dir, name));
+      const receipts = Array.isArray(ledger?.receipts) ? ledger.receipts.length : 0;
+      if (!ledger || (receipts === 0 && ledger.writeSucceeded !== true)) {
+        summary.skipped += 1;
+        continue;
+      }
+      const res = await writeEpisode(projectRoot, {
+        ledger, ledgerKey: name, config, homeDir, projectId, existingKeys,
+      });
+      if (res.status === 'recorded') summary.recorded += 1;
+      else if (res.status === 'duplicate') summary.skipped += 1;
+      else summary.failed += 1;
+    }
+  } catch (error) {
+    return { ...summary, reason: error?.message ?? String(error) };
+  }
+  return summary;
+}

package/src/core/metadata.js

@@ -114,6 +114,27 @@ export async function writeInstallMetadata({
   }
 }
 
+export const CLI_LOCATOR_REL = path.join('.ukit', 'storage', 'cli.json');
+
+// `.ukit/storage/cli.json` — absolute node + CLI entry of the install that
+// last refreshed this project. Read by .claude/ukit/runtime/ukit-cli.mjs so
+// hook-side CLI spawns work without `ukit` on the host's PATH. Advisory:
+// a write failure only degrades hooks back to the PATH lookup.
+export async function writeCliLocator({ projectRoot, packageRoot, packageVersion }) {
+  if (!projectRoot || !packageRoot) return false;
+  try {
+    await writeJson(path.join(projectRoot, CLI_LOCATOR_REL), {
+      node: process.execPath,
+      bin: path.join(path.resolve(packageRoot), 'bin', 'ukit'),
+      version: packageVersion ?? null,
+      writtenAt: new Date().toISOString(),
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 export async function removeTrackedPathsFromMetadata({
   installMetaPath,
   projectRoot,

package/src/core/runInstallPipeline.js

@@ -10,7 +10,7 @@ import { buildInstallPlan } from './buildPlan.js';
 import { diffInstallPlan } from './diffPlan.js';
 import { applyDiffResults, pruneOldBackups } from './applyPlan.js';
 import { summarizeDiff, toDiffRows } from './report.js';
-import { writeInstallMetadata } from './metadata.js';
+import { writeInstallMetadata, writeCliLocator } from './metadata.js';
 import { cleanupLegacyPaths, migrateLegacyRuntimeRoot } from './migrateLegacy.js';
 import { ensureGitignore } from './ensureGitignore.js';
 import { repairBrokenHooks } from './repairBrokenHooks.js';
@@ -477,6 +477,11 @@ export async function runInstallPipeline({
       retainedManagedRelativePaths,
     });
 
+    // 3.3.0: hooks spawn the CLI (episodes, self-improve) from a GUI-launched
+    // host whose PATH often lacks nvm/volta shims — `ukit` on PATH silently
+    // failed. Record the absolute node + bin path of THIS install instead.
+    await writeCliLocator({ projectRoot: pathConfig.projectRoot, packageRoot: pathConfig.packageRoot, packageVersion });
+
     const { userLayer, userRows } = await runUserLayerPass({
       pathConfig,
       homeDir,

package/src/core/runtimeConfig.js

@@ -5,6 +5,7 @@ import { buildRuntimePaths } from './runtimePaths.js';
 import { buildUserPaths } from './userPaths.js';
 import { loadShippedCompactBudget } from './compact/contextBudget.js';
 import { buildConfigContracts } from './executionContracts.js';
+import { mergeTunedOverlay } from '../learning/tunedOverlay.js';
 
 const require = createRequire(import.meta.url);
 const { version: PACKAGE_VERSION } = require('../../package.json');
@@ -299,11 +300,14 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
     },
     // M01.1 stage keys (docs/pstack/MIGRATION_ROLLBACK named-keys table). Every stage
     // key treats absence as "off"; stages promote off -> shadow -> canary -> default.
+    // 3.3.0 zero-config: every routing stage ships 'default'. escalation at
+    // 'default' enforces verification evidence at Stop for high-risk routes —
+    // self-healing (run the verification), never a hard deadlock.
     routing: {
-      routeSchema: { stage: 'off' },
-      rigor: { stage: 'off' },
-      fastPath: { stage: 'off' },
-      escalation: { stage: 'off' },
+      routeSchema: { stage: 'default' },
+      rigor: { stage: 'default' },
+      fastPath: { stage: 'default' },
+      escalation: { stage: 'default' },
     },
     // C52 M07: `unic-decision` is the owner's local non-LLM Lava/JEV model in
     // UNIC Provider. Its OpenAI-compatible API is transport only, not proof of
@@ -413,13 +417,12 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
       promotion: { episodeToRuleRequiresApproval: true },
       recall: { maxRecords: 8 },
       // M06 rollout flags (SPEC §5 FR-001): per-plane stage on the shared
-      // off→shadow→canary→default ladder. eligibility/writer/index ship
-      // 'default' (the w1-2 path is the shipped behavior); decision ships
-      // 'off' — plumbing only, no consumer yet. killSwitch is absolute.
+      // off→shadow→canary→default ladder. 3.3.0 zero-config: every plane
+      // ships 'default'. killSwitch is absolute.
       eligibility: { stage: 'default' },
       writer: { stage: 'default' },
       index: { stage: 'default' },
-      decision: { stage: 'off' },
+      decision: { stage: 'default' },
       canaryProjects: [],
       killSwitch: false,
     },
@@ -438,26 +441,29 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
       maxRetries: 1,
       confidenceThreshold: 50,
     },
-    // Phase-4 learning loop (SPEC §8a). Advisory only — applyMode 'manual'
-    // means suggestions are computed + persisted, never auto-applied.
+    // Phase-4 learning loop (SPEC §8a). 3.3.0 zero-config: applyMode 'auto'
+    // lets the self-improve cycle apply clamped one-step tuning through the
+    // .ukit/storage/learning/tuned.json overlay (src/learning/tunedOverlay.js);
+    // 'manual' = suggestions only, 'off' = nothing computed.
     learning: {
       feedback: { enabled: true, maxEvents: 200 },
       proposals: { minCount: 3, minSessions: 2 },
       episodes: { autoWrite: true },
-      tuning: { enabled: true, applyMode: 'manual' },
+      tuning: { enabled: true, applyMode: 'auto' },
+      // 3.3.0: automatic collect → learn → apply pass (src/learning/selfImprove.js).
+      selfImprove: { enabled: true },
       // 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; report-only at
-      // 'shadow'. overlays: delta overlays on policy fields; base-version
-      // mismatch → conflict, never silent apply. Promotion stays manual.
-      candidates: { stage: 'shadow', minOccurrences: 3 },
-      overlays: { stage: 'off' },
+      // only after minOccurrences + cross-session evidence (status
+      // 'proposed'; rule promotion still needs approval). overlays: only
+      // approved + enabled overlays apply; base-version mismatch → conflict.
+      candidates: { stage: 'default', minOccurrences: 3 },
+      overlays: { stage: 'default' },
     },
-    // C52 M04.1 compact resumable state (SPEC §5 FR-012–FR-015). Stage 'off'
-    // → no resumable-run records written or consumed; resume falls back to
-    // the existing reinject path.
+    // C52 M04.1 compact resumable state (SPEC §5 FR-012–FR-015): a bounded
+    // resumable-run record per route so a compacted session resumes mid-task.
     continuity: {
-      resumableRun: { stage: 'off' },
+      resumableRun: { stage: 'default' },
     },
     // C63 DR-02 + C64 DR-03/04 + C66 DR-06 + C67 DR-07/08 + C69 DR-10
     // decision-first-runtime (SPEC §2 G1-FR07, §2 G2-FR07/08, §2 G4-FR07,
@@ -471,29 +477,35 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
     // gates the G6 caller-wait promotion profile and
     // `decisionRuntime.resourcePolicy` gates the G6 pressure/coalescing
     // policy; `decisionRuntime.diagnostics` gates the G7 explainable-trace /
-    // replay / support-record readers. Absence or malformed stage resolves
-    // 'off' → zero files under .ukit/storage/agent-runtime/, zero behavior
-    // change.
+    // replay / support-record readers. 3.3.0 zero-config: every family ships
+    // 'shadow' — evidence is recorded while the deterministic owners stay
+    // authoritative; promotion.js promotes a family only once its frozen
+    // PROMOTION_CRITERIA hold on sampled runs. diagnostics ships 'default'
+    // (sanitized support records, explicit CLI act).
     decisionRuntime: {
-      contract: { stage: 'off' },
-      supervisor: { stage: 'off' },
-      scheduler: { stage: 'off' },
-      vm: { stage: 'off' },
-      adapters: { stage: 'off' },
-      context: { stage: 'off' },
-      completion: { stage: 'off' },
-      quality: { stage: 'off' },
-      promotion: { stage: 'off' },
-      resourcePolicy: { stage: 'off' },
-      diagnostics: { stage: 'off' },
+      contract: { stage: 'shadow' },
+      supervisor: { stage: 'shadow' },
+      scheduler: { stage: 'shadow' },
+      vm: { stage: 'shadow' },
+      adapters: { stage: 'shadow' },
+      context: { stage: 'shadow' },
+      completion: { stage: 'shadow' },
+      quality: { stage: 'shadow' },
+      promotion: { stage: 'shadow' },
+      resourcePolicy: { stage: 'shadow' },
+      diagnostics: { stage: 'default' },
     },
 
-    // C52 M06 experiments (SPEC §5 FR-021–FR-023). Disabled by default —
-    // zero calls and zero prompt content when off; no auto-promotion.
+    // C52 M06 experiments (SPEC §5 FR-021–FR-023). 3.3.0 zero-config: enabled;
+    // each experiment still runs only where a caller invokes it and never
+    // auto-promotes its own result.
     experiments: {
-      deliberation: { enabled: false },
-      dynamicWorkflow: { enabled: false, maxAttemptsPerFailure: 2, noProgressCap: 3 },
+      deliberation: { enabled: true },
+      dynamicWorkflow: { enabled: true, maxAttemptsPerFailure: 2, noProgressCap: 3 },
     },
+    // Flight recorder (docs/OBSERVABILITY.md): 'default' activates recorder,
+    // analytics, support projection and evaluation. 'off' is the kill switch.
+    observability: { stage: 'default' },
     safePatch: {
       enabled: true,
       strictSharedRisk: true,
@@ -1091,12 +1103,19 @@ export function validateRuntimeConfig(config) {
           errors.push('learning.tuning must be an object.');
         } else {
           pushBooleanError(errors, learning.tuning.enabled, 'learning.tuning.enabled');
-          const VALID_APPLY_MODES = new Set(['manual', 'off']);
+          const VALID_APPLY_MODES = new Set(['auto', 'manual', 'off']);
           if (!VALID_APPLY_MODES.has(learning.tuning.applyMode)) {
             errors.push(`learning.tuning.applyMode must be one of: ${[...VALID_APPLY_MODES].join(', ')}.`);
           }
         }
       }
+      if (learning.selfImprove !== undefined) {
+        if (!isPlainObject(learning.selfImprove)) {
+          errors.push('learning.selfImprove must be an object.');
+        } else {
+          pushBooleanError(errors, learning.selfImprove.enabled, 'learning.selfImprove.enabled');
+        }
+      }
       // C52 M04.2 stage keys — same optional-present contract as routing.*.
       if (learning.candidates !== undefined) {
         if (!isPlainObject(learning.candidates)) {
@@ -1191,7 +1210,7 @@ export async function inspectRuntimeConfig(projectRoot, { homeDir } = {}) {
 
   const user = await readUserConfig(homeDir);
   const userLayer = user.parseError ? null : stripProjectManagedKeys(user.rawConfig);
-  const mergedRaw = mergeObjects(userLayer ?? {}, rawConfig ?? {});
+  const mergedRaw = await mergeTunedOverlay(projectRoot, mergeObjects(userLayer ?? {}, rawConfig ?? {}));
 
   const config = normalizeLegacyOpencodeEntries(buildDefaultRuntimeConfig(mergedRaw));
   const validation = validateRuntimeConfig(config);

package/src/learning/selfImprove.js

@@ -0,0 +1,205 @@
+// selfImprove.js — the automatic collect → learn → apply cycle (3.3.0).
+//
+// One bounded pass that turns what hooks already record into memory,
+// diagnostics, tuning, and the flight recorder — no human command needed.
+// Triggered detached by `.claude/ukit/runtime/self-improve-trigger.mjs` from
+// Claude SessionEnd, omp session_stop, and route-task.mjs (the Codex helper
+// path), and runnable by hand via `ukit self-improve`.
+//
+// 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
+//                   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
+//                   candidates (rules still need `ukit memory approve`)
+//   5. telemetry  — ingest stored hook/ledger telemetry, flush, refresh the
+//                   support view
+//
+// Guards: `.ukit/storage/learning/self-improve.json` stamp rate-limits the
+// pass (minIntervalMs, default 10 min) and a file lock keeps two triggers from
+// overlapping. Never throws.
+
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import { inspectRuntimeConfig } from '../core/runtimeConfig.js';
+import { withFileLock } from '../core/fileOps.js';
+import { detectProjectContext } from '../context/detectProjectContext.js';
+import { backfillEpisodes } from '../core/memory/episodes.js';
+import { mineFailurePatterns } from '../diagnostics/failurePatterns.js';
+import { collectFeedbackEvents } from '../diagnostics/feedbackEvents.js';
+import { collectSkillAccuracy } from '../diagnostics/skillAccuracy.js';
+import { computeTuningSuggestions } from './tuning.js';
+import { proposeFromPatterns } from './patternProposals.js';
+import {
+  TUNABLE_KEYS,
+  clampTunable,
+  readTunedDocument,
+  resolveApplyMode,
+  writeTunedDocument,
+} from './tunedOverlay.js';
+
+export const STAMP_REL = path.join('.ukit', 'storage', 'learning', 'self-improve.json');
+export const DEFAULT_MIN_INTERVAL_MS = 10 * 60 * 1000;
+// A tuned key moves at most one step per cooldown window.
+export const TUNING_COOLDOWN_MS = 24 * 60 * 60 * 1000;
+const TELEMETRY_DEADLINE_MS = 30_000;
+const FLUSH_DEADLINE_MS = 10_000;
+
+async function readJson(filePath) {
+  try {
+    return JSON.parse(await fs.readFile(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+async function writeJsonAtomic(filePath, value) {
+  const tmp = `${filePath}.tmp-${process.pid}`;
+  try {
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.writeFile(tmp, `${JSON.stringify(value, null, 2)}\n`);
+    await fs.rename(tmp, filePath);
+  } catch {
+    await fs.rm(tmp, { force: true }).catch(() => {});
+  }
+}
+
+async function step(name, fn) {
+  try {
+    return { name, ...(await fn()) };
+  } catch (error) {
+    return { name, status: 'failed', reason: error?.message ?? String(error) };
+  }
+}
+
+// Applies tuning suggestions to the overlay. Pure over its inputs apart from
+// the overlay write, so it is testable without the rest of the cycle.
+export async function applyTuning(projectRoot, suggestions, { now = Date.now() } = {}) {
+  const doc = (await readTunedDocument(projectRoot))
+    ?? { overrides: {}, lastAppliedAt: {}, history: [] };
+  const applied = [];
+  for (const suggestion of Array.isArray(suggestions) ? suggestions : []) {
+    const key = suggestion?.target;
+    if (!TUNABLE_KEYS[key]) continue;
+    const last = Number(doc.lastAppliedAt[key]);
+    if (Number.isFinite(last) && now - last < TUNING_COOLDOWN_MS) continue;
+    const value = clampTunable(key, suggestion.suggested);
+    if (value === null || doc.overrides[key] === value) continue;
+    const from = doc.overrides[key] ?? suggestion.current ?? null;
+    doc.overrides[key] = value;
+    doc.lastAppliedAt[key] = now;
+    doc.history.push({
+      at: new Date(now).toISOString(),
+      key,
+      from,
+      to: value,
+      reason: suggestion?.evidence?.reason ?? null,
+    });
+    applied.push({ key, from, to: value });
+  }
+  if (applied.length > 0) {
+    doc.history = doc.history.slice(-50);
+    await writeTunedDocument(projectRoot, doc);
+  }
+  return applied;
+}
+
+async function collectTelemetry(projectRoot, config) {
+  const { resolveStage } = await import('../core/observability/emit/config.js');
+  if (resolveStage(config) === 'off') return { status: 'skipped', reason: 'stage_off' };
+  const { getRecorder, segmentsRoot } = await import('../core/observability/emit/lifecycle.js');
+  const { ingestStoredTelemetry } = await import('../core/observability/adapters/ingest.js');
+  const { maybeRefreshSupport } = await import('../core/observability/support/schedule.js');
+  await fs.mkdir(segmentsRoot(projectRoot), { recursive: true });
+  const recorder = getRecorder({ projectRoot, config });
+  const ingest = await ingestStoredTelemetry({ projectRoot, recorder, deadlineMs: TELEMETRY_DEADLINE_MS });
+  const flush = await recorder.flush({ deadlineMs: FLUSH_DEADLINE_MS });
+  const support = await maybeRefreshSupport({ projectRoot, config, recorder });
+  const emitted = Object.values(ingest?.coverage ?? {})
+    .reduce((sum, cov) => sum + (Number(cov?.emitted) || 0), 0);
+  return {
+    status: ingest?.ok === true ? ingest.status : 'failed',
+    emitted,
+    written: flush?.written ?? 0,
+    support: support?.status ?? 'unknown',
+  };
+}
+
+/**
+ * Run one self-improve pass.
+ * @param {string} projectRoot
+ * @param {{ force?: boolean, homeDir?: string, now?: number, minIntervalMs?: number }} [opts]
+ * @returns {Promise<{status: 'ran'|'skipped', reason?: string, steps?: object[]}>}
+ */
+export async function runSelfImprove(projectRoot, {
+  force = false,
+  homeDir = os.homedir(),
+  now = Date.now(),
+  minIntervalMs = DEFAULT_MIN_INTERVAL_MS,
+} = {}) {
+  const root = path.resolve(projectRoot);
+  const stampPath = path.join(root, STAMP_REL);
+  try {
+    const { config, rawConfig } = await inspectRuntimeConfig(root, { homeDir });
+    if (config?.learning?.selfImprove?.enabled === false) {
+      return { status: 'skipped', reason: 'disabled' };
+    }
+    const stamp = await readJson(stampPath);
+    const lastRunAt = Date.parse(stamp?.lastRunAt ?? '');
+    if (!force && Number.isFinite(lastRunAt) && now - lastRunAt < minIntervalMs) {
+      return { status: 'skipped', reason: 'min_interval' };
+    }
+
+    const outcome = await withFileLock(stampPath, async () => {
+      const steps = [];
+      steps.push(await step('episodes', async () => {
+        const res = await backfillEpisodes(root, { config, homeDir, now });
+        return { status: res.reason ? 'skipped' : 'ok', ...res };
+      }));
+      steps.push(await step('diagnostics', async () => {
+        const patterns = await mineFailurePatterns(root);
+        const feedback = await collectFeedbackEvents(root);
+        const skills = await collectSkillAccuracy(root);
+        return {
+          status: 'ok',
+          patterns: Array.isArray(patterns?.patterns) ? patterns.patterns.length : 0,
+          feedbackEvents: Array.isArray(feedback?.events) ? feedback.events.length : 0,
+          skills: Object.keys(skills?.skills ?? {}).length,
+        };
+      }));
+      steps.push(await step('tuning', async () => {
+        const result = await computeTuningSuggestions(root);
+        const mode = resolveApplyMode(rawConfig ?? {});
+        const applied = mode === 'auto' ? await applyTuning(root, result.suggestions, { now }) : [];
+        return { status: 'ok', mode, suggestions: result.suggestions.length, applied };
+      }));
+      steps.push(await step('proposals', async () => {
+        const projectId = (await detectProjectContext(root, { homeDir })).project.name;
+        const minCount = Number(config?.learning?.proposals?.minCount) || undefined;
+        const res = await proposeFromPatterns(root, projectId, { minCount, dryRun: false });
+        return {
+          status: res.error ? 'failed' : 'ok',
+          proposed: res.proposed.filter((p) => p.status === 'proposed').length,
+          reason: res.error,
+        };
+      }));
+      steps.push(await step('telemetry', () => collectTelemetry(root, config)));
+
+      await writeJsonAtomic(stampPath, {
+        lastRunAt: new Date(now).toISOString(),
+        steps,
+      });
+      return steps;
+    }, { maxWaitMs: 500 });
+
+    if (outcome === undefined) return { status: 'skipped', reason: 'locked' };
+    return { status: 'ran', steps: outcome };
+  } catch (error) {
+    return { status: 'skipped', reason: error?.message ?? String(error) };
+  }
+}

package/src/learning/tunedOverlay.js

@@ -0,0 +1,112 @@
+// tunedOverlay.js — auto-applied tuning overlay (learning.tuning.applyMode 'auto').
+//
+// The self-improve cycle writes clamped one-step tuning changes to
+// `.ukit/storage/learning/tuned.json`; runtime config readers merge the
+// overlay over the project config. The file lives outside the install-managed
+// `config.json`, so a reinstall never erases learned values, and deleting the
+// file (or setting applyMode 'manual'|'off') is a complete rollback.
+//
+// Contract:
+//   * Only TUNABLE_KEYS are honored; every value is clamped to its bounds on
+//     read, so a hand-edited or corrupt overlay can never push a key outside
+//     the range the tuner itself is allowed to reach.
+//   * Never throws: missing/corrupt overlay → no overrides.
+//   * Merge point: inspectRuntimeConfig (src/core/runtimeConfig.js) applies
+//     the overlay after the user+project merge, before defaults/validation.
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+export const TUNED_REL = path.join('.ukit', 'storage', 'learning', 'tuned.json');
+export const TUNED_VERSION = 1;
+
+export const TUNABLE_KEYS = Object.freeze({
+  'codeIntel.retriever.weights.exact': { min: 0.1, max: 2.0 },
+  'codeIntel.retriever.weights.symbol': { min: 0.1, max: 2.0 },
+  'codeIntel.retriever.weights.bm25': { min: 0.1, max: 2.0 },
+  'codeIntel.retriever.weights.semantic': { min: 0.1, max: 2.0 },
+  'codeIntel.retriever.weights.vector': { min: 0.1, max: 2.0 },
+  'orchestration.escalation.debugLoopThreshold': { min: 1, max: 5, integer: true },
+});
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+export function clampTunable(key, value) {
+  const spec = TUNABLE_KEYS[key];
+  if (!spec || typeof value !== 'number' || !Number.isFinite(value)) return null;
+  const clamped = Math.min(spec.max, Math.max(spec.min, value));
+  return spec.integer ? Math.round(clamped) : Math.round(clamped * 100) / 100;
+}
+
+export function sanitizeOverrides(raw) {
+  const out = {};
+  if (!isPlainObject(raw)) return out;
+  for (const [key, value] of Object.entries(raw)) {
+    const clamped = clampTunable(key, value);
+    if (clamped !== null) out[key] = clamped;
+  }
+  return out;
+}
+
+export async function readTunedDocument(projectRoot) {
+  try {
+    const doc = JSON.parse(await fs.readFile(path.join(projectRoot, TUNED_REL), 'utf8'));
+    if (!isPlainObject(doc)) return null;
+    return {
+      version: TUNED_VERSION,
+      overrides: sanitizeOverrides(doc.overrides),
+      lastAppliedAt: isPlainObject(doc.lastAppliedAt) ? doc.lastAppliedAt : {},
+      history: Array.isArray(doc.history) ? doc.history.slice(-50) : [],
+    };
+  } catch {
+    return null;
+  }
+}
+
+export async function writeTunedDocument(projectRoot, doc) {
+  const filePath = path.join(projectRoot, TUNED_REL);
+  const tmp = `${filePath}.tmp-${process.pid}`;
+  try {
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.writeFile(tmp, `${JSON.stringify({ ...doc, version: TUNED_VERSION }, null, 2)}\n`);
+    await fs.rename(tmp, filePath);
+    return true;
+  } catch {
+    await fs.rm(tmp, { force: true }).catch(() => {});
+    return false;
+  }
+}
+
+// Resolves the effective apply mode from a raw (pre-default) config object:
+// absent → 'auto' (the shipped default).
+export function resolveApplyMode(rawConfig) {
+  const tuning = rawConfig?.learning?.tuning;
+  if (tuning?.enabled === false) return 'off';
+  const mode = tuning?.applyMode;
+  return mode === 'manual' || mode === 'off' || mode === 'auto' ? mode : 'auto';
+}
+
+// Returns a copy of `config` with `overrides` set at their dotted paths.
+export function applyOverrides(config, overrides) {
+  if (!isPlainObject(overrides) || Object.keys(overrides).length === 0) return config;
+  const next = structuredClone(isPlainObject(config) ? config : {});
+  for (const [key, value] of Object.entries(overrides)) {
+    const parts = key.split('.');
+    let node = next;
+    for (const part of parts.slice(0, -1)) {
+      if (!isPlainObject(node[part])) node[part] = {};
+      node = node[part];
+    }
+    node[parts[parts.length - 1]] = value;
+  }
+  return next;
+}
+
+// Merge helper for config readers: overlay applies only in 'auto' mode.
+export async function mergeTunedOverlay(projectRoot, rawConfig) {
+  if (resolveApplyMode(rawConfig) !== 'auto') return rawConfig;
+  const doc = await readTunedDocument(projectRoot);
+  return doc ? applyOverrides(rawConfig, doc.overrides) : rawConfig;
+}

package/template_project/.claude/hooks/session-episode.sh

@@ -112,25 +112,45 @@ try {
 const config = readJson(configPath) || {};
 if (config?.learning?.episodes?.autoWrite !== true) process.exit(0);
 
-const probe = spawnSync("ukit", ["--version"], {
-  shell: true, stdio: "ignore", timeout: 2000,
-});
-if (probe.error || probe.status === null || probe.status === undefined) process.exit(0);
-
 const sessionId = typeof payload.session_id === "string" && payload.session_id.trim()
   ? payload.session_id.trim()
   : null;
 
-spawnSync("ukit", ["memory", "episode"], {
-  shell: true,
-  stdio: "ignore",
-  timeout: 4000,
-  cwd: projectRoot,
-  env: sessionId
-    ? { ...process.env, UKIT_SESSION_ID: sessionId }
-    : process.env,
-});
-' "$UKIT_INPUT_FILE" "$CONFIG_FILE" "$PROJECT_ROOT" 2>/dev/null || true
+(async () => {
+  // 3.3.0: prefer the absolute node + CLI recorded by `ukit install`
+  // (.ukit/storage/cli.json, validated by resolveCliLocator) — GUI-launched
+  // hosts often lack nvm/volta on PATH, which made the bare `ukit` spawn fail
+  // silently. PATH lookup stays the fallback for pre-locator installs.
+  let trigger = null;
+  try {
+    trigger = await import(require("url").pathToFileURL(process.argv[4]).href);
+  } catch {}
+  const located = trigger?.resolveCliLocator?.(projectRoot) ?? null;
+  const cli = located
+    ? { cmd: located.node, pre: [located.bin], shell: false }
+    : { cmd: "ukit", pre: [], shell: true };
+
+  const probe = spawnSync(cli.cmd, [...cli.pre, "--version"], {
+    shell: cli.shell, stdio: "ignore", timeout: 2000,
+  });
+  if (probe.error || probe.status === null || probe.status === undefined) return;
+
+  spawnSync(cli.cmd, [...cli.pre, "memory", "episode"], {
+    shell: cli.shell,
+    stdio: "ignore",
+    timeout: 4000,
+    cwd: projectRoot,
+    env: sessionId
+      ? { ...process.env, UKIT_SESSION_ID: sessionId }
+      : process.env,
+  });
+
+  // Detached self-improve pass (episode backfill for sessions whose stop id
+  // did not match their ledger, diagnostics, auto-tuning, telemetry
+  // collect). Returns in ms; rate-limited inside the trigger.
+  trigger?.triggerSelfImprove?.({ projectRoot });
+})().catch(() => {}).finally(() => process.exit(0));
+' "$UKIT_INPUT_FILE" "$CONFIG_FILE" "$PROJECT_ROOT" "$SCRIPT_DIR/../ukit/runtime/self-improve-trigger.mjs" 2>/dev/null || true
 
 rm -f "$UKIT_INPUT_FILE" 2>/dev/null || true
 exit 0

package/template_project/.claude/ukit/index/route-task.mjs

@@ -1722,6 +1722,19 @@ async function main() {
   }
 
   printRouteState(sharedState);
+
+  // 3.3.0: Codex has no hook lifecycle — route-task is the one helper it runs
+  // per task, so it doubles as the self-improve trigger there. Fire-and-forget:
+  // detached child, rate-limited inside the trigger, never throws. Opt out
+  // with UKIT_SELF_IMPROVE=0 (tests/CI) or learning.selfImprove.enabled:false.
+  if (process.env.UKIT_SELF_IMPROVE !== '0') {
+    try {
+      const { triggerSelfImprove } = await import('../runtime/self-improve-trigger.mjs');
+      triggerSelfImprove({ projectRoot: rootDir });
+    } catch {
+      // background work only — a missing/broken trigger never affects routing
+    }
+  }
 }
 
 async function ensureFreshIndex({ rootDir, logPrefix, signal = null, deadlineMs = null, discoverySnapshot = null } = {}) {

package/template_project/.claude/ukit/runtime/self-improve-trigger.mjs

@@ -0,0 +1,98 @@
+// self-improve-trigger.mjs — fire-and-forget launcher for `ukit self-improve`.
+//
+// Called from every engine's natural lifecycle point:
+//   * Claude Code  — SessionEnd  (session-episode.sh)
+//   * omp          — session_stop (same script via ukit-bridge.js)
+//   * Codex        — route-task.mjs, the helperCommand Codex runs per task
+//                    (Codex has no hook lifecycle)
+//
+// Contract:
+//   * NEVER blocks the caller: the CLI runs detached (own process group,
+//     stdio ignored, unref'd); this module returns in a few ms.
+//   * NEVER throws; every failure is a silent no-op — self-improvement is
+//     background work and must not add noise to a user's session.
+//   * Cheap gates first: config opt-out (learning.selfImprove.enabled:false),
+//     the pass's own rate-limit stamp, and the CLI locator. The locator
+//     (.ukit/storage/cli.json, written by `ukit install`) holds absolute
+//     node + bin paths, so GUI-launched hosts without nvm on PATH still work;
+//     without it there is no trusted CLI to launch and the trigger no-ops.
+//
+// CLI: node self-improve-trigger.mjs [projectRoot]
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+export const MIN_INTERVAL_MS = 10 * 60 * 1000;
+
+function readJson(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+// The locator is a project file: never trust it blindly. `bin` must be the
+// `bin/ukit` of a directory whose package.json names @ngockhoale/ukit, and
+// `node` must be a node executable — a committed/forged cli.json cannot turn
+// the trigger into an arbitrary-binary launcher.
+export function resolveCliLocator(projectRoot) {
+  const locator = readJson(path.join(projectRoot, '.ukit', 'storage', 'cli.json'));
+  if (!locator || typeof locator.node !== 'string' || typeof locator.bin !== 'string') return null;
+  if (!/^node(\.exe)?$/i.test(path.basename(locator.node))) return null;
+  if (path.basename(locator.bin) !== 'ukit' || path.basename(path.dirname(locator.bin)) !== 'bin') return null;
+  const pkg = readJson(path.join(path.dirname(locator.bin), '..', 'package.json'));
+  if (pkg?.name !== '@ngockhoale/ukit') return null;
+  if (!fs.existsSync(locator.node) || !fs.existsSync(locator.bin)) return null;
+  return { node: locator.node, bin: locator.bin };
+}
+
+export function selfImproveDue(projectRoot, now = Date.now()) {
+  const config = readJson(path.join(projectRoot, '.ukit', 'storage', 'config.json'));
+  if (config?.learning?.selfImprove?.enabled === false) return false;
+  const stamp = readJson(path.join(projectRoot, '.ukit', 'storage', 'learning', 'self-improve.json'));
+  const lastRunAt = Date.parse(stamp?.lastRunAt ?? '');
+  return !(Number.isFinite(lastRunAt) && now - lastRunAt < MIN_INTERVAL_MS);
+}
+
+// Returns true when a pass was launched.
+export function triggerSelfImprove({ projectRoot, now = Date.now(), spawnImpl = spawn } = {}) {
+  try {
+    if (typeof projectRoot !== 'string' || projectRoot.length === 0) return false;
+    const root = path.resolve(projectRoot);
+    if (!selfImproveDue(root, now)) return false;
+    const cli = resolveCliLocator(root);
+    if (!cli) return false;
+    const env = { ...process.env };
+    // Hook self-deadlines must not leak into a background pass.
+    delete env.UKIT_HOOK_DEADLINE_MS;
+    const child = spawnImpl(cli.node, [cli.bin, 'self-improve', '--if-due', '--quiet'], {
+      cwd: root,
+      env,
+      detached: true,
+      stdio: 'ignore',
+      windowsHide: true,
+    });
+    child.on?.('error', () => {});
+    child.unref?.();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function isMainModule() {
+  try {
+    const self = fs.realpathSync(fileURLToPath(import.meta.url));
+    const invoked = process.argv[1] ? fs.realpathSync(process.argv[1]) : '';
+    return self === invoked;
+  } catch {
+    return false;
+  }
+}
+
+if (isMainModule()) {
+  triggerSelfImprove({ projectRoot: process.argv[2] || process.env.CLAUDE_PROJECT_DIR || process.cwd() });
+}

package/template_project/ukit/storage/config.json

@@ -85,16 +85,16 @@
   },
   "routing": {
     "routeSchema": {
-      "stage": "off"
+      "stage": "default"
     },
     "rigor": {
-      "stage": "shadow"
+      "stage": "default"
     },
     "fastPath": {
-      "stage": "shadow"
+      "stage": "default"
     },
     "escalation": {
-      "stage": "shadow"
+      "stage": "default"
     }
   },
   "decisionPlane": {
@@ -316,7 +316,20 @@
     },
     "recall": {
       "maxRecords": 8
-    }
+    },
+    "eligibility": {
+      "stage": "default"
+    },
+    "writer": {
+      "stage": "default"
+    },
+    "index": {
+      "stage": "default"
+    },
+    "decision": {
+      "stage": "default"
+    },
+    "killSwitch": false
   },
   "memory": {
     "enabled": true,
@@ -346,31 +359,69 @@
     },
     "tuning": {
       "enabled": true,
-      "applyMode": "manual"
+      "applyMode": "auto"
+    },
+    "selfImprove": {
+      "enabled": true
     },
     "candidates": {
-      "stage": "shadow",
+      "stage": "default",
       "minOccurrences": 3
     },
     "overlays": {
-      "stage": "off"
+      "stage": "default"
     }
   },
   "continuity": {
     "resumableRun": {
-      "stage": "off"
+      "stage": "default"
     }
   },
   "experiments": {
     "deliberation": {
-      "enabled": false
+      "enabled": true
     },
     "dynamicWorkflow": {
-      "enabled": false,
+      "enabled": true,
       "maxAttemptsPerFailure": 2,
       "noProgressCap": 3
     }
   },
+  "decisionRuntime": {
+    "contract": {
+      "stage": "shadow"
+    },
+    "supervisor": {
+      "stage": "shadow"
+    },
+    "scheduler": {
+      "stage": "shadow"
+    },
+    "vm": {
+      "stage": "shadow"
+    },
+    "adapters": {
+      "stage": "shadow"
+    },
+    "context": {
+      "stage": "shadow"
+    },
+    "completion": {
+      "stage": "shadow"
+    },
+    "quality": {
+      "stage": "shadow"
+    },
+    "promotion": {
+      "stage": "shadow"
+    },
+    "resourcePolicy": {
+      "stage": "shadow"
+    },
+    "diagnostics": {
+      "stage": "default"
+    }
+  },
   "safePatch": {
     "enabled": true,
     "strictSharedRisk": true,
@@ -600,15 +651,15 @@
       },
       "tu_ghi_episode_ket_thuc_session": {
         "field": "learning.episodes.autoWrite",
-        "mac_dinh": false,
-        "y_nghia": "N\u1ebfu true, hook SessionEnd t\u1ef1 ghi episode v\u00e0o memory v2 khi k\u1ebft th\u00fac session (c\u1ea7n `ukit` c\u00f3 tr\u00ean PATH). M\u1eb7c \u0111\u1ecbnh t\u1eaft \u0111\u1ec3 tr\u00e1nh ghi memory khi user ch\u01b0a mu\u1ed1n.",
-        "khi_nao_bat": "Ch\u1ec9 b\u1eadt khi anh mu\u1ed1n UKit t\u1ef1 l\u01b0u episode m\u1ed7i session; d\u1eef li\u1ec7u v\u1eabn n\u1eb1m local trong .ukit/storage."
+        "mac_dinh": true,
+        "y_nghia": "B\u1eadt m\u1eb7c \u0111\u1ecbnh: UKit t\u1ef1 ghi episode v\u00e0o memory v2 cho m\u1ed7i session \u0111\u00e3 k\u1ebft th\u00fac (hook SessionEnd/session_stop + chu k\u1ef3 self-improve qu\u00e9t exec-ledger, ch\u1ea1y \u0111\u01b0\u1ee3c c\u1ea3 tr\u00ean Codex). D\u1eef li\u1ec7u n\u1eb1m local trong .ukit/storage.",
+        "khi_nao_bat": "Ch\u1ec9 t\u1eaft (false) khi kh\u00f4ng mu\u1ed1n UKit l\u01b0u episode."
       },
       "tat_goi_y_tuning": {
         "field": "learning.tuning.applyMode",
-        "mac_dinh": "manual",
-        "y_nghia": "manual = UKit ch\u1ec9 t\u00ednh v\u00e0 l\u01b0u g\u1ee3i \u00fd tuning v\u00e0o .ukit/storage/learning/suggestions.json, KH\u00d4NG bao gi\u1edd t\u1ef1 s\u1eeda weights/threshold. off = t\u1eaft lu\u00f4n vi\u1ec7c t\u00ednh g\u1ee3i \u00fd.",
-        "khuyen_nghi": "Gi\u1eef manual. Kh\u00f4ng c\u00f3 ch\u1ebf \u0111\u1ed9 auto-apply \u2014 m\u1ecdi thay \u0111\u1ed5i weights/threshold \u0111\u1ec1u do ng\u01b0\u1eddi d\u00f9ng t\u1ef1 s\u1eeda."
+        "mac_dinh": "auto",
+        "y_nghia": "auto (m\u1eb7c \u0111\u1ecbnh) = chu k\u1ef3 self-improve t\u1ef1 \u00e1p d\u1ee5ng thay \u0111\u1ed5i tuning t\u1eebng b\u01b0\u1edbc nh\u1ecf, c\u00f3 gi\u1edbi h\u1ea1n (retriever weights, escalation.debugLoopThreshold) v\u00e0o .ukit/storage/learning/tuned.json. manual = ch\u1ec9 ghi g\u1ee3i \u00fd v\u00e0o suggestions.json. off = kh\u00f4ng t\u00ednh.",
+        "khuyen_nghi": "Gi\u1eef auto. Rollback: xo\u00e1 .ukit/storage/learning/tuned.json ho\u1eb7c \u0111\u1eb7t manual."
       }
     },
     "version": "Phi\u00ean b\u1ea3n config runtime \u0111i k\u00e8m package UKit.",