@ngockhoale/ukit 2.6.8 → 2.6.10

package/CHANGELOG.md

@@ -2,6 +2,58 @@
 
 All notable changes to UKit are documented here.
 
+## 2.6.9 - 2026-09-19
+
+Code Intelligence scale release — cycle C30 (CI-301..305, TASK-218..222).
+
+- Vector lane: dep-free `vectorProvider.js` (FNV-1a feature-hashed embeddings,
+  L2-normalized, cosine-ranked; injectable loader seam for real embeddings,
+  degrade to hashed/null); wired as RRF lane w=0.6 between bm25 and semantic.
+- Analogy lane: `analogy.js` fingerprints memory `procedure` records + index
+  symbols/files; `analogy` compile mode ranks by Jaccard, hits land in
+  packet.memory + L2 evidence.
+- Co-change mining: `cochange.js` mines `git log --name-only` (spawnSync,
+  bounded, core.quotePath=false) into `cochange.json`; impact sets gain a
+  provenance-preserving co-change lane (kind:'cochange', confidence=count/10).
+- L3 summaries: `summaries.js` extractive docblock/symbol summaries for
+  deep_flow+analogy packets; `packetToText` renders `summary:` lines.
+- Graph store: `graph.js` `codegraph.json` JsonGraphStore (imports+calls+
+  cochange → nodes/edges, content-gated atomic write), contract-only
+  scip/pdg/lsp stubs via `createGraphProvider`.
+- Derived artifacts wired into `ukit index build|refresh`, stale-refresh,
+  install, and index scripts via `buildDerivedIndexArtifacts` (config-gated,
+  never fatal, outside the core build's atomic-rename contract).
+- Config: `codeIntel.{embedding,analogy,cochange,summaries,graph}` +
+  `retriever.weights.vector` validated in runtimeConfig with template parity;
+  `enabled:false` honored for analogy/graph lanes.
+- Verification: full suite 2720/2720 green; unpacked ceiling 6.9MB.
+
+## 2.6.8 - 2026-09-19
+
+Code Intelligence Plane + memory v2 release — cycles C26–C29
+(TASK-001..011, CI-201..206, DOC-201..206, DOC-301..305).
+
+- Memory v2: 4-type record model (`project_rule|derived_fact|episode|procedure`),
+  atomic `records.json` store, backup-first idempotent migration from v1,
+  `ukit memory v2` ops; legacy `.ukit/storage/memory/` layout and all
+  `ukit memory *` subcommands stay compatible.
+- Code Intelligence Plane: `compileContext` → Context Packet v1 with
+  peek→expand→read levels and token budgets; Task Router v1; freshness
+  identity (`HEAD + overlay + config`) with incremental dirty-gated reuse
+  and per-branch snapshots; hybrid retriever (exact + symbol + BM25 + RRF
+  rerank); `impact.js` multi-hop impact sets; post-edit `invalidation.js`
+  dirty-set and `diagnostics.js` feeding packet `next_actions`;
+  `TypeScriptSemanticProvider` (optional `typescript` import — no new deps,
+  degrade-safe).
+- CLI: `ukit code peek|search|context|impact` (`--depth`, `--diagnostics`),
+  `ukit index status|doctor`, `ukit doctor --docs` (doc-contract checks).
+- Docs governance: `docContracts.js` validator (links/stale-version/
+  render-vars/commands/budgets/registry/templates/dead-docs/archive-suggestions),
+  `context_layers` + `docs=` route segment, host capability matrix, BUG docs
+  consolidated into `docs/BUG_INDEX.md`, PROMPT_CACHING canonical/vendor split,
+  `templates/instructions/core.md` 210→157 lines.
+- Benchmarks: `scripts/bench/runGold.mjs` scorecard + `--json` export.
+
 ## 2.6.7 - 2026-09-19
 
 Canonical-instructions release — second roadmap slice (cycle C25,

package/package.json

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

package/scripts/index/build-index.mjs

@@ -1,13 +1,14 @@
 #!/usr/bin/env node
 import path from 'node:path';
 
-import { buildCodeIndex } from '../../src/index/buildIndex.js';
+import { buildCodeIndex, buildDerivedIndexArtifacts } from '../../src/index/buildIndex.js';
 
 const args = process.argv.slice(2);
 const rootArg = readFlagValue(args, '--root');
 const rootDir = rootArg ? path.resolve(rootArg) : process.cwd();
 
 const summary = await buildCodeIndex({ rootDir });
+await buildDerivedIndexArtifacts(rootDir);
 
 console.log('[index:build] completed');
 console.log(`root: ${rootDir}`);

package/scripts/index/query-index.mjs

@@ -6,6 +6,7 @@ import {
 } from '../../src/index/queryIndex.js';
 import {
   buildCodeIndex,
+  buildDerivedIndexArtifacts,
   isIndexStale,
   DEFAULT_INDEX_CACHE_MAX_AGE_MS,
 } from '../../src/index/buildIndex.js';
@@ -28,6 +29,7 @@ if (!query) {
   const stale = await isIndexStale({ rootDir, maxAgeMs: DEFAULT_INDEX_CACHE_MAX_AGE_MS });
   if (stale) {
     await buildCodeIndex({ rootDir });
+    await buildDerivedIndexArtifacts(rootDir);
   }
 
   const limit = Number.parseInt(flags.get('--limit') ?? '5', 10);

package/src/cli/commands/indexTools.js

@@ -1,5 +1,6 @@
 import {
   buildCodeIndex,
+  buildDerivedIndexArtifacts,
   isIndexStale,
   DEFAULT_INDEX_CACHE_MAX_AGE_MS,
   getIndexArtifactGeneratedAt,
@@ -42,6 +43,9 @@ export async function runIndexTools({ projectRoot, argv = [] }) {
 
   if (subcommand === 'build' || subcommand === 'refresh') {
     const summary = await buildCodeIndex({ rootDir: projectRoot });
+    // Derived artifacts (CI-303/CI-305): cochange.json + codegraph.json.
+    // Best-effort, config-gated, never fatal.
+    await buildDerivedIndexArtifacts(projectRoot);
     const label = subcommand === 'build' ? 'build' : 'refresh';
     console.log(`[UKit] Index ${label} completed.`);
     console.log(`[UKit] files=${summary.fileCount}, symbols=${summary.symbolCount}, imports=${summary.importCount}`);
@@ -389,6 +393,7 @@ async function refreshIndexIfStale(rootDir) {
   }
 
   await buildCodeIndex({ rootDir });
+  await buildDerivedIndexArtifacts(rootDir);
 
   if (lastRefreshMs !== null) {
     console.log(`[UKit] stale index refreshed (last=${new Date(lastRefreshMs).toISOString()})`);

package/src/cli/commands/install.js

@@ -2,7 +2,7 @@ import { buildPathConfig } from '../../core/paths.js';
 import { runInstallPipeline } from '../../core/runInstallPipeline.js';
 import { formatRepairReport } from '../../core/repairBrokenHooks.js';
 import { formatGatewayResilienceReport } from '../../core/gatewayResilienceEnv.js';
-import { buildCodeIndex } from '../../index/buildIndex.js';
+import { buildCodeIndex, buildDerivedIndexArtifacts } from '../../index/buildIndex.js';
 import { installIndexRefreshHooks } from '../../index/gitHooks.js';
 import fs from 'node:fs/promises';
 import { pathExists, readJsonIfExists, removeFileOrLinkOnly } from '../../core/fileOps.js';
@@ -323,6 +323,7 @@ export async function runInstall({ packageRoot, projectRoot, packageVersion, arg
   let indexSummary;
   try {
     indexSummary = await buildCodeIndex({ rootDir: projectRoot });
+    await buildDerivedIndexArtifacts(projectRoot);
   } catch (error) {
     console.log('[UKit] Install files synced, but source index build failed.');
     console.log('[UKit] Fix the repo state, then rerun `ukit install` so the AI can index source code first.');

package/src/cli/commands/metrics.js

@@ -0,0 +1,127 @@
+// `ukit metrics` — read-only 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.
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { collectRouteOutcomes } from '../../diagnostics/routeOutcomes.js';
+import { buildRuntimePaths } from '../../core/runtimePaths.js';
+
+const HELP_FLAGS = new Set(['--help', '-h', 'help']);
+const KNOWN_FLAGS = new Set(['--json']);
+
+const MODE_FIELDS = ['routes', 'joined', 'writeOk', 'writeFail', 'verifyAttempted', 'verifyOk', 'verifyFail', 'rescue', 'stalled'];
+
+function printUsage() {
+  console.log('Usage: ukit metrics [--json]');
+  console.log('');
+  console.log('Print a read-only roll-up of UKit telemetry:');
+  console.log('  route-outcomes    route-audit ↔ exec-ledger join stats per mode/taskType');
+  console.log('  failure-patterns  mined failure signatures (n/a when unavailable)');
+  console.log('  memory            v2 record count by status');
+  console.log('');
+  console.log('Options:');
+  console.log('  --json   Print the full roll-up object as JSON');
+}
+
+async function collectMemorySummary(projectRoot) {
+  try {
+    const { memoryV2RecordsPath } = buildRuntimePaths(projectRoot);
+    const raw = await fs.readFile(memoryV2RecordsPath, 'utf8');
+    const doc = JSON.parse(raw);
+    const records = Array.isArray(doc) ? doc : (Array.isArray(doc?.records) ? doc.records : []);
+    const byStatus = {};
+    for (const record of records) {
+      const status = record?.status ?? 'unknown';
+      byStatus[status] = (byStatus[status] ?? 0) + 1;
+    }
+    return { total: records.length, byStatus };
+  } catch {
+    return { total: 0, byStatus: {} };
+  }
+}
+
+async function collectFailurePatterns(projectRoot) {
+  try {
+    const mod = await import('../../diagnostics/failurePatterns.js');
+    if (typeof mod?.mineFailurePatterns !== 'function') return null;
+    return await mod.mineFailurePatterns(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}`);
+  const header = ['mode', ...MODE_FIELDS];
+  console.log(`  ${header.join('\t')}`);
+  for (const [mode, bucket] of Object.entries(routeOutcomes.byMode)) {
+    console.log(`  ${[mode, ...MODE_FIELDS.map((field) => bucket[field] ?? 0)].join('\t')}`);
+  }
+  if (Object.keys(routeOutcomes.byMode).length === 0) {
+    console.log('  (no route-audit data)');
+  }
+}
+
+function printFailurePatterns(failurePatterns) {
+  console.log('failure-patterns');
+  if (!failurePatterns) {
+    console.log('  n/a');
+    return;
+  }
+  const patterns = Array.isArray(failurePatterns.patterns) ? failurePatterns.patterns : [];
+  if (patterns.length === 0) {
+    console.log('  (none)');
+    return;
+  }
+  for (const pattern of patterns) {
+    console.log(`  ${pattern.count}× ${pattern.signature}  sessions=${pattern.sessions}`);
+  }
+}
+
+function printMemory(memory) {
+  const statusPairs = Object.entries(memory.byStatus).map(([status, count]) => `${status}=${count}`).join(' ');
+  console.log(`memory: v2 records=${memory.total}${statusPairs ? `  (${statusPairs})` : ''}`);
+}
+
+export async function runMetrics({ 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 metrics flag(s): ${unknown.join(', ')}`);
+    printUsage();
+    process.exitCode = 1;
+    return;
+  }
+
+  const routeOutcomes = await collectRouteOutcomes(projectRoot).catch((error) => ({
+    ledgersScanned: 0,
+    auditRowsScanned: 0,
+    joined: 0,
+    unmatchedAudit: 0,
+    unmatchedLedger: 0,
+    byMode: {},
+    byTaskType: {},
+    joinCoverage: 0,
+    error: error?.message ?? String(error),
+  }));
+  const failurePatterns = await collectFailurePatterns(projectRoot);
+  const memory = await collectMemorySummary(projectRoot);
+
+  const rollup = { routeOutcomes, failurePatterns, memory };
+
+  if (argv.includes('--json')) {
+    console.log(JSON.stringify(rollup, null, 2));
+    return;
+  }
+
+  printRouteOutcomes(routeOutcomes);
+  console.log('');
+  printFailurePatterns(failurePatterns);
+  console.log('');
+  printMemory(memory);
+}

package/src/cli/index.js

@@ -7,6 +7,7 @@ import { runStatus } from './commands/status.js';
 import { runMemory } from './commands/memory.js';
 import { runUpdate } from './commands/update.js';
 import { runCode } from './commands/code.js';
+import { runMetrics } from './commands/metrics.js';
 
 const GLOBAL_FLAGS = new Set(['--help', '-h', '--version', '-v']);
 
@@ -65,6 +66,11 @@ export async function runCli({ argv, packageRoot, projectRoot, packageVersion })
     return;
   }
 
+  if (command === 'metrics') {
+    await runMetrics({ projectRoot, argv: commandArgv });
+    return;
+  }
+
   if (command === 'update') {
     await runUpdate({ packageVersion, argv: commandArgv });
     return;
@@ -98,6 +104,7 @@ export async function runCli({ argv, packageRoot, projectRoot, packageVersion })
     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('  metrics            Telemetry roll-up (route outcomes, failure patterns, memory)');
     console.log('  update             Upgrade the global UKit CLI to the latest version');
     console.log('  version            Show UKit version');
     console.log('');

package/src/core/codeintel/analogy.js

@@ -0,0 +1,197 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { getArtifactPath, INDEX_ARTIFACTS, INDEX_SCHEMA_VERSION } from '../../index/paths.js';
+import { loadRuntimeConfig } from '../runtimeConfig.js';
+
+// Analogy lane (SPEC §4, CI-302): ranks memory `procedure` records and
+// index-bound file/symbol fingerprints against the query by Jaccard overlap.
+// Read-only over both stores; every failure mode degrades into `omitted`
+// reasons — never throws, never fabricates analogies.
+//
+// fingerprint = sorted-unique normalized features:
+//   lowercase [a-z0-9_$.-] tokens (length >= 3, minus stopwords) plus
+//   camelCase/punctuation sub-splits so `routeTaskFiles` shares features with
+//   "route task files" and `src/routing.js` shares `routing`.
+
+const STOPWORDS = new Set([
+  'the', 'a', 'an', 'and', 'or', 'to', 'for', 'of', 'with', 'in', 'on', 'is', 'are',
+  'this', 'that', 'it', 'as', 'by', 'be', 'use', 'using', 'implement', 'fix', 'task',
+  'cần', 'và', 'là', 'cho', 'một', 'những', 'dùng',
+]);
+
+const MAX_MATCHED_FEATURES = 8;
+const DEFAULT_LIMIT = 5;
+
+function pushToken(set, raw) {
+  const token = String(raw ?? '').toLowerCase();
+  if (token.length >= 3 && !STOPWORDS.has(token)) set.add(token);
+  // Sub-split on punctuation + camelCase boundaries so compound tokens share
+  // features with their parts (e.g. `routeTaskFiles` → route/task/files).
+  const split = String(raw ?? '').replace(/([a-z0-9])([A-Z])/g, '$1 $2');
+  for (const part of split.split(/[^A-Za-z0-9_$]+/)) {
+    const sub = part.toLowerCase();
+    if (sub.length >= 3 && !STOPWORDS.has(sub)) set.add(sub);
+  }
+}
+
+/**
+ * fingerprintText(text) → string[] sorted-unique normalized features.
+ */
+export function fingerprintText(text) {
+  const features = new Set();
+  for (const token of String(text ?? '').split(/[^A-Za-z0-9_$.-]+/)) {
+    pushToken(features, token);
+  }
+  return [...features].sort();
+}
+
+/**
+ * fingerprintRecord(record) → string[] | null.
+ * Only `procedure` records carry an analogy fingerprint (SPEC §4).
+ */
+export function fingerprintRecord(record) {
+  if (!record || typeof record !== 'object') return null;
+  if (record.type !== 'procedure') return null;
+  const parts = [record.text];
+  if (record.meta && typeof record.meta === 'object') {
+    parts.push(JSON.stringify(record.meta));
+  }
+  if (record.provenance) parts.push(record.provenance);
+  return fingerprintText(parts.filter(Boolean).join(' '));
+}
+
+/**
+ * fingerprintFile({ filePath, symbols }) → string[] — path-shape tokens
+ * (incl. dir basenames) + symbol names.
+ */
+export function fingerprintFile({ filePath, symbols } = {}) {
+  const features = new Set(fingerprintText(filePath));
+  for (const sym of Array.isArray(symbols) ? symbols : []) {
+    for (const feature of fingerprintText(sym?.name)) features.add(feature);
+  }
+  return [...features].sort();
+}
+
+async function readArtifact(rootDir, name) {
+  try {
+    const raw = await fs.readFile(getArtifactPath(rootDir, name), 'utf8');
+    const parsed = JSON.parse(raw);
+    if (parsed?.schemaVersion !== undefined && parsed.schemaVersion !== INDEX_SCHEMA_VERSION) {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+// Memory lane — lazy-imported inside try/catch so a missing/disabled memory
+// v2 store degrades instead of throwing.
+async function loadProcedureCandidates(projectRoot, config) {
+  if (config?.memoryV2?.enabled === false) {
+    return { records: null, why: 'memory-unavailable' };
+  }
+  try {
+    const loader = await import('../memory/storeV2Loader.js');
+    const records = await import('../memory/records.js');
+    if (typeof loader?.loadV2Records !== 'function' || typeof records?.isRecordUsable !== 'function') {
+      return { records: null, why: 'memory-unavailable' };
+    }
+    const loaded = await loader.loadV2Records(projectRoot, { type: 'procedure' });
+    if (!Array.isArray(loaded) || loaded.length === 0) {
+      return { records: [], why: 'memory-unavailable' };
+    }
+    return { records: loaded.filter((r) => records.isRecordUsable(r)), why: null };
+  } catch {
+    return { records: null, why: 'memory-unavailable' };
+  }
+}
+
+function jaccard(querySet, candidateFeatures) {
+  let shared = 0;
+  const matched = [];
+  for (const feature of candidateFeatures) {
+    if (querySet.has(feature)) {
+      shared += 1;
+      if (matched.length < MAX_MATCHED_FEATURES) matched.push(feature);
+    }
+  }
+  if (shared === 0) return null;
+  const union = querySet.size + candidateFeatures.length - shared;
+  return { score: shared / union, matched };
+}
+
+/**
+ * findAnalogies(projectRoot, query, { limit = 5 }) →
+ *   { analogies: [{ kind:'procedure'|'code', ref, path?, score, matched:string[] }],
+ *     omitted: [{what,why}] }
+ *
+ * Jaccard over fingerprint sets; `score>0` rows only. Ties → ref localeCompare.
+ */
+export async function findAnalogies(projectRoot, query, { limit = DEFAULT_LIMIT } = {}) {
+  const rootDir = path.resolve(projectRoot ?? process.cwd());
+  const effectiveLimit = Math.max(1, typeof limit === 'number' && Number.isFinite(limit) ? limit : DEFAULT_LIMIT);
+  const omitted = [];
+  const analogies = [];
+
+  const queryFeatures = new Set(fingerprintText(query));
+  if (queryFeatures.size === 0) {
+    omitted.push({ what: 'analogy-lane', why: 'empty-query-features' });
+    return { analogies, omitted };
+  }
+
+  let config = null;
+  try {
+    config = await loadRuntimeConfig(rootDir);
+  } catch {
+    config = null;
+  }
+
+  // Lane 1 — memory `procedure` records.
+  const memory = await loadProcedureCandidates(rootDir, config);
+  if (memory.why) {
+    omitted.push({ what: 'analogy-lane', why: memory.why });
+  }
+  for (const record of memory.records ?? []) {
+    const features = fingerprintRecord(record);
+    if (!features || features.length === 0) continue;
+    const hit = jaccard(queryFeatures, features);
+    if (!hit) continue;
+    analogies.push({ kind: 'procedure', ref: record.id, ...hit });
+  }
+
+  // Lane 2 — index files/symbols (schema-guarded artifact reads).
+  const [filesArtifact, symbolsArtifact] = await Promise.all([
+    readArtifact(rootDir, INDEX_ARTIFACTS.files),
+    readArtifact(rootDir, INDEX_ARTIFACTS.symbols),
+  ]);
+  if (!filesArtifact && !symbolsArtifact) {
+    omitted.push({ what: 'analogy-lane', why: 'index-missing' });
+  }
+  const symbolsByFile = new Map();
+  for (const sym of symbolsArtifact?.items ?? []) {
+    if (!sym?.filePath) continue;
+    const list = symbolsByFile.get(sym.filePath) ?? [];
+    list.push(sym);
+    symbolsByFile.set(sym.filePath, list);
+  }
+  const codePaths = new Set();
+  for (const item of filesArtifact?.items ?? []) {
+    if (item?.filePath) codePaths.add(item.filePath);
+  }
+  for (const filePath of symbolsByFile.keys()) codePaths.add(filePath);
+  for (const filePath of codePaths) {
+    const features = fingerprintFile({ filePath, symbols: symbolsByFile.get(filePath) ?? [] });
+    if (features.length === 0) continue;
+    const hit = jaccard(queryFeatures, features);
+    if (!hit) continue;
+    analogies.push({ kind: 'code', ref: filePath, path: filePath, ...hit });
+  }
+
+  analogies.sort((a, b) => b.score - a.score || a.ref.localeCompare(b.ref));
+  if (analogies.length === 0 && !memory.why && filesArtifact && symbolsArtifact) {
+    omitted.push({ what: 'analogy-lane', why: 'no-match' });
+  }
+  return { analogies: analogies.slice(0, effectiveLimit), omitted };
+}