@yemi33/minions 0.1.290 → 0.1.292

package/CHANGELOG.md

@@ -1,11 +1,15 @@
 # Changelog
 
-## 0.1.290 (2026-04-03)
+## 0.1.292 (2026-04-03)
 
 ### Features
+- harden shared.js — backup verification, lock TOCTOU, docs
 -  all doc-chats use Sonnet with full tools (agent change)
 
 ### Fixes
+-  add behavioral tests for CRITICAL propagation and stale lock ENOENT
+-  CRITICAL errors in safeJson now propagate to callers
+-  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

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/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/shared.js

@@ -52,14 +52,37 @@ function safeJson(p) {
       const backupData = JSON.parse(fs.readFileSync(backupPath, 'utf8'));
       // Backup is valid — restore it to the primary file (atomic via safeWrite)
       console.log(`[safeJson] restored ${path.basename(p)} from .backup sidecar`);
-      try { safeWrite(p, backupData); } catch { /* best-effort restore */ }
+      try {
+        safeWrite(p, backupData);
+        // Verify the restored file matches expected content
+        const verifyData = JSON.parse(fs.readFileSync(p, 'utf8'));
+        if (JSON.stringify(verifyData) !== JSON.stringify(backupData)) {
+          const errMsg = `[safeJson] CRITICAL: backup restore verification failed for ${p} — written data does not match backup`;
+          console.error(errMsg);
+          throw new Error(errMsg);
+        }
+      } catch (restoreErr) {
+        // Re-throw CRITICAL errors so they propagate to callers
+        if (restoreErr.message && restoreErr.message.includes('CRITICAL')) throw restoreErr;
+        const errMsg = `[safeJson] CRITICAL: backup restore failed for ${p}: ${restoreErr.message}`;
+        console.error(errMsg);
+        throw new Error(errMsg);
+      }
       return backupData;
-    } catch {
+    } catch (outerErr) {
+      // Let CRITICAL errors propagate — callers must know about data integrity failures
+      if (outerErr.message && outerErr.message.includes('CRITICAL')) throw outerErr;
       return null;
     }
   }
 }
 
+/**
+ * Monotonic counter for generating unique temp file names within this process.
+ * Assumes single-thread execution (no worker_threads). If worker_threads are
+ * introduced, this must be replaced with an atomic or thread-safe counter to
+ * avoid temp file name collisions.
+ */
 let _tmpCounter = 0;
 
 function safeWrite(p, data) {
@@ -129,10 +152,19 @@ function withFileLock(lockPath, fn, {
       try {
         const stat = fs.statSync(lockPath);
         if (Date.now() - stat.mtimeMs > LOCK_STALE_MS) {
-          try { fs.unlinkSync(lockPath); } catch { /* race: another process removed it */ }
-          continue; // retry immediately after removing stale lock
+          try {
+            fs.unlinkSync(lockPath);
+          } catch (unlinkErr) {
+            // ENOENT: another process deleted the lock between stat and unlink — safe to retry
+            if (unlinkErr.code !== 'ENOENT') throw unlinkErr;
+          }
+          sleepMs(retryDelayMs); // avoid busy-loop on contention
+          continue;
         }
-      } catch { /* lock file disappeared between EEXIST and stat — retry will succeed */ }
+      } catch (staleErr) {
+        // ENOENT from statSync: lock file disappeared between EEXIST and stat — retry will succeed
+        if (staleErr.code !== 'ENOENT') throw staleErr;
+      }
       sleepMs(retryDelayMs);
     }
   }

package/engine.js

@@ -1461,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,

package/package.json

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