@ngockhoale/ukit 2.6.10 → 2.6.11

package/manifests/platform.full.yaml

@@ -1325,6 +1325,17 @@ items:
     packs:
       - core
 
+  - id: hook-session-episode
+    type: hook
+    sourceTemplate: .claude/hooks/session-episode.sh
+    targetPath: .claude/hooks/session-episode.sh
+    requires: []
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: ukit-index-anchor-search-script
     type: config
     sourceTemplate: .claude/ukit/index/anchor-search.mjs

package/package.json

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

package/src/cli/commands/feedback.js

@@ -0,0 +1,97 @@
+// `ukit feedback` — manual wrong-route label capture (SPEC C32 §3c).
+//
+// `ukit feedback "<text>" [--target <file>]` appends
+// `{ts, text, targetFile?, sessionId?}` to
+// `.ukit/storage/cache/feedback-manual.jsonl` and prints `feedback recorded`.
+// `sessionId` = UKIT_SESSION_ID env only (SessionEnd hook exports it) — omitted
+// when unset. `--list` prints a byKind roll-up via collectFeedbackEvents and
+// never writes. Missing/empty text or unknown flag → usage on stderr, exit 1.
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { collectFeedbackEvents } from '../../diagnostics/feedbackEvents.js';
+
+const HELP_FLAGS = new Set(['--help', '-h', 'help']);
+
+function printUsage(stream = console.log) {
+  stream('Usage: ukit feedback "<text>" [--target <file>]');
+  stream('       ukit feedback --list');
+  stream('');
+  stream('Record a manual wrong-route correction label, or inspect collected');
+  stream('feedback events (rescue / re-route / repeat-stall / user-correction).');
+}
+
+async function appendManualLine(projectRoot, record) {
+  const filePath = path.join(projectRoot, '.ukit', 'storage', 'cache', 'feedback-manual.jsonl');
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  await fs.appendFile(filePath, JSON.stringify(record) + '\n');
+}
+
+export async function runFeedback({ projectRoot, argv = [] }) {
+  const args = argv ?? [];
+
+  if (args.some((a) => HELP_FLAGS.has(a))) {
+    printUsage();
+    return;
+  }
+
+  if (args.includes('--list')) {
+    const result = await collectFeedbackEvents(projectRoot);
+    console.log('feedback-events');
+    console.log(`  audit rows: ${result.auditRowsScanned}  ledgers: ${result.ledgersScanned}`);
+    for (const [kind, count] of Object.entries(result.byKind)) {
+      console.log(`  ${kind}: ${count}`);
+    }
+    for (const event of result.events.slice(0, 5)) {
+      console.log(`  - ${event.kind} · ${event.detail}`);
+    }
+    return;
+  }
+
+  let text = null;
+  let targetFile;
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === '--target') {
+      targetFile = args[i + 1];
+      i += 1;
+      if (typeof targetFile !== 'string' || targetFile.startsWith('--')) {
+        console.error('Missing value for --target.');
+        printUsage(console.error);
+        process.exitCode = 1;
+        return;
+      }
+      continue;
+    }
+    if (arg.startsWith('--')) {
+      console.error(`Unknown flag: ${arg}`);
+      printUsage(console.error);
+      process.exitCode = 1;
+      return;
+    }
+    if (text == null) {
+      text = arg;
+    }
+  }
+
+  if (!text || !text.trim()) {
+    console.error('Missing feedback text.');
+    printUsage(console.error);
+    process.exitCode = 1;
+    return;
+  }
+
+  const record = { ts: Date.now(), text: text.trim() };
+  if (typeof targetFile === 'string' && targetFile) record.targetFile = targetFile;
+  const sessionId = process.env.UKIT_SESSION_ID;
+  if (sessionId) record.sessionId = sessionId;
+
+  try {
+    await appendManualLine(projectRoot, record);
+  } catch (error) {
+    console.error(`Failed to record feedback: ${error?.message ?? error}`);
+    process.exitCode = 1;
+    return;
+  }
+  console.log('feedback recorded');
+}

package/src/cli/commands/memory.js

@@ -8,6 +8,7 @@ import {
   runProjectHygiene,
 } from '../../core/memory/store.js';
 import {
+  addRecord,
   getRecord,
   loadRecords,
   queryRecords,
@@ -20,7 +21,9 @@ import { inspectRuntimeConfig } from '../../core/runtimeConfig.js';
 import { buildRuntimePaths } from '../../core/runtimePaths.js';
 import { pathExists } from '../../core/fileOps.js';
 import { detectProjectContext } from '../../context/detectProjectContext.js';
+import { listLedgerFiles, LEDGER_DIR_REL } from '../../diagnostics/ledgerFiles.js';
 import fs from 'node:fs/promises';
+import path from 'node:path';
 
 const HELP_FLAGS = new Set(['--help', '-h', 'help']);
 
@@ -177,6 +180,192 @@ async function runMemoryV2(projectRoot, args) {
   throw new Error(`Unknown memory v2 op: ${op}. Expected list|show|promote|stale|migrate.`);
 }
 
+// ---- `ukit memory promote` — MEMORY.md `## ukit-learned` lane (SPEC §7a) ----
+
+const LEARNED_START = '<!-- ukit-learned:start -->';
+const LEARNED_END = '<!-- ukit-learned:end -->';
+const MEM_REF_RE = /<!--\s*mem:(mem_[0-9a-f]{12})\s*-->/g;
+
+// Approved promotable records: active project_rule/procedure belonging to the
+// project, not bulk-migrated v1 leftovers (created_by 'migration'), and not
+// still-pending candidates (meta.legacyStatus 'pending').
+async function collectPromotableRecords(projectRoot, projectId) {
+  const records = await loadRecords(projectRoot);
+  return records.filter((r) =>
+    (r.type === 'project_rule' || r.type === 'procedure')
+    && r.status === 'active'
+    && r.created_by !== 'migration'
+    && r.meta?.legacyStatus !== 'pending'
+    && (r.project_id == null || r.project_id === projectId));
+}
+
+function renderLearnedBlock(records) {
+  const lines = [LEARNED_START, '## ukit-learned'];
+  for (const r of records) {
+    lines.push(`- [${r.type}] ${r.text}  <!-- mem:${r.id} -->`);
+  }
+  lines.push(LEARNED_END);
+  return lines.join('\n');
+}
+
+// Ids already referenced in mem:<id> comments OUTSIDE the managed block are
+// user-promoted manually — promote must not duplicate them inside the block.
+function externallyReferencedIds(content) {
+  const withoutBlock = content.replace(
+    new RegExp(`${escapeRe(LEARNED_START)}[\\s\\S]*?${escapeRe(LEARNED_END)}`, 'g'),
+    '',
+  );
+  const ids = new Set();
+  for (const m of withoutBlock.matchAll(MEM_REF_RE)) ids.add(m[1]);
+  return ids;
+}
+
+function escapeRe(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+async function writeTextAtomic(filePath, text) {
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  const tmp = `${filePath}.tmp-${process.pid}-${Math.random().toString(16).slice(2)}`;
+  await fs.writeFile(tmp, text);
+  await fs.rename(tmp, filePath);
+}
+
+async function runMemoryPromote(projectRoot, args) {
+  const dryRun = args.includes('--dry-run');
+  const projectId = (await detectProjectContext(projectRoot)).project.name;
+  const memoryMdPath = path.join(projectRoot, 'docs', 'MEMORY.md');
+
+  let existing = '';
+  try {
+    existing = await fs.readFile(memoryMdPath, 'utf8');
+  } catch {
+    existing = '';
+  }
+
+  const outsideIds = externallyReferencedIds(existing);
+  const promotable = (await collectPromotableRecords(projectRoot, projectId))
+    .filter((r) => !outsideIds.has(r.id));
+
+  const block = renderLearnedBlock(promotable);
+
+  if (dryRun) {
+    console.log('[UKit] memory promote (dry-run) — rendered block:');
+    console.log(block);
+    console.log(`[UKit] promoted: ${promotable.length} records → docs/MEMORY.md (dry-run)`);
+    return;
+  }
+
+  let next;
+  const startIdx = existing.indexOf(LEARNED_START);
+  const endIdx = existing.indexOf(LEARNED_END);
+  if (startIdx >= 0 && endIdx > startIdx) {
+    next = `${existing.slice(0, startIdx)}${block}${existing.slice(endIdx + LEARNED_END.length)}`;
+  } else if (existing.length > 0) {
+    next = `${existing.replace(/\s*$/, '')}\n\n${block}\n`;
+  } else {
+    next = `${block}\n`;
+  }
+
+  await writeTextAtomic(memoryMdPath, next);
+  console.log(`[UKit] promoted: ${promotable.length} records → docs/MEMORY.md`);
+}
+
+// ---- `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 lastCommand = receipts.length > 0
+    ? String(receipts[receipts.length - 1].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);
+}
+
+async function runMemoryEpisode(projectRoot, args) {
+  const dryRun = args.includes('--dry-run');
+  const sessionFlag = extractFlag(args, '--session').value;
+
+  const { config } = await inspectRuntimeConfig(projectRoot);
+  if (config?.memoryV2?.enabled === false) {
+    console.log('[UKit] episode: skipped (memoryV2 disabled)');
+    return;
+  }
+
+  const { ledger, ledgerKey } = await resolveLedger(projectRoot, sessionFlag);
+  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);
+  if (existing.some((r) => r.meta?.ledgerKey === ledgerKey)) {
+    console.log('[UKit] episode: already recorded');
+    return;
+  }
+
+  const ttlDays = Number(config?.memoryV2?.episodeTtlDays) || 90;
+  const projectId = (await detectProjectContext(projectRoot)).project.name;
+  const record = await addRecord(projectRoot, {
+    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 },
+  });
+  console.log(`[UKit] episode: recorded ${record.id} for session ${sessionId}`);
+}
+
 export async function runMemory({ projectRoot, argv = [] }) {
   const runtimePaths = buildRuntimePaths(projectRoot);
   if (!(await pathExists(runtimePaths.runtimeRoot))) {
@@ -242,6 +431,53 @@ export async function runMemory({ projectRoot, argv = [] }) {
     return;
   }
 
+  if (subcommand === 'learn') {
+    const applyFlag = rest.includes('--apply');
+    const knownFlags = new Set(['--apply']);
+    const minFlag = extractFlag(rest, '--min');
+    const projectFlag = extractFlag(minFlag.rest, '--project');
+    for (const arg of projectFlag.rest) {
+      if (arg.startsWith('--') && !knownFlags.has(arg)) {
+        throw new Error(`Unknown flag for memory learn: ${arg}`);
+      }
+    }
+    const minCount = minFlag.value != null ? Number(minFlag.value) : undefined;
+    if (minFlag.value != null && (!Number.isFinite(minCount) || minCount < 1)) {
+      throw new Error(`Invalid --min value: ${minFlag.value}`);
+    }
+    const projectId = projectFlag.value ?? (await detectProjectContext(projectRoot)).project.name;
+
+    const { proposeFromPatterns } = await import('../../learning/patternProposals.js');
+    const result = await proposeFromPatterns(projectRoot, projectId, {
+      minCount,
+      dryRun: !applyFlag,
+    });
+    if (result.error) {
+      console.log(`[UKit] memory learn: ${result.error}`);
+    }
+
+    if (!applyFlag) {
+      console.log(`[UKit] memory learn (dry-run) — ${result.patternsScanned} pattern(s) scanned, ${result.eligible} eligible.`);
+      for (const entry of result.proposed) {
+        console.log(`  [${entry.status}] ${entry.signature} — ${entry.text}`);
+      }
+      console.log('[UKit] Run `ukit memory learn --apply` to write pending candidates.');
+      return;
+    }
+
+    const proposed = result.proposed.filter((p) => p.status === 'proposed').length;
+    const duplicates = result.proposed.filter((p) => p.status === 'duplicate').length;
+    const skipped = result.proposed.filter((p) => p.status === 'skipped').length;
+    for (const entry of result.proposed) {
+      console.log(`  [${entry.status}] ${entry.signature} — ${entry.text}`);
+    }
+    console.log(`[UKit] memory learn: proposed ${proposed}, duplicate ${duplicates}, skipped ${skipped} for project ${projectId}.`);
+    if (proposed > 0) {
+      console.log('[UKit] Review with `ukit memory list --pending`, then `ukit memory approve <id>`.');
+    }
+    return;
+  }
+
   if (subcommand === 'approve' || subcommand === 'reject') {
     const projectFlagIndex = rest.indexOf('--project');
     const explicitProjectId = projectFlagIndex >= 0 ? rest[projectFlagIndex + 1] : null;
@@ -327,6 +563,16 @@ export async function runMemory({ projectRoot, argv = [] }) {
     return;
   }
 
+  if (subcommand === 'promote') {
+    await runMemoryPromote(projectRoot, rest);
+    return;
+  }
+
+  if (subcommand === 'episode') {
+    await runMemoryEpisode(projectRoot, rest);
+    return;
+  }
+
   if (subcommand === 'forget') {
     const memoryId = rest.join(' ').trim();
     if (!memoryId) {
@@ -353,7 +599,7 @@ export async function runMemory({ projectRoot, argv = [] }) {
 
 export function printMemoryHelp() {
   console.log('UKit Memory Commands');
-  console.log('Usage: ukit memory <list|search|recall|forget|export|propose|approve|reject|hygiene> [args]');
+  console.log('Usage: ukit memory <list|search|recall|forget|export|propose|approve|reject|learn|promote|episode|hygiene> [args]');
   console.log('');
   console.log('Subcommands:');
   console.log('  list               List memory items in shared .ukit/storage/memory');
@@ -365,5 +611,8 @@ export function printMemoryHelp() {
   console.log('  propose "<text>" [--category <name>] [--project <id>]  Propose a project convention for human approval');
   console.log('  approve <id> [--project <id>]  Approve a pending pattern candidate into project conventions');
   console.log('  reject <id> [--project <id>]   Reject a pending pattern candidate');
+  console.log('  learn [--apply] [--min <n>] [--project <id>]  Propose pending candidates from mined failure patterns (dry-run by default)');
+  console.log('  promote [--dry-run]   Render approved rules/procedures into the ## ukit-learned block in docs/MEMORY.md');
+  console.log('  episode [--dry-run] [--session <id>]  Write a session episode record from the exec-ledger');
   console.log('  hygiene [--project <id>]  Run decision-conflict resolution + session archiving now');
 }

package/src/cli/commands/metrics.js

@@ -51,6 +51,16 @@ async function collectFailurePatterns(projectRoot) {
   }
 }
 
+async function lazyCollect(modulePath, exportName, projectRoot) {
+  try {
+    const mod = await import(modulePath);
+    if (typeof mod?.[exportName] !== 'function') return null;
+    return await mod[exportName](projectRoot);
+  } catch {
+    return null;
+  }
+}
+
 function printRouteOutcomes(routeOutcomes) {
   console.log('route-outcomes');
   console.log(`  ledgers: ${routeOutcomes.ledgersScanned}  audit rows: ${routeOutcomes.auditRowsScanned}  joined: ${routeOutcomes.joined}  coverage: ${(routeOutcomes.joinCoverage * 100).toFixed(1)}%  unmatched audit: ${routeOutcomes.unmatchedAudit}  unmatched ledger: ${routeOutcomes.unmatchedLedger}`);
@@ -85,6 +95,92 @@ function printMemory(memory) {
   console.log(`memory: v2 records=${memory.total}${statusPairs ? `  (${statusPairs})` : ''}`);
 }
 
+function printFeedback(feedback) {
+  console.log('feedback');
+  if (!feedback) {
+    console.log('  n/a');
+    return;
+  }
+  const kinds = Object.entries(feedback.byKind ?? {})
+    .map(([kind, count]) => `${kind}=${count}`).join('  ');
+  console.log(`  ${kinds || '(none)'}`);
+  const events = Array.isArray(feedback.events) ? feedback.events.slice(0, 5) : [];
+  for (const event of events) {
+    console.log(`  ${event.kind}: ${event.detail ?? ''}`);
+  }
+}
+
+function printSkills(skillAccuracy) {
+  console.log('skills');
+  if (!skillAccuracy) {
+    console.log('  n/a');
+    return;
+  }
+  const skills = Object.entries(skillAccuracy.skills ?? {});
+  if (skills.length === 0) {
+    console.log('  (none)');
+  } else {
+    console.log('  skill\ttriggers\tjoined\taccuracy');
+    for (const [id, bucket] of skills) {
+      const accuracy = bucket.accuracy === null ? 'n/a' : bucket.accuracy.toFixed(2);
+      console.log(`  ${id}\t${bucket.triggers}\t${bucket.joined}\t${accuracy}`);
+    }
+  }
+  const low = Array.isArray(skillAccuracy.lowAccuracy) ? skillAccuracy.lowAccuracy : [];
+  if (low.length > 0) {
+    console.log(`  lowAccuracy: ${low.map((e) => `${e.id}=${e.accuracy.toFixed(2)}`).join('  ')}`);
+  }
+}
+
+async function collectLearningSuggestions(projectRoot) {
+  try {
+    const raw = await fs.readFile(
+      path.join(projectRoot, '.ukit', 'storage', 'learning', 'suggestions.json'), 'utf8');
+    const doc = JSON.parse(raw);
+    const suggestions = Array.isArray(doc?.suggestions) ? doc.suggestions : [];
+    return {
+      pending: suggestions.length,
+      targets: suggestions.map((s) => s?.target).filter(Boolean),
+      generatedAt: doc?.generatedAt ?? null,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function printLearning(learning) {
+  console.log('learning');
+  if (!learning) {
+    console.log('  n/a');
+    return;
+  }
+  console.log(`  pending=${learning.pending}${learning.generatedAt ? `  generatedAt=${learning.generatedAt}` : ''}`);
+  for (const target of learning.targets.slice(0, 10)) {
+    console.log(`  - ${target}`);
+  }
+}
+
+function printLaneStats(laneStats) {
+  console.log('retriever-lanes');
+  if (!laneStats) {
+    console.log('  n/a');
+    return;
+  }
+  if (laneStats.empty) {
+    console.log('  (no retriever-lanes.jsonl data)');
+    return;
+  }
+  const lanes = Object.entries(laneStats.lanes ?? {});
+  if (lanes.length === 0) {
+    console.log('  (none)');
+    return;
+  }
+  console.log('  lane\tretrievals\ttotalHits\texclusive\tavgWeight\tcontribution');
+  for (const [lane, bucket] of lanes) {
+    console.log(`  ${lane}\t${bucket.retrievals}\t${bucket.totalHits}\t${bucket.exclusive}\t${bucket.avgWeight.toFixed(2)}\t${bucket.contribution.toFixed(2)}`);
+  }
+}
+
 export async function runMetrics({ projectRoot, argv = [] }) {
   if (argv.some((flag) => HELP_FLAGS.has(flag))) {
     printUsage();
@@ -111,8 +207,12 @@ export async function runMetrics({ projectRoot, argv = [] }) {
   }));
   const failurePatterns = await collectFailurePatterns(projectRoot);
   const memory = await collectMemorySummary(projectRoot);
+  const feedback = await lazyCollect('../../diagnostics/feedbackEvents.js', 'collectFeedbackEvents', projectRoot);
+  const skillAccuracy = await lazyCollect('../../diagnostics/skillAccuracy.js', 'collectSkillAccuracy', projectRoot);
+  const laneStats = await lazyCollect('../../diagnostics/laneStats.js', 'collectLaneStats', projectRoot);
+  const learning = await collectLearningSuggestions(projectRoot);
 
-  const rollup = { routeOutcomes, failurePatterns, memory };
+  const rollup = { routeOutcomes, failurePatterns, memory, feedback, skillAccuracy, laneStats, learning };
 
   if (argv.includes('--json')) {
     console.log(JSON.stringify(rollup, null, 2));
@@ -123,5 +223,13 @@ export async function runMetrics({ projectRoot, argv = [] }) {
   console.log('');
   printFailurePatterns(failurePatterns);
   console.log('');
+  printFeedback(feedback);
+  console.log('');
+  printSkills(skillAccuracy);
+  console.log('');
+  printLaneStats(laneStats);
+  console.log('');
+  printLearning(learning);
+  console.log('');
   printMemory(memory);
 }

package/src/cli/index.js

@@ -8,6 +8,7 @@ import { runMemory } from './commands/memory.js';
 import { runUpdate } from './commands/update.js';
 import { runCode } from './commands/code.js';
 import { runMetrics } from './commands/metrics.js';
+import { runFeedback } from './commands/feedback.js';
 
 const GLOBAL_FLAGS = new Set(['--help', '-h', '--version', '-v']);
 
@@ -71,6 +72,11 @@ export async function runCli({ argv, packageRoot, projectRoot, packageVersion })
     return;
   }
 
+  if (command === 'feedback') {
+    await runFeedback({ projectRoot, argv: commandArgv });
+    return;
+  }
+
   if (command === 'update') {
     await runUpdate({ packageVersion, argv: commandArgv });
     return;
@@ -105,6 +111,7 @@ export async function runCli({ argv, packageRoot, projectRoot, packageVersion })
     console.log('  status             Show UKit runtime status');
     console.log('  memory             Inspect shared UKit memory');
     console.log('  metrics            Telemetry roll-up (route outcomes, failure patterns, memory)');
+    console.log('  feedback           Record or list wrong-route feedback labels');
     console.log('  update             Upgrade the global UKit CLI to the latest version');
     console.log('  version            Show UKit version');
     console.log('');

package/src/core/codeintel/retriever.js

@@ -1,5 +1,7 @@
 import fs from 'node:fs/promises';
+import fsSync from 'node:fs';
 import path from 'node:path';
+import { createHash } from 'node:crypto';
 
 import { getArtifactPath, INDEX_ARTIFACTS, INDEX_SCHEMA_VERSION, normalizeRelative } from '../../index/paths.js';
 import { loadRuntimeConfig } from '../runtimeConfig.js';
@@ -260,6 +262,55 @@ function concatMerge(lanes) {
   return merged;
 }
 
+// FR-202b (TASK-228): fire-and-forget lane telemetry. One JSONL line per
+// retrieval at .ukit/storage/cache/retriever-lanes.jsonl; query persisted as
+// sha256 only (no raw prompts on disk). Failures are swallowed — telemetry
+// must never break retrieve(). Sync writes keep the fire-and-forget contract
+// deterministic for callers/tests.
+const RETRIEVER_LANES_MAX_BYTES = 256 * 1024;
+const RETRIEVER_LANES_KEEP_LINES = 2000;
+
+function emitRetrieverLaneTelemetry(rootDir, { query, mode, lanes, omitted, mergedPaths, merge, weights }) {
+  try {
+    const laneStats = {};
+    for (const laneName of LANE_ORDER) {
+      const lane = lanes.get(laneName);
+      const stat = {
+        hits: lane ? lane.length : 0,
+        weightUsed: weights?.[laneName] ?? 0,
+      };
+      const why = omitted?.find((o) => o?.what === `${laneName}-lane`)?.why;
+      if (!lane && why) stat.omitted = why;
+      if (lane) stat.paths = lane.map((entry) => entry.path).slice(0, 100);
+      laneStats[laneName] = stat;
+    }
+    const event = {
+      ts: Date.now(),
+      query: createHash('sha256').update(String(query ?? '')).digest('hex'),
+      mode,
+      lanes: laneStats,
+      mergedPaths,
+      merge,
+    };
+    const filePath = path.join(rootDir, '.ukit', 'storage', 'cache', 'retriever-lanes.jsonl');
+    fsSync.mkdirSync(path.dirname(filePath), { recursive: true });
+    // Best-effort cap: past 256 KiB keep only the newest ~2000 lines.
+    try {
+      const st = fsSync.statSync(filePath);
+      if (st.size > RETRIEVER_LANES_MAX_BYTES) {
+        const kept = fsSync.readFileSync(filePath, 'utf8').split('\n').filter(Boolean)
+          .slice(-RETRIEVER_LANES_KEEP_LINES);
+        fsSync.writeFileSync(filePath, kept.length ? `${kept.join('\n')}\n` : '');
+      }
+    } catch {
+      // Missing/unreadable file is fine — append below recreates it.
+    }
+    fsSync.appendFileSync(filePath, `${JSON.stringify(event)}\n`);
+  } catch {
+    // Telemetry is advisory; never propagate.
+  }
+}
+
 /**
  * retrieve(projectRoot, query, { mode, limit, snapshot, merge, weights }) →
  *   { anchors, evidence, relations, omitted }
@@ -384,6 +435,20 @@ export async function retrieve(projectRoot, query, { mode = 'search', limit, sna
     omitted.push({ what: 'anchors', why: 'no-match' });
   }
 
+  // FR-202b: emit lane telemetry only when a merge result exists — skipped
+  // entirely on the early no-index return and on empty merges.
+  if (merged.length > 0) {
+    emitRetrieverLaneTelemetry(rootDir, {
+      query: normalizedQuery,
+      mode,
+      lanes,
+      omitted,
+      mergedPaths: anchors.map((a) => a.path),
+      merge: effectiveMerge,
+      weights: effectiveWeights,
+    });
+  }
+
   const relations = [];
 
   // Impact mode — 1-hop reverse imports: who imports each anchor file.