@ngockhoale/ukit 3.0.3 → 3.0.5

package/src/core/memory/learningCandidates.js

@@ -0,0 +1,302 @@
+// learningCandidates.js — M04.2 learning candidates (SPEC §5 FR-016, FR-018; C11).
+//
+// Normalizes repeated corrections/suppressions/escalations/verification-gaps
+// into observation records, then promotes them to LearningCandidate records
+// (C11) only after configured recurrence AND cross-session evidence.
+//
+// Contracts:
+//   * Gated by `learning.candidates.stage` — 'off' (default) means zero
+//     writes: observeLearningSignal is a no-op, maybeCreateCandidate returns
+//     null. At 'shadow'/'canary'/'default' everything is still REPORT-ONLY:
+//     candidates are created with meta.status 'proposed' and promotion stays
+//     manual via the existing pending-candidate flow in store.js.
+//   * Observations are memoryV2 records (provenance 'learning-observation');
+//     candidates are memoryV2 records (provenance 'learning-candidate').
+//     No second store.
+//   * Scope classification is conservative: any session-scoped signal pins
+//     the candidate to 'session' — session signals never leak to
+//     project/user.
+//   * Conflict detection prefers conditional refinement; project constraints
+//     outrank user preferences (C11).
+//   * NEVER THROWS on malformed signals — they are skipped, not fatal.
+
+import crypto from 'node:crypto';
+import { loadRuntimeConfig, resolveConfigStage } from '../runtimeConfig.js';
+import { addRecord, queryRecords } from './storeV2.js';
+
+export const OBSERVATION_PROVENANCE = 'learning-observation';
+export const CANDIDATE_PROVENANCE = 'learning-candidate';
+
+const SIGNAL_KINDS = new Set([
+  'correction',
+  'suppression',
+  'escalation',
+  'verification-gap',
+]);
+
+// C11 proposalType per signal kind.
+const PROPOSAL_TYPE_BY_KIND = {
+  correction: 'preference',
+  suppression: 'constraint',
+  escalation: 'knowledge',
+  'verification-gap': 'overlay',
+};
+
+// C11 candidate scopes → memoryV2 record scopes.
+const CANDIDATE_TO_RECORD_SCOPE = {
+  session: 'session',
+  project: 'repo',
+  user: 'user',
+};
+
+const DEFAULT_MIN_OCCURRENCES = 3;
+const DEFAULT_MIN_SESSIONS = 2;
+const MAX_EVIDENCE_REFS = 24;
+// Records live in the single records.json document — bound every field that
+// carries caller-controlled text so a signal can never grow it unboundedly.
+const MAX_SIGNAL_TEXT = 512;
+const MAX_META_FIELD = 512;
+
+function boundText(value, max = MAX_META_FIELD) {
+  if (value == null) return null;
+  const text = typeof value === 'string' ? value : JSON.stringify(value);
+  return typeof text === 'string' ? text.slice(0, max) : null;
+}
+
+// Like boundText but preserves non-string scalars (numbers/booleans) so a
+// proposedDelta value keeps its type for downstream overlay conversion.
+function boundField(value, max = MAX_META_FIELD) {
+  if (value == null) return null;
+  if (typeof value !== 'string') return value;
+  return value.slice(0, max);
+}
+
+// Bounds a proposedDelta in place-shape: {field, value} stay typed fields —
+// stringifying the whole object would break detectCandidateConflicts and
+// overlayFromCandidate, which read delta.field/delta.value.
+function boundDelta(delta) {
+  if (delta == null || typeof delta !== 'object') return boundText(delta);
+  return {
+    ...delta,
+    field: boundField(delta.field),
+    value: boundField(delta.value),
+  };
+}
+
+function normalizeText(text) {
+  return String(text ?? '').toLowerCase().replace(/\s+/g, ' ').trim();
+}
+
+function normalizeValue(value) {
+  if (value == null) return '';
+  return normalizeText(typeof value === 'string' ? value : JSON.stringify(value));
+}
+
+
+function signalScopeHint(signal) {
+  const hint = signal?.scopeHint ?? signal?.scope;
+  return hint === 'project' || hint === 'user' ? hint : 'session';
+}
+
+async function candidatesConfig(projectRoot) {
+  const config = await loadRuntimeConfig(projectRoot);
+  const stage = resolveConfigStage(config, 'learning.candidates.stage');
+  const raw = config?.learning?.candidates ?? {};
+  return {
+    stage,
+    minOccurrences: Number.isFinite(raw.minOccurrences) && raw.minOccurrences > 0
+      ? raw.minOccurrences
+      : DEFAULT_MIN_OCCURRENCES,
+    minSessions: Number.isFinite(raw.minSessions) && raw.minSessions > 0
+      ? raw.minSessions
+      : DEFAULT_MIN_SESSIONS,
+  };
+}
+
+/**
+ * classifyCandidateScope(signal) → 'session' | 'project' | 'user'
+ * Conservative: unknown/absent hints resolve to 'session'.
+ */
+export function classifyCandidateScope(signal) {
+  return signalScopeHint(signal);
+}
+
+/**
+ * detectCandidateConflicts(candidate, existing) → conflicts[]
+ * A conflict is a contradiction on the same target: the candidate proposes a
+ * different value for a field an existing project_rule/constraint already
+ * pins. Project (repo-scoped) constraints outrank user-scoped candidates —
+ * the conflict is flagged `outranked` and resolved by conditional refinement
+ * rather than silent override.
+ */
+export function detectCandidateConflicts(candidate, existing = []) {
+  const target = normalizeText(candidate?.target ?? candidate?.proposedDelta?.field);
+  if (!target) return [];
+  const proposedValue = normalizeValue(
+    candidate?.proposedDelta?.value ?? candidate?.proposedDelta,
+  );
+
+  const conflicts = [];
+  for (const record of existing ?? []) {
+    if (!record || record.status === 'archived') continue;
+    if (record.provenance === CANDIDATE_PROVENANCE
+        && record.meta?.status !== 'approved') continue;
+    const recordTarget = normalizeText(record.meta?.target ?? record.meta?.constraint);
+    if (!recordTarget || recordTarget !== target) continue;
+    const recordValue = normalizeValue(record.meta?.value);
+    if (!recordValue || recordValue === proposedValue) continue;
+    const isProjectConstraint = record.type === 'project_rule' || record.scope === 'repo';
+    conflicts.push({
+      type: 'contradiction',
+      recordId: record.id,
+      target,
+      existingValue: record.meta?.value ?? null,
+      proposedValue: candidate?.proposedDelta?.value ?? null,
+      outranked: isProjectConstraint && candidate?.scope === 'user',
+      resolution: 'conditional-refinement',
+    });
+  }
+  return conflicts;
+}
+
+/**
+ * observeLearningSignal(projectRoot, signal) → observation record | null
+ * signal: { kind, text, sessionId?, projectId?, scopeHint?, target?,
+ *           condition?, proposedDelta?, evidenceRef? }
+ * Returns null when the feature stage is 'off' or the signal is malformed.
+ */
+export async function observeLearningSignal(projectRoot, signal = {}) {
+  const { stage } = await candidatesConfig(projectRoot);
+  if (stage === 'off') return null;
+  if (!SIGNAL_KINDS.has(signal?.kind) || !normalizeText(signal?.text)) return null;
+
+  // Every caller-controlled string is bounded — records.json is a single
+  // document, so an unbounded signal would grow it without limit.
+  const text = boundText(signal.text, MAX_SIGNAL_TEXT);
+  const target = boundText(signal.target);
+  const signature = `${signal.kind}:${normalizeText(target ?? text)}`.slice(0, MAX_META_FIELD);
+
+  return addRecord(projectRoot, {
+    type: 'derived_fact',
+    scope: CANDIDATE_TO_RECORD_SCOPE[signalScopeHint(signal)],
+    text: `learning-signal ${signal.kind}: ${String(text).trim()}`,
+    provenance: OBSERVATION_PROVENANCE,
+    confidence: 0.3,
+    createdBy: 'learning-observe',
+    projectId: boundText(signal.projectId),
+    meta: {
+      kind: signal.kind,
+      signature,
+      sessionId: boundText(signal.sessionId),
+      scopeHint: signalScopeHint(signal),
+      target,
+      condition: boundText(signal.condition),
+      proposedDelta: boundDelta(signal.proposedDelta),
+      evidenceRef: boundText(signal.evidenceRef),
+      observedAt: Date.now(),
+    },
+  });
+}
+
+function candidateText(kind, signalText, occurrences, sessions) {
+  return `Learning candidate (${kind}): "${String(signalText).trim()}" — observed ${occurrences}× across ${sessions} sessions.`;
+}
+
+/**
+ * maybeCreateCandidate(projectRoot) → candidate record | null
+ * Scans observation records, groups by signature + projectId, and promotes
+ * the first eligible group (occurrences >= minOccurrences AND distinct
+ * sessions >= minSessions) into a proposed LearningCandidate. Idempotent —
+ * an existing proposed/approved candidate for the signature is returned
+ * instead of duplicated.
+ */
+export async function maybeCreateCandidate(projectRoot) {
+  const { stage, minOccurrences, minSessions } = await candidatesConfig(projectRoot);
+  if (stage === 'off') return null;
+
+  const records = await queryRecords(projectRoot, {});
+  const observations = records
+    .filter((r) => r.provenance === OBSERVATION_PROVENANCE && r.status !== 'archived')
+    .sort((a, b) => (a.meta?.observedAt ?? a.created_at ?? 0) - (b.meta?.observedAt ?? b.created_at ?? 0));
+  const existingCandidates = records.filter((r) => r.provenance === CANDIDATE_PROVENANCE);
+
+  const groups = new Map();
+  for (const obs of observations) {
+    const key = `${obs.project_id ?? ''}|${obs.meta?.signature ?? ''}`;
+    if (!groups.has(key)) groups.set(key, []);
+    groups.get(key).push(obs);
+  }
+
+  let firstExisting = null;
+  for (const group of groups.values()) {
+    const signature = group[0]?.meta?.signature;
+    const projectId = group[0]?.project_id ?? null;
+
+    const existing = existingCandidates.find(
+      (r) => r.meta?.signature === signature
+        && (r.project_id ?? null) === projectId
+        && (r.meta?.status === 'proposed' || r.meta?.status === 'approved'),
+    );
+    // Remember the first existing candidate but KEEP SCANNING — returning it
+    // here starved every later eligible group: group A's candidate blocked
+    // group B's from ever being created.
+    if (existing) {
+      firstExisting ??= existing;
+      continue;
+    }
+
+    const sessions = new Set(group.map((o) => o.meta?.sessionId ?? null));
+    if (group.length < minOccurrences || sessions.size < minSessions) continue;
+
+    const scope = group.reduce(
+      (narrowest, o) => {
+        const s = o.meta?.scopeHint ?? 'session';
+        return s === 'session' ? 'session' : narrowest === 'session' ? 'session' : s === 'project' ? 'project' : narrowest;
+      },
+      'user',
+    );
+
+    const first = group[0];
+    const evidenceRefs = group
+      .flatMap((o) => [o.meta?.evidenceRef, o.id])
+      .filter(Boolean)
+      .slice(0, MAX_EVIDENCE_REFS);
+
+    const draft = {
+      scope,
+      target: first.meta?.target ?? null,
+      proposedDelta: first.meta?.proposedDelta ?? { field: first.meta?.target ?? null, value: first.text },
+    };
+    const conflicts = detectCandidateConflicts(draft, records);
+
+    const candidateId = `lc_${crypto.randomBytes(6).toString('hex')}`;
+    return addRecord(projectRoot, {
+      type: 'derived_fact',
+      scope: CANDIDATE_TO_RECORD_SCOPE[scope],
+      text: candidateText(first.meta?.kind, first.text, group.length, sessions.size),
+      provenance: CANDIDATE_PROVENANCE,
+      confidence: Math.min(0.9, 0.4 + group.length * 0.1),
+      createdBy: 'learning-candidate',
+      projectId,
+      meta: {
+        id: candidateId,
+        candidateId,
+        schemaVersion: 1,
+        status: 'proposed',
+        signature,
+        kind: first.meta?.kind ?? null,
+        scope,
+        proposalType: PROPOSAL_TYPE_BY_KIND[first.meta?.kind] ?? 'knowledge',
+        condition: first.meta?.condition ?? `when ${first.meta?.kind ?? 'signal'} recurs`,
+        proposedDelta: draft.proposedDelta,
+        target: draft.target,
+        evidenceRefs,
+        occurrences: group.length,
+        sessions: sessions.size,
+        conflicts,
+      },
+    });
+  }
+
+  return firstExisting;
+}

package/src/core/memory/migrate.js

@@ -10,7 +10,7 @@ import { buildRuntimePaths } from '../runtimePaths.js';
 import { readJsonIfExists, writeJson } from '../fileOps.js';
 import { loadRuntimeConfig } from '../runtimeConfig.js';
 import { createRecord } from './records.js';
-import { saveRecords } from './storeV2.js';
+import { mutateRecordStore } from './recordStore.js';
 
 const MARKER_NAME = 'migrated-from-v1.json';
 const DAY_MS = 24 * 60 * 60 * 1000;
@@ -24,11 +24,14 @@ async function pathExists(targetPath) {
   }
 }
 
+// Returns { value, corrupt } — a parse failure is reported, never silently
+// dropped: corrupt legacy files count toward runMigration's `skipped` total
+// and keep needsMigration true so the loss is surfaced, not hidden.
 async function readJsonTolerant(filePath) {
   try {
-    return await readJsonIfExists(filePath);
+    return { value: await readJsonIfExists(filePath), corrupt: false };
   } catch {
-    return null;
+    return { value: null, corrupt: true };
   }
 }
 
@@ -64,9 +67,10 @@ function fingerprint(type, text) {
   return crypto.createHash('sha1').update(`v1:${type}:${normalized}`).digest('hex');
 }
 
-const skippedCounter = { count: 0 };
+// Per-run skip counter — threaded explicitly so concurrent runMigration calls
+// can never cross-report each other's skips (a module-level counter did).
 
-function makeRecord({ type, scope, text, confidence, provenance, projectId = null, validUntil = null, createdAt = null, meta = {}, status = null }) {
+function makeRecord({ type, scope, text, confidence, provenance, projectId = null, validUntil = null, createdAt = null, meta = {}, status = null }, skip) {
   try {
     const record = createRecord({
       type,
@@ -84,12 +88,12 @@ function makeRecord({ type, scope, text, confidence, provenance, projectId = nul
     if (status) record.status = status;
     return record;
   } catch {
-    skippedCounter.count += 1;
+    skip.count += 1;
     return null;
   }
 }
 
-function migrateUserMemory(user, records) {
+function migrateUserMemory(user, records, skip) {
   if (!user || typeof user !== 'object') return;
   for (const rule of Array.isArray(user.rules) ? user.rules : []) {
     if (typeof rule !== 'string' || !rule) continue;
@@ -97,7 +101,7 @@ function migrateUserMemory(user, records) {
       type: 'project_rule', scope: 'user', text: rule,
       confidence: 1.0, provenance: 'legacy:user-rules',
       createdAt: user.updatedAt,
-    });
+    }, skip);
     if (rec) records.push(rec);
   }
   const prefs = user.preferences && typeof user.preferences === 'object' ? user.preferences : {};
@@ -107,12 +111,12 @@ function migrateUserMemory(user, records) {
       type: 'derived_fact', scope: 'user', text,
       confidence: 1.0, provenance: 'legacy:user-preferences',
       createdAt: user.updatedAt,
-    });
+    }, skip);
     if (rec) records.push(rec);
   }
 }
 
-function migrateProjectMemory(project, projectId, records) {
+function migrateProjectMemory(project, projectId, records, skip) {
   if (!project || typeof project !== 'object') return;
   const createdAt = project.updatedAt;
 
@@ -122,7 +126,7 @@ function migrateProjectMemory(project, projectId, records) {
       type: 'project_rule', scope: 'repo', text,
       confidence: 0.9, provenance: 'legacy:conventions',
       projectId, createdAt,
-    });
+    }, skip);
     if (rec) records.push(rec);
   }
 
@@ -132,7 +136,7 @@ function migrateProjectMemory(project, projectId, records) {
       type: 'project_rule', scope: 'repo', text,
       confidence: 1.0, provenance: 'legacy:activeRules',
       projectId, createdAt,
-    });
+    }, skip);
     if (rec) records.push(rec);
   }
 
@@ -144,7 +148,7 @@ function migrateProjectMemory(project, projectId, records) {
       type: 'derived_fact', scope: 'repo', text,
       confidence: 0.9, provenance: 'legacy:decisions',
       projectId, createdAt: decision.when ?? createdAt,
-    });
+    }, skip);
     if (rec) records.push(rec);
   }
 
@@ -157,7 +161,7 @@ function migrateProjectMemory(project, projectId, records) {
       type: 'derived_fact', scope: 'repo', text,
       confidence: 0.8, provenance: 'legacy:project-profile',
       projectId, createdAt,
-    });
+    }, skip);
     if (rec) records.push(rec);
   }
 
@@ -172,11 +176,11 @@ function migrateProjectMemory(project, projectId, records) {
     };
     let rec = null;
     if (legacyStatus === 'approved') {
-      rec = makeRecord({ ...base, type: 'project_rule', scope: 'repo', confidence: 0.9 });
+      rec = makeRecord({ ...base, type: 'project_rule', scope: 'repo', confidence: 0.9 }, skip);
     } else if (legacyStatus === 'rejected') {
-      rec = makeRecord({ ...base, type: 'derived_fact', status: 'archived' });
+      rec = makeRecord({ ...base, type: 'derived_fact', status: 'archived' }, skip);
     } else {
-      rec = makeRecord({ ...base, type: 'derived_fact' });
+      rec = makeRecord({ ...base, type: 'derived_fact' }, skip);
     }
     if (rec) records.push(rec);
   }
@@ -190,7 +194,7 @@ function sessionText(session) {
   ].filter(Boolean).join(' — ');
 }
 
-function migrateSession(session, episodeTtlMs, records) {
+function migrateSession(session, episodeTtlMs, records, skip) {
   if (!session || typeof session !== 'object') return;
   const text = sessionText(session);
   if (!text) return;
@@ -202,19 +206,24 @@ function migrateSession(session, episodeTtlMs, records) {
     projectId: typeof session.projectId === 'string' ? session.projectId : null,
     createdAt, validUntil,
     meta: { legacyId: session.id ?? null },
-  });
+  }, skip);
   if (rec) records.push(rec);
 }
 
 async function collectLegacySources(paths) {
-  const sources = { user: null, projects: [], sessions: [] };
+  const sources = { user: null, projects: [], sessions: [], corruptFiles: 0 };
 
   const user = await readJsonTolerant(paths.userMemoryPath);
-  if (user) sources.user = user;
+  if (user.corrupt) sources.corruptFiles += 1;
+  if (user.value) sources.user = user.value;
 
   for (const name of await listJsonFiles(paths.projectsDir)) {
     const filePath = path.join(paths.projectsDir, name);
-    const content = await readJsonTolerant(filePath);
+    const { value: content, corrupt } = await readJsonTolerant(filePath);
+    if (corrupt) {
+      sources.corruptFiles += 1;
+      continue;
+    }
     if (!content) continue;
     if (name.endsWith('.archive.json')) {
       for (const s of Array.isArray(content.sessions) ? content.sessions : []) {
@@ -227,7 +236,11 @@ async function collectLegacySources(paths) {
 
   for (const name of await listJsonFiles(paths.sessionsDir)) {
     const filePath = path.join(paths.sessionsDir, name);
-    const content = await readJsonTolerant(filePath);
+    const { value: content, corrupt } = await readJsonTolerant(filePath);
+    if (corrupt) {
+      sources.corruptFiles += 1;
+      continue;
+    }
     if (!content) continue;
     if (name.endsWith('.archive.json') && Array.isArray(content.sessions)) {
       sources.sessions.push(...content.sessions);
@@ -240,10 +253,11 @@ async function collectLegacySources(paths) {
 }
 
 function hasLegacyContent(sources) {
-  return Boolean(sources.user) || sources.projects.length > 0 || sources.sessions.length > 0;
+  return Boolean(sources.user) || sources.projects.length > 0
+    || sources.sessions.length > 0 || sources.corruptFiles > 0;
 }
 
-async function buildRecords(projectRoot, paths, sources) {
+async function buildRecords(projectRoot, paths, sources, skip) {
   const config = await loadRuntimeConfig(projectRoot);
   const ttlDays = Number.isFinite(config?.memoryV2?.episodeTtlDays) && config.memoryV2.episodeTtlDays > 0
     ? config.memoryV2.episodeTtlDays
@@ -251,9 +265,9 @@ async function buildRecords(projectRoot, paths, sources) {
   const episodeTtlMs = ttlDays * DAY_MS;
 
   const records = [];
-  if (sources.user) migrateUserMemory(sources.user, records);
-  for (const { id, content } of sources.projects) migrateProjectMemory(content, id, records);
-  for (const session of sources.sessions) migrateSession(session, episodeTtlMs, records);
+  if (sources.user) migrateUserMemory(sources.user, records, skip);
+  for (const { id, content } of sources.projects) migrateProjectMemory(content, id, records, skip);
+  for (const session of sources.sessions) migrateSession(session, episodeTtlMs, records, skip);
   return records;
 }
 
@@ -285,9 +299,9 @@ export async function runMigration(projectRoot, { dryRun = false } = {}) {
   const sources = await collectLegacySources(paths);
   if (!hasLegacyContent(sources)) return empty;
 
-  skippedCounter.count = 0;
-  const records = await buildRecords(projectRoot, paths, sources);
-  const skipped = skippedCounter.count;
+  const skip = { count: 0 };
+  const records = await buildRecords(projectRoot, paths, sources, skip);
+  const skipped = skip.count + sources.corruptFiles;
   if (dryRun) {
     return { migrated: records.length, skipped, markerPath, backupDir: null };
   }
@@ -307,7 +321,20 @@ export async function runMigration(projectRoot, { dryRun = false } = {}) {
     }
   }
 
-  await saveRecords(projectRoot, records);
+  // Merge into the existing store under the shared lock — never clobber.
+  // records.json can already hold records when the marker is absent (a crash
+  // between saveRecords and the marker write, or a manual re-run); overwriting
+  // it would silently destroy post-migration data. source_fingerprint dedupes
+  // re-migrated records so the merge stays idempotent.
+  await mutateRecordStore(paths.memoryV2RecordsPath, (existing) => {
+    const fingerprints = new Set(
+      existing.map((r) => r.source_fingerprint).filter(Boolean),
+    );
+    const additions = records.filter(
+      (r) => !r.source_fingerprint || !fingerprints.has(r.source_fingerprint),
+    );
+    return { result: additions.length, records: [...existing, ...additions] };
+  });
 
   const counts = {
     total: records.length,

package/src/core/memory/recordStore.js

@@ -4,7 +4,7 @@
 // (storeV2.js) and the user store (userMemory.js) share one implementation.
 // Writes go through fileOps.writeJson (tmp+rename).
 
-import { readJsonIfExists, writeJson } from '../fileOps.js';
+import { readJsonIfExists, writeJson, withFileLock } from '../fileOps.js';
 import { normalizeRecord } from './records.js';
 
 const SCHEMA_VERSION = 2;
@@ -79,3 +79,26 @@ export function applyRecordPatch(records, id, patch = {}) {
   updated[index] = normalized;
   return { record: normalized, records: updated };
 }
+
+/**
+ * mutateRecordStore(recordsPath, mutate) → mutate's result | null
+ * Serializes a read-modify-write cycle on the records document under the
+ * shared file lock (fileOps.withFileLock) so concurrent add/update flows —
+ * in-process or across hook processes — never lose each other's writes.
+ * `mutate(records)` returns { result, records } to persist, or null to skip
+ * the write (e.g. id not found). Throws when the lock wait expires: a
+ * silently dropped mutation would corrupt caller state worse than an error.
+ */
+export async function mutateRecordStore(recordsPath, mutate) {
+  const outcome = await withFileLock(recordsPath, async () => {
+    const { records } = await readRecordStore(recordsPath);
+    const mutation = await mutate(records);
+    if (!mutation) return null;
+    await writeRecordStore(recordsPath, mutation.records);
+    return mutation.result ?? null;
+  });
+  if (outcome === undefined) {
+    throw new Error(`mutateRecordStore: lock wait expired for ${recordsPath} — mutation skipped`);
+  }
+  return outcome;
+}

package/src/core/memory/store.js

@@ -365,9 +365,11 @@ async function forgetMemoryItemV2(projectRoot, memoryId, runtimePaths) {
 
   if (memoryId === 'user:user' || memoryId === 'user') {
     const userRecords = await v2.queryRecords(projectRoot, { scope: 'user' });
-    const archived = await archiveAll(userRecords);
+    await archiveAll(userRecords);
     await writeJson(runtimePaths.userMemoryPath, defaultUserMemory());
-    return { removed: archived > 0 || true, type: 'user', path: runtimePaths.userMemoryPath };
+    // The reset above always removes user memory — `removed` reports that the
+    // forget happened, not how many v2 records were archived.
+    return { removed: true, type: 'user', path: runtimePaths.userMemoryPath };
   }
 
   const id = String(memoryId);
@@ -539,13 +541,28 @@ export async function runProjectHygiene(projectRoot, projectId) {
 }
 
 function patternCandidateFromRecord(record) {
+  const isLearningCandidate = record.provenance === 'learning-candidate';
   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',
+    // Learning candidates carry C11 status 'proposed'; the pending listing
+    // keeps the legacy 'pending' label so consumers see one shape.
+    status: record.meta?.legacyStatus
+      ?? (isLearningCandidate && record.meta?.status === 'proposed' ? 'pending' : record.meta?.status)
+      ?? 'pending',
+    ...(isLearningCandidate ? {
+      kind: 'learning-candidate',
+      candidateStatus: record.meta?.status ?? 'proposed',
+      scope: record.meta?.scope ?? null,
+      proposalType: record.meta?.proposalType ?? null,
+      condition: record.meta?.condition ?? null,
+      proposedDelta: record.meta?.proposedDelta ?? null,
+      evidenceRefs: record.meta?.evidenceRefs ?? [],
+      conflicts: record.meta?.conflicts ?? [],
+    } : {}),
     _recordId: record.id,
   };
 }
@@ -594,32 +611,51 @@ 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')
+      && record.status !== 'archived'
+      && (record.meta?.legacyStatus === 'pending'
+        // Learning candidates (TASK-008) surface through the same pending
+        // listing — no second store. C11 'proposed' maps to 'pending'.
+        || (record.provenance === 'learning-candidate' && record.meta?.status === 'proposed')))
     .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);
+  // Only candidate records are resolvable — matching every record by meta.id
+  // let a delta-overlay (meta.id 'ov_*') be "approved" into a project_rule or
+  // archived, corrupting the overlay store.
+  const target = records.find((record) => (
+    String(record.provenance ?? '').includes('pattern-candidate')
+      || record.provenance === 'learning-candidate'
+  ) && (record.meta?.id === candidateId || record.id === candidateId));
   if (!target) {
     throw new Error(`Pattern candidate not found: ${candidateId}`);
   }
 
   let updated;
+  const isLearningCandidate = target.provenance === 'learning-candidate';
   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' },
+      meta: {
+        ...target.meta,
+        legacyStatus: 'approved',
+        // Keep the C11 status field in sync for learning candidates.
+        ...(isLearningCandidate ? { status: 'approved' } : {}),
+      },
     });
   } else {
     updated = await v2.updateRecord(projectRoot, target.id, {
       status: 'archived',
-      meta: { ...target.meta, legacyStatus: 'rejected' },
+      meta: {
+        ...target.meta,
+        legacyStatus: 'rejected',
+        ...(isLearningCandidate ? { status: 'rejected' } : {}),
+      },
     });
   }
   return patternCandidateFromRecord(updated ?? target);