@ngockhoale/ukit 3.0.7 → 3.0.9

package/src/cli/commands/memory.js

@@ -8,25 +8,25 @@ import {
   runProjectHygiene,
 } from '../../core/memory/store.js';
 import {
-  addRecord,
   getRecord,
   loadRecords,
   queryRecords,
   stats as v2Stats,
-  updateRecord,
 } from '../../core/memory/storeV2.js';
 import {
-  addUserRecord,
   getUserRecord,
   queryUserRecords,
-  removeUserRecord,
-  updateUserRecord,
   userMemoryStats,
 } from '../../core/memory/userMemory.js';
 import { runMigration } from '../../core/memory/migrate.js';
-import { getContextInjection, search } from '../../core/memory/retrieval.js';
+import { createBackup, restoreBackup, diagnoseStore } from '../../core/memory/storeBackup.js';
+import { mutateMemory } from '../../core/memory/mutateMemory.js';
+import { redactWritePayload } from '../../core/memory/writeGuard.js';
+import { deletePromptCacheEntries } from '../../core/token/index.js';
+import { expand, getContextInjection, search } from '../../core/memory/retrieval.js';
 import { inspectRuntimeConfig } from '../../core/runtimeConfig.js';
 import { buildRuntimePaths } from '../../core/runtimePaths.js';
+import { buildUserPaths } from '../../core/userPaths.js';
 import { pathExists } from '../../core/fileOps.js';
 import { detectProjectContext } from '../../context/detectProjectContext.js';
 import { listLedgerFiles, LEDGER_DIR_REL } from '../../diagnostics/ledgerFiles.js';
@@ -94,6 +94,37 @@ async function listAllPendingPatternCandidates(projectRoot, runtimePaths) {
   }
   return results;
 }
+// FR-025: guard rejections surface labels only — never the matched value or
+// record body. Returns true when the result was a handled rejection.
+function printGuardRejection(res) {
+  const labels = Array.isArray(res.labels) && res.labels.length > 0
+    ? res.labels.join(', ')
+    : 'unknown';
+  console.log(`[UKit] rejected: ${res.reason ?? 'secret-detected'} (${labels})`);
+}
+
+// Shared mutateMemory error mapping for CLI write ops: conflict/not-found/
+// corrupt become thrown errors; rejected prints labels and returns quietly.
+function handleMutationResult(res, { notFoundMessage }) {
+  if (res.status === 'ok') return res;
+  if (res.status === 'not-found') throw new Error(notFoundMessage);
+  if (res.status === 'conflict') {
+    throw new Error(`Write conflict (${res.reason ?? 'revision-mismatch'}) — a concurrent writer won; re-run the command.`);
+  }
+  // M06 rollout flag (SPEC §9): writer stage 'off'/killSwitch surfaces as a
+  // typed disabled message, not a failure — the write lane is intentionally
+  // gated, exit-code class unchanged.
+  if (res.status === 'disabled' && res.reason === 'rollout-stage') {
+    console.log('[UKit] memory writer disabled by rollout stage');
+    return res;
+  }
+  if (res.status === 'rejected') {
+    printGuardRejection(res);
+    return res;
+  }
+  throw new Error(`Memory write failed: ${res.status}${res.reason ? ` — ${res.reason}` : ''}`);
+}
+
 
 // ---- `ukit memory v2` ops (SPEC §11) ----
 
@@ -151,13 +182,29 @@ async function runMemoryV2(projectRoot, args) {
       throw new Error(`Cannot promote ${record.type} records (only derived_fact or episode).`);
     }
     // Explicit approval only — no auto-promotion (SPEC §11,
-    // memoryV2.promotion.episodeToRuleRequiresApproval).
-    const updated = await updateRecord(projectRoot, id, {
-      type: 'project_rule',
-      scope: 'repo',
-      provenance: `${record.provenance ?? 'manual'};promoted-from:${record.id}`,
+    // memoryV2.promotion.episodeToRuleRequiresApproval). The write goes
+    // through mutateMemory with expectedRevision so a concurrent writer
+    // surfaces as a conflict instead of a silent clobber (FR-023).
+    const res = await mutateMemory(
+      { kind: 'project', projectRoot },
+      {
+        op: 'update',
+        payload: {
+          id,
+          patch: {
+            type: 'project_rule',
+            scope: 'repo',
+            provenance: `${record.provenance ?? 'manual'};promoted-from:${record.id}`,
+          },
+        },
+        expectedRevision: record.revision,
+      },
+    );
+    const handled = handleMutationResult(res, {
+      notFoundMessage: `Memory v2 record not found: ${id}`,
     });
-    console.log(`[UKit] Promoted ${updated.id} → project_rule.`);
+    if (handled.status !== 'ok') return;
+    console.log(`[UKit] Promoted ${handled.record.id} → project_rule.`);
     return;
   }
 
@@ -166,10 +213,22 @@ async function runMemoryV2(projectRoot, args) {
     if (!id) {
       throw new Error('Missing record id. Usage: ukit memory v2 stale <id>');
     }
-    const updated = await updateRecord(projectRoot, id, { status: 'stale' });
-    if (!updated) {
+    const record = await getRecord(projectRoot, id);
+    if (!record) {
       throw new Error(`Memory v2 record not found: ${id}`);
     }
+    const res = await mutateMemory(
+      { kind: 'project', projectRoot },
+      {
+        op: 'update',
+        payload: { id, patch: { status: 'stale' } },
+        expectedRevision: record.revision,
+      },
+    );
+    const handled = handleMutationResult(res, {
+      notFoundMessage: `Memory v2 record not found: ${id}`,
+    });
+    if (handled.status !== 'ok') return;
     console.log(`[UKit] Marked ${id} as stale.`);
     return;
   }
@@ -178,9 +237,19 @@ async function runMemoryV2(projectRoot, args) {
     const dryRun = rest.includes('--dry-run');
     const result = await runMigration(projectRoot, { dryRun });
     if (dryRun) {
-      console.log(`[UKit] Dry-run: would migrate ${result.migrated} record(s), skip ${result.skipped}.`);
+      // Per-record plan: counts per action + ids only — never record bodies.
+      const counts = {};
+      for (const entry of result.plan) {
+        counts[entry.action] = (counts[entry.action] ?? 0) + 1;
+      }
+      const countText = Object.entries(counts).map(([a, n]) => `${a}=${n}`).join(' ') || 'none';
+      console.log(`[UKit] migrate dry-run: ${countText} (migrated=${result.migrated} skipped=${result.skipped})`);
+      for (const entry of result.plan) {
+        console.log(`[UKit]   ${entry.action} ${entry.id} (${entry.source}) — ${entry.reason}`);
+      }
       return;
     }
+
     if (result.migrated === 0) {
       console.log('[UKit] Nothing to migrate (marker present or no legacy memory).');
       return;
@@ -191,17 +260,16 @@ async function runMemoryV2(projectRoot, args) {
     console.log(`[UKit] v2 store: ${stats.total} record(s) — ${JSON.stringify(stats.byType)}`);
     return;
   }
-
   throw new Error(`Unknown memory v2 op: ${op}. Expected list|show|promote|stale|migrate.`);
 }
 
 // ---- `ukit memory --user` — user-level store at ~/.ukit (FR-011) ----
 // Same v2 record document, no v1→v2 migration (the user layer starts at v2).
-// Ops: list|add|get|update|forget|stats; an optional `v2` token is accepted so
+// Ops: list|add|get|update|forget|purge|stats; an optional `v2` token is accepted so
 // `memory --user v2 add` and `memory --user add` are equivalent. Any other
 // subcommand under --user is a misuse error — v1 lanes stay project-level.
 
-const USER_MEMORY_OPS = new Set(['list', 'add', 'get', 'update', 'forget', 'stats']);
+const USER_MEMORY_OPS = new Set(['list', 'add', 'get', 'update', 'forget', 'purge', 'stats']);
 
 async function runUserMemory(homeDir, args) {
   const rest = (args[0] ?? '').toLowerCase() === 'v2' ? args.slice(1) : args;
@@ -210,7 +278,7 @@ async function runUserMemory(homeDir, args) {
 
   if (!USER_MEMORY_OPS.has(op)) {
     throw new Error(
-      `--user only supports v2 ops (list|add|get|update|forget|stats); got "${op}".`,
+      `--user only supports v2 ops (list|add|get|update|forget|purge|stats); got "${op}".`,
     );
   }
 
@@ -242,15 +310,32 @@ async function runUserMemory(homeDir, args) {
     if (!text) {
       throw new Error('Missing record text. Usage: ukit memory --user add [--type <type>] [--scope <scope>] <text>');
     }
-    const record = await addUserRecord({
-      type: typeFlag.value ?? 'derived_fact',
-      scope: scopeFlag.value ?? 'user',
-      text,
-      provenance: provenanceFlag.value ?? 'cli',
-      createdBy: 'cli',
-    }, { homeDir });
-    console.log(`[UKit] Added user record ${record.id}.`);
-    return;
+    const res = await mutateMemory(
+      { kind: 'user', homeDir },
+      {
+        op: 'add',
+        payload: {
+          type: typeFlag.value ?? 'derived_fact',
+          scope: scopeFlag.value ?? 'user',
+          text,
+          provenance: provenanceFlag.value ?? 'cli',
+          createdBy: 'cli',
+        },
+      },
+    );
+    if (res.status === 'ok') {
+      console.log(`[UKit] Added user record ${res.record.id}.`);
+      return;
+    }
+    if (res.status === 'duplicate') {
+      console.log(`[UKit] User record already exists${res.record ? ` (${res.record.id})` : ''}.`);
+      return;
+    }
+    if (res.status === 'rejected') {
+      printGuardRejection(res);
+      return;
+    }
+    throw new Error(`User memory add failed: ${res.status}${res.reason ? ` — ${res.reason}` : ''}`);
   }
 
   if (op === 'get') {
@@ -283,11 +368,15 @@ async function runUserMemory(homeDir, args) {
     if (Object.keys(patch).length === 0) {
       throw new Error('Nothing to update. Pass --status/--type/--scope or new text.');
     }
-    const updated = await updateUserRecord(id, patch, { homeDir });
-    if (!updated) {
-      throw new Error(`User memory record not found: ${id}`);
-    }
-    console.log(`[UKit] Updated user record ${updated.id}.`);
+    const res = await mutateMemory(
+      { kind: 'user', homeDir },
+      { op: 'update', payload: { id, patch } },
+    );
+    const handled = handleMutationResult(res, {
+      notFoundMessage: `User memory record not found: ${id}`,
+    });
+    if (handled.status !== 'ok') return;
+    console.log(`[UKit] Updated user record ${handled.record.id}.`);
     return;
   }
 
@@ -296,14 +385,40 @@ async function runUserMemory(homeDir, args) {
     if (!id) {
       throw new Error('Missing record id. Usage: ukit memory --user forget <id>');
     }
-    const removed = await removeUserRecord(id, { homeDir });
-    if (!removed) {
-      throw new Error(`User memory record not found: ${id}`);
-    }
+    // forget = archive semantics (SPEC G5) — the record stays in the store
+    // with status:'archived' so tombstone/review invariants hold.
+    const res = await mutateMemory(
+      { kind: 'user', homeDir },
+      { op: 'forget', payload: { id } },
+    );
+    const handled = handleMutationResult(res, {
+      notFoundMessage: `User memory record not found: ${id}`,
+    });
+    if (handled.status !== 'ok') return;
     console.log(`[UKit] Forgot user record ${id}.`);
     return;
   }
 
+  if (op === 'purge') {
+    const confirm = opArgs.includes('--confirm');
+    const id = opArgs.filter((a) => a !== '--confirm').join(' ').trim();
+    if (!id) {
+      throw new Error('Missing record id. Usage: ukit memory --user purge <id> --confirm');
+    }
+    if (!confirm) {
+      throw new Error(`Refusing to purge user record ${id} — re-run with --confirm.`);
+    }
+    const res = await mutateMemory(
+      { kind: 'user', homeDir },
+      { op: 'purge', payload: { id }, confirmScope: 'user' },
+    );
+    const handled = handleMutationResult(res, {
+      notFoundMessage: `User memory record not found: ${id}`,
+    });
+    if (handled.status !== 'ok') return;
+    console.log(`[UKit] Purged ${id} (tombstone recorded).`);
+    return;
+  }
   // op === 'stats'
   const stats = await userMemoryStats({ homeDir });
   console.log(`[UKit] User memory: total=${stats.total} byType=${JSON.stringify(stats.byType)} byStatus=${JSON.stringify(stats.byStatus)} invalidSkipped=${stats.invalidSkipped}`);
@@ -482,28 +597,116 @@ async function runMemoryEpisode(projectRoot, args) {
 
   const ttlDays = Number(config?.memoryV2?.episodeTtlDays) || 90;
   const projectId = (await detectProjectContext(projectRoot)).project.name;
-  const record = await addRecord(projectRoot, {
-    type: 'episode',
-    scope: 'session',
-    text,
-    provenance: 'exec-ledger',
-    confidence: 0.6,
-    createdBy: 'episode-hook',
-    projectId,
-    validUntil: Date.now() + ttlDays * 24 * 60 * 60 * 1000,
-    meta: { sessionId, ledgerKey },
-  });
-  console.log(`[UKit] episode: recorded ${record.id} for session ${sessionId}`);
+  // FR-023: the add goes through mutateMemory with the ledger key as the
+  // idempotency key — a hook-invoked rerun is a journal 'duplicate' even if
+  // the meta.ledgerKey fast-path above is bypassed.
+  const res = await mutateMemory(
+    { kind: 'project', projectRoot },
+    {
+      op: 'add',
+      idempotencyKey: ledgerKey,
+      payload: {
+        type: 'episode',
+        scope: 'session',
+        text,
+        provenance: 'exec-ledger',
+        confidence: 0.6,
+        createdBy: 'episode-hook',
+        projectId,
+        validUntil: Date.now() + ttlDays * 24 * 60 * 60 * 1000,
+        meta: { sessionId, ledgerKey },
+      },
+    },
+  );
+  if (res.status === 'duplicate') {
+    console.log('[UKit] episode: already recorded');
+    return;
+  }
+  if (res.status === 'rejected') {
+    printGuardRejection(res);
+    return;
+  }
+  if (res.status !== 'ok') {
+    throw new Error(`episode write failed: ${res.status}${res.reason ? ` — ${res.reason}` : ''}`);
+  }
+  console.log(`[UKit] episode: recorded ${res.record.id} for session ${sessionId}`);
+}
+
+// ---- `ukit memory backup|restore|doctor` — operator lane (SPEC §9, FR-011) ----
+// Output is counts/ids/paths only — never record bodies. `doctor` is strictly
+// read-only; `--dry-run` flags write nothing. `--user` targets the user store
+// at ~/.ukit instead of the project store (dispatch happens before the generic
+// --user lane so these subcommands keep their own flag semantics).
+
+async function runMemoryStoreOps(subcommand, { projectRoot, homeDir, isUser, rest }) {
+  if (subcommand === 'backup') {
+    const outFlag = extractFlag(rest, '--out');
+    const { backupDir, manifest } = await createBackup({
+      projectRoot: isUser ? null : projectRoot,
+      homeDir: isUser ? homeDir : undefined,
+      outDir: outFlag.value ?? undefined,
+      includeUser: isUser,
+    });
+    console.log(`[UKit] Backup written: ${backupDir}`);
+    for (const store of manifest.stores) {
+      console.log(
+        `[UKit]   ${store.kind}: state=${store.state} records=${store.recordCount} tombstones=${store.tombstoneCount} file=${store.file ?? 'none'}`,
+      );
+    }
+    return;
+  }
+
+  if (subcommand === 'restore') {
+    const dryRun = rest.includes('--dry-run');
+    const positional = rest.filter((a) => a !== '--dry-run');
+    const backupDir = positional.join(' ').trim();
+    if (!backupDir) {
+      throw new Error('Missing backup dir. Usage: ukit memory restore <backupDir> [--dry-run] [--user]');
+    }
+    const result = await restoreBackup(backupDir, {
+      projectRoot: isUser ? null : projectRoot,
+      homeDir,
+      dryRun,
+    });
+    for (const entry of result.plan) {
+      const detail = entry.reason ?? (entry.records != null ? `records=${entry.records}` : `added=${entry.added ?? 0}`);
+      console.log(`[UKit]   ${entry.kind}: ${entry.action} ${detail}`);
+    }
+    console.log(
+      dryRun
+        ? `[UKit] restore dry-run: ${result.plan.length} plan entr(ies), restored=0 skipped=${result.skipped} — nothing written.`
+        : `[UKit] Restored ${result.restored} record(s), skipped ${result.skipped}.`,
+    );
+    return;
+  }
+
+  if (subcommand === 'doctor') {
+    const { stores } = await diagnoseStore({
+      projectRoot: isUser ? null : projectRoot,
+      homeDir: isUser ? homeDir : undefined,
+    });
+    for (const store of stores) {
+      console.log(
+        `[UKit] ${store.kind}: state=${store.state} generation=${store.generation} records=${store.recordCount} tombstones=${store.tombstoneCount} quarantine=${store.quarantine.length}`,
+      );
+      if (store.state !== 'ok') {
+        const paths = isUser ? buildUserPaths({ homeDir }) : buildRuntimePaths(projectRoot);
+        const quarantineDir = path.join(path.dirname(paths.memoryV2RecordsPath), 'quarantine');
+        console.log(`[UKit]   quarantine-dir: ${quarantineDir}`);
+        for (const q of store.quarantine) {
+          console.log(`[UKit]   quarantined: ${q}`);
+        }
+        if (store.hint) console.log(`[UKit]   hint: ${store.hint}`);
+      }
+    }
+    return;
+  }
 }
 
 export async function runMemory({ projectRoot, homeDir = os.homedir(), argv = [] }) {
   const userFlagIndex = argv.indexOf('--user');
   const isUser = userFlagIndex >= 0;
   const runtimePaths = buildRuntimePaths(projectRoot);
-  // --user operates on ~/.ukit and does not require the project runtime.
-  if (!isUser && !(await pathExists(runtimePaths.runtimeRoot))) {
-    throw new Error('Shared UKit runtime not found. Run `ukit install` first.');
-  }
 
   const argvRest = isUser
     ? [...argv.slice(0, userFlagIndex), ...argv.slice(userFlagIndex + 1)]
@@ -516,6 +719,23 @@ export async function runMemory({ projectRoot, homeDir = os.homedir(), argv = []
     return;
   }
 
+  // Operator lane runs without the runtime gate: doctor must report
+  // state=missing on a project with no store yet, and backup/restore are
+  // exactly the tools used before/without a full install.
+  if (subcommand === 'backup' || subcommand === 'restore' || subcommand === 'doctor') {
+    await runMemoryStoreOps(subcommand, { projectRoot, homeDir, isUser, rest });
+    return;
+  }
+
+  // --user operates on ~/.ukit and does not require the project runtime.
+  if (!isUser && !(await pathExists(runtimePaths.runtimeRoot))) {
+    throw new Error('Shared UKit runtime not found. Run `ukit install` first.');
+  }
+
+
+
+
+
   if (isUser) {
     await runUserMemory(homeDir, argvRest);
     return;
@@ -659,15 +879,57 @@ export async function runMemory({ projectRoot, homeDir = os.homedir(), argv = []
       throw new Error('Missing query. Usage: ukit memory search <query>');
     }
 
-    const results = await search(query, 'all', 10, { projectRoot });
+    const projectContext = await detectProjectContext(projectRoot, { homeDir });
+    const results = await search(query, 'all', 10, {
+      projectRoot,
+      // Stable registry id (M01-05) — never the display name. Null/ambiguous
+      // is still passed through: policy denies repo-bound records rather than
+      // silently widening to cross-repo results.
+      projectId: projectContext.project.id ?? null,
+      projectAliases: projectContext.project.aliases ?? [],
+    });
     if (results.length === 0) {
       console.log('[UKit] No memory matches found.');
       return;
     }
 
     for (const result of results) {
-      console.log(`${result.id} — ${result.summary}`);
+      // FR-007: `<id> — <snippet> [<freshness≠fresh>] (<kind>:<locator>)` —
+      // tag only when the resolved state is not fresh; citation only when the
+      // hit carries one. Ids/locators/labels only — never meta or bodies.
+      const snippet = result.snippet ?? result.summary;
+      const tag = result.freshness && result.freshness.state !== 'fresh'
+        ? ` [${result.freshness.state}]`
+        : '';
+      const cite = result.citation
+        ? ` (${result.citation.kind}:${result.citation.locator})`
+        : '';
+      console.log(`${result.id} — ${snippet}${tag}${cite}`);
+    }
+    return;
+  }
+
+  if (subcommand === 'expand') {
+    const id = rest.join(' ').trim();
+    if (!id) {
+      throw new Error('Missing memory id. Usage: ukit memory expand <id>');
+    }
+
+    const projectContext = await detectProjectContext(projectRoot, { homeDir });
+    const result = await expand(id, {
+      projectRoot,
+      projectId: projectContext.project.id ?? null,
+      projectAliases: projectContext.project.aliases ?? [],
+    });
+    // FR-007: the hit block carries citation/freshness/reasons — provenance
+    // surface only, never record meta. Legacy lane has no hit; its
+    // fullContent is the pre-existing expansion surface.
+    if (result.hit) {
+      console.log(JSON.stringify(result.hit, null, 2));
+    } else {
+      console.log(result.fullContent);
     }
+    console.log(`relatedItems: ${(result.relatedItems ?? []).join(', ') || 'none'}`);
     return;
   }
 
@@ -687,8 +949,9 @@ export async function runMemory({ projectRoot, homeDir = os.homedir(), argv = []
       throw new Error('Memory recall is disabled in .ukit/storage/config.json.');
     }
 
-    const projectContext = await detectProjectContext(projectRoot);
-    const injection = await getContextInjection(query, projectContext.project.name, {
+    const projectContext = await detectProjectContext(projectRoot, { homeDir });
+    const injection = await getContextInjection(query, projectContext.project.id ?? null, {
+      projectAliases: projectContext.project.aliases ?? [],
       projectRoot,
       maxTokens: runtimeConfig.memory.maxInjectionTokens,
       promptCache: Boolean(runtimeConfig.tokenPipeline?.promptCache),
@@ -729,25 +992,53 @@ export async function runMemory({ projectRoot, homeDir = os.homedir(), argv = []
     return;
   }
 
+  if (subcommand === 'purge') {
+    const memoryId = rest.join(' ').trim();
+    if (!memoryId) {
+      throw new Error('Missing memory id. Usage: ukit memory purge <id>');
+    }
+    // FR-023/§9: purge removes the record, writes a tombstone, then sweeps
+    // prompt-cache entries that embedded the purged record's text.
+    const res = await mutateMemory(
+      { kind: 'project', projectRoot },
+      { op: 'purge', payload: { id: memoryId } },
+    );
+    const handled = handleMutationResult(res, {
+      notFoundMessage: `Memory record not found: ${memoryId}`,
+    });
+    if (handled.status !== 'ok') return;
+    await deletePromptCacheEntries(projectRoot, { selectedIds: [memoryId] });
+    console.log(`[UKit] Purged ${memoryId} (tombstone recorded).`);
+    return;
+  }
+
   if (subcommand === 'export') {
     const data = await exportMemory(projectRoot);
-    console.log(JSON.stringify(data, null, 2));
+    // FR-023/025: defense-in-depth redaction at the CLI boundary too —
+    // store.js exportMemory already redacts, this catches any future lane.
+    const { config } = await inspectRuntimeConfig(projectRoot);
+    const { payload: safe } = redactWritePayload({ meta: data }, { config });
+    console.log(JSON.stringify(safe.meta, null, 2));
     return;
   }
 
+
+
   throw new Error(`Unknown memory subcommand: ${subcommand}. Run "ukit memory help".`);
 }
 
 export function printMemoryHelp() {
   console.log('UKit Memory Commands');
-  console.log('Usage: ukit memory <list|search|recall|forget|export|propose|approve|reject|learn|promote|episode|hygiene> [args]');
+  console.log('Usage: ukit memory <list|search|expand|recall|forget|purge|export|propose|approve|reject|learn|promote|episode|hygiene|backup|restore|doctor> [args]');
   console.log('');
   console.log('Subcommands:');
   console.log('  list               List memory items in shared .ukit/storage/memory');
   console.log('  list --pending     List pending pattern candidates awaiting approval');
-  console.log('  search <query>     Search memory summaries and content');
+  console.log('  search <query>     Search memory summaries and content (prints freshness tag + citation)');
+  console.log('  expand <id>        Print the MemoryHit block (citation/freshness/reasons) + related ids');
   console.log('  recall <task>      Print a compact previous-context block for the current task');
-  console.log('  forget <id>        Remove one memory item by id');
+  console.log('  forget <id>        Archive one memory item by id');
+  console.log('  purge <id>         Remove a v2 record + tombstone it, and sweep prompt-cache entries');
   console.log('  export             Print all memory as JSON');
   console.log('  propose "<text>" [--category <name>] [--project <id>]  Propose a project convention for human approval');
   console.log('  approve <id> [--project <id>]  Approve a pending pattern candidate into project conventions');
@@ -756,6 +1047,9 @@ export function printMemoryHelp() {
   console.log('  promote [--dry-run]   Render approved rules/procedures into the ## ukit-learned block in docs/MEMORY.md');
   console.log('  episode [--dry-run] [--session <id>]  Write a session episode record from the exec-ledger');
   console.log('  hygiene [--project <id>]  Run decision-conflict resolution + session archiving now');
-  console.log('  v2 <list|show|promote|stale|migrate>  Operate on the project v2 record store');
-  console.log('  --user [v2] <list|add|get|update|forget|stats>  Operate on the user-level store at ~/.ukit/storage/memory/v2/records.json');
+  console.log('  backup [--out <dir>] [--user]  Snapshot v2 store(s) + sha256 manifest into a backup dir');
+  console.log('  restore <dir> [--dry-run] [--user]  Restore store(s) from a backup dir (plan only with --dry-run)');
+  console.log('  doctor [--user]        Diagnose v2 store state + counts + quarantine (read-only)');
+  console.log('  v2 <list|show|promote|stale|migrate>  Operate on the project v2 record store (migrate supports --dry-run plan output)');
+  console.log('  --user [v2] <list|add|get|update|forget|purge|stats>  Operate on the user-level store at ~/.ukit/storage/memory/v2/records.json (purge requires --confirm)');
 }

package/src/context/detectProjectContext.js

@@ -1,6 +1,7 @@
 import path from 'node:path';
 import { readJsonIfExists } from '../core/fileOps.js';
 import { detectPackageManager } from '../core/packageManager.js';
+import { resolveProjectIdentity } from '../core/memory/projectIdentity.js';
 
 function inferProjectName(projectRoot, packageJson) {
   if (typeof packageJson?.name === 'string' && packageJson.name.trim() !== '') {
@@ -10,16 +11,25 @@ function inferProjectName(projectRoot, packageJson) {
   return path.basename(projectRoot);
 }
 
-export async function detectProjectContext(projectRoot) {
+export async function detectProjectContext(projectRoot, { homeDir } = {}) {
   const packageJsonPath = path.join(projectRoot, 'package.json');
   // A corrupt package.json must degrade to basename naming, not crash the
   // status/memory CLIs with a raw SyntaxError.
   const packageJson = await readJsonIfExists(packageJsonPath).catch(() => null);
 
+  // Identity resolution must never break context detection: any resolver
+  // failure degrades to `id: null` (SPEC §10 — deny-by-default downstream).
+  const identity = await resolveProjectIdentity(projectRoot, { homeDir })
+    .catch(() => null);
+
   return {
     project: {
       root: projectRoot,
       name: inferProjectName(projectRoot, packageJson),
+      id: identity?.projectId ?? null,
+      // Registry-attested display names — lets the read path match migrated
+      // v1 records whose project_id is still the legacy name (M01-05).
+      aliases: Array.isArray(identity?.aliases) ? identity.aliases : [],
     },
     runtime: {
       packageManager: await detectPackageManager(projectRoot, packageJson),