@ngockhoale/ukit 2.6.6 → 2.6.8

package/scripts/docs/render-instructions.mjs

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+// DOC-102 renderer CLI (SPEC §8.2).
+//   node scripts/docs/render-instructions.mjs --write   (default) regenerate all outputs
+//   node scripts/docs/render-instructions.mjs --check   print DRIFT <path> per mismatch, exit 1
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import {
+  renderInstructionsFromDisk,
+  checkRenderedInstructions,
+} from '../../src/render/instructionRenderer.js';
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+
+const USAGE = 'usage: render-instructions.mjs [--write|--check]';
+
+const args = process.argv.slice(2);
+const unknown = args.filter((a) => a !== '--write' && a !== '--check');
+if (unknown.length > 0) {
+  console.error(`${USAGE}\nunknown flag: ${unknown[0]}`);
+  process.exit(2);
+}
+
+const mode = args.includes('--check') ? 'check' : 'write';
+
+try {
+  if (mode === 'check') {
+    const drift = await checkRenderedInstructions({ repoRoot });
+    for (const target of drift) {
+      console.log(`DRIFT ${target}`);
+    }
+    process.exit(drift.length > 0 ? 1 : 0);
+  }
+
+  const rendered = await renderInstructionsFromDisk({ repoRoot, write: true });
+  for (const [target, content] of rendered) {
+    console.log(`WROTE ${target} (${content.split('\n').length - 1} lines)`);
+  }
+} catch (err) {
+  console.error(err && err.message ? err.message : err);
+  process.exit(1);
+}

package/scripts/release/verify-release.mjs

@@ -45,6 +45,12 @@ const steps = [
     args: ['test:artifact'],
     env: process.env,
   },
+  {
+    label: 'Doc contracts',
+    command: 'yarn',
+    args: ['vitest', 'run', 'tests/consistency/docContracts.test.js'],
+    env: process.env,
+  },
   {
     label: 'Core test suite',
     command: 'yarn',

package/src/cli/commands/code.js

@@ -0,0 +1,182 @@
+import { compileContext } from '../../core/codeintel/compiler.js';
+import { packetToText, validatePacket } from '../../core/codeintel/packet.js';
+import { IndexFileSyntaxProvider } from '../../core/codeintel/providers.js';
+
+// `ukit code` — CLI surface over the codeintel plane (SPEC §11).
+// Every subcommand emits a Context Packet v1: `--json` prints the raw packet,
+// default prints `packetToText`. Unknown/missing subcommand → help + non-zero.
+
+const HELP_FLAGS = new Set(['--help', '-h', 'help']);
+const SUBCOMMANDS = new Set(['peek', 'search', 'context', 'impact']);
+
+function extractFlag(args, flag) {
+  const index = args.indexOf(flag);
+  if (index < 0) return { value: null, rest: args };
+  return {
+    value: args[index + 1] ?? null,
+    rest: [...args.slice(0, index), ...args.slice(index + 2)],
+  };
+}
+
+function hasFlag(args, flag) {
+  return args.includes(flag);
+}
+
+function parsePositiveInt(value, fallback) {
+  const parsed = Number.parseInt(value ?? '', 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+function printPacket(packet, { json }) {
+  if (json) {
+    console.log(JSON.stringify(packet, null, 2));
+    return;
+  }
+  console.log(packetToText(packet));
+  const validation = validatePacket(packet);
+  if (!validation.ok) {
+    console.log(`[UKit] packet validation warnings: ${validation.errors.join('; ')}`);
+  }
+}
+
+async function printFileOutline(projectRoot, filePath) {
+  try {
+    const provider = new IndexFileSyntaxProvider({ rootDir: projectRoot });
+    if (!provider.supports(filePath)) {
+      return;
+    }
+    const symbols = await provider.symbols(filePath);
+    if (!Array.isArray(symbols) || symbols.length === 0) {
+      return;
+    }
+    console.log('');
+    console.log(`## Outline (${filePath})`);
+    for (const item of symbols) {
+      console.log(`${item.line ?? '?'}: ${item.name ?? item.kind ?? ''}${item.kind ? ` [${item.kind}]` : ''}`);
+    }
+  } catch {
+    // Outline is best-effort decoration; never fail the packet print for it.
+  }
+}
+
+export async function runCode({ projectRoot, argv = [] }) {
+  const [subcommandRaw, ...rest] = argv;
+  const subcommand = (subcommandRaw ?? '').toLowerCase();
+
+  if (!subcommand || HELP_FLAGS.has(subcommand)) {
+    printCodeHelp();
+    if (!subcommand) {
+      process.exitCode = 1;
+    }
+    return;
+  }
+
+  if (!SUBCOMMANDS.has(subcommand)) {
+    console.error(`[UKit] Unknown code subcommand: ${subcommand}`);
+    printCodeHelp();
+    process.exitCode = 1;
+    return;
+  }
+
+  const json = hasFlag(rest, '--json');
+  const withoutJson = rest.filter((arg) => arg !== '--json');
+
+  if (subcommand === 'peek') {
+    const { value: lines, rest: args } = extractFlag(withoutJson, '--lines');
+    const filePath = args[0];
+    if (!filePath) {
+      console.error('[UKit] Missing file path. Usage: ukit code peek <path> [--lines a-b] [--json]');
+      process.exitCode = 1;
+      return;
+    }
+    const packet = await compileContext(projectRoot, {
+      prompt: filePath,
+      filesHinted: [filePath],
+    }, { mode: 'peek' });
+    printPacket(packet, { json });
+    if (!json) {
+      await printFileOutline(projectRoot, filePath);
+      if (lines) {
+        console.log(`(note: --lines ${lines} accepted; v1 outline prints full symbol list)`);
+      }
+    }
+    return;
+  }
+
+  if (subcommand === 'search') {
+    const { value: limitArg, rest: args } = extractFlag(withoutJson, '--limit');
+    const limit = parsePositiveInt(limitArg, 20);
+    const query = args.join(' ').trim();
+    if (!query) {
+      console.error('[UKit] Missing query. Usage: ukit code search "<query>" [--limit n] [--json]');
+      process.exitCode = 1;
+      return;
+    }
+    const packet = await compileContext(projectRoot, query);
+    if (packet.evidence.length > limit) {
+      const dropped = packet.evidence.splice(limit);
+      for (const item of dropped) {
+        packet.omitted.push({ what: item.path ?? 'evidence', why: 'limit' });
+      }
+    }
+    if (packet.anchors.length > limit) {
+      packet.anchors = packet.anchors.slice(0, limit);
+    }
+    printPacket(packet, { json });
+    return;
+  }
+
+  if (subcommand === 'context') {
+    const { value: mode, rest: afterMode } = extractFlag(withoutJson, '--mode');
+    const { value: budgetArg, rest: afterBudget } = extractFlag(afterMode, '--budget');
+    const budget = budgetArg !== null ? parsePositiveInt(budgetArg, null) : undefined;
+    const diagnostics = hasFlag(afterBudget, '--diagnostics');
+    const args = afterBudget.filter((arg) => arg !== '--diagnostics');
+    const task = args.join(' ').trim();
+    if (!task) {
+      console.error('[UKit] Missing task. Usage: ukit code context "<task>" [--mode m] [--budget n] [--diagnostics] [--json]');
+      process.exitCode = 1;
+      return;
+    }
+    const packet = await compileContext(projectRoot, task, {
+      mode: mode ?? undefined,
+      budget: budget ?? undefined,
+      diagnostics: diagnostics || undefined,
+    });
+    printPacket(packet, { json });
+    return;
+  }
+
+  // subcommand === 'impact'
+  const { value: depthArg, rest: impactArgs } = extractFlag(withoutJson, '--depth');
+  const depth = depthArg !== null ? parsePositiveInt(depthArg, null) : undefined;
+  const target = impactArgs[0];
+  if (!target) {
+    console.error('[UKit] Missing target. Usage: ukit code impact <path|symbol> [--depth N] [--json]');
+    process.exitCode = 1;
+    return;
+  }
+  const packet = await compileContext(projectRoot, {
+    prompt: target,
+    filesHinted: target.includes('/') || /\.[a-z0-9]+$/i.test(target) ? [target] : [],
+  }, { mode: 'impact', depth: depth ?? undefined });
+  printPacket(packet, { json });
+}
+
+export function printCodeHelp() {
+  console.log('UKit Code Commands (codeintel plane)');
+  console.log('Usage: ukit code <peek|search|context|impact> [args]');
+  console.log('');
+  console.log('Subcommands:');
+  console.log('  peek <path> [--lines a-b]   L0 outline-only packet + file outline');
+  console.log('  search "<query>" [--limit n]  Routed retrieval packet over the index');
+  console.log('  context "<task>" [--mode m] [--budget n] [--diagnostics]  Compiled context packet for a task');
+  console.log('  impact <path|symbol> [--depth N]  L2 packet with multi-hop reverse-import edges');
+  console.log('');
+  console.log('Options:');
+  console.log('  --json              Print raw Context Packet JSON (default: text render)');
+  console.log('  --mode <m>          Force router mode: none|peek|targeted|explore|impact|deep_flow|analogy');
+  console.log('  --budget <n>        Override routed token budget');
+  console.log('  --depth <N>         Impact-mode hop depth (clamped 1..codeIntel.impact.maxDepth)');
+  console.log('  --diagnostics       Include post-edit diagnostics in next_actions');
+}

package/src/cli/commands/doctor.js

@@ -22,10 +22,11 @@ import {
   inspectProjectImportant,
   inspectProjectImportantWiring,
 } from '../../core/projectImportant.js';
+import { runDocContractChecks } from '../../core/docContracts.js';
 
 export const DOCTOR_HELP_FLAGS = new Set(['--help', '-h']);
-const KNOWN_FLAGS = new Set([...DOCTOR_HELP_FLAGS, '--skills', '--gateway']);
-const SUPPORTED_FLAGS_LIST = '--help, -h, --skills, --gateway';
+const KNOWN_FLAGS = new Set([...DOCTOR_HELP_FLAGS, '--skills', '--gateway', '--docs']);
+const SUPPORTED_FLAGS_LIST = '--help, -h, --skills, --gateway, --docs';
 
 export function printDoctorHelp() {
   console.log('Usage: ukit doctor [options]');
@@ -36,6 +37,7 @@ export function printDoctorHelp() {
   console.log('  --help, -h      Show this help message');
   console.log('  --skills        Also print a skill word-count/budget report');
   console.log('  --gateway       Live gateway probe (streaming + non-streaming); advisory only');
+  console.log('  --docs          Run doc-contract checks (manifests/documentation.yaml projects only)');
 }
 
 export async function runDoctor({ packageRoot, projectRoot, argv = [], homeDir = os.homedir() }) {
@@ -366,6 +368,36 @@ export async function runDoctor({ packageRoot, projectRoot, argv = [], homeDir =
     }
   }
 
+  // FR-007: doc-contract checks (DOC-203 validator) — only when the project root
+  // carries manifests/documentation.yaml (doc-governed maintainer repo). Downstream
+  // projects get a skip advisory; error-severity failures block via exitCode 1,
+  // warnings are advisory only.
+  let docContractErrors = false;
+  if (argv.includes('--docs')) {
+    const docManifestPath = path.join(projectRoot, 'manifests', 'documentation.yaml');
+    if (!(await pathExists(docManifestPath))) {
+      console.log('');
+      console.log('[UKit] Doc contract checks — not a doc-governed project — skipped (no manifests/documentation.yaml).');
+    } else {
+      const report = await runDocContractChecks({ rootDir: projectRoot });
+      console.log('');
+      console.log('[UKit] Doc contract checks:');
+      for (const check of report.checks) {
+        const mark = check.skipped ? '-' : ok(check.passed);
+        const severity = check.severity === 'warning' ? ' (warning)' : '';
+        console.log(`[UKit]   ${mark}  ${check.label}${severity}`);
+        if (check.detail) console.log(`[UKit]      detail: ${check.detail}`);
+        if (check.remedy && (!check.passed || check.severity === 'warning')) {
+          console.log(`[UKit]      remedy: ${check.remedy}`);
+        }
+      }
+      console.log(
+        `[UKit]   summary: ${report.summary.passed} passed, ${report.summary.errors} errors, ${report.summary.warnings} warnings, ${report.summary.skipped} skipped`,
+      );
+      docContractErrors = report.summary.errors > 0;
+    }
+  }
+
   const allPassed = Object.values(checks).every(Boolean);
   const failedProjectChecks = projectChecks.filter(
     (check) => check.applicable !== false && !check.passed,
@@ -381,7 +413,7 @@ export async function runDoctor({ packageRoot, projectRoot, argv = [], homeDir =
     }
   }
 
-  if (!allPassed || blockingFailures.length > 0) {
+  if (!allPassed || blockingFailures.length > 0 || docContractErrors) {
     console.log('[UKit] Some checks failed.');
     if (!allPassed && blockingFailures.length === 0) {
       console.log('[UKit] Re-run `ukit install` to repair install-managed files.');

package/src/cli/commands/indexTools.js

@@ -10,6 +10,9 @@ import { deriveTaskRoute } from '../../index/taskRouting.js';
 import { queryCodeIndex, getFileOutline } from '../../index/queryIndex.js';
 import { triageBug } from '../../bug/triageBug.js';
 import { installIndexRefreshHooks, removeIndexRefreshHooks } from '../../index/gitHooks.js';
+import fs from 'node:fs/promises';
+import { INDEX_ARTIFACTS, INDEX_SCHEMA_VERSION, getArtifactPath } from '../../index/paths.js';
+import { computeIdentity, readSnapshot, guardLevel } from '../../core/codeintel/freshness.js';
 import {
   parseIndexArgs,
   CONTEXT_FLAG_DEFINITIONS,
@@ -221,6 +224,64 @@ export async function runIndexTools({ projectRoot, argv = [] }) {
     return;
   }
 
+  if (subcommand === 'status') {
+    // L0 freshness identity report (SPEC §7) — never refreshes, never throws.
+    const identity = await computeIdentity(projectRoot);
+    const snapshot = await readSnapshot(projectRoot);
+    const stale = !snapshot || snapshot.identity !== identity.identity;
+
+    console.log('[UKit] Index status:');
+    console.log(`identity: ${identity.identity}`);
+    console.log(`headSha: ${identity.headSha}`);
+    console.log(`overlayHash: ${identity.overlayHash}`);
+    console.log(`configHash: ${identity.configHash}`);
+    console.log(`snapshot: ${snapshot ? snapshot.identity : 'none'}`);
+    console.log(`stale: ${stale ? 'yes' : 'no'}`);
+
+    const artifacts = await collectArtifactAges(projectRoot);
+    if (artifacts.length === 0) {
+      console.log('artifacts: none (index not built)');
+    } else {
+      console.log('artifacts:');
+      for (const item of artifacts) {
+        console.log(`  ${item.name}: ${item.age}`);
+      }
+    }
+    return;
+  }
+
+  if (subcommand === 'doctor') {
+    // Freshness guard + artifact schema checks (SPEC §7). Exit non-zero when
+    // the recommended repair level is L2 or higher.
+    const guard = await guardLevel(projectRoot, { maxLevel: 'L4' });
+    const problems = [];
+
+    console.log('[UKit] Index doctor:');
+    console.log(`identity: ${guard.identity.identity}`);
+    console.log(`headSha: ${guard.identity.headSha}`);
+    console.log(`snapshot: ${guard.snapshot ? guard.snapshot.identity : 'none'}`);
+    console.log(`stale: ${guard.stale ? 'yes' : 'no'}`);
+    console.log(`recommendedLevel: ${guard.recommendedLevel}`);
+
+    const schemaIssues = await checkArtifactSchemas(projectRoot);
+    for (const issue of schemaIssues) {
+      problems.push(issue);
+      console.log(`problem: ${issue}`);
+    }
+    if (schemaIssues.length === 0) {
+      console.log('schema: ok');
+    }
+
+    const needsRepair = ['L2', 'L3', 'L4'].includes(guard.recommendedLevel) || problems.length > 0;
+    if (needsRepair) {
+      console.log('[UKit] Index needs repair. Run "ukit index build".');
+      process.exitCode = 1;
+    } else {
+      console.log('[UKit] Index healthy.');
+    }
+    return;
+  }
+
   if (subcommand === 'hooks') {
     const action = (rest[0] ?? 'install').toLowerCase();
     if (action === 'help' || action === '--help' || action === '-h') {
@@ -250,7 +311,7 @@ export async function runIndexTools({ projectRoot, argv = [] }) {
 
 export function printIndexHelp() {
   console.log('UKit Index Commands');
-  console.log('Usage: ukit index <build|refresh|query|triage|context|verify|route> [args]');
+  console.log('Usage: ukit index <build|refresh|query|triage|context|verify|route|status|doctor> [args]');
   console.log('');
   console.log('Subcommands:');
   console.log('  build                 Build codebase index cache');
@@ -260,6 +321,8 @@ export function printIndexHelp() {
   console.log('  context "<intent>"    Suggest minimal file context with reasons');
   console.log('  verify "<intent>"     Suggest verification lane from indexed context');
   console.log('  route "<prompt>"      Suggest skill + context + verification next step');
+  console.log('  status                Show freshness identity, snapshot, artifact ages');
+  console.log('  doctor                Freshness guard + artifact schema checks');
   console.log('  hooks [install|remove]  Manage git-hook auto-refresh');
   console.log('');
   console.log('Aliases:');
@@ -275,6 +338,44 @@ function printIndexHooksHelp() {
   console.log('  ukit index hooks remove');
 }
 
+async function collectArtifactAges(rootDir) {
+  const entries = [];
+  for (const [key, fileName] of Object.entries(INDEX_ARTIFACTS)) {
+    try {
+      const stat = await fs.stat(getArtifactPath(rootDir, fileName));
+      const ageMs = Date.now() - stat.mtimeMs;
+      const ageMinutes = Math.max(0, Math.round(ageMs / 60000));
+      entries.push({ name: fileName, age: `${ageMinutes}m old` });
+    } catch {
+      // missing artifact — not listed
+    }
+  }
+  return entries;
+}
+
+async function checkArtifactSchemas(rootDir) {
+  const issues = [];
+  const required = ['meta', 'files', 'symbols'];
+  for (const key of required) {
+    const fileName = INDEX_ARTIFACTS[key];
+    let parsed;
+    try {
+      const raw = await fs.readFile(getArtifactPath(rootDir, fileName), 'utf8');
+      parsed = JSON.parse(raw);
+    } catch {
+      issues.push(`${fileName}: missing or unreadable`);
+      continue;
+    }
+    if (parsed?.schemaVersion !== INDEX_SCHEMA_VERSION) {
+      issues.push(`${fileName}: schemaVersion ${parsed?.schemaVersion ?? 'none'} != ${INDEX_SCHEMA_VERSION}`);
+    }
+    if (key !== 'meta' && !Array.isArray(parsed?.items)) {
+      issues.push(`${fileName}: items is not an array`);
+    }
+  }
+  return issues;
+}
+
 async function refreshIndexIfStale(rootDir) {
   const lastRefreshMs = await getIndexArtifactGeneratedAt({ rootDir });
   const stale = await isIndexStale({

package/src/cli/commands/memory.js

@@ -7,6 +7,14 @@ import {
   resolvePatternCandidate,
   runProjectHygiene,
 } from '../../core/memory/store.js';
+import {
+  getRecord,
+  loadRecords,
+  queryRecords,
+  stats as v2Stats,
+  updateRecord,
+} from '../../core/memory/storeV2.js';
+import { runMigration } from '../../core/memory/migrate.js';
 import { getContextInjection, search } from '../../core/memory/retrieval.js';
 import { inspectRuntimeConfig } from '../../core/runtimeConfig.js';
 import { buildRuntimePaths } from '../../core/runtimePaths.js';
@@ -26,6 +34,30 @@ function extractFlag(args, flag) {
 }
 
 async function listAllPendingPatternCandidates(projectRoot, runtimePaths) {
+  // v2 mode: pending pattern candidates live as derived_fact records with
+  // meta.legacyStatus === 'pending' (facade handles the conversion).
+  // Respect memoryV2.enabled — without this check loadRecords would run the
+  // lazy v1→v2 migration even when the whole v2 lane is disabled.
+  let v2Enabled = true;
+  try {
+    const { config } = await inspectRuntimeConfig(projectRoot);
+    if (config?.memoryV2?.enabled === false) v2Enabled = false;
+  } catch {
+    // unreadable config → default enabled
+  }
+  const records = v2Enabled ? await loadRecords(projectRoot) : [];
+  if (records.length > 0) {
+    const projectIds = new Set(records.map((r) => r.project_id).filter(Boolean));
+    const results = [];
+    for (const projectId of projectIds) {
+      const pending = await listPendingPatternCandidates(projectRoot, projectId);
+      for (const candidate of pending) {
+        results.push({ ...candidate, projectId });
+      }
+    }
+    return results;
+  }
+
   let entries = [];
   try {
     entries = await fs.readdir(runtimePaths.projectsDir, { withFileTypes: true });
@@ -45,6 +77,106 @@ async function listAllPendingPatternCandidates(projectRoot, runtimePaths) {
   return results;
 }
 
+// ---- `ukit memory v2` ops (SPEC §11) ----
+
+async function runMemoryV2(projectRoot, args) {
+  const [opRaw, ...rest] = args;
+  const op = (opRaw ?? 'list').toLowerCase();
+
+  if (op === 'list') {
+    const typeFlag = extractFlag(rest, '--type');
+    const scopeFlag = extractFlag(typeFlag.rest, '--scope');
+    const statusFlag = extractFlag(scopeFlag.rest, '--status');
+    const records = await queryRecords(projectRoot, {
+      type: typeFlag.value ?? undefined,
+      scope: scopeFlag.value ?? undefined,
+      status: statusFlag.value ?? undefined,
+    });
+    if (records.length === 0) {
+      console.log('[UKit] No memory v2 records found.');
+      return;
+    }
+    for (const record of records) {
+      const scopeLabel = record.project_id ?? record.scope;
+      console.log(`${record.id} [${record.type}/${scopeLabel}/${record.status}] — ${record.text}`);
+    }
+    return;
+  }
+
+  if (op === 'show') {
+    const id = rest.join(' ').trim();
+    if (!id) {
+      throw new Error('Missing record id. Usage: ukit memory v2 show <id>');
+    }
+    const record = await getRecord(projectRoot, id);
+    if (!record) {
+      throw new Error(`Memory v2 record not found: ${id}`);
+    }
+    console.log(JSON.stringify(record, null, 2));
+    return;
+  }
+
+  if (op === 'promote') {
+    const id = rest.join(' ').trim();
+    if (!id) {
+      throw new Error('Missing record id. Usage: ukit memory v2 promote <id>');
+    }
+    const record = await getRecord(projectRoot, id);
+    if (!record) {
+      throw new Error(`Memory v2 record not found: ${id}`);
+    }
+    if (record.type === 'project_rule') {
+      console.log(`[UKit] ${id} is already a project_rule — nothing to do.`);
+      return;
+    }
+    if (record.type !== 'derived_fact' && record.type !== 'episode') {
+      throw new Error(`Cannot promote ${record.type} records (only derived_fact or episode).`);
+    }
+    // Explicit approval only — no auto-promotion (SPEC §11,
+    // memoryV2.promotion.episodeToRuleRequiresApproval).
+    const updated = await updateRecord(projectRoot, id, {
+      type: 'project_rule',
+      scope: 'repo',
+      provenance: `${record.provenance ?? 'manual'};promoted-from:${record.id}`,
+    });
+    console.log(`[UKit] Promoted ${updated.id} → project_rule.`);
+    return;
+  }
+
+  if (op === 'stale') {
+    const id = rest.join(' ').trim();
+    if (!id) {
+      throw new Error('Missing record id. Usage: ukit memory v2 stale <id>');
+    }
+    const updated = await updateRecord(projectRoot, id, { status: 'stale' });
+    if (!updated) {
+      throw new Error(`Memory v2 record not found: ${id}`);
+    }
+    console.log(`[UKit] Marked ${id} as stale.`);
+    return;
+  }
+
+  if (op === 'migrate') {
+    const dryRun = rest.includes('--dry-run');
+    const result = await runMigration(projectRoot, { dryRun });
+    if (dryRun) {
+      console.log(`[UKit] Dry-run: would migrate ${result.migrated} record(s), skip ${result.skipped}.`);
+      return;
+    }
+    if (result.migrated === 0) {
+      console.log('[UKit] Nothing to migrate (marker present or no legacy memory).');
+      return;
+    }
+    console.log(`[UKit] Migrated ${result.migrated} record(s) to v2.`);
+    console.log(`[UKit] Backup: ${result.backupDir ?? 'none'} — marker: ${result.markerPath}`);
+    const stats = await v2Stats(projectRoot);
+    console.log(`[UKit] v2 store: ${stats.total} record(s) — ${JSON.stringify(stats.byType)}`);
+    return;
+  }
+
+  throw new Error(`Unknown memory v2 op: ${op}. Expected list|show|promote|stale|migrate.`);
+}
+
 export async function runMemory({ projectRoot, argv = [] }) {
   const runtimePaths = buildRuntimePaths(projectRoot);
   if (!(await pathExists(runtimePaths.runtimeRoot))) {
@@ -59,6 +191,11 @@ export async function runMemory({ projectRoot, argv = [] }) {
     return;
   }
 
+  if (subcommand === 'v2') {
+    await runMemoryV2(projectRoot, rest);
+    return;
+  }
+
   if (subcommand === 'list') {
     if (rest.includes('--pending')) {
       const pending = await listAllPendingPatternCandidates(projectRoot, runtimePaths);

package/src/cli/index.js

@@ -6,6 +6,7 @@ import { runIndexTools } from './commands/indexTools.js';
 import { runStatus } from './commands/status.js';
 import { runMemory } from './commands/memory.js';
 import { runUpdate } from './commands/update.js';
+import { runCode } from './commands/code.js';
 
 const GLOBAL_FLAGS = new Set(['--help', '-h', '--version', '-v']);
 
@@ -49,6 +50,11 @@ export async function runCli({ argv, packageRoot, projectRoot, packageVersion })
     return;
   }
 
+  if (command === 'code') {
+    await runCode({ projectRoot, argv: commandArgv });
+    return;
+  }
+
   if (command === 'status') {
     await runStatus({ projectRoot, argv: commandArgv });
     return;
@@ -89,6 +95,7 @@ export async function runCli({ argv, packageRoot, projectRoot, packageVersion })
     console.log('  doctor             Validate manifest, stack, docs, and UKit state');
     console.log('  uninstall          Remove all UKit-managed assets');
     console.log('  index              Codebase index tools (build/query/triage)');
+    console.log('  code               Context compiler surface (peek/search/context/impact)');
     console.log('  status             Show UKit runtime status');
     console.log('  memory             Inspect shared UKit memory');
     console.log('  update             Upgrade the global UKit CLI to the latest version');