@yemi33/minions 0.1.154 → 0.1.156

package/CHANGELOG.md

@@ -1,6 +1,19 @@
 # Changelog
 
-## 0.1.154 (2026-04-02)
+## 0.1.156 (2026-04-02)
+
+### Engine
+- engine.js
+- engine/shared.js
+
+### Dashboard
+- dashboard/js/render-plans.js
+- dashboard/js/render-prd.js
+
+### Other
+- test/unit.test.js
+
+## 0.1.155 (2026-04-02)
 
 ### Engine
 - engine.js
@@ -17,11 +30,15 @@
 - dashboard/js/refresh.js
 - dashboard/js/render-inbox.js
 - dashboard/js/render-kb.js
+- dashboard/js/render-pipelines.js
 - dashboard/js/render-plans.js
 - dashboard/js/render-prd.js
 - dashboard/js/render-work-items.js
 - dashboard/styles.css
 
+### Playbooks
+- implement.md
+
 ### Documentation
 - deprecated.json
 

package/dashboard/js/render-pipelines.js

@@ -2,6 +2,68 @@
 
 let _pipelinesData = [];
 
+/**
+ * Render clickable artifact links for a pipeline stage.
+ * Each artifact type gets an icon and navigates to the relevant detail view.
+ */
+function _renderArtifactLinks(artifacts) {
+  if (!artifacts) return '';
+  var links = [];
+  var linkStyle = 'display:inline-flex;align-items:center;gap:2px;padding:1px 6px;border-radius:10px;font-size:10px;cursor:pointer;text-decoration:none;color:var(--blue);background:color-mix(in srgb, var(--blue) 10%, transparent);border:1px solid color-mix(in srgb, var(--blue) 20%, transparent)';
+
+  // Work items → navigate to work page & open detail
+  (artifacts.workItems || []).forEach(function(id) {
+    links.push('<span style="' + linkStyle + '" onclick="event.stopPropagation();closeModal();switchPage(\'work\');setTimeout(function(){openWorkItemDetail(\'' + escHtml(id) + '\')},200)" title="Open work item ' + escHtml(id) + '">⚙ ' + escHtml(id) + '</span>');
+  });
+
+  // Meetings → navigate to meetings page & open detail
+  (artifacts.meetings || []).forEach(function(id) {
+    links.push('<span style="' + linkStyle + '" onclick="event.stopPropagation();closeModal();switchPage(\'meetings\');setTimeout(function(){openMeetingDetail(\'' + escHtml(id) + '\')},200)" title="Open meeting ' + escHtml(id) + '">💬 ' + escHtml(id) + '</span>');
+  });
+
+  // Plans → navigate to plans page
+  (artifacts.plans || []).forEach(function(name) {
+    links.push('<span style="' + linkStyle + '" onclick="event.stopPropagation();closeModal();switchPage(\'plans\')" title="Plan: ' + escHtml(name) + '">📋 ' + escHtml(name.replace(/\.md$/, '').slice(0, 30)) + '</span>');
+  });
+
+  // PRDs → navigate to PRD page
+  (artifacts.prds || []).forEach(function(name) {
+    links.push('<span style="' + linkStyle + '" onclick="event.stopPropagation();closeModal();switchPage(\'prd\')" title="PRD: ' + escHtml(name) + '">📄 ' + escHtml(name.replace(/\.json$/, '').slice(0, 30)) + '</span>');
+  });
+
+  // PRs → navigate to PRs page
+  (artifacts.prs || []).forEach(function(id) {
+    links.push('<span style="' + linkStyle + '" onclick="event.stopPropagation();closeModal();switchPage(\'prs\')" title="Pull request ' + escHtml(id) + '">🔀 PR-' + escHtml(id) + '</span>');
+  });
+
+  // Sub-stages (parallel) — just label them, no nav needed
+  (artifacts.subStages || []).forEach(function(id) {
+    links.push('<span style="' + linkStyle + ';cursor:default;color:var(--muted);background:color-mix(in srgb, var(--muted) 8%, transparent);border-color:color-mix(in srgb, var(--muted) 15%, transparent)" title="Sub-stage ' + escHtml(id) + '">⚓ ' + escHtml(id) + '</span>');
+  });
+
+  if (links.length === 0) return '';
+  return '<div style="margin-top:6px;display:flex;flex-wrap:wrap;gap:4px">' + links.join('') + '</div>';
+}
+
+/**
+ * Collect and deduplicate artifacts from all stages in a run.
+ * Returns { merged: { workItems, meetings, plans, prds, prs, subStages }, total }.
+ */
+function _collectRunArtifacts(run) {
+  var merged = { workItems: [], meetings: [], plans: [], prds: [], prs: [], subStages: [] };
+  var stages = run.stages || {};
+  for (var stageId in stages) {
+    var a = stages[stageId].artifacts || {};
+    ['workItems', 'meetings', 'plans', 'prds', 'prs', 'subStages'].forEach(function(key) {
+      (a[key] || []).forEach(function(v) {
+        if (merged[key].indexOf(v) === -1) merged[key].push(v);
+      });
+    });
+  }
+  var total = merged.workItems.length + merged.meetings.length + merged.plans.length + merged.prds.length + merged.prs.length;
+  return { merged: merged, total: total };
+}
+
 function renderPipelines(pipelines) {
   _pipelinesData = pipelines || [];
   const el = document.getElementById('pipelines-content');
@@ -29,6 +91,45 @@ function renderPipelines(pipelines) {
       return '<span style="color:' + color + ';font-size:11px" title="' + escHtml(s.id) + ': ' + escHtml(s.title || s.type) + ' (' + stageStatus + ')">' + icon + ' ' + escHtml(s.id) + '</span>';
     }).join(' <span style="color:var(--border)">\u2192</span> ');
 
+    // Build step-progress indicator for pipelines with a run
+    var progressHtml = '';
+    var displayRun = activeRun || lastRun;
+    if (displayRun && (p.stages || []).length > 0) {
+      var totalStages = (p.stages || []).length;
+      var completedCount = 0;
+      var runningCount = 0;
+      var failedCount = 0;
+      (p.stages || []).forEach(function(s) {
+        var st = displayRun.stages?.[s.id]?.status;
+        if (st === 'completed') completedCount++;
+        else if (st === 'running') runningCount++;
+        else if (st === 'failed') failedCount++;
+      });
+      var pct = Math.round((completedCount / totalStages) * 100);
+
+      // Segmented progress bar — one segment per stage
+      var segments = (p.stages || []).map(function(s) {
+        var st = displayRun.stages?.[s.id]?.status || 'pending';
+        var cls = st === 'completed' ? 'complete' : st === 'running' ? 'running' : st === 'failed' ? 'failed' : st === 'waiting-human' ? 'waiting' : 'pending';
+        return '<div class="pl-prog-seg ' + cls + '" style="width:' + (100 / totalStages) + '%" title="' + escHtml(s.id) + ': ' + st + '"></div>';
+      }).join('');
+
+      var statusParts = [];
+      if (completedCount) statusParts.push(completedCount + ' done');
+      if (runningCount) statusParts.push(runningCount + ' running');
+      if (failedCount) statusParts.push(failedCount + ' failed');
+      var remaining = totalStages - completedCount - runningCount - failedCount;
+      if (remaining > 0) statusParts.push(remaining + ' pending');
+
+      progressHtml = '<div class="pl-progress-wrap">' +
+        '<div class="pl-progress-bar">' + segments + '</div>' +
+        '<div class="pl-progress-label">' +
+          '<span style="font-weight:600;color:' + (pct === 100 ? 'var(--green)' : failedCount ? 'var(--red)' : 'var(--blue)') + '">' + pct + '%</span>' +
+          '<span style="color:var(--muted)">' + statusParts.join(' \u00b7 ') + '</span>' +
+        '</div>' +
+      '</div>';
+    }
+
     return '<div style="background:var(--surface);border:1px solid var(--border);border-radius:8px;padding:12px 16px;margin-bottom:8px;cursor:pointer" onclick="openPipelineDetail(\'' + escHtml(p.id) + '\')">' +
       '<div style="display:flex;justify-content:space-between;align-items:center">' +
         '<strong style="font-size:13px">' + escHtml(p.title) + '</strong>' +
@@ -39,6 +140,7 @@ function renderPipelines(pipelines) {
         '</div>' +
       '</div>' +
       '<div style="margin-top:6px;display:flex;gap:4px;align-items:center;flex-wrap:wrap">' + stageFlow + '</div>' +
+      progressHtml +
     '</div>';
   }).join('');
 }
@@ -61,7 +163,28 @@ function openPipelineDetail(id) {
     '</div>' +
   '</div>';
 
-  // Stage detail
+  // Stage detail with progress bar
+  var detailRun = activeRun || (p.runs || []).slice(-1)[0];
+  if (detailRun && (p.stages || []).length > 0) {
+    var dtotal = (p.stages || []).length;
+    var ddone = 0, drun = 0, dfail = 0;
+    (p.stages || []).forEach(function(s) {
+      var st = detailRun.stages?.[s.id]?.status;
+      if (st === 'completed') ddone++;
+      else if (st === 'running') drun++;
+      else if (st === 'failed') dfail++;
+    });
+    var dpct = Math.round((ddone / dtotal) * 100);
+    var dsegs = (p.stages || []).map(function(s) {
+      var st = detailRun.stages?.[s.id]?.status || 'pending';
+      var cls = st === 'completed' ? 'complete' : st === 'running' ? 'running' : st === 'failed' ? 'failed' : st === 'waiting-human' ? 'waiting' : 'pending';
+      return '<div class="pl-prog-seg ' + cls + '" style="width:' + (100 / dtotal) + '%" title="' + escHtml(s.id) + ': ' + st + '"></div>';
+    }).join('');
+    html += '<div class="pl-progress-wrap">' +
+      '<div class="pl-progress-bar" style="height:8px">' + dsegs + '</div>' +
+      '<div class="pl-progress-label"><span style="font-weight:600;color:' + (dpct === 100 ? 'var(--green)' : dfail ? 'var(--red)' : 'var(--blue)') + '">' + dpct + '% complete</span> <span style="color:var(--muted)">(' + ddone + '/' + dtotal + ' stages)</span></div>' +
+    '</div>';
+  }
   html += '<h4 style="font-size:12px;color:var(--blue);margin:0">Stages</h4>';
   (p.stages || []).forEach(function(s, i) {
     var stageRun = activeRun?.stages?.[s.id] || {};
@@ -75,6 +198,7 @@ function openPipelineDetail(id) {
         '<span style="color:' + statusColor + ';font-size:10px;font-weight:600">' + stageStatus.toUpperCase() + '</span>' +
       '</div>' +
       '<div style="font-size:10px;color:var(--muted);margin-top:4px">Type: ' + escHtml(s.type) + ' | Depends on: ' + escHtml(deps) + (s.agent ? ' | Agent: ' + escHtml(s.agent) : '') + '</div>' +
+      _renderArtifactLinks(stageRun.artifacts) +
       (stageRun.output ? '<div style="margin-top:6px;font-size:11px;max-height:150px;overflow-y:auto">' + renderMd(stageRun.output.slice(0, 500)) + '</div>' : '') +
       (stageStatus === 'waiting-human' ? '<button class="pr-pager-btn" style="font-size:9px;padding:2px 8px;color:var(--green);border-color:var(--green);margin-top:6px" onclick="_continuePipeline(\'' + escHtml(id) + '\',\'' + escHtml(s.id) + '\',this)">Continue</button>' : '') +
     '</div>';
@@ -84,12 +208,20 @@ function openPipelineDetail(id) {
   var runs = (p.runs || []).slice(-5).reverse();
   if (runs.length > 0) {
     html += '<h4 style="font-size:12px;color:var(--blue);margin:0">Recent Runs</h4>';
-    runs.forEach(function(r) {
+    runs.forEach(function(r, ri) {
       var color = r.status === 'completed' ? 'var(--green)' : r.status === 'failed' ? 'var(--red)' : r.status === 'running' ? 'var(--blue)' : 'var(--muted)';
-      html += '<div style="font-size:10px;display:flex;gap:8px;align-items:center">' +
-        '<span style="color:' + color + ';font-weight:600">' + r.status + '</span>' +
-        '<span style="color:var(--muted)">' + (r.startedAt ? new Date(r.startedAt).toLocaleString() : '') + '</span>' +
-        (r.completedAt ? '<span style="color:var(--muted)">\u2192 ' + new Date(r.completedAt).toLocaleString() + '</span>' : '') +
+      // Collect all artifacts across stages for this run
+      var runArtifacts = _collectRunArtifacts(r);
+      var artifactCount = runArtifacts.total;
+      var toggleId = 'run-artifacts-' + ri;
+      html += '<div style="font-size:10px">' +
+        '<div style="display:flex;gap:8px;align-items:center">' +
+          '<span style="color:' + color + ';font-weight:600">' + r.status + '</span>' +
+          '<span style="color:var(--muted)">' + (r.startedAt ? new Date(r.startedAt).toLocaleString() : '') + '</span>' +
+          (r.completedAt ? '<span style="color:var(--muted)">\u2192 ' + new Date(r.completedAt).toLocaleString() + '</span>' : '') +
+          (artifactCount > 0 ? '<span style="color:var(--blue);cursor:pointer;user-select:none" onclick="var el=document.getElementById(\'' + toggleId + '\');el.style.display=el.style.display===\'none\'?\'flex\':\'none\'" title="Toggle artifacts">' + artifactCount + ' artifact' + (artifactCount !== 1 ? 's' : '') + ' ▾</span>' : '') +
+        '</div>' +
+        (artifactCount > 0 ? '<div id="' + toggleId + '" style="display:none;flex-wrap:wrap;gap:4px;margin-top:4px;margin-left:12px">' + _renderArtifactLinks(runArtifacts.merged) + '</div>' : '') +
       '</div>';
     });
   }

package/dashboard/js/render-plans.js

@@ -66,9 +66,7 @@ function derivePlanStatus(prdFile, mdFile, prdJsonStatus, workItems) {
   const implementWi = wi.filter(w => w.type !== 'plan-to-prd' && w.type !== 'verify');
   const hasPendingPrd = wi.some(w => w.type === 'plan-to-prd' && (w.status === 'pending' || w.status === 'dispatched'));
   const hasActiveWork = implementWi.some(w => w.status === 'pending' || w.status === 'dispatched');
-  const allDone = implementWi.length > 0 && implementWi.every(w =>
-    w.status === 'done'
-  );
+  const allDone = implementWi.length > 0 && implementWi.every(w => w.status === 'done');
   const hasFailed = implementWi.some(w => w.status === 'failed');
 
   // User-set statuses take priority when no work has started
@@ -304,6 +302,48 @@ function openArchivedPlansModal() {
   document.getElementById('modal').classList.add('open');
 }
 
+// Disable all PRD action buttons to prevent double-clicks
+function qaDisablePrdButtons() {
+  const container = document.getElementById('qa-generate-prd-btn');
+  if (container) container.querySelectorAll('button').forEach(b => { b.disabled = true; b.style.opacity = '0.5'; });
+}
+
+// Show plan version action buttons (Run alongside / Replace / Just save)
+function showPlanVersionActions(thread, newFile, originalFile) {
+  const esc = newFile.replace(/'/g, "\\'");
+  // Look up existing PRD for the original plan's project
+  const allPlans = window._lastStatus?.plans || [];
+  const origPlan = allPlans.find(p => p.file === originalFile);
+  const project = origPlan?.project || '';
+  const existingPrd = allPlans.find(p => p.file.endsWith('.json') && p.project === project && p.status !== 'completed');
+
+  const btn = document.createElement('div');
+  btn.id = 'qa-generate-prd-btn';
+  btn.style.cssText = 'margin:8px 0;padding:8px 12px;background:rgba(63,185,80,0.1);border:1px solid rgba(63,185,80,0.3);border-radius:6px;display:flex;flex-wrap:wrap;align-items:center;gap:8px';
+
+  if (existingPrd) {
+    btn.innerHTML = '<span style="color:var(--green);font-weight:600;font-size:12px;width:100%">New plan version created — existing PRD running</span>' +
+      '<button onclick="qaNewPrd(\'' + esc + '\')" style="background:var(--green);color:#fff;border:none;border-radius:4px;padding:4px 12px;font-size:11px;font-weight:600;cursor:pointer" title="Execute this plan as a separate PRD alongside the current one">Run alongside</button>' +
+      '<button onclick="qaReplacePrd(\'' + esc + '\')" style="background:var(--orange);color:#fff;border:none;border-radius:4px;padding:4px 12px;font-size:11px;font-weight:600;cursor:pointer" title="Pause existing PRD, clean pending items, execute this plan instead">Replace old PRD</button>' +
+      '<button onclick="qaJustSave(this)" style="background:var(--surface2);color:var(--text);border:1px solid var(--border);border-radius:4px;padding:4px 12px;font-size:11px;cursor:pointer" title="Keep the new version saved without dispatching any work">Just save</button>' +
+      '<span style="color:var(--muted);font-size:10px;width:100%">Run alongside keeps current work going. Replace pauses it and starts fresh.</span>';
+  } else {
+    btn.innerHTML = '<span style="color:var(--green);font-weight:600;font-size:12px;width:100%">New plan version created</span>' +
+      '<button onclick="qaNewPrd(\'' + esc + '\')" style="background:var(--green);color:#fff;border:none;border-radius:4px;padding:4px 12px;font-size:11px;font-weight:600;cursor:pointer">Execute plan</button>' +
+      '<button onclick="qaJustSave(this)" style="background:var(--surface2);color:var(--text);border:1px solid var(--border);border-radius:4px;padding:4px 12px;font-size:11px;cursor:pointer">Just save</button>' +
+      '<span style="color:var(--muted);font-size:10px">Execute dispatches an agent to create PRD items from this plan</span>';
+  }
+  // Remove any previous action buttons
+  const old = thread.querySelector('#qa-generate-prd-btn');
+  if (old) old.remove();
+  thread.appendChild(btn);
+}
+
+function qaJustSave(el) {
+  const container = el.closest('#qa-generate-prd-btn');
+  if (container) container.innerHTML = '<span style="color:var(--muted);font-size:11px">Saved. No work dispatched.</span>';
+}
+
 async function planExecute(file, project, btn) {
   if (btn) { btn.textContent = 'Executing...'; btn.disabled = true; btn.style.color = 'var(--blue)'; }
   try {
@@ -694,4 +734,4 @@ async function planUnarchive(file, btn) {
   } catch (e) { resetBtn(); alert('Error: ' + e.message); }
 }
 
-window.MinionsPlans = { openCreatePlanModal, refreshPlans, derivePlanStatus, renderPlans, openArchivedPlansModal, planExecute, planSubmitRevise, planShowRevise, planHideRevise, planView, planApprove, planArchive, planUnarchive, planDelete, planPause, planReject, planDiscuss, planOpenInDocChat, planRegeneratePRD, openVerifyGuide, triggerVerify };
+window.MinionsPlans = { openCreatePlanModal, refreshPlans, derivePlanStatus, renderPlans, openArchivedPlansModal, qaDisablePrdButtons, showPlanVersionActions, qaJustSave, planExecute, planSubmitRevise, planShowRevise, planHideRevise, planView, planApprove, planArchive, planUnarchive, planDelete, planPause, planReject, planDiscuss, planOpenInDocChat, planRegeneratePRD, openVerifyGuide, triggerVerify };

package/dashboard/js/render-prd.js

@@ -116,7 +116,7 @@ function renderPrdProgress(prog) {
       'failed':      'background:rgba(248,81,73,0.15);color:var(--red)',
       'paused':      'background:rgba(139,148,158,0.15);color:var(--muted)',
     };
-    const labels = { 'done': 'DONE', 'in-progress': 'WIP', 'failed': 'FAIL', 'paused': 'PAUSED', 'missing': '—' };
+    const labels = { 'done': 'DONE', 'in-progress': 'WIP', 'failed': 'FAIL', 'paused': 'PAUSED', 'missing': '\u2014' };
     const style = styles[s] || 'background:var(--surface);color:var(--muted)';
     const label = labels[s] || '—';
     return '<span style="font-size:9px;font-weight:700;padding:2px 6px;border-radius:3px;letter-spacing:0.5px;white-space:nowrap;' + style + '">' + label + '</span>';

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

@@ -345,12 +345,22 @@ function openCreateWorkItemModal() {
       '</div>' +
       '<label style="color:var(--text);font-size:var(--text-md)">Acceptance Criteria <textarea id="wi-new-ac" rows="2" style="' + inputStyle + ';resize:vertical" placeholder="One criterion per line (optional)"></textarea></label>' +
       '<label style="color:var(--text);font-size:var(--text-md)">References <textarea id="wi-new-refs" rows="2" style="' + inputStyle + ';resize:vertical" placeholder="url | title | type — one per line (optional)"></textarea></label>' +
+      '<label id="wi-new-skippr-row" style="color:var(--text);font-size:var(--text-md);display:flex;gap:8px;align-items:center;cursor:pointer"><input type="checkbox" id="wi-new-skippr"> Skip PR creation (push branch only)</label>' +
       '<div style="display:flex;justify-content:flex-end;gap:8px;margin-top:4px">' +
         '<button onclick="closeModal()" class="pr-pager-btn">Cancel</button>' +
         '<button onclick="_submitCreateWorkItem()" style="padding:6px 16px;background:var(--blue);color:#fff;border:none;border-radius:var(--radius-sm);cursor:pointer">Create</button>' +
       '</div>' +
     '</div>';
   document.getElementById('modal').classList.add('open');
+  // Show skipPr checkbox only for implement/fix types
+  const typeSelect = document.getElementById('wi-new-type');
+  const skipPrRow = document.getElementById('wi-new-skippr-row');
+  function _toggleSkipPr() {
+    const v = typeSelect?.value || '';
+    if (skipPrRow) skipPrRow.style.display = (v === 'implement' || v === 'fix') ? 'flex' : 'none';
+  }
+  _toggleSkipPr();
+  if (typeSelect) typeSelect.addEventListener('change', _toggleSkipPr);
   setTimeout(() => document.getElementById('wi-new-title')?.focus(), 100);
 }
 
@@ -376,6 +386,8 @@ async function _submitCreateWorkItem() {
     if (project) body.project = project;
     if (acceptanceCriteria.length) body.acceptanceCriteria = acceptanceCriteria;
     if (references.length && references[0].url) body.references = references;
+    const skipPr = document.getElementById('wi-new-skippr')?.checked || false;
+    if (skipPr) body.skipPr = true;
 
     try { closeModal(); } catch { /* expected */ }
     showToast('cmd-toast', 'Creating work item...', true);

package/dashboard/styles.css

@@ -178,6 +178,18 @@
   .prd-legend-dot.complete { background: var(--green); }
   .prd-legend-dot.in-progress { background: var(--yellow); }
   .prd-legend-dot.missing { background: var(--border); }
+
+  /* Pipeline Step-Progress */
+  .pl-progress-wrap { margin-top: 8px; }
+  .pl-progress-bar { width: 100%; height: 6px; background: var(--bg); border-radius: 3px; overflow: hidden; display: flex; border: 1px solid var(--border); }
+  .pl-prog-seg { height: 100%; transition: background 0.3s ease; }
+  .pl-prog-seg.complete { background: var(--green); }
+  .pl-prog-seg.running { background: var(--blue); animation: plSegPulse 1.5s ease-in-out infinite; }
+  .pl-prog-seg.failed { background: var(--red); }
+  .pl-prog-seg.waiting { background: var(--yellow); }
+  .pl-prog-seg.pending { background: transparent; }
+  @keyframes plSegPulse { 0%, 100% { opacity: 1; } 50% { opacity: 0.5; } }
+  .pl-progress-label { display: flex; gap: 8px; align-items: center; margin-top: 4px; font-size: 10px; }
   .prd-items-list { display: flex; flex-direction: column; gap: 3px; max-height: 400px; overflow-y: auto; padding: 0 8px; }
   .prd-item-row { display: flex; align-items: center; gap: 8px; padding: 4px 8px; border-radius: var(--radius-sm); font-size: var(--text-base); background: var(--surface2); border: 1px solid var(--border); border-left: 3px solid var(--border); }
   .prd-item-row.st-done { border-left-color: var(--green); }

package/dashboard.js

@@ -1038,6 +1038,7 @@ const server = http.createServer(async (req, res) => {
       if (body.agents) item.agents = body.agents;
       if (body.references) item.references = body.references;
       if (body.acceptanceCriteria) item.acceptanceCriteria = body.acceptanceCriteria;
+      if (body.skipPr === true) item.skipPr = true;
       items.push(item);
       safeWrite(wiPath, items);
       return jsonReply(res, 200, { ok: true, id });
@@ -1076,6 +1077,7 @@ const server = http.createServer(async (req, res) => {
       if (agent !== undefined) item.agent = agent || null;
       if (body.references !== undefined) item.references = body.references;
       if (body.acceptanceCriteria !== undefined) item.acceptanceCriteria = body.acceptanceCriteria;
+      if (body.skipPr !== undefined) item.skipPr = body.skipPr === true;
       item.updatedAt = new Date().toISOString();
 
       safeWrite(wiPath, items);
@@ -1643,7 +1645,7 @@ If nothing to do: { "duplicates": [], "reclassify": [], "remove": [] }`;
             file: f, format: 'draft', archived,
             project: projectMatch ? projectMatch[1].trim() : '',
             summary: titleMatch ? titleMatch[1].trim() : f.replace('.md', ''),
-            status: archived ? 'completed' : completedPrdFiles.has(f) ? 'converted' : 'draft',
+            status: archived ? 'completed' : completedPrdFiles.has(f) ? 'approved' : 'active',
             branchStrategy: '',
             featureBranch: '',
             itemCount: (content.match(/^\d+\.\s+\*\*/gm) || []).length,
@@ -3057,7 +3059,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     }},
 
     // Work items
-    { method: 'POST', path: '/api/work-items', desc: 'Create a new work item', params: 'title, type?, description?, priority?, project?, agent?, agents?, scope?, references?, acceptanceCriteria?', handler: handleWorkItemsCreate },
+    { method: 'POST', path: '/api/work-items', desc: 'Create a new work item', params: 'title, type?, description?, priority?, project?, agent?, agents?, scope?, references?, acceptanceCriteria?, skipPr?', handler: handleWorkItemsCreate },
     { method: 'POST', path: '/api/work-items/update', desc: 'Edit a pending/failed work item', params: 'id, source?, title?, description?, type?, priority?, agent?, references?, acceptanceCriteria?', handler: handleWorkItemsUpdate },
     { method: 'POST', path: '/api/work-items/retry', desc: 'Reset a failed/dispatched item to pending', params: 'id, source?', handler: handleWorkItemsRetry },
     { method: 'POST', path: '/api/work-items/delete', desc: 'Remove a work item, kill agent, clear dispatch', params: 'id, source?', handler: handleWorkItemsDelete },
@@ -3136,12 +3138,10 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     { method: 'POST', path: '/api/plans/reject', desc: 'Reject a plan', params: 'file, rejectedBy?, reason?', handler: handlePlansReject },
     { method: 'POST', path: '/api/plans/regenerate', desc: 'Reset pending/failed work items for a plan so they re-materialize', params: 'source', handler: handlePlansRegenerate },
     { method: 'POST', path: '/api/plans/delete', desc: 'Delete a plan file and clean up work items', params: 'file', handler: handlePlansDelete },
-    { method: 'POST', path: '/api/plans/archive', desc: 'Move a plan/PRD to archive (preserves work items)', params: 'file', handler: handlePlansArchive },
+    { method: 'POST', path: '/api/plans/archive', desc: 'Archive a plan/PRD (move to archive folder, also archives source .md plan if PRD)', params: 'file', handler: handlePlansArchiveMove },
     { method: 'POST', path: '/api/plans/unarchive', desc: 'Restore a plan/PRD from archive', params: 'file', handler: handlePlansUnarchive },
     { method: 'POST', path: '/api/plans/revise', desc: 'Request revision with feedback, dispatches agent to revise', params: 'file, feedback, requestedBy?', handler: handlePlansRevise },
     { method: 'POST', path: '/api/plans/discuss', desc: 'Generate a plan discussion session script for Claude CLI', params: 'file', handler: handlePlansDiscuss },
-    { method: 'POST', path: '/api/plans/archive', desc: 'Archive a plan/PRD (move to archive folder)', params: 'file', handler: handlePlansArchiveMove },
-    { method: 'POST', path: '/api/plans/unarchive', desc: 'Unarchive a plan/PRD (restore from archive folder)', params: 'file', handler: handlePlansUnarchive },
     { method: 'GET', path: /^\/api\/plans\/archive\/([^?]+)$/, desc: 'Read an archived plan file', handler: handlePlansArchiveRead },
     { method: 'GET', path: /^\/api\/plans\/([^?]+)$/, desc: 'Read a full plan (JSON from prd/ or markdown from plans/)', handler: handlePlansRead },
 

package/engine/shared.js

@@ -501,7 +501,27 @@ function parseSkillFrontmatter(content, filename) {
 // Never touched by polling loops — only written when a PR is first linked to a PRD item.
 
 function getPrLinks() {
-  try { return JSON.parse(require('fs').readFileSync(PR_LINKS_PATH, 'utf8')); } catch { return {}; }
+  // Derive from PR.prdItems (single source of truth) + legacy pr-links.json as fallback
+  const links = {};
+  try {
+    const projects = getProjects();
+    for (const project of projects) {
+      const prs = safeJson(projectPrPath(project)) || [];
+      for (const pr of prs) {
+        for (const itemId of (pr.prdItems || [])) {
+          if (!links[pr.id]) links[pr.id] = itemId;
+        }
+      }
+    }
+  } catch { /* optional */ }
+  // Merge legacy pr-links.json for items not yet in PR.prdItems
+  try {
+    const legacy = JSON.parse(require('fs').readFileSync(PR_LINKS_PATH, 'utf8'));
+    for (const [prId, itemId] of Object.entries(legacy)) {
+      if (!links[prId]) links[prId] = itemId;
+    }
+  } catch { /* optional */ }
+  return links;
 }
 
 function addPrLink(prId, itemId) {
@@ -512,6 +532,33 @@ function addPrLink(prId, itemId) {
   safeWrite(PR_LINKS_PATH, links);
 }
 
+/**
+ * Locked mutation of a project's pull-requests.json.
+ * Single source of truth for PR data including prdItems links.
+ */
+function mutatePrs(project, mutateFn) {
+  const prPath = projectPrPath(project);
+  return mutateJsonFileLocked(prPath, (prs) => {
+    return mutateFn(Array.isArray(prs) ? prs : []);
+  }, { defaultValue: [] });
+}
+
+/**
+ * Link a PR to a work item via PR.prdItems (single source of truth).
+ * Uses file-locked mutation to prevent race conditions.
+ */
+function linkPrToItem(project, prId, itemId) {
+  if (!prId || !itemId) return;
+  mutatePrs(project, (prs) => {
+    const pr = prs.find(p => p.id === prId);
+    if (pr) {
+      pr.prdItems = Array.isArray(pr.prdItems) ? pr.prdItems : [];
+      if (!pr.prdItems.includes(itemId)) pr.prdItems.push(itemId);
+    }
+    return prs;
+  });
+}
+
 module.exports = {
   MINIONS_DIR,
   PR_LINKS_PATH,
@@ -549,6 +596,8 @@ module.exports = {
   projectPrPath,
   getPrLinks,
   addPrLink,
+  mutatePrs,
+  linkPrToItem,
   nextWorkItemId,
   getAdoOrgBase,
   sanitizePath,

package/engine.js

@@ -307,7 +307,7 @@ function spawnAgent(dispatchItem, config) {
 
           if (isSharedBranch) {
             log('info', `Creating worktree for shared branch: ${worktreePath} on ${branchName}`);
-            try { exec(`git fetch origin "${branchName}"`, { ..._gitOpts, cwd: rootDir }); } catch (e) { log('warn', 'git: ' + e.message); }
+            try { exec(`git fetch origin "${branchName}"`, { ..._gitOpts, cwd: rootDir }); } catch (e) { log('warn', 'git fetch: ' + e.message); }
             try {
               runWorktreeAdd(rootDir, worktreePath, `"${branchName}"`, _worktreeGitOpts, worktreeCreateRetries);
             } catch (eShared) {
@@ -317,6 +317,11 @@ function spawnAgent(dispatchItem, config) {
                   log('info', `Shared branch ${branchName} already checked out at ${existingWtPath} — reusing`);
                   worktreePath = existingWtPath;
                 } else { throw eShared; }
+              } else if (eShared.message?.includes('invalid reference') || eShared.message?.includes('not a valid branch')) {
+                // Branch doesn't exist yet — create it from main
+                log('info', `Shared branch ${branchName} not found — creating from ${project.mainBranch || 'main'}`);
+                const mainRef = sanitizeBranch(project.mainBranch || 'main');
+                runWorktreeAdd(rootDir, worktreePath, `-b "${branchName}" ${mainRef}`, _worktreeGitOpts, worktreeCreateRetries);
               } else { throw eShared; }
             }
           } else {
@@ -1190,9 +1195,17 @@ function materializePlansAsWorkItems(config) {
           const root = path.resolve(firstProject.localPath);
           const mainBranch = firstProject.mainBranch || 'main';
           const branch = sanitizeBranch(plan.feature_branch);
-          // Create branch from main (idempotent — ignores if exists)
-          exec(`git branch "${branch}" "${mainBranch}" 2>/dev/null || true`, { cwd: root, stdio: 'pipe' });
-          exec(`git push -u origin "${branch}" 2>/dev/null || true`, { cwd: root, stdio: 'pipe' });
+          // Create branch from main — verify it actually succeeded
+          try {
+            exec(`git branch "${branch}" "${mainBranch}"`, { cwd: root, stdio: 'pipe', windowsHide: true });
+          } catch (e) {
+            // Branch may already exist — that's fine
+            if (!e.message?.includes('already exists')) throw e;
+          }
+          // Push to remote (best-effort — may not have a remote)
+          try {
+            exec(`git push -u origin "${branch}"`, { cwd: root, stdio: 'pipe', windowsHide: true, timeout: 15000 });
+          } catch { /* no remote or push failed — branch still exists locally */ }
           log('info', `Shared branch pre-created: ${branch} for plan ${file}`);
         } catch (err) {
           log('warn', `Failed to pre-create shared branch for ${file}: ${err.message}`);
@@ -1373,6 +1386,7 @@ function discoverFromWorkItems(config, project) {
       }
     }
 
+    if (item.status === 'needs-human-review') continue; // Explicit skip — flagged for human attention
     if (item.status !== 'queued' && item.status !== 'pending') continue;
 
     // Dependency gate: skip items whose depends_on are not yet met; propagate failure
@@ -1474,6 +1488,11 @@ function discoverFromWorkItems(config, project) {
     const ac = (Array.isArray(item.acceptanceCriteria) ? item.acceptanceCriteria : []).map(c => '- [ ] ' + c).join('\n');
     vars.acceptance_criteria = ac ? '## Acceptance Criteria\n\n' + ac : '';
 
+    // Inject PR section — conditional based on skipPr flag
+    vars.pr_section = item.skipPr
+      ? '## Push Branch\n\n**PR creation is skipped for this work item.** Push your branch and report the branch name.\n\n```bash\ngit push -u origin {{branch_name}}\n```\n\nInclude the branch name in your completion summary.'
+      : '## Create PR (MANDATORY)\n\n**Your task is NOT complete until a pull request exists.** If PR creation fails, retry up to 3 times before reporting the error.\n\n{{pr_create_instructions}}\n- sourceRefName: `refs/heads/{{branch_name}}`\n- targetRefName: `refs/heads/{{main_branch}}`\n- title: `{{commit_message}}`\n- labels: `["minions:{{agent_id}}"]`\n\nInclude in the PR description:\n- What was built and why\n- Files changed\n- How to build and test, browser URL if applicable\n- Test plan\n\n## Post self-review on PR\n\n{{pr_comment_instructions}}\n- pullRequestId: `<from PR creation>`\n- Re-read your own diff critically before posting\n- Sign: `Built by Minions ({{agent_name}} — {{agent_role}})`';
+
     // Inject checkpoint context if agent left a checkpoint.json from a prior run
     vars.checkpoint_context = '';
     try {
@@ -1559,15 +1578,13 @@ function discoverFromWorkItems(config, project) {
     setCooldown(key);
   }
 
-  // Write back updated statuses (always, since we mark items dispatched before newWork check)
-  if (newWork.length > 0) {
+  // Write back updated statuses — needsWrite covers mutation-only ticks, newWork covers dispatches
+  if (needsWrite || newWork.length > 0) {
     const workItemsPath = projectWorkItemsPath(project);
     safeWrite(workItemsPath, items);
     for (const s of prdSyncQueue) syncPrdItemStatus(s.id, 'dispatched', s.sourcePlan);
   }
 
-  if (needsWrite) safeWrite(projectWorkItemsPath(project), items);
-
   const skipTotal = skipped.gated + skipped.noAgent;
   if (skipTotal > 0) {
     log('debug', `Work item discovery (${project?.name}): skipped ${skipTotal} items (${skipped.gated} gated, ${skipped.noAgent} no agent)`);
@@ -1755,8 +1772,10 @@ function discoverCentralWorkItems(config) {
   const items = safeJson(centralPath) || [];
   const projects = getProjects(config);
   const newWork = [];
+  let needsWrite = false;
 
   for (const item of items) {
+    if (item.status === 'needs-human-review') continue; // Explicit skip — flagged for human attention
     if (item.status !== 'queued' && item.status !== 'pending') continue;
 
     const key = `central-work-${item.id}`;
@@ -1809,6 +1828,12 @@ function discoverCentralWorkItems(config) {
         const fanAc = (Array.isArray(item.acceptanceCriteria) ? item.acceptanceCriteria : []).map(c => '- [ ] ' + c).join('\n');
         vars.acceptance_criteria = fanAc ? '## Acceptance Criteria\n\n' + fanAc : '';
 
+        // Inject PR section — conditional based on skipPr flag
+        const fanBranch = '{{branch_name}}';
+        vars.pr_section = item.skipPr
+          ? '## Push Branch\n\n**PR creation is skipped for this work item.** Push your branch and report the branch name.\n\n```bash\ngit push -u origin ' + fanBranch + '\n```\n\nInclude the branch name in your completion summary.'
+          : '## Create PR (MANDATORY)\n\n**Your task is NOT complete until a pull request exists.** If PR creation fails, retry up to 3 times before reporting the error.\n\n{{pr_create_instructions}}\n- sourceRefName: `refs/heads/' + fanBranch + '`\n- targetRefName: `refs/heads/{{main_branch}}`\n- title: `{{commit_message}}`\n- labels: `["minions:{{agent_id}}"]`\n\nInclude in the PR description:\n- What was built and why\n- Files changed\n- How to build and test, browser URL if applicable\n- Test plan\n\n## Post self-review on PR\n\n{{pr_comment_instructions}}\n- pullRequestId: `<from PR creation>`\n- Re-read your own diff critically before posting\n- Sign: `Built by Minions ({{agent_name}} — {{agent_role}})`';
+
         if (workType === 'ask') {
           vars.question = item.title + (item.description ? '\n\n' + item.description : '');
           vars.task_id = item.id;
@@ -1828,7 +1853,7 @@ function discoverCentralWorkItems(config) {
         if (!prompt) {
           if (renderError) {
             log('warn', `Fan-out: ${item.id} → ${agent.id}: ${renderError.message}`);
-            if (item._pendingReason !== 'critical_vars_missing') { item._pendingReason = 'critical_vars_missing'; }
+            if (item._pendingReason !== 'critical_vars_missing') { item._pendingReason = 'critical_vars_missing'; needsWrite = true; }
           } else {
             log('warn', `Fan-out: playbook '${playbookName}' failed to render for ${item.id} → ${agent.id}, skipping`);
           }
@@ -1854,6 +1879,7 @@ function discoverCentralWorkItems(config) {
       item.dispatched_to = idleAgents.map(a => a.id).join(', ');
       item.scope = 'fan-out';
       item.fanOutAgents = idleAgents.map(a => a.id);
+      needsWrite = true;
       setCooldown(key);
       log('info', `Fan-out: ${item.id} dispatched to ${idleAgents.length} agents: ${idleAgents.map(a => a.name).join(', ')}`);
 
@@ -1981,10 +2007,12 @@ function discoverCentralWorkItems(config) {
         if (renderError) {
           log('warn', `Dispatch: ${item.id}: ${renderError.message}`);
           item._pendingReason = 'critical_vars_missing';
+          needsWrite = true;
         } else {
           log('warn', `Dispatch: playbook '${playbookName}' failed to render for ${item.id}, resetting to pending`);
         }
         item.status = 'pending';
+        needsWrite = true;
         continue;
       }
 
@@ -2001,11 +2029,12 @@ function discoverCentralWorkItems(config) {
       item.status = 'dispatched';
       item.dispatched_at = ts();
       item.dispatched_to = agentId;
+      needsWrite = true;
       setCooldown(key);
     }
   }
 
-  if (newWork.length > 0) safeWrite(centralPath, items);
+  if (needsWrite || newWork.length > 0) safeWrite(centralPath, items);
   return newWork;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.154",
+  "version": "0.1.156",
   "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/implement.md

@@ -50,28 +50,7 @@ git push -u origin {{branch_name}}
 
 Do NOT remove the worktree — the engine handles cleanup automatically.
 
-## Create PR (MANDATORY)
-
-**Your task is NOT complete until a pull request exists.** If PR creation fails, retry up to 3 times before reporting the error.
-
-{{pr_create_instructions}}
-- sourceRefName: `refs/heads/{{branch_name}}`
-- targetRefName: `refs/heads/{{main_branch}}`
-- title: `{{commit_message}}`
-- labels: `["minions:{{agent_id}}"]`
-
-Include in the PR description:
-- What was built and why
-- Files changed
-- How to build and test, browser URL if applicable
-- Test plan
-
-## Post self-review on PR
-
-{{pr_comment_instructions}}
-- pullRequestId: `<from PR creation>`
-- Re-read your own diff critically before posting
-- Sign: `Built by Minions ({{agent_name}} — {{agent_role}})`
+{{pr_section}}
 
 ## Signal Completion