@yemi33/minions 0.1.741 → 0.1.743

package/CHANGELOG.md

@@ -1,11 +1,13 @@
 # Changelog
 
-## 0.1.741 (2026-04-09)
+## 0.1.743 (2026-04-09)
 
 ### Features
 - add prNumber field to pull-requests.json records (#711)
 
 ### Fixes
+-  link plan files as artifacts on plan/plan-to-prd work items
+-  escalate failed plan items instead of blocking indefinitely (closes #722) (#733)
 -  handle NUL pseudo-file in Windows worktree cleanup (#731)
 
 ## 0.1.739 (2026-04-09)

package/engine/lifecycle.js

@@ -8,7 +8,7 @@ const path = require('path');
 const os = require('os');
 const shared = require('./shared');
 const { safeRead, safeJson, safeWrite, mutateJsonFileLocked, mutateWorkItems, execSilent, projectPrPath, getPrLinks, addPrLink,
-  log, ts, dateStamp, WI_STATUS, DONE_STATUSES, WORK_TYPE, PLAN_STATUS, PR_STATUS, DISPATCH_RESULT,
+  log, ts, dateStamp, WI_STATUS, DONE_STATUSES, PLAN_TERMINAL_STATUSES, WORK_TYPE, PLAN_STATUS, PR_STATUS, DISPATCH_RESULT,
   ENGINE_DEFAULTS, DEFAULT_AGENT_METRICS, FAILURE_CLASS } = shared;
 const { trackEngineUsage } = require('./llm');
 const queries = require('./queries');
@@ -34,7 +34,7 @@ function checkPlanCompletion(meta, config) {
   const planItems = allWorkItems.filter(w => w.sourcePlan === planFile && w.itemType !== 'pr' && w.itemType !== 'verify');
   if (planItems.length === 0) return;
 
-  // Hard completion gate: every PRD feature ID must have a corresponding work item in done status.
+  // Hard completion gate: every PRD feature ID must have a corresponding work item in a terminal state.
   const planFeatureIds = new Set((plan.missing_features || []).map(f => f.id).filter(Boolean));
   const workItemById = {};
   for (const w of planItems) { if (w.id) workItemById[w.id] = w; }
@@ -51,20 +51,36 @@ function checkPlanCompletion(meta, config) {
     return;
   }
 
-  // Check 2: every feature's work item must be done (or PRD item marked done externally)
-  const notDone = [...planFeatureIds].filter(id => {
+  // Check 2: every feature must be in a terminal state (done, failed, or cancelled).
+  // Failed/cancelled items are unrecoverable — waiting on them blocks the plan indefinitely.
+  const notTerminal = [...planFeatureIds].filter(id => {
     const w = workItemById[id];
-    if (w && DONE_STATUSES.has(w.status)) return false;
+    if (w && PLAN_TERMINAL_STATUSES.has(w.status)) return false;
     const prdItem = (plan.missing_features || []).find(f => f.id === id);
-    return !(prdItem && DONE_STATUSES.has(prdItem.status));
+    return !(prdItem && PLAN_TERMINAL_STATUSES.has(prdItem.status));
   });
-  if (notDone.length > 0) {
-    log('info', `Plan ${planFile}: waiting for done on ${notDone.length}/${planFeatureIds.size} item(s): ${notDone.join(', ')}`);
+  if (notTerminal.length > 0) {
+    log('info', `Plan ${planFile}: waiting for ${notTerminal.length}/${planFeatureIds.size} item(s) to reach terminal state: ${notTerminal.join(', ')}`);
     return;
   }
 
   const doneItems = planItems.filter(w => DONE_STATUSES.has(w.status));
-  const failedItems = planItems.filter(w => w.status === WI_STATUS.FAILED);
+  const failedItems = planItems.filter(w => w.status === WI_STATUS.FAILED || w.status === WI_STATUS.CANCELLED);
+
+  // Escalate failed/cancelled items to human — write inbox alert (deduped by slug)
+  if (failedItems.length > 0) {
+    const alertSlug = `plan-failure-escalation-${planFile.replace('.json', '')}`;
+    const failDetails = failedItems.map(w =>
+      `- \`${w.id}\`: ${w.title || 'Unknown'} — ${w.failReason || w.status}`
+    ).join('\n');
+    shared.writeToInbox('engine', alertSlug,
+      `# Plan Items Failed: ${plan.plan_summary || planFile}\n\n` +
+      `**${failedItems.length}** of ${planFeatureIds.size} item(s) failed or were cancelled:\n\n${failDetails}\n\n` +
+      `The plan is completing with partial results (${doneItems.length} done, ${failedItems.length} failed).\n` +
+      `Review failed items and re-dispatch manually if needed.\n`
+    );
+    log('warn', `Plan ${planFile}: ${failedItems.length} item(s) failed/cancelled — escalating to human: ${failedItems.map(w => w.id).join(', ')}`);
+  }
 
   // 1. Mark plan as completed
   plan.status = PLAN_STATUS.COMPLETED;

package/engine/queries.js

@@ -754,6 +754,8 @@ function getWorkItems(config) {
     }
     if (item.branch || item.featureBranch) arts.branch = item.branch || item.featureBranch;
     if (item.sourcePlan) arts.sourcePlan = item.sourcePlan;
+    if (item._planFileName) arts.plan = item._planFileName;
+    else if (item.planFile) arts.plan = item.planFile;
     if (item._pr) arts.pr = item._pr;
     if (Object.keys(arts).length > 0) item._artifacts = arts;
   }

package/engine/shared.js

@@ -562,6 +562,9 @@ const WI_STATUS = {
 // Read-side: accept legacy aliases for backward compat with old data/clients.
 // Write-side: only WI_STATUS.DONE is written (cleanup.js migrates old values on each run).
 const DONE_STATUSES = new Set([WI_STATUS.DONE, 'in-pr', 'implemented', 'complete']);
+// Terminal statuses for plan completion — item won't progress further (done, failed, cancelled).
+// Used by checkPlanCompletion to unblock the gate when items are in an unrecoverable state.
+const PLAN_TERMINAL_STATUSES = new Set([...DONE_STATUSES, WI_STATUS.FAILED, WI_STATUS.CANCELLED]);
 const WORK_TYPE = {
   IMPLEMENT: 'implement', IMPLEMENT_LARGE: 'implement:large', FIX: 'fix', REVIEW: 'review',
   VERIFY: 'verify', PLAN: 'plan', PLAN_TO_PRD: 'plan-to-prd', DECOMPOSE: 'decompose',
@@ -989,7 +992,7 @@ module.exports = {
   KB_CATEGORIES,
   classifyInboxItem,
   ENGINE_DEFAULTS,
-  WI_STATUS, DONE_STATUSES, WORK_TYPE, PLAN_STATUS, PR_STATUS, DISPATCH_RESULT,
+  WI_STATUS, DONE_STATUSES, PLAN_TERMINAL_STATUSES, WORK_TYPE, PLAN_STATUS, PR_STATUS, DISPATCH_RESULT,
   PIPELINE_STATUS, STAGE_TYPE, MEETING_STATUS, AGENT_STATUS,
   FAILURE_CLASS, ESCALATION_POLICY, COMPLETION_FIELDS,
   DEFAULT_AGENT_METRICS,

package/package.json

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