@yemi33/minions 0.1.1673 → 0.1.1674

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.1.1674 (2026-05-02)
+
+### Other
+- refactor: collapse needs-human-review into failed + simplify migration paths
+
 ## 0.1.1673 (2026-05-02)
 
 ### Fixes

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

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

package/docs/rfc-completion-json.md

@@ -187,7 +187,7 @@ The agent must not write the file in pieces. Empty, truncated, or malformed JSON
 | `partial` | Some progress; agent ran out of turns or hit a known stop point | Auto-retry per `RECOVERY_RECIPES` (`engine/recovery.js`) |
 | `failed` | Hard failure; no recovery attempted by agent | Use `failure.class` to pick recipe |
 | `noop` | Idempotent bail (review already posted, plan already shipped, etc.) | Mark WI `done` without retry, no failure metric |
-| `needs-review` | Agent could not classify; flag for human | Set WI `needs-human-review` |
+| `needs-review` | Agent could not classify; flag for human | Set WI `failed` with an explicit `failReason` |
 
 `noop` collapses the current `isReviewBailout` (lifecycle.js:907), the `verify-plan-already-shipped` family of skills, and the "shared-branch redispatch" skill into a single explicit signal. Any agent that detects "the work is already done" returns `status: "noop"` and a one-line `summary` — the engine takes the success path without retry.
 
@@ -370,7 +370,7 @@ The current ` ```completion ` block in `playbooks/fix.md:85-93` and `playbooks/i
 
 ### 7.3 No-PR Tasks
 
-`explore`, `ask`, `test`, `docs`, `plan-to-prd`, and the read-only legs of `meeting-*` simply omit `prs[]`. They still write completion.json with `status` + `summary`. This makes "I had nothing to push" an explicit signal instead of inferred from "no PR URL found in stdout" (which today triggers the auto-retry-then-needs-review chain at `lifecycle.js:1943-1984`).
+`explore`, `ask`, `test`, `docs`, `plan-to-prd`, and the read-only legs of `meeting-*` simply omit `prs[]`. They still write completion.json with `status` + `summary`. This makes "I had nothing to push" an explicit signal instead of inferred from "no PR URL found in stdout" (which today triggers the auto-retry-then-failed chain at `lifecycle.js:1943-1984`).
 
 ## 8. Validation & Testing
 

package/engine/cleanup.js

@@ -507,48 +507,39 @@ function runCleanup(config, verbose = false) {
     } catch (e) { log('warn', 'reconcile failed-with-PR: ' + e.message); }
   }
 
-  // 6b. Migrate legacy work-item statuses to canonical 'done'
-  // in-pr, implemented, complete → done (one-time correction per item)
+  // 6b. Migrate legacy work-item statuses to canonical replacements
+  // in-pr, implemented, complete → done; needs-human-review → failed
   const LEGACY_DONE_ALIASES = new Set(['in-pr', 'implemented', 'complete']);
-  for (const project of projects) {
+  const LEGACY_NEEDS_REVIEW_STATUS = 'needs-human-review';
+  const LEGACY_NEEDS_REVIEW_FAIL_REASON = 'Manual intervention required (migrated from needs-human-review)';
+  function _migrateLegacyItem(item) {
+    if (LEGACY_DONE_ALIASES.has(item.status)) {
+      item.status = shared.WI_STATUS.DONE;
+      delete item._retryCount;
+      delete item._pendingReason;
+      if (!item.completedAt) item.completedAt = shared.ts();
+      return true;
+    }
+    if (item.status === LEGACY_NEEDS_REVIEW_STATUS) {
+      item.status = shared.WI_STATUS.FAILED;
+      if (!item.failReason) item.failReason = LEGACY_NEEDS_REVIEW_FAIL_REASON;
+      if (!item.failedAt) item.failedAt = shared.ts();
+      delete item.completedAt;
+      return true;
+    }
+    return false;
+  }
+  function _migrateLegacyItemsAt(wiPath, label) {
     try {
-      const wiPath = projectWorkItemsPath(project);
       let migrated = 0;
-        mutateWorkItems(wiPath, items => {
-          for (const item of items) {
-            if (LEGACY_DONE_ALIASES.has(item.status)) {
-              item.status = shared.WI_STATUS.DONE;
-              delete item._retryCount;
-              delete item._pendingReason;
-              if (!item.completedAt) item.completedAt = shared.ts();
-              migrated++;
-            }
-          }
-        });
-      if (migrated > 0) {
-        log('info', `Migrated ${migrated} legacy status(es) → done in ${project.name} work items`);
-      }
-    } catch (e) { log('warn', 'migrate legacy statuses: ' + e.message); }
+      mutateWorkItems(wiPath, items => {
+        for (const item of items) if (_migrateLegacyItem(item)) migrated++;
+      });
+      if (migrated > 0) log('info', `Migrated ${migrated} legacy status(es) in ${label}`);
+    } catch (e) { log('warn', `migrate legacy statuses (${label}): ${e.message}`); }
   }
-  // Central work items
-  try {
-    const centralPath = path.join(MINIONS_DIR, 'work-items.json');
-    let migrated = 0;
-    mutateWorkItems(centralPath, items => {
-      for (const item of items) {
-        if (LEGACY_DONE_ALIASES.has(item.status)) {
-          item.status = shared.WI_STATUS.DONE;
-          delete item._retryCount;
-          delete item._pendingReason;
-          if (!item.completedAt) item.completedAt = shared.ts();
-          migrated++;
-        }
-      }
-    });
-    if (migrated > 0) {
-      log('info', `Migrated ${migrated} legacy status(es) → done in central work items`);
-    }
-  } catch (e) { log('warn', 'migrate central legacy statuses: ' + e.message); }
+  for (const project of projects) _migrateLegacyItemsAt(projectWorkItemsPath(project), `${project.name} work items`);
+  _migrateLegacyItemsAt(path.join(MINIONS_DIR, 'work-items.json'), 'central work items');
 
   // 6c. Strip stale retry metadata from completed work items
   cleaned.doneRetryCounts = 0;
@@ -591,18 +582,23 @@ function runCleanup(config, verbose = false) {
     const prdFiles = prdDirEntries.filter(f => f.endsWith('.json'));
     for (const pf of prdFiles) {
       const prdPath = path.join(PRD_DIR, pf);
-      const prd = safeJson(prdPath);
-      if (!prd?.missing_features) continue;
       let migrated = 0;
-      for (const feat of prd.missing_features) {
-        if (LEGACY_DONE_ALIASES.has(feat.status)) {
-          feat.status = shared.WI_STATUS.DONE;
-          migrated++;
+      shared.withFileLock(`${prdPath}.lock`, () => {
+        const prd = safeJson(prdPath);
+        if (!prd?.missing_features) return;
+        for (const feat of prd.missing_features) {
+          if (LEGACY_DONE_ALIASES.has(feat.status)) {
+            feat.status = shared.WI_STATUS.DONE;
+            migrated++;
+          } else if (feat.status === LEGACY_NEEDS_REVIEW_STATUS) {
+            feat.status = shared.WI_STATUS.FAILED;
+            migrated++;
+          }
         }
-      }
+        if (migrated > 0) safeWrite(prdPath, prd);
+      });
       if (migrated > 0) {
-        safeWrite(prdPath, prd);
-        log('info', `Migrated ${migrated} legacy PRD item status(es) → done in ${pf}`);
+        log('info', `Migrated ${migrated} legacy PRD item status(es) in ${pf}`);
       }
     }
   } catch (e) { log('warn', 'migrate PRD legacy statuses: ' + e.message); }

package/engine/copilot-models.json

@@ -1,5 +1,5 @@
 {
   "runtime": "copilot",
   "models": null,
-  "cachedAt": "2026-05-02T04:13:14.794Z"
+  "cachedAt": "2026-05-02T04:24:34.949Z"
 }

package/engine/lifecycle.js

@@ -637,14 +637,21 @@ function syncPrdItemStatus(itemId, status, sourcePlan) {
     const files = sourcePlan ? [sourcePlan] : require('fs').readdirSync(prdDir).filter(f => f.endsWith('.json'));
     for (const pf of files) {
       const fpath = path.join(prdDir, pf);
+      // Lock-free peek: most PRDs won't contain the ID, so skip the lock cost.
       const plan = safeJson(fpath);
-      if (!plan?.missing_features) continue;
-      const feature = plan.missing_features.find(f => f.id === itemId);
-      if (feature && feature.status !== status) {
-        feature.status = status;
-        shared.safeWrite(fpath, plan);
-        return;
-      }
+      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);
+        const f = fresh?.missing_features?.find(x => x.id === itemId);
+        if (f && f.status !== status) {
+          f.status = status;
+          safeWrite(fpath, fresh);
+          updated = true;
+        }
+      });
+      if (updated) return;
     }
   } catch (err) { log('warn', `PRD status sync: ${err.message}`); }
 }
@@ -947,18 +954,19 @@ function isPrAttachmentRequired(type, item, meta = {}) {
   if (branchStrategy === 'shared-branch' && item.itemType !== 'pr' && !explicit) return false;
 
   // Fix/test work items dispatched against an existing PR don't produce a new
-  // PR — the agent updates meta.pr in place. Only require fresh PR attachment
-  // when there's NO existing PR to operate on (rare: standalone fix dispatched
-  // from CC without a PR target). The meta.pr short-circuit beats the
-  // explicit-flag fallthrough so a legacy requiresPr:true fix doesn't trigger
-  // the contract when there's already a PR attached.
+  // PR — the agent updates meta.pr in place. The meta.pr short-circuit beats
+  // the explicit-flag fallthrough so a legacy requiresPr:true fix doesn't
+  // trigger the contract when there's already a PR attached.
   if ((type === WORK_TYPE.FIX || type === WORK_TYPE.TEST) && meta?.pr) return false;
 
+  // Standalone test work is usually pure build/run/verify. It should only be
+  // PR-required when the caller explicitly marks it as file-changing work.
+  if (type === WORK_TYPE.TEST && !explicit) return false;
+
   return explicit
     || type === WORK_TYPE.IMPLEMENT
     || type === WORK_TYPE.IMPLEMENT_LARGE
-    || type === WORK_TYPE.FIX
-    || type === WORK_TYPE.TEST;
+    || type === WORK_TYPE.FIX;
 }
 
 function readOptionalJsonStrict(filePath, label, validate) {
@@ -1148,18 +1156,19 @@ function _outputContainsPrUrl(output) {
 function markMissingPrAttachment(meta, agentId, reason, resultSummary, severity) {
   const noPrWiPath = resolveWorkItemPath(meta);
   const isHard = severity !== 'soft';
-  let syncNeedsReviewToPrd = false;
+  let syncFailedToPrd = false;
   if (noPrWiPath) {
     mutateJsonFileLocked(noPrWiPath, data => {
       if (!Array.isArray(data)) return data;
       const w = data.find(i => i.id === meta.item.id);
       if (!w) return data;
       if (isHard) {
-        w.status = WI_STATUS.NEEDS_REVIEW;
+        w.status = WI_STATUS.FAILED;
         w._missingPrAttachment = true;
         w.failReason = reason;
+        w.failedAt = ts();
         w._lastReviewReason = reason;
-        syncNeedsReviewToPrd = !!meta.item?.sourcePlan;
+        syncFailedToPrd = !!meta.item?.sourcePlan;
         delete w.completedAt;
         delete w._noPr;
         delete w._noPrReason;
@@ -1173,8 +1182,8 @@ function markMissingPrAttachment(meta, agentId, reason, resultSummary, severity)
       return data;
     }, { skipWriteIfUnchanged: true });
   }
-  if (isHard && syncNeedsReviewToPrd) {
-    syncPrdItemStatus(meta.item.id, WI_STATUS.NEEDS_REVIEW, meta.item.sourcePlan);
+  if (isHard && syncFailedToPrd) {
+    syncPrdItemStatus(meta.item.id, WI_STATUS.FAILED, meta.item.sourcePlan);
   }
   if (isHard) {
     shared.writeToInbox('engine', `missing-pr-attachment-${meta.item.id}`,
@@ -1206,25 +1215,26 @@ function markMissingPrAttachment(meta, agentId, reason, resultSummary, severity)
 
 function markPrAttachmentVerificationError(meta, agentId, reason, resultSummary) {
   const wiPath = resolveWorkItemPath(meta);
-  let syncNeedsReviewToPrd = false;
+  let syncFailedToPrd = false;
   if (wiPath) {
     mutateJsonFileLocked(wiPath, data => {
       if (!Array.isArray(data)) return data;
       const w = data.find(i => i.id === meta.item.id);
       if (!w) return data;
-      w.status = WI_STATUS.NEEDS_REVIEW;
+      w.status = WI_STATUS.FAILED;
       w._prAttachmentStateError = true;
       w.failReason = reason;
+      w.failedAt = ts();
       w._lastReviewReason = reason;
-      syncNeedsReviewToPrd = !!meta.item?.sourcePlan;
+      syncFailedToPrd = !!meta.item?.sourcePlan;
       delete w.completedAt;
       delete w._missingPrAttachment;
       delete w._unverifiedPrAttachment;
       return data;
     }, { skipWriteIfUnchanged: true });
   }
-  if (syncNeedsReviewToPrd) {
-    syncPrdItemStatus(meta.item.id, WI_STATUS.NEEDS_REVIEW, meta.item.sourcePlan);
+  if (syncFailedToPrd) {
+    syncPrdItemStatus(meta.item.id, WI_STATUS.FAILED, meta.item.sourcePlan);
   }
   shared.writeToInbox('engine', `pr-attachment-state-error-${meta.item.id}`,
     `# PR attachment verification blocked for ${meta.item.id}\n\n` +

package/engine/shared.js

@@ -1089,7 +1089,7 @@ function runtimeConfigWarnings(config, registeredRuntimes) {
 
 const WI_STATUS = {
   PENDING: 'pending', DISPATCHED: 'dispatched', DONE: 'done', FAILED: 'failed',
-  PAUSED: 'paused', QUEUED: 'queued', NEEDS_REVIEW: 'needs-human-review',
+  PAUSED: 'paused', QUEUED: 'queued',
   DECOMPOSED: 'decomposed', CANCELLED: 'cancelled',
 };
 // Read-side: accept legacy aliases for backward compat with old data/clients.

package/engine.js

@@ -100,6 +100,8 @@ const mutateWorkItems = shared.mutateWorkItems;
 const mutatePullRequests = shared.mutatePullRequests;
 const withFileLock = shared.withFileLock;
 
+const CHECKPOINT_CAP_FAIL_REASON = 'Exceeded 3 checkpoint-resumes; manual intervention required';
+
 // ─── Dispatch Management (extracted to engine/dispatch.js) ───────────────────
 
 const { mutateDispatch, addToDispatch, isRetryableFailureReason, completeDispatch,
@@ -2789,10 +2791,16 @@ function discoverFromWorkItems(config, project) {
     const promptAgentId = deferredAgentResolution ? reservedAgentId : agentId;
     const promptResult = renderProjectWorkItemPromptForAgent(item, workType, promptAgentId, config, project, root, branchName);
     if (promptResult.needsReview) {
-      log('warn', `Work item ${item.id} exceeded 3 checkpoint-resumes — marking as needs-human-review`);
-      item.status = WI_STATUS.NEEDS_REVIEW;
+      log('warn', `Work item ${item.id} exceeded 3 checkpoint-resumes — marking as failed for manual intervention`);
+      item.status = WI_STATUS.FAILED;
+      item.failReason = CHECKPOINT_CAP_FAIL_REASON;
+      item.failedAt = ts();
       item._checkpointCount = promptResult.checkpointCount;
       needsWrite = true;
+      if (item.sourcePlan) {
+        try { syncPrdItemStatus(item.id, WI_STATUS.FAILED, item.sourcePlan); }
+        catch (e) { log('warn', `PRD status sync after checkpoint cap (${item.id}): ${e.message}`); }
+      }
       continue;
     }
     if (promptResult.checkpointCount !== null) {
@@ -3305,8 +3313,17 @@ function discoverCentralWorkItems(config) {
         workType,
       });
       if (cpResult.needsReview) {
-        log('warn', `Work item ${item.id} exceeded 3 checkpoint-resumes — marking as needs-human-review`);
-        mutations.set(item.id, { status: WI_STATUS.NEEDS_REVIEW, _checkpointCount: cpResult.checkpointCount });
+        log('warn', `Work item ${item.id} exceeded 3 checkpoint-resumes — marking as failed for manual intervention`);
+        mutations.set(item.id, {
+          status: WI_STATUS.FAILED,
+          failReason: CHECKPOINT_CAP_FAIL_REASON,
+          failedAt: ts(),
+          _checkpointCount: cpResult.checkpointCount,
+        });
+        if (item.sourcePlan) {
+          try { syncPrdItemStatus(item.id, WI_STATUS.FAILED, item.sourcePlan); }
+          catch (e) { log('warn', `PRD status sync after checkpoint cap (${item.id}): ${e.message}`); }
+        }
         continue;
       }
       if (cpResult.checkpointCount !== null) {

package/package.json

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