@ngockhoale/ukit 2.6.8 → 2.6.9

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.9",
   "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/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 };
+}

package/src/core/codeintel/cochange.js

@@ -0,0 +1,205 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+import { getArtifactPath, INDEX_ARTIFACTS } from '../../index/paths.js';
+import { writeJson } from '../fileOps.js';
+
+// Co-change mining (SPEC §6 — CI-303). Parses bounded `git log --name-only`
+// history into co-commit pair counts persisted as `.cache/index/cochange.json`.
+// The artifact feeds `impactSet` context edges (kind:'cochange') only — it does
+// NOT create edges in the structural import/call graph. Never throws: non-git
+// dirs and git failures yield null.
+
+export const COCHANGE_SCHEMA_VERSION = 1;
+
+const MAX_FILES_PER_COMMIT = 50;
+const GIT_MAX_BUFFER = 16 * 1024 * 1024;
+
+// Same discipline as freshness.js runGit: spawnSync (no shell), bounded
+// timeout/maxBuffer, null on any failure — never throws.
+function runGit(rootDir, args, timeoutMs) {
+  try {
+    const result = spawnSync('git', args, {
+      cwd: rootDir,
+      encoding: 'utf8',
+      timeout: timeoutMs,
+      maxBuffer: GIT_MAX_BUFFER,
+    });
+    if (result.error || result.status !== 0) return null;
+    return result.stdout ?? '';
+  } catch {
+    return null;
+  }
+}
+
+function getHeadSha(rootDir, timeoutMs) {
+  const out = runGit(rootDir, ['rev-parse', 'HEAD'], timeoutMs);
+  const sha = (out || '').trim();
+  return /^[0-9a-f]{40}$/i.test(sha) ? sha.toLowerCase() : null;
+}
+
+// Parses `git log --name-only --format=sha:%H` output into
+// [{ sha, files: string[] }] commits. File lines are the non-sha, non-blank
+// lines following a `sha:` header.
+function parseLog(output) {
+  const commits = [];
+  let current = null;
+  for (const line of output.split('\n')) {
+    if (line.startsWith('sha:')) {
+      const sha = line.slice(4).trim();
+      if (/^[0-9a-f]{40}$/i.test(sha)) {
+        current = { sha: sha.toLowerCase(), files: [] };
+        commits.push(current);
+      } else {
+        current = null;
+      }
+      continue;
+    }
+    if (!current) continue;
+    const rel = line.trim();
+    if (rel) current.files.push(rel);
+  }
+  return commits;
+}
+
+function pairKey(a, b) {
+  return a < b ? `${a}|${b}` : `${b}|${a}`;
+}
+
+/**
+ * mineCoChanges(projectRoot, { maxCommits?, timeoutMs? })
+ *   → artifact { schemaVersion, generatedAt, headSha,
+ *                pairs: [{a,b,count,lastSha}] sorted a|b asc,
+ *                fileCounts: {file: n}, truncated: bool }
+ *   → null when git is unavailable/fails.
+ * Writes getArtifactPath(root, 'cochange') when non-null.
+ */
+export async function mineCoChanges(projectRoot, { maxCommits = 500, timeoutMs = 5000 } = {}) {
+  const rootDir = path.resolve(projectRoot ?? process.cwd());
+  const cap = Number.isFinite(Number(maxCommits)) && Number(maxCommits) > 0
+    ? Math.floor(Number(maxCommits))
+    : 500;
+  const timeout = Number.isFinite(Number(timeoutMs)) && Number(timeoutMs) > 0
+    ? Math.floor(Number(timeoutMs))
+    : 5000;
+
+  const headSha = getHeadSha(rootDir, timeout);
+  if (!headSha) return null;
+
+  // Fetch cap+1 so we can detect truncation when history runs deeper.
+  const log = runGit(
+    rootDir,
+    ['-c', 'core.quotePath=false', 'log', '--name-only', '--format=sha:%H', '-n', String(cap + 1)],
+    timeout,
+  );
+  if (log === null) return null;
+
+  let commits = parseLog(log);
+  const truncated = commits.length > cap;
+  if (truncated) commits = commits.slice(0, cap);
+
+  const fileCounts = {};
+  const pairs = new Map(); // 'a|b' → { a, b, count, lastSha }
+  for (const commit of commits) {
+    const seen = new Set(commit.files);
+    for (const rel of seen) {
+      fileCounts[rel] = (fileCounts[rel] ?? 0) + 1;
+    }
+    // Giant commits (merge/squash noise) still count for fileCounts but are
+    // skipped for pair accumulation.
+    if (seen.size > MAX_FILES_PER_COMMIT) continue;
+    const files = [...seen];
+    for (let i = 0; i < files.length; i += 1) {
+      for (let j = i + 1; j < files.length; j += 1) {
+        const a = files[i] < files[j] ? files[i] : files[j];
+        const b = files[i] < files[j] ? files[j] : files[i];
+        const key = pairKey(a, b);
+        const existing = pairs.get(key);
+        if (existing) {
+          existing.count += 1;
+          // git log is newest-first: keep the first-seen sha (latest commit).
+        } else {
+          pairs.set(key, { a, b, count: 1, lastSha: commit.sha });
+        }
+      }
+    }
+  }
+
+  const artifact = {
+    schemaVersion: COCHANGE_SCHEMA_VERSION,
+    generatedAt: new Date().toISOString(),
+    headSha,
+    pairs: [...pairs.values()].sort((x, y) => pairKey(x.a, x.b).localeCompare(pairKey(y.a, y.b))),
+    fileCounts,
+    truncated,
+  };
+
+  try {
+    await writeJson(getArtifactPath(rootDir, INDEX_ARTIFACTS.cochange), artifact);
+  } catch {
+    // Artifact write failure is non-fatal: caller still gets the data.
+  }
+  return artifact;
+}
+
+/**
+ * readCoChanges(projectRoot) → artifact | null
+ * Schema-guarded: schemaVersion !== COCHANGE_SCHEMA_VERSION → null.
+ */
+export async function readCoChanges(projectRoot) {
+  const rootDir = path.resolve(projectRoot ?? process.cwd());
+  try {
+    const raw = await fs.readFile(getArtifactPath(rootDir, INDEX_ARTIFACTS.cochange), 'utf8');
+    const artifact = JSON.parse(raw);
+    if (!artifact || typeof artifact !== 'object') return null;
+    if (artifact.schemaVersion !== COCHANGE_SCHEMA_VERSION) return null;
+    if (!Array.isArray(artifact.pairs)) return null;
+    return artifact;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * coChangeEdges(projectRoot, seeds, { minCount? })
+ *   → edge[] { from: seed, to: peer, kind: 'cochange',
+ *              confidence: min(1, count/10), provider: 'git-cochange',
+ *              evidence: 'cochange.json', snapshot: headSha }
+ * Returns [] when the artifact is missing/stale or no pairs qualify.
+ */
+export async function coChangeEdges(projectRoot, seeds, { minCount = 2 } = {}) {
+  const artifact = await readCoChanges(projectRoot);
+  if (!artifact) return [];
+  const threshold = Number.isFinite(Number(minCount)) ? Number(minCount) : 2;
+  const seedSet = new Set(
+    Array.isArray(seeds) ? seeds.filter((s) => typeof s === 'string' && s.length > 0) : [],
+  );
+  if (seedSet.size === 0) return [];
+
+  const edges = [];
+  for (const pair of artifact.pairs) {
+    if (!pair?.a || !pair?.b || typeof pair.count !== 'number') continue;
+    if (pair.count < threshold) continue;
+    let from = null;
+    let to = null;
+    if (seedSet.has(pair.a) && !seedSet.has(pair.b)) {
+      from = pair.a;
+      to = pair.b;
+    } else if (seedSet.has(pair.b) && !seedSet.has(pair.a)) {
+      from = pair.b;
+      to = pair.a;
+    }
+    if (!from) continue;
+    edges.push({
+      from,
+      to,
+      kind: 'cochange',
+      confidence: Math.min(1, pair.count / 10),
+      provider: 'git-cochange',
+      evidence: 'cochange.json',
+      snapshot: artifact.headSha,
+    });
+  }
+  return edges;
+}

package/src/core/codeintel/compiler.js

@@ -8,6 +8,8 @@ import { retrieve } from './retriever.js';
 import { impactSet } from './impact.js';
 import { readDirty } from './invalidation.js';
 import { runDiagnostics } from './diagnostics.js';
+import { findAnalogies } from './analogy.js';
+import { summarizeFile } from './summaries.js';
 import { createEdge } from './providers.js';
 import { loadRuntimeConfig } from '../runtimeConfig.js';
 
@@ -21,8 +23,10 @@ import { loadRuntimeConfig } from '../runtimeConfig.js';
 //   peek                → L0 outline only (no excerpts, no relations)
 //   targeted | explore  → L1 + anchors + relations
 //   impact              → L2 + 1-hop reverse-import edges (retrieve mode impact)
-//   deep_flow | analogy → routed but no graph/embedding lanes in v1 →
-//                         `omitted: { what:'graph evidence', why:'provider unavailable' }`
+//   analogy             → L3 + procedural-fingerprint lane (memory procedures
+//                         + index symbols/files ranked by Jaccard) + summaries
+//   deep_flow           → L3 + deterministic extractive summaries on top-N
+//                         path evidence (summaries.js — no graph lane in v1)
 //   read                → L2 excerpts; emitted when depth >= 2 or `read:true`.
 //
 // Budget units are token estimates (≈ 4 chars/token over serialized evidence).
@@ -40,11 +44,13 @@ const DEPTH_LEVEL = Object.freeze({
   targeted: 'L1',
   explore: 'L1',
   impact: 'L2',
-  deep_flow: 'L2',
-  analogy: 'L2',
+  deep_flow: 'L3',
+  analogy: 'L3',
 });
 
-const UNAVAILABLE_LANES = new Set(['deep_flow', 'analogy']);
+// Kept for the unavailable-lane contract — deep_flow became a real L3 lane in
+// CI-304, so the set is empty but the omission mechanism remains for future lanes.
+const UNAVAILABLE_LANES = new Set();
 
 function estimateTokens(value) {
   try {
@@ -218,10 +224,10 @@ export async function compileContext(projectRoot, task, options = {}) {
           from: edge.from,
           to: edge.to,
           kind: edge.kind ?? 'import',
-          confidence: 1,
-          provider: 'index-file',
-          evidence: 'imports.json',
-          snapshot: typeof identity.identity === 'string' ? identity.identity : null,
+          confidence: typeof edge.confidence === 'number' ? edge.confidence : 1,
+          provider: edge.provider ?? 'index-file',
+          evidence: edge.evidence ?? 'imports.json',
+          snapshot: edge.snapshot ?? (typeof identity.identity === 'string' ? identity.identity : null),
         })),
       };
       for (const entry of impact.omitted ?? []) packet.omitted.push(entry);
@@ -233,6 +239,50 @@ export async function compileContext(projectRoot, task, options = {}) {
     }
   }
 
+  // Analogy lane (SPEC §4/§5, CI-302): fingerprints memory `procedure`
+  // records + index symbols/files, ranks by Jaccard. Procedure hits land in
+  // `packet.memory` + L2 memory evidence; code hits become anchors + L2 index
+  // evidence. Read-only, degrades into `omitted` — never throws.
+  if (mode === 'analogy' && config?.codeIntel?.analogy?.enabled !== false) {
+    try {
+      const analogyLimit = typeof config?.codeIntel?.analogy?.limit === 'number'
+        ? config.codeIntel.analogy.limit
+        : 5;
+      const lane = await findAnalogies(rootDir, query, { limit: analogyLimit });
+      const seenAnchorPaths = new Set((result.anchors ?? []).map((a) => a?.path));
+      for (const entry of lane.analogies ?? []) {
+        if (entry.kind === 'procedure') {
+          result.evidence.push({
+            level: 'L2',
+            source: 'memory',
+            why: `analogy: ${entry.ref} (score ${entry.score.toFixed(2)})`,
+            ...(entry.path ? { path: entry.path } : {}),
+          });
+          packet.memory.push({ id: entry.ref, score: entry.score });
+        } else {
+          result.evidence.push({
+            level: 'L2',
+            source: 'index',
+            why: `analogy: ${entry.ref} (score ${entry.score.toFixed(2)})`,
+            path: entry.path,
+          });
+          if (entry.path && !seenAnchorPaths.has(entry.path)) {
+            seenAnchorPaths.add(entry.path);
+            result.anchors.push({ path: entry.path });
+          }
+        }
+      }
+      if ((lane.analogies ?? []).length === 0) {
+        packet.omitted.push({ what: 'analogy-lane', why: 'no-match' });
+      }
+      for (const entry of lane.omitted ?? []) {
+        packet.omitted.push(entry);
+      }
+    } catch {
+      packet.omitted.push({ what: 'analogy-lane', why: 'analogy-error' });
+    }
+  }
+
   // L0 peek emits outline-level evidence only: same paths, no excerpts.
   const candidates = (result.evidence ?? []).map((item) => {
     const next = { ...item, level };
@@ -240,6 +290,29 @@ export async function compileContext(projectRoot, task, options = {}) {
     return next;
   });
 
+  // L3 summaries lane (SPEC §7, CI-304): attach a deterministic extractive
+  // summary to the top `codeIntel.summaries.maxItems` (default 5) evidence
+  // items that carry a path. Pre-budget so token cost is accounted for.
+  if (level === 'L3' && config?.codeIntel?.summaries?.enabled !== false) {
+    const maxItems = typeof config?.codeIntel?.summaries?.maxItems === 'number'
+      ? config.codeIntel.summaries.maxItems
+      : 5;
+    let attached = 0;
+    for (const item of candidates) {
+      if (attached >= maxItems) break;
+      if (!item.path) continue;
+      try {
+        const result = await summarizeFile(rootDir, item.path);
+        if (result && result.summary) {
+          item.summary = result.summary;
+          attached += 1;
+        }
+      } catch {
+        // summary lane degrades silently — evidence stays valid without it
+      }
+    }
+  }
+
   // L2 read lane: attach excerpts to the top candidates only.
   if (wantRead && level !== 'L0') {
     for (const item of candidates) {