@yemi33/minions 0.1.2423 → 0.1.2425

package/engine/meeting.js

@@ -7,6 +7,7 @@ const fs = require('fs');
 const path = require('path');
 const shared = require('./shared');
 const { safeJson, uid, log, ts, ENGINE_DEFAULTS, WORK_TYPE, DISPATCH_RESULT, MEETING_STATUS } = shared;
+const apiValidation = require('./api-validation');
 const queries = require('./queries');
 const { getDispatch, getConfig } = queries;
 const { renderPlaybook } = require('./playbook');
@@ -21,14 +22,31 @@ const EMPTY_OUTPUT_PATTERNS = ['(no output)', '(no findings)', '(no response)'];
 // tests can redirect the meetings directory without patching module internals.
 const MEETINGS_DIR = path.join(shared.MINIONS_DIR, 'meetings');
 const MEETING_NOTE_ARTIFACT_ROOT = path.join(shared.MINIONS_DIR, 'notes', 'inbox');
-const TERMINAL_MEETING_STATUSES = new Set(['completed', 'archived']);
+const MEETING_LIMITS = Object.freeze({
+  maxTitleLength: 200,
+  maxAgendaLength: 20000,
+  maxNoteLength: 4000,
+  maxParticipants: 50,
+  maxIdentifierLength: 128,
+});
+const TERMINAL_MEETING_STATUSES = new Set([
+  MEETING_STATUS.COMPLETED,
+  MEETING_STATUS.ARCHIVED,
+]);
 const ROUND_STATUS_BY_NAME = {
-  investigate: 'investigating',
-  debate: 'debating',
-  conclude: 'concluding',
+  investigate: MEETING_STATUS.INVESTIGATING,
+  debate: MEETING_STATUS.DEBATING,
+  conclude: MEETING_STATUS.CONCLUDING,
 };
 const ROUND_NUMBER_BY_NAME = { investigate: 1, debate: 2, conclude: 3 };
 const ACTIVE_MEETING_STATUSES = new Set(Object.values(ROUND_STATUS_BY_NAME));
+const MEETING_ACTION_STATUSES = Object.freeze({
+  note: ACTIVE_MEETING_STATUSES,
+  advance: ACTIVE_MEETING_STATUSES,
+  end: ACTIVE_MEETING_STATUSES,
+  archive: new Set([MEETING_STATUS.COMPLETED]),
+  unarchive: new Set([MEETING_STATUS.ARCHIVED]),
+});
 
 function isTerminalMeetingStatus(status) {
   return TERMINAL_MEETING_STATUSES.has(String(status || '').toLowerCase());
@@ -50,6 +68,141 @@ function expectedMeetingStatusForRound(roundName) {
   return ROUND_STATUS_BY_NAME[String(roundName || '').toLowerCase()] || null;
 }
 
+function validateMeetingId(value) {
+  return apiValidation.validateIdentifier(value, {
+    field: 'id',
+    path: 'id',
+    trim: true,
+    maxLength: MEETING_LIMITS.maxIdentifierLength,
+    pattern: /^MTG-[A-Za-z0-9_-]+$/,
+  });
+}
+
+function validateMeetingCreateInput(input, config, options = {}) {
+  apiValidation.validatePlainObject(input, { field: 'body', path: 'body' });
+  const title = apiValidation.validateString(input.title, {
+    field: 'title',
+    path: 'title',
+    trim: true,
+    minLength: 1,
+    maxLength: MEETING_LIMITS.maxTitleLength,
+  });
+  const agenda = apiValidation.validateString(input.agenda, {
+    field: 'agenda',
+    path: 'agenda',
+    trim: true,
+    minLength: 1,
+    maxLength: MEETING_LIMITS.maxAgendaLength,
+  });
+  const minimumParticipants = Number.isInteger(options.minParticipants)
+    ? options.minParticipants
+    : 0;
+  const sourceParticipants = input.participants === undefined ? [] : input.participants;
+  apiValidation.validateArray(sourceParticipants, {
+    field: 'participants',
+    path: 'participants',
+    minLength: minimumParticipants,
+    maxLength: MEETING_LIMITS.maxParticipants,
+  });
+
+  const participants = [];
+  const seen = new Set();
+  const configuredAgents = config && typeof config === 'object'
+    ? Object.keys(config.agents || {})
+    : null;
+  sourceParticipants.forEach((participant, index) => {
+    const pathParts = ['participants', index];
+    const id = apiValidation.validateIdentifier(participant, {
+      field: 'participants',
+      path: pathParts,
+      trim: true,
+      maxLength: MEETING_LIMITS.maxIdentifierLength,
+    });
+    if (seen.has(id)) {
+      throw new apiValidation.ApiInputError(`participants[${index}] duplicates participant "${id}"`, {
+        code: 'duplicate-participant',
+        field: 'participants',
+        path: pathParts,
+        rejectedValue: participant,
+      });
+    }
+    if (configuredAgents) {
+      if (!configuredAgents.includes(id)) {
+        throw new apiValidation.ApiInputError(
+          `participants[${index}] must name a configured agent`,
+          {
+            code: 'invalid-enum',
+            field: 'participants',
+            path: pathParts,
+            rejectedValue: participant,
+            allowedValues: configuredAgents,
+          },
+        );
+      }
+    }
+    seen.add(id);
+    participants.push(id);
+  });
+  return { title, agenda, participants };
+}
+
+function validateMeetingNote(note) {
+  return apiValidation.validateString(note, {
+    field: 'note',
+    path: 'note',
+    trim: true,
+    minLength: 1,
+    maxLength: MEETING_LIMITS.maxNoteLength,
+  });
+}
+
+function assertMeetingLifecycle(meeting, action) {
+  const allowedStatuses = MEETING_ACTION_STATUSES[action];
+  if (!allowedStatuses) throw new TypeError(`Unknown meeting lifecycle action: ${action}`);
+  if (!allowedStatuses.has(meeting.status)) {
+    throw new apiValidation.ApiInputError(
+      `Meeting ${meeting.id} cannot ${action} while status is ${meeting.status || '(missing)'}`,
+      {
+        code: 'meeting-state-conflict',
+        statusCode: 409,
+        field: 'status',
+        path: 'status',
+        rejectedValue: meeting.status,
+        allowedValues: [...allowedStatuses],
+      },
+    );
+  }
+  return meeting;
+}
+
+function setMeetingRound(meeting, roundName) {
+  const status = expectedMeetingStatusForRound(roundName);
+  const round = ROUND_NUMBER_BY_NAME[String(roundName || '').toLowerCase()];
+  if (!status || !round) throw new TypeError(`Unknown meeting round: ${roundName}`);
+  meeting.status = status;
+  meeting.round = round;
+  meeting.roundStartedAt = ts();
+  return meeting;
+}
+
+function completeMeeting(meeting) {
+  meeting.status = MEETING_STATUS.COMPLETED;
+  meeting.completedAt = ts();
+  return meeting;
+}
+
+function advanceMeetingState(meeting) {
+  if (meeting.status === MEETING_STATUS.INVESTIGATING) return setMeetingRound(meeting, 'debate');
+  if (meeting.status === MEETING_STATUS.DEBATING) return setMeetingRound(meeting, 'conclude');
+  if (meeting.status === MEETING_STATUS.CONCLUDING) {
+    completeMeeting(meeting);
+    meeting.roundStartedAt = ts();
+    return meeting;
+  }
+  assertMeetingLifecycle(meeting, 'advance');
+  return meeting;
+}
+
 function roundKeyFor(roundName, round) {
   const numeric = Number(round);
   if (Number.isFinite(numeric) && numeric > 0) return String(numeric);
@@ -106,17 +259,13 @@ function buildFailedMeetingConclusion(meeting, agents, reason) {
 function advanceMeetingIfRoundComplete(meeting, roundName, meetingId, config = null, pendingInboxWrites = null) {
   if (roundName === 'investigate') {
     if (!allParticipantsFinishedRound(meeting, roundName, meeting.round)) return false;
-    meeting.status = 'debating';
-    meeting.round = 2;
-    meeting.roundStartedAt = ts();
+    setMeetingRound(meeting, 'debate');
     log('info', `Meeting ${meetingId}: all findings finished — advancing to debate`);
     return true;
   }
   if (roundName === 'debate') {
     if (!allParticipantsFinishedRound(meeting, roundName, meeting.round)) return false;
-    meeting.status = 'concluding';
-    meeting.round = 3;
-    meeting.roundStartedAt = ts();
+    setMeetingRound(meeting, 'conclude');
     log('info', `Meeting ${meetingId}: all debate responses finished — advancing to conclusion`);
     return true;
   }
@@ -125,8 +274,7 @@ function advanceMeetingIfRoundComplete(meeting, roundName, meetingId, config = n
     const autoConclusion = buildFailedMeetingConclusion(meeting, agents);
     meeting.conclusion = { content: autoConclusion, agent: 'system', submittedAt: ts() };
     meeting.transcript.push({ round: meeting.round, agent: 'system', type: 'conclusion', content: autoConclusion, at: ts() });
-    meeting.status = 'completed';
-    meeting.completedAt = ts();
+    completeMeeting(meeting);
     // Defer inbox write until AFTER the mutateMeeting lock releases —
     // writeMeetingTranscriptToInbox hits the filesystem (slug dedup, write)
     // and must not block other writers. Matches the happy-path pattern at
@@ -489,13 +637,16 @@ function saveMeeting(meeting) {
   return mutateMeeting(meeting.id, () => meeting);
 }
 
-function createMeeting({ title, agenda, participants }) {
+function createMeeting(input, config, options) {
+  const validated = validateMeetingCreateInput(input, config, options);
   const id = 'MTG-' + uid();
   const meeting = {
-    id, title, agenda,
-    status: 'investigating',
+    id,
+    title: validated.title,
+    agenda: validated.agenda,
+    status: MEETING_STATUS.INVESTIGATING,
     round: 1,
-    participants: participants || [],
+    participants: validated.participants,
     createdBy: 'human',
     createdAt: ts(),
     roundStartedAt: ts(),
@@ -739,8 +890,7 @@ function collectMeetingFindings(meetingId, agentId, roundName, output, structure
     } else if (roundName === 'conclude') {
       meeting.conclusion = { content, agent: agentId, submittedAt: ts() };
       meeting.transcript.push({ round: meeting.round, agent: agentId, type: 'conclusion', content, at: ts() });
-      meeting.status = 'completed';
-      meeting.completedAt = ts();
+      completeMeeting(meeting);
       // Defer inbox write until AFTER the lock releases — writeToInbox hits
       // the filesystem (slug dedup, write) and must not block other writers.
       concludedMeeting = meeting;
@@ -767,10 +917,15 @@ function collectMeetingFindings(meetingId, agentId, roundName, output, structure
 }
 
 function addMeetingNote(meetingId, note) {
+  const normalizedNote = validateMeetingNote(note);
+  const existing = getMeeting(meetingId);
+  if (!existing) return null;
+  assertMeetingLifecycle(existing, 'note');
   return mutateMeeting(meetingId, (meeting) => {
     if (!meeting) return null;
-    meeting.humanNotes.push(note);
-    meeting.transcript.push({ round: meeting.round, agent: 'human', type: 'note', content: note, at: ts() });
+    assertMeetingLifecycle(meeting, 'note');
+    meeting.humanNotes.push(normalizedNote);
+    meeting.transcript.push({ round: meeting.round, agent: 'human', type: 'note', content: normalizedNote, at: ts() });
     return meeting;
   });
 }
@@ -844,7 +999,8 @@ function advanceMeetingRound(meetingId) {
   // already terminal. The authoritative status check still runs INSIDE the
   // lock below.
   const existing = getMeeting(meetingId);
-  if (!existing || existing.status === MEETING_STATUS.COMPLETED || existing.status === MEETING_STATUS.ARCHIVED) return null;
+  if (!existing) return null;
+  assertMeetingLifecycle(existing, 'advance');
 
   // CRITICAL: kill BEFORE acquiring the meeting lock. _killMeetingDispatches
   // mutates dispatch state and shells out to kill processes — never
@@ -853,13 +1009,9 @@ function advanceMeetingRound(meetingId) {
   _killMeetingDispatches(meetingId);
 
   return mutateMeeting(meetingId, (meeting) => {
-    if (!meeting || meeting.status === MEETING_STATUS.COMPLETED || meeting.status === MEETING_STATUS.ARCHIVED) return null;
-    if (meeting.status === 'investigating') { meeting.status = 'debating'; meeting.round = 2; }
-    else if (meeting.status === 'debating') { meeting.status = 'concluding'; meeting.round = 3; }
-    else if (meeting.status === 'concluding') { meeting.status = 'completed'; meeting.completedAt = ts(); }
-    else return meeting; // unknown active status — no state change, but report current
-    meeting.roundStartedAt = ts();
-    return meeting;
+    if (!meeting) return null;
+    assertMeetingLifecycle(meeting, 'advance');
+    return advanceMeetingState(meeting);
   });
 }
 
@@ -868,19 +1020,23 @@ function endMeeting(meetingId) {
   // teardown / process kills never run inside our lock callback.
   const existing = getMeeting(meetingId);
   if (!existing) return null;
+  assertMeetingLifecycle(existing, 'end');
   _killMeetingDispatches(meetingId);
 
   return mutateMeeting(meetingId, (meeting) => {
     if (!meeting) return null;
-    meeting.status = MEETING_STATUS.COMPLETED;
-    meeting.completedAt = ts();
-    return meeting;
+    assertMeetingLifecycle(meeting, 'end');
+    return completeMeeting(meeting);
   });
 }
 
 function archiveMeeting(id) {
+  const existing = getMeeting(id);
+  if (!existing) return null;
+  assertMeetingLifecycle(existing, 'archive');
   return mutateMeeting(id, (meeting) => {
     if (!meeting) return null;
+    assertMeetingLifecycle(meeting, 'archive');
     meeting.status = MEETING_STATUS.ARCHIVED;
     meeting.archivedAt = ts();
     return meeting;
@@ -888,18 +1044,22 @@ function archiveMeeting(id) {
 }
 
 function unarchiveMeeting(id) {
+  const existing = getMeeting(id);
+  if (!existing) return null;
+  assertMeetingLifecycle(existing, 'unarchive');
   return mutateMeeting(id, (meeting) => {
-    if (!meeting || meeting.status !== 'archived') return null;
-    meeting.status = 'completed';
+    if (!meeting) return null;
+    assertMeetingLifecycle(meeting, 'unarchive');
+    meeting.status = MEETING_STATUS.COMPLETED;
     delete meeting.archivedAt;
     return meeting;
   });
 }
 
 function deleteMeeting(id) {
+  if (!getMeeting(id)) return false;
   _killMeetingDispatches(id);
   const filePath = path.join(MEETINGS_DIR, id + '.json');
-  if (!fs.existsSync(filePath)) return false;
   try {
     fs.unlinkSync(filePath);
   } catch (e) {
@@ -1042,10 +1202,13 @@ function checkMeetingTimeouts(config) {
   }
 }
 module.exports = {
+  MEETING_LIMITS,
   MEETINGS_DIR, getMeetings, summarizeMeetingsForStatus, getMeeting, saveMeeting, mutateMeeting, createMeeting,
   invalidateMeetingsCache,
   discoverMeetingWork, collectMeetingFindings, checkMeetingTimeouts,
   addMeetingNote, advanceMeetingRound, endMeeting, archiveMeeting, unarchiveMeeting, deleteMeeting,
+  validateMeetingId, validateMeetingCreateInput, validateMeetingNote,
+  assertMeetingLifecycle, setMeetingRound, completeMeeting, advanceMeetingState,
   EMPTY_OUTPUT_PATTERNS,
   // exported for testing — engine code MUST go through
   // getMeetings/discoverMeetingWork/collectMeetingFindings/checkMeetingTimeouts,

package/engine/memory-retrieval.js

@@ -1,10 +1,12 @@
 // engine/memory-retrieval.js — deterministic task-aware memory selection.
 
 const memoryStore = require('./memory-store');
+const reviewLearning = require('./review-learning');
 
 const DEFAULT_TOP_K = 8;
 const DEFAULT_MAX_BYTES = 8 * 1024;
 const DEFAULT_CANDIDATES = 50;
+const REVIEW_LEARNING_CANDIDATE_LIMIT = 200;
 
 function buildTaskMemoryQuery(context = {}) {
   const references = Array.isArray(context.references)
@@ -152,6 +154,281 @@ function retrieveRelevantMemory(context = {}, options = {}) {
   };
 }
 
+// ── Reserved deterministic review-lesson recall ─────────────────────────────
+// A dedicated project + audience recall path that never depends on an FTS hit:
+// active review-learning lessons are listed straight from the project-scoped
+// index (memory-store#listActiveReviewLearnings) and ranked so that exact
+// affected-file, symbol, and tag overlap wins before lexical relevance,
+// confidence, and recency. The pack is byte-bounded independently of the
+// generic Relevant Memory budget and is fenced separately at the injection
+// site. Review-learning records are globally excluded from generic recall
+// (memory-store#searchMemoryRecords), so this is their only recall surface.
+
+const REVIEW_FILE_PATH_RE = /(?:[\w.$@+-]+\/)+[\w.$@+-]+\.[a-z0-9]{1,8}/gi;
+const REVIEW_BACKTICK_RE = /`([^`\n]{1,120})`/g;
+const REVIEW_CAMEL_RE = /\b[a-z][a-z0-9]*(?:[A-Z][a-z0-9]*)+\b/g;
+const REVIEW_CALL_RE = /\b([a-z_$][a-z0-9_$]{1,63})\s*\(/gi;
+const REVIEW_LEX_STOP = new Set([
+  'the', 'and', 'for', 'with', 'that', 'this', 'from', 'into', 'when', 'then',
+  'have', 'has', 'was', 'are', 'not', 'but', 'you', 'your', 'all', 'any',
+  'use', 'using', 'via', 'per', 'fix', 'review', 'implement', 'task', 'work',
+]);
+
+function _asArray(value) {
+  if (value == null || value === '') return [];
+  return Array.isArray(value) ? value : [value];
+}
+
+function _reviewContextText(context) {
+  const references = _asArray(context.references).map(ref => {
+    if (typeof ref === 'string') return ref;
+    if (!ref || typeof ref !== 'object') return '';
+    return [ref.path, ref.url, ref.title, ref.type].filter(Boolean).join(' ');
+  }).join(' ');
+  return [
+    context.title,
+    context.description,
+    context.type,
+    context.failureClass,
+    context.sourcePlan,
+    references,
+    context.prTitle,
+    context.prBranch,
+  ].filter(Boolean).join('\n');
+}
+
+function _reviewFilePaths(context, text) {
+  const raw = [];
+  for (const value of [..._asArray(context.files), ..._asArray(context.changedFiles)]) raw.push(value);
+  for (const ref of _asArray(context.references)) {
+    if (ref && typeof ref === 'object' && ref.path) raw.push(ref.path);
+  }
+  for (const match of text.matchAll(REVIEW_FILE_PATH_RE)) raw.push(match[0]);
+  return raw;
+}
+
+function _reviewSymbols(context, text) {
+  const raw = [..._asArray(context.symbols)];
+  for (const match of text.matchAll(REVIEW_BACKTICK_RE)) {
+    const inner = match[1].trim();
+    if (/^[\w.$/<>:-]+$/.test(inner)) raw.push(inner);
+  }
+  for (const match of text.matchAll(REVIEW_CAMEL_RE)) raw.push(match[0]);
+  for (const match of text.matchAll(REVIEW_CALL_RE)) raw.push(match[1]);
+  return raw;
+}
+
+function _reviewTags(context) {
+  const raw = [..._asArray(context.tags)];
+  if (context.type) raw.push(context.type);
+  return raw;
+}
+
+// Derive normalized affected-file, symbol, and tag hints for any project-bound
+// work item or PR dispatch. Normalization mirrors the capture side exactly
+// (review-learning#normalizeReviewFacets) so hint ↔ lesson facet comparison is
+// deterministic and case-insensitive.
+function deriveReviewFacetHints(context = {}) {
+  const text = _reviewContextText(context);
+  return reviewLearning.normalizeReviewFacets({
+    files: _reviewFilePaths(context, text),
+    symbols: _reviewSymbols(context, text),
+    tags: _reviewTags(context),
+  });
+}
+
+function _reviewLexTokens(text) {
+  const tokens = String(text || '').toLowerCase().match(/[a-z0-9][a-z0-9_.-]{2,63}/g) || [];
+  return new Set(tokens.filter(token => !REVIEW_LEX_STOP.has(token)));
+}
+
+function _overlapCount(a, b) {
+  if (!a.length || !b.length) return 0;
+  const other = new Set(b);
+  let count = 0;
+  for (const value of a) if (other.has(value)) count += 1;
+  return count;
+}
+
+function _lessonFacets(record) {
+  try {
+    return reviewLearning.normalizeReviewFacets(record.metadata || {});
+  } catch {
+    return { files: [], symbols: [], tags: [], area: 'general' };
+  }
+}
+
+// Rank applicable lessons: exact symbol, then file, then tag overlap dominate;
+// lexical relevance, confidence, and recency only break ties. A lesson is
+// applicable when it shares at least one exact facet OR any lexical token, so a
+// lexically unrelated task touching the same file/symbol still recalls it.
+function rankApplicableReviewLearnings(records, hints, options = {}) {
+  const hintTokens = options.hintTokens || _reviewLexTokens(options.queryText || '');
+  const scored = (Array.isArray(records) ? records : []).map(record => {
+    const facets = _lessonFacets(record);
+    const symbolOverlap = _overlapCount(hints.symbols, facets.symbols);
+    const fileOverlap = _overlapCount(hints.files, facets.files);
+    const tagOverlap = _overlapCount(hints.tags, facets.tags);
+    const lessonTokens = _reviewLexTokens(
+      `${record.title || ''}\n${record.body || ''}\n${(record.tags || []).join(' ')}`,
+    );
+    let lexical = 0;
+    for (const token of hintTokens) if (lessonTokens.has(token)) lexical += 1;
+    const confidence = Math.max(0, Math.min(1, Number(record.confidence) || 0));
+    const reasons = [];
+    if (symbolOverlap) reasons.push('exact-symbol');
+    if (fileOverlap) reasons.push('exact-file');
+    if (tagOverlap) reasons.push('exact-tag');
+    if (lexical) reasons.push('lexical');
+    const applicable = (symbolOverlap + fileOverlap + tagOverlap) > 0 || lexical > 0;
+    if (!applicable) reasons.push('not-applicable');
+    const score =
+      (symbolOverlap * 1000000) +
+      (fileOverlap * 10000) +
+      (tagOverlap * 100) +
+      Math.min(50, lexical) +
+      confidence;
+    return { record, facets, symbolOverlap, fileOverlap, tagOverlap, lexical, confidence, applicable, score, reasons };
+  });
+  return scored.sort((a, b) =>
+    b.symbolOverlap - a.symbolOverlap ||
+    b.fileOverlap - a.fileOverlap ||
+    b.tagOverlap - a.tagOverlap ||
+    b.lexical - a.lexical ||
+    b.confidence - a.confidence ||
+    Number(b.record.updatedAt || 0) - Number(a.record.updatedAt || 0) ||
+    String(a.record.id).localeCompare(String(b.record.id)));
+}
+
+function _formatReviewLesson(entry, bodyBytes) {
+  const record = entry.record;
+  const meta = record.metadata || {};
+  const provenance = [
+    `id=${record.id}`,
+    `audience=${meta.audience || 'project-team'}`,
+    meta.disposition ? `disposition=${meta.disposition}` : '',
+    `area=${meta.area || 'general'}`,
+    entry.facets.files.length ? `files=${entry.facets.files.join(',')}` : '',
+    entry.facets.symbols.length ? `symbols=${entry.facets.symbols.join(',')}` : '',
+    entry.facets.tags.length ? `tags=${entry.facets.tags.join(',')}` : '',
+    `date=${new Date(record.validFrom || record.createdAt || Date.now()).toISOString().slice(0, 10)}`,
+  ].filter(Boolean).join(' | ');
+  const fullBody = String(record.body || '');
+  const body = _truncateUtf8(fullBody, bodyBytes);
+  const truncated = body.length < fullBody.length ? '\n\n_[excerpt truncated]_' : '';
+  return `### ${record.title}\n_${provenance}_\n\n${body}${truncated}`;
+}
+
+// Bounded, deterministic recall of applicable prior review lessons. Returns a
+// separately-packable block capped at review-learning applicableTopK records /
+// applicableBytes, plus a bounded decision trace (stable ids, scores, reason
+// codes) suitable for retrieval telemetry.
+function retrieveApplicableReviewLearnings(context = {}, options = {}) {
+  const started = process.hrtime.bigint();
+  const project = String(context.project || '').trim();
+  const durationOf = () => Number(process.hrtime.bigint() - started) / 1e6;
+  const base = {
+    project,
+    hints: { files: [], symbols: [], tags: [], area: 'general' },
+    candidates: [],
+    selected: [],
+    text: '',
+    bytes: 0,
+    decisionTrace: [],
+    selectedIds: [],
+    durationMs: 0,
+  };
+  // Only dispatches with a resolved project context are eligible. Projectless
+  // Command Center and unrelated central work get no review-learning section.
+  if (!project) return { ...base, durationMs: durationOf() };
+
+  const bounds = reviewLearning.REVIEW_LEARNING_BOUNDS;
+  const topK = Math.max(1, Math.min(bounds.applicableTopK, Number(options.topK) || bounds.applicableTopK));
+  const maxBytes = Math.max(512, Math.min(bounds.applicableBytes, Number(options.maxBytes) || bounds.applicableBytes));
+  const hints = deriveReviewFacetHints(context);
+  const agent = String(context.agent || '').trim().toLowerCase();
+
+  let lessons;
+  try {
+    lessons = memoryStore.listActiveReviewLearnings({
+      project,
+      limit: Number(options.candidateLimit) || REVIEW_LEARNING_CANDIDATE_LIMIT,
+    });
+  } catch {
+    return { ...base, hints, durationMs: durationOf() };
+  }
+
+  // Audience gate: project-team lessons reach any agent in the same project;
+  // author-only lessons require the matching author agent. Project scoping is
+  // already enforced by listActiveReviewLearnings, so names/paths never leak
+  // across projects.
+  const audienceFiltered = (lessons || []).filter(record => {
+    const audience = String(record.metadata?.audience || 'project-team').toLowerCase();
+    if (audience === 'author') {
+      return !!agent && String(record.metadata?.authorAgent || '').toLowerCase() === agent;
+    }
+    return true;
+  });
+
+  const hintTokens = _reviewLexTokens(_reviewContextText(context));
+  const ranked = rankApplicableReviewLearnings(audienceFiltered, hints, { hintTokens });
+
+  const selected = [];
+  const decisionTrace = [];
+  let used = 0;
+  let rank = 0;
+  for (const entry of ranked) {
+    const traceEntry = {
+      id: entry.record.id,
+      rank,
+      score: Number(entry.score.toFixed(4)),
+      selected: false,
+      reasons: entry.reasons.slice(),
+    };
+    rank += 1;
+    if (!entry.applicable) {
+      decisionTrace.push(traceEntry);
+      continue;
+    }
+    if (selected.length >= topK) {
+      traceEntry.reasons.push('record-cap');
+      decisionTrace.push(traceEntry);
+      continue;
+    }
+    const remaining = maxBytes - used;
+    if (remaining < 128) {
+      traceEntry.reasons.push('byte-cap');
+      decisionTrace.push(traceEntry);
+      continue;
+    }
+    const block = _formatReviewLesson(entry, Math.max(96, remaining - 96));
+    const separator = selected.length ? '\n\n---\n\n' : '';
+    const bytes = Buffer.byteLength(separator + block, 'utf8');
+    if (bytes > remaining) {
+      traceEntry.reasons.push('byte-cap');
+      decisionTrace.push(traceEntry);
+      continue;
+    }
+    used += bytes;
+    selected.push({ record: entry.record, block });
+    traceEntry.selected = true;
+    decisionTrace.push(traceEntry);
+  }
+
+  const text = selected.map(item => item.block).join('\n\n---\n\n');
+  return {
+    project,
+    hints,
+    candidates: ranked,
+    selected: selected.map(item => item.record),
+    text,
+    bytes: used,
+    decisionTrace,
+    selectedIds: selected.map(item => item.record.id),
+    durationMs: durationOf(),
+  };
+}
+
 module.exports = {
   DEFAULT_TOP_K,
   DEFAULT_MAX_BYTES,
@@ -161,5 +438,8 @@ module.exports = {
   dedupeMemoryCandidates,
   packMemoryResults,
   retrieveRelevantMemory,
+  deriveReviewFacetHints,
+  rankApplicableReviewLearnings,
+  retrieveApplicableReviewLearnings,
   _truncateUtf8,
 };