forge-workflow 0.1.0-beta.4 → 0.1.0-beta.6

package/lib/commands/hooks.js

@@ -29,15 +29,16 @@ const {
 } = require('../hook-global-installer');
 const fs = require('node:fs');
 const path = require('node:path');
-const { sessionStartCapability, userPromptSubmitCapability, sessionEndCapability } = require('../hook-renderer');
-const { collectDigestData, buildMemoryDigest, defaultFetchIssues, defaultFetchNotes } = require('../memory-digest');
+const { sessionStartCapability, userPromptSubmitCapability, sessionEndCapability, readAttentionCapability } = require('../hook-renderer');
+const { buildMemoryDigest, buildReadAttentionDigest, defaultFetchIssues, defaultFetchNotes } = require('../memory-digest');
 const { collectInbox, buildInboxNudge } = require('../inbox');
 const { collectDigest } = require('../pr-monitor/digest');
 const { loadDispatchText } = require('../using-forge');
 const projectMemory = require('../project-memory');
-const { parseHookInput, selectInjection, DEFAULT_TOKEN_BUDGET, DEFAULT_SCORE_FLOOR } = require('../memory-recall');
-const { fenceUntrusted } = require('../untrusted-content');
+const { parseHookInput, selectInjection, meaningfulTokens, DEFAULT_TOKEN_BUDGET, DEFAULT_SCORE_FLOOR } = require('../memory-recall');
+const { launchMemoryRecallEvent } = require('../memory-recall-events');
 const { getResolvedRuntimeGraph } = require('../core/runtime-graph');
+const { fireAndForget } = require('../pr-monitor/reconcile-executor');
 
 // Default-ON rail; `forge gate disable rail.memory_recall` turns tier-2 off. Mirrors
 // autoShepherdRailEnabled (lib/commands/ship.js): absent id = enabled, fail-open to true.
@@ -47,6 +48,42 @@ const MEMORY_RECALL_RAIL = 'rail.memory_recall';
 const MEMORY_RECALL_CANDIDATES = 25;
 // Cross-turn dedupe memory: how many recently-injected keys to remember per session.
 const SEEN_KEYS_CAP = 40;
+const SESSION_START_DEADLINE_MS = 9_000;
+const PROMPT_RECALL_DEADLINE_MS = 4_500;
+const PROMPT_RECALL_SQLITE_BUSY_MS = 1_000;
+
+function withinDeadline(work, fallback, deadlineMs, onTimeout) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => {
+      if (onTimeout) onTimeout();
+      resolve(fallback);
+    }, deadlineMs);
+    Promise.resolve().then(work).then(
+      value => {
+        clearTimeout(timer);
+        resolve(value);
+      },
+      () => {
+        clearTimeout(timer);
+        resolve(fallback);
+      },
+    );
+  });
+}
+
+async function collectSessionStartData(projectRoot, opts, deadlineMs) {
+  const fetchNotes = opts.fetchNotes || defaultFetchNotes;
+  const fetchIssues = opts.fetchIssues || defaultFetchIssues;
+  const fetchInbox = opts.fetchInbox || collectInbox;
+  const bounded = work => withinDeadline(work, [], deadlineMs);
+  const [notes, ready, claimed, inbox] = await Promise.all([
+    bounded(() => fetchNotes(projectRoot, opts)),
+    bounded(() => fetchIssues(projectRoot, 'ready', opts)),
+    bounded(() => fetchIssues(projectRoot, 'in_progress', opts)),
+    bounded(() => fetchInbox(projectRoot, opts)),
+  ]);
+  return { notes, ready, claimed, inbox };
+}
 
 function memoryRecallRailEnabled(projectRoot, resolveGraph = getResolvedRuntimeGraph) {
   try {
@@ -96,12 +133,46 @@ function saveSeenKeys(projectRoot, sessionId, keys) {
   }
 }
 
+// Shadow-log the tier-2 recall decision (kernel issue f71784d3 step-0 instrument): one JSON
+// line per run records what was retrieved and what cleared the floor, so the corpus-dependent
+// scoreFloor can be tuned from real data instead of guessed. Capped so it never grows unbounded.
+const SHADOW_LOG_MAX_BYTES = 512 * 1024;
+// A shadow record is a tuning sample, not an archive. It contains only aggregate counts/scores.
+
+function shadowLogPath(projectRoot) {
+  return path.join(projectRoot, '.forge', 'memory-recall', 'shadow.jsonl');
+}
+
+// Append one JSON line, then evict whole records oldest-first until the file fits the byte cap.
+// Trimming by bytes (not line count) is what keeps this hook's synchronous read/write bounded: a
+// record that exceeds the cap alone leaves the file empty rather than permanently oversized.
+// Best-effort — any failure is swallowed by the caller so logging never affects the hook result.
+function appendShadowLog(projectRoot, record) {
+  const file = shadowLogPath(projectRoot);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.appendFileSync(file, `${JSON.stringify(record)}\n`, 'utf8');
+  let size;
+  try { size = fs.statSync(file).size; } catch { size = 0; }
+  if (size <= SHADOW_LOG_MAX_BYTES) return;
+  const lines = fs.readFileSync(file, 'utf8').split('\n').filter(Boolean);
+  const keep = [];
+  let bytes = 0;
+  for (let i = lines.length - 1; i >= 0; i -= 1) {
+    const cost = Buffer.byteLength(`${lines[i]}\n`, 'utf8');
+    if (bytes + cost > SHADOW_LOG_MAX_BYTES) break;
+    bytes += cost;
+    keep.unshift(lines[i]);
+  }
+  fs.writeFileSync(file, keep.length ? `${keep.join('\n')}\n` : '', 'utf8');
+}
+
 function usage() {
   return 'Usage: forge hooks install --global [--harness codex|hermes|all] [--dry-run]\n'
     + '       forge hooks session-start --harness <claude> (machine-facing; emits SessionStart context)\n'
     + '       forge hooks inbox-pickup --harness <claude> (machine-facing; emits UserPromptSubmit context)\n'
     + '       forge hooks shepherd-events --harness <claude> (machine-facing; emits UserPromptSubmit PR-monitor deltas)\n'
     + '       forge hooks memory-recall --harness <claude> (machine-facing; emits UserPromptSubmit query-relevant memory)\n'
+    + '       forge hooks read-attention --harness <claude> (machine-facing; emits path-matched PreToolUse:Read context)\n'
     + '       forge hooks capture --harness <claude> --trigger <precompact|stop> (machine-facing; captures a session summary on exit)';
 }
 
@@ -142,12 +213,23 @@ const CAPTURE_TAGS = ['type:session-summary', CAPTURE_AUTO_TAG];
  * @returns {string}
  */
 function buildCaptureNote(trigger, issues) {
-  const capped = issues.slice(0, CAPTURE_ISSUE_CAP);
-  const lines = capped.map(issue => {
+  const stableIssues = [...new Map(issues.map(issue => {
+    const id = String((issue && issue.id) || '');
     const title = String((issue && (issue.title || issue.id)) || 'untitled').replace(/\s+/g, ' ').trim();
+    return [`${id}\0${title}`, { id, title }];
+  })).values()].sort((left, right) => {
+    const leftKey = `${left.id}\0${left.title}`;
+    const rightKey = `${right.id}\0${right.title}`;
+    if (leftKey < rightKey) return -1;
+    if (leftKey > rightKey) return 1;
+    return 0;
+  });
+  const capped = stableIssues.slice(0, CAPTURE_ISSUE_CAP);
+  const lines = capped.map(issue => {
+    const title = issue.title;
     return `- ${title.length > CAPTURE_TITLE_CAP ? `${title.slice(0, CAPTURE_TITLE_CAP)}…` : title}`;
   });
-  const more = issues.length > capped.length ? `\n- …and ${issues.length - capped.length} more` : '';
+  const more = stableIssues.length > capped.length ? `\n- …and ${stableIssues.length - capped.length} more` : '';
   const body = lines.length
     ? `Session boundary (${trigger}) — in-progress:\n${lines.join('\n')}${more}`
     : `Session boundary (${trigger}) — no in-progress issues.`;
@@ -176,16 +258,19 @@ function formatSessionStart(harness, text) {
  *
  * @param {string[]} rest - args after the `session-start` action.
  * @param {string} projectRoot
- * @param {object} [opts] - injectable digest fetchers ({ fetchNotes, fetchIssues }).
+ * @param {object} [opts] - injectable digest fetchers ({ fetchNotes, fetchIssues }) and an
+ *   optional host `harness` capability ({ hasBgShell: true, runBgShell(argv, { cwd }) }).
  * @returns {Promise<{ success: boolean, output: string }>}
  */
 async function handleSessionStart(rest, projectRoot, opts = {}) {
   const harness = parseHarness(rest);
-  if (!sessionStartCapability(harness).rendered) return { success: true, output: '' };
-
-  // NOTE: the autonomous-shepherd session-start trigger is deferred to W-S4c along with the
-  // per-command dispatch trigger — both need a firing-policy + containment design (a naive
-  // trigger spawns a session-outliving daemon that breaks test isolation).
+  const capability = sessionStartCapability(harness);
+  if (!capability.rendered) return { success: true, output: '', reason: capability.reason };
+  try {
+    const triggerContext = { projectRoot };
+    if (opts.harness !== undefined) triggerContext.harness = opts.harness;
+    (opts.fireAndForget || fireAndForget)(triggerContext);
+  } catch { /* the automatic trigger must never break session start */ }
 
   // The using-forge dispatch bootstrap is injected FIRST so Forge skills auto-trigger from turn
   // one (the Superpowers mechanism): a reasoning-driven system, not just harness description
@@ -201,7 +286,11 @@ async function handleSessionStart(rest, projectRoot, opts = {}) {
 
   let digestText = '';
   try {
-    const data = await collectDigestData(projectRoot, opts);
+    const data = await collectSessionStartData(
+      projectRoot,
+      opts,
+      opts.sessionStartDeadlineMs || SESSION_START_DEADLINE_MS,
+    );
     const digest = buildMemoryDigest(data, opts);
     if (!digest.empty) digestText = digest.text;
   } catch { /* fail-open: a kernel outage must not suppress the dispatch bootstrap */ }
@@ -222,6 +311,41 @@ function formatUserPromptSubmit(harness, text) {
   return '';
 }
 
+function formatPreToolUse(harness, text) {
+  if (harness !== 'claude') return '';
+  return JSON.stringify({
+    hookSpecificOutput: { hookEventName: 'PreToolUse', additionalContext: text },
+  });
+}
+
+function fetchReadAttentionNotes(projectRoot) {
+  return projectMemory.recent(projectRoot, 100).map(entry => ({
+    note: typeof entry.value === 'string' ? entry.value : JSON.stringify(entry.value),
+    tags: Array.isArray(entry.tags) ? entry.tags : [],
+    sourceAgent: entry.sourceAgent,
+    timestamp: entry.timestamp,
+  }));
+}
+
+async function handleReadAttention(rest, projectRoot, opts = {}) {
+  try {
+    const harness = parseHarness(rest);
+    const capability = readAttentionCapability(harness);
+    if (!capability.rendered) return { success: true, output: '', reason: capability.reason };
+    const readInput = opts.readInput || readHookStdin;
+    const payload = JSON.parse(readInput() || '{}');
+    const targetPath = payload?.tool_input?.file_path || payload?.tool_input?.path;
+    if (!targetPath) return { success: true, output: '' };
+    const fetchNotes = opts.fetchNotes || fetchReadAttentionNotes;
+    const notes = await fetchNotes(projectRoot, { ...opts, noteLimit: 100 });
+    const digest = buildReadAttentionDigest(targetPath, notes, opts);
+    if (digest.empty) return { success: true, output: '' };
+    return { success: true, output: formatPreToolUse(harness, digest.text) };
+  } catch {
+    return { success: true, output: '' };
+  }
+}
+
 /**
  * `forge hooks inbox-pickup --harness <h>` — the COMPLIANT comment-back CONTEXT hook. On each
  * prompt it emits harness-native UserPromptSubmit JSON carrying a COMPACT count+pointer nudge
@@ -243,7 +367,8 @@ function formatUserPromptSubmit(harness, text) {
 async function handleInboxPickup(rest, projectRoot, opts = {}) {
   try {
     const harness = parseHarness(rest);
-    if (!userPromptSubmitCapability(harness).rendered) return { success: true, output: '' };
+    const capability = userPromptSubmitCapability(harness);
+    if (!capability.rendered) return { success: true, output: '', reason: capability.reason };
     const pending = await collectInbox(projectRoot, opts);
     const nudge = buildInboxNudge(pending);
     if (nudge.empty) return { success: true, output: '' };
@@ -314,43 +439,161 @@ function handleShepherdEvents(rest, projectRoot, opts = {}) {
  *   loadSeen, saveSeen, scoreFloor, tokenBudget }.
  * @returns {{ success: boolean, output: string }}
  */
-function handleMemoryRecall(rest, projectRoot, opts = {}) {
+async function runMemoryRecall(rest, projectRoot, opts = {}) {
+  const observation = opts.observation || {};
   try {
     const harness = parseHarness(rest);
-    if (!userPromptSubmitCapability(harness).rendered) return { success: true, output: '' };
+    observation.harness = harness;
+    const capability = userPromptSubmitCapability(harness);
+    if (!capability.rendered) {
+      observation.outcome = 'unsupported';
+      return { success: true, output: '', reason: capability.reason };
+    }
 
     const railEnabled = opts.railEnabled || memoryRecallRailEnabled;
-    if (!railEnabled(projectRoot)) return { success: true, output: '' };
+    if (!railEnabled(projectRoot)) {
+      observation.outcome = 'filtered';
+      return { success: true, output: '' };
+    }
 
     const readInput = opts.readInput || readHookStdin;
     const { prompt, sessionId } = parseHookInput(readInput());
-    if (!prompt) return { success: true, output: '' };
+    if (!prompt) {
+      observation.outcome = 'filtered';
+      return { success: true, output: '' };
+    }
 
     const search = opts.search
-      || ((root, query, limit) => projectMemory.searchRankedScored(root, query, limit));
+      || ((root, query, limit, options) => projectMemory.searchRankedScored(root, query, limit, options));
     const loadSeen = opts.loadSeen || loadSeenKeys;
     const saveSeen = opts.saveSeen || saveSeenKeys;
-
-    const hits = search(projectRoot, prompt, MEMORY_RECALL_CANDIDATES) || [];
-    const excludeKeys = loadSeen(projectRoot, sessionId) || [];
-    const { lines, injectedKeys } = selectInjection({
+    const appendShadow = opts.appendShadow || appendShadowLog;
+
+    // Stopword-aware, unicode-safe tokenization lives HERE (single source); the driver's
+    // buildMemoryFtsMatchOr only quotes+ORs whatever tokens it receives. Passing the raw prompt
+    // to a token-AND match was the 0-recall bug (kernel issue f71784d3).
+    const tokens = meaningfulTokens(prompt);
+    const excludeKeys = await loadSeen(projectRoot, sessionId) || [];
+    const hits = await search(
+      projectRoot,
+      tokens.join(' '),
+      MEMORY_RECALL_CANDIDATES,
+      {
+        excludeKeys: excludeKeys.slice(0, 256),
+        busyTimeoutMs: Math.max(0, Math.min(
+          opts.promptRecallSqliteBusyMs ?? PROMPT_RECALL_SQLITE_BUSY_MS,
+          (opts.promptRecallDeadlineMs || PROMPT_RECALL_DEADLINE_MS) - 100,
+        )),
+      },
+    ) || [];
+    observation.candidateCount = hits.length;
+    observation.eligibleCount = hits.length;
+    if (opts.deadline?.expired) {
+      observation.outcome = 'timeout';
+      return { success: true, output: '', reason: 'timeout' };
+    }
+    const scoreFloor = typeof opts.scoreFloor === 'number' ? opts.scoreFloor : DEFAULT_SCORE_FLOOR;
+    const { lines, entries, injectedKeys } = selectInjection({
       query: prompt,
       hits,
-      scoreFloor: typeof opts.scoreFloor === 'number' ? opts.scoreFloor : DEFAULT_SCORE_FLOOR,
+      scoreFloor,
       tokenBudget: opts.tokenBudget || DEFAULT_TOKEN_BUDGET,
       excludeKeys,
     });
-    if (!lines.length) return { success: true, output: '' };
 
-    saveSeen(projectRoot, sessionId, injectedKeys);
-    const fenced = lines.map(line => fenceUntrusted(line, { source: 'memory' })).join('\n');
+    // Step-0 instrument: record every real query (even ones that inject nothing) so the floor is
+    // tuned from data. Own try/catch — a logging failure must NEVER fall through to the fail-open
+    // outer catch (which would suppress a legitimate injection).
+    if (tokens.length) {
+      try {
+        appendShadow(projectRoot, {
+          candidateCount: hits.length,
+          injectedCount: injectedKeys.length,
+          candidateScoreMin: hits.length ? Math.min(...hits.map(hit => Number(hit?.score) || 0)) : null,
+          candidateScoreMax: hits.length ? Math.max(...hits.map(hit => Number(hit?.score) || 0)) : null,
+          scoreFloor,
+        });
+      } catch { /* best-effort: shadow logging never affects the hook result */ }
+    }
+
+    if (!lines.length) {
+      observation.outcome = hits.length ? 'filtered' : 'empty';
+      return { success: true, output: '' };
+    }
+
+    if (opts.deadline?.expired) return { success: true, output: '', reason: 'timeout' };
+    try {
+      const pending = saveSeen(projectRoot, sessionId, injectedKeys);
+      if (pending && typeof pending.catch === 'function') pending.catch(() => {});
+    } catch { /* dedupe persistence never suppresses an injection */ }
+    const sections = [
+      ['confirmed', 'Confirmed memory (project-local; provenance shown)'],
+      ['suggested', 'Suggested memory — verify before relying'],
+    ].map(([trust, heading]) => {
+      const selectedLines = entries.filter(entry => entry.trust === trust).map(entry => entry.line);
+      return selectedLines.length ? `${heading}\n${selectedLines.join('\n')}` : '';
+    }).filter(Boolean);
+    const fenced = sections.join('\n');
+    const selected = hits.filter(hit => injectedKeys.includes(hit.memory_id || hit.key));
+    observation.outcome = 'selected';
+    observation.selectedIds = injectedKeys;
+    observation.sourceMix = selected.reduce((mix, hit) => {
+      const sourceAgent = hit.provenance?.source_agent || hit.sourceAgent || 'unknown';
+      mix[sourceAgent] = (mix[sourceAgent] || 0) + 1;
+      return mix;
+    }, {});
+    observation.trustMix = selected.reduce((mix, hit) => {
+      const trust = hit.trust_status || 'unknown';
+      mix[trust] = (mix[trust] || 0) + 1;
+      return mix;
+    }, {});
+    observation.tokenEstimate = Math.ceil(fenced.length / 4);
     return { success: true, output: formatUserPromptSubmit(harness, fenced) };
   } catch {
     // Fail-open: a context hook must never break a prompt.
+    observation.outcome = 'error';
     return { success: true, output: '' };
   }
 }
 
+async function handleMemoryRecall(rest, projectRoot, opts = {}) {
+  const harness = parseHarness(rest);
+  const startedAt = Date.now();
+  const observation = { harness };
+  const record = result => {
+    const outcome = result.reason === 'timeout'
+      ? 'timeout'
+      : (observation.outcome || (result.output ? 'selected' : 'empty'));
+    const eventObservation = {
+      ...observation,
+      outcome,
+      harness,
+      elapsedMs: Date.now() - startedAt,
+    };
+    try {
+      const pending = (opts.recordRecallEvent || opts.launchRecallEvent || launchMemoryRecallEvent)(
+        projectRoot,
+        eventObservation,
+      );
+      if (pending && typeof pending.catch === 'function') pending.catch(() => {});
+    } catch { /* Operational evidence is best-effort and must never delay or suppress a prompt. */ }
+    return result;
+  };
+  const capability = userPromptSubmitCapability(harness);
+  if (!capability.rendered) {
+    observation.outcome = 'unsupported';
+    return record({ success: true, output: '', reason: capability.reason });
+  }
+  const deadline = { expired: false };
+  const result = await withinDeadline(
+    () => runMemoryRecall(rest, projectRoot, { ...opts, deadline, observation }),
+    { success: true, output: '', reason: 'timeout' },
+    opts.promptRecallDeadlineMs || PROMPT_RECALL_DEADLINE_MS,
+    () => { deadline.expired = true; },
+  );
+  return record(result);
+}
+
 /**
  * `forge hooks capture --harness <h> --trigger <precompact|stop>` — the CAPTURE-on-exit hook.
  * PreCompact (before context compaction) and Stop (turn end) fire it; it snapshots a bounded
@@ -374,7 +617,8 @@ function handleMemoryRecall(rest, projectRoot, opts = {}) {
 async function handleCapture(rest, projectRoot, opts = {}) {
   try {
     const harness = parseHarness(rest);
-    if (!sessionEndCapability(harness).rendered) return { success: true, output: '' };
+    const capability = sessionEndCapability(harness);
+    if (!capability.rendered) return { success: true, output: '', reason: capability.reason };
     const trigger = parseTrigger(rest);
 
     const fetchIssues = opts.fetchIssues || defaultFetchIssues;
@@ -503,11 +747,12 @@ async function handler(args, flags = {}, projectRoot, opts = {}) {
   if (action === 'inbox-pickup') return handleInboxPickup(args.slice(1), projectRoot, opts);
   if (action === 'shepherd-events') return handleShepherdEvents(args.slice(1), projectRoot, opts);
   if (action === 'memory-recall') return handleMemoryRecall(args.slice(1), projectRoot, opts);
+  if (action === 'read-attention') return handleReadAttention(args.slice(1), projectRoot, opts);
   if (action === 'capture') return handleCapture(args.slice(1), projectRoot, opts);
   if (action === 'install') return handleInstall(args, flags, opts);
   return {
     success: false,
-    error: `forge hooks supports: install, session-start, inbox-pickup, shepherd-events, capture.\n${usage()}`,
+    error: `forge hooks supports: install, session-start, inbox-pickup, shepherd-events, memory-recall, read-attention, capture.\n${usage()}`,
   };
 }
 
@@ -521,4 +766,5 @@ module.exports = {
     '--dry-run': 'Preview the merge without writing anything',
   },
   handler,
+  _internal: { appendShadowLog, SHADOW_LOG_MAX_BYTES },
 };

package/lib/commands/insights.js

@@ -36,7 +36,7 @@ function positionals(args) {
   return values;
 }
 
-async function handler(args, flags, projectRoot) {
+async function handler(args, flags, projectRoot, opts = {}) {
   const commandFlags = flags ?? {};
   const [subcommand, candidateId] = positionals(args);
   if (subcommand === 'accept' || subcommand === 'reject') {
@@ -54,14 +54,19 @@ async function handler(args, flags, projectRoot) {
     };
   }
 
-  const result = analyzeInsights(projectRoot, {
+  const result = await analyzeInsights(projectRoot, {
     limit: readOption(args, '--limit', undefined),
     minCount: readOption(args, '--min-count', undefined),
     since: readOption(args, '--since', undefined),
+    // Injectable kernel-read seams (Slice C2); undefined falls back to the real
+    // cli-broker-factory-backed reads inside analyzeInsights.
+    runIssueOperation: opts.runIssueOperation,
+    listRecentEvents: opts.listRecentEvents,
+    env: opts.env,
   });
   if (args.includes('--review-feedback')) {
     result.limitations = [
-      'Compatibility note: --review-feedback now reads Beads interactions and issue evidence; external review-provider comments are not inferred.',
+      'Compatibility note: --review-feedback now reads kernel events and issue evidence; external review-provider comments are not inferred.',
       ...result.limitations,
     ];
   }

package/lib/commands/memory.js

@@ -4,6 +4,62 @@ const remember = require('./remember');
 const recall = require('./recall');
 const insights = require('./insights');
 const { stripGlobalFlags } = require('../global-flags');
+const projectMemory = require('../project-memory');
+const { MEMORY_REVIEW_ENTRY_LIMIT, reviewMemories, stalenessForMemory } = require('../memory/hygiene');
+
+function renderReview(review) {
+  const lines = [`Memory hygiene: ${review.findings.length} finding(s), ${review.scanned}/${review.total} scanned.`];
+  for (const finding of review.findings) {
+    const detail = finding.claim ? finding.claim : `${finding.count} equivalent records`;
+    lines.push(`${finding.review_id}  ${finding.kind}  ${detail}`);
+  }
+  if (!review.usage.available) lines.push('Usage staleness: unavailable; no demotion applied.');
+  else if (review.usage.demoted > 0) lines.push(`Usage staleness: ${review.usage.demoted} memory record(s) demoted after 90 days.`);
+  if (review.truncated) lines.push('Results truncated by the bounded review limits.');
+  return lines.join('\n');
+}
+
+async function reviewHandler(args, flags, projectRoot, opts = {}) {
+  const recentMemories = opts.recentMemories || projectMemory.recent;
+  const countMemories = opts.countMemories || projectMemory.count;
+  const loadUsageStatus = opts.usageProjections
+    ? async (root, keys, options) => {
+      try {
+        const projections = await opts.usageProjections(root, keys, options);
+        return projections instanceof Map
+          ? { available: true, projections }
+          : { available: false, projections: new Map() };
+      } catch {
+        return { available: false, projections: new Map() };
+      }
+    }
+    : projectMemory.usageProjectionStatus;
+  const store = opts.store || projectMemory.resolveStore(projectRoot, opts);
+  const sharedOptions = { ...opts, store };
+  const entries = await recentMemories(projectRoot, MEMORY_REVIEW_ENTRY_LIMIT, sharedOptions);
+  const total = await countMemories(projectRoot, sharedOptions);
+  const usageStatus = await loadUsageStatus(projectRoot, entries.map(entry => entry.key), sharedOptions);
+  const usageAvailable = usageStatus?.available === true && usageStatus.projections instanceof Map;
+  const projections = usageAvailable ? usageStatus.projections : new Map();
+  const now = typeof opts.now === 'string' ? opts.now : new Date().toISOString();
+  const usageFindings = usageAvailable ? entries.map(entry => {
+    if (typeof entry?.key !== 'string' || typeof entry.timestamp !== 'string') return null;
+    try {
+      const status = stalenessForMemory({ created_at: entry.timestamp }, projections.get(entry.key) || null, { now });
+      return status.demote ? { memory_id: projectMemory.memoryUsageIdentity(entry.key), ...status } : null;
+    } catch {
+      return null;
+    }
+  }).filter(Boolean).map(({ age_days: _ageDays, ...finding }) => finding) : [];
+  const review = {
+    ...reviewMemories(entries, { total }),
+    usage: { available: usageAvailable, demoted: usageFindings.length, findings: usageFindings },
+  };
+  return {
+    success: true,
+    output: args.includes('--json') || flags.json ? JSON.stringify(review, null, 2) : renderReview(review),
+  };
+}
 
 // One memorable surface over the EXISTING memory commands (kernel issue 25362344): every
 // subcommand delegates to the standalone remember/recall/insights handlers — the same
@@ -29,9 +85,17 @@ const SUBCOMMANDS = {
     handler: insights.handler,
     summary: 'Detect recurring evidence patterns and suggest follow-ups (= forge insights)',
   },
+  review: {
+    handler: reviewHandler,
+    summary: 'Report bounded duplicate and explicit-contradiction findings with stable review ids',
+  },
+  doctor: {
+    handler: reviewHandler,
+    summary: 'Alias for memory review',
+  },
 };
 
-const usage = 'Usage: forge memory <add|recall|search|insights> [args]';
+const usage = 'Usage: forge memory <add|recall|search|insights|review|doctor> [args]';
 
 function renderHelp() {
   const width = Math.max(...Object.keys(SUBCOMMANDS).map(name => name.length));
@@ -75,7 +139,7 @@ async function handler(args, flags, projectRoot, opts) {
 module.exports = {
   name: 'memory',
   description:
-    'Unified memory surface: forge memory add|recall|search|insights (wraps remember/recall/insights)',
+    'Unified memory surface: add, recall, search, insights, and bounded hygiene review',
   usage,
   handler,
 };