@ngockhoale/ukit 2.6.6 → 2.6.8

package/src/core/memory/retrieval.js

@@ -6,6 +6,9 @@ import {
   writePromptCacheEntry,
 } from '../token/index.js';
 import { listMemoryItems } from './store.js';
+import { isRecordUsable } from './records.js';
+import { loadV2Records } from './storeV2Loader.js';
+import { loadRuntimeConfig } from '../runtimeConfig.js';
 
 const STOPWORDS = new Set([
   'the', 'a', 'an', 'and', 'or', 'to', 'for', 'of', 'with', 'in', 'on', 'is', 'are',
@@ -83,6 +86,7 @@ function getTimestamp(item) {
   return item.content?.updatedAt
     ?? item.content?.endedAt
     ?? item.content?.startedAt
+    ?? item.created_at
     ?? 0;
 }
 
@@ -158,7 +162,106 @@ function buildSearchResult(item, relevanceScore) {
   };
 }
 
+// ---- Memory v2 records path (SPEC §2–§3) ----
+
+const RECORD_TYPE_WEIGHTS = Object.freeze({
+  project_rule: 7,
+  derived_fact: 5,
+  procedure: 5,
+  episode: 3,
+});
+
+// Lazy import: storeV2.js is owned by TASK-002; missing module or a disabled
+// memoryV2 config falls back to the legacy items path. queryRecords itself
+// triggers ensureMigrated on the real store — no explicit migration here.
+async function queryV2Records(projectRoot) {
+  try {
+    const config = await loadRuntimeConfig(projectRoot);
+    if (config?.memoryV2?.enabled === false) {
+      return [];
+    }
+  } catch {
+    // unreadable config → default enabled, keep going
+  }
+  return loadV2Records(projectRoot, {});
+}
+
+function scoreRecord(record, queryTokens) {
+  const typeWeight = RECORD_TYPE_WEIGHTS[record.type] ?? 1;
+  if (queryTokens.length === 0) {
+    return typeWeight * Math.max(0.1, record.confidence ?? 1);
+  }
+
+  const recordTokens = new Set(tokenize(`${record.text ?? ''} ${record.provenance ?? ''}`));
+  let matched = 0;
+  for (const token of queryTokens) {
+    if (recordTokens.has(token)) {
+      matched += 1;
+    }
+  }
+  if (matched === 0) {
+    return 0;
+  }
+
+  const recencyBonus = record.created_at > 0
+    ? Math.min(1, record.created_at / Date.now())
+    : 0;
+  return typeWeight * matched * Math.max(0.1, record.confidence ?? 1) + recencyBonus;
+}
+
+// Legacy scope names ('user'|'project'|'session') map onto v2 scope/type:
+// 'project' ↔ scope 'repo'/'task', 'session' ↔ type 'episode'.
+const LEGACY_SCOPE_MATCH = {
+  user: (record) => record.scope === 'user',
+  project: (record) => record.scope === 'repo' || record.scope === 'task',
+  session: (record) => record.type === 'episode' || record.scope === 'session',
+};
+
+function recordWithinScope(record, scope, projectId) {
+  if (scope !== 'all') {
+    const matcher = LEGACY_SCOPE_MATCH[scope];
+    const matches = matcher ? matcher(record) : (record.scope === scope || record.type === scope);
+    if (!matches) return false;
+  }
+  if (projectId && record.project_id && record.project_id !== projectId) {
+    return false;
+  }
+  return true;
+}
+
+function buildRecordSearchResult(record, relevanceScore) {
+  return {
+    id: record.id,
+    summary: record.text,
+    relevanceScore,
+    source: record.type,
+    timestamp: record.created_at ?? 0,
+    sourcePath: null,
+  };
+}
+
+function searchRecords(records, query, scope, limit, projectId) {
+  const queryTokens = tokenize(query);
+  return records
+    .filter((record) => isRecordUsable(record))
+    .filter((record) => recordWithinScope(record, scope, projectId))
+    .map((record) => ({ record, score: scoreRecord(record, queryTokens) }))
+    .filter((entry) => entry.score > 0)
+    .sort((left, right) => (
+      right.score - left.score
+      || (right.record.created_at ?? 0) - (left.record.created_at ?? 0)
+      || String(right.record.text ?? '').localeCompare(String(left.record.text ?? ''))
+    ))
+    .slice(0, limit)
+    .map((entry) => buildRecordSearchResult(entry.record, entry.score));
+}
+
 export async function search(query, scope = 'all', limit = 10, { projectRoot, projectId } = {}) {
+  const records = await queryV2Records(projectRoot);
+  if (records.length > 0) {
+    return searchRecords(records, query, scope, limit, projectId);
+  }
+
   const items = await listMemoryItems(projectRoot);
   const queryTokens = tokenize(query);
 
@@ -207,6 +310,33 @@ function findRelatedItemIds(targetItem, allItems) {
 }
 
 export async function expand(id, { projectRoot } = {}) {
+  const records = await queryV2Records(projectRoot);
+  if (records.length > 0) {
+    // Resolve legacy item ids too: 'session:<legacyId>' → episode with
+    // meta.legacyId, 'project:<projectId>' → records of that project.
+    const colonIdx = String(id).indexOf(':');
+    const legacyKind = colonIdx > 0 ? String(id).slice(0, colonIdx) : null;
+    const legacyId = colonIdx > 0 ? String(id).slice(colonIdx + 1) : id;
+    const target = records.find((record) => record.id === id)
+      ?? (legacyKind === 'session'
+        ? records.find((record) => record.type === 'episode' && record.meta?.legacyId === legacyId)
+        : legacyKind === 'project'
+          ? records.find((record) => record.project_id === legacyId)
+          : null);
+    if (!target) {
+      return { id, fullContent: '', relatedItems: [] };
+    }
+    return {
+      id: target.id,
+      fullContent: JSON.stringify(target, null, 2),
+      relatedItems: records
+        .filter((record) => record.id !== target.id)
+        .filter((record) => record.type === target.type || record.project_id === target.project_id)
+        .map((record) => record.id)
+        .slice(0, 5),
+    };
+  }
+
   const items = await listMemoryItems(projectRoot);
   const target = items.find((item) => item.id === id);
   if (!target) {
@@ -259,6 +389,15 @@ function buildInjectionSnippet(item) {
   return `user-rules=${(content.rules ?? []).slice(0, 3).join('; ') || 'n/a'}`;
 }
 
+function includeUserMemoryOrRecord(includeUserMemory, record) {
+  return includeUserMemory || record.scope !== 'user';
+}
+
+function buildRecordSnippet(record) {
+  const text = String(record.text ?? '').trim();
+  return `${record.type}=${text.length > 160 ? `${text.slice(0, 157)}...` : text}`;
+}
+
 function normalizePressurePhase(phase) {
   const normalized = String(phase ?? '').trim().toLowerCase();
   return ['monitor', 'soft', 'hard'].includes(normalized) ? normalized : 'monitor';
@@ -380,7 +519,8 @@ export async function getContextInjection(
     inputCompression = true,
   } = {},
 ) {
-  const items = await listMemoryItems(projectRoot);
+  const records = await queryV2Records(projectRoot);
+  const items = records.length > 0 ? [] : await listMemoryItems(projectRoot);
   const pressureState = await readCompactPressureState(projectRoot);
   const recallPlan = resolveRecallPressurePlan({
     maxTokens,
@@ -388,14 +528,20 @@ export async function getContextInjection(
     pressureState,
   });
   const rankedItems = await search(currentTask, 'all', Math.max(limit * 3, 8), { projectRoot, projectId });
-  const selectedItems = selectContextItems({
-    items,
-    rankedItems,
-    projectId,
-    limit: recallPlan.limit,
-    includeUserMemory: recallPlan.includeUserMemory,
-    allowProjectFallback: !String(currentTask ?? '').trim(),
-  });
+  const selectedItems = records.length > 0
+    ? dedupeItemsById(rankedItems
+        .map((entry) => records.find((record) => record.id === entry.id))
+        .filter(Boolean)
+        .filter((record) => includeUserMemoryOrRecord(recallPlan.includeUserMemory, record)))
+        .slice(0, Math.max(1, recallPlan.limit))
+    : selectContextItems({
+        items,
+        rankedItems,
+        projectId,
+        limit: recallPlan.limit,
+        includeUserMemory: recallPlan.includeUserMemory,
+        allowProjectFallback: !String(currentTask ?? '').trim(),
+      });
 
   if (selectedItems.length === 0) {
     return '';
@@ -418,8 +564,12 @@ export async function getContextInjection(
     }
   }
 
-  const rawBodyLines = selectedItems.map((item) => `- [${item.type}] ${buildDetailedInjectionSnippet(item)}`);
-  const bodyLines = selectedItems.map((item) => `- ${buildInjectionSnippet(item)}`);
+  const rawBodyLines = records.length > 0
+    ? selectedItems.map((record) => `- [${record.type}] ${buildRecordSnippet(record)}`)
+    : selectedItems.map((item) => `- [${item.type}] ${buildDetailedInjectionSnippet(item)}`);
+  const bodyLines = records.length > 0
+    ? selectedItems.map((record) => `- ${buildRecordSnippet(record)}`)
+    : selectedItems.map((item) => `- ${buildInjectionSnippet(item)}`);
   const rawLines = ['## Previous Context', ...rawBodyLines];
   const rawText = rawLines.join('\n');
   const conciseText = ['## Previous Context', ...bodyLines].join('\n');

package/src/core/memory/store.js

@@ -6,6 +6,178 @@ import { readJsonIfExists, writeJson } from '../fileOps.js';
 import { loadRuntimeConfig } from '../runtimeConfig.js';
 import { runHygiene } from './hygiene.js';
 
+// ---- Memory v2 facade (SPEC §3/§11) ----
+// Every exported signature and CLI output shape is preserved. When the v2
+// store is active — `v2/records.json` exists, or lazy `ensureMigrated` inside
+// storeV2's read path just ran the v1→v2 migration — reads/writes delegate to
+// storeV2 records. Otherwise the legacy file-based path below runs unchanged.
+// storeV2/migrate are lazy-imported to keep this module decoupled and to match
+// the storeV2↔migrate cycle-avoidance pattern.
+
+async function storeV2() {
+  return import('./storeV2.js');
+}
+
+async function v2Active(projectRoot) {
+  try {
+    const config = await loadRuntimeConfig(projectRoot);
+    if (config?.memoryV2?.enabled === false) return false;
+  } catch {
+    // unreadable config → default enabled, keep going
+  }
+
+  const v2 = await storeV2();
+  // loadRecords triggers ensureMigrated (lazy migration) when autoMigrate is
+  // on; records.json existing afterwards — or already — means v2 mode.
+  await v2.loadRecords(projectRoot);
+  try {
+    await fs.access(buildRuntimePaths(projectRoot).memoryV2RecordsPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const LEGACY_CONVENTION_PROVENANCE = new Set([
+  'legacy:conventions',
+  'propose-approved',
+]);
+
+function parsePreferenceText(text) {
+  const raw = String(text ?? '');
+  const idx = raw.indexOf(' = ');
+  if (idx <= 0) return null;
+  const key = raw.slice(0, idx).trim();
+  const valueRaw = raw.slice(idx + 3);
+  let value = valueRaw;
+  try {
+    value = JSON.parse(valueRaw);
+  } catch {
+    // keep string form
+  }
+  return [key, value];
+}
+
+function recordDecisionParts(text) {
+  const raw = String(text ?? '');
+  const idx = raw.indexOf(' — ');
+  if (idx <= 0) return { what: raw };
+  return { what: raw.slice(0, idx), why: raw.slice(idx + 3) };
+}
+
+function summarizeSessionText(text) {
+  const raw = String(text ?? '');
+  const idx = raw.indexOf(' — ');
+  const task = idx > 0 ? raw.slice(0, idx) : raw;
+  const outcomeMatch = /outcome: ([^—]+)/.exec(raw);
+  const outcome = outcomeMatch ? outcomeMatch[1].trim() : 'unknown';
+  return `${task} — ${outcome}`;
+}
+
+function recordsToMemoryItems(records, runtimePaths) {
+  // list/export keep legacy semantics — all non-archived records stay visible
+  // (TTL-expired episodes included; recall applies isRecordUsable on top).
+  const usable = records.filter((record) => record.status !== 'archived');
+
+  // ---- user item (always emitted, like the legacy path) ----
+  const preferences = {};
+  const rules = [];
+  for (const record of usable.filter((r) => r.scope === 'user')) {
+    if (record.type === 'project_rule') {
+      rules.push(record.text);
+    } else {
+      const parsed = parsePreferenceText(record.text);
+      if (parsed) preferences[parsed[0]] = parsed[1];
+    }
+  }
+  const userMemory = { preferences, rules, updatedAt: Date.now() };
+
+  // ---- project items grouped by project_id ----
+  const projectIds = [...new Set(
+    usable
+      .filter((r) => typeof r.project_id === 'string' && r.project_id)
+      .map((r) => r.project_id),
+  )];
+  const projectItems = projectIds.map((projectId) => {
+    const scoped = usable.filter((r) => r.project_id === projectId && r.type !== 'episode');
+    const conventions = scoped
+      .filter((r) => r.type === 'project_rule'
+        && (LEGACY_CONVENTION_PROVENANCE.has(r.provenance)
+          || r.meta?.legacyStatus === 'approved'))
+      .map((r) => r.text);
+    const activeRules = scoped
+      .filter((r) => r.type === 'project_rule' && !conventions.includes(r.text))
+      .map((r) => r.text);
+    const decisions = scoped
+      .filter((r) => r.type === 'derived_fact' && r.provenance === 'legacy:decisions')
+      .map((r) => ({ id: r.meta?.id ?? r.id, ...recordDecisionParts(r.text), when: r.created_at }));
+    const profileFacts = scoped
+      .filter((r) => r.type === 'derived_fact' && r.provenance === 'legacy:project-profile')
+      .map((r) => r.text);
+    const content = {
+      id: projectId,
+      name: projectId,
+      architecture: profileFacts[0] ?? null,
+      techStack: profileFacts.slice(1),
+      conventions,
+      activeRules,
+      decisions,
+      patternCandidates: [],
+      sessions: [],
+      updatedAt: usable
+        .filter((r) => r.project_id === projectId)
+        .reduce((max, r) => Math.max(max, r.created_at ?? 0), 0),
+    };
+    return {
+      id: `project:${projectId}`,
+      type: 'project',
+      summary: summarizeProjectMemory(content),
+      searchableText: createSearchableText('project', content),
+      sourcePath: path.join(runtimePaths.projectsDir, `${sanitizeProjectId(projectId)}.json`),
+      content,
+    };
+  });
+
+  // ---- session items from episode records ----
+  const sessionItems = usable
+    .filter((r) => r.type === 'episode')
+    .map((record) => {
+      const legacyId = record.meta?.legacyId ?? record.id;
+      const content = {
+        id: legacyId,
+        projectId: record.project_id ?? null,
+        taskDescription: String(record.text ?? '').split(' — ')[0],
+        outcome: summarizeSessionText(record.text).split(' — ').pop(),
+        keyActions: [],
+        nextSteps: [],
+        filesChanged: [],
+        startedAt: record.created_at ?? null,
+        endedAt: record.created_at ?? null,
+      };
+      return {
+        id: `session:${legacyId}`,
+        type: 'session',
+        summary: summarizeSessionMemory(content),
+        searchableText: createSearchableText('session', content),
+        sourcePath: path.join(runtimePaths.sessionsDir, `${legacyId}.json`),
+        content,
+      };
+    });
+
+  return [
+    {
+      id: 'user:user',
+      type: 'user',
+      summary: summarizeUserMemory(userMemory),
+      searchableText: createSearchableText('user', userMemory),
+      sourcePath: runtimePaths.userMemoryPath,
+      content: userMemory,
+    },
+    ...projectItems,
+    ...sessionItems,
+  ];
+}
+
 function defaultUserMemory() {
   return {
     preferences: {},
@@ -100,6 +272,17 @@ function createSearchableText(type, content) {
 
 export async function exportMemory(projectRoot) {
   const runtimePaths = buildRuntimePaths(projectRoot);
+  if (await v2Active(projectRoot)) {
+    const v2 = await storeV2();
+    const items = recordsToMemoryItems(await v2.loadRecords(projectRoot), runtimePaths);
+    const user = items.find((item) => item.type === 'user')?.content ?? defaultUserMemory();
+    return {
+      user,
+      projects: items.filter((item) => item.type === 'project').map((item) => item.content),
+      sessions: items.filter((item) => item.type === 'session').map((item) => item.content),
+    };
+  }
+
   const user = (await readMemoryJson(runtimePaths.userMemoryPath)) ?? defaultUserMemory();
   const projects = (await readDirectoryJsonItems(runtimePaths.projectsDir)).map((item) => item.content);
   const sessions = (await readDirectoryJsonItems(runtimePaths.sessionsDir)).map((item) => item.content);
@@ -107,8 +290,34 @@ export async function exportMemory(projectRoot) {
   return { user, projects, sessions };
 }
 
+// Read-compat: corrupt legacy files still surface the same warning the legacy
+// read path emits, so `ukit memory list` output stays identical post-migration.
+async function warnOnCorruptLegacyFiles(runtimePaths) {
+  await readMemoryJson(runtimePaths.userMemoryPath);
+  for (const dirPath of [runtimePaths.projectsDir, runtimePaths.sessionsDir]) {
+    let entries = [];
+    try {
+      entries = await fs.readdir(dirPath, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (entry.isFile() && entry.name.endsWith('.json')) {
+        await readMemoryJson(path.join(dirPath, entry.name));
+      }
+    }
+  }
+}
+
 export async function listMemoryItems(projectRoot) {
   const runtimePaths = buildRuntimePaths(projectRoot);
+  if (await v2Active(projectRoot)) {
+    const v2 = await storeV2();
+    const records = await v2.loadRecords(projectRoot);
+    await warnOnCorruptLegacyFiles(runtimePaths);
+    return recordsToMemoryItems(records, runtimePaths);
+  }
+
   const userMemory = (await readMemoryJson(runtimePaths.userMemoryPath)) ?? defaultUserMemory();
   const projectMemories = await readDirectoryJsonItems(runtimePaths.projectsDir);
   const sessionMemories = await readDirectoryJsonItems(runtimePaths.sessionsDir);
@@ -141,8 +350,70 @@ export async function listMemoryItems(projectRoot) {
   ];
 }
 
+async function forgetMemoryItemV2(projectRoot, memoryId, runtimePaths) {
+  const v2 = await storeV2();
+  const archiveAll = async (records) => {
+    let archived = 0;
+    for (const record of records) {
+      if (record.status !== 'archived') {
+        await v2.updateRecord(projectRoot, record.id, { status: 'archived' });
+        archived += 1;
+      }
+    }
+    return archived;
+  };
+
+  if (memoryId === 'user:user' || memoryId === 'user') {
+    const userRecords = await v2.queryRecords(projectRoot, { scope: 'user' });
+    const archived = await archiveAll(userRecords);
+    await writeJson(runtimePaths.userMemoryPath, defaultUserMemory());
+    return { removed: archived > 0 || true, type: 'user', path: runtimePaths.userMemoryPath };
+  }
+
+  const id = String(memoryId);
+  const separatorIndex = id.indexOf(':');
+  if (separatorIndex <= 0 || separatorIndex === id.length - 1) {
+    return { removed: false, type: null, path: null };
+  }
+  const type = id.slice(0, separatorIndex);
+  const rawId = id.slice(separatorIndex + 1);
+  if (rawId.includes('/') || rawId.includes('\\') || rawId === '..') {
+    return { removed: false, type, path: null };
+  }
+
+  const records = await v2.loadRecords(projectRoot);
+  const matched = type === 'session'
+    ? records.filter((r) => r.type === 'episode' && (r.meta?.legacyId === rawId || r.id === rawId))
+    : type === 'project'
+      ? records.filter((r) => r.project_id === rawId)
+      : [];
+  const archived = await archiveAll(matched);
+
+  // Keep the legacy mirror in sync so a later read-compat consumer cannot
+  // resurrect a forgotten item.
+  const baseDir = type === 'project'
+    ? runtimePaths.projectsDir
+    : type === 'session'
+      ? runtimePaths.sessionsDir
+      : null;
+  let legacyRemoved = false;
+  if (baseDir) {
+    try {
+      await fs.unlink(path.join(baseDir, `${rawId}.json`));
+      legacyRemoved = true;
+    } catch {
+      legacyRemoved = false;
+    }
+  }
+
+  return { removed: archived > 0 || legacyRemoved, type: baseDir ? type : null, path: null };
+}
+
 export async function forgetMemoryItem(projectRoot, memoryId) {
   const runtimePaths = buildRuntimePaths(projectRoot);
+  if (await v2Active(projectRoot)) {
+    return forgetMemoryItemV2(projectRoot, memoryId, runtimePaths);
+  }
   if (memoryId === 'user:user' || memoryId === 'user') {
     await writeJson(runtimePaths.userMemoryPath, defaultUserMemory());
     return { removed: true, type: 'user', path: runtimePaths.userMemoryPath };
@@ -246,8 +517,106 @@ export async function runProjectHygiene(projectRoot, projectId) {
   return persistProjectMemoryWithHygiene(projectRoot, runtimePaths, projectId, filePath, memory);
 }
 
+function patternCandidateFromRecord(record) {
+  return {
+    id: record.meta?.id ?? record.id,
+    text: record.text,
+    category: record.meta?.category ?? null,
+    detectedFrom: record.meta?.detectedFrom ?? null,
+    detectedAt: record.meta?.detectedAt ?? record.created_at ?? null,
+    status: record.meta?.legacyStatus ?? 'pending',
+    _recordId: record.id,
+  };
+}
+
+async function proposePatternCandidateV2(projectRoot, projectId, candidate) {
+  const v2 = await storeV2();
+  const normalizedText = normalizePatternText(candidate?.text);
+  if (!normalizedText) {
+    throw new Error('proposePatternCandidate requires candidate.text');
+  }
+
+  const existing = (await v2.queryRecords(projectRoot, { projectId }))
+    .filter((record) => record.provenance === 'pattern-candidate'
+      || String(record.provenance ?? '').includes('pattern-candidate'))
+    .find((record) => record.meta?.legacyStatus === 'pending'
+      && normalizePatternText(record.text) === normalizedText);
+  if (existing) {
+    return patternCandidateFromRecord(existing);
+  }
+
+  const entry = {
+    id: `pc_${crypto.randomBytes(6).toString('hex')}`,
+    text: candidate.text,
+    category: candidate?.category ?? null,
+    detectedFrom: candidate?.detectedFrom ?? null,
+    detectedAt: Date.now(),
+    status: 'pending',
+  };
+
+  await v2.addRecord(projectRoot, {
+    type: 'derived_fact',
+    scope: 'task',
+    text: entry.text,
+    provenance: 'pattern-candidate',
+    confidence: 0.4,
+    createdBy: 'propose',
+    projectId,
+    meta: { ...entry, legacyStatus: 'pending' },
+  });
+  return entry;
+}
+
+async function listPendingPatternCandidatesV2(projectRoot, projectId) {
+  const v2 = await storeV2();
+  return (await v2.queryRecords(projectRoot, { projectId }))
+    .filter((record) => record.type === 'derived_fact'
+      && record.meta?.legacyStatus === 'pending'
+      && record.status !== 'archived')
+    .map(patternCandidateFromRecord);
+}
+
+async function resolvePatternCandidateV2(projectRoot, projectId, candidateId, decision) {
+  const v2 = await storeV2();
+  const records = await v2.queryRecords(projectRoot, { projectId });
+  const target = records.find((record) => record.meta?.id === candidateId || record.id === candidateId);
+  if (!target) {
+    throw new Error(`Pattern candidate not found: ${candidateId}`);
+  }
+
+  let updated;
+  if (decision === 'approve') {
+    updated = await v2.updateRecord(projectRoot, target.id, {
+      type: 'project_rule',
+      scope: 'repo',
+      confidence: 0.9,
+      provenance: `${target.provenance ?? 'pattern-candidate'};promoted-from:${target.id}`,
+      meta: { ...target.meta, legacyStatus: 'approved' },
+    });
+  } else {
+    updated = await v2.updateRecord(projectRoot, target.id, {
+      status: 'archived',
+      meta: { ...target.meta, legacyStatus: 'rejected' },
+    });
+  }
+  return patternCandidateFromRecord(updated ?? target);
+}
+
 export async function proposePatternCandidate(projectRoot, projectId, candidate) {
   const runtimePaths = buildRuntimePaths(projectRoot);
+  if (await v2Active(projectRoot)) {
+    const entry = await proposePatternCandidateV2(projectRoot, projectId, candidate);
+    // Mirror into the legacy project file (hygiene + conventions) so the
+    // untouched-on-disk legacy format stays read-compatible.
+    const { filePath, memory } = await readProjectMemoryForId(runtimePaths, projectId);
+    const patternCandidates = Array.isArray(memory.patternCandidates) ? memory.patternCandidates : [];
+    if (!patternCandidates.some((existing) => existing.id === entry.id)) {
+      memory.patternCandidates = [...patternCandidates, entry];
+      await persistProjectMemoryWithHygiene(projectRoot, runtimePaths, projectId, filePath, memory);
+    }
+    return entry;
+  }
+
   const { filePath, memory } = await readProjectMemoryForId(runtimePaths, projectId);
 
   const normalizedText = normalizePatternText(candidate?.text);
@@ -279,6 +648,10 @@ export async function proposePatternCandidate(projectRoot, projectId, candidate)
 
 export async function listPendingPatternCandidates(projectRoot, projectId) {
   const runtimePaths = buildRuntimePaths(projectRoot);
+  if (await v2Active(projectRoot)) {
+    return listPendingPatternCandidatesV2(projectRoot, projectId);
+  }
+
   const { memory } = await readProjectMemoryForId(runtimePaths, projectId);
   const patternCandidates = Array.isArray(memory.patternCandidates) ? memory.patternCandidates : [];
   return patternCandidates.filter((entry) => entry.status === 'pending');
@@ -290,6 +663,31 @@ export async function resolvePatternCandidate(projectRoot, projectId, candidateI
   }
 
   const runtimePaths = buildRuntimePaths(projectRoot);
+  if (await v2Active(projectRoot)) {
+    const resolved = await resolvePatternCandidateV2(projectRoot, projectId, candidateId, decision);
+    // Mirror the resolution into the legacy project file.
+    const { filePath, memory } = await readProjectMemoryForId(runtimePaths, projectId);
+    const patternCandidates = Array.isArray(memory.patternCandidates) ? memory.patternCandidates : [];
+    const target = patternCandidates.find((entry) => entry.id === candidateId);
+    if (target) {
+      target.status = resolved.status;
+      if (decision === 'approve') {
+        const conventions = Array.isArray(memory.conventions) ? memory.conventions : [];
+        if (!conventions.includes(target.text)) {
+          memory.conventions = [...conventions, target.text];
+        }
+      }
+      await persistProjectMemoryWithHygiene(projectRoot, runtimePaths, projectId, filePath, memory);
+    } else if (decision === 'approve') {
+      const conventions = Array.isArray(memory.conventions) ? memory.conventions : [];
+      if (!conventions.includes(resolved.text)) {
+        memory.conventions = [...conventions, resolved.text];
+        await persistProjectMemoryWithHygiene(projectRoot, runtimePaths, projectId, filePath, memory);
+      }
+    }
+    return resolved;
+  }
+
   const { filePath, memory } = await readProjectMemoryForId(runtimePaths, projectId);
 
   const patternCandidates = Array.isArray(memory.patternCandidates) ? memory.patternCandidates : [];