@ngockhoale/ukit 3.3.3 → 3.4.0

package/scripts/probe/codex-capability-probe.mjs

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+// codex-capability-probe.mjs — TASK-001 / BL-001 + BL-002 scripted probe.
+//
+// Probes the installed `.codex/` surface of a UKit workspace and records what
+// can be shown WITHOUT a live Codex CLI session:
+//   1. codex CLI presence on PATH (live-session gate).
+//   2. `.codex/` surface inventory (symlinks + files shipped by install).
+//   3. `.codex/agents` resolution into real agent definitions.
+//   4. Review-lane script reachability: `review-verdict.mjs` and
+//      `review-panel-aggregate.mjs` invoked THROUGH the `.codex/ukit` symlink
+//      (the exact path instruction-mediated Codex Bash would use).
+//   5. Instruction mediation: `.codex/README.md` / `settings.json` point the
+//      model at `.codex/ukit/index/*` helpers.
+//
+// Honesty contract (SPEC §14): output states are PROVEN / ADVISORY-REACHABLE /
+// INCONCLUSIVE / UNSUPPORTED — a cell can never be promoted beyond what the
+// printed evidence shows. `codex-cli: absent` ⇒ subagent consumption is
+// INCONCLUSIVE by construction; no claim of tested capability is emitted.
+//
+// Usage: node scripts/probe/codex-capability-probe.mjs [workspace-root]
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import process from 'node:process';
+import { spawnSync } from 'node:child_process';
+
+// The probe targets an INSTALLED workspace (.codex/ exists after `ukit
+// install`); pass the workspace root explicitly when it differs from cwd.
+const ROOT = path.resolve(process.argv[2] ?? process.cwd());
+const CODEX_DIR = path.join(ROOT, '.codex');
+
+const out = [];
+const say = (line = '') => { out.push(line); console.log(line); };
+
+function commandOnPath(cmd) {
+  const r = spawnSync('sh', ['-c', `command -v ${cmd}`], { encoding: 'utf8' });
+  return r.status === 0 ? r.stdout.trim() : null;
+}
+
+function lstatKind(p) {
+  try {
+    const st = fs.lstatSync(p);
+    if (st.isSymbolicLink()) return `symlink -> ${fs.readlinkSync(p)}`;
+    if (st.isDirectory()) return 'dir';
+    return `file (${st.size}B)`;
+  } catch {
+    return 'ABSENT';
+  }
+}
+
+say(`probe-root: ${ROOT}`);
+say(`probe-at: ${new Date().toISOString()}`);
+
+// --- 1. codex CLI presence -------------------------------------------------
+const codexBin = commandOnPath('codex');
+say(`codex-cli: ${codexBin ? `present (${codexBin})` : 'absent'}`);
+
+// --- 2. .codex surface inventory ------------------------------------------
+say('--- .codex surface inventory ---');
+let codexEntries = [];
+try {
+  codexEntries = fs.readdirSync(CODEX_DIR).sort();
+} catch {
+  say('.codex/: ABSENT (run `node bin/ukit install` first)');
+}
+for (const name of codexEntries) {
+  say(`  .codex/${name}: ${lstatKind(path.join(CODEX_DIR, name))}`);
+}
+
+// --- 3. .codex/agents resolution -------------------------------------------
+say('--- .codex/agents resolution ---');
+const agentsDir = path.join(CODEX_DIR, 'agents');
+let agentFiles = [];
+try {
+  agentFiles = fs.readdirSync(agentsDir).filter((f) => f.endsWith('.md')).sort();
+} catch {
+  // absent
+}
+say(`  resolved-agent-files: ${agentFiles.length} [${agentFiles.join(', ')}]`);
+for (const wanted of ['code-reviewer.md', 'handoff-planner.md', 'handoff-review.md']) {
+  say(`  ${wanted}: ${agentFiles.includes(wanted) ? 'present' : 'absent'}`);
+}
+
+// --- 4. review-lane reachability via .codex/ukit ---------------------------
+say('--- review-lane reachability (via .codex/ukit symlink) ---');
+const verdictCli = path.join(CODEX_DIR, 'ukit', 'index', 'review-verdict.mjs');
+const panelCli = path.join(CODEX_DIR, 'ukit', 'index', 'review-panel-aggregate.mjs');
+say(`  .codex/ukit/index/review-verdict.mjs: ${fs.existsSync(verdictCli) ? 'resolves' : 'missing'}`);
+say(`  .codex/ukit/index/review-panel-aggregate.mjs: ${fs.existsSync(panelCli) ? 'resolves' : 'missing'}`);
+
+let verdictReachable = false;
+let panelReachable = false;
+if (fs.existsSync(verdictCli) || fs.existsSync(panelCli)) {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'ukit-codex-probe-'));
+  try {
+    if (fs.existsSync(verdictCli)) {
+      const findings = path.join(tmp, 'findings.json');
+      fs.writeFileSync(findings, JSON.stringify({
+        findings: [{ id: 'P1', severity: 'minor', file: 'probe.js', line: 1, claim: 'probe finding' }],
+      }));
+      // Isolate config: empty root/home => decisionPlane stage resolves 'off',
+      // so no gateway call — deterministic fallback is the demonstrated path.
+      const r = spawnSync('node', [verdictCli, '--file', findings], {
+        encoding: 'utf8',
+        env: { ...process.env, UKIT_TEST_ROOT: tmp, UKIT_TEST_HOME: tmp },
+        timeout: 15000,
+      });
+      const parsed = JSON.parse(r.stdout.trim() || '{}');
+      say(`  review-verdict run: exit=${r.status} verdict=${parsed.verdict ?? 'UNPARSED'} `
+        + `stage=${parsed.stage ?? '-'} verdictSource=${parsed.verdictSource ?? '-'} `
+        + `outcomeClass=${parsed.outcomeClass ?? '-'}`);
+      verdictReachable = r.status === 0 && typeof parsed.verdict === 'string';
+    }
+    if (fs.existsSync(panelCli)) {
+      const task = path.join(tmp, 'PROBE-TASK.md');
+      fs.writeFileSync(task, [
+        '# probe task',
+        '## Reviewer Verdict',
+        'MEMBER: probe-reviewer-a',
+        'VERDICT: APPROVED',
+        '## Reviewer Verdict',
+        'MEMBER: probe-reviewer-b',
+        'VERDICT: APPROVED',
+        '## Other',
+        'tail',
+        '',
+      ].join('\n'));
+      const r = spawnSync('node', [panelCli, task], { encoding: 'utf8', timeout: 15000 });
+      const verdictLine = (r.stdout || '').split('\n').find((l) => /^VERDICT:/.test(l)) ?? '(no VERDICT line)';
+      say(`  review-panel-aggregate run: exit=${r.status} ${verdictLine.trim()}`);
+      panelReachable = r.status === 0 && /^VERDICT: approved/.test(verdictLine.trim());
+    }
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
+// --- 5. instruction mediation ----------------------------------------------
+say('--- instruction mediation ---');
+const readmePath = path.join(CODEX_DIR, 'README.md');
+const settingsPath = path.join(CODEX_DIR, 'settings.json');
+try {
+  const readme = fs.readFileSync(readmePath, 'utf8');
+  const hits = (readme.match(/\.codex\/ukit\/index\/[\w-]+\.mjs/g) ?? []);
+  say(`  .codex/README.md helper references: ${[...new Set(hits)].join(', ') || 'none'}`);
+} catch {
+  say('  .codex/README.md: ABSENT');
+}
+try {
+  const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+  const helper = settings?.skillRouter?.helperCommand ?? '(none)';
+  say(`  .codex/settings.json skillRouter.helperCommand: ${helper}`);
+} catch {
+  say('  .codex/settings.json: ABSENT/unparseable');
+}
+
+// --- verdicts ---------------------------------------------------------------
+say('--- verdicts ---');
+const agentsSurface = agentFiles.length > 0;
+say(`codex.subagents: ${codexBin ? 'PENDING-LIVE' : 'INCONCLUSIVE'}`
+  + ` (.codex/agents surface ${agentsSurface ? 'shipped+resolved' : 'not resolvable'};`
+  + ` host consumption ${codexBin ? 'requires live-session drive' : 'unprovable — codex CLI absent'})`);
+say(`codex.review-lane: ${verdictReachable && panelReachable ? 'ADVISORY-REACHABLE' : 'INCONCLUSIVE'}`
+  + ` (instruction-mediated Bash via .codex/ukit symlink;`
+  + ` review-verdict=${verdictReachable ? 'ran' : 'failed'},`
+  + ` panel-aggregate=${panelReachable ? 'ran' : 'failed'};`
+  + ' enforcement: advisory — Codex exposes no hook surface)');
+say('probe-end');

package/src/cli/commands/doctor.js

@@ -31,6 +31,10 @@ import { findOpencodeArtifacts, opencodeSteerMessage } from '../../core/opencode
 import { buildUserPaths } from '../../core/userPaths.js';
 import { loadPlaybooks } from '../../core/userPlaybooks.js';
 import { userMemoryStats } from '../../core/memory/userMemory.js';
+import {
+  inspectVerificationMap,
+  doctorRecipeCheck,
+} from '../../index/verificationMap.js';
 
 import { resolveSeamStages } from '../../core/observability/rollout.js';
 import {
@@ -248,6 +252,97 @@ function printFlightRecorderSection(flightRecorder) {
   }
 }
 
+// TASK-006 (BL-008) — Codex surface report. Advisory only: the section prints
+// what was measured, never an assumption — hook-surface absence, the
+// .codex/agents + .codex/ukit symlink state, the subagents capability cell read
+// from manifests/hostCapabilities.yaml (TASK-001 probe values), and the
+// advisory enforcement ceiling. It never enters `checks`/`projectChecks`, so
+// it can never move the exit code.
+
+// '.codex/agents' ships as a symlink to '../.claude/agents'. readdir follows
+// the symlink, so a broken link and a missing real directory collapse into
+// the same 'broken' state — readdir failing while the path itself exists
+// means the entry is present but unreadable (dangling link, or a file).
+async function inspectCodexDirEntry(projectRoot, name) {
+  const entryPath = path.join(projectRoot, '.codex', name);
+  // lstat (not pathExists/stat): the entry ships as a symlink, and a dangling
+  // symlink stats ENOENT — indistinguishable from absent. lstat sees the link
+  // itself, so 'broken' reports the dangling-link truth.
+  let stat = null;
+  try {
+    stat = await fs.lstat(entryPath);
+  } catch {
+    return { state: 'absent', count: null };
+  }
+  if (!stat.isDirectory() && !stat.isSymbolicLink()) return { state: 'broken', count: null };
+  try {
+    const entries = await fs.readdir(entryPath);
+    return {
+      state: 'resolves',
+      count: entries.filter((e) => e.endsWith('.md')).length,
+    };
+  } catch {
+    return { state: 'broken', count: null };
+  }
+}
+
+async function inspectCodexSurface({ projectRoot, packageRoot }) {
+  const codexDir = path.join(projectRoot, '.codex');
+  if (!(await pathExists(codexDir))) return { installed: false };
+
+  const subagentsCell = { state: null, note: null };
+  try {
+    const caps = parse(await fs.readFile(
+      path.join(packageRoot, 'manifests', 'hostCapabilities.yaml'), 'utf8',
+    ));
+    const cell = caps?.hosts?.codex?.subagents;
+    subagentsCell.state = typeof cell?.state === 'string' ? cell.state : null;
+    subagentsCell.note = typeof cell?.note === 'string' ? cell.note
+      : typeof cell?.evidence === 'string' ? cell.evidence : null;
+  } catch {
+    // manifest absent/unreadable — state stays unknown, never assumed.
+  }
+
+  return {
+    installed: true,
+    readme: await pathExists(path.join(codexDir, 'README.md')),
+    settings: await pathExists(path.join(codexDir, 'settings.json')),
+    settingsLocal: await pathExists(path.join(codexDir, 'settings.local.json')),
+    agents: await inspectCodexDirEntry(projectRoot, 'agents'),
+    ukit: await inspectCodexDirEntry(projectRoot, 'ukit'),
+    subagents: subagentsCell,
+  };
+}
+
+function printCodexSurfaceSection(surface) {
+  const mark = (v) => (v ? '✓' : '✗');
+  console.log('[UKit] Codex surface checks (advisory — never affects exit code):');
+  if (!surface.installed) {
+    console.log('[UKit]   -  codex surface not installed (no .codex/ directory — run ukit install to add it)');
+    return;
+  }
+  const entryLine = (label, entry) => {
+    if (entry.state === 'resolves') {
+      console.log(`[UKit]   ✓  ${label}: resolves${entry.count !== null ? ` (${entry.count} .md)` : ''}`);
+    } else if (entry.state === 'broken') {
+      console.log(`[UKit]   ✗  ${label}: broken (present but unreadable — rerun ukit install)`);
+    } else {
+      console.log(`[UKit]   -  ${label}: absent`);
+    }
+  };
+  console.log(`[UKit]   ${mark(surface.readme)}  .codex/README.md`);
+  console.log(`[UKit]   ${mark(surface.settings)}  .codex/settings.json`);
+  console.log(`[UKit]   ${mark(surface.settingsLocal)}  .codex/settings.local.json`);
+  entryLine('.codex/agents', surface.agents);
+  entryLine('.codex/ukit', surface.ukit);
+  const subagents = surface.subagents;
+  console.log(
+    `[UKit]   -  codex.subagents capability: ${subagents.state ?? 'unknown'}${subagents.note ? ` — ${subagents.note}` : ''}`,
+  );
+  console.log('[UKit]   -  hook surface: absent — Codex exposes no hook surface; routing is instruction-mediated via route-task.mjs');
+  console.log('[UKit]   -  enforcement ceiling: advisory — codex outcome records carry enforcement: advisory');
+}
+
 // --json machine shape: null = unknown (mirrors `ukit telemetry status`).
 function flightRecorderJson(flightRecorder) {
   const { segments, queue, lastProjection, crashes } = flightRecorder;
@@ -276,6 +371,53 @@ function flightRecorderJson(flightRecorder) {
   };
 }
 
+
+// TASK-C85-014 (BL-014): recipe-vs-package.json check. A verification recipe
+// whose named harness script is absent degrades to a capability-negotiated
+// fallback RECEIPT — the report returns the receipt spec verbatim and never
+// fabricates a runnable command. Advisory row only: a missing/malformed map
+// or an absent harness warns, it never fails the doctor run.
+export async function inspectVerificationRecipe({ projectRoot, homeDir = null, builtinPath = null } = {}) {
+  const inspection = await inspectVerificationMap({ projectRoot, homeDir, builtinPath });
+  if (!inspection.map) {
+    return {
+      status: 'warn',
+      label: `verification-map recipes: unavailable (${inspection.reason || 'no-map'})`,
+      detail: 'guard and stop gate fall back to pre-map verification behavior',
+      remedy: 'Run ukit install to seed ~/.ukit/playbooks/verification-map.json',
+      missing: [],
+      checked: 0,
+      source: null,
+      reason: inspection.reason || 'no-map',
+    };
+  }
+  let scripts = {};
+  try {
+    const pkg = JSON.parse(await fs.readFile(path.join(projectRoot, 'package.json'), 'utf8'));
+    scripts = pkg?.scripts && typeof pkg.scripts === 'object' ? pkg.scripts : {};
+  } catch {
+    scripts = {};
+  }
+  const check = doctorRecipeCheck({ map: inspection.map, packageJsonScripts: scripts });
+  if (check.missing.length === 0) {
+    return {
+      status: 'ok',
+      label: `verification-map recipes: ${check.checked} harness script(s) present`,
+      missing: [],
+      checked: check.checked,
+      source: inspection.source,
+      reason: null,
+    };
+  }
+  return {
+    status: 'warn',
+    label: `verification-map recipes: ${check.missing.length} harness script(s) absent from package.json`,
+    missing: check.missing,
+    checked: check.checked,
+    source: inspection.source,
+    reason: 'absent-harness',
+  };
+}
 export async function runDoctor({ packageRoot, projectRoot, argv = [], homeDir = os.homedir(), ompPath = 'omp' }) {
   const unknownFlags = argv.filter((flag) => !KNOWN_FLAGS.has(flag));
   if (unknownFlags.length > 0) {
@@ -616,6 +758,32 @@ export async function runDoctor({ packageRoot, projectRoot, argv = [], homeDir =
     }
   }
 
+  // TASK-006 (BL-008) — codex surface report. Statements, never assumptions:
+  // what is on disk and what the manifests record. Advisory only — it never
+  // enters `checks` or `projectChecks` and cannot move the exit code.
+  printCodexSurfaceSection(await inspectCodexSurface({ projectRoot, packageRoot }));
+
+
+  // TASK-C85-014 (BL-014) — verification-map recipe check. Advisory only:
+  // warn rows never enter the blocking set and never fabricate a command —
+  // a recipe naming an absent harness prints its fallback RECEIPT spec.
+  {
+    const recipe = await inspectVerificationRecipe({ projectRoot, homeDir });
+    console.log('[UKit] Verification-map checks (advisory — does not affect exit code):');
+    const sev = recipe.status === 'warn' ? ' (warning)' : '';
+    console.log(`[UKit]   ${ok(recipe.status === 'ok')}  ${recipe.label}${sev}`);
+    if (recipe.detail) console.log(`[UKit]      detail: ${recipe.detail}`);
+    for (const entry of recipe.missing ?? []) {
+      console.log(`[UKit]      missing: ${entry.artifactClass} → package.json script '${entry.script}'`);
+      if (entry.fallback) console.log(`[UKit]      fallback: ${entry.fallback}`);
+    }
+    if (recipe.remedy && recipe.status === 'warn') {
+      console.log(`[UKit]      remedy: ${recipe.remedy}`);
+    }
+    if (recipe.status === 'warn' && recipe.reason === 'absent-harness') {
+      console.log('[UKit]      remedy: add the named script(s) to package.json, or rely on the fallback receipt attestation — no substitute command is fabricated.');
+    }
+  }
   if (runtimeConfigInspection.errors.length > 0) {
     console.log(`[UKit] Runtime config issues: ${runtimeConfigInspection.errors.join(' | ')}`);
   }

package/src/cli/commands/indexTools.js

@@ -226,6 +226,13 @@ export async function runIndexTools({ projectRoot, argv = [] }) {
     if (nextDisplay) {
       console.log(`next: ${nextDisplay}`);
     }
+    // BL-018: the fix-loop escalation lane — 'blocked' on exhaustion.
+    if (result.routeSummary?.escalatedLane) {
+      console.log(`escalatedLane: ${result.routeSummary.escalatedLane}`);
+      if (result.routeSummary.escalateReason) {
+        console.log(`escalateReason: ${result.routeSummary.escalateReason}`);
+      }
+    }
     if (result.routeSummary?.delegateHint) {
       console.log(`delegate: ${result.routeSummary.delegateHint}`);
     }

package/src/cli/commands/metrics.js

@@ -1,10 +1,19 @@
-// `ukit metrics` — read-only telemetry roll-up (SPEC §6, SI-102).
+// `ukit metrics` — telemetry roll-up (SPEC §6, SI-102).
 // Route outcomes + failure patterns (lazy, degrade to n/a) + v2 memory count.
 // Never exits non-zero on missing telemetry; unknown flag → exit 1.
+// BL-019 (SPEC FR-001): the one deliberate write — the joined corpus derives
+// tier-map.json, the cache artifact the router reads for measured tier picks.
 
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { collectRouteOutcomes } from '../../diagnostics/routeOutcomes.js';
+import { MODEL_TIER_BY_CONTRACT } from '../../core/executionContracts.js';
+import {
+  deriveTierStats,
+  evaluateTierPromotion,
+  buildTierMapArtifact,
+  writeTierMap,
+} from '../../index/tierSelection.js';
 import { buildRuntimePaths } from '../../core/runtimePaths.js';
 
 const HELP_FLAGS = new Set(['--help', '-h', 'help']);
@@ -74,6 +83,57 @@ function printRouteOutcomes(routeOutcomes) {
   }
 }
 
+// BL-019 (SPEC FR-001 §7): derive the measured tier map from the joined
+// corpus and persist the cache artifact the router reads. Returns the rollup
+// the print/JSON surfaces consume; null when there is no joined data at all
+// (no artifact written — an empty corpus must not clobber a live promote map).
+async function deriveAndWriteTierMap(projectRoot, routeOutcomes) {
+  try {
+    const joinedRows = Array.isArray(routeOutcomes?.joinedRows) ? routeOutcomes.joinedRows : [];
+    if (joinedRows.length === 0) return null;
+    const stats = deriveTierStats(joinedRows);
+    const evaluation = evaluateTierPromotion({ stats, staticMap: MODEL_TIER_BY_CONTRACT });
+    const artifact = buildTierMapArtifact({ stats, staticMap: MODEL_TIER_BY_CONTRACT });
+    await writeTierMap(projectRoot, artifact);
+    return {
+      joinedRoutes: stats.joinedRoutes,
+      agreement: evaluation.agreement,
+      cheaperShare: evaluation.cheaperShare,
+      regressionFree: evaluation.regressionFree,
+      decision: evaluation.decision,
+      reasons: evaluation.reasons,
+      byMode: evaluation.byMode,
+    };
+  } catch (error) {
+    return { error: error?.message ?? String(error) };
+  }
+}
+
+function printTierSelection(tierSelection) {
+  console.log('tier-selection');
+  if (!tierSelection) {
+    console.log('  n/a (no joined route↔outcome data)');
+    return;
+  }
+  if (tierSelection.error) {
+    console.log(`  n/a (${tierSelection.error})`);
+    return;
+  }
+  const reasons = Array.isArray(tierSelection.reasons) && tierSelection.reasons.length > 0
+    ? `  reasons: ${tierSelection.reasons.join(', ')}`
+    : '';
+  console.log(
+    `  joined: ${tierSelection.joinedRoutes}  agreement: ${(tierSelection.agreement * 100).toFixed(1)}%`
+    + `  cheaper-share: ${(tierSelection.cheaperShare * 100).toFixed(1)}%`
+    + `  regression-free: ${tierSelection.regressionFree}`
+    + `  decision: ${tierSelection.decision}${reasons}`,
+  );
+  const picks = Object.entries(tierSelection.byMode ?? {});
+  if (picks.length > 0) {
+    console.log(`  measured: ${picks.map(([mode, tier]) => `${mode}→${tier}`).join('  ')}`);
+  }
+}
+
 function printFailurePatterns(failurePatterns) {
   console.log('failure-patterns');
   if (!failurePatterns) {
@@ -211,8 +271,10 @@ export async function runMetrics({ projectRoot, argv = [] }) {
   const skillAccuracy = await lazyCollect('../../diagnostics/skillAccuracy.js', 'collectSkillAccuracy', projectRoot);
   const laneStats = await lazyCollect('../../diagnostics/laneStats.js', 'collectLaneStats', projectRoot);
   const learning = await collectLearningSuggestions(projectRoot);
+  // BL-019: derive + persist the measured tier map from the joined corpus.
+  const tierSelection = await deriveAndWriteTierMap(projectRoot, routeOutcomes);
 
-  const rollup = { routeOutcomes, failurePatterns, memory, feedback, skillAccuracy, laneStats, learning };
+  const rollup = { routeOutcomes, failurePatterns, memory, feedback, skillAccuracy, laneStats, learning, tierSelection };
 
   if (argv.includes('--json')) {
     console.log(JSON.stringify(rollup, null, 2));
@@ -229,6 +291,8 @@ export async function runMetrics({ projectRoot, argv = [] }) {
   console.log('');
   printLaneStats(laneStats);
   console.log('');
+  printTierSelection(tierSelection);
+  console.log('');
   printLearning(learning);
   console.log('');
   printMemory(memory);

package/src/cli/commands/playbook.js

@@ -13,7 +13,7 @@ export function printPlaybookHelp() {
   console.log('Resolution precedence: project (.ukit/playbooks) > user (~/.ukit/playbooks) > builtin.');
 }
 
-export async function runPlaybook({ projectRoot, homeDir, argv = [], builtins } = {}) {
+export async function runPlaybook({ projectRoot, homeDir, argv = [], builtins, builtinDir } = {}) {
   const [subcommandRaw, ...rest] = argv;
   const subcommand = (subcommandRaw ?? 'list').toLowerCase();
 
@@ -23,9 +23,9 @@ export async function runPlaybook({ projectRoot, homeDir, argv = [], builtins }
   }
 
   if (subcommand === 'list') {
-    const rows = await listPlaybooks({ projectRoot, homeDir, builtins });
+    const rows = await listPlaybooks({ projectRoot, homeDir, builtins, builtinDir });
     if (rows.length === 0) {
-      console.log('No playbooks found (built-ins: bug-fix, issue-implementation)');
+      console.log('No playbooks found (built-ins: bug-fix, feature-implementation)');
       return;
     }
     console.log('id | source | lanes');
@@ -40,7 +40,7 @@ export async function runPlaybook({ projectRoot, homeDir, argv = [], builtins }
     if (!id) {
       throw new Error('Missing playbook id. Usage: ukit playbook show <id>');
     }
-    const playbook = await resolvePlaybook(id, { projectRoot, homeDir, builtins });
+    const playbook = await resolvePlaybook(id, { projectRoot, homeDir, builtins, builtinDir });
     if (playbook === null) {
       throw new Error(`Unknown playbook: ${id}`);
     }

package/src/cli/commands/vm.js

@@ -1,19 +1,25 @@
 // `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.
+// D-02, D-03; BL-031 live `run` entry). Discovery + shadow-evidence
+// commands over the language-compiled runtime; shadow runs never execute
+// real operations (stub startFn), the `run` lane launches RUN-node specs
+// through the real supervisor — canary/default only. 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)
+//   run <planId>            Live execution through a real VmEngine +
+//                           supervisor launches (canary/default only);
+//                           appends one evidence record per run (BL-031)
 //   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,
+// .ukit/storage/agent-runtime/ (G-D1); 'run' additionally refuses any
+// stage below canary with `live_stage_required`. Exit codes: 0 success,
 // 2 typed failure, 1 usage error.
 
 import fs from 'node:fs/promises';
@@ -28,12 +34,13 @@ import { loadPlan, loadPlanLibrary } from '../../core/agentRuntime/planLibrary.j
 import { promote, promotionCriteriaFor } from '../../core/agentRuntime/promotion.js';
 import {
   runShadowPlan,
+  runLivePlan,
   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 SUBCOMMANDS = new Set(['list', 'show', 'status', 'shadow-run', 'run', 'evidence']);
+const OPERAND_SUBCOMMANDS = new Set(['show', 'shadow-run', 'run', 'evidence']);
 
 const RUNTIME_REL = path.join('.ukit', 'storage', 'agent-runtime');
 
@@ -45,6 +52,8 @@ function printUsage() {
   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('  run <planId>         Execute live via the real VmEngine+supervisor path');
+  console.log('                       (requires decisionRuntime.vm stage canary or default)');
   console.log('  evidence <key>       Print the promote() verdict over stored runs');
   console.log('');
   console.log('Options:');
@@ -168,6 +177,27 @@ async function shadowRunCommand({ projectRoot, config, planId }) {
   }
 }
 
+// --- run (BL-031 live lane) -------------------------------------------------
+
+async function runCommand({ projectRoot, config, planId }) {
+  // Stage narrowing lives inside runLivePlan: 'shadow' → live_stage_required
+  // typed refuse, exit 2, zero writes; canary/default execute + append
+  // exactly one evidence record through the same sink as shadow-run.
+  const res = await runLivePlan(planId, { projectRoot, config });
+  if (!res.ok) {
+    console.error(`[UKit] vm run: ${res.code} — ${res.reason}`);
+    process.exitCode = 2;
+    return;
+  }
+  console.log(`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 }) {
@@ -177,15 +207,25 @@ async function evidenceCommand({ projectRoot, config, key, json }) {
     process.exitCode = 2;
     return;
   }
-  const verdict = promote(config, { key, runs: res.runs });
+  // Comparison artifacts are recorded evidence, not sampled runs — they
+  // stay out of the promote() run set but their verdict prints verbatim.
+  const replay = [...res.runs].reverse().find((r) => r?.kind === 'replay-comparison');
+  const sampled = res.runs.filter((r) => r?.kind !== 'replay-comparison');
+  const verdict = promote(config, { key, runs: sampled });
   const criteria = promotionCriteriaFor(key);
   if (json) {
-    console.log(JSON.stringify({ key, runs: res.runs.length, dropped: res.dropped, criteria, verdict }));
+    console.log(JSON.stringify({
+      key, runs: res.runs.length, dropped: res.dropped, criteria, verdict,
+      ...(replay ? { replay } : {}),
+    }));
     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}`);
+  if (replay) {
+    console.log(`replay ${key}: verdict=${replay.verdict} reason=${replay.reason} defectsCaught=${replay.defectsCaught} rows=${replay.rows?.length ?? 0}`);
+  }
 }
 
 // --- dispatch -------------------------------------------------------------
@@ -238,5 +278,6 @@ export async function runVm({ projectRoot, argv = [] }) {
   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 });
+  if (sub === 'run') return runCommand({ projectRoot, config, planId: operand });
   return evidenceCommand({ projectRoot, config, key: operand, json: flags.includes('--json') });
 }