@yemi33/minions 0.1.547 → 0.1.549

package/CHANGELOG.md

@@ -1,6 +1,16 @@
 # Changelog
 
-## 0.1.547 (2026-04-07)
+## 0.1.549 (2026-04-07)
+
+### Fixes
+-  prefer git rev-parse over .minions-commit for disk version detection
+
+## 0.1.548 (2026-04-07)
+
+### Features
+-  auto-enrich linked PRs, progressive markdown rendering, KB sort
+- extract buildWorkItemDispatchVars() from duplicated discovery code (#467)
+- Replace JSON.parse(safeRead()) with safeJsonArr/safeJsonObj in dashboard.js (#465)
 
 ### Fixes
 - remap sequential PRD item IDs to prevent cross-PRD collisions (#474)

package/bin/minions.js

@@ -217,6 +217,11 @@ function getInstalledVersion() {
 
 function saveInstalledVersion(version) {
   fs.writeFileSync(path.join(MINIONS_HOME, '.minions-version'), version);
+  // Persist source commit so dashboard can detect repo-based installs
+  try {
+    const commit = execSync('git rev-parse --short HEAD', { cwd: PKG_ROOT, encoding: 'utf8', timeout: 5000, windowsHide: true }).trim();
+    if (commit) fs.writeFileSync(path.join(MINIONS_HOME, '.minions-commit'), commit);
+  } catch {}
 }
 
 // ─── Init / Upgrade ─────────────────────────────────────────────────────────

package/dashboard/js/render-plans.js

@@ -381,10 +381,12 @@ function planHideRevise(file) {
 
 let _planPollInterval = null;
 let _planPollFile = null;
+let _planPollLastRaw = null;
 
 function _stopPlanPoll() {
   if (_planPollInterval) { clearInterval(_planPollInterval); _planPollInterval = null; }
   _planPollFile = null;
+  _planPollLastRaw = null;
 }
 
 function _renderPlanModal(normalizedFile, raw, lastMod) {
@@ -488,6 +490,7 @@ async function planView(file) {
     const raw = await planRes.text();
 
     const { title, text } = _renderPlanModal(normalizedFile, raw, lastMod);
+    _planPollLastRaw = raw;
 
     _modalDocContext = { title, content: text, selection: '' };
     _modalFilePath = resolvedPath || ((normalizedFile.endsWith('.json') ? 'prd/' : 'plans/') + normalizedFile); showModalQa();
@@ -502,7 +505,7 @@ async function planView(file) {
       }
       fetch('/api/plans/' + encodeURIComponent(normalizedFile))
         .then(function(r) { return r.text().then(function(raw) { return { raw: raw, lastMod: r.headers.get('Last-Modified') }; }); })
-        .then(function(d) { if (_planPollFile === normalizedFile) _renderPlanModal(normalizedFile, d.raw, d.lastMod); })
+        .then(function(d) { if (_planPollFile === normalizedFile && d.raw !== _planPollLastRaw) { _planPollLastRaw = d.raw; _renderPlanModal(normalizedFile, d.raw, d.lastMod); } })
         .catch(function() {});
     }, 3000);
   } catch (e) { console.error(e); }

package/dashboard/js/render-prs.js

@@ -20,7 +20,7 @@ function prRow(pr) {
   const prId = pr.id || '—';
   return '<tr>' +
     '<td><span class="pr-id">' + escHtml(String(prId)) + '</span></td>' +
-    '<td><a class="pr-title" href="' + escHtml(safeUrl(url)) + '" target="_blank" rel="noopener">' + escHtml(pr.title || 'Untitled') + '</a></td>' +
+    '<td><a class="pr-title" href="' + escHtml(safeUrl(url)) + '" target="_blank" rel="noopener">' + escHtml(pr.title || 'Untitled') + '</a>' + (pr.description ? '<div class="pr-desc">' + escHtml(pr.description.length > 120 ? pr.description.slice(0, 120) + '...' : pr.description) + '</div>' : '') + '</td>' +
     '<td><span class="pr-agent">' + escHtml(pr.agent || '—') + '</span></td>' +
     '<td><span class="pr-branch">' + escHtml(pr.branch || '—') + '</span></td>' +
     '<td><span class="pr-badge ' + reviewClass + '">' + escHtml(reviewLabel) + '</span></td>' +

package/dashboard/js/utils.js

@@ -60,8 +60,11 @@ function copyLlmText(btn) {
  */
 function renderMd(s) {
   if (!s) return '';
-  // Truncate excessively long inputs to prevent regex backtracking
-  if (s.length > 10000) s = s.slice(0, 10000) + '\n\n…(truncated)';
+  if (s.length > 10000) return _renderMdChunked(s);
+  return _renderMdCore(s);
+}
+
+function _renderMdCore(s) {
   let html = escHtml(s);
 
   // 1. Extract code blocks and inline code into placeholders (protect from other transforms)
@@ -199,6 +202,78 @@ function renderMd(s) {
   return '<div class="md-content">' + html + '</div>';
 }
 
+var MD_CHUNK_SIZE = 10000;
+var _mdChunkUid = 0;
+
+function _renderMdChunked(fullText) {
+  // Split at blank-line boundaries to avoid breaking code blocks and other multi-line elements
+  var chunks = [];
+  var pos = 0;
+  while (pos < fullText.length) {
+    if (pos + MD_CHUNK_SIZE >= fullText.length) {
+      chunks.push(fullText.slice(pos));
+      break;
+    }
+    var target = pos + MD_CHUNK_SIZE;
+    var searchStart = Math.max(pos + Math.floor(MD_CHUNK_SIZE * 0.7), pos);
+    var searchEnd = Math.min(target + 500, fullText.length);
+    var slice = fullText.slice(searchStart, searchEnd);
+    var lastBlank = slice.lastIndexOf('\n\n');
+    var best;
+    if (lastBlank !== -1) {
+      best = searchStart + lastBlank + 2;
+    } else {
+      var nl = fullText.indexOf('\n', target);
+      best = (nl !== -1 && nl - target < 500) ? nl + 1 : target;
+    }
+    chunks.push(fullText.slice(pos, best));
+    pos = best;
+  }
+
+  var firstHtml = _renderMdCore(chunks[0]);
+  var uid = '_mdChunk' + (++_mdChunkUid);
+  if (chunks.length <= 1) return firstHtml;
+
+  var sentinel = '<div id="' + uid + '" style="padding:12px 0;color:var(--muted);font-size:11px">Loading more content...</div>';
+
+  setTimeout(function() {
+    var el = document.getElementById(uid);
+    if (!el) return;
+    var scrollParent = el.closest('.modal-body') || el.parentElement;
+    var idx = 1;
+    var obs = null;
+    function loadNext() {
+      if (idx >= chunks.length) {
+        if (obs) obs.disconnect();
+        el.remove();
+        return;
+      }
+      el.insertAdjacentHTML('beforebegin', _renderMdCore(chunks[idx]));
+      idx++;
+      if (idx >= chunks.length) {
+        if (obs) obs.disconnect();
+        el.remove();
+      }
+    }
+    if (typeof IntersectionObserver !== 'undefined') {
+      obs = new IntersectionObserver(function(entries) {
+        if (!entries[0].isIntersecting) return;
+        loadNext();
+        // Yield to browser for paint before re-observing, so rapid chunk loads don't block rendering
+        if (idx < chunks.length && el.parentNode) {
+          obs.unobserve(el);
+          requestAnimationFrame(function() { if (el.parentNode) obs.observe(el); });
+        }
+      }, { root: scrollParent, rootMargin: '200px' });
+      obs.observe(el);
+    } else {
+      var timer = setInterval(function() { loadNext(); if (idx >= chunks.length) clearInterval(timer); }, 100);
+    }
+  }, 0);
+
+  return firstHtml + sentinel;
+}
+
 function openBugReport() {
   document.getElementById('modal-title').textContent = 'Report a Bug';
   document.getElementById('modal-body').innerHTML =

package/dashboard/styles.css

@@ -236,6 +236,7 @@
   .pr-table tr:hover { background: var(--surface2); }
   .pr-title { color: var(--blue); text-decoration: none; font-weight: 500; }
   .pr-title:hover { text-decoration: underline; }
+  .pr-desc { color: var(--muted); font-size: var(--text-sm); font-weight: 400; margin-top: 2px; line-height: 1.4; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; max-width: 400px; }
   .pr-id { color: var(--muted); font-family: Consolas, monospace; font-size: var(--text-base); }
   .pr-agent { font-size: var(--text-base); color: var(--text); }
   .pr-branch { font-family: Consolas, monospace; font-size: var(--text-sm); color: var(--muted); background: var(--bg); padding: var(--space-1) var(--space-3); border-radius: 3px; border: 1px solid var(--border); }

package/dashboard.js

@@ -230,7 +230,11 @@ function getDiskVersion() {
     try { diskVersion = require('@yemi33/minions/package.json').version; } catch {}
   }
   let diskCommit = null;
+  // Prefer git (authoritative for repo-based dev), fall back to .minions-commit (installed copies)
   try { diskCommit = require('child_process').execSync('git rev-parse --short HEAD', { cwd: MINIONS_DIR, encoding: 'utf8', timeout: 5000, windowsHide: true }).trim(); } catch {}
+  if (!diskCommit) {
+    try { diskCommit = fs.readFileSync(path.join(MINIONS_DIR, '.minions-commit'), 'utf8').trim() || null; } catch {}
+  }
   _diskVersionCache = { diskVersion, diskCommit };
   _diskVersionCacheTs = now;
   return _diskVersionCache;
@@ -240,7 +244,7 @@ function getMcpServers() {
   try {
     const home = os.homedir();
     const claudeJsonPath = path.join(home, '.claude.json');
-    const data = JSON.parse(safeRead(claudeJsonPath) || '{}');
+    const data = safeJsonObj(claudeJsonPath);
     const servers = data.mcpServers || {};
     return Object.entries(servers).map(([name, cfg]) => ({
       name,
@@ -1082,7 +1086,7 @@ const server = http.createServer(async (req, res) => {
       }) || PROJECTS[0] || null;
       if (project) {
         const wiPath = shared.projectWorkItemsPath(project);
-        const items = JSON.parse(safeRead(wiPath) || '[]');
+        const items = safeJsonArr(wiPath);
         const verify = items.find(w => w.sourcePlan === body.file && w.itemType === 'verify');
         if (verify) {
           return jsonReply(res, 200, { ok: true, verifyId: verify.id });
@@ -1150,7 +1154,7 @@ const server = http.createServer(async (req, res) => {
       // Clear cooldown so item isn't blocked by exponential backoff
       try {
         const cooldownPath = path.join(MINIONS_DIR, 'engine', 'cooldowns.json');
-        const cooldowns = JSON.parse(safeRead(cooldownPath) || '{}');
+        const cooldowns = safeJsonObj(cooldownPath);
         if (cooldowns[dispatchKey]) {
           delete cooldowns[dispatchKey];
           safeWrite(cooldownPath, cooldowns);
@@ -1201,7 +1205,7 @@ const server = http.createServer(async (req, res) => {
       // Clean cooldown entries so item can be re-created immediately
       try {
         const cooldownPath = path.join(MINIONS_DIR, 'engine', 'cooldowns.json');
-        const cooldowns = JSON.parse(safeRead(cooldownPath) || '{}');
+        const cooldowns = safeJsonObj(cooldownPath);
         let cleaned = false;
         for (const key of Object.keys(cooldowns)) {
           if (key.includes(id)) { delete cooldowns[key]; cleaned = true; }
@@ -1525,7 +1529,7 @@ const server = http.createServer(async (req, res) => {
     try {
       const body = await readBody(req);
       const dispatchPath = path.join(MINIONS_DIR, 'engine', 'dispatch.json');
-      const dispatch = JSON.parse(safeRead(dispatchPath) || '{}');
+      const dispatch = safeJsonObj(dispatchPath);
       const active = dispatch.active || [];
       const cancelled = [];
 
@@ -1537,7 +1541,7 @@ const server = http.createServer(async (req, res) => {
         // Kill agent process
         const statusPath = path.join(MINIONS_DIR, 'agents', d.agent, 'status.json');
         try {
-          const status = JSON.parse(safeRead(statusPath) || '{}');
+          const status = safeJsonObj(statusPath);
           if (status.pid) {
             try {
               const safePid = shared.validatePid(status.pid);
@@ -1907,7 +1911,7 @@ If nothing to do: { "duplicates": [], "reclassify": [], "remove": [] }`;
       { dir: path.join(PRD_DIR, 'archive'), archived: true },
     ];
     // Load work items to check for completed plan-to-prd conversions
-    const centralWi = JSON.parse(safeRead(path.join(MINIONS_DIR, 'work-items.json')) || '[]');
+    const centralWi = safeJsonArr(path.join(MINIONS_DIR, 'work-items.json'));
     const completedPrdFiles = new Set(
       centralWi.filter(w => w.type === 'plan-to-prd' && w.status === 'done' && w.planFile)
         .map(w => w.planFile)
@@ -2048,7 +2052,7 @@ If nothing to do: { "duplicates": [], "reclassify": [], "remove": [] }`;
       const body = await readBody(req);
       if (!body.file) return jsonReply(res, 400, { error: 'file required' });
       const planPath = resolvePlanPath(body.file);
-      const plan = JSON.parse(safeRead(planPath) || '{}');
+      const plan = safeJsonObj(planPath);
       plan.status = 'approved';
       plan.approvedAt = new Date().toISOString();
       plan.approvedBy = body.approvedBy || os.userInfo().username;
@@ -2101,7 +2105,7 @@ If nothing to do: { "duplicates": [], "reclassify": [], "remove": [] }`;
       const body = await readBody(req);
       if (!body.file) return jsonReply(res, 400, { error: 'file required' });
       const planPath = resolvePlanPath(body.file);
-      const plan = JSON.parse(safeRead(planPath) || '{}');
+      const plan = safeJsonObj(planPath);
       plan.status = 'paused';
       plan.pausedAt = new Date().toISOString();
       safeWrite(planPath, plan);
@@ -2134,7 +2138,7 @@ If nothing to do: { "duplicates": [], "reclassify": [], "remove": [] }`;
                   if (activeEntry) {
                     const statusPath = path.join(MINIONS_DIR, 'agents', activeEntry.agent, 'status.json');
                     try {
-                      const agentStatus = JSON.parse(safeRead(statusPath) || '{}');
+                      const agentStatus = safeJsonObj(statusPath);
                       if (agentStatus.pid) {
                         try {
                           const safePid = shared.validatePid(agentStatus.pid);
@@ -2293,7 +2297,7 @@ If nothing to do: { "duplicates": [], "reclassify": [], "remove": [] }`;
       const body = await readBody(req);
       if (!body.file) return jsonReply(res, 400, { error: 'file required' });
       const planPath = resolvePlanPath(body.file);
-      const plan = JSON.parse(safeRead(planPath) || '{}');
+      const plan = safeJsonObj(planPath);
       plan.status = 'rejected';
       plan.rejectedAt = new Date().toISOString();
       plan.rejectedBy = body.rejectedBy || os.userInfo().username;
@@ -2375,7 +2379,7 @@ If nothing to do: { "duplicates": [], "reclassify": [], "remove": [] }`;
       // Read PRD content before deleting to get source_plan for cleanup
       let prdSourcePlan = null;
       if (body.file.endsWith('.json')) {
-        try { prdSourcePlan = JSON.parse(safeRead(planPath) || '{}').source_plan || null; } catch {}
+        try { prdSourcePlan = safeJsonObj(planPath).source_plan || null; } catch {}
       }
       safeUnlink(planPath);
 
@@ -2442,7 +2446,7 @@ If nothing to do: { "duplicates": [], "reclassify": [], "remove": [] }`;
       let archivedSource = null;
       if (body.file.endsWith('.json')) {
         try {
-          const prd = JSON.parse(safeRead(archivePath) || '{}');
+          const prd = safeJsonObj(archivePath);
           prd.status = 'archived';
           prd.archivedAt = new Date().toISOString();
           safeWrite(archivePath, prd);
@@ -2501,7 +2505,7 @@ If nothing to do: { "duplicates": [], "reclassify": [], "remove": [] }`;
       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 = JSON.parse(safeRead(planPath) || '{}');
+      const plan = safeJsonObj(planPath);
       plan.status = 'revision-requested';
       plan.revision_feedback = body.feedback;
       plan.revisionRequestedAt = new Date().toISOString();
@@ -2546,7 +2550,7 @@ If nothing to do: { "duplicates": [], "reclassify": [], "remove": [] }`;
         sourcePlanFile = body.sourcePlan;
       } else {
         // Heuristic: find .md plan by matching prefix or by reading PRD's generated_from field
-        const prd = JSON.parse(safeRead(prdPath) || '{}');
+        const prd = safeJsonObj(prdPath);
         if (prd.source_plan) {
           sourcePlanFile = prd.source_plan;
         } else {
@@ -2596,7 +2600,7 @@ If nothing to do: { "duplicates": [], "reclassify": [], "remove": [] }`;
       safeWrite(sourcePlanPath, result.content);
 
       // Step 2: Pause the old PRD so it stops materializing items
-      const prd = JSON.parse(safeRead(prdPath) || '{}');
+      const prd = safeJsonObj(prdPath);
       prd.status = 'revision-requested';
       prd.revision_feedback = body.instruction;
       prd.revisionRequestedAt = new Date().toISOString();
@@ -2826,7 +2830,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
                 const wiPaths = [path.join(MINIONS_DIR, 'work-items.json')];
                 for (const proj of PROJECTS) wiPaths.push(shared.projectWorkItemsPath(proj));
                 const dispatchPath = path.join(MINIONS_DIR, 'engine', 'dispatch.json');
-                const dispatch = JSON.parse(safeRead(dispatchPath) || '{}');
+                const dispatch = safeJsonObj(dispatchPath);
                 const killedAgents = new Set();
                 const resetItemIds = new Set();
                 for (const wiPath of wiPaths) {
@@ -2841,7 +2845,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
                           if (activeEntry) {
                             const statusPath = path.join(MINIONS_DIR, 'agents', activeEntry.agent, 'status.json');
                             try {
-                              const agentStatus = JSON.parse(safeRead(statusPath) || '{}');
+                              const agentStatus = safeJsonObj(statusPath);
                               if (agentStatus.pid) {
                                 try {
                                   const safePid = shared.validatePid(agentStatus.pid);
@@ -3822,6 +3826,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         prs.push({
           id: prId,
           title: (title || 'PR #' + prNum + ' (polling...)').slice(0, 120),
+          description: '',
           agent: 'human',
           branch: '',
           reviewStatus: autoObserve ? 'pending' : 'none',
@@ -3837,7 +3842,47 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       }, { defaultValue: [] });
       if (duplicate) return jsonReply(res, 400, { error: 'PR already tracked' });
       invalidateStatusCache();
-      return jsonReply(res, 200, { ok: true, id: prId });
+      jsonReply(res, 200, { ok: true, id: prId });
+
+      // Async-enrich: fetch title, description, branch, author from GitHub/ADO API
+      (async () => {
+        try {
+          let prData = null;
+          const ghMatch = url.match(/github\.com\/([^/]+\/[^/]+)\/pull\/(\d+)/);
+          const adoMatch = url.match(/dev\.azure\.com\/([^/]+)\/([^/]+)\/_git\/([^/]+)\/pullrequest\/(\d+)/);
+          if (ghMatch) {
+            const slug = ghMatch[1];
+            const result = await shared.execAsync(`gh api "repos/${slug}/pulls/${prNum}"`, { timeout: 15000, encoding: 'utf-8' });
+            const d = JSON.parse(result);
+            prData = { title: d.title, description: d.body, branch: d.head?.ref, author: d.user?.login };
+          } else if (adoMatch) {
+            const [, adoOrg, adoProj, adoRepo] = adoMatch;
+            try {
+              const { getAdoToken } = require('./engine/ado');
+              const token = await getAdoToken();
+              if (token) {
+                const apiUrl = `https://dev.azure.com/${adoOrg}/${adoProj}/_apis/git/repositories/${adoRepo}/pullrequests/${prNum}?api-version=7.1`;
+                const result = await shared.execAsync(`curl -s --max-time 10 -H "Authorization: Bearer ${token}" "${apiUrl}"`, { encoding: 'utf-8', timeout: 15000, windowsHide: true });
+                const d = JSON.parse(result);
+                prData = { title: d.title, description: d.description, branch: d.sourceRefName?.replace('refs/heads/', ''), author: d.createdBy?.displayName };
+              }
+            } catch { /* ADO token may not be available */ }
+          }
+          if (!prData) return;
+          mutateJsonFileLocked(prPath, (prs) => {
+            const pr = prs.find(p => p.id === prId);
+            if (!pr) return prs;
+            if (!title && prData.title) pr.title = prData.title.slice(0, 120);
+            if (prData.description) pr.description = prData.description.slice(0, 500);
+            if (!pr.branch && prData.branch) pr.branch = prData.branch;
+            if (pr.agent === 'human' && prData.author) pr.agent = prData.author;
+            return prs;
+          }, { defaultValue: [] });
+          invalidateStatusCache();
+        } catch (e) {
+          shared.log('warn', `PR link enrichment failed for ${prId}: ${e.message}`);
+        }
+      })();
     }},
 
     { method: 'POST', path: '/api/pull-requests/delete', desc: 'Remove a PR from tracking', params: 'id, project?', handler: async (req, res) => {

package/engine/queries.js

@@ -547,6 +547,7 @@ function getKnowledgeBaseEntries() {
       });
     }
   }
+  entries.sort((a, b) => (b.date || '').localeCompare(a.date || ''));
   _kbCache = entries;
   _kbCacheTs = now;
   return entries;

package/engine.js

@@ -1655,61 +1655,21 @@ function discoverFromWorkItems(config, project) {
       commit_message: item.commitMessage || `feat: ${item.title || item.id}`,
       notes_content: '',
     };
-    try { vars.notes_content = fs.readFileSync(path.join(MINIONS_DIR, 'notes.md'), 'utf8'); } catch { /* optional */ }
-
-    // Inject references and acceptance criteria
-    const refs = (item.references || []).filter(r => r && r.url).map(r =>
-      '- [' + (r.title || r.url) + '](' + r.url + ')' + (r.type ? ' (' + r.type + ')' : '')
-    ).join('\n');
-    vars.references = refs ? '## References\n\n' + refs : '';
-    const ac = normalizeAc(item.acceptanceCriteria).map(c => '- [ ] ' + c).join('\n');
-    vars.acceptance_criteria = ac ? '## Acceptance Criteria\n\n' + ac : '';
-
-    // Inject checkpoint context if agent left a checkpoint.json from a prior run
-    vars.checkpoint_context = '';
-    try {
-      const wtPath = vars.worktree_path || root;
-      const cpPath = path.join(wtPath, 'checkpoint.json');
-      if (fs.existsSync(cpPath)) {
-        const cpData = JSON.parse(fs.readFileSync(cpPath, 'utf8'));
-        const cpCount = (item._checkpointCount || 0) + 1;
-        if (cpCount > 3) {
-          log('warn', `Work item ${item.id} exceeded 3 checkpoint-resumes — marking as needs-human-review`);
-          item.status = WI_STATUS.NEEDS_REVIEW;
-          item._checkpointCount = cpCount;
-          needsWrite = true;
-          continue;
-        }
-        item._checkpointCount = cpCount;
-        needsWrite = true;
-        const cpSummary = [
-          `## Checkpoint (Resume #${cpCount}/3)`,
-          '',
-          'A previous agent run timed out but left a checkpoint. Continue from where it left off.',
-          '',
-          cpData.completed && cpData.completed.length > 0 ? `### Completed\n${cpData.completed.map(s => '- ' + s).join('\n')}` : '',
-          cpData.remaining && cpData.remaining.length > 0 ? `### Remaining\n${cpData.remaining.map(s => '- ' + s).join('\n')}` : '',
-          cpData.blockers && cpData.blockers.length > 0 ? `### Blockers\n${cpData.blockers.map(s => '- ' + s).join('\n')}` : '',
-          cpData.branch_state ? `### Branch State\n${cpData.branch_state}` : '',
-        ].filter(Boolean).join('\n');
-        vars.checkpoint_context = cpSummary;
-        log('info', `Injecting checkpoint context for ${item.id} (resume #${cpCount})`);
-      }
-    } catch (e) { log('warn', `checkpoint read for ${item.id}: ${e.message}`); }
-
-    // Inject ask-specific variables for the ask playbook
-    if (workType === WORK_TYPE.ASK) {
-      vars.question = item.title + (item.description ? '\n\n' + item.description : '');
-      vars.task_id = item.id;
-      vars.notes_content = '';
-      try { vars.notes_content = fs.readFileSync(path.join(MINIONS_DIR, 'notes.md'), 'utf8'); } catch { /* optional */ }
+    // Build common vars: references, acceptance criteria, checkpoint, notes, task context
+    const cpResult = buildWorkItemDispatchVars(item, vars, config, {
+      worktreePath: vars.worktree_path || root,
+      workType,
+    });
+    if (cpResult.needsReview) {
+      log('warn', `Work item ${item.id} exceeded 3 checkpoint-resumes — marking as needs-human-review`);
+      item.status = WI_STATUS.NEEDS_REVIEW;
+      item._checkpointCount = cpResult.checkpointCount;
+      needsWrite = true;
+      continue;
     }
-
-    // Resolve implicit context references (e.g., "ripley's plan", "the latest plan")
-    const resolvedCtx = resolveTaskContext(item, config);
-    if (resolvedCtx.additionalContext) {
-      vars.additional_context = (vars.additional_context || '') + resolvedCtx.additionalContext;
-      vars.task_description = vars.task_description + resolvedCtx.additionalContext;
+    if (cpResult.checkpointCount !== null) {
+      item._checkpointCount = cpResult.checkpointCount;
+      needsWrite = true;
     }
 
     const playbookName = selectPlaybook(workType, item);
@@ -1795,6 +1755,90 @@ function normalizeAc(ac) {
   return [];
 }
 
+/**
+ * Build common dispatch vars for a work item: references, acceptance criteria,
+ * checkpoint context, notes content, and resolved task context.
+ *
+ * Consolidates duplicated patterns across discoverFromWorkItems, discoverCentralWorkItems
+ * (normal + fan-out). Caller-specific vars (project_name, work_branch, plan vars) are NOT
+ * handled here — they remain in the caller.
+ *
+ * @param {Object} item - Work item
+ * @param {Object} vars - Mutable vars object to populate (must already have base vars)
+ * @param {Object} config - Engine config
+ * @param {Object} [options]
+ * @param {string} [options.worktreePath] - Path for checkpoint lookup (omit to skip checkpoint)
+ * @param {boolean} [options.includeNotes=true] - Whether to read notes.md into vars.notes_content
+ * @param {string} [options.workType] - Work type (used for ASK-specific vars)
+ * @returns {{ needsReview: boolean, checkpointCount: number|null }} checkpoint side-effect info
+ */
+function buildWorkItemDispatchVars(item, vars, config, options = {}) {
+  const { worktreePath, includeNotes = true, workType } = options;
+
+  // Notes content (uses queries.getNotes instead of inline fs.readFileSync)
+  if (includeNotes) {
+    vars.notes_content = getNotes() || '';
+  }
+
+  // References
+  const refs = (item.references || []).filter(r => r && r.url).map(r =>
+    '- [' + (r.title || r.url) + '](' + r.url + ')' + (r.type ? ' (' + r.type + ')' : '')
+  ).join('\n');
+  vars.references = refs ? '## References\n\n' + refs : '';
+
+  // Acceptance criteria
+  const ac = normalizeAc(item.acceptanceCriteria).map(c => '- [ ] ' + c).join('\n');
+  vars.acceptance_criteria = ac ? '## Acceptance Criteria\n\n' + ac : '';
+
+  // Checkpoint context
+  vars.checkpoint_context = '';
+  const result = { needsReview: false, checkpointCount: null };
+  if (worktreePath) {
+    try {
+      const cpPath = path.join(worktreePath, 'checkpoint.json');
+      if (fs.existsSync(cpPath)) {
+        const cpData = JSON.parse(fs.readFileSync(cpPath, 'utf8'));
+        const cpCount = (item._checkpointCount || 0) + 1;
+        result.checkpointCount = cpCount;
+        if (cpCount > 3) {
+          result.needsReview = true;
+        } else {
+          const cpSummary = [
+            `## Checkpoint (Resume #${cpCount}/3)`,
+            '',
+            'A previous agent run timed out but left a checkpoint. Continue from where it left off.',
+            '',
+            cpData.completed && cpData.completed.length > 0 ? `### Completed\n${cpData.completed.map(s => '- ' + s).join('\n')}` : '',
+            cpData.remaining && cpData.remaining.length > 0 ? `### Remaining\n${cpData.remaining.map(s => '- ' + s).join('\n')}` : '',
+            cpData.blockers && cpData.blockers.length > 0 ? `### Blockers\n${cpData.blockers.map(s => '- ' + s).join('\n')}` : '',
+            cpData.branch_state ? `### Branch State\n${cpData.branch_state}` : '',
+          ].filter(Boolean).join('\n');
+          vars.checkpoint_context = cpSummary;
+          log('info', `Injecting checkpoint context for ${item.id} (resume #${cpCount})`);
+        }
+      }
+    } catch (e) { log('warn', `checkpoint read for ${item.id}: ${e.message}`); }
+  }
+
+  // ASK-specific variables
+  if (workType === WORK_TYPE.ASK) {
+    vars.question = item.title + (item.description ? '\n\n' + item.description : '');
+    vars.task_id = item.id;
+    vars.notes_content = getNotes() || '';
+  }
+
+  // Resolve implicit context references (e.g., "ripley's plan", "the latest plan")
+  const resolvedCtx = resolveTaskContext(item, config);
+  if (resolvedCtx.additionalContext) {
+    vars.additional_context = (vars.additional_context || '') + resolvedCtx.additionalContext;
+    if (vars.task_description !== undefined) {
+      vars.task_description = vars.task_description + resolvedCtx.additionalContext;
+    }
+  }
+
+  return result;
+}
+
 function buildProjectContext(projects, assignedProject, isFanOut, agentName, agentRole) {
   const projectList = projects.map(p => {
     let line = `### ${p.name}\n`;
@@ -2028,25 +2072,11 @@ function discoverCentralWorkItems(config) {
           project_path: ap?.localPath || '',
         };
 
-        // Inject references and acceptance criteria
-        const fanRefs = (item.references || []).filter(r => r && r.url).map(r =>
-          '- [' + (r.title || r.url) + '](' + r.url + ')' + (r.type ? ' (' + r.type + ')' : '')
-        ).join('\n');
-        vars.references = fanRefs ? '## References\n\n' + fanRefs : '';
-        const fanAc = normalizeAc(item.acceptanceCriteria).map(c => '- [ ] ' + c).join('\n');
-        vars.acceptance_criteria = fanAc ? '## Acceptance Criteria\n\n' + fanAc : '';
-
-        if (workType === WORK_TYPE.ASK) {
-          vars.question = item.title + (item.description ? '\n\n' + item.description : '');
-          vars.task_id = item.id;
-          vars.notes_content = '';
-          try { vars.notes_content = fs.readFileSync(path.join(MINIONS_DIR, 'notes.md'), 'utf8'); } catch { /* optional */ }
-        }
-
-        const resolvedCtx = resolveTaskContext(item, config);
-        if (resolvedCtx.additionalContext) {
-          vars.additional_context = (vars.additional_context || '') + resolvedCtx.additionalContext;
-        }
+        // Build common vars: references, acceptance criteria, notes (ASK only), task context
+        buildWorkItemDispatchVars(item, vars, config, {
+          includeNotes: false,
+          workType,
+        });
 
         const playbookName = selectPlaybook(workType, item);
         const prompt = renderPlaybook(playbookName, vars) || renderPlaybook('work-item', vars);
@@ -2103,49 +2133,25 @@ function discoverCentralWorkItems(config) {
         additional_context: item.prompt ? `## Additional Context\n\n${item.prompt}` : '',
         scope_section: buildProjectContext(projects, null, false, agentName, agentRole),
         project_path: firstProject?.localPath || '',
-        notes_content: '',
       };
-      try { vars.notes_content = fs.readFileSync(path.join(MINIONS_DIR, 'notes.md'), 'utf8'); } catch { /* optional */ }
-
-      // Inject references and acceptance criteria
-      const normRefs = (item.references || []).filter(r => r && r.url).map(r =>
-        '- [' + (r.title || r.url) + '](' + r.url + ')' + (r.type ? ' (' + r.type + ')' : '')
-      ).join('\n');
-      vars.references = normRefs ? '## References\n\n' + normRefs : '';
-      const normAc = normalizeAc(item.acceptanceCriteria).map(c => '- [ ] ' + c).join('\n');
-      vars.acceptance_criteria = normAc ? '## Acceptance Criteria\n\n' + normAc : '';
-
-      // Inject checkpoint context if agent left a checkpoint.json from a prior run
-      vars.checkpoint_context = '';
-      try {
-        const centralBranch = item.branch || `work/${item.id}`;
-        const centralWtPath = firstProject?.localPath
-          ? path.resolve(firstProject.localPath, config.engine?.worktreeRoot || '../worktrees', centralBranch)
-          : '';
-        const cpPath = centralWtPath ? path.join(centralWtPath, 'checkpoint.json') : '';
-        if (cpPath && fs.existsSync(cpPath)) {
-          const cpData = JSON.parse(fs.readFileSync(cpPath, 'utf8'));
-          const cpCount = (item._checkpointCount || 0) + 1;
-          if (cpCount > 3) {
-            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: cpCount });
-            continue;
-          }
-          mutations.set(item.id, Object.assign(mutations.get(item.id) || {}, { _checkpointCount: cpCount }));
-          const cpSummary = [
-            `## Checkpoint (Resume #${cpCount}/3)`,
-            '',
-            'A previous agent run timed out but left a checkpoint. Continue from where it left off.',
-            '',
-            cpData.completed && cpData.completed.length > 0 ? `### Completed\n${cpData.completed.map(s => '- ' + s).join('\n')}` : '',
-            cpData.remaining && cpData.remaining.length > 0 ? `### Remaining\n${cpData.remaining.map(s => '- ' + s).join('\n')}` : '',
-            cpData.blockers && cpData.blockers.length > 0 ? `### Blockers\n${cpData.blockers.map(s => '- ' + s).join('\n')}` : '',
-            cpData.branch_state ? `### Branch State\n${cpData.branch_state}` : '',
-          ].filter(Boolean).join('\n');
-          vars.checkpoint_context = cpSummary;
-          log('info', `Injecting checkpoint context for ${item.id} (resume #${cpCount})`);
-        }
-      } catch (e) { log('warn', `checkpoint read for ${item.id}: ${e.message}`); }
+
+      // Build common vars: references, acceptance criteria, checkpoint, notes, task context
+      const centralBranch = item.branch || `work/${item.id}`;
+      const centralWtPath = firstProject?.localPath
+        ? path.resolve(firstProject.localPath, config.engine?.worktreeRoot || '../worktrees', centralBranch)
+        : '';
+      const cpResult = buildWorkItemDispatchVars(item, vars, config, {
+        worktreePath: centralWtPath || undefined,
+        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 });
+        continue;
+      }
+      if (cpResult.checkpointCount !== null) {
+        mutations.set(item.id, Object.assign(mutations.get(item.id) || {}, { _checkpointCount: cpResult.checkpointCount }));
+      }
 
       // Inject plan-specific variables for the plan playbook
       if (workType === WORK_TYPE.PLAN) {
@@ -2156,8 +2162,7 @@ function discoverCentralWorkItems(config) {
         vars.plan_title = item.title;
         vars.plan_file = planFileName;
         vars.task_description = item.title;
-        vars.notes_content = '';
-        try { vars.notes_content = fs.readFileSync(path.join(MINIONS_DIR, 'notes.md'), 'utf8'); } catch { /* optional */ }
+        // Notes already populated by buildWorkItemDispatchVars — no need to re-read
         // Track expected plan filename in meta for chainPlanToPrd
         mutations.set(item.id, Object.assign(mutations.get(item.id) || {}, { _planFileName: planFileName }));
       }
@@ -2191,20 +2196,7 @@ function discoverCentralWorkItems(config) {
           : 'Choose the best strategy based on your analysis of item dependencies.';
       }
 
-      // Inject ask-specific variables for the ask playbook
-      if (workType === WORK_TYPE.ASK) {
-        vars.question = item.title + (item.description ? '\n\n' + item.description : '');
-        vars.task_id = item.id;
-        vars.notes_content = '';
-        try { vars.notes_content = fs.readFileSync(path.join(MINIONS_DIR, 'notes.md'), 'utf8'); } catch { /* optional */ }
-      }
-
-      // Resolve implicit context references
-      const resolvedCtx = resolveTaskContext(item, config);
-      if (resolvedCtx.additionalContext) {
-        vars.additional_context = (vars.additional_context || '') + resolvedCtx.additionalContext;
-        vars.task_description = vars.task_description + resolvedCtx.additionalContext;
-      }
+      // ASK and resolveTaskContext already handled by buildWorkItemDispatchVars above
 
       const playbookName = selectPlaybook(workType, item);
       const prompt = renderPlaybook(playbookName, vars) || renderPlaybook('work-item', vars);
@@ -2733,7 +2725,7 @@ module.exports = {
   reconcileItemsWithPrs, detectDependencyCycles,
 
   // Playbooks
-  renderPlaybook,
+  renderPlaybook, buildWorkItemDispatchVars,
 
   // Timeout / Steering / Idle (re-exported from engine/timeout.js)
   checkTimeouts, checkSteering, checkIdleThreshold,

package/package.json

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