@yemi33/minions 0.1.289 → 0.1.291

package/CHANGELOG.md

@@ -1,15 +1,20 @@
 # Changelog
 
-## 0.1.289 (2026-04-03)
+## 0.1.291 (2026-04-03)
 
 ### Features
 -  all doc-chats use Sonnet with full tools (agent change)
 
 ### Fixes
+-  defer plan archiving until verify completes, add 20 verify tests
+-  enforce worktree isolation — 4 code paths fixed
 - ' not 'Evaluate:'
 -  cross-platform compatibility — signal handling, paths, home dir
 -  engine sidebar badge only triggers on new dispatch errors
 
+### Other
+- resolve merge conflicts — accept agent changes, keep worktree isolation fix
+
 ## 0.1.285 (2026-04-03)
 
 ### Fixes

package/dashboard/js/render-plans.js

@@ -227,7 +227,9 @@ function renderPlans(plans) {
       'onclick="event.stopPropagation();planExecute(\'' + escHtml(p.file) + '\',\'' + escHtml(p.project) + '\',this)">Execute</button>' : '';
     const showPause = effectiveStatus === 'in-progress' && prdFile && !isArchived;
     const showResume = (effectiveStatus === 'paused' || effectiveStatus === 'awaiting-approval') && prdFile && !isArchived;
-    const showVerify = effectiveStatus === 'completed' && prdFile && !isArchived;
+    const verifyWi = allWi.find(w => w.itemType === 'verify' && w.sourcePlan === prdFile);
+    const hasVerifyWi = !!verifyWi;
+    const showVerify = effectiveStatus === 'completed' && prdFile && !isArchived && !hasVerifyWi;
     const pauseBtn = showPause ? '<button class="pr-pager-btn" style="font-size:9px;padding:2px 8px;color:var(--yellow)" ' +
       'onclick="event.stopPropagation();planPause(\'' + escHtml(prdFile) + '\',this)">Pause</button>' : '';
     const resumeBtn = showResume
@@ -256,7 +258,7 @@ function renderPlans(plans) {
             (p.updatedAt ? '<span title="Last updated: ' + p.updatedAt + '">Updated ' + timeAgo(p.updatedAt) + '</span>' : '') +
             (p.completedAt ? '<span>' + p.completedAt.slice(0, 10) + '</span>' : '') +
             (p.generatedBy ? '<span>by ' + escHtml(p.generatedBy) + '</span>' : '') +
-            executeBtn + pauseBtn + resumeBtn + verifyBtn + archiveBtn + deleteBtn +
+            executeBtn + pauseBtn + resumeBtn + verifyBtn + (hasVerifyWi ? _renderVerifyBadge(verifyWi) : '') + archiveBtn + deleteBtn +
           '</div>' +
         '</div>' +
       '</div>' +
@@ -442,13 +444,15 @@ function _renderPlanModal(normalizedFile, raw, lastMod) {
     'onclick="planPause(\'' + escHtml(normalizedFile) + '\',this)">Pause</button>' : '';
   const modalResumeBtn = isPaused ? '<button class="pr-pager-btn" style="font-size:10px;padding:2px 10px;color:var(--green)" ' +
     'onclick="planApprove(\'' + escHtml(normalizedFile) + '\',this)">Resume</button>' : '';
-  const modalVerifyBtn = isModalCompleted ? '<button class="pr-pager-btn" style="font-size:10px;padding:2px 10px;color:var(--green)" ' +
+  const modalVerifyWi = (window._lastWorkItems || []).find(w => w.itemType === 'verify' && w.sourcePlan === normalizedFile);
+  const modalVerifyBtn = isModalCompleted && !modalVerifyWi ? '<button class="pr-pager-btn" style="font-size:10px;padding:2px 10px;color:var(--green)" ' +
     'onclick="triggerVerify(\'' + escHtml(normalizedFile) + '\',this)">Verify</button>' : '';
+  const modalVerifyInfo = modalVerifyWi ? _renderVerifyBadge(modalVerifyWi) : '';
   const modalArchiveBtn = '<button class="pr-pager-btn" style="font-size:10px;padding:2px 10px;color:var(--muted)" ' +
     'onclick="planArchive(\'' + escHtml(normalizedFile) + '\')">Archive</button>';
   const lastModLabel = lastMod ? '<div style="font-size:10px;color:var(--muted);font-weight:400;margin-top:2px">Last updated: ' + new Date(lastMod).toLocaleString() + '</div>' : '';
   const actionBtns = '<div style="display:flex;gap:4px;flex-wrap:wrap;margin-top:4px">' +
-    (modalCompletedLabel || '') + (modalInProgressLabel || '') + (modalExecuteBtn || '') + (modalPauseBtn || '') + (modalResumeBtn || '') + (modalVerifyBtn || '') +
+    (modalCompletedLabel || '') + (modalInProgressLabel || '') + (modalExecuteBtn || '') + (modalPauseBtn || '') + (modalResumeBtn || '') + (modalVerifyBtn || '') + (modalVerifyInfo || '') +
     ' ' + modalArchiveBtn +
     ' <button class="pr-pager-btn" style="font-size:10px;padding:2px 10px;color:var(--red)" ' +
     'onclick="planDelete(\'' + escHtml(normalizedFile) + '\')">Delete</button>' +
@@ -664,6 +668,17 @@ async function planRegeneratePRD(source) {
   } catch (e) { alert('Error: ' + e.message); }
 }
 
+function _renderVerifyBadge(verifyWi) {
+  const statusColors = { pending: 'var(--muted)', dispatched: 'var(--blue)', done: 'var(--green)', failed: 'var(--red)' };
+  const color = statusColors[verifyWi.status] || 'var(--muted)';
+  const label = verifyWi.status === 'dispatched' ? 'Verifying...' : verifyWi.status === 'done' ? 'Verified' : verifyWi.status === 'failed' ? 'Verify failed' : 'Verify pending';
+  const allPrs = (window._lastStatus?.pullRequests) || [];
+  const verifyPr = allPrs.find(pr => (pr.prdItems || []).includes(verifyWi.id));
+  const prLink = verifyPr?.url ? ' <a href="' + escHtml(verifyPr.url) + '" target="_blank" onclick="event.stopPropagation()" style="color:var(--blue);text-decoration:none;font-size:9px">E2E PR</a>' : '';
+  const branchInfo = verifyPr?.branch ? ' <span style="font-size:8px;color:var(--muted)" title="' + escHtml(verifyPr.branch) + '">(' + escHtml(verifyPr.branch.slice(0, 25)) + ')</span>' : '';
+  return '<span style="font-size:9px;font-weight:600;color:' + color + ';padding:0 4px">' + label + '</span>' + prLink + branchInfo;
+}
+
 async function openVerifyGuide(file) {
   try {
     const normalizedFile = normalizePlanFile(file);

package/engine/ado.js

@@ -5,7 +5,7 @@
 
 const path = require('path');
 const shared = require('./shared');
-const { exec, getAdoOrgBase, log, dateStamp } = shared;
+const { exec, getAdoOrgBase, addPrLink, log, dateStamp } = shared;
 const { getPrs } = require('./queries');
 
 // Lazy require to avoid circular dependency — only needed for engine().handlePostMerge
@@ -29,7 +29,7 @@ function getAdoToken() {
   try {
     // azureauth supports multiple --mode flags as an ordered fallback chain:
     // tries IWA (Integrated Windows Auth) first, falls back to broker if unavailable.
-    const token = exec('azureauth ado token --mode broker --mode iwa --output token --timeout 5', {
+    const token = exec('azureauth ado token --mode iwa --mode broker --output token --timeout 1', {
       timeout: 15000, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true    }).trim();
     if (token && token.startsWith('eyJ')) {
       _adoTokenCache = { token, expiresAt: Date.now() + 30 * 60 * 1000 };
@@ -46,20 +46,9 @@ function getAdoToken() {
 
 async function adoFetch(url, token, _retryCount = 0) {
   const MAX_RETRIES = 1;
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), 30000);
-  let res;
-  try {
-    res = await fetch(url, {
-      signal: controller.signal,
-      headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' }
-    });
-  } catch (err) {
-    clearTimeout(timer);
-    if (err.name === 'AbortError') throw new Error(`ADO API timeout (30s) for ${url.split('?')[0]}`);
-    throw err;
-  }
-  clearTimeout(timer);
+  const res = await fetch(url, {
+    headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' }
+  });
   if (!res.ok) throw new Error(`ADO API ${res.status}: ${res.statusText}`);
   const text = await res.text();
   if (!text || text.trimStart().startsWith('<')) {
@@ -366,8 +355,9 @@ async function reconcilePrs(config) {
       const confirmedItemId = linkedItem ? linkedItemId : null;
 
       if (existingIds.has(prId)) {
-        // PR already tracked — update prdItems if we can extract an ID
+        // PR already tracked — write link to pr-links.json if we can extract an ID
         if (confirmedItemId) {
+          addPrLink(prId, confirmedItemId);
           const existing = existingPrs.find(p => p.id === prId);
           if (existing && !(existing.prdItems || []).includes(confirmedItemId)) {
             existing.prdItems = Array.isArray(existing.prdItems) ? existing.prdItems : [];
@@ -390,12 +380,25 @@ async function reconcilePrs(config) {
         url: prUrl,
         prdItems: confirmedItemId ? [confirmedItemId] : [],
       });
+      if (confirmedItemId) addPrLink(prId, confirmedItemId);
       existingIds.add(prId);
       projectAdded++;
       log('info', `PR reconciliation: added ${prId} (branch: ${branch}${confirmedItemId ? ', linked to ' + confirmedItemId : ''}) to ${project.name}`);
     }
 
-    if (projectAdded > 0 || projectUpdated > 0) {
+    // Backfill prdItems from pr-links for any PR with empty array
+    const prLinks = shared.getPrLinks();
+    let backfilled = 0;
+    for (const pr of existingPrs) {
+      const linked = prLinks[pr.id];
+      if (linked && !(pr.prdItems || []).includes(linked)) {
+        pr.prdItems = Array.isArray(pr.prdItems) ? pr.prdItems : [];
+        pr.prdItems.push(linked);
+        backfilled++;
+      }
+    }
+
+    if (projectAdded > 0 || projectUpdated > 0 || backfilled > 0) {
       shared.safeWrite(prPath, existingPrs);
       totalAdded += projectAdded;
       if (projectUpdated > 0) log('info', `PR reconciliation: linked ${projectUpdated} existing PR(s) to PRD items in ${project.name}`);

package/engine/cooldown.js

@@ -7,12 +7,10 @@ const path = require('path');
 const shared = require('./shared');
 const queries = require('./queries');
 
-const { createHash } = require('crypto');
 const { safeJson, safeWrite, log } = shared;
 const { ENGINE_DIR } = queries;
 
 const COOLDOWN_PATH = path.join(ENGINE_DIR, 'cooldowns.json');
-const PENDING_CONTEXTS_CAP = 10;
 const dispatchCooldowns = new Map(); // key → { timestamp, failures }
 
 function loadCooldowns() {
@@ -26,35 +24,6 @@ function loadCooldowns() {
     }
   }
   log('info', `Loaded ${dispatchCooldowns.size} cooldowns from disk`);
-  // One-time purge of bloated pendingContexts on startup
-  purgeBloatedCooldowns();
-}
-
-/** Deduplicate and cap pendingContexts in all loaded cooldown entries. */
-function purgeBloatedCooldowns() {
-  let totalRemoved = 0;
-  for (const [k, v] of dispatchCooldowns) {
-    if (!Array.isArray(v.pendingContexts) || v.pendingContexts.length <= 1) continue;
-    const seen = new Set();
-    const deduped = [];
-    for (const ctx of v.pendingContexts) {
-      const hash = _contentHash(ctx);
-      if (!seen.has(hash)) {
-        seen.add(hash);
-        deduped.push(ctx);
-      }
-    }
-    const before = v.pendingContexts.length;
-    // Apply FIFO cap after dedup — keep the most recent entries
-    v.pendingContexts = deduped.length > PENDING_CONTEXTS_CAP
-      ? deduped.slice(deduped.length - PENDING_CONTEXTS_CAP)
-      : deduped;
-    totalRemoved += before - v.pendingContexts.length;
-  }
-  if (totalRemoved > 0) {
-    log('info', `Purged ${totalRemoved} duplicate/excess pendingContexts entries from cooldowns`);
-    saveCooldowns();
-  }
 }
 
 let _cooldownWriteTimer = null;
@@ -86,26 +55,10 @@ function setCooldown(key) {
   saveCooldowns();
 }
 
-function _contentHash(content) {
-  const str = typeof content === 'string' ? content : JSON.stringify(content);
-  return createHash('sha256').update(str).digest('hex');
-}
-
 function setCooldownWithContext(key, context) {
   const existing = dispatchCooldowns.get(key);
   const pendingContexts = existing?.pendingContexts || [];
-  if (context) {
-    // Dedup: only append if content differs from all existing entries
-    const newHash = _contentHash(context);
-    const isDuplicate = pendingContexts.some(c => _contentHash(c) === newHash);
-    if (!isDuplicate) {
-      pendingContexts.push(context);
-      // FIFO cap: drop oldest entries when exceeding cap
-      while (pendingContexts.length > PENDING_CONTEXTS_CAP) {
-        pendingContexts.shift();
-      }
-    }
-  }
+  if (context) pendingContexts.push(context);
   dispatchCooldowns.set(key, {
     timestamp: Date.now(),
     failures: existing?.failures || 0,
@@ -148,16 +101,13 @@ function isAlreadyDispatched(key) {
 
 module.exports = {
   COOLDOWN_PATH,
-  PENDING_CONTEXTS_CAP,
   dispatchCooldowns,
   loadCooldowns,
   saveCooldowns,
-  purgeBloatedCooldowns,
   isOnCooldown,
   setCooldown,
   setCooldownWithContext,
   getCoalescedContexts,
   setCooldownFailure,
   isAlreadyDispatched,
-  _contentHash,
 };

package/engine/github.js

@@ -5,7 +5,7 @@
  */
 
 const shared = require('./shared');
-const { exec, getProjects, projectPrPath, projectWorkItemsPath, safeJson, safeWrite, MINIONS_DIR, log, dateStamp } = shared;
+const { exec, getProjects, projectPrPath, projectWorkItemsPath, safeJson, safeWrite, MINIONS_DIR, addPrLink, getPrLinks, log, dateStamp } = shared;
 const { getPrs } = require('./queries');
 const path = require('path');
 
@@ -341,6 +341,7 @@ async function reconcilePrs(config) {
 
       if (existingIds.has(prId)) {
         if (confirmedItemId) {
+          addPrLink(prId, confirmedItemId);
           const existing = existingPrs.find(p => p.id === prId);
           if (existing && !(existing.prdItems || []).includes(confirmedItemId)) {
             existing.prdItems = Array.isArray(existing.prdItems) ? existing.prdItems : [];
@@ -363,13 +364,26 @@ async function reconcilePrs(config) {
         url: prUrl,
         prdItems: confirmedItemId ? [confirmedItemId] : [],
       });
+      if (confirmedItemId) addPrLink(prId, confirmedItemId);
       existingIds.add(prId);
       projectAdded++;
 
       log('info', `GitHub PR reconciliation: added ${prId} (branch: ${branch}${confirmedItemId ? ', linked to ' + confirmedItemId : ''}) to ${project.name}`);
     }
 
-    if (projectAdded > 0) {
+    // Backfill prdItems from pr-links for any PR with empty array
+    const prLinks = getPrLinks();
+    let backfilled = 0;
+    for (const pr of existingPrs) {
+      const linked = prLinks[pr.id];
+      if (linked && !(pr.prdItems || []).includes(linked)) {
+        pr.prdItems = Array.isArray(pr.prdItems) ? pr.prdItems : [];
+        pr.prdItems.push(linked);
+        backfilled++;
+      }
+    }
+
+    if (projectAdded > 0 || backfilled > 0) {
       safeWrite(prPath, existingPrs);
       totalAdded += projectAdded;
     }

package/engine/lifecycle.js

@@ -148,7 +148,10 @@ function checkPlanCompletion(meta, config) {
   // existingPrItem/existingVerify guards, so the flag does NOT block crash recovery of those.
   plan._completionNotified = true;
   mutateJsonFileLocked(planPath, (data) => {
+    data.status = 'completed';
+    data.completedAt = plan.completedAt;
     data._completionNotified = true;
+    if (plan._timing) data._timing = plan._timing;
     return data;
   });
 
@@ -227,9 +230,10 @@ function checkPlanCompletion(meta, config) {
     ).join('\n');
 
     // List projects and their worktree paths for the agent
-    const projectWorktrees = Object.entries(projectPrs).map(([name, { project: p }]) =>
-      `- **${name}**: \`${p.localPath}/../worktrees/verify-${planSlug}\``
-    ).join('\n');
+    const projectWorktrees = Object.entries(projectPrs).map(([name, { project: p }]) => {
+      const lp = p.localPath.replace(/\\/g, '/');
+      return `- **${name}**: see setup commands below (\`${lp}/../worktrees/verify-${name}-${planSlug}-*\`)`;
+    }).join('\n');
 
     const description = [
       `Verification task for completed plan \`${planFile}\`.`,
@@ -274,19 +278,30 @@ function checkPlanCompletion(meta, config) {
     log('info', `Created verification work item ${verifyId} for plan ${planFile}`);
   }
 
-  // 5. Archive: move PRD .json to prd/archive/ and source .md plan to plans/archive/
+  // 5. Archive deferred until verify completes (see runPostCompletionHooks).
+  //    Plan stays active until verification finishes so artifacts are visible.
+
+  log('info', `PRD ${planFile} completed: ${doneItems.length} done, ${failedItems.length} failed, runtime ${runtimeMin}m`);
+}
+
+// ─── Plan Archiving (called after verify completes) ─────────────────────────
+
+function archivePlan(planFile, plan, projects, config) {
+  const planPath = path.join(PRD_DIR, planFile);
+  const projectName = plan.project || '';
+
+  // Archive PRD .json to prd/archive/
   const prdArchiveDir = path.join(PRD_DIR, 'archive');
   if (!fs.existsSync(prdArchiveDir)) fs.mkdirSync(prdArchiveDir, { recursive: true });
-  shared.safeWrite(planPath, plan); // save completed status first
-  try {
-    fs.renameSync(planPath, path.join(prdArchiveDir, planFile));
-    log('info', `Archived completed PRD: prd/archive/${planFile}`);
-  } catch (err) {
-    log('warn', `Failed to archive PRD ${planFile}: ${err.message}`);
+  if (fs.existsSync(planPath)) {
     shared.safeWrite(planPath, plan);
+    try {
+      fs.renameSync(planPath, path.join(prdArchiveDir, planFile));
+      log('info', `Archived completed PRD: prd/archive/${planFile}`);
+    } catch (err) { log('warn', `Failed to archive PRD ${planFile}: ${err.message}`); }
   }
 
-  // Also archive the source .md plan if it exists (use source_plan field, not content matching)
+  // Archive the source .md plan
   const planArchiveDir = path.join(PLANS_DIR, 'archive');
   if (!fs.existsSync(planArchiveDir)) fs.mkdirSync(planArchiveDir, { recursive: true });
   if (plan.source_plan) {
@@ -298,7 +313,6 @@ function checkPlanCompletion(meta, config) {
       } catch (err) { log('warn', `Failed to archive source plan ${plan.source_plan}: ${err.message}`); }
     }
   } else {
-    // Fallback: scan for matching .md files (legacy PRDs without source_plan)
     try {
       const mdFiles = fs.readdirSync(PLANS_DIR).filter(f => f.endsWith('.md'));
       for (const md of mdFiles) {
@@ -314,16 +328,25 @@ function checkPlanCompletion(meta, config) {
     } catch (err) { log('warn', `Plan archive scan: ${err.message}`); }
   }
 
-  // 6. Clean up ALL worktrees created for this plan's work items (shared-branch + per-item)
+  // Clean up ALL worktrees created for this plan's work items (shared-branch + per-item)
   try {
-    // Collect all branch slugs: shared-branch + per-item branches + item IDs
+    let allWi = [];
+    for (const p of projects) {
+      try { allWi = allWi.concat(safeJson(shared.projectWorkItemsPath(p)) || []); } catch {}
+    }
+    const planWi = allWi.filter(w => w.sourcePlan === planFile && w.itemType !== 'verify');
+    const allPrs = [];
+    for (const p of projects) {
+      try { allPrs.push(...(safeJson(shared.projectPrPath(p)) || [])); } catch {}
+    }
+
     const branchSlugs = new Set();
     if (plan.feature_branch) branchSlugs.add(shared.sanitizeBranch(plan.feature_branch).toLowerCase());
-    for (const w of doneItems) {
+    for (const w of planWi) {
       if (w.branch) branchSlugs.add(shared.sanitizeBranch(w.branch).toLowerCase());
       if (w.id) branchSlugs.add(w.id.toLowerCase());
     }
-    for (const pr of uniquePrs) {
+    for (const pr of allPrs.filter(pr => (pr.prdItems || []).some(id => planWi.find(w => w.id === id)))) {
       if (pr.branch) branchSlugs.add(shared.sanitizeBranch(pr.branch).toLowerCase());
     }
 
@@ -345,10 +368,8 @@ function checkPlanCompletion(meta, config) {
         }
       }
     }
-    if (cleanedWt > 0) log('info', `Plan completion: cleaned ${cleanedWt} worktree(s)`);
+    if (cleanedWt > 0) log('info', `Plan archive: cleaned ${cleanedWt} worktree(s)`);
   } catch (err) { log('warn', `Worktree cleanup: ${err.message}`); }
-
-  log('info', `PRD ${planFile} completed: ${doneItems.length} done, ${failedItems.length} failed, runtime ${runtimeMin}m`);
 }
 
 // ─── Plan → PRD Chaining ─────────────────────────────────────────────────────
@@ -1424,6 +1445,19 @@ function runPostCompletionHooks(dispatchItem, agentId, code, stdout, config) {
   let prsCreatedCount = 0;
   if (isSuccess) prsCreatedCount = syncPrsFromOutput(stdout, agentId, meta, config) || 0;
 
+  // Archive plan after verify task completes (AFTER PR sync so E2E PR is linked)
+  if (meta?.item?.itemType === 'verify' && meta?.item?.sourcePlan) {
+    try {
+      const vPlanFile = meta.item.sourcePlan;
+      const vPlanPath = path.join(PRD_DIR, vPlanFile);
+      const vPlan = safeJson(vPlanPath);
+      if (vPlan) {
+        const vProjects = shared.getProjects(config);
+        archivePlan(vPlanFile, vPlan, vProjects, config);
+      }
+    } catch (err) { log('warn', `Verify archive: ${err.message}`); }
+  }
+
   // Clean up worktree for non-shared-branch tasks after completion
   if (meta?.branch && meta?.branchStrategy !== 'shared-branch') {
     try {
@@ -1551,6 +1585,7 @@ function syncPrdFromPrs(config) {
 
 module.exports = {
   checkPlanCompletion,
+  archivePlan,
   updateWorkItemStatus,
   syncPrdItemStatus,
   syncPrsFromOutput,

package/engine/pipeline.js

@@ -175,6 +175,7 @@ function executeTaskStage(stage, stageState, run, config) {
       status: 'pending',
       created: ts(),
       createdBy: 'pipeline:' + run.pipelineId,
+      branch: `pipeline/${run.pipelineId}/${stage.id}`,
       _pipelineRun: run.runId,
       _pipelineStage: stage.id,
     });
@@ -248,6 +249,7 @@ function executePlanStage(stage, stageState, run, config) {
       planFile: path.basename(filePath),
       created: ts(),
       createdBy: 'pipeline:' + run.pipelineId,
+      branch: `pipeline/${run.pipelineId}/${stage.id}`,
       _pipelineRun: run.runId,
       _pipelineStage: stage.id,
     });

package/engine/playbook.js

@@ -206,25 +206,9 @@ 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 {
@@ -296,12 +280,9 @@ function renderPlaybook(type, vars) {
   };
   const allVars = { ...projectVars, ...vars };
 
-  // Substitute variables — two passes to resolve nested templates
-  // (e.g. pr_section contains {{pr_create_instructions}}, {{branch_name}}, etc.)
-  for (let pass = 0; pass < 2; pass++) {
-    for (const [key, val] of Object.entries(allVars)) {
-      content = content.replace(new RegExp(`\\{\\{${key}\\}\\}`, 'g'), String(val));
-    }
+  // Substitute variables
+  for (const [key, val] of Object.entries(allVars)) {
+    content = content.replace(new RegExp(`\\{\\{${key}\\}\\}`, 'g'), String(val));
   }
 
   // Warn on variables that resolved to empty string
@@ -318,20 +299,6 @@ 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;
 }
 
@@ -503,8 +470,6 @@ function buildPrDispatch(agentId, config, project, pr, type, extraVars, taskLabe
 
 module.exports = {
   renderPlaybook,
-  getLastRenderError,
-  CRITICAL_VARS,
   buildSystemPrompt,
   buildAgentContext,
   selectPlaybook,

package/engine/routing.js

@@ -136,7 +136,7 @@ function resolveAgent(workType, config, authorAgent = null) {
   if (config.engine?.allowTempAgents) {
     const tempId = `temp-${shared.uid()}`;
     _claimedAgents.add(tempId);
-    tempAgents.set(tempId, { name: `Temp-${tempId.slice(5, 13)}`, role: 'Temporary Agent', createdAt: ts() });
+    tempAgents.set(tempId, { name: `Temp-${tempId.slice(5, 9)}`, role: 'Temporary Agent', createdAt: ts() });
     log('info', `Spawning temp agent ${tempId} — all permanent agents busy`);
     return tempId;
   }

package/engine.js

@@ -290,10 +290,9 @@ function spawnAgent(dispatchItem, config) {
       log('info', `Reusing existing worktree for ${branchName}: ${existingWt}`);
       try { exec(`git fetch origin "${branchName}"`, { ..._gitOpts, cwd: rootDir }); } catch (e) { log('warn', 'git: ' + e.message); }
       try { exec(`git pull origin "${branchName}"`, { ..._gitOpts, cwd: existingWt }); } catch (e) { log('warn', 'git: ' + e.message); }
-    } else if (type !== 'implement') {
-      // Only implement tasks may create new worktrees.
-      // Other task types are reuse-only: if no existing worktree, run in rootDir.
-      log('info', `${type}: no existing worktree for ${branchName} — creation disabled for non-implement tasks, falling back to rootDir`);
+    } else if (['meeting', 'ask', 'explore'].includes(type)) {
+      // Read-only tasks — no worktree needed, run in rootDir
+      log('info', `${type}: read-only task, no worktree needed — running in rootDir`);
       branchName = null;
       worktreePath = null;
     } else {
@@ -423,6 +422,11 @@ function spawnAgent(dispatchItem, config) {
   const systemPrompt = buildSystemPrompt(agentId, config, project);
   const agentContext = buildAgentContext(agentId, config, project);
 
+  // Safety check: warn if a write-capable task is running in the main repo without a worktree
+  if (cwd === rootDir && ['implement', 'implement:large', 'fix', 'test', 'verify', 'plan-to-prd'].includes(type)) {
+    log('warn', `Agent ${agentId} running ${type} task in main repo (no worktree) for ${id} — changes may land on master directly`);
+  }
+
   // Prepend bulk context to task prompt — keeps system prompt small and stable
   const fullTaskPrompt = agentContext
     ? `## Agent Context\n\n${agentContext}\n---\n\n## Your Task\n\n${taskPrompt}`
@@ -1457,6 +1461,8 @@ function discoverFromWorkItems(config, project) {
       task_description: item.title + (item.description ? '\n\n' + item.description : ''),
       task_id: item.id,
       work_type: workType,
+      source_plan: item.sourcePlan || '',
+      plan_slug: (item.sourcePlan || '').replace('.json', ''),
       additional_context: item.prompt ? `## Additional Context\n\n${item.prompt}` : '',
       scope_section: `## Scope: Project — ${project?.name || 'default'}\n\nThis task is scoped to a single project.`,
       branch_name: branchName,
@@ -1475,6 +1481,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 : '');
@@ -1798,6 +1836,7 @@ function discoverCentralWorkItems(config) {
           prompt,
           meta: {
             dispatchKey: fanKey, source: 'central-work-item-fanout', item, parentKey: key,
+            branch: `fan/${item.id}/${fanAgentId}`,
             deadline: item.timeout ? Date.now() + item.timeout : Date.now() + (config.engine?.fanOutTimeout || config.engine?.agentTimeout || DEFAULTS.agentTimeout)
           }
         });
@@ -1845,6 +1884,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
@@ -1909,7 +1981,7 @@ function discoverCentralWorkItems(config) {
         agentRole,
         task: item.title || item.description?.slice(0, 80) || item.id,
         prompt,
-        meta: { dispatchKey: key, source: 'central-work-item', item, planFileName: item.planFile || item._planFileName || null }
+        meta: { dispatchKey: key, source: 'central-work-item', item, planFileName: item.planFile || item._planFileName || null, branch: item.branch || item.featureBranch || `work/${item.id}` }
       });
 
       item.status = 'dispatched';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.289",
+  "version": "0.1.291",
   "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/verify.md

@@ -13,11 +13,14 @@ Repo: {{repo_name}} | Org: {{ado_org}} | ADO Project: {{ado_project}}
 
 ## Your Task
 
-Build, test, and verify a set of related changes. Your job is to:
-1. **Set up one worktree per project** with all PR branches merged in
-2. **Build and test** from each worktree
-3. **Start the webapp** on localhost (keep it running — **detached so it survives after your process exits**)
-4. **Write a manual testing guide**
+Verify that a set of related changes work correctly together. You must **figure out** how to build, test, and run this specific project — do not assume any particular language, framework, or tooling. Your job is to:
+
+1. **Set up worktrees** with all PR branches merged
+2. **Understand the project** — read its docs to learn how to build, test, and run it
+3. **Build and test** from each worktree
+4. **Start the application** if applicable (keep it running detached)
+5. **Write a transparent verification report and testing guide**
+6. **Create E2E pull requests**
 
 ## Step 1: Set Up Worktrees
 
@@ -29,100 +32,130 @@ If any merge conflicts occur:
 
 After setup, all changes for a project are in a single directory — no switching between branches.
 
-## Step 2: Build Each Project
+## Step 2: Understand the Project
 
-For each project worktree listed above:
-1. `cd` into the worktree path
-2. Read its CLAUDE.md / package.json / README for build instructions
-3. Install dependencies (`yarn install`, `npm install`, etc.)
-4. Run the build (`yarn build`, `npm run build`, etc.)
-5. Record: PASS or FAIL with error output
+For each project worktree, **read its documentation** to understand:
+- What language/framework it uses
+- How to install dependencies
+- How to build it
+- How to run tests
+- How to start it (if it has a runnable application)
+
+Check these files: `CLAUDE.md`, `README.md`, `package.json`, `Makefile`, `Cargo.toml`, `pyproject.toml`, `build.gradle`, `CMakeLists.txt`, `docker-compose.yml`, `Podfile`, `build.gradle.kts`, `*.xcodeproj`, `*.xcworkspace`, or whatever build system the project uses.
 
-If a build fails, **do NOT fix it** — report the error and continue with other projects.
+**Do not assume any specific platform.** The project could be a web app, mobile app (Android/iOS/React Native/Flutter), backend service, CLI tool, library, monorepo, or anything else. Adapt your verification approach to what the project actually is.
 
-## Step 3: Run Tests
+## Step 3: Build and Test
+
+For each project worktree:
+1. `cd` into the worktree path
+2. Install dependencies using whatever the project requires
+3. Run the build using the project's build system
+4. Run the test suite
+5. Record: PASS or FAIL with error output, test counts (passed/failed/skipped)
 
-For each project that built successfully:
-1. Run the test suite from the worktree
-2. Record passed/failed/skipped counts
+If a build or test fails, **do NOT fix it** — report the exact error and continue with other projects.
 
-## Step 4: Start the Webapp
+## Step 4: Start the Application (if applicable)
 
-Determine which project is the **user-facing webapp** (has a dev server, UI):
-- Check for `dev`, `start`, `serve` scripts in package.json
-- Look for web frameworks (React, Next.js, TanStack, Vite, etc.)
+Determine if the project has a **runnable application** (web server, API, desktop app, mobile emulator, etc.) by reading its documentation and build config. For mobile apps, check if an emulator/simulator can be launched or if building an APK/IPA is the appropriate verification step.
 
 If found:
-1. Start the dev server **detached from your process** so it survives after you exit:
+1. Start it **detached from your process** so it survives after you exit. Use the platform-appropriate method:
    ```bash
    cd <worktree-path>
-   node -e "
-   const { spawn } = require('child_process');
-   const fs = require('fs');
-   const child = spawn('cmd', ['/c', '<start-command>'], {
-     cwd: process.cwd(),
-     detached: true,
-     stdio: ['ignore', fs.openSync('dev-server.log', 'w'), fs.openSync('dev-server.log', 'w')]
-   });
-   child.unref();
-   fs.writeFileSync('dev-server.pid', String(child.pid));
-   console.log('Server started, PID:', child.pid);
-   "
+   nohup <start-command> > app-server.log 2>&1 &
+   echo $! > app-server.pid
    ```
-2. Wait a few seconds, then verify it's responding: `curl -s -o /dev/null -w "%{http_code}" http://localhost:<PORT>`
-3. Note the localhost URL, port, and PID
+   On Windows, use `spawn` with `detached: true` and `child.unref()`.
+
+2. Wait a few seconds, then verify it's responding (e.g. `curl -s -o /dev/null -w "%{http_code}" http://localhost:<PORT>`)
+3. Note the URL, port, and PID
 4. Output the exact restart command with **absolute worktree paths**
-5. Include stop command: `taskkill //PID <PID> //F`
+5. Include the stop command (e.g. `kill <PID>` or `taskkill /PID <PID> /F` on Windows)
+
+If the project has no runnable application, skip this step and note that in the guide.
+
+## Step 5: Write the Verification Report and Testing Guide
 
-## Step 5: Write the Manual Testing Guide
+Create the guide in TWO locations:
+1. **Permanent location** (linked from dashboard): `{{team_root}}/prd/guides/verify-{{plan_slug}}.md`
+2. **Inbox copy** (for team consolidation): `{{team_root}}/notes/inbox/verify-{{plan_slug}}.md`
 
-Create the testing guide in TWO locations:
-1. **Permanent location** (linked from dashboard): `{{team_root}}/prd/guides/verify-{{date}}.md`
-2. **Inbox copy** (for team consolidation): `{{team_root}}/notes/inbox/verify-{{date}}.md`
+**Be transparent.** The guide must clearly state what was built, what was tested, what passed, what failed, and what still needs human verification.
 
 Structure:
 
 ```markdown
-# Manual Testing Guide
+# Verification Report & Testing Guide
 
 **Date:** {{date}}
-**Plan:** <plan file>
-**Local Server:** http://localhost:XXXX (or N/A)
-**Restart Command:** `cd <absolute-worktree-path> && <command>`
+**Plan:** {{source_plan}}
+**Verified by:** {{agent_name}}
+
+## What Was Built
+
+For each completed plan item, summarize:
+- **Item ID:** what it implements
+- **Key changes:** files modified, features added, behaviors changed
+- **PR:** link to the individual PR
 
-## Build Status
+## Verification Results
+
+### Build Status
 
 | Project | Worktree Path | Build | Tests | Notes |
 |---------|--------------|-------|-------|-------|
-| name | path | PASS/FAIL | X pass, Y fail | notes |
+| name | path | PASS/FAIL | X pass, Y fail, Z skip | error details if any |
+
+### Automated Test Results
+- Total: X passed, Y failed, Z skipped
+- Notable failures: (list any, with error messages)
+- Test coverage notes: (are the new features covered by tests?)
+
+### What Was Verified
+For each plan item, state what you actually checked:
+- Did the build pass with this change included?
+- Did existing tests pass?
+- Were there new tests for the new functionality?
+- Any runtime errors observed?
+
+### What Could NOT Be Verified Automatically
+List anything that requires human judgment:
+- UI/UX changes that need visual inspection
+- Behaviors that depend on external services
+- Performance characteristics
+- Edge cases not covered by tests
+
+## Manual Testing Guide
 
-## What to Test
+**How to run:** (server URL, emulator command, APK path, or N/A)
+**Restart Command:** `cd <absolute-worktree-path> && <command>` (if applicable)
 
 ### <Feature Name> (Plan Item ID)
 **What changed:** brief description
 **How to test:**
-1. Navigate to http://localhost:XXXX/path
-2. Click on / interact with ...
-3. You should see ...
+1. Step-by-step instructions
+2. With concrete actions (URLs, buttons, inputs)
+3. And expected outcomes
 
-**Expected behavior:**
-- (from acceptance criteria)
-- (from acceptance criteria)
+**Acceptance criteria check:**
+- [ ] (from plan item acceptance criteria)
+- [ ] (from plan item acceptance criteria)
 
 ### <Next Feature> ...
 
 ## Integration Points
 
-Cross-project interactions to verify:
-- e.g., "Bebop sends message via AugLoop → OfficeAgent receives and responds"
-- e.g., "Progression UI updates in real-time as WebSocket messages arrive"
+Cross-project or cross-feature interactions to verify:
+- e.g., "Service A calls Service B — verify the API contract"
 
 ## Known Issues
 - Build warnings, test failures, merge conflicts, unimplemented items
 
 ## Quick Smoke Test
 A minimal 5-step checklist to verify the core functionality:
-1. Open http://localhost:XXXX
+1. ...
 2. ...
 3. ...
 4. ...
@@ -131,24 +164,24 @@ A minimal 5-step checklist to verify the core functionality:
 
 ## Step 6: Create E2E Pull Requests
 
-For each project that has changes, create a single **aggregate PR** that combines all the plan's branches into one. This gives the human reviewer a single diff showing the full picture of everything built.
+For each project that has changes, create a single **aggregate PR** that combines all the plan's branches into one. This gives the human reviewer a single diff showing the full picture.
 
 For each project worktree:
 
-1. You're already in the worktree with all branches merged. Push this combined branch:
+1. Push the combined branch:
    ```bash
    cd <worktree-path>
-   git checkout -b e2e/<plan-slug>
-   git push origin e2e/<plan-slug>
+   git checkout -b e2e/{{plan_slug}}
+   git push origin e2e/{{plan_slug}}
    ```
 
 2. Create a PR targeting the project's main branch using `mcp__azure-ado__repo_create_pull_request` (or `gh pr create` for GitHub):
    - **Title:** `[E2E] <plan summary>`
    - **Description:** Include:
      - The plan summary
-     - List of all individual PRs that are merged into this branch
-     - The testing guide (copy from Step 5)
-     - Build/test status from Step 2-3
+     - List of all individual PRs merged into this branch
+     - Build/test status from Step 3
+     - Link to the testing guide
    - **Target branch:** the project's main branch (e.g., `main` or `master`)
    - **Do NOT auto-complete** — this is for review only
    - **Mark as draft** if the option is available
@@ -163,7 +196,7 @@ For each project worktree:
      id: 'PR-<number>',
      title: '[E2E] <plan summary>',
      agent: '{{agent_name}}',
-     branch: 'e2e/<plan-slug>',
+     branch: 'e2e/{{plan_slug}}',
      reviewStatus: 'pending',
      status: 'active',
      created: new Date().toISOString().slice(0,10),
@@ -178,12 +211,14 @@ For each project worktree:
 
 ## Rules
 
+- **Read the project docs first** — never assume a build system, language, or framework
 - Base testing steps on the **acceptance criteria** from each plan item
-- Include **concrete steps** — URLs, buttons to click, inputs to type, expected visual results
+- Include **concrete steps** — URLs, buttons to click, inputs to type, expected results
+- Be **transparent** — clearly separate what you verified vs what needs human review
 - If a project doesn't build, still document what SHOULD be testable once fixed
 - Do NOT fix code — only report issues
 - Leave all worktrees in place for the user to inspect
-- The local server MUST be started **detached** (using `spawn` with `detached: true` + `child.unref()`) so it keeps running after your process exits. Save the PID to `dev-server.pid` in the worktree.
+- The application MUST be started **detached** so it keeps running after your process exits
 - Use absolute paths everywhere so the user can copy-paste commands
 - E2E PRs are for review only — do NOT auto-complete or merge them