@ngockhoale/ukit 2.6.8 → 2.6.10

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) {

package/src/core/codeintel/graph.js

@@ -0,0 +1,291 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { getArtifactPath, INDEX_ARTIFACTS, INDEX_SCHEMA_VERSION } from '../../index/paths.js';
+import { readJsonIfExists, writeJson } from '../fileOps.js';
+import { createEdge } from './providers.js';
+import { COCHANGE_SCHEMA_VERSION } from './cochange.js';
+
+// Graph contract + JSON store (SPEC §9 — CI-305). Builds `.cache/index/codegraph.json`
+// from existing index artifacts (imports.json + calls.json, + cochange.json when
+// present) and exposes a GraphProvider seam so SCIP/PDG/LSP backends can slot in
+// later without touching consumers. No SQLite, no new deps — providers other than
+// 'json' are contract-only NullGraphProvider stubs this cycle.
+
+export const GRAPH_SCHEMA_VERSION = 1;
+
+const VALID_GRAPH_STORES = new Set(['json', 'scip', 'pdg', 'lsp', 'null']);
+
+async function readArtifact(rootDir, name, expectedSchemaVersion) {
+  try {
+    const raw = await fs.readFile(getArtifactPath(rootDir, name), 'utf8');
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object') return null;
+    if (expectedSchemaVersion !== undefined && parsed.schemaVersion !== expectedSchemaVersion) {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+// Same specifier-resolution discipline as impact.js — local copy so this lane
+// does not import same-wave sibling internals.
+function resolveRelativeSpecifier(fromFile, specifier, fileSet) {
+  const candidates = [];
+  if (specifier.startsWith('.')) {
+    const base = path.posix.normalize(path.posix.join(path.posix.dirname(fromFile), specifier));
+    candidates.push(base, `${base}.js`, `${base}.ts`, `${base}.mjs`, `${base}.jsx`, `${base}.tsx`, `${base}/index.js`, `${base}/index.ts`);
+  } else {
+    candidates.push(specifier);
+  }
+  for (const candidate of candidates) {
+    if (fileSet.has(candidate)) return candidate;
+  }
+  return null;
+}
+
+/**
+ * buildGraphArtifact(projectRoot) → artifact | null
+ *
+ * Merges imports.json + calls.json (+ cochange.json when present) into a
+ * codegraph.json artifact: { schemaVersion, generatedAt, nodes, edges }.
+ * Node ids: files → their relative path, symbols → `symbol:<name>`.
+ * Edges use the canonical createEdge shape. Writes the artifact atomically via
+ * fileOps.writeJson; returns null when no source artifacts exist. Never throws
+ * on missing/partial sources.
+ */
+export async function buildGraphArtifact(projectRoot) {
+  const rootDir = path.resolve(projectRoot ?? process.cwd());
+
+  const [importsArtifact, callsArtifact, cochangeArtifact, filesArtifact] = await Promise.all([
+    readArtifact(rootDir, INDEX_ARTIFACTS.imports, INDEX_SCHEMA_VERSION),
+    readArtifact(rootDir, INDEX_ARTIFACTS.calls, INDEX_SCHEMA_VERSION),
+    readArtifact(rootDir, INDEX_ARTIFACTS.cochange, COCHANGE_SCHEMA_VERSION),
+    readArtifact(rootDir, INDEX_ARTIFACTS.files, INDEX_SCHEMA_VERSION),
+  ]);
+
+  if (!importsArtifact && !callsArtifact && !cochangeArtifact) {
+    return null;
+  }
+
+  const fileSet = new Set();
+  for (const file of filesArtifact?.items ?? []) {
+    if (file?.filePath) fileSet.add(file.filePath);
+  }
+  for (const imp of importsArtifact?.items ?? []) {
+    if (imp?.from) fileSet.add(imp.from);
+  }
+  for (const call of callsArtifact?.items ?? []) {
+    if (call?.filePath) fileSet.add(call.filePath);
+  }
+
+  const nodes = new Map(); // id → node
+  const edges = new Map(); // dedupe key → edge
+  const addFileNode = (filePath) => {
+    if (filePath && !nodes.has(filePath)) {
+      nodes.set(filePath, { id: filePath, kind: 'file', path: filePath });
+    }
+  };
+  const addSymbolNode = (name, filePath) => {
+    if (!name) return null;
+    const id = `symbol:${name}`;
+    if (!nodes.has(id)) {
+      nodes.set(id, { id, kind: 'symbol', path: filePath ?? null });
+    }
+    return id;
+  };
+  const addEdge = (edge, dedupeExtra = '') => {
+    const key = `${edge.from}»${edge.to}»${edge.kind}»${dedupeExtra}`;
+    if (!edges.has(key)) edges.set(key, edge);
+  };
+
+  // import edges: from-file → resolved target file
+  for (const imp of importsArtifact?.items ?? []) {
+    if (!imp?.from || !imp?.to) continue;
+    addFileNode(imp.from);
+    const target = resolveRelativeSpecifier(imp.from, imp.to, fileSet) ?? imp.to;
+    if (target === imp.from) continue;
+    addFileNode(target);
+    addEdge(createEdge({
+      from: imp.from,
+      to: target,
+      kind: 'import',
+      provider: 'json-graph',
+      evidence: INDEX_ARTIFACTS.imports,
+    }));
+  }
+
+  // call edges: caller file → callee file (resolved via symbol→file map);
+  // symbol nodes recorded regardless so queries can address them.
+  const symbolToFile = new Map();
+  for (const call of callsArtifact?.items ?? []) {
+    if (call?.filePath && call?.symbol && !symbolToFile.has(call.symbol)) {
+      symbolToFile.set(call.symbol, call.filePath);
+    }
+  }
+  for (const call of callsArtifact?.items ?? []) {
+    if (!call?.filePath) continue;
+    addFileNode(call.filePath);
+    if (call?.symbol) addSymbolNode(call.symbol, call.filePath);
+    for (const name of call.calls ?? []) {
+      const target = symbolToFile.get(name);
+      if (!target || target === call.filePath) continue;
+      addEdge(createEdge({
+        from: call.filePath,
+        to: target,
+        kind: 'call',
+        provider: 'json-graph',
+        evidence: INDEX_ARTIFACTS.calls,
+      }), name);
+    }
+  }
+
+  // co-change edges: pair endpoints become file nodes; count feeds confidence.
+  for (const pair of cochangeArtifact?.pairs ?? []) {
+    if (!pair?.a || !pair?.b) continue;
+    addFileNode(pair.a);
+    addFileNode(pair.b);
+    const confidence = Math.min(1, (pair.count ?? 1) / 10);
+    addEdge(createEdge({
+      from: pair.a,
+      to: pair.b,
+      kind: 'cochange',
+      confidence,
+      provider: 'json-graph',
+      evidence: INDEX_ARTIFACTS.cochange,
+    }), String(pair.count ?? ''));
+    addEdge(createEdge({
+      from: pair.b,
+      to: pair.a,
+      kind: 'cochange',
+      confidence,
+      provider: 'json-graph',
+      evidence: INDEX_ARTIFACTS.cochange,
+    }), String(pair.count ?? ''));
+  }
+
+  const artifact = {
+    schemaVersion: GRAPH_SCHEMA_VERSION,
+    generatedAt: new Date().toISOString(),
+    nodes: [...nodes.values()],
+    edges: [...edges.values()],
+  };
+
+  try {
+    // Content-gated write: unchanged graph (ignoring generatedAt) must not
+    // bump the artifact mtime — refresh's "no rewrite when nothing changed"
+    // guarantee covers derived artifacts too.
+    const graphPath = getArtifactPath(rootDir, INDEX_ARTIFACTS.codegraph);
+    const existing = await readJsonIfExists(graphPath);
+    const strip = ({ generatedAt, ...rest }) => rest;
+    if (!existing || JSON.stringify(strip(existing)) !== JSON.stringify(strip(artifact))) {
+      await writeJson(graphPath, artifact);
+    }
+  } catch {
+    // Artifact-write failure (read-only .cache, EACCES) is non-fatal — the
+    // in-memory artifact is still returned for the caller/summary.
+  }
+  return artifact;
+}
+
+/**
+ * JsonGraphStore — GraphProvider over `.cache/index/codegraph.json`.
+ * Schema-guarded (GRAPH_SCHEMA_VERSION); a missing/mismatched/corrupt artifact
+ * yields empty results per op, never throws.
+ */
+export class JsonGraphStore {
+  constructor(projectRoot) {
+    this.name = 'json';
+    this.rootDir = path.resolve(projectRoot ?? process.cwd());
+    this._artifactPromise = null;
+  }
+
+  capabilities() {
+    return { nodes: true, edges: true, queries: true };
+  }
+
+  async _load() {
+    if (!this._artifactPromise) {
+      this._artifactPromise = (async () => {
+        const artifact = await readJsonIfExists(getArtifactPath(this.rootDir, INDEX_ARTIFACTS.codegraph));
+        if (!artifact || typeof artifact !== 'object') return null;
+        if (artifact.schemaVersion !== GRAPH_SCHEMA_VERSION) return null;
+        if (!Array.isArray(artifact.nodes) || !Array.isArray(artifact.edges)) return null;
+        return artifact;
+      })();
+    }
+    return this._artifactPromise;
+  }
+
+  async nodes() {
+    const artifact = await this._load();
+    return artifact?.nodes ?? [];
+  }
+
+  async edgesFrom(id) {
+    const artifact = await this._load();
+    if (!artifact || typeof id !== 'string') return [];
+    return artifact.edges.filter((edge) => edge?.from === id);
+  }
+
+  /**
+   * query(q) → edge[] | null. Resolves a node id (file path or `symbol:` id) to
+   * its outgoing edges; null when the node is absent or no artifact exists.
+   */
+  async query(q) {
+    const artifact = await this._load();
+    if (!artifact) return null;
+    const nodeId = typeof q === 'object' && q !== null ? q.path ?? q.id ?? null : q;
+    if (typeof nodeId !== 'string' || nodeId === '') return null;
+    const exists = artifact.nodes.some((node) => node?.id === nodeId);
+    if (!exists) return null;
+    return artifact.edges.filter((edge) => edge?.from === nodeId);
+  }
+}
+
+/**
+ * NullGraphProvider — contract-only stub for SCIP/PDG/LSP/'null' backends.
+ * All capabilities false; every op returns empty/null. Never throws.
+ */
+export class NullGraphProvider {
+  constructor(backend = 'null') {
+    this.name = backend;
+  }
+
+  capabilities() {
+    return { nodes: false, edges: false, queries: false };
+  }
+
+  async nodes() {
+    return [];
+  }
+
+  async edgesFrom() {
+    return [];
+  }
+
+  async query() {
+    return null;
+  }
+}
+
+/**
+ * createGraphProvider({ projectRoot?, config? }) → GraphProvider
+ * codeIntel.graph.store: 'json' (default/unset) → JsonGraphStore;
+ * 'scip' | 'pdg' | 'lsp' | 'null' → NullGraphProvider (contract-only seam).
+ */
+export function createGraphProvider({ projectRoot, config } = {}) {
+  if (config?.codeIntel?.graph?.enabled === false) {
+    return new NullGraphProvider('disabled');
+  }
+  const store = config?.codeIntel?.graph?.store;
+  if (store === undefined || store === 'json') {
+    return new JsonGraphStore(projectRoot);
+  }
+  if (VALID_GRAPH_STORES.has(store)) {
+    return new NullGraphProvider(store);
+  }
+  return new NullGraphProvider('null');
+}

package/src/core/codeintel/impact.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 
 import { getArtifactPath, INDEX_ARTIFACTS, INDEX_SCHEMA_VERSION } from '../../index/paths.js';
 import { loadRuntimeConfig } from '../runtimeConfig.js';
+import { readCoChanges, coChangeEdges } from './cochange.js';
 
 // Multi-hop impact/trace engine (SPEC §4) — cycle-safe BFS over imports.json +
 // calls.json edges. `dependents` walks reverse edges (who imports the seed),
@@ -247,5 +248,27 @@ export async function impactSet(projectRoot, seeds, {
   };
   if (frontierCheck('rev') || (wantDeps && frontierCheck('fwd'))) truncated = true;
 
+  // Co-change lane (SPEC §6): when enabled (in-code default true) and the
+  // direction touches dependents, union kind:'cochange' edges for seed peers
+  // (count ≥ minCount) as context — peers join `nodes` at hop:0 with via:[],
+  // not as graph hops. Missing artifact → omitted reason; never fatal.
+  const cochangeConfig = config?.codeIntel?.cochange;
+  const cochangeEnabled = cochangeConfig?.enabled !== false;
+  if (cochangeEnabled && wantRev) {
+    const cochangeArtifact = await readCoChanges(rootDir);
+    if (!cochangeArtifact) {
+      omitted.push({ what: 'cochange-lane', why: 'index-missing' });
+    } else {
+      const minCount = typeof cochangeConfig?.minCount === 'number' ? cochangeConfig.minCount : 2;
+      const coEdges = await coChangeEdges(rootDir, seedFiles, { minCount });
+      for (const edge of coEdges) {
+        emitEdge(edge);
+        if (!nodes.has(edge.to)) {
+          nodes.set(edge.to, { file: edge.to, hop: 0, via: [] });
+        }
+      }
+    }
+  }
+
   return { nodes: [...nodes.values()], edges, truncated, omitted };
 }

package/src/core/codeintel/packet.js

@@ -108,6 +108,7 @@ export function packetToText(packet) {
   lines.push('## Evidence');
   for (const e of packet.evidence ?? []) {
     lines.push(`- [${e.level}/${e.source}] ${e.path ?? ''} — ${e.why ?? ''}`);
+    if (e.summary) lines.push(`  summary: ${e.summary}`);
     if (e.excerpt) lines.push(`  ${e.excerpt}`);
   }
   if ((packet.evidence ?? []).length === 0) lines.push('(none)');