@yemi33/minions 0.1.1870 → 0.1.1872

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.1.1872 (2026-05-11)
+
+### Features
+-  Stale-HEAD guard on fix-task pushes (P-c8f2d5e3) (#2360)
+- Cached buildStatus invalidation on no-op completion (#2355)
+-  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/lifecycle.js

@@ -1592,7 +1592,7 @@ async function detectPrFixBranchChange(meta, config) {
   return { changed: null, beforeHead, afterHead: remoteHead || '', reason: 'unable to prove branch head after fix' };
 }
 
-function recordPrNoOpFixAttempt(target, cause, source, dispatchItem, branchChange, config) {
+function recordPrNoOpFixAttempt(target, cause, source, dispatchItem, branchChange, config, noopReason) {
   const evidenceFingerprint = shared.prFixEvidenceFingerprint(target, cause);
   const prior = shared.getPrNoOpFixRecord(target, cause);
   const sameEvidence = prior?.evidenceFingerprint === evidenceFingerprint;
@@ -1623,6 +1623,20 @@ function recordPrNoOpFixAttempt(target, cause, source, dispatchItem, branchChang
     afterHead: branchChange?.afterHead || '',
   };
 
+  // Record a same-SHA dispatch outcome on the PR record so the eligibility
+  // filter can short-circuit duplicate build-fix dispatches against an
+  // unchanged commit. Reset happens implicitly when headSha advances and the
+  // discovery filter compares lastDispatchHeadSha to the current head.
+  const headSha = getPrFixBaselineHead(target);
+  target.lastDispatchedAt = now;
+  target.lastDispatchOutcome = 'noop';
+  target.lastDispatchHeadSha = headSha;
+  target.lastDispatchReason = String(
+    noopReason
+      || branchChange?.reason
+      || 'fix completed without changing the PR branch'
+  ).slice(0, 500);
+
   if (cause === shared.PR_FIX_CAUSE.HUMAN_FEEDBACK && target.humanFeedback) {
     target.humanFeedback.pendingFix = !paused;
     if (paused) target.humanFeedback.noOpPaused = true;
@@ -1639,6 +1653,14 @@ function clearPrNoOpFixAttempt(target, cause) {
   if (Object.keys(target._noOpFixes).length === 0) delete target._noOpFixes;
   if (target._lastNoOpFix?.cause === cause) delete target._lastNoOpFix;
   if (target.humanFeedback) delete target.humanFeedback.noOpPaused;
+  // The lastDispatch* trackers exist to prevent duplicate noop dispatches at
+  // the same head; once the agent actually pushed a fix we no longer want them
+  // to suppress a fresh dispatch (the SHA may have moved or the next failure
+  // is genuinely new).
+  delete target.lastDispatchedAt;
+  delete target.lastDispatchOutcome;
+  delete target.lastDispatchHeadSha;
+  delete target.lastDispatchReason;
 }
 
 function updatePrAfterFix(pr, project, source, options = {}, legacyDispatchId = '') {
@@ -1666,7 +1688,7 @@ function updatePrAfterFix(pr, project, source, options = {}, legacyDispatchId =
       target.minionsReview = next;
     };
     if (explicitlyChangedBranch && options.branchChange?.changed === false) {
-      const record = recordPrNoOpFixAttempt(target, cause, source, options.dispatchItem, options.branchChange, options.config);
+      const record = recordPrNoOpFixAttempt(target, cause, source, options.dispatchItem, options.branchChange, options.config, options.noopReason);
       result = { noOp: true, cause, paused: !!record.paused, count: record.count };
       log('warn', `Updated ${pr.id} → recorded no-op ${cause} fix attempt ${record.count}${record.paused ? ' (paused)' : ''}; PR branch was unchanged`);
       return prs;
@@ -1678,7 +1700,7 @@ function updatePrAfterFix(pr, project, source, options = {}, legacyDispatchId =
     // automation cause handled — a future tick with working detection must
     // be free to re-dispatch.
     if (explicitlyChangedBranch && options.branchChange?.changed === null) {
-      const record = recordPrNoOpFixAttempt(target, cause, source, options.dispatchItem, options.branchChange, options.config);
+      const record = recordPrNoOpFixAttempt(target, cause, source, options.dispatchItem, options.branchChange, options.config, options.noopReason);
       result = { noOp: true, cause, paused: !!record.paused, count: record.count, indeterminate: true };
       log('warn', `Updated ${pr.id} → recorded indeterminate ${cause} fix attempt ${record.count}${record.paused ? ' (paused)' : ''}; PR branch advance could not be verified${options.branchChange?.reason ? ` (${options.branchChange.reason})` : ''}`);
       return prs;
@@ -3208,6 +3230,7 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
       dispatchItem,
       branchChange: prFixBranchChange,
       config,
+      noopReason: noopRationale || meta?._noopReason || '',
     });
     // (#984) Sync PRD status for PR-linked features: fix work items have a different ID
     // than the original PRD feature, so syncPrdItemStatus(fixWiId, ...) finds nothing.

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/spawn-agent.js

@@ -162,6 +162,81 @@ function formatProcessExitSentinel(exitCode, signal) {
   return `\n[process-exit] code=${exitCode}${signal ? ` signal=${signal}` : ''}\n`;
 }
 
+/**
+ * Pre-push stale-HEAD guard for fix-task dispatches (P-c8f2d5e3).
+ *
+ * When the engine reuses an existing worktree on a PR branch that was rebased
+ * upstream (force-push), the local HEAD can sit behind origin/<branch>. The
+ * first push from that worktree silently overwrites the rebased history — a
+ * confirmed silent-overwrite footgun captured in team memory.
+ *
+ * This helper runs:
+ *   git fetch origin <branch>
+ *   git rev-list --count HEAD..origin/<branch>
+ * inside the worktree. When the count is > 0 it throws a clear, actionable
+ * error so engine.spawnAgent can abort the dispatch before invoking the
+ * runtime CLI — i.e. before the agent has a chance to push.
+ *
+ * The fetch is best-effort: if origin doesn't have the ref yet (first push on
+ * a fresh branch, common for shared-branch plan items), the helper returns
+ * `{ ok: true, skipped: 'no-upstream' }` instead of failing — there's no
+ * rebased tip to overwrite. Any other fetch failure is also treated as a
+ * skip with `skipped: 'fetch-failed'` so transient network issues don't
+ * brick an otherwise-healthy dispatch.
+ *
+ * @param {object} args
+ * @param {string} args.branch - PR branch name (already sanitized)
+ * @param {string} args.cwd    - Worktree path
+ * @param {function} [args.exec] - Async exec(cmd, opts) — injectable for tests
+ * @param {object}   [args.gitOpts] - Options passed through to exec
+ * @returns {Promise<{ok: true, behindCount: number, skipped?: string}>}
+ * @throws {Error & {code: 'STALE_HEAD'}} when local HEAD is behind origin
+ */
+async function assertStaleHeadOk({ branch, cwd, exec, gitOpts } = {}) {
+  if (!branch) throw new Error('assertStaleHeadOk: branch is required');
+  if (!cwd) throw new Error('assertStaleHeadOk: cwd is required');
+  const execFn = typeof exec === 'function'
+    ? exec
+    : require('./shared').execAsync;
+  const opts = { ...(gitOpts || {}), cwd };
+
+  // Best-effort fetch. Branch-missing-on-origin is a legitimate state (first
+  // push on a freshly-cut feature branch) and must NOT block dispatch.
+  try {
+    await execFn(`git fetch origin "${branch}"`, opts);
+  } catch (err) {
+    const msg = (err && (err.stderr?.toString?.() || err.message || '')) + '';
+    if (/couldn'?t find remote ref|not found in upstream|unknown revision/i.test(msg)) {
+      return { ok: true, behindCount: 0, skipped: 'no-upstream' };
+    }
+    // Other failures (network/auth/timeout) — skip rather than block.
+    return { ok: true, behindCount: 0, skipped: 'fetch-failed' };
+  }
+
+  let countOut;
+  try {
+    countOut = await execFn(`git rev-list --count HEAD..origin/${branch}`, opts);
+  } catch (err) {
+    // origin/<branch> resolution failed AFTER fetch — treat as no-upstream.
+    return { ok: true, behindCount: 0, skipped: 'rev-list-failed' };
+  }
+  const raw = typeof countOut === 'string'
+    ? countOut
+    : (countOut?.stdout?.toString?.() ?? String(countOut ?? ''));
+  const behindCount = parseInt(String(raw).trim(), 10);
+  if (!Number.isFinite(behindCount) || behindCount <= 0) {
+    return { ok: true, behindCount: Number.isFinite(behindCount) ? behindCount : 0 };
+  }
+  const err = new Error(
+    `PR branch was rebased; local HEAD is stale (${behindCount} commits behind origin). ` +
+    `Run \`git pull --rebase origin ${branch}\` first.`
+  );
+  err.code = 'STALE_HEAD';
+  err.behindCount = behindCount;
+  err.branch = branch;
+  throw err;
+}
+
 // The orphan reaper recovers an agent's exit code by scanning live-output.log for
 // `[process-exit] code=N`. The previous design wrote the sentinel to stdout, hoping
 // the engine's stdout consumer (engine.js) would copy it into the file — but when
@@ -456,6 +531,6 @@ function main() {
   });
 }
 
-module.exports = { parseSpawnArgs, buildSpawnInvocation, normalizeRuntimeExit, shouldInjectAdoTokenEnv, injectAdoTokenEnv, injectAdoTokenEnvForRepoHost, writeProcessExitSentinel, computeAddDirs, createParentPipeForwarder };
+module.exports = { parseSpawnArgs, buildSpawnInvocation, normalizeRuntimeExit, shouldInjectAdoTokenEnv, injectAdoTokenEnv, injectAdoTokenEnvForRepoHost, writeProcessExitSentinel, computeAddDirs, createParentPipeForwarder, assertStaleHeadOk };
 
 if (require.main === module) main();

package/engine.js

@@ -28,6 +28,7 @@ const { exec, execAsync, execSilent, runFile, ts, ENGINE_DEFAULTS,
   WI_STATUS, DONE_STATUSES, WORK_TYPE, PLAN_STATUS, PRD_ITEM_STATUS, PRD_MATERIALIZABLE, PR_STATUS, DISPATCH_RESULT, AGENT_STATUS,
   FAILURE_CLASS } = shared;
 const { resolveRuntime } = require('./engine/runtimes');
+const { assertStaleHeadOk } = require('./engine/spawn-agent');
 const queries = require('./engine/queries');
 
 // ─── Paths ──────────────────────────────────────────────────────────────────
@@ -110,7 +111,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) ──────────────
@@ -1114,6 +1115,41 @@ async function spawnAgent(dispatchItem, config) {
     log('warn', `Agent ${agentId} running ${type} task in main repo (no worktree) for ${id} — changes may land on master directly`);
   }
 
+  // ── Stale-HEAD guard for fix-task pushes (P-c8f2d5e3) ────────────────────
+  // When a PR branch is rebased upstream (force-push), a reused worktree can
+  // sit on local HEAD that's behind origin/<branch>. The first push from that
+  // worktree silently overwrites the rebased history. Fix-task dispatches are
+  // the canonical case: they always target an existing PR branch the engine
+  // already polled. Abort dispatch BEFORE invoking the runtime CLI so the
+  // agent never gets a chance to push over the rebased tip.
+  // Read-only and non-fix dispatches are out of scope — implement tasks cut
+  // their own branch from main, and review/verify don't push.
+  if (type === WORK_TYPE.FIX && branchName && worktreePath && cwd === worktreePath) {
+    try {
+      const guard = await assertStaleHeadOk({
+        branch: branchName,
+        cwd: worktreePath,
+        exec: execAsync,
+        gitOpts: { ..._gitOpts, timeout: 15000 },
+      });
+      if (guard.skipped) {
+        log('info', `Stale-HEAD guard skipped for ${id} (${branchName}): ${guard.skipped}`);
+      }
+    } catch (err) {
+      if (err && err.code === 'STALE_HEAD') {
+        log('error', `Stale-HEAD guard rejected fix dispatch ${id} on ${branchName}: ${err.message}`);
+        _cleanupPromptFiles();
+        completeDispatch(id, DISPATCH_RESULT.ERROR, err.message.slice(0, 300));
+        cleanupTempAgent(agentId);
+        return null;
+      }
+      // Non-STALE_HEAD failures from the guard itself shouldn't block dispatch
+      // (the guard is conservative by design — fetch/network issues fall through
+      // to skipped:'fetch-failed'). Log and continue.
+      log('warn', `Stale-HEAD guard error for ${id} (${branchName}): ${err.message}`);
+    }
+  }
+
   // ── Runtime + opts resolution (P-2a6d9c4f) ────────────────────────────────
   // Every CLI-specific knob flows through the runtime adapter resolved from
   // resolveAgentCli(agent, engine). Engine code MUST NOT branch on
@@ -2936,6 +2972,20 @@ async function discoverFromPrs(config, project) {
     const autoFixBuilds = config.engine?.autoFixBuilds ?? ENGINE_DEFAULTS.autoFixBuilds;
     if (pollEnabled && autoFixBuilds && pr.status === PR_STATUS.ACTIVE && pr.buildStatus === 'failing'
       && !isPrNoOpFixCauseSuppressed(pr, shared.PR_FIX_CAUSE.BUILD_FAILURE)) {
+      // P-b7e1c4d2: skip when the most recent dispatch already noop'd against
+      // the same head SHA — chronic across PRs #2315–#2323 where every fix
+      // agent rebutted "this is a pre-existing master baseline" but the
+      // cached buildStatus:failing kept re-triggering the loop. The check
+      // clears automatically once a new commit lands (lastDispatchHeadSha
+      // stops matching the current head).
+      const currentHeadSha = String(pr.headSha || pr._adoSourceCommit || pr._adoHeadCommit || '').trim();
+      if (pr.lastDispatchOutcome === 'noop'
+        && pr.lastDispatchHeadSha
+        && currentHeadSha
+        && pr.lastDispatchHeadSha === currentHeadSha) {
+        log('info', `Skipping build-fix for ${pr.id}: last dispatch was noop on the same head ${currentHeadSha.slice(0, 8)} (${(pr.lastDispatchReason || '').slice(0, 120)})`);
+        continue;
+      }
       const buildCauseKey = getPrAutomationCauseKey('build', pr);
       const key = getPrAutomationDispatchKey(`build-fix-${project?.name || 'default'}-${prDisplayId}`, buildCauseKey);
       if (isPrAutomationCauseHandledOrPending(project, pr, buildCauseKey)) continue;
@@ -4257,7 +4307,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 +5027,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.1872",
   "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"