@yemi33/minions 0.1.1679 → 0.1.1681

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.1.1681 (2026-05-02)
+
+### Features
+-  plan completion lifecycle audit fixes (#1982)
+
+## 0.1.1680 (2026-05-02)
+
+### Other
+- Improve agent playbook accuracy
+
 ## 0.1.1679 (2026-05-02)
 
 ### Fixes

package/dashboard.js

@@ -2309,12 +2309,14 @@ const server = http.createServer(async (req, res) => {
       // If archived, temporarily restore to active so checkPlanCompletion can find it
       const activePath = path.join(prdDir, body.file);
       if (fromArchive) {
-        const plan = safeJson(prdPath);
-        if (!plan) return jsonReply(res, 500, { error: 'Could not parse PRD file' });
-        plan.status = 'approved';
-        delete plan.completedAt;
-        delete plan.planStale;
-        safeWrite(activePath, plan);
+        const archivedPlan = safeJson(prdPath);
+        if (!archivedPlan) return jsonReply(res, 500, { error: 'Could not parse PRD file' });
+        mutateJsonFileLocked(activePath, () => {
+          archivedPlan.status = 'approved';
+          delete archivedPlan.completedAt;
+          delete archivedPlan.planStale;
+          return archivedPlan;
+        }, { defaultValue: archivedPlan });
       }
 
       const config = queries.getConfig();
@@ -2347,11 +2349,10 @@ const server = http.createServer(async (req, res) => {
       }
 
       // No existing verify — clear completion flag and trigger fresh creation
-      const planData = safeJson(activePath);
-      if (planData?._completionNotified) {
-        planData._completionNotified = false;
-        safeWrite(activePath, planData);
-      }
+      mutateJsonFileLocked(activePath, (planData) => {
+        if (planData?._completionNotified) planData._completionNotified = false;
+        return planData;
+      }, { defaultValue: {}, skipWriteIfUnchanged: true });
 
       const lifecycle = require('./engine/lifecycle');
       lifecycle.checkPlanCompletion({ item: { sourcePlan: body.file, id: 'manual' } }, config);
@@ -3572,15 +3573,18 @@ const server = http.createServer(async (req, res) => {
       const body = await readBody(req);
       if (!body.file) return jsonReply(res, 400, { error: 'file required' });
       const planPath = resolvePlanPath(body.file);
-      const plan = safeJsonObj(planPath);
-      const wasStale = !!plan.planStale;
-      plan.status = 'approved';
-      plan.approvedAt = new Date().toISOString();
-      plan.approvedBy = body.approvedBy || os.userInfo().username;
-      delete plan.pausedAt;
-      delete plan.planStale;
-      delete plan._completionNotified;
-      safeWrite(planPath, plan);
+      let wasStale = false;
+      const plan = mutateJsonFileLocked(planPath, (data) => {
+        if (!data || Array.isArray(data) || typeof data !== 'object') data = {};
+        wasStale = !!data.planStale;
+        data.status = 'approved';
+        data.approvedAt = new Date().toISOString();
+        data.approvedBy = body.approvedBy || os.userInfo().username;
+        delete data.pausedAt;
+        delete data.planStale;
+        delete data._completionNotified;
+        return data;
+      }, { defaultValue: {} });
 
       // Resume paused work items across all projects
       let resumed = 0;
@@ -3662,10 +3666,12 @@ const server = http.createServer(async (req, res) => {
       const body = await readBody(req);
       if (!body.file) return jsonReply(res, 400, { error: 'file required' });
       const planPath = resolvePlanPath(body.file);
-      const plan = safeJsonObj(planPath);
-      plan.status = 'paused';
-      plan.pausedAt = new Date().toISOString();
-      safeWrite(planPath, plan);
+      mutateJsonFileLocked(planPath, (plan) => {
+        if (!plan || Array.isArray(plan) || typeof plan !== 'object') plan = {};
+        plan.status = 'paused';
+        plan.pausedAt = new Date().toISOString();
+        return plan;
+      }, { defaultValue: {} });
 
       // Propagate pause to materialized work items across all projects:
       // kill any active agent process and reset non-completed items to paused.
@@ -3799,12 +3805,14 @@ const server = http.createServer(async (req, res) => {
       const body = await readBody(req);
       if (!body.file) return jsonReply(res, 400, { error: 'file required' });
       const planPath = resolvePlanPath(body.file);
-      const plan = safeJsonObj(planPath);
-      plan.status = 'rejected';
-      plan.rejectedAt = new Date().toISOString();
-      plan.rejectedBy = body.rejectedBy || os.userInfo().username;
-      if (body.reason) plan.rejectionReason = body.reason;
-      safeWrite(planPath, plan);
+      const plan = mutateJsonFileLocked(planPath, (data) => {
+        if (!data || Array.isArray(data) || typeof data !== 'object') data = {};
+        data.status = 'rejected';
+        data.rejectedAt = new Date().toISOString();
+        data.rejectedBy = body.rejectedBy || os.userInfo().username;
+        if (body.reason) data.rejectionReason = body.reason;
+        return data;
+      }, { defaultValue: {} });
 
       // Teams notification for plan rejection — non-blocking
       try { teams.teamsNotifyPlanEvent({ name: plan.plan_summary || body.file, file: body.file }, 'plan-rejected').catch(() => {}); } catch {}
@@ -3956,18 +3964,23 @@ const server = http.createServer(async (req, res) => {
 
       let archivedSource = null;
       let plan = {};
+      const archiveWarnings = [];
       if (isPrd) {
         try {
-          plan = safeJsonObj(archivePath) || {};
-          plan.status = 'archived';
-          plan.archivedAt = new Date().toISOString();
-          safeWrite(archivePath, plan);
+          plan = mutateJsonFileLocked(archivePath, (data) => {
+            if (!data || Array.isArray(data) || typeof data !== 'object') data = {};
+            data.status = 'archived';
+            data.archivedAt = new Date().toISOString();
+            return data;
+          }, { defaultValue: {} }) || {};
           // Without removing the .backup sidecar, safeJson would auto-restore the
           // pre-completion snapshot on engine restart, re-triggering plan completion
           // and spawning duplicate verify tasks (regression of #f28162b0).
-          const backupPath = planPath + '.backup';
-          try { fs.unlinkSync(backupPath); } catch {
-            try { fs.writeFileSync(backupPath, JSON.stringify({ status: 'archived' })); } catch { /* best-effort */ }
+          const backupCleanup = shared.neutralizeJsonBackupSidecar(planPath);
+          if (!backupCleanup.ok) {
+            const warning = `Archive backup cleanup failed for ${body.file}: unlink failed (${backupCleanup.unlinkError}); fallback neutralize failed (${backupCleanup.writeError})`;
+            archiveWarnings.push(warning);
+            console.warn(warning);
           }
           if (plan.source_plan) {
             const mdPath = path.join(PLANS_DIR, plan.source_plan);
@@ -4006,7 +4019,9 @@ const server = http.createServer(async (req, res) => {
       } catch (e) { console.error('plan worktree cleanup:', e.message); }
 
       invalidateStatusCache();
-      return jsonReply(res, 200, { ok: true, archived: body.file, archivedSource, cancelledItems });
+      const payload = { ok: true, archived: body.file, archivedSource, cancelledItems };
+      if (archiveWarnings.length > 0) payload.warnings = archiveWarnings;
+      return jsonReply(res, 200, payload);
     } catch (e) { return jsonReply(res, 400, { error: e.message }); }
   }
 
@@ -4047,12 +4062,14 @@ const server = http.createServer(async (req, res) => {
       const body = await readBody(req);
       if (!body.file || !body.feedback) return jsonReply(res, 400, { error: 'file and feedback required' });
       const planPath = resolvePlanPath(body.file);
-      const plan = safeJsonObj(planPath);
-      plan.status = 'revision-requested';
-      plan.revision_feedback = body.feedback;
-      plan.revisionRequestedAt = new Date().toISOString();
-      plan.revisionRequestedBy = body.requestedBy || os.userInfo().username;
-      safeWrite(planPath, plan);
+      const plan = mutateJsonFileLocked(planPath, (data) => {
+        if (!data || Array.isArray(data) || typeof data !== 'object') data = {};
+        data.status = 'revision-requested';
+        data.revision_feedback = body.feedback;
+        data.revisionRequestedAt = new Date().toISOString();
+        data.revisionRequestedBy = body.requestedBy || os.userInfo().username;
+        return data;
+      }, { defaultValue: {} });
 
       // Create a work item to revise the plan
       const wiPath = path.join(MINIONS_DIR, 'work-items.json');

package/docs/plan-lifecycle.md

@@ -6,8 +6,8 @@ How plans go from idea to verified, running code.
 
 ```
 /plan "feature description"
-  → agent writes plan JSON (plan-*.json)
-  → engine chains plan → PRD (plan-to-prd)
+  → agent writes plan markdown (plans/plan-*.md)
+  → human reviews and explicitly runs plan-to-prd
   → agent converts plan into structured PRD items with acceptance criteria
   → engine materializes PRD items as work items (PL-W001, PL-W002, ...)
   → engine dispatches work items respecting dependency order
@@ -15,6 +15,7 @@ How plans go from idea to verified, running code.
   → engine auto-reviews PRs, handles feedback loops
   → all items done → engine creates VERIFY task
   → verify agent builds everything, starts webapp, writes testing guide
+  → human archives the PRD/plan from the dashboard when ready
 ```
 
 ## Dependency Management
@@ -66,7 +67,7 @@ When all PRD items reach `done` or `failed` status, `checkPlanCompletion()` fire
 1. **Completion summary** written to `notes/inbox/` with results, timing, and PR list
 2. **Verification task** created (type `verify`, priority `high`) — see below
 3. **PR work item** created for shared-branch plans (to merge the feature branch)
-4. **Plan archived** to `plans/archive/`
+4. **PRD status** persisted as `completed` with `_completionNotified`; files stay active until manual archive
 
 ## Verification Task
 
@@ -109,6 +110,21 @@ git merge "origin/feat/PL-W005" --no-edit
 
 The verify agent and the user can then build and run from these paths.
 
+## Manual Archive Lifecycle
+
+Archiving is a deliberate dashboard action, not a post-verify side effect. When a PRD completes, `checkPlanCompletion()` writes the completion summary, persists `status: "completed"` plus `_completionNotified`, and creates the verify work item. The PRD remains in `prd/` and its source plan remains in `plans/` so humans can review the guide, inspect the final state, resume stale work, or reopen items before hiding the plan from active views.
+
+The verify agent does not call `archivePlan()`. After the testing guide and any follow-up PR work are satisfactory, use the dashboard archive action, which calls `POST /api/plans/archive` with the active PRD or plan filename.
+
+Manual archive behavior:
+
+1. For PRD JSON files, the dashboard moves `prd/<file>.json` to `prd/archive/<file>.json`, marks the archived JSON with `status: "archived"` and `archivedAt`, and removes or neutralizes the active `.backup` sidecar so `safeJson()` cannot restore a stale completed PRD on restart.
+2. If the PRD has `source_plan`, the matching `plans/<source>.md` is moved to `plans/archive/<source>.md`.
+3. Pending or queued work items linked to the archived PRD are cancelled with `_cancelledBy: "plan-archived"`; completed work items remain as history.
+4. Plan worktrees are cleaned up by the archive handler/lifecycle cleanup path.
+
+Use unarchive only when the archived PRD/plan should reappear in active views. Reopening completed work should happen before archive, or after unarchive, so the materializer can see the active PRD file.
+
 ## Human Feedback on PRs
 
 After PRs are created, humans can leave comments containing `@minions` to trigger fix tasks. If you're the only human commenting, any comment triggers a fix — no keyword needed. See `pollPrHumanComments()` in `engine/ado.js`.
@@ -130,11 +146,11 @@ After PRs are created, humans can leave comments containing `@minions` to trigge
 
 | File | Purpose |
 |------|---------|
-| `plans/*.json` | Active plan files with PRD items |
-| `plans/archive/` | Completed/archived plans |
+| `plans/*.md` | Source plans awaiting review or linked to active PRDs |
+| `prd/*.json` | Active PRDs with materializable items |
+| `plans/archive/`, `prd/archive/` | Manually archived plans and PRDs |
 | `playbooks/verify.md` | Verification task playbook |
 | `playbooks/implement.md` | Implementation playbook |
 | `playbooks/plan-to-prd.md` | Plan → PRD conversion playbook |
-| `engine/lifecycle.js` | `checkPlanCompletion`, `chainPlanToPrd` |
+| `engine/lifecycle.js` | `checkPlanCompletion`, completion hooks, PRD sync |
 | `engine.js` | `spawnAgent` (dependency merging), `resolveDependencyBranches` |
-

package/engine/copilot-models.json

@@ -1,5 +1,5 @@
 {
   "runtime": "copilot",
   "models": null,
-  "cachedAt": "2026-05-02T05:46:43.671Z"
+  "cachedAt": "2026-05-02T13:35:00.752Z"
 }

package/engine/lifecycle.js

@@ -69,6 +69,12 @@ function checkPlanCompletion(meta, config) {
 
   const doneItems = planItems.filter(w => DONE_STATUSES.has(w.status));
   const failedItems = planItems.filter(w => w.status === WI_STATUS.FAILED || w.status === WI_STATUS.CANCELLED);
+  const isActiveVerify = (wi) => wi && (
+    wi.status === WI_STATUS.PENDING ||
+    wi.status === WI_STATUS.QUEUED ||
+    wi.status === WI_STATUS.DISPATCHED
+  );
+  const isReopenableVerify = (wi) => wi && (DONE_STATUSES.has(wi.status) || wi.status === WI_STATUS.FAILED);
 
   if (failedItems.length > 0) {
     const failDetails = failedItems.map(w =>
@@ -166,6 +172,7 @@ function checkPlanCompletion(meta, config) {
       const mainBranch = shared.resolveMainBranch(primaryProject.localPath, primaryProject.mainBranch);
       const itemSummary = doneItems.map(w => '- ' + w.id + ': ' + w.title.replace('Implement: ', '')).join('\n');
       mutateWorkItems(wiPath, workItems => {
+        if (workItems.some(w => w.sourcePlan === planFile && w.itemType === 'pr')) return workItems;
         workItems.push({
           id, title: `Create PR for plan: ${plan.plan_summary || planFile}`,
           type: 'implement', priority: 'high',
@@ -181,9 +188,23 @@ function checkPlanCompletion(meta, config) {
   // 4. Create verification work item (build, test, start webapp, write testing guide)
   // Only one verify per PRD — skip if pending/dispatched, re-open if done/failed (PRD was modified)
   const existingVerify = allWorkItems.find(w => w.sourcePlan === planFile && w.itemType === 'verify');
-  if (existingVerify && (existingVerify.status === WI_STATUS.PENDING || existingVerify.status === WI_STATUS.DISPATCHED)) {
+  if (isActiveVerify(existingVerify)) {
     log('info', `Plan ${planFile}: verify WI ${existingVerify.id} already ${existingVerify.status} — skipping`);
-  } else if (doneItems.length > 0) {
+  } else if (isReopenableVerify(existingVerify) && doneItems.length > 0) {
+    const verifyProject = existingVerify.project || projectName;
+    const vWiPath = shared.projectWorkItemsPath(
+      projects.find(p => p.name?.toLowerCase() === verifyProject?.toLowerCase()) || primaryProject
+    );
+    let reopenedVerify = false;
+    mutateWorkItems(vWiPath, items => {
+      const v = items.find(w => w.id === existingVerify.id);
+      if (isReopenableVerify(v)) {
+        shared.reopenWorkItem(v);
+        reopenedVerify = true;
+      }
+    });
+    if (reopenedVerify) log('info', `Re-opened verification work item ${existingVerify.id} for modified plan ${planFile}`);
+  } else if (!existingVerify && doneItems.length > 0) {
     const verifyId = 'PL-' + shared.uid();
     const planSlug = planFile.replace('.json', '');
 
@@ -276,7 +297,17 @@ function checkPlanCompletion(meta, config) {
       prSummary,
     ].join('\n');
 
+    let createdVerify = false;
+    let reopenedVerifyId = null;
     mutateWorkItems(wiPath, workItems => {
+      const v = workItems.find(w => w.sourcePlan === planFile && w.itemType === 'verify');
+      if (v) {
+        if (isReopenableVerify(v)) {
+          shared.reopenWorkItem(v);
+          reopenedVerifyId = v.id;
+        }
+        return workItems;
+      }
       workItems.push({
         id: verifyId,
         title: `Verify plan: ${(plan.plan_summary || planFile).slice(0, 80)}`,
@@ -290,32 +321,19 @@ function checkPlanCompletion(meta, config) {
         itemType: 'verify',
         project: projectName,
       });
+      createdVerify = true;
     });
-    log('info', `Created verification work item ${verifyId} for plan ${planFile}`);
+    if (createdVerify) {
+      log('info', `Created verification work item ${verifyId} for plan ${planFile}`);
 
-    // Teams notification for verify creation — non-blocking
-    try {
-      const teams = require('./teams');
-      teams.teamsNotifyPlanEvent({ name: plan.plan_summary || planFile, file: planFile }, 'verify-created').catch(() => {});
-    } catch {}
-  } else if (existingVerify && DONE_STATUSES.has(existingVerify.status) && doneItems.length > 0) {
-    // PRD was modified and re-completed — re-open the existing verify instead of creating a duplicate
-    const verifyProject = existingVerify.project || projectName;
-    const vWiPath = shared.projectWorkItemsPath(
-      projects.find(p => p.name?.toLowerCase() === verifyProject?.toLowerCase()) || primaryProject
-    );
-    mutateWorkItems(vWiPath, items => {
-      const v = items.find(w => w.id === existingVerify.id);
-      if (v && DONE_STATUSES.has(v.status)) {
-        v.status = WI_STATUS.PENDING;
-        v._reopened = true;
-        delete v.completedAt;
-        delete v.dispatched_to;
-        delete v.dispatched_at;
-        v._retryCount = 0;
-      }
-    });
-    log('info', `Re-opened verification work item ${existingVerify.id} for modified plan ${planFile}`);
+      // Teams notification for verify creation — non-blocking
+      try {
+        const teams = require('./teams');
+        teams.teamsNotifyPlanEvent({ name: plan.plan_summary || planFile, file: planFile }, 'verify-created').catch(() => {});
+      } catch {}
+    } else if (reopenedVerifyId) {
+      log('info', `Re-opened verification work item ${reopenedVerifyId} for modified plan ${planFile}`);
+    }
   }
 
   // Archive deferred until verify completes
@@ -350,9 +368,9 @@ function archivePlan(planFile, plan, projects, config) {
     // plan completion and spawning duplicate verify tasks for already-archived plans.
     // On Windows, the unlink can fail due to file locking; overwrite with archived status
     // as a fallback so a restored backup is inert even if deletion fails.
-    const backupPath = planPath + '.backup';
-    try { fs.unlinkSync(backupPath); } catch {
-      try { fs.writeFileSync(backupPath, JSON.stringify({ status: 'archived' })); } catch { }
+    const backupCleanup = shared.neutralizeJsonBackupSidecar(planPath);
+    if (!backupCleanup.ok) {
+      log('warn', `Archive backup cleanup failed for ${planFile}: unlink failed (${backupCleanup.unlinkError}); fallback neutralize failed (${backupCleanup.writeError})`);
     }
   } catch (err) {
     log('warn', `Failed to archive PRD ${planFile}: ${err.message}`);
@@ -440,95 +458,6 @@ function cleanupPlanWorktrees(planFile, plan, projects, config) {
   } catch (err) { log('warn', `Plan worktree cleanup: ${err.message}`); }
 }
 
-// ─── Plan → PRD Chaining ─────────────────────────────────────────────────────
-function chainPlanToPrd(dispatchItem, meta, config) {
-
-  const planDir = path.join(MINIONS_DIR, 'plans');
-  if (!fs.existsSync(planDir)) fs.mkdirSync(planDir, { recursive: true });
-
-  let planFileName = meta?.planFileName || meta?.item?._planFileName;
-  if (planFileName && fs.existsSync(path.join(planDir, planFileName))) {
-    // Exact match from meta
-  } else {
-    const planFiles = fs.readdirSync(planDir)
-      .filter(f => f.endsWith('.md') || f.endsWith('.json'))
-      .map(f => ({ name: f, mtime: fs.statSync(path.join(planDir, f)).mtimeMs }))
-      .sort((a, b) => b.mtime - a.mtime);
-    planFileName = planFiles[0]?.name;
-    if (!planFileName) {
-      log('warn', `Plan chaining: no plan files found in plans/ after task ${dispatchItem.id}`);
-      return;
-    }
-    log('info', `Plan chaining: using mtime fallback — found ${planFileName}`);
-  }
-
-  if (planFileName.endsWith('.json')) {
-    const mdName = planFileName.replace(/\.json$/, '.md');
-    // Check plans/ first, then prd/ for .json files
-    const jsonPath = fs.existsSync(path.join(planDir, planFileName))
-      ? path.join(planDir, planFileName)
-      : path.join(MINIONS_DIR, 'prd', planFileName);
-    const mdPath = path.join(planDir, mdName);
-    try {
-      const content = fs.readFileSync(jsonPath, 'utf8');
-      const parsed = JSON.parse(content);
-      if (!parsed.missing_features) {
-        fs.renameSync(jsonPath, mdPath);
-        planFileName = mdName;
-        log('info', `Plan chaining: renamed ${planFileName} → ${mdName} (plans must be .md)`);
-      }
-    } catch {
-      try {
-        if (fs.existsSync(jsonPath)) fs.renameSync(jsonPath, path.join(planDir, mdName));
-        planFileName = mdName;
-        log('info', `Plan chaining: renamed to .md (not valid JSON)`);
-      } catch (err) { log('warn', `Plan rename fallback: ${err.message}`); }
-    }
-  }
-
-  const planFile = { name: planFileName };
-  const planPath = path.join(planDir, planFileName);
-  let planContent;
-  try { planContent = fs.readFileSync(planPath, 'utf8'); } catch (err) {
-    log('error', `Plan chaining: failed to read plan file ${planFile.name}: ${err.message}`);
-    return;
-  }
-
-  const projectName = meta?.item?.project || meta?.project?.name;
-  const projects = shared.getProjects(config);
-  if (projects.length === 0) {
-    log('error', 'Plan chaining: no projects configured');
-    return;
-  }
-  const targetProject = projectName
-    ? projects.find(p => p.name === projectName) || projects[0]
-    : projects[0];
-
-  if (!targetProject) {
-    log('error', 'Plan chaining: no target project available');
-    return;
-  }
-
-  log('info', `Plan chaining: queuing plan-to-prd for next tick (chained from ${dispatchItem.id})`);
-  const wiPath = path.join(MINIONS_DIR, 'work-items.json');
-  shared.mutateJsonFileLocked(wiPath, (items) => {
-    if (!Array.isArray(items)) items = [];
-    items.push({
-      id: 'W-' + shared.uid(),
-      title: `Convert plan to PRD: ${meta?.item?.title || planFile.name}`,
-      type: 'plan-to-prd',
-      priority: meta?.item?.priority || 'high',
-      description: `Plan file: plans/${planFile.name}\nChained from plan task ${dispatchItem.id}`,
-      status: WI_STATUS.PENDING,
-      created: ts(),
-      createdBy: 'engine:chain',
-      project: targetProject.name,
-      planFile: planFile.name,
-    });
-    return items;
-  }, { defaultValue: [] });
-}
-
 // ─── Work Item Path Resolution ───────────────────────────────────────────────
 
 /** Resolve the work-items.json path from dispatch meta. Reused by retry paths. */
@@ -642,15 +571,14 @@ function syncPrdItemStatus(itemId, status, sourcePlan) {
       const feature = plan?.missing_features?.find(f => f.id === itemId);
       if (!feature || feature.status === status) continue;
       let updated = false;
-      shared.withFileLock(`${fpath}.lock`, () => {
-        const fresh = safeJson(fpath);
+      mutateJsonFileLocked(fpath, (fresh) => {
         const f = fresh?.missing_features?.find(x => x.id === itemId);
         if (f && f.status !== status) {
           f.status = status;
-          safeWrite(fpath, fresh);
           updated = true;
         }
-      });
+        return fresh;
+      }, { skipWriteIfUnchanged: true });
       if (updated) return;
     }
   } catch (err) { log('warn', `PRD status sync: ${err.message}`); }
@@ -682,31 +610,28 @@ function reconcilePrdStatuses(config) {
   for (const file of prdFiles) {
     try {
       const fpath = path.join(PRD_DIR, file);
-      const plan = safeJson(fpath);
-      if (!plan?.missing_features) continue;
-      // Skip completed/archived PRDs — no reconciliation needed
-      if (plan.status === PLAN_STATUS.COMPLETED) continue;
-
-      let modified = false;
-      for (const feature of plan.missing_features) {
-        if (feature.status === PRD_ITEM_STATUS.MISSING && doneWiById.has(feature.id)) {
-          feature.status = PRD_ITEM_STATUS.UPDATED;
-          modified = true;
-          log('info', `PRD backward-scan: promoted ${feature.id} from missing→updated in ${file} (done work item exists)`);
-        }
-        // (#984) Stale status: PRD item stuck at dispatched/failed/pending while WI is done —
-        // happens when fix work items complete with a different ID than the original PRD feature
-        else if (_STALE_PRD_STATUSES.has(feature.status) && doneWiById.has(feature.id)) {
-          const prev = feature.status;
-          feature.status = WI_STATUS.DONE;
-          modified = true;
-          log('info', `PRD backward-scan: promoted ${feature.id} from ${prev}→done in ${file} (done work item exists)`);
-        }
-      }
+      const logMessages = [];
+      mutateJsonFileLocked(fpath, (plan) => {
+        if (!plan?.missing_features) return plan;
+        // Skip completed/archived PRDs — no reconciliation needed
+        if (plan.status === PLAN_STATUS.COMPLETED) return plan;
 
-      if (modified) {
-        safeWrite(fpath, plan);
-      }
+        for (const feature of plan.missing_features) {
+          if (feature.status === PRD_ITEM_STATUS.MISSING && doneWiById.has(feature.id)) {
+            feature.status = PRD_ITEM_STATUS.UPDATED;
+            logMessages.push(`PRD backward-scan: promoted ${feature.id} from missing→updated in ${file} (done work item exists)`);
+          }
+          // (#984) Stale status: PRD item stuck at dispatched/failed/pending while WI is done —
+          // happens when fix work items complete with a different ID than the original PRD feature
+          else if (_STALE_PRD_STATUSES.has(feature.status) && doneWiById.has(feature.id)) {
+            const prev = feature.status;
+            feature.status = WI_STATUS.DONE;
+            logMessages.push(`PRD backward-scan: promoted ${feature.id} from ${prev}→done in ${file} (done work item exists)`);
+          }
+        }
+        return plan;
+      }, { skipWriteIfUnchanged: true });
+      for (const message of logMessages) log('info', message);
     } catch (err) { log('warn', `PRD backward-scan for ${file}: ${err.message}`); }
   }
 }
@@ -1608,19 +1533,17 @@ async function handlePostMerge(pr, project, config, newStatus) {
       const planFiles = fs.readdirSync(prdDir).filter(f => f.endsWith('.json'));
       let updated = 0;
       for (const pf of planFiles) {
-        const plan = safeJson(path.join(prdDir, pf));
-        if (!plan?.missing_features) continue;
-        let changed = false;
-        for (const feature of plan.missing_features) {
-          if (mergedItemSet.has(feature.id) && feature.status !== WI_STATUS.DONE) {
-            feature.status = WI_STATUS.DONE;
-            changed = true;
-            updated++;
+        const planPath = path.join(prdDir, pf);
+        mutateJsonFileLocked(planPath, (plan) => {
+          if (!plan?.missing_features) return plan;
+          for (const feature of plan.missing_features) {
+            if (mergedItemSet.has(feature.id) && feature.status !== WI_STATUS.DONE) {
+              feature.status = WI_STATUS.DONE;
+              updated++;
+            }
           }
-        }
-        if (changed) {
-          shared.safeWrite(path.join(prdDir, pf), plan);
-        }
+          return plan;
+        }, { skipWriteIfUnchanged: true });
       }
       if (updated > 0) log('info', `Post-merge: marked ${mergedItemIds.join(', ')} as done for ${pr.id}`);
     } catch (err) { log('warn', `Post-merge PRD update: ${err.message}`); }

package/engine/shared.js

@@ -212,6 +212,33 @@ function safeUnlink(p) {
   try { fs.unlinkSync(p); } catch { /* cleanup */ }
 }
 
+function neutralizeJsonBackupSidecar(filePath, inertData = { status: 'archived' }) {
+  const backupPath = filePath + '.backup';
+  try {
+    fs.unlinkSync(backupPath);
+    return { ok: true, action: 'removed', backupPath };
+  } catch (unlinkErr) {
+    if (unlinkErr.code === 'ENOENT') return { ok: true, action: 'absent', backupPath };
+    try {
+      safeWrite(backupPath, inertData);
+      return {
+        ok: true,
+        action: 'neutralized',
+        backupPath,
+        unlinkError: unlinkErr.message,
+      };
+    } catch (writeErr) {
+      return {
+        ok: false,
+        action: 'failed',
+        backupPath,
+        unlinkError: unlinkErr.message,
+        writeError: writeErr.message,
+      };
+    }
+  }
+}
+
 // ── Dispatch Prompt Sidecar (#1167) ─────────────────────────────────────────
 // Large prompts (PR diffs, build error logs, coalesced human feedback) inlined
 // into dispatch.json caused hundreds-of-MB bloat per entry and eventual V8 OOM
@@ -2387,6 +2414,7 @@ module.exports = {
   safeJson, safeJsonObj, safeJsonArr,
   safeWrite,
   safeUnlink,
+  neutralizeJsonBackupSidecar,
   PROMPT_CONTEXTS_DIR,
   dispatchPromptSidecarPath,
   dispatchCompletionReportPath,

package/engine.js

@@ -1767,6 +1767,16 @@ function buildWiDescription(item, planFile) {
 
 function materializePlansAsWorkItems(config) {
   if (!fs.existsSync(PRD_DIR)) { try { fs.mkdirSync(PRD_DIR, { recursive: true }); } catch (e) { log('warn', 'create PRD directory: ' + e.message); } }
+  const writePrdLocked = (fileName, data) => {
+    return mutateJsonFileLocked(path.join(PRD_DIR, fileName), () => data, { defaultValue: data });
+  };
+  const mutatePrdLocked = (fileName, fallback, mutator, options = {}) => {
+    return mutateJsonFileLocked(path.join(PRD_DIR, fileName), (current) => {
+      if (!current?.missing_features && fallback?.missing_features) current = fallback;
+      if (!current || Array.isArray(current) || typeof current !== 'object') current = {};
+      return mutator(current) || current;
+    }, { defaultValue: fallback || {}, ...options });
+  };
 
   // Enforce: PRDs must be .json — auto-rename .md files that contain valid PRD JSON
   // Check both prd/ and plans/ (agents may still write JSON to plans/)
@@ -1782,7 +1792,7 @@ function materializePlansAsWorkItems(config) {
           const parsed = JSON.parse(stripped);
           if (parsed.missing_features) {
             const jsonName = mf.replace(/\.md$/, '.json');
-            safeWrite(path.join(PRD_DIR, jsonName), parsed);
+            writePrdLocked(jsonName, parsed);
             try { fs.unlinkSync(path.join(checkDir, mf)); } catch { /* cleanup */ }
             log('info', `Plan enforcement: moved ${mf} → prd/${jsonName} (PRDs must be .json in prd/)`);
           }
@@ -1797,7 +1807,7 @@ function materializePlansAsWorkItems(config) {
           try {
             const parsed = safeJson(path.join(PLANS_DIR, jf));
             if (parsed?.missing_features) {
-              safeWrite(path.join(PRD_DIR, jf), parsed);
+              writePrdLocked(jf, parsed);
               try { fs.unlinkSync(path.join(PLANS_DIR, jf)); } catch { /* cleanup */ }
               log('info', `Auto-migrated PRD ${jf} from plans/ to prd/`);
             }
@@ -1814,7 +1824,7 @@ function materializePlansAsWorkItems(config) {
   const SEQUENTIAL_ID_RE = /^P-?\d+$/;
 
   for (const file of planFiles) {
-    const plan = safeJson(path.join(PRD_DIR, file));
+    let plan = safeJson(path.join(PRD_DIR, file));
     if (!plan?.missing_features) continue;
 
     // ID collision prevention: remap sequential IDs (P-001, P-002) to globally unique P-<uid> IDs.
@@ -1826,19 +1836,25 @@ function materializePlansAsWorkItems(config) {
         const anyMaterialized = plan.missing_features.some(f =>
           SEQUENTIAL_ID_RE.test(f.id) && allWorkItems.some(w => w.id === f.id && w.sourcePlan === file));
         if (!anyMaterialized) {
-          const idMap = new Map();
-          for (const f of plan.missing_features) {
-            if (SEQUENTIAL_ID_RE.test(f.id)) {
-              const newId = 'P-' + shared.uid();
-              idMap.set(f.id, newId);
-              f.id = newId;
+          let remappedCount = 0;
+          plan = mutatePrdLocked(file, plan, (current) => {
+            const features = Array.isArray(current.missing_features) ? current.missing_features : [];
+            if (!features.some(f => SEQUENTIAL_ID_RE.test(f.id))) return current;
+            const idMap = new Map();
+            for (const f of features) {
+              if (SEQUENTIAL_ID_RE.test(f.id)) {
+                const newId = 'P-' + shared.uid();
+                idMap.set(f.id, newId);
+                f.id = newId;
+              }
             }
-          }
-          for (const f of plan.missing_features) {
-            if (f.depends_on) f.depends_on = f.depends_on.map(d => idMap.get(d) || d);
-          }
-          safeWrite(path.join(PRD_DIR, file), plan);
-          log('info', `Remapped ${idMap.size} sequential ID(s) in ${file} to prevent cross-PRD collisions`);
+            for (const f of features) {
+              if (f.depends_on) f.depends_on = f.depends_on.map(d => idMap.get(d) || d);
+            }
+            remappedCount = idMap.size;
+            return current;
+          });
+          if (remappedCount > 0) log('info', `Remapped ${remappedCount} sequential ID(s) in ${file} to prevent cross-PRD collisions`);
         }
       }
     } catch (e) { log('warn', `Sequential ID remapping failed for ${file}: ${e.message}`); }
@@ -1851,25 +1867,26 @@ function materializePlansAsWorkItems(config) {
         const recorded = plan.sourcePlanModifiedAt ? new Date(plan.sourcePlanModifiedAt).getTime() : null;
         if (!recorded) {
           // First time seeing this plan — record baseline mtime (no clean needed)
-          plan.sourcePlanModifiedAt = new Date(sourceMtime).toISOString();
-          safeWrite(path.join(PRD_DIR, file), plan);
+          plan = mutatePrdLocked(file, plan, (current) => {
+            if (!current.sourcePlanModifiedAt) current.sourcePlanModifiedAt = new Date(sourceMtime).toISOString();
+            return current;
+          }, { skipWriteIfUnchanged: true });
         } else if (sourceMtime > recorded) {
           // Source plan changed — auto-clean pending/failed items so they re-materialize with updated data
           log('info', `Source plan ${plan.source_plan} updated — re-syncing PRD ${file}`);
           autoCleanPrdWorkItems(file, config);
-          plan.sourcePlanModifiedAt = new Date(sourceMtime).toISOString();
-          plan.lastSyncedFromPlan = ts();
 
           // Handle PRD based on current status
           const prdStatus = plan.status || (plan.requires_approval ? 'awaiting-approval' : null);
 
-          // Flag stale for all statuses — user decides when to regenerate/resume from dashboard
-          if (prdStatus) {
-            plan.planStale = true;
-            log('info', `PRD ${file} flagged as stale (plan revised while ${prdStatus}) — user can regenerate from dashboard`);
-          }
-
-          safeWrite(path.join(PRD_DIR, file), plan);
+          plan = mutatePrdLocked(file, plan, (current) => {
+            current.sourcePlanModifiedAt = new Date(sourceMtime).toISOString();
+            current.lastSyncedFromPlan = ts();
+            const currentPrdStatus = current.status || (current.requires_approval ? 'awaiting-approval' : null);
+            if (currentPrdStatus) current.planStale = true;
+            return current;
+          });
+          if (prdStatus) log('info', `PRD ${file} flagged as stale (plan revised while ${prdStatus}) — user can regenerate from dashboard`);
         }
       } catch (e) { log('warn', 'plan staleness check: ' + e.message); }
     }
@@ -1879,10 +1896,12 @@ function materializePlansAsWorkItems(config) {
     const planStatus = plan.status || (plan.requires_approval ? 'awaiting-approval' : null);
     if (planStatus === 'awaiting-approval') {
       if (config.engine?.autoApprovePlans) {
-        plan.status = 'approved';
-        plan.approvedAt = ts();
-        plan.approvedBy = 'auto-mode';
-        safeWrite(path.join(PRD_DIR, file), plan);
+        plan = mutatePrdLocked(file, plan, (current) => {
+          current.status = 'approved';
+          current.approvedAt = ts();
+          current.approvedBy = 'auto-mode';
+          return current;
+        });
         log('info', `Auto-approved plan: ${file}`);
       } else {
         continue; // Skip — waiting for human approval
@@ -3389,7 +3408,7 @@ function discoverCentralWorkItems(config) {
         vars.plan_file = planFileName;
         vars.task_description = item.title;
         // Notes already populated by buildWorkItemDispatchVars — no need to re-read
-        // Track expected plan filename in meta for chainPlanToPrd
+        // Track expected plan filename for artifacts and follow-up plan-to-prd prompts.
         mutations.set(item.id, Object.assign(mutations.get(item.id) || {}, { _planFileName: planFileName }));
       }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.1679",
+  "version": "0.1.1681",
   "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/fix.md

@@ -17,6 +17,14 @@ Branch: `{{pr_branch}}`
 
 {{review_note}}
 
+## Finding Triage
+
+Before editing, split the feedback into:
+
+- **Blocking findings to fix:** correctness, safety, build/test failure, missing requested behavior, broken compatibility, or review comments explicitly required for approval.
+- **Findings to answer with rationale:** comments where the current approach is intentionally correct, the reviewer misunderstood the code, or the requested change would broaden the PR beyond its purpose.
+- **Non-blocking suggestions:** style, optional refactors, extra docs, or enhancements that are not required for approval. Do not implement these unless they are necessary to resolve a blocking issue.
+
 ## Health Check
 
 Before starting work, run `git status` and verify the worktree is clean and on the expected branch (`{{pr_branch}}`). If the worktree is dirty or on the wrong branch, report the issue and stop.
@@ -42,6 +50,7 @@ Before pushing, prove the review fix did not break the branch:
 
 - Use the project's source of truth for commands: `CLAUDE.md`, README, package scripts, Makefile, or equivalent build config.
 - Run checks that are relevant to the addressed findings. Prefer the full suite when practical.
+- Capture the exact commands run and meaningful results in the PR comment and completion report.
 - Fix regressions you introduced. If failures are pre-existing or unrelated, capture the evidence and include it in the PR comment.
 - Do not push code that breaks existing tests or the build because of your changes.
 

package/playbooks/implement.md

@@ -34,11 +34,21 @@ Before starting work, run `git status` and verify the worktree is clean and on t
 
 Use subagents only for genuinely parallel, independent tasks (e.g., editing files in unrelated modules simultaneously). For sequential work, single-file edits, searches, and file reads, work directly — do not spawn subagents.
 
+## Context Discovery
+
+Before editing, assemble a small, dependency-aware context pack:
+
+- Read project instructions first (`CLAUDE.md`, README, package scripts, Makefile, or equivalent).
+- Identify candidate files from the task text, existing symbols, comparable implementations, direct imports/callers, and corresponding tests.
+- Read the smallest useful set of files first (usually 5-8). Expand only when a concrete question, failing validation, or missing pattern requires it.
+- For large files, read imports, exported/public entry points, and task-relevant sections before reading the whole file.
+
 ## Delivery Contract
 
 Deliver this as if the user asked you directly in a CLI:
 
 - Understand the requested behavior and relevant acceptance criteria before editing.
+- State the likely files to touch, patterns to follow, and main risks to yourself before making the first code change.
 - Read the smallest useful set of source, tests, docs, and comparable implementations needed to make the change correctly.
 - Follow existing project conventions, including logging, typing, error handling, and test structure.
 - Make the complete change required by the task; do not add unrelated cleanups or speculative improvements.
@@ -55,6 +65,7 @@ Before publishing, prove the change with the repo's own documented checks:
 
 - Use the project's source of truth for commands: `CLAUDE.md`, README, package scripts, Makefile, or equivalent build config.
 - Run the checks that are relevant to this task, including tests that cover the changed behavior. Prefer the full suite when practical.
+- Capture the exact commands run and the meaningful result in the PR description or completion report. Do not summarize validation as "tests passed" without naming what ran.
 - Fix regressions you introduced. If failures are pre-existing or outside the task, capture the evidence and make that explicit in the PR.
 - Do not publish changes with a broken build or failing tests that you introduced.
 

package/playbooks/plan.md

@@ -28,12 +28,14 @@ A user has described a feature they want built. Your job is to create a detailed
 - Map the areas of code that this feature will touch
 - Identify existing patterns, conventions, and extension points
 - Note dependencies and potential conflicts with in-progress work
+- Build a concise context pack before planning: start with 5-15 candidate files from paths, symbols, comparable implementations, imports/callers, and tests; read the smallest useful set (usually 5-8 files) and expand only for specific unknowns
 
 ### 3. Design the Approach
 - Outline the high-level architecture for the feature
 - Identify what needs to be created vs modified
 - Consider edge cases, error handling, and backwards compatibility
 - Note any prerequisites or migrations needed
+- Record non-obvious design decisions with the alternatives considered and why the chosen option best fits existing architecture
 
 ### 4. Break Down into Work Items
 - Decompose into discrete, PR-sized chunks of work

package/playbooks/review.md

@@ -23,7 +23,14 @@ Use subagents only for genuinely parallel, independent tasks (e.g., reviewing un
    git diff {{main_branch}}...origin/{{pr_branch}}
    ```
 
-2. For each changed file, verify:
+2. Think about deploy risk before commenting:
+   - What user-visible behavior changed?
+   - What dependencies, callers, or tests could be affected?
+   - What security, data-loss, concurrency, or compatibility risks are plausible for this diff?
+
+3. Run or inspect the repo's documented checks when practical. Use `CLAUDE.md`, README, package scripts, Makefile, or equivalent as the command source of truth, and record the exact commands/results in the review body.
+
+4. For each changed file, verify:
    - Does it follow existing patterns?
    - Are file paths and imports correct?
    - Follows the project's logging conventions (check CLAUDE.md)?
@@ -31,14 +38,19 @@ Use subagents only for genuinely parallel, independent tasks (e.g., reviewing un
    - Tests cover the important logic?
    - No security issues (injection, unsanitized input)?
 
-3. Do NOT blindly approve. If you find real issues:
+5. Classify findings by ship risk:
+   - **Blocking:** failing checks, security/data-loss risk, broken existing behavior, missing requested behavior, invalid API/schema/data migration, or tests that do not cover changed critical logic.
+   - **Non-blocking:** style preferences, minor refactors, optional documentation, low-risk performance ideas, or additional tests that are useful but not required for safety.
+
+6. Do NOT blindly approve. If you find real blocking issues:
    - Verdict: **REQUEST_CHANGES**
    - List specific issues with file paths and line numbers
    - Describe what needs to change
 
-4. If the code is genuinely ready:
+7. If the code is genuinely ready:
    - Verdict: **APPROVE**
    - Note any minor non-blocking suggestions
+   - Do not request changes for nits, speculative edge cases, or unrelated improvements
 
 ## Post Review — Submit your verdict
 
@@ -55,6 +67,19 @@ Your review body **MUST** start with one of these verdict lines (exactly as show
 Follow the verdict line with your detailed review findings, then sign off:
 - Sign: `Review by Minions ({{agent_name}} — {{agent_role}})`
 
+Use this structure after the verdict:
+
+```markdown
+Automated checks:
+- `<command>`: pass/fail/skipped — short result or reason
+
+Blocking issues:
+- None, or `path:line` — issue and required fix
+
+Non-blocking suggestions:
+- None, or `path:line` — suggestion
+```
+
 After running the command, confirm it succeeded (check the command output for errors). If it fails, retry once.
 
 ## Handling Merge Conflicts

package/playbooks/shared-rules.md

@@ -13,6 +13,8 @@ Treat a Minions assignment like the user typed the same task directly into a cap
 - Optimize for the requested outcome, not for mechanically completing checklist steps.
 - Use judgment to choose the smallest reliable workflow that fully satisfies the task.
 - Read only the context needed to make correct decisions; do not perform broad archaeology unless the task requires it.
+- Build an initial context pack before editing: start from repo docs and team memory, identify 5-15 candidate files by path names, symbols, imports, tests, and comparable implementations, then read the smallest useful pack (usually 5-8 files). Expand beyond that only when a specific gap or failure proves more context is needed.
+- Prefer dependency-aware context over keyword-only searching: when touching a file, also check its direct imports, direct callers when easy to find, and corresponding tests. For small repos, a simple repo map plus targeted search is enough.
 - Validate with the repo's own documented commands and acceptance criteria. If full validation is impossible or pre-existing failures block it, explain that precisely instead of inventing a green result.
 - Prefer direct work over ceremony. Branches, PRs, inbox notes, completion reports/blocks, and status comments exist for traceability; they should not change what "done" means for the user.
 - Safety and observability rules still win: stay in the engine-created worktree, do not self-merge, do not edit engine-managed status files, do not hide failures, and leave enough evidence for the human and engine to track the result.