@ngockhoale/ukit 2.6.7 → 2.6.8

package/src/core/memory/storeV2.js

@@ -0,0 +1,171 @@
+// Memory v2 store — SPEC §3.
+// Single atomic JSON document at <memoryRoot>/v2/records.json
+// ({ schemaVersion: 2, records: [...] }); writes via fileOps.writeJson (tmp+rename).
+// Read ops call ensureMigrated() first so every consumer triggers the lazy
+// v1→v2 migration (SPEC §4); migrate.js is lazy-imported to break the
+// storeV2↔migrate import cycle (runMigration writes via saveRecords).
+
+import fs from 'node:fs/promises';
+import { buildRuntimePaths } from '../runtimePaths.js';
+import { readJsonIfExists, writeJson } from '../fileOps.js';
+import { loadRuntimeConfig } from '../runtimeConfig.js';
+import { createRecord, normalizeRecord } from './records.js';
+
+const SCHEMA_VERSION = 2;
+
+// Per-process memoization for ensureMigrated — one-shot check per projectRoot.
+const migratedRoots = new Set();
+
+async function ensureMigrated(projectRoot) {
+  const key = String(projectRoot);
+  if (migratedRoots.has(key)) return;
+  migratedRoots.add(key); // mark first: a failed/again migration must not loop
+  try {
+    const paths = buildRuntimePaths(projectRoot);
+    let recordsExists = false;
+    try {
+      await fs.access(paths.memoryV2RecordsPath);
+      recordsExists = true;
+    } catch {
+      recordsExists = false;
+    }
+    if (recordsExists) return;
+
+    const config = await loadRuntimeConfig(projectRoot);
+    if (config?.memoryV2?.autoMigrate === false) return;
+
+    const migrate = await import('./migrate.js');
+    if (await migrate.needsMigration(projectRoot)) {
+      await migrate.runMigration(projectRoot);
+    }
+  } catch {
+    // Lazy migration is best-effort: a failed auto-run must not break reads.
+  }
+}
+
+function isRawRecord(input) {
+  return input && typeof input === 'object' && typeof input.id === 'string'
+    && typeof input.status === 'string';
+}
+
+/**
+ * loadRecords(projectRoot) → record[] — tolerant: invalid entries skipped.
+ */
+export async function loadRecords(projectRoot) {
+  await ensureMigrated(projectRoot);
+  const { records } = await readStore(projectRoot);
+  return records;
+}
+
+async function readStore(projectRoot) {
+  const paths = buildRuntimePaths(projectRoot);
+  let doc;
+  try {
+    doc = await readJsonIfExists(paths.memoryV2RecordsPath);
+  } catch {
+    return { records: [], invalidSkipped: 1 };
+  }
+  if (!doc) return { records: [], invalidSkipped: 0 };
+
+  const rawRecords = Array.isArray(doc.records) ? doc.records : [];
+  const records = [];
+  let invalidSkipped = Array.isArray(doc.records) ? 0 : 1;
+  for (const raw of rawRecords) {
+    const normalized = normalizeRecord(raw);
+    if (normalized) records.push(normalized);
+    else invalidSkipped += 1;
+  }
+  return { records, invalidSkipped };
+}
+
+/**
+ * saveRecords(projectRoot, records) → void — atomic write; drops unrecoverable entries.
+ */
+export async function saveRecords(projectRoot, records) {
+  const paths = buildRuntimePaths(projectRoot);
+  const normalized = (Array.isArray(records) ? records : [])
+    .map((raw) => normalizeRecord(raw))
+    .filter(Boolean);
+  await writeJson(paths.memoryV2RecordsPath, {
+    schemaVersion: SCHEMA_VERSION,
+    records: normalized,
+  });
+}
+
+/**
+ * addRecord(projectRoot, recordInput) → record
+ * Accepts either createRecord-style input or a full raw record (normalized).
+ */
+export async function addRecord(projectRoot, recordInput) {
+  const record = isRawRecord(recordInput)
+    ? normalizeRecord(recordInput)
+    : createRecord(recordInput);
+  if (!record) {
+    throw new Error('addRecord: input could not be normalized into a valid record');
+  }
+  const { records } = await readStore(projectRoot);
+  await saveRecords(projectRoot, [...records, record]);
+  return record;
+}
+
+const PATCHABLE_FIELDS = ['type', 'scope', 'text', 'provenance', 'confidence',
+  'valid_until', 'status', 'project_id', 'meta', 'source_fingerprint'];
+
+/**
+ * updateRecord(projectRoot, id, patch) → record | null
+ */
+export async function updateRecord(projectRoot, id, patch = {}) {
+  await ensureMigrated(projectRoot);
+  const { records } = await readStore(projectRoot);
+  const index = records.findIndex((r) => r.id === id);
+  if (index === -1) return null;
+
+  const next = { ...records[index] };
+  for (const field of PATCHABLE_FIELDS) {
+    if (Object.prototype.hasOwnProperty.call(patch, field)) {
+      next[field] = patch[field];
+    }
+  }
+  const normalized = normalizeRecord(next);
+  if (!normalized) {
+    throw new Error(`updateRecord: patch produces an invalid record (id ${id})`);
+  }
+  records[index] = normalized;
+  await saveRecords(projectRoot, records);
+  return normalized;
+}
+
+/**
+ * getRecord(projectRoot, id) → record | null
+ */
+export async function getRecord(projectRoot, id) {
+  await ensureMigrated(projectRoot);
+  const { records } = await readStore(projectRoot);
+  return records.find((r) => r.id === id) ?? null;
+}
+
+/**
+ * queryRecords(projectRoot, { type?, scope?, status?, projectId? }) → record[]
+ */
+export async function queryRecords(projectRoot, { type, scope, status, projectId } = {}) {
+  const records = await loadRecords(projectRoot);
+  return records.filter((r) => (type == null || r.type === type)
+    && (scope == null || r.scope === scope)
+    && (status == null || r.status === status)
+    && (projectId == null || r.project_id === projectId));
+}
+
+/**
+ * stats(projectRoot) → { total, byType, byStatus, invalidSkipped }
+ */
+export async function stats(projectRoot) {
+  await ensureMigrated(projectRoot);
+  const { records, invalidSkipped } = await readStore(projectRoot);
+  const byType = {};
+  const byStatus = {};
+  for (const r of records) {
+    byType[r.type] = (byType[r.type] ?? 0) + 1;
+    byStatus[r.status] = (byStatus[r.status] ?? 0) + 1;
+  }
+  return { total: records.length, byType, byStatus, invalidSkipped };
+}

package/src/core/memory/storeV2Loader.js

@@ -0,0 +1,22 @@
+// Lazy/defensive bridge to storeV2.js (owned by TASK-002).
+// Real storeV2.queryRecords performs ensureMigrated auto-migration internally —
+// consumers must never call migration themselves; just call this and treat an
+// empty result as "fall back to the legacy memory path".
+
+/**
+ * loadV2Records(projectRoot) → record[] | []
+ * Returns [] when storeV2 is unavailable, disabled upstream, or the v2 store
+ * holds no records yet. Callers decide fallback.
+ */
+export async function loadV2Records(projectRoot, filter = {}) {
+  try {
+    const storeV2 = await import('./storeV2.js');
+    if (typeof storeV2?.queryRecords !== 'function') {
+      return [];
+    }
+    const records = await storeV2.queryRecords(projectRoot, filter);
+    return Array.isArray(records) ? records : [];
+  } catch {
+    return [];
+  }
+}

package/src/core/runtimeConfig.js

@@ -157,6 +157,36 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
         cap: 'smart',
       },
     },
+    codeIntel: {
+      enabled: true,
+      router: { enabled: true, defaultMode: 'auto' },
+      budgets: {
+        peek: 500,
+        targeted: 2000,
+        impact: 3000,
+        explore: 4000,
+        deep_flow: 6000,
+        analogy: 4000,
+      },
+      freshness: { guardLevel: 'L0', autoRefresh: false, incremental: true },
+      retriever: {
+        limit: 20,
+        bm25: { k1: 1.2, b: 0.75 },
+        merge: 'rrf',
+        rrfK: 60,
+        weights: { exact: 1.0, symbol: 1.2, bm25: 0.8, semantic: 1.0 },
+      },
+      impact: { defaultDepth: 2, maxDepth: 4, maxNodes: 200 },
+      diagnostics: { enabled: true, timeoutMs: 8000 },
+      providers: { semantic: 'null' },
+    },
+    memoryV2: {
+      enabled: true,
+      autoMigrate: true,
+      episodeTtlDays: 90,
+      promotion: { episodeToRuleRequiresApproval: true },
+      recall: { maxRecords: 8 },
+    },
     memory: {
       enabled: true,
       autoCapture: true,
@@ -354,6 +384,101 @@ export function validateRuntimeConfig(config) {
     }
   }
 
+  if (!isPlainObject(config.codeIntel)) {
+    errors.push('codeIntel must be an object.');
+  } else {
+    const codeIntel = config.codeIntel;
+    pushBooleanError(errors, codeIntel.enabled, 'codeIntel.enabled');
+    if (!isPlainObject(codeIntel.router)) {
+      errors.push('codeIntel.router must be an object.');
+    } else {
+      pushBooleanError(errors, codeIntel.router.enabled, 'codeIntel.router.enabled');
+      const VALID_ROUTER_MODES = new Set(['auto', 'none', 'peek', 'targeted', 'explore', 'impact', 'deep_flow', 'analogy']);
+      if (!VALID_ROUTER_MODES.has(codeIntel.router.defaultMode)) {
+        errors.push(`codeIntel.router.defaultMode must be one of: ${[...VALID_ROUTER_MODES].join(', ')}.`);
+      }
+    }
+    if (!isPlainObject(codeIntel.budgets)) {
+      errors.push('codeIntel.budgets must be an object.');
+    } else {
+      for (const key of ['peek', 'targeted', 'impact', 'explore', 'deep_flow', 'analogy']) {
+        pushPositiveNumberError(errors, codeIntel.budgets[key], `codeIntel.budgets.${key}`);
+      }
+    }
+    if (!isPlainObject(codeIntel.freshness)) {
+      errors.push('codeIntel.freshness must be an object.');
+    } else {
+      const VALID_GUARD_LEVELS = new Set(['L0', 'L1', 'L2', 'L3', 'L4']);
+      if (!VALID_GUARD_LEVELS.has(codeIntel.freshness.guardLevel)) {
+        errors.push(`codeIntel.freshness.guardLevel must be one of: ${[...VALID_GUARD_LEVELS].join(', ')}.`);
+      }
+      pushBooleanError(errors, codeIntel.freshness.autoRefresh, 'codeIntel.freshness.autoRefresh');
+      pushBooleanError(errors, codeIntel.freshness.incremental, 'codeIntel.freshness.incremental');
+    }
+    if (!isPlainObject(codeIntel.retriever)) {
+      errors.push('codeIntel.retriever must be an object.');
+    } else {
+      pushPositiveNumberError(errors, codeIntel.retriever.limit, 'codeIntel.retriever.limit');
+      if (!isPlainObject(codeIntel.retriever.bm25)) {
+        errors.push('codeIntel.retriever.bm25 must be an object.');
+      } else {
+        pushPositiveNumberError(errors, codeIntel.retriever.bm25.k1, 'codeIntel.retriever.bm25.k1');
+        pushPositiveNumberError(errors, codeIntel.retriever.bm25.b, 'codeIntel.retriever.bm25.b');
+      }
+      const VALID_RETRIEVER_MERGES = new Set(['rrf', 'concat']);
+      if (!VALID_RETRIEVER_MERGES.has(codeIntel.retriever.merge)) {
+        errors.push(`codeIntel.retriever.merge must be one of: ${[...VALID_RETRIEVER_MERGES].join(', ')}.`);
+      }
+      pushPositiveNumberError(errors, codeIntel.retriever.rrfK, 'codeIntel.retriever.rrfK');
+      if (!isPlainObject(codeIntel.retriever.weights)) {
+        errors.push('codeIntel.retriever.weights must be an object.');
+      } else {
+        for (const lane of ['exact', 'symbol', 'bm25', 'semantic']) {
+          if (typeof codeIntel.retriever.weights[lane] !== 'number' || Number.isNaN(codeIntel.retriever.weights[lane])) {
+            errors.push(`codeIntel.retriever.weights.${lane} must be a number.`);
+          }
+        }
+      }
+    }
+    if (!isPlainObject(codeIntel.impact)) {
+      errors.push('codeIntel.impact must be an object.');
+    } else {
+      pushPositiveNumberError(errors, codeIntel.impact.defaultDepth, 'codeIntel.impact.defaultDepth');
+      pushPositiveNumberError(errors, codeIntel.impact.maxDepth, 'codeIntel.impact.maxDepth');
+      pushPositiveNumberError(errors, codeIntel.impact.maxNodes, 'codeIntel.impact.maxNodes');
+    }
+    if (!isPlainObject(codeIntel.diagnostics)) {
+      errors.push('codeIntel.diagnostics must be an object.');
+    } else {
+      pushBooleanError(errors, codeIntel.diagnostics.enabled, 'codeIntel.diagnostics.enabled');
+      pushPositiveNumberError(errors, codeIntel.diagnostics.timeoutMs, 'codeIntel.diagnostics.timeoutMs');
+    }
+    if (!isPlainObject(codeIntel.providers)) {
+      errors.push('codeIntel.providers must be an object.');
+    } else {
+      pushNonEmptyStringError(errors, codeIntel.providers.semantic, 'codeIntel.providers.semantic');
+    }
+  }
+
+  if (!isPlainObject(config.memoryV2)) {
+    errors.push('memoryV2 must be an object.');
+  } else {
+    const memoryV2 = config.memoryV2;
+    pushBooleanError(errors, memoryV2.enabled, 'memoryV2.enabled');
+    pushBooleanError(errors, memoryV2.autoMigrate, 'memoryV2.autoMigrate');
+    pushPositiveNumberError(errors, memoryV2.episodeTtlDays, 'memoryV2.episodeTtlDays');
+    if (!isPlainObject(memoryV2.promotion)) {
+      errors.push('memoryV2.promotion must be an object.');
+    } else {
+      pushBooleanError(errors, memoryV2.promotion.episodeToRuleRequiresApproval, 'memoryV2.promotion.episodeToRuleRequiresApproval');
+    }
+    if (!isPlainObject(memoryV2.recall)) {
+      errors.push('memoryV2.recall must be an object.');
+    } else {
+      pushPositiveNumberError(errors, memoryV2.recall.maxRecords, 'memoryV2.recall.maxRecords');
+    }
+  }
+
   if (!isPlainObject(config.memory)) {
     errors.push('memory must be an object.');
   } else {

package/src/core/runtimePaths.js

@@ -4,6 +4,7 @@ export function buildRuntimePaths(projectRoot) {
   const runtimeRoot = path.join(projectRoot, '.ukit');
   const storageRoot = path.join(runtimeRoot, 'storage');
   const memoryRoot = path.join(storageRoot, 'memory');
+  const memoryV2Dir = path.join(memoryRoot, 'v2');
   const cacheRoot = path.join(storageRoot, 'cache');
 
   return {
@@ -11,6 +12,8 @@ export function buildRuntimePaths(projectRoot) {
     storageRoot,
     cacheRoot,
     memoryRoot,
+    memoryV2Dir,
+    memoryV2RecordsPath: path.join(memoryV2Dir, 'records.json'),
     teeCacheDir: path.join(cacheRoot, 'tee'),
     configPath: path.join(storageRoot, 'config.json'),
     promptCachePath: path.join(cacheRoot, 'prompt-cache.json'),

package/src/index/taskRouting.js

@@ -14,6 +14,34 @@ import {
 
 const MAX_ACTIVE_ROUTE_SKILLS = 2;
 
+// Declared complexity→docs mapping (DOC-201 FR-001). Canonical declaration lives in
+// manifests/documentation.yaml `context_layers`; this constant is the routing-side copy
+// (the router must not read the registry at runtime — zero new deps). Keep in sync.
+// `queued-task` is omitted v1: docs/TASKS.md does not exist in every repo (SPEC §14).
+// `shared-simple` mirrors the non-trivial layer to match deriveContextMode's FULL lane.
+const CONTEXT_LAYER_DOCS = {
+  taskTypes: {
+    trivial: [],
+    simple: ['docs/MEMORY.md'],
+    'non-trivial': ['docs/MEMORY.md', 'docs/PROJECT.md', 'docs/CODE_MAP.md'],
+    'shared-simple': ['docs/MEMORY.md', 'docs/PROJECT.md', 'docs/CODE_MAP.md'],
+  },
+  intents: {
+    'open-ended': ['docs/STATUS.md'],
+    'open-ended-status': ['docs/STATUS.md'],
+    handoff: ['docs/AI_HANDOFF/INDEX.md'],
+  },
+};
+const CONTEXT_DOCS_MAX = 4;
+
+function deriveContextDocs({ taskType = null, intentMode = null } = {}) {
+  const docs = [
+    ...(CONTEXT_LAYER_DOCS.taskTypes[taskType] ?? []),
+    ...(CONTEXT_LAYER_DOCS.intents[intentMode] ?? []),
+  ];
+  return unique(docs).slice(0, CONTEXT_DOCS_MAX);
+}
+
 export async function deriveTaskRoute({
   rootDir = process.cwd(),
   promptText = '',
@@ -206,6 +234,7 @@ export function buildRouteSummary({
   nextAction = null,
   handoffBudget = null,
   worklogBudget = null,
+  contextDocs = null,
 } = {}) {
   const autonomyLevel = routingContext.autonomyLevel ?? 'balanced';
   const delegationRecommendation = deriveDelegationRecommendation({
@@ -264,10 +293,19 @@ export function buildRouteSummary({
   );
   const nextActionCommand = compactHelperLane ? null : nextAction?.command ?? null;
   const handoffFile = routingContext.intentMode === 'handoff' ? 'docs/AI_HANDOFF/ACTIVE.md' : null;
+  // DOC-201 FR-002: resolved context-layer docs (declared in manifests/documentation.yaml).
+  // Explicit override wins; otherwise derive from taskType + intentMode.
+  const resolvedContextDocs = ((Array.isArray(contextDocs) ? contextDocs : null)
+    ?? deriveContextDocs({ taskType, intentMode: routingContext.intentMode ?? null }))
+    .slice(0, CONTEXT_DOCS_MAX);
+  const docsSegment = resolvedContextDocs.length > 0
+    ? `docs=[${resolvedContextDocs.slice(0, CONTEXT_DOCS_MAX).map((p) => path.posix.basename(String(p).replaceAll('\\', '/'))).join(',')}]`
+    : null;
   const summaryLine = [
     routingContext.taskType ? `task=${routingContext.taskType}` : null,
     handoffFile ? `handoff=${handoffFile}` : null,
     formatCompactSegment('targets', primaryTargets),
+    docsSegment,
     formatCompactSegment('tests', relatedTests),
     formatCompactSegment('styles', styleFiles),
     editGuardHint ? `editGuard=${editGuardHint}` : null,
@@ -303,6 +341,7 @@ export function buildRouteSummary({
     nextActionCommand,
     helperHint,
     contextMode,
+    contextDocs: resolvedContextDocs,
     line: summaryLine || 'task=unknown',
   };
 }

package/templates/.claude/ukit/index/route-task.mjs

@@ -22,6 +22,34 @@ const {
 } = indexCore;
 
 const MAX_ACTIVE_ROUTE_SKILLS = 2;
+
+// Declared complexity→docs mapping (DOC-201 FR-001). Canonical declaration lives in
+// manifests/documentation.yaml `context_layers`; this constant is the routing-side copy
+// (the router must not read the registry at runtime — zero new deps). Keep in sync.
+// `queued-task` is omitted v1: docs/TASKS.md does not exist in every repo (SPEC §14).
+// `shared-simple` mirrors the non-trivial layer to match deriveContextMode's FULL lane.
+const CONTEXT_LAYER_DOCS = {
+  taskTypes: {
+    trivial: [],
+    simple: ['docs/MEMORY.md'],
+    'non-trivial': ['docs/MEMORY.md', 'docs/PROJECT.md', 'docs/CODE_MAP.md'],
+    'shared-simple': ['docs/MEMORY.md', 'docs/PROJECT.md', 'docs/CODE_MAP.md'],
+  },
+  intents: {
+    'open-ended': ['docs/STATUS.md'],
+    'open-ended-status': ['docs/STATUS.md'],
+    handoff: ['docs/AI_HANDOFF/INDEX.md'],
+  },
+};
+const CONTEXT_DOCS_MAX = 4;
+
+function deriveContextDocs({ taskType = null, intentMode = null } = {}) {
+  const docs = [
+    ...(CONTEXT_LAYER_DOCS.taskTypes[taskType] ?? []),
+    ...(CONTEXT_LAYER_DOCS.intents[intentMode] ?? []),
+  ];
+  return unique(docs).slice(0, CONTEXT_DOCS_MAX);
+}
 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',
@@ -1293,6 +1321,7 @@ function formatDisplayRouteSummary(routeSummary = null, routingContext = {}) {
     taskSegment,
     extractRouteLineSegment(line, 'handoff'),
     extractRouteLineSegment(line, 'targets'),
+    extractRouteLineSegment(line, 'docs'),
     extractRouteLineSegment(line, 'tests'),
     extractRouteLineSegment(line, 'styles'),
     policySegment,
@@ -2108,6 +2137,7 @@ function buildRouteSummary({
   contextRecommendation = null,
   verificationRecommendation = null,
   nextAction = null,
+  contextDocs = null,
 } = {}) {
   const autonomyLevel = routingContext.autonomyLevel ?? 'balanced';
   const delegationRecommendation = deriveDelegationRecommendation({
@@ -2174,10 +2204,19 @@ function buildRouteSummary({
   const nextActionCommand = compactHelperLane ? null : nextAction?.command ?? null;
   const handoffFile = routingContext.intentMode === 'handoff' ? 'docs/AI_HANDOFF/ACTIVE.md' : null;
   const visionLane = Boolean(routingContext.visionLane);
+  // DOC-201 FR-002: resolved context-layer docs (declared in manifests/documentation.yaml).
+  // Explicit override wins; otherwise derive from taskType + intentMode.
+  const resolvedContextDocs = ((Array.isArray(contextDocs) ? contextDocs : null)
+    ?? deriveContextDocs({ taskType, intentMode: routingContext.intentMode ?? null }))
+    .slice(0, CONTEXT_DOCS_MAX);
+  const docsSegment = resolvedContextDocs.length > 0
+    ? `docs=[${resolvedContextDocs.slice(0, CONTEXT_DOCS_MAX).map((p) => path.posix.basename(String(p).replaceAll('\\', '/'))).join(',')}]`
+    : null;
   const line = [
     routingContext.taskType ? `task=${routingContext.taskType}` : null,
     handoffFile ? `handoff=${handoffFile}` : null,
     formatCompactSegment('targets', primaryTargets),
+    docsSegment,
     formatCompactSegment('tests', relatedTests),
     formatCompactSegment('styles', styleFiles),
     editGuardHint ? `editGuard=${editGuardHint}` : null,
@@ -2209,6 +2248,7 @@ function buildRouteSummary({
     nextActionCommand,
     helperHint,
     contextMode,
+    contextDocs: resolvedContextDocs,
     ...(visionLane ? {
       visionLane: true,
       visionReason: routingContext.visionReason ?? null,