@yemi33/minions 0.1.145 → 0.1.147

package/CHANGELOG.md

@@ -1,6 +1,19 @@
 # Changelog
 
-## 0.1.145 (2026-04-01)
+## 0.1.147 (2026-04-01)
+
+### Engine
+- engine/lifecycle.js
+- engine/shared.js
+
+### Dashboard
+- dashboard/js/render-work-items.js
+
+### Other
+- .github/workflows/pr-tests.yml
+- test/unit.test.js
+
+## 0.1.146 (2026-04-01)
 
 ### Engine
 - engine.js
@@ -12,13 +25,23 @@
 - 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-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;
@@ -388,6 +388,9 @@ function openWorkItemDetail(id) {
   if (item.references?.length) html += field('References', item.references.map(r => '<a href="' + escHtml(r.url) + '" target="_blank" style="color:var(--blue)">' + escHtml(r.title || r.url) + '</a>' + (r.type ? ' <span style="color:var(--muted);font-size:10px">(' + escHtml(r.type) + ')</span>' : '')).join('<br>'));
   if (item._humanFeedback) html += field('Human Feedback', (item._humanFeedback.rating === 'up' ? '👍' : '👎') + (item._humanFeedback.comment ? ' — ' + escHtml(item._humanFeedback.comment) : ''));
   if (item._pr) html += field('Pull Request', '<a href="' + escHtml(item._prUrl || '#') + '" target="_blank" style="color:var(--blue)">' + escHtml(item._pr) + '</a>');
+  if (item._totalCostUsd != null) html += field('Cumulative Cost', '$' + Number(item._totalCostUsd).toFixed(4));
+  if (item._totalInputTokens) html += field('Total Input Tokens', Number(item._totalInputTokens).toLocaleString());
+  if (item._totalOutputTokens) html += field('Total Output Tokens', Number(item._totalOutputTokens).toLocaleString());
   html += '</div>';
 
   document.getElementById('modal-title').textContent = item.title || item.id;

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

@@ -1025,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'.
@@ -1119,6 +1153,47 @@ function runPostCompletionHooks(dispatchItem, agentId, code, stdout, config) {
     } catch (err) { log('warn', `Session save: ${err.message}`); }
   }
 
+  // ── Accumulate per-work-item cost tracking ──────────────────────────────────
+  if (taskUsage && meta?.item?.id) {
+    try {
+      const wiPath = meta.source === 'central-work-item' || meta.source === 'central-work-item-fanout'
+        ? path.join(MINIONS_DIR, 'work-items.json')
+        : meta.project?.name ? path.join(MINIONS_DIR, 'projects', meta.project.name, 'work-items.json') : null;
+      if (wiPath) {
+        mutateJsonFileLocked(wiPath, (items) => {
+          if (!Array.isArray(items)) return items;
+          const wi = items.find(i => i.id === meta.item.id);
+          if (wi) {
+            wi._totalCostUsd = (wi._totalCostUsd || 0) + (taskUsage.costUsd || 0);
+            wi._totalInputTokens = (wi._totalInputTokens || 0) + (taskUsage.inputTokens || 0);
+            wi._totalOutputTokens = (wi._totalOutputTokens || 0) + (taskUsage.outputTokens || 0);
+          }
+          return items;
+        }, { defaultValue: [] });
+
+        // Cost ceiling circuit breaker — treat like evalMaxIterations exceeded
+        const engineCfg = config?.engine || {};
+        const evalMaxCost = engineCfg.evalMaxCost != null ? engineCfg.evalMaxCost : shared.ENGINE_DEFAULTS.evalMaxCost;
+        if (evalMaxCost != null && evalMaxCost > 0) {
+          const freshItems = safeJson(wiPath) || [];
+          const wi = freshItems.find(i => i.id === meta.item.id);
+          if (wi && wi._totalCostUsd > evalMaxCost && wi.status !== 'needs-human-review') {
+            mutateJsonFileLocked(wiPath, (items) => {
+              if (!Array.isArray(items)) return items;
+              const target = items.find(i => i.id === meta.item.id);
+              if (target) {
+                target.status = 'needs-human-review';
+                target.failReason = `Cumulative cost $${wi._totalCostUsd.toFixed(2)} exceeds evalMaxCost ceiling $${evalMaxCost.toFixed(2)}`;
+                log('warn', `Work item ${meta.item.id} exceeded cost ceiling ($${wi._totalCostUsd.toFixed(2)} > $${evalMaxCost.toFixed(2)}) — needs-human-review`);
+              }
+              return items;
+            }, { defaultValue: [] });
+          }
+        }
+      }
+    } catch (err) { log('warn', `Cost accumulation: ${err.message}`); }
+  }
+
   // Handle decomposition results — create sub-items from decompose agent output
   let skipDoneStatus = false;
   if (type === 'decompose' && isSuccess && meta?.item?.id) {
@@ -1145,6 +1220,106 @@ function runPostCompletionHooks(dispatchItem, agentId, code, stdout, config) {
   }
 
   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);
@@ -1346,6 +1521,7 @@ module.exports = {
   updateMetrics,
   recordContextPressureOnWorkItem,
   parseAgentOutput,
+  parseEvalVerdict,
   runPostCompletionHooks,
   syncPrdFromPrs,
 };

package/engine/shared.js

@@ -356,6 +356,9 @@ 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
+  evalMaxCost: null, // USD ceiling per work item across all eval iterations; null = no limit (gather baseline data first)
 };
 
 const DEFAULT_AGENTS = {

package/engine.js

@@ -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 : '');
@@ -1859,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

package/package.json

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