@yemi33/minions 0.1.144 → 0.1.146

package/CHANGELOG.md

@@ -1,18 +1,34 @@
 # Changelog
 
-## 0.1.144 (2026-04-01)
+## 0.1.146 (2026-04-01)
 
 ### Engine
+- engine.js
 - engine/ado.js
 - engine/cleanup.js
 - engine/cooldown.js
 - engine/github.js
+- engine/lifecycle.js
 - engine/meeting.js
 - engine/playbook.js
 - engine/routing.js
+- engine/shared.js
 - engine/timeout.js
 
+### Dashboard
+- dashboard/js/render-other.js
+- dashboard/js/render-work-items.js
+- dashboard/pages/engine.html
+- dashboard/styles.css
+
+### Playbooks
+- evaluate.md
+- fix.md
+- implement.md
+
 ### Other
+- CLAUDE.md
+- routing.md
 - test/unit.test.js
 
 ## 0.1.143 (2026-04-01)

package/dashboard/js/render-other.js

@@ -44,6 +44,7 @@ function renderMetrics(metrics) {
   if (agents.length === 0) {
     el.innerHTML = '<p class="empty">No metrics yet. Metrics appear after agents complete tasks.</p>';
     renderTokenUsage(metrics);
+    renderContextPressure(metrics);
     return;
   }
   let html = '<table class="pr-table"><thead><tr><th>Agent</th><th>Done</th><th>Errors</th><th>PRs</th><th>Approved</th><th>Rejected</th><th>Rate</th><th>Reviews</th></tr></thead><tbody>';
@@ -64,6 +65,7 @@ function renderMetrics(metrics) {
   html += '</tbody></table>';
   el.innerHTML = html;
   renderTokenUsage(metrics);
+  renderContextPressure(metrics);
 }
 
 function renderTokenUsage(metrics) {
@@ -183,4 +185,25 @@ function renderTokenUsage(metrics) {
   el.innerHTML = html;
 }
 
-window.MinionsOther = { renderProjects, renderMcpServers, renderMetrics, renderTokenUsage };
+function renderContextPressure(metrics) {
+  const el = document.getElementById('context-pressure-content');
+  if (!el) return;
+  const cp = metrics._contextPressure;
+  if (!cp || !cp.dispatches) {
+    el.innerHTML = '<p class="empty">No context pressure data yet. Data appears after agents complete tasks.</p>';
+    return;
+  }
+  const avgTurns = (cp.totalTurns / cp.dispatches).toFixed(1);
+  const turnLimitPct = ((cp.turnLimitHits / cp.dispatches) * 100).toFixed(1);
+  const pctColor = parseFloat(turnLimitPct) > 20 ? 'var(--red)' : parseFloat(turnLimitPct) > 5 ? 'var(--yellow, orange)' : 'var(--green)';
+
+  let html = '<div class="token-tiles">';
+  html += '<div class="token-tile"><div class="token-tile-label">Avg Turns</div><div class="token-tile-value">' + avgTurns + '</div><div class="token-tile-sub">per dispatch</div></div>';
+  html += '<div class="token-tile"><div class="token-tile-label">Max Turns</div><div class="token-tile-value">' + cp.maxTurns + '</div></div>';
+  html += '<div class="token-tile"><div class="token-tile-label">Hit Turn Limit</div><div class="token-tile-value" style="color:' + pctColor + '">' + turnLimitPct + '%</div><div class="token-tile-sub">' + cp.turnLimitHits + ' of ' + cp.dispatches + ' dispatches</div></div>';
+  html += '<div class="token-tile"><div class="token-tile-label">Total Dispatches</div><div class="token-tile-value">' + cp.dispatches + '</div></div>';
+  html += '</div>';
+  el.innerHTML = html;
+}
+
+window.MinionsOther = { renderProjects, renderMcpServers, renderMetrics, renderTokenUsage, renderContextPressure };

package/dashboard/js/render-work-items.js

@@ -6,7 +6,7 @@ const WI_PER_PAGE = 20;
 
 function wiRow(item) {
   const statusBadge = (s) => {
-    const cls = s === 'failed' ? 'rejected' : s === 'dispatched' ? 'building' : s === 'pending' || s === 'queued' ? 'active' : s === 'done' ? 'approved' : 'draft';
+    const cls = s === 'failed' ? 'rejected' : s === 'needs-human-review' ? 'needs-review' : s === 'dispatched' ? 'building' : s === 'pending' || s === 'queued' ? 'active' : s === 'done' ? 'approved' : 'draft';
     return '<span class="pr-badge ' + cls + '">' + escHtml(s) + '</span>';
   };
   const typeBadge = (t) => '<span class="dispatch-type ' + (t || 'implement') + '">' + escHtml(t || 'implement') + '</span>';
@@ -38,9 +38,9 @@ function wiRow(item) {
       (item.acceptanceCriteria && item.acceptanceCriteria.length ? '<span title="' + item.acceptanceCriteria.length + ' acceptance criteria">&#x2611;' + item.acceptanceCriteria.length + '</span>' : '') +
     '</td>' +
     '<td style="white-space:nowrap">' +
-      ((item.status === 'pending' || item.status === 'failed') ? '<button class="pr-pager-btn" style="font-size:9px;padding:1px 6px;color:var(--blue);border-color:var(--blue);margin-right:4px" onclick="event.stopPropagation();editWorkItem(\'' + escHtml(item.id) + '\',\'' + escHtml(item._source || '') + '\')" title="Edit work item">&#x270E;</button>' : '') +
-      ((item.status === 'done' || item.status === 'failed') ? '<button class="pr-pager-btn" style="font-size:9px;padding:1px 6px;color:var(--muted);border-color:var(--border);margin-right:4px" onclick="event.stopPropagation();archiveWorkItem(\'' + escHtml(item.id) + '\',\'' + escHtml(item._source || '') + '\')" title="Archive work item">&#x1F4E6;</button>' : '') +
-      ((item.status === 'done' || item.status === 'failed') && !item._humanFeedback ? '<button class="pr-pager-btn" style="font-size:9px;padding:1px 6px;color:var(--green);border-color:var(--green);margin-right:4px" onclick="event.stopPropagation();feedbackWorkItem(\'' + escHtml(item.id) + '\',\'' + escHtml(item._source || '') + '\')" title="Give feedback">&#x1F44D;&#x1F44E;</button>' : (item._humanFeedback ? '<span style="font-size:9px" title="Feedback given">' + (item._humanFeedback.rating === 'up' ? '&#x1F44D;' : '&#x1F44E;') + '</span> ' : '')) +
+      ((item.status === 'pending' || item.status === 'failed' || item.status === 'needs-human-review') ? '<button class="pr-pager-btn" style="font-size:9px;padding:1px 6px;color:var(--blue);border-color:var(--blue);margin-right:4px" onclick="event.stopPropagation();editWorkItem(\'' + escHtml(item.id) + '\',\'' + escHtml(item._source || '') + '\')" title="Edit work item">&#x270E;</button>' : '') +
+      ((item.status === 'done' || item.status === 'failed' || item.status === 'needs-human-review') ? '<button class="pr-pager-btn" style="font-size:9px;padding:1px 6px;color:var(--muted);border-color:var(--border);margin-right:4px" onclick="event.stopPropagation();archiveWorkItem(\'' + escHtml(item.id) + '\',\'' + escHtml(item._source || '') + '\')" title="Archive work item">&#x1F4E6;</button>' : '') +
+      ((item.status === 'done' || item.status === 'failed' || item.status === 'needs-human-review') && !item._humanFeedback ? '<button class="pr-pager-btn" style="font-size:9px;padding:1px 6px;color:var(--green);border-color:var(--green);margin-right:4px" onclick="event.stopPropagation();feedbackWorkItem(\'' + escHtml(item.id) + '\',\'' + escHtml(item._source || '') + '\')" title="Give feedback">&#x1F44D;&#x1F44E;</button>' : (item._humanFeedback ? '<span style="font-size:9px" title="Feedback given">' + (item._humanFeedback.rating === 'up' ? '&#x1F44D;' : '&#x1F44E;') + '</span> ' : '')) +
       '<button class="pr-pager-btn" style="font-size:9px;padding:1px 6px;color:var(--red);border-color:var(--red)" onclick="event.stopPropagation();deleteWorkItem(\'' + escHtml(item.id) + '\',\'' + escHtml(item._source || '') + '\')" title="Delete work item and kill agent">&#x2715;</button>' +
     '</td>' +
   '</tr>';
@@ -49,7 +49,7 @@ function wiRow(item) {
 function renderWorkItems(items) {
   items = items.filter(function(w) { return !isDeleted('wi:' + w.id); });
   // Sort: active/dispatched first, then by most recent activity
-  const statusOrder = { dispatched: 0, pending: 1, queued: 1, failed: 2, done: 3 };
+  const statusOrder = { dispatched: 0, pending: 1, queued: 1, 'needs-human-review': 2, failed: 2, done: 3 };
   items.sort((a, b) => {
     const sa = statusOrder[a.status] ?? 2, sb = statusOrder[b.status] ?? 2;
     if (sa !== sb) return sa - sb;

package/dashboard/pages/engine.html

@@ -10,3 +10,7 @@
         <h2>Token Usage</h2>
         <div id="token-usage-content"><p class="empty">No usage data yet.</p></div>
       </section>
+      <section>
+        <h2>Context Pressure</h2>
+        <div id="context-pressure-content"><p class="empty">No context pressure data yet. Data appears after agents complete tasks.</p></div>
+      </section>

package/dashboard/styles.css

@@ -186,6 +186,7 @@
   .prd-item-row.st-in-progress { border-left-color: var(--yellow); animation: prdWipPulse 2s infinite; }
   @keyframes prdWipPulse { 0%, 100% { box-shadow: 0 0 0 0 rgba(210,153,34,0); } 50% { box-shadow: 0 0 0 4px rgba(210,153,34,0.2); } }
   .prd-item-row.st-failed { border-left-color: var(--red); }
+  .prd-item-row.st-needs-human-review { border-left-color: var(--orange); }
   .prd-item-row.st-paused { border-left-color: var(--muted); opacity: 0.5; }
   .prd-item-id { font-family: Consolas, monospace; color: var(--muted); min-width: 36px; font-size: 0.9em; }
   .prd-item-name { flex: 1; color: var(--text); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
@@ -232,6 +233,7 @@
   .pr-badge.active { background: rgba(88,166,255,0.15); color: var(--blue); border: 1px solid var(--blue); }
   .pr-badge.approved { background: rgba(63,185,80,0.15); color: var(--green); border: 1px solid var(--green); }
   .pr-badge.rejected { background: rgba(248,81,73,0.15); color: var(--red); border: 1px solid var(--red); }
+  .pr-badge.needs-review { background: rgba(227,179,65,0.15); color: var(--orange); border: 1px solid var(--orange); }
   .pr-badge.merged { background: rgba(188,140,255,0.15); color: var(--purple); border: 1px solid var(--purple); }
   .pr-badge.building { background: rgba(210,153,34,0.15); color: var(--yellow); border: 1px solid var(--yellow); animation: pulse 1.5s infinite; }
   .pr-badge.build-pass { background: rgba(63,185,80,0.15); color: var(--green); border: 1px solid var(--green); }

package/engine/lifecycle.js

@@ -932,6 +932,30 @@ function createReviewFeedbackForAuthor(reviewerAgentId, pr, config) {
   if (wrote) log('info', `Created review feedback for ${authorAgentId} from ${reviewerAgentId} on ${pr.id}`);
 }
 
+function recordContextPressureOnWorkItem(meta, turnCount, outputLogSizeBytes, hitTurnLimit) {
+  const itemId = meta.item?.id;
+  if (!itemId) return;
+
+  let wiPath;
+  if (meta.source === 'central-work-item' || meta.source === 'central-work-item-fanout') {
+    wiPath = path.join(MINIONS_DIR, 'work-items.json');
+  } else if (meta.source === 'work-item' && meta.project?.name) {
+    wiPath = path.join(MINIONS_DIR, 'projects', meta.project.name, 'work-items.json');
+  }
+  if (!wiPath) return;
+
+  shared.mutateJsonFileLocked(wiPath, (items) => {
+    if (!Array.isArray(items)) return items;
+    const target = items.find(i => i.id === itemId);
+    if (target) {
+      target._turnCount = turnCount;
+      target._outputLogSizeBytes = outputLogSizeBytes;
+      target._hitTurnLimit = hitTurnLimit;
+    }
+    return items;
+  }, { defaultValue: [] });
+}
+
 function updateMetrics(agentId, dispatchItem, result, taskUsage, prsCreatedCount, model) {
 
   const metricsPath = path.join(ENGINE_DIR, 'metrics.json');
@@ -977,6 +1001,20 @@ function updateMetrics(agentId, dispatchItem, result, taskUsage, prsCreatedCount
   for (const day of Object.keys(metrics._daily)) {
     if (day < cutoffStr) delete metrics._daily[day];
   }
+
+  // Update contextPressure aggregate
+  if (taskUsage && taskUsage.numTurns > 0) {
+    if (!metrics._contextPressure) metrics._contextPressure = { totalTurns: 0, dispatches: 0, maxTurns: 0, turnLimitHits: 0 };
+    const cp = metrics._contextPressure;
+    cp.totalTurns += taskUsage.numTurns;
+    cp.dispatches++;
+    if (taskUsage.numTurns > cp.maxTurns) cp.maxTurns = taskUsage.numTurns;
+    // Check if this dispatch hit the turn limit
+    const engineConfig = require('./queries').getConfig()?.engine || {};
+    const turnLimit = engineConfig.maxTurns || 100;
+    if (taskUsage.numTurns >= turnLimit) cp.turnLimitHits++;
+  }
+
   shared.safeWrite(metricsPath, metrics);
 }
 
@@ -987,6 +1025,40 @@ function parseAgentOutput(stdout) {
   return { resultSummary: text, taskUsage: usage, sessionId, model };
 }
 
+/**
+ * Resolve work-items.json path from dispatch meta.
+ * Central items → MINIONS_DIR/work-items.json; project items → projects/<name>/work-items.json.
+ */
+function resolveWiPath(meta) {
+  if (meta.source === 'central-work-item' || meta.source === 'central-work-item-fanout') {
+    return path.join(MINIONS_DIR, 'work-items.json');
+  }
+  if (meta.project?.name) {
+    return path.join(MINIONS_DIR, 'projects', meta.project.name, 'work-items.json');
+  }
+  return null;
+}
+
+/**
+ * Parse structured eval verdict from evaluate agent output.
+ * Looks for a JSON block with { pass, build, tests, criteria_met, criteria_failed, feedback }.
+ * Returns parsed object or null if not found.
+ */
+function parseEvalVerdict(text) {
+  if (!text) return null;
+  // Look for JSON fenced block first, then bare JSON
+  const fenced = text.match(/```(?:json)?\s*\n(\{[\s\S]*?"pass"\s*:[\s\S]*?\})\s*\n```/);
+  if (fenced) {
+    try { return JSON.parse(fenced[1]); } catch { /* fall through */ }
+  }
+  // Try bare JSON with "pass" key
+  const bare = text.match(/(\{[\s\S]*?"pass"\s*:[\s\S]*?\})/);
+  if (bare) {
+    try { return JSON.parse(bare[1]); } catch { /* ignore */ }
+  }
+  return null;
+}
+
 /**
  * Handle decomposition result — parse sub-items from agent output and create child work items.
  * Called from runPostCompletionHooks when type === 'decompose'.
@@ -1089,7 +1161,124 @@ function runPostCompletionHooks(dispatchItem, agentId, code, stdout, config) {
     // If decomposition produced nothing, fall through to mark parent as done
   }
 
+  // Record context utilization metrics on the work item
+  if (meta?.item?.id) {
+    try {
+      const engineConfig = (config.engine || {});
+      const turnLimit = engineConfig.maxTurns || 100;
+      const turnCount = taskUsage?.numTurns || 0;
+      const hitTurnLimit = turnCount >= turnLimit;
+      let outputLogSizeBytes = 0;
+      try {
+        const liveLogPath = path.join(AGENTS_DIR, agentId, 'live-output.log');
+        const stat = fs.statSync(liveLogPath);
+        outputLogSizeBytes = stat.size;
+      } catch { /* file may not exist */ }
+      recordContextPressureOnWorkItem(meta, turnCount, outputLogSizeBytes, hitTurnLimit);
+    } catch (err) { log('warn', `Context pressure record: ${err.message}`); }
+  }
+
   if (isSuccess && meta?.item?.id && !skipDoneStatus) updateWorkItemStatus(meta, 'done', '');
+
+  // Auto-dispatch evaluate work item after implement completes successfully
+  if (isSuccess && !skipDoneStatus && type === 'implement' && meta?.item?.id) {
+    const evalLoop = config.engine?.evalLoop ?? shared.ENGINE_DEFAULTS.evalLoop;
+    if (evalLoop) {
+      try {
+        const wiPath = resolveWiPath(meta);
+        if (wiPath) {
+          const items = safeJson(wiPath) || [];
+          // Dedup: skip if an evaluate item already exists for this parent
+          const existing = items.find(i => i._evalParentId === meta.item.id && i.type === 'evaluate');
+          if (existing) {
+            log('info', `Eval loop: evaluate item ${existing.id} already exists for ${meta.item.id}, skipping`);
+          } else {
+            const parentItem = items.find(i => i.id === meta.item.id);
+            const evalItem = {
+              id: 'W-' + shared.uid(),
+              title: `Evaluate: ${meta.item.title || meta.item.id}`,
+              type: 'evaluate',
+              priority: meta.item.priority || 'high',
+              status: 'pending',
+              created: ts(),
+              createdBy: 'engine:eval-loop',
+              project: meta.project?.name || meta.item.project,
+              branch_name: parentItem?.branch_name || meta.branch || null,
+              pr_url: parentItem?.pr_url || null,
+              acceptance_criteria: parentItem?.acceptance_criteria || meta.item.acceptance_criteria || null,
+              _evalParentId: meta.item.id,
+            };
+            if (parentItem?.sourcePlan) evalItem.sourcePlan = parentItem.sourcePlan;
+            // Mark parent as eval-dispatched before writing to prevent duplicates on re-run
+            if (parentItem) parentItem._evalDispatched = true;
+            items.push(evalItem);
+            shared.safeWrite(wiPath, items);
+            log('info', `Eval loop: created ${evalItem.id} for completed implement ${meta.item.id}`);
+          }
+        }
+      } catch (err) {
+        log('warn', `Eval loop dispatch error: ${err.message}`);
+      }
+    }
+  }
+
+  // Evaluate completion: parse verdict and handle eval→fix iteration loop
+  if (isSuccess && type === 'evaluate' && meta?.item?._evalParentId) {
+    try {
+      const verdict = parseEvalVerdict(resultSummary || stdout);
+      const evalLoop = config.engine?.evalLoop ?? shared.ENGINE_DEFAULTS.evalLoop;
+      const maxIter = config.engine?.evalMaxIterations ?? shared.ENGINE_DEFAULTS.evalMaxIterations;
+
+      if (verdict && !verdict.pass && evalLoop) {
+        const wiPath = resolveWiPath(meta);
+        if (wiPath) {
+          const items = safeJson(wiPath) || [];
+          const parent = items.find(i => i.id === meta.item._evalParentId);
+          if (parent) {
+            const iterations = (parent._evalIterations || 0) + 1;
+            parent._evalIterations = iterations;
+
+            if (iterations >= maxIter) {
+              // Max iterations reached — escalate to human review
+              parent.status = 'needs-human-review';
+              parent._evalEscalatedAt = ts();
+              shared.safeWrite(wiPath, items);
+              log('info', `Eval loop: ${parent.id} reached ${iterations}/${maxIter} iterations — escalated to needs-human-review`);
+            } else {
+              // Create fix work item with evaluator feedback
+              const fixItem = {
+                id: 'W-' + shared.uid(),
+                title: `Fix: ${parent.title || parent.id} (eval iteration ${iterations})`,
+                type: 'fix',
+                priority: parent.priority || 'high',
+                status: 'pending',
+                created: ts(),
+                createdBy: 'engine:eval-loop',
+                project: meta.project?.name || meta.item.project,
+                branch_name: parent.branch_name || meta.item.branch_name || null,
+                pr_url: parent.pr_url || meta.item.pr_url || null,
+                acceptance_criteria: parent.acceptance_criteria || null,
+                _evalParentId: parent.id,
+                _evalFeedback: verdict.feedback || null,
+                _evalCriteriaFailed: verdict.criteria_failed || null,
+              };
+              if (parent.sourcePlan) fixItem.sourcePlan = parent.sourcePlan;
+              // Clear eval-dispatched flag so next fix→eval cycle can dispatch
+              parent._evalDispatched = false;
+              // Parent stays 'done' — fix item picks up from here
+              parent.status = 'done';
+              items.push(fixItem);
+              shared.safeWrite(wiPath, items);
+              log('info', `Eval loop: created fix ${fixItem.id} for failed eval on ${parent.id} (iteration ${iterations}/${maxIter})`);
+            }
+          }
+        }
+      }
+    } catch (err) {
+      log('warn', `Eval verdict processing error: ${err.message}`);
+    }
+  }
+
   if (!isSuccess && meta?.item?.id) {
     // Auto-retry: read fresh _retryCount from file (not stale dispatch-time snapshot)
     let retries = (meta.item._retryCount || 0);
@@ -1289,7 +1478,9 @@ module.exports = {
   updateAgentHistory,
   createReviewFeedbackForAuthor,
   updateMetrics,
+  recordContextPressureOnWorkItem,
   parseAgentOutput,
+  parseEvalVerdict,
   runPostCompletionHooks,
   syncPrdFromPrs,
 };

package/engine/meeting.js

@@ -78,8 +78,12 @@ function discoverMeetingWork(config) {
     const agents = config.agents || {};
 
     if (roundName === 'concluding') {
-      // Only one agent concludes (first participant)
-      const concluder = meeting.participants[0];
+      // Pick the first non-busy participant as concluder (fallback to any participant)
+      const busyAgents = new Set(
+        (dispatch.active || []).map(d => d.agent).filter(Boolean)
+      );
+      const concluder = meeting.participants.find(p => !busyAgents.has(p))
+        || meeting.participants[0];
       if (!concluder) continue;
       const key = `meeting-${meeting.id}-r${round}-${concluder}`;
       if (activeKeys.has(key)) continue;

package/engine/playbook.js

@@ -206,9 +206,25 @@ function resolveTaskContext(item, config) {
   return resolved;
 }
 
+// ─── Critical Variable Definitions ─────────────────────────────────────────
+// Variables that MUST resolve to non-empty values for dispatch to proceed.
+// If any critical variable is empty or unresolved, renderPlaybook returns null.
+const CRITICAL_VARS = {
+  'implement': ['task_description', 'branch_name'],
+  'implement-shared': ['task_description', 'branch_name'],
+  'fix': ['task_description', 'branch_name'],
+  'work-item': ['task_description'],
+};
+
+// Module-level error state — callers check via getLastRenderError() after null return
+let _lastRenderError = null;
+
+function getLastRenderError() { return _lastRenderError; }
+
 // ─── Playbook Renderer ──────────────────────────────────────────────────────
 
 function renderPlaybook(type, vars) {
+  _lastRenderError = null;
   const pbPath = path.join(PLAYBOOKS_DIR, `${type}.md`);
   let content;
   try { content = fs.readFileSync(pbPath, 'utf8'); } catch {
@@ -299,6 +315,20 @@ function renderPlaybook(type, vars) {
     log('warn', `Playbook "${type}": unresolved template variables: ${unresolved.join(', ')}`);
   }
 
+  // Block dispatch if critical variables are empty or unresolved
+  const criticalVars = CRITICAL_VARS[type] || [];
+  if (criticalVars.length > 0) {
+    const emptySet = new Set(emptyVars);
+    const unresolvedSet = new Set(unresolved);
+    const criticalMissing = criticalVars.filter(v => emptySet.has(v) || unresolvedSet.has(v));
+    if (criticalMissing.length > 0) {
+      const msg = `Playbook "${type}": critical variables empty or unresolved: ${criticalMissing.join(', ')} — blocking dispatch`;
+      log('warn', msg);
+      _lastRenderError = { reason: 'critical_vars_missing', vars: criticalMissing, message: msg };
+      return null;
+    }
+  }
+
   return content;
 }
 
@@ -470,6 +500,8 @@ function buildPrDispatch(agentId, config, project, pr, type, extraVars, taskLabe
 
 module.exports = {
   renderPlaybook,
+  getLastRenderError,
+  CRITICAL_VARS,
   buildSystemPrompt,
   buildAgentContext,
   selectPlaybook,

package/engine/shared.js

@@ -356,6 +356,8 @@ const ENGINE_DEFAULTS = {
   autoApprovePlans: false, // auto-approve PRDs without waiting for human approval
   autoReview: true, // auto-dispatch review agents for new PRs (disable for manual review workflow)
   meetingRoundTimeout: 600000, // 10min per meeting round before auto-advance
+  evalLoop: true, // enable evaluate→fix loop after implementation completes
+  evalMaxIterations: 3, // max evaluate→fix cycles before escalating to human
 };
 
 const DEFAULT_AGENTS = {

package/engine.js

@@ -120,7 +120,7 @@ const { getRouting, parseRoutingTable, getRoutingTableCached, getMonthlySpend,
 
 // ─── Playbook, system prompt, agent context (extracted to engine/playbook.js) ─
 
-const { renderPlaybook, buildSystemPrompt, buildAgentContext, selectPlaybook,
+const { renderPlaybook, getLastRenderError, buildSystemPrompt, buildAgentContext, selectPlaybook,
   buildBaseVars, buildPrDispatch, resolveTaskContext,
   getRepoHostLabel, getRepoHostToolRule } = require('./engine/playbook');
 
@@ -1474,6 +1474,38 @@ function discoverFromWorkItems(config, project) {
     const ac = (item.acceptanceCriteria || []).map(c => '- [ ] ' + c).join('\n');
     vars.acceptance_criteria = ac ? '## Acceptance Criteria\n\n' + ac : '';
 
+    // Inject checkpoint context if agent left a checkpoint.json from a prior run
+    vars.checkpoint_context = '';
+    try {
+      const wtPath = vars.worktree_path || root;
+      const cpPath = path.join(wtPath, 'checkpoint.json');
+      if (fs.existsSync(cpPath)) {
+        const cpData = JSON.parse(fs.readFileSync(cpPath, 'utf8'));
+        const cpCount = (item._checkpointCount || 0) + 1;
+        if (cpCount > 3) {
+          log('warn', `Work item ${item.id} exceeded 3 checkpoint-resumes — marking as needs-human-review`);
+          item.status = 'needs-human-review';
+          item._checkpointCount = cpCount;
+          needsWrite = true;
+          continue;
+        }
+        item._checkpointCount = cpCount;
+        needsWrite = true;
+        const cpSummary = [
+          `## Checkpoint (Resume #${cpCount}/3)`,
+          '',
+          'A previous agent run timed out but left a checkpoint. Continue from where it left off.',
+          '',
+          cpData.completed && cpData.completed.length > 0 ? `### Completed\n${cpData.completed.map(s => '- ' + s).join('\n')}` : '',
+          cpData.remaining && cpData.remaining.length > 0 ? `### Remaining\n${cpData.remaining.map(s => '- ' + s).join('\n')}` : '',
+          cpData.blockers && cpData.blockers.length > 0 ? `### Blockers\n${cpData.blockers.map(s => '- ' + s).join('\n')}` : '',
+          cpData.branch_state ? `### Branch State\n${cpData.branch_state}` : '',
+        ].filter(Boolean).join('\n');
+        vars.checkpoint_context = cpSummary;
+        log('info', `Injecting checkpoint context for ${item.id} (resume #${cpCount})`);
+      }
+    } catch (e) { log('warn', `checkpoint read for ${item.id}: ${e.message}`); }
+
     // Inject ask-specific variables for the ask playbook
     if (workType === 'ask') {
       vars.question = item.title + (item.description ? '\n\n' + item.description : '');
@@ -1493,9 +1525,17 @@ function discoverFromWorkItems(config, project) {
     if (playbookName === 'work-item' && workType === 'review') {
       log('info', `Work item ${item.id} is type "review" but has no PR — using work-item playbook`);
     }
-    const prompt = item.prompt || renderPlaybook(playbookName, vars) || renderPlaybook('work-item', vars) || item.description;
+    const rendered = renderPlaybook(playbookName, vars);
+    const renderError = getLastRenderError();
+    // If critical vars are missing, block dispatch entirely — don't fall through to work-item playbook
+    const prompt = item.prompt || rendered || (renderError ? null : (renderPlaybook('work-item', vars) || item.description));
     if (!prompt) {
-      log('warn', `No playbook rendered for ${item.id} (type: ${workType}, playbook: ${playbookName}) — skipping`);
+      if (renderError) {
+        log('warn', `Skipping ${item.id}: ${renderError.message}`);
+        if (item._pendingReason !== 'critical_vars_missing') { item._pendingReason = 'critical_vars_missing'; needsWrite = true; }
+      } else {
+        log('warn', `No playbook rendered for ${item.id} (type: ${workType}, playbook: ${playbookName}) — skipping`);
+      }
       continue;
     }
 
@@ -1782,9 +1822,16 @@ function discoverCentralWorkItems(config) {
         }
 
         const playbookName = selectPlaybook(workType, item);
-        const prompt = renderPlaybook(playbookName, vars) || renderPlaybook('work-item', vars);
+        const rendered = renderPlaybook(playbookName, vars);
+        const renderError = getLastRenderError();
+        const prompt = rendered || (renderError ? null : renderPlaybook('work-item', vars));
         if (!prompt) {
-          log('warn', `Fan-out: playbook '${playbookName}' failed to render for ${item.id} → ${agent.id}, skipping`);
+          if (renderError) {
+            log('warn', `Fan-out: ${item.id} → ${agent.id}: ${renderError.message}`);
+            if (item._pendingReason !== 'critical_vars_missing') { item._pendingReason = 'critical_vars_missing'; }
+          } else {
+            log('warn', `Fan-out: playbook '${playbookName}' failed to render for ${item.id} → ${agent.id}, skipping`);
+          }
           continue;
         }
 
@@ -1844,6 +1891,39 @@ function discoverCentralWorkItems(config) {
       const normAc = (item.acceptanceCriteria || []).map(c => '- [ ] ' + c).join('\n');
       vars.acceptance_criteria = normAc ? '## Acceptance Criteria\n\n' + normAc : '';
 
+      // Inject checkpoint context if agent left a checkpoint.json from a prior run
+      vars.checkpoint_context = '';
+      try {
+        const centralBranch = item.branch || `work/${item.id}`;
+        const centralWtPath = firstProject?.localPath
+          ? path.resolve(firstProject.localPath, config.engine?.worktreeRoot || '../worktrees', centralBranch)
+          : '';
+        const cpPath = centralWtPath ? path.join(centralWtPath, 'checkpoint.json') : '';
+        if (cpPath && fs.existsSync(cpPath)) {
+          const cpData = JSON.parse(fs.readFileSync(cpPath, 'utf8'));
+          const cpCount = (item._checkpointCount || 0) + 1;
+          if (cpCount > 3) {
+            log('warn', `Work item ${item.id} exceeded 3 checkpoint-resumes — marking as needs-human-review`);
+            item.status = 'needs-human-review';
+            item._checkpointCount = cpCount;
+            continue;
+          }
+          item._checkpointCount = cpCount;
+          const cpSummary = [
+            `## Checkpoint (Resume #${cpCount}/3)`,
+            '',
+            'A previous agent run timed out but left a checkpoint. Continue from where it left off.',
+            '',
+            cpData.completed && cpData.completed.length > 0 ? `### Completed\n${cpData.completed.map(s => '- ' + s).join('\n')}` : '',
+            cpData.remaining && cpData.remaining.length > 0 ? `### Remaining\n${cpData.remaining.map(s => '- ' + s).join('\n')}` : '',
+            cpData.blockers && cpData.blockers.length > 0 ? `### Blockers\n${cpData.blockers.map(s => '- ' + s).join('\n')}` : '',
+            cpData.branch_state ? `### Branch State\n${cpData.branch_state}` : '',
+          ].filter(Boolean).join('\n');
+          vars.checkpoint_context = cpSummary;
+          log('info', `Injecting checkpoint context for ${item.id} (resume #${cpCount})`);
+        }
+      } catch (e) { log('warn', `checkpoint read for ${item.id}: ${e.message}`); }
+
       // Inject plan-specific variables for the plan playbook
       if (workType === 'plan') {
         // Ensure plans directory exists before agent tries to write
@@ -1894,9 +1974,16 @@ function discoverCentralWorkItems(config) {
       }
 
       const playbookName = selectPlaybook(workType, item);
-      const prompt = renderPlaybook(playbookName, vars) || renderPlaybook('work-item', vars);
+      const rendered = renderPlaybook(playbookName, vars);
+      const renderError = getLastRenderError();
+      const prompt = rendered || (renderError ? null : renderPlaybook('work-item', vars));
       if (!prompt) {
-        log('warn', `Dispatch: playbook '${playbookName}' failed to render for ${item.id}, resetting to pending`);
+        if (renderError) {
+          log('warn', `Dispatch: ${item.id}: ${renderError.message}`);
+          item._pendingReason = 'critical_vars_missing';
+        } else {
+          log('warn', `Dispatch: playbook '${playbookName}' failed to render for ${item.id}, resetting to pending`);
+        }
         item.status = 'pending';
         continue;
       }
@@ -2378,6 +2465,7 @@ module.exports = {
 
   // Playbooks
   renderPlaybook,
+  getLastRenderError,
 
   // Timeout / Steering / Idle (re-exported from engine/timeout.js)
   checkTimeouts, checkSteering, checkIdleThreshold,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.144",
+  "version": "0.1.146",
   "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"

package/playbooks/evaluate.md

@@ -0,0 +1,114 @@
+# Evaluate: {{item_name}}
+
+> Agent: {{agent_name}} ({{agent_role}}) | Team root: {{team_root}}
+
+## Context
+
+Project: {{project_name}}
+Repo: {{repo_name}} | Org: {{ado_org}} | ADO Project: {{ado_project}}
+PR: {{pr_url}}
+Work Item: {{item_id}}
+
+## Acceptance Criteria
+
+{{acceptance_criteria}}
+
+## Task Description
+
+{{task_description}}
+
+## Your Task
+
+You are the **Evaluator** in the Planner-Generator-Evaluator pattern. Your job is to independently verify whether the implementation in the PR branch meets the acceptance criteria. You are NOT the implementer — you are the skeptic.
+
+**Mindset: Do not pass unless build succeeds AND all acceptance criteria are demonstrably met.** Assume the implementation is incomplete or wrong until proven otherwise. Look for edge cases, missing requirements, and silent failures.
+
+## Step 1: Check Out the PR Branch
+
+```bash
+cd {{project_path}}
+git fetch origin
+git checkout {{branch_name}}
+git pull origin {{branch_name}}
+```
+
+## Step 2: Build
+
+Run the project build. Check `CLAUDE.md`, `package.json`, or `README` for build instructions.
+
+```bash
+# Typical:
+npm install && npm run build
+# Or whatever the project uses
+```
+
+Record: **PASS** or **FAIL** with error output.
+
+If the build fails, **stop here** — the verdict is `pass: false`. Include the build error in feedback.
+
+## Step 3: Run Tests
+
+Run the full test suite:
+
+```bash
+npm test
+```
+
+Record: **X passed / Y failed / Z skipped**.
+
+If any tests fail, note which ones and whether they are related to the changes.
+
+## Step 4: Diff Review Against Acceptance Criteria
+
+Review the actual code changes:
+
+```bash
+git diff {{main_branch}}...{{branch_name}} --stat
+git diff {{main_branch}}...{{branch_name}}
+```
+
+For **each** acceptance criterion, determine:
+- **Met**: The diff demonstrably satisfies this criterion. Cite the specific file/line.
+- **Not met**: The diff does not satisfy this criterion, or satisfies it only partially. Explain what's missing.
+
+Be precise. "Looks good" is not an evaluation — cite file paths and line numbers.
+
+## Step 5: Output Structured Verdict
+
+After completing your evaluation, output the following JSON block as your final output. This MUST be valid JSON wrapped in a `json` fenced code block:
+
+```json
+{
+  "pass": false,
+  "build": true,
+  "tests": "42/42",
+  "criteria_met": [
+    "criterion 1 — met because X (source: path/to/file.js:42)"
+  ],
+  "criteria_failed": [
+    "criterion 2 — not met because Y is missing"
+  ],
+  "feedback": "Summary of what needs to change for this to pass. Be specific — file names, line numbers, what to add/fix."
+}
+```
+
+Field definitions:
+- `pass`: `true` only if build succeeds AND **all** acceptance criteria are met. Otherwise `false`.
+- `build`: `true` if the build completed without errors, `false` otherwise.
+- `tests`: String in format `"passed/total"` (e.g., `"38/40"`). Use `"N/A"` if no test suite exists.
+- `criteria_met`: Array of strings — one per criterion that IS met. Include source references.
+- `criteria_failed`: Array of strings — one per criterion that is NOT met. Explain why.
+- `feedback`: Actionable feedback for the implementer. Be specific about what to fix. If `pass` is `true`, use this for minor suggestions or "LGTM".
+
+## Rules
+
+- **No Playwright / browser testing** — this phase evaluates build, tests, and code review only.
+- **Do NOT fix code** — only evaluate and report. You are the evaluator, not the implementer.
+- **Do NOT rubber-stamp** — if a criterion is ambiguous, evaluate conservatively (fail it and explain).
+- **Build failure is an automatic fail** — do not evaluate criteria if the build doesn't pass.
+- **Every criterion must be addressed** — `criteria_met` + `criteria_failed` should cover all acceptance criteria.
+- **Cite sources** — reference file paths and line numbers for every met/failed criterion.
+
+{{references}}
+
+**Note:** Do NOT write to `agents/*/status.json` — the engine manages your status automatically.

package/playbooks/fix.md

@@ -11,6 +11,8 @@ Repo: {{repo_name}} | Org: {{ado_org}} | Project: {{ado_project}}
 Fix issues found by {{reviewer}} on **{{pr_id}}**: {{pr_title}}
 Branch: `{{pr_branch}}`
 
+{{checkpoint_context}}
+
 ## Review Findings to Address
 
 {{review_note}}

package/playbooks/implement.md

@@ -18,6 +18,8 @@ Implement PRD item **{{item_id}}: {{item_name}}**
 - Complexity: {{item_complexity}}
 - Description: {{item_description}}
 
+{{checkpoint_context}}
+
 ## Projects
 
 Primary repo: **{{repo_name}}** ({{ado_org}}/{{ado_project}}) at `{{project_path}}`

package/routing.md

@@ -17,6 +17,7 @@ How the engine decides who handles what. Parsed by engine.js — keep the table
 | test | dallas | ralph |
 | ask | ripley | rebecca |
 | verify | dallas | ralph |
+| evaluate | ripley | lambert |
 | decompose | ripley | rebecca |
 | meeting | ripley | rebecca |