@yemi33/minions 0.1.1870 → 0.1.1871

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.1.1871 (2026-05-11)
+
+### Features
+-  per-agent memory file architecture (P-f1c5a8b6) (#2354)
+-  Implement pre-dispatch acceptance criteria validation gate (P-a2d6b9c7) (#2352)
+
 ## 0.1.1870 (2026-05-11)
 
 ### Fixes

package/engine/consolidation.js

@@ -15,6 +15,109 @@ const queries = require('./queries');
 const { getInboxFiles, getNotes, INBOX_DIR, ENGINE_DIR,
   NOTES_PATH, KNOWLEDGE_DIR, ARCHIVE_DIR } = queries;
 
+// Per-agent memory files live under knowledge/agents/<agent>.md and are
+// injected into individual agent prompts (in addition to the broadcast
+// notes.md). See knowledge/agents/README.md for the convention.
+const AGENT_MEMORY_DIR = path.join(KNOWLEDGE_DIR, 'agents');
+// Cap per-agent file size; oldest sections are pruned at section boundaries.
+const AGENT_MEMORY_BUDGET_BYTES = 25000;
+// Match valid agent IDs (lowercase alphanumeric + hyphen, no path separators);
+// excludes temp-* IDs which we filter separately.
+const AGENT_ID_PATTERN = /^[a-z][a-z0-9-]{0,40}$/;
+
+/**
+ * Extract the authoring agent for an inbox item.
+ * Prefers YAML frontmatter `agent:` field; falls back to filename prefix
+ * (`<agent>-...md`). Returns lowercase agent id or null.
+ */
+function extractInboxAgent(item) {
+  const content = String(item?.content || '');
+  const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+  if (fmMatch) {
+    const agentLine = fmMatch[1].split('\n').find(l => /^agent:\s*/i.test(l));
+    if (agentLine) {
+      const val = agentLine.replace(/^agent:\s*/i, '').trim().toLowerCase();
+      if (val && AGENT_ID_PATTERN.test(val)) return val;
+    }
+  }
+  // Filename fallback: take the leading [a-z][a-z0-9]* segment up to the
+  // first hyphen (e.g. `dallas-task-1.md` → `dallas`). Hyphens inside the
+  // capture would over-match (`rebecca-pr-7-2026.md` → `rebecca-pr-7`).
+  const nameMatch = String(item?.name || '').match(/^([a-z][a-z0-9]{1,40})-/i);
+  if (nameMatch) {
+    const val = nameMatch[1].toLowerCase();
+    if (AGENT_ID_PATTERN.test(val)) return val;
+  }
+  return null;
+}
+
+/**
+ * Append an inbox item to its author's personal memory file when the agent
+ * is a known team member (must be present in `knownAgents`) and not a
+ * temp-* id. Strict superset of broadcast consolidation — this never
+ * replaces the notes.md write; it's an additional per-agent personalization
+ * layer. Returns true on write, false on skip.
+ *
+ * `knownAgents` is required (a Set of lowercase agent IDs from
+ * `config.agents`). When omitted, per-agent routing is skipped entirely so
+ * we never create memory files for unverified IDs.
+ */
+function appendToAgentMemory(item, knownAgents) {
+  const agent = extractInboxAgent(item);
+  if (!agent) return false;
+  if (agent.startsWith('temp-')) return false;
+  if (!knownAgents || !knownAgents.has(agent)) return false;
+
+  if (!fs.existsSync(AGENT_MEMORY_DIR)) {
+    try { fs.mkdirSync(AGENT_MEMORY_DIR, { recursive: true }); }
+    catch (err) { log('warn', `Failed to create agent memory dir: ${err.message}`); return false; }
+  }
+
+  const memPath = path.join(AGENT_MEMORY_DIR, `${agent}.md`);
+  const content = String(item.content || '').trim();
+  if (!content) return false;
+
+  const titleMatch = content.match(/^#\s+(.+)/m);
+  const title = titleMatch ? titleMatch[1].trim() : (item.name || 'untitled').replace(/\.md$/, '');
+  const entry = `\n\n---\n\n### ${dateStamp()}: ${title}\n_Source: \`notes/inbox/${item.name}\`_\n\n${content}\n`;
+
+  try {
+    shared.withFileLock(memPath + '.lock', () => {
+      const existing = (fs.existsSync(memPath) ? safeRead(memPath) : '') || '';
+      let next = existing + entry;
+      if (Buffer.byteLength(next, 'utf8') > AGENT_MEMORY_BUDGET_BYTES) {
+        // Find the last section boundary that keeps us under budget.
+        const limit = AGENT_MEMORY_BUDGET_BYTES;
+        // Keep the header (everything before the first '\n---\n\n### ' boundary)
+        // and as many recent sections as fit.
+        const firstBoundary = next.indexOf('\n---\n\n### ');
+        if (firstBoundary > 0) {
+          const header = next.slice(0, firstBoundary);
+          const rest = next.slice(firstBoundary);
+          // Drop oldest sections until we're under budget.
+          const sections = rest.split('\n---\n\n### ').filter(Boolean);
+          let trimmed = sections;
+          while (trimmed.length > 1 &&
+                 Buffer.byteLength(header + '\n---\n\n### ' + trimmed.join('\n---\n\n### '), 'utf8') > limit) {
+            trimmed = trimmed.slice(1);
+          }
+          next = header + '\n---\n\n### ' + trimmed.join('\n---\n\n### ');
+          if (!next.endsWith('\n')) next += '\n';
+        } else {
+          // No boundaries — just truncate from the end (rare).
+          next = next.slice(-limit);
+        }
+        log('info', `Pruned knowledge/agents/${agent}.md to stay under ${limit} bytes`);
+      }
+      safeWrite(memPath, next);
+    });
+    return true;
+  } catch (err) {
+    log('warn', `Failed to append to knowledge/agents/${agent}.md: ${err.message}`);
+    return false;
+  }
+}
+
 // Track in-flight LLM consolidation to prevent concurrent runs
 let _consolidationInFlight = false;
 let _consolidationStartedAt = 0;
@@ -174,7 +277,7 @@ function consolidateWithLLM(items, existingNotes, files, config) {
     fallbackDone = true;
     if (message) log('warn', message);
     if (err?.message) log('debug', `LLM error: ${err.message}`);
-    consolidateWithRegex(items, files);
+    consolidateWithRegex(items, files, config);
   }
 
   const llmCall = callLLM(prompt, sysPrompt, {
@@ -250,7 +353,7 @@ function consolidateWithLLM(items, existingNotes, files, config) {
 
         safeWrite(NOTES_PATH, newContent);
       });
-      classifyToKnowledgeBase(items);
+      classifyToKnowledgeBase(items, config);
       archiveInboxFiles(files);
       log('info', `LLM consolidation complete: ${files.length} notes processed`);
     } else {
@@ -267,7 +370,7 @@ function consolidateWithLLM(items, existingNotes, files, config) {
 
 // ─── Regex Fallback Consolidation ────────────────────────────────────────────
 
-function consolidateWithRegex(items, files) {
+function consolidateWithRegex(items, files, config) {
 
   const allInsights = [];
   for (const item of items) {
@@ -379,17 +482,21 @@ function consolidateWithRegex(items, files) {
     }
     safeWrite(NOTES_PATH, newContent);
   });
-  classifyToKnowledgeBase(items);
+  classifyToKnowledgeBase(items, config);
   archiveInboxFiles(files);
   log('info', `Regex fallback: consolidated ${files.length} notes \u2192 ${deduped.length} insights into notes.md`);
 }
 
 // ─── Knowledge Base Classification ───────────────────────────────────────────
 
-function classifyToKnowledgeBase(items) {
+function classifyToKnowledgeBase(items, config) {
 
   if (!fs.existsSync(KNOWLEDGE_DIR)) fs.mkdirSync(KNOWLEDGE_DIR, { recursive: true });
 
+  const knownAgents = config && config.agents
+    ? new Set(Object.keys(config.agents).map(k => k.toLowerCase()))
+    : null;
+
   const categoryDirs = {};
   // Include 'general' as fallback category even if not in KB_CATEGORIES
   const allCategories = KB_CATEGORIES.includes('general') ? KB_CATEGORIES : [...KB_CATEGORIES, 'general'];
@@ -424,6 +531,11 @@ function classifyToKnowledgeBase(items) {
     } catch (err) {
       log('warn', `Failed to classify ${item.name} to knowledge base: ${err.message}`);
     }
+
+    // Per-agent memory routing — strict superset of broadcast consolidation.
+    // Appends the inbox content to knowledge/agents/<agent>.md when the
+    // author is a configured team member (skips temp-* and unknown agents).
+    appendToAgentMemory(item, knownAgents);
   }
 
   if (classified > 0) {
@@ -474,6 +586,11 @@ module.exports = {
   consolidateInbox,
   classifyToKnowledgeBase,
   checkDuplicateHash,
+  // per-agent memory routing
+  extractInboxAgent,
+  appendToAgentMemory,
+  AGENT_MEMORY_DIR,
+  AGENT_MEMORY_BUDGET_BYTES,
   // exported for testing
   buildConsolidationPrompt,
   consolidateWithLLM,

package/engine/dispatch.js

@@ -174,6 +174,105 @@ function addToDispatch(item) {
   return item.id;
 }
 
+// ─── Pre-Dispatch Acceptance Criteria Gate (P-a2d6b9c7, Ripley §3) ──────────
+//
+// Optional cheap-LLM validation gate that runs *before* queue insertion so
+// impossible/ambiguous work items are routed to a review queue rather than
+// burning a full agent run. Opt-in via ENGINE_DEFAULTS.enablePreDispatchEval.
+//
+// Wired from engine.js discoverWork(); kept as a separate async wrapper so
+// the existing synchronous addToDispatch() call sites are unaffected.
+
+function _persistInvalidWorkItem(item, evaluation) {
+  const meta = item?.meta;
+  const itemId = meta?.item?.id;
+  if (!itemId) return;
+  let wiPath;
+  try { wiPath = lifecycle().resolveWorkItemPath(meta); } catch { wiPath = null; }
+  if (!wiPath) return;
+  try {
+    mutateWorkItems(wiPath, (items) => {
+      if (!Array.isArray(items)) return items;
+      const idx = items.findIndex(w => w && w.id === itemId);
+      if (idx === -1) return items;
+      items[idx]._preDispatchEval = {
+        valid: false,
+        reason: evaluation.reason || '',
+        evaluatedAt: ts(),
+      };
+      return items;
+    }, { skipWriteIfUnchanged: true });
+  } catch (e) {
+    log('warn', `pre-dispatch-eval: failed to persist reason on ${itemId}: ${e.message}`);
+  }
+}
+
+function _routeToReviewQueue(item, evaluation) {
+  item.id = item.id || `${item.agent || 'unassigned'}-${item.type}-${shared.uid()}`;
+  item.created_at = ts();
+  item.meta = item.meta && typeof item.meta === 'object' ? item.meta : {};
+  item._preDispatchEval = {
+    valid: false,
+    reason: evaluation.reason || '',
+    evaluatedAt: ts(),
+  };
+  mutateDispatch((dispatch) => {
+    dispatch.review = Array.isArray(dispatch.review) ? dispatch.review : [];
+    // Dedup against the review queue itself so repeated discovery passes don't
+    // flood the queue with duplicates of the same WI.
+    const wiId = item.meta?.item?.id;
+    if (wiId && dispatch.review.some(d => d?.meta?.item?.id === wiId)) {
+      return dispatch;
+    }
+    dispatch.review.push(item);
+    return dispatch;
+  });
+}
+
+/**
+ * Async wrapper around addToDispatch that consults the pre-dispatch validator
+ * when ENGINE_DEFAULTS.enablePreDispatchEval is true. Validator failures are
+ * fail-open (the item still queues) — this gate must never wedge dispatch.
+ *
+ * @param {object} item - dispatch item (same shape addToDispatch expects).
+ * @param {object} [opts]
+ * @param {object} [opts.config] - engine config; defaults to queries.getConfig().
+ * @param {Function} [opts.validate] - injection point for tests; defaults to
+ *   require('./pre-dispatch-eval').validateAcceptanceCriteria.
+ * @returns {Promise<string|null>} dispatch id when queued; null when routed to review.
+ */
+async function addToDispatchWithValidation(item, opts = {}) {
+  const config = opts.config || queries.getConfig();
+  const enabled = config?.engine?.enablePreDispatchEval ?? ENGINE_DEFAULTS.enablePreDispatchEval;
+  if (!enabled) return addToDispatch(item);
+
+  const wi = item?.meta?.item;
+  const criteria = wi && (wi.acceptance_criteria || wi.acceptanceCriteria);
+  if (!Array.isArray(criteria) || criteria.length === 0) {
+    return addToDispatch(item);
+  }
+
+  const validate = typeof opts.validate === 'function'
+    ? opts.validate
+    : require('./pre-dispatch-eval').validateAcceptanceCriteria;
+
+  let evaluation;
+  try {
+    evaluation = await validate(wi, { engineConfig: config?.engine });
+  } catch (e) {
+    log('warn', `pre-dispatch-eval: validator threw — failing open: ${e.message}`);
+    return addToDispatch(item);
+  }
+
+  if (!evaluation || evaluation.valid !== false) return addToDispatch(item);
+
+  _persistInvalidWorkItem(item, evaluation);
+  _routeToReviewQueue(item, evaluation);
+  log('warn', `pre-dispatch-eval: blocked work item ${wi.id} — ${evaluation.reason || 'criteria not actionable'}`);
+  return null;
+}
+
+
 function _resolveDispatchProject(projectRef, config) {
   if (!projectRef) return null;
   const projects = getProjects(config);
@@ -686,6 +785,7 @@ function cancelPendingWorkItems(wiPath, matchFn, reason) {
 module.exports = {
   mutateDispatch,
   addToDispatch,
+  addToDispatchWithValidation,
   getPrDispatchDedupeKey,
   isRetryableFailureReason,
   completeDispatch,

package/engine/playbook.js

@@ -421,6 +421,25 @@ function renderPlaybook(type, vars) {
     inertAppendices.push('\n\n---\n\n## Team Notes (MUST READ)\n\n' + notes);
   }
 
+  // Inject per-agent memory file (knowledge/agents/<agentId>.md) — personal
+  // notebook curated by the consolidation pipeline. Capped at the same
+  // notes budget; missing file degrades gracefully (silent skip).
+  const agentIdForMemory = vars.agent_id;
+  if (agentIdForMemory && /^[a-z][a-z0-9-]{0,40}$/i.test(agentIdForMemory) && !String(agentIdForMemory).toLowerCase().startsWith('temp-')) {
+    const agentMemPath = path.join(MINIONS_DIR, 'knowledge', 'agents', `${String(agentIdForMemory).toLowerCase()}.md`);
+    let agentMem = '';
+    try { agentMem = fs.readFileSync(agentMemPath, 'utf8'); } catch { /* optional — file may not exist */ }
+    if (agentMem && agentMem.trim()) {
+      if (Buffer.byteLength(agentMem, 'utf8') > ENGINE_DEFAULTS.maxNotesPromptBytes) {
+        const sections = agentMem.split(/(?=^### )/m);
+        const recent = sections.slice(-10).join('') || agentMem;
+        const budget = Math.max(0, ENGINE_DEFAULTS.maxNotesPromptBytes);
+        agentMem = truncateTextBytes(recent, budget, '\n\n_...agent memory truncated_');
+      }
+      inertAppendices.push('\n\n---\n\n## Personal Memory (your past learnings — MUST READ)\n\n' + agentMem);
+    }
+  }
+
   // Inject KB guardrail
   content += `\n\n---\n\n## Knowledge Base Rules\n\n`;
   content += `**Never delete, move, or overwrite files in \`knowledge/\`.** The sweep (consolidation engine) is the only process that writes to \`knowledge/\`. If you think a KB file is wrong, note it in your learnings file — do not touch \`knowledge/\` directly.\n`;

package/engine/pre-dispatch-eval.js

@@ -0,0 +1,130 @@
+/**
+ * engine/pre-dispatch-eval.js — Cheap LLM gate that screens work items for
+ * clear/actionable/testable acceptance criteria *before* they are queued for
+ * dispatch. Catches impossible or ambiguous items so a slow/expensive agent
+ * run isn't burned on something that can't succeed.
+ *
+ * Conservative scope (per task contract):
+ *   - Validation only — never rewrites or "fixes" criteria.
+ *   - Opt-in via `ENGINE_DEFAULTS.enablePreDispatchEval` (default false) so it
+ *     can be enabled per-environment without forcing fleet-wide rollout.
+ *   - Fail-open: any LLM error / runtime-unavailable / parse failure resolves
+ *     `{ valid: true }` so the gate cannot wedge dispatch on its own.
+ *
+ * Wired from engine/dispatch.js → addToDispatchWithValidation().
+ *
+ * Source: Ripley §3 recommendation in
+ *   knowledge/architecture/2026-05-11-ripley-daily-architecture-bug-review-ripley-s-investigati.md
+ *   (Daily Architecture & Bug Review — 2026-05-11). Lambert + Rebecca debate
+ *   rounds reaffirmed: validate-only, no auto-rewrite, opt-in flag.
+ */
+
+const shared = require('./shared');
+const { log } = shared;
+const { callLLM } = require('./llm');
+
+const SYSTEM_PROMPT = 'Output only JSON.';
+const DEFAULT_TIMEOUT_MS = 60000;
+const DEFAULT_MODEL = 'haiku'; // claude shorthand; the runtime adapter expands it (see engine/runtimes/claude.js resolveModel)
+
+function _extractCriteria(workItem) {
+  if (!workItem || typeof workItem !== 'object') return [];
+  const candidates = [workItem.acceptance_criteria, workItem.acceptanceCriteria];
+  for (const c of candidates) {
+    if (Array.isArray(c) && c.length > 0) return c.map(String).filter(Boolean);
+  }
+  return [];
+}
+
+function _buildPrompt(workItem, criteria) {
+  const title = workItem.title || workItem.name || workItem.id || 'untitled';
+  const description = (workItem.description || '').trim();
+  const lines = [
+    `Work item: ${title}`,
+  ];
+  if (description) lines.push('', 'Description:', description);
+  lines.push('', 'Acceptance criteria:');
+  for (const c of criteria) lines.push(`- ${c}`);
+  lines.push('',
+    'Are these acceptance criteria clear, actionable, and testable?',
+    'Reply with JSON: {"valid": true|false, "reason": "..."}.');
+  return lines.join('\n');
+}
+
+function _parseResponse(text) {
+  let body = String(text || '').trim();
+  if (!body) return null;
+  const fence = body.match(/```(?:json)?\s*([\s\S]*?)```/i);
+  if (fence) body = fence[1].trim();
+  // Tolerate prose around the JSON object — grab the first top-level {...}
+  if (body[0] !== '{') {
+    const m = body.match(/\{[\s\S]*\}/);
+    if (m) body = m[0];
+  }
+  try { return JSON.parse(body); } catch { return null; }
+}
+
+/**
+ * Validate a work item's acceptance criteria with a fast/cheap LLM call.
+ *
+ * @param {object} workItem - work item with `acceptance_criteria` (or
+ *   `acceptanceCriteria`) plus title/description for context.
+ * @param {object} [opts]
+ * @param {object} [opts.engineConfig] - passed through to callLLM for
+ *   runtime/model resolution (CC path).
+ * @param {string} [opts.model] - explicit model override; defaults to 'haiku'.
+ * @param {number} [opts.timeout] - LLM timeout in ms.
+ * @returns {Promise<{valid: boolean, reason: string}>}
+ */
+async function validateAcceptanceCriteria(workItem, opts = {}) {
+  const criteria = _extractCriteria(workItem);
+  if (criteria.length === 0) {
+    return { valid: true, reason: 'no acceptance criteria to validate' };
+  }
+
+  const prompt = _buildPrompt(workItem, criteria);
+  let result;
+  try {
+    result = await callLLM(prompt, SYSTEM_PROMPT, {
+      timeout: Number(opts.timeout) > 0 ? Number(opts.timeout) : DEFAULT_TIMEOUT_MS,
+      label: 'pre-dispatch-eval',
+      model: opts.model || DEFAULT_MODEL,
+      maxTurns: 1,
+      direct: true,
+      engineConfig: opts.engineConfig,
+    });
+  } catch (e) {
+    log('warn', `pre-dispatch-eval: LLM call threw — failing open: ${e?.message || e}`);
+    return { valid: true, reason: `validator error: ${e?.message || 'unknown'}` };
+  }
+
+  if (!result) {
+    return { valid: true, reason: 'validator returned no result' };
+  }
+  if (result.missingRuntime) {
+    log('warn', 'pre-dispatch-eval: runtime unavailable — failing open');
+    return { valid: true, reason: 'validator runtime unavailable' };
+  }
+  if (result.code !== 0) {
+    log('warn', `pre-dispatch-eval: LLM exit ${result.code} — failing open: ${result.errorMessage || ''}`);
+    return { valid: true, reason: `validator exit ${result.code}` };
+  }
+
+  const parsed = _parseResponse(result.text);
+  if (!parsed || typeof parsed.valid !== 'boolean') {
+    log('warn', 'pre-dispatch-eval: response missing boolean valid field — failing open');
+    return { valid: true, reason: 'validator response unparseable' };
+  }
+  return {
+    valid: parsed.valid,
+    reason: String(parsed.reason || '').trim() || (parsed.valid ? 'criteria look testable' : 'criteria not clear/actionable/testable'),
+  };
+}
+
+module.exports = {
+  validateAcceptanceCriteria,
+  // Exposed for unit testing — engine code MUST go through validateAcceptanceCriteria.
+  _extractCriteria,
+  _buildPrompt,
+  _parseResponse,
+};

package/engine/shared.js

@@ -1099,6 +1099,7 @@ const ENGINE_DEFAULTS = {
   ignoredCommentAuthors: [], // comments from these authors are auto-closed and never trigger fixes
   agentBusyReassignMs: 600000, // 10min — reassign work item to another agent if preferred agent is busy beyond this threshold
   ccEffort: null, // effort level for CC/doc-chat (null, 'low', 'medium', 'high')
+  enablePreDispatchEval: false, // opt-in: cheap LLM gate before queueing — see engine/pre-dispatch-eval.js (Ripley §3 recommendation, 2026-05-11 architecture review)
 
   // ── Runtime fleet (P-3b8e5f1d) ──────────────────────────────────────────────
   // Single source of truth for which CLI runtime + model every spawn uses.

package/engine.js

@@ -110,7 +110,7 @@ function isPipelineBranchName(branchName) {
 
 // ─── Dispatch Management (extracted to engine/dispatch.js) ───────────────────
 
-const { mutateDispatch, addToDispatch, isRetryableFailureReason, completeDispatch,
+const { mutateDispatch, addToDispatch, addToDispatchWithValidation, isRetryableFailureReason, completeDispatch,
   writeInboxAlert, updateAgentStatus, pruneStalePrDispatches } = require('./engine/dispatch');
 
 // ─── Timeout / Steering / Idle (extracted to engine/timeout.js) ──────────────
@@ -4257,7 +4257,7 @@ async function discoverWork(config) {
   const allWork = [...allFixes, ...allReviews, ...allWorkItems, ...centralWork];
 
   for (const item of allWork) {
-    addToDispatch(item);
+    await addToDispatchWithValidation(item, { config });
     if (item.meta?.dispatchKey) setCooldown(item.meta.dispatchKey);
     if (item.meta?.source === 'pr-human-feedback') {
       clearPendingHumanFeedbackFlag(item.meta.project, item.meta.pr?.id);
@@ -4977,7 +4977,7 @@ module.exports = {
   validateConfig,
 
   // Dispatch management (re-exported from engine/dispatch.js)
-  mutateDispatch, addToDispatch, isRetryableFailureReason, completeDispatch, writeInboxAlert, updateAgentStatus, pruneStalePrDispatches,
+  mutateDispatch, addToDispatch, addToDispatchWithValidation, isRetryableFailureReason, completeDispatch, writeInboxAlert, updateAgentStatus, pruneStalePrDispatches,
   activeProcesses, realActivityMap, engineRestartGraceExempt,
   get engineRestartGraceUntil() { return engineRestartGraceUntil; },
   set engineRestartGraceUntil(v) { engineRestartGraceUntil = v; },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.1870",
+  "version": "0.1.1871",
   "description": "Multi-agent AI dev team that runs from ~/.minions/ — five autonomous agents share a single engine, dashboard, and knowledge base",
   "bin": {
     "minions": "bin/minions.js"