@yemi33/minions 0.1.1640 → 0.1.1641

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.1.1641 (2026-04-30)
+
+### Features
+- harden PR attachment contract (#1908)
+
 ## 0.1.1640 (2026-04-30)
 
 ### Fixes

package/dashboard.js

@@ -63,6 +63,55 @@ function reloadConfig() {
   PROJECTS = _getProjects(CONFIG);
 }
 
+function getWorkItemIdFromPrLinkContext(context, workItemId) {
+  if (typeof workItemId === 'string' && workItemId.trim()) return workItemId.trim();
+  if (!context) return null;
+  if (typeof context === 'object' && typeof context.workItemId === 'string' && context.workItemId.trim()) return context.workItemId.trim();
+  if (typeof context === 'string') {
+    const match = context.match(/\b(P-[a-z0-9]{6,}|W-[a-z0-9]{6,}|PL-[a-z0-9]{6,})\b/i);
+    return match ? match[1] : null;
+  }
+  return null;
+}
+
+function linkPullRequestForTracking({ url, title, project: projectName, autoObserve, context, workItemId }, config = CONFIG) {
+  if (!url) {
+    const err = new Error('url required');
+    err.statusCode = 400;
+    throw err;
+  }
+  const projects = shared.getProjects(config);
+  const targetProject = projectName ? projects.find(p => p.name?.toLowerCase() === projectName.toLowerCase()) : (projects[0] || null);
+  const prPath = targetProject ? shared.projectPrPath(targetProject) : path.join(MINIONS_DIR, 'pull-requests.json');
+
+  const prNumMatch = url.match(/\/pull\/(\d+)|pullrequest\/(\d+)/);
+  const prNum = prNumMatch ? (prNumMatch[1] || prNumMatch[2]) : Date.now().toString().slice(-6);
+  const prId = shared.getCanonicalPrId(targetProject, prNum, url);
+  const linkedWorkItemId = getWorkItemIdFromPrLinkContext(context, workItemId);
+  const contextText = typeof context === 'string' ? context : (context == null ? '' : JSON.stringify(context));
+  const result = shared.upsertPullRequestRecord(prPath, {
+    id: prId,
+    prNumber: parseInt(prNum, 10) || null,
+    title: (title || 'PR #' + prNum + ' (polling...)').slice(0, 120),
+    description: '',
+    agent: 'human',
+    branch: '',
+    reviewStatus: 'pending',
+    status: 'active',
+    created: new Date().toISOString(),
+    url,
+    prdItems: linkedWorkItemId ? [linkedWorkItemId] : [],
+    _manual: true,
+    _contextOnly: !autoObserve,
+    _autoObserve: !!autoObserve,
+    _context: contextText,
+  }, {
+    project: targetProject,
+    itemId: linkedWorkItemId,
+  });
+  return { ...result, prPath, targetProject, prNum };
+}
+
 function _normalizeSkillDirForCompare(dir) {
   const resolved = path.resolve(String(dir || '').replace(/\//g, path.sep));
   return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
@@ -5840,66 +5889,13 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     // Agents
     { method: 'POST', path: '/api/pull-requests/link', desc: 'Manually link an external PR for tracking', params: 'url, title?, project?, autoObserve?, context?, workItemId?', handler: async (req, res) => {
       const body = await readBody(req);
-      const { url, title, project: projectName, autoObserve, context, workItemId } = body;
+      const { url } = body;
       if (!url) return jsonReply(res, 400, { error: 'url required' });
 
-      // Determine project
       reloadConfig();
-      const projects = shared.getProjects(CONFIG);
-      const targetProject = projectName ? projects.find(p => p.name?.toLowerCase() === projectName.toLowerCase()) : (projects[0] || null);
-      const prPath = targetProject ? shared.projectPrPath(targetProject) : path.join(MINIONS_DIR, 'pull-requests.json');
-
-      // Extract PR number from URL
-      const prNumMatch = url.match(/\/pull\/(\d+)|pullrequest\/(\d+)/);
-      const prNum = prNumMatch ? (prNumMatch[1] || prNumMatch[2]) : Date.now().toString().slice(-6);
-      const prId = shared.getCanonicalPrId(targetProject, prNum, url);
-      const contextText = typeof context === 'string' ? context : (context == null ? '' : JSON.stringify(context));
-
-      // Resolve a work-item association from either the top-level workItemId
-      // field (preferred) or context.workItemId (legacy CC payload shape).
-      // Without this, manually-linked PRs end up with prdItems=[] and the
-      // Work Items page renders no PR even though _context records the ID.
-      const linkedItemId = (typeof workItemId === 'string' && workItemId.trim())
-        || (context && typeof context === 'object' && typeof context.workItemId === 'string' && context.workItemId.trim())
-        || '';
-
-      // Atomic check-and-insert to prevent duplicates and races with polling loops
-      let duplicate = false;
-      mutateJsonFileLocked(prPath, (prs) => {
-        if (!Array.isArray(prs)) prs = [];
-        if (prs.some(p => p.id === prId || p.url === url)) { duplicate = true; return prs; }
-        prs.push({
-          id: prId,
-          prNumber: parseInt(prNum, 10) || null,
-          title: (title || 'PR #' + prNum + ' (polling...)').slice(0, 120),
-          description: '',
-          agent: 'human',
-          branch: '',
-          reviewStatus: 'pending',
-          status: 'active',
-          created: new Date().toISOString(),
-          url,
-          prdItems: linkedItemId ? [linkedItemId] : [],
-          _manual: true,
-          _contextOnly: !autoObserve,
-          _autoObserve: !!autoObserve,
-          _context: contextText,
-        });
-        return prs;
-      }, { defaultValue: [] });
-      if (duplicate) return jsonReply(res, 400, { error: 'PR already tracked' });
-      // Persist the work-item ↔ PR association in pr-links.json so
-      // queries.getWorkItems() can render item._pr / item._prUrl. addPrLink
-      // is idempotent and handles the central / project-scoped split.
-      if (linkedItemId) {
-        try {
-          shared.addPrLink(prId, linkedItemId, { project: targetProject, prNumber: parseInt(prNum, 10) || null, url });
-        } catch (e) {
-          shared.log('warn', `PR link addPrLink failed for ${prId} → ${linkedItemId}: ${e.message}`);
-        }
-      }
+      const { id: prId, prPath, targetProject, prNum, created, linked } = linkPullRequestForTracking(body, CONFIG);
       invalidateStatusCache();
-      jsonReply(res, 200, { ok: true, id: prId });
+      jsonReply(res, 200, { ok: true, id: prId, created, linked });
 
       // Async-enrich: fetch title, description, branch, author from GitHub/ADO API
       (async () => {
@@ -6426,6 +6422,7 @@ module.exports = {
   _parseDocChatResultText,
   _messageRequestsOrchestration,
   _formatDocChatContext,
+  _linkPullRequestForTracking: linkPullRequestForTracking,
   _resolveSkillReadPath,
   DOC_CHAT_DOCUMENT_DELIMITER,
 };

package/engine/ado.js

@@ -5,7 +5,7 @@
 
 const path = require('path');
 const shared = require('./shared');
-const { exec, execAsync, getAdoOrgBase, addPrLink, log, ts, dateStamp, PR_STATUS, createThrottleTracker } = shared;
+const { exec, execAsync, getAdoOrgBase, log, ts, dateStamp, PR_STATUS, createThrottleTracker } = shared;
 const { getPrs } = require('./queries');
 const { mutateJsonFileLocked } = shared;
 
@@ -803,7 +803,18 @@ async function reconcilePrs(config) {
         }
         // PR already tracked — write link to pr-links.json if we can extract an ID
         if (confirmedItemId) {
-          addPrLink(prId, confirmedItemId, { project, prNumber: adoPr.pullRequestId, url: prUrl });
+          shared.upsertPullRequestRecord(prPath, existing || {
+            id: prId,
+            prNumber: adoPr.pullRequestId,
+            title: (adoPr.title || `PR #${adoPr.pullRequestId}`).slice(0, 120),
+            agent: (linkedItem?.dispatched_to || adoPr.createdBy?.displayName || 'unknown').toLowerCase(),
+            branch,
+            reviewStatus: 'pending',
+            status: 'active',
+            created: adoPr.creationDate || ts(),
+            url: prUrl,
+            prdItems: [],
+          }, { project, itemId: confirmedItemId });
           if (existing && !(existing.prdItems || []).includes(confirmedItemId)) {
             existing.prdItems = Array.isArray(existing.prdItems) ? existing.prdItems : [];
             existing.prdItems.push(confirmedItemId);
@@ -818,7 +829,7 @@ async function reconcilePrs(config) {
       // are human-authored and should not be auto-tracked or auto-reviewed.
       if (!confirmedItemId) continue;
 
-      existingPrs.push({
+      const entry = {
         id: prId,
         prNumber: adoPr.pullRequestId,
         title: (adoPr.title || `PR #${adoPr.pullRequestId}`).slice(0, 120),
@@ -829,8 +840,9 @@ async function reconcilePrs(config) {
         created: adoPr.creationDate || ts(),
         url: prUrl,
         prdItems: [confirmedItemId],
-      });
-      addPrLink(prId, confirmedItemId, { project, prNumber: adoPr.pullRequestId, url: prUrl });
+      };
+      const upserted = shared.upsertPullRequestRecord(prPath, entry, { project, itemId: confirmedItemId });
+      existingPrs.push(upserted.record || entry);
       existingIds.add(prId);
       projectAdded++;
       log('info', `PR reconciliation: added ${prId} (branch: ${branch}, linked to ${confirmedItemId}) to ${project.name}`);

package/engine/copilot-models.json

@@ -1,5 +1,5 @@
 {
   "runtime": "copilot",
   "models": null,
-  "cachedAt": "2026-04-30T17:09:32.809Z"
+  "cachedAt": "2026-04-30T17:23:35.113Z"
 }

package/engine/github.js

@@ -5,7 +5,7 @@
  */
 
 const shared = require('./shared');
-const { exec, execAsync, getProjects, projectPrPath, projectWorkItemsPath, safeJson, safeWrite, mutateJsonFileLocked, MINIONS_DIR, addPrLink, getPrLinks, backfillPrPrdItems, log, ts, dateStamp, PR_STATUS, PR_POLLABLE_STATUSES, createThrottleTracker } = shared;
+const { exec, execAsync, getProjects, projectPrPath, projectWorkItemsPath, safeJson, safeWrite, mutateJsonFileLocked, MINIONS_DIR, getPrLinks, backfillPrPrdItems, log, ts, dateStamp, PR_STATUS, PR_POLLABLE_STATUSES, createThrottleTracker } = shared;
 const { getPrs } = require('./queries');
 const path = require('path');
 
@@ -717,7 +717,18 @@ async function reconcilePrs(config) {
           metadataUpdated++;
         }
         if (confirmedItemId) {
-          addPrLink(prId, confirmedItemId, { project, prNumber: ghPr.number, url: prUrl });
+          shared.upsertPullRequestRecord(prPath, existing || {
+            id: prId,
+            prNumber: ghPr.number,
+            title: (ghPr.title || `PR #${ghPr.number}`).slice(0, 120),
+            agent: (linkedItem?.dispatched_to || ghPr.user?.login || 'unknown').toLowerCase(),
+            branch,
+            reviewStatus: 'pending',
+            status: 'active',
+            created: ghPr.created_at || ts(),
+            url: prUrl,
+            prdItems: [],
+          }, { project, itemId: confirmedItemId });
           if (existing && !(existing.prdItems || []).includes(confirmedItemId)) {
             existing.prdItems = Array.isArray(existing.prdItems) ? existing.prdItems : [];
             existing.prdItems.push(confirmedItemId);
@@ -732,7 +743,7 @@ async function reconcilePrs(config) {
       // Only auto-track PRs linked to a minions work item — skip human-authored PRs
       if (!confirmedItemId && !isE2eBranch) continue;
 
-      currentPrs.push({
+      const entry = {
         id: prId,
         prNumber: ghPr.number,
         title: (ghPr.title || `PR #${ghPr.number}`).slice(0, 120),
@@ -743,8 +754,9 @@ async function reconcilePrs(config) {
         created: ghPr.created_at || ts(),
         url: prUrl,
         prdItems: [confirmedItemId],
-      });
-      addPrLink(prId, confirmedItemId, { project, prNumber: ghPr.number, url: prUrl });
+      };
+      const upserted = shared.upsertPullRequestRecord(prPath, entry, { project, itemId: confirmedItemId });
+      currentPrs.push(upserted.record || entry);
       existingIds.add(prId);
       projectAdded++;
 

package/engine/lifecycle.js

@@ -7,7 +7,7 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 const shared = require('./shared');
-const { safeRead, safeJson, safeWrite, mutateJsonFileLocked, mutateWorkItems, execSilent, execAsync, projectPrPath, getPrLinks, addPrLink,
+const { safeRead, safeJson, safeWrite, mutateJsonFileLocked, mutateWorkItems, execSilent, execAsync, projectPrPath, getPrLinks,
   log, ts, dateStamp, WI_STATUS, DONE_STATUSES, PLAN_TERMINAL_STATUSES, WORK_TYPE, PLAN_STATUS, PRD_ITEM_STATUS, PR_STATUS, DISPATCH_RESULT,
   ENGINE_DEFAULTS, DEFAULT_AGENT_METRICS, FAILURE_CLASS } = shared;
 const { trackEngineUsage } = require('./llm');
@@ -853,53 +853,172 @@ function syncPrsFromOutput(output, agentId, meta, config) {
   const entryBranch = meta?.branch || '';
 
   for (const [prPath, { name, project: targetProject, entries }] of newPrsByPath) {
-    const linksToPersist = [];
-    mutateJsonFileLocked(prPath, (data) => {
-      const prs = Array.isArray(data) ? data : [];
-      // Normalize legacy YYYY-MM-DD created dates to ISO
-      for (const p of prs) {
-        if (p.created && p.created.length === 10) p.created = p.created + 'T00:00:00.000Z';
-      }
-      for (const { prId, fullId, entry } of entries) {
-        if (prs.some(p => p.id === fullId || (p.url && p.url === entry.url))) continue;
-
-        // Branch-level dedup: skip if an active PR already exists on the same branch.
-        // This prevents duplicate PRs when an agent retries and calls `gh pr create` again
-        // on the same branch (GitHub allows multiple PRs from one branch).
-        // Only block when the existing PR is active — abandoned/merged PRs don't conflict.
-        const branch = entry.branch || entryBranch;
-        if (branch) {
-          const existingOnBranch = prs.find(p => p.branch === branch && p.status === PR_STATUS.ACTIVE && p.id !== fullId);
-          if (existingOnBranch) {
-            log('warn', `Duplicate PR detected: ${fullId} on branch ${branch} — already tracked as ${existingOnBranch.id}. Skipping.`);
-            // Best-effort close the duplicate on GitHub (non-blocking, fire-and-forget)
-            try {
-              const ghSlug = output.match(/github\.com\/([^/]+\/[^/]+)/)?.[1];
-              if (ghSlug) {
-                execAsync(`gh pr close ${prId} --repo ${ghSlug} --comment "Closing duplicate — ${existingOnBranch.id} already tracks this branch."`, { timeout: 15000 })
-                  .catch(() => {});
-              }
-            } catch { /* best-effort */ }
-            continue;
+    for (const { prId, fullId, entry } of entries) {
+      let duplicateOnBranch = null;
+      const result = shared.upsertPullRequestRecord(prPath, entry, {
+        project: targetProject,
+        itemId: meta?.item?.id || null,
+        beforeInsert: (prs, normalizedEntry) => {
+          // Normalize legacy YYYY-MM-DD created dates to ISO while the file is locked.
+          for (const p of prs) {
+            if (p.created && p.created.length === 10) p.created = p.created + 'T00:00:00.000Z';
           }
-        }
-
-        prs.push(entry);
-        if (meta?.item?.id) {
-          linksToPersist.push({ prId: fullId, itemId: meta.item.id, project: targetProject, prNumber: entry.prNumber, url: entry.url });
-        }
-        added++;
+          // Branch-level dedup: skip if an active PR already exists on the same branch.
+          // This prevents duplicate PRs when an agent retries and calls `gh pr create` again
+          // on the same branch (GitHub allows multiple PRs from one branch).
+          // Only block when the existing PR is active — abandoned/merged PRs don't conflict.
+          const branch = normalizedEntry.branch || entryBranch;
+          if (!branch) return true;
+          duplicateOnBranch = prs.find(p => p.branch === branch && p.status === PR_STATUS.ACTIVE && p.id !== normalizedEntry.id) || null;
+          return !duplicateOnBranch;
+        },
+      });
+      if (duplicateOnBranch) {
+        log('warn', `Duplicate PR detected: ${fullId} on branch ${entry.branch || entryBranch} — already tracked as ${duplicateOnBranch.id}. Skipping.`);
+        // Best-effort close the duplicate on GitHub (non-blocking, fire-and-forget)
+        try {
+          const ghSlug = output.match(/github\.com\/([^/]+\/[^/]+)/)?.[1];
+          if (ghSlug) {
+            execAsync(`gh pr close ${prId} --repo ${ghSlug} --comment "Closing duplicate — ${duplicateOnBranch.id} already tracks this branch."`, { timeout: 15000 })
+              .catch(() => {});
+          }
+        } catch { /* best-effort */ }
+        continue;
       }
-      return prs;
-    });
-    for (const { prId, itemId, project, prNumber, url } of linksToPersist) {
-      addPrLink(prId, itemId, { project, prNumber, url });
+      if (result.created || result.linked) added++;
     }
     log('info', `Synced PR(s) from ${agentName}'s output to ${name === '_central' ? 'central' : name}/pull-requests.json`);
   }
   return added;
 }
 
+function isPrAttachmentRequired(type, item, meta = {}) {
+  if (!item?.id || item.skipPr) return false;
+  const explicit = item.requiresPr === true
+    || item.prRequired === true
+    || item.requiresPullRequest === true
+    || item.itemType === 'pr';
+  if (meta.branchStrategy === 'shared-branch' && item.itemType !== 'pr' && !explicit) return false;
+  return explicit
+    || type === WORK_TYPE.IMPLEMENT
+    || type === WORK_TYPE.IMPLEMENT_LARGE
+    || type === WORK_TYPE.FIX
+    || type === WORK_TYPE.TEST;
+}
+
+function hasCanonicalPrAttachment(itemId, config) {
+  if (!itemId) return false;
+  if (Object.values(getPrLinks()).some(linkedIds => (linkedIds || []).includes(itemId))) return true;
+  const projects = shared.getProjects(config);
+  for (const p of projects) {
+    const prs = safeJson(shared.projectPrPath(p)) || [];
+    if (prs.some(pr => (pr.prdItems || []).includes(itemId))) return true;
+  }
+  const centralPrs = safeJson(path.join(MINIONS_DIR, 'pull-requests.json')) || [];
+  return centralPrs.some(pr => (pr.prdItems || []).includes(itemId));
+}
+
+async function findOpenPrForBranch(meta, config) {
+  if (!meta?.branch) return null;
+  const projectObj = shared.getProjects(config).find(p => p.name === meta?.project?.name);
+  if (!projectObj) return null;
+  const host = projectObj.repoHost || 'ado';
+  if (host === 'github') {
+    const ghSlug = projectObj.prUrlBase?.match(/github\.com\/([^/]+\/[^/]+)\/pull/)?.[1];
+    if (!ghSlug) return null;
+    for (let attempt = 0; attempt < 3; attempt++) {
+      if (attempt > 0) await new Promise(r => setTimeout(r, 3000));
+      let raw = '';
+      try {
+        raw = await execAsync(`gh pr list --head "${meta.branch}" --repo ${ghSlug} --json number,url,state --limit 1`, { timeout: 15000, windowsHide: true });
+        const parsed = JSON.parse(raw || '[]');
+        const hits = Array.isArray(parsed) ? parsed : [];
+        if (hits.length > 0 && hits[0].state === 'OPEN') {
+          return { project: projectObj, prNumber: hits[0].number, url: hits[0].url };
+        }
+        if (attempt === 2) {
+          log('warn', `Auto-link fallback: no open PR found on branch ${meta.branch} after 3 attempts (raw: ${(raw || '').slice(0, 200)})`);
+        }
+      } catch (err) {
+        if (attempt === 2) {
+          const rawSuffix = raw ? ` (raw: ${raw.slice(0, 200)})` : '';
+          log('warn', `Auto-link fallback: gh pr list lookup failed on branch ${meta.branch} after 3 attempts: ${err.message}${rawSuffix}`);
+        }
+      }
+    }
+    return null;
+  }
+  if (host === 'ado') {
+    const found = await require('./ado').findOpenPrOnBranch(projectObj, meta.branch);
+    return found ? { project: projectObj, prNumber: found.prNumber, url: found.url } : null;
+  }
+  log('debug', `Skipping branch PR lookup for unsupported repo host "${host}" on ${projectObj.name}`);
+  return null;
+}
+
+function markMissingPrAttachment(meta, agentId, reason, resultSummary) {
+  const noPrWiPath = resolveWorkItemPath(meta);
+  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;
+      w.status = WI_STATUS.NEEDS_REVIEW;
+      w._missingPrAttachment = true;
+      w.failReason = reason;
+      w._lastReviewReason = reason;
+      delete w.completedAt;
+      delete w._noPr;
+      delete w._noPrReason;
+      return data;
+    }, { skipWriteIfUnchanged: true });
+  }
+  shared.writeToInbox('engine', `missing-pr-attachment-${meta.item.id}`,
+    `# PR attachment missing for ${meta.item.id}\n\n` +
+    `**Agent:** ${agentId}\n` +
+    `**Work item:** \`${meta.item.id}\` — ${meta.item.title || ''}\n` +
+    `**Type:** ${meta.item.type || 'unknown'}\n` +
+    `**Branch:** ${meta.branch || '(none)'}\n\n` +
+    `${reason}\n` +
+    (resultSummary ? `\n## Agent summary\n${resultSummary}\n` : ''),
+    null,
+    { sourceItem: meta.item.id, reason: 'missing-pr-attachment' });
+}
+
+async function enforcePrAttachmentContract(type, meta, agentId, config, resultSummary) {
+  if (!isPrAttachmentRequired(type, meta?.item, meta)) return null;
+  if (hasCanonicalPrAttachment(meta.item.id, config)) return null;
+
+  const found = await findOpenPrForBranch(meta, config);
+  if (found) {
+    const entry = {
+      id: shared.getCanonicalPrId(found.project, found.prNumber, found.url),
+      prNumber: found.prNumber,
+      title: meta.item?.title || `PR #${found.prNumber}`,
+      agent: agentId,
+      branch: meta.branch || '',
+      reviewStatus: 'pending',
+      status: PR_STATUS.ACTIVE,
+      created: ts(),
+      url: found.url,
+      prdItems: [meta.item.id],
+      sourcePlan: meta.item?.sourcePlan || '',
+      itemType: meta.item?.itemType || '',
+    };
+    shared.upsertPullRequestRecord(shared.projectPrPath(found.project), entry, {
+      project: found.project,
+      itemId: meta.item.id,
+    });
+    log('info', `Auto-linked existing PR ${entry.id} on branch ${meta.branch} for ${meta.item.id}`);
+    if (hasCanonicalPrAttachment(meta.item.id, config)) return null;
+  }
+
+  const reason = `PR-producing work item ${meta.item.id} completed without a canonically attached PR record. Successful completion requires PR.prdItems/pr-links.json to include the work item; branch names, note URLs, and _context.workItemId metadata are not sufficient.`;
+  markMissingPrAttachment(meta, agentId, reason, resultSummary);
+  log('warn', reason);
+  return { reason, itemId: meta.item.id };
+}
+
 // ─── Post-Completion Hooks ──────────────────────────────────────────────────
 
 /**
@@ -1688,8 +1807,8 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
     log('info', `Structured completion reports PR (${structuredCompletion.pr}) but regex sync found none — PR may already be tracked`);
   }
 
-  // Auto-recover: if a failed implement/fix agent created PRs, it likely succeeded before the failure surfaced.
-  const prCreatingType = type === WORK_TYPE.IMPLEMENT || type === WORK_TYPE.IMPLEMENT_LARGE || type === WORK_TYPE.FIX;
+  // Auto-recover: if a failed implement/fix/test agent created PRs, it likely succeeded before the failure surfaced.
+  const prCreatingType = type === WORK_TYPE.IMPLEMENT || type === WORK_TYPE.IMPLEMENT_LARGE || type === WORK_TYPE.FIX || type === WORK_TYPE.TEST;
   const autoRecovered = !isSuccess && prsCreatedCount > 0 && prCreatingType && !!meta?.item?.id;
   if (autoRecovered) {
     log('info', `Auto-recovery: agent failed but created ${prsCreatedCount} PR(s) — upgrading ${meta.item.id} to done`);
@@ -1799,6 +1918,12 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
     }
   }
 
+  let completionContractFailure = null;
+  if (effectiveSuccess && meta?.item?.id && !skipDoneStatus) {
+    completionContractFailure = await enforcePrAttachmentContract(type, meta, agentId, config, resultSummary);
+    if (completionContractFailure) skipDoneStatus = true;
+  }
+
   if (effectiveSuccess && meta?.item?.id && !skipDoneStatus) {
     meta._agentId = agentId;
     updateWorkItemStatus(meta, WI_STATUS.DONE, '');
@@ -1898,131 +2023,6 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
     }
   }
 
-  // Detect implement tasks that completed without creating a PR
-  if (effectiveSuccess && (type === WORK_TYPE.IMPLEMENT || type === WORK_TYPE.IMPLEMENT_LARGE || type === WORK_TYPE.FIX) && prsCreatedCount === 0 && meta?.item?.id && !meta?.item?.skipPr && meta?.project?.localPath) {
-    // Check if a PR already exists linked to this work item (from a previous attempt)
-    let existingPrFound = Object.values(getPrLinks()).some(linkedIds => (linkedIds || []).includes(meta.item.id));
-    // Also check pull-requests.json for PRs with matching prdItems or branch
-    if (!existingPrFound) {
-      const allProjects = shared.getProjects(config);
-      for (const p of allProjects) {
-        const prs = safeJson(shared.projectPrPath(p)) || [];
-        if (prs.some(pr => (pr.prdItems || []).includes(meta.item.id) || (pr.branch && pr.branch.includes(meta.item.id)))) {
-          existingPrFound = true;
-          break;
-        }
-      }
-    }
-    // Last resort: query the platform directly for an open PR on this branch.
-    // Handles the case where a prior orphaned dispatch created a PR but the engine
-    // never processed its output — so the PR exists on the platform but not in pull-requests.json.
-    if (!existingPrFound && meta?.branch) {
-      const projectObj = shared.getProjects(config).find(p => p.name === meta?.project?.name);
-      if (projectObj) {
-        try {
-          let found = null;
-          const host = projectObj.repoHost || 'ado';
-          if (host === 'github') {
-            const ghSlug = projectObj.prUrlBase?.match(/github\.com\/([^/]+\/[^/]+)\/pull/)?.[1];
-            if (ghSlug) {
-              // Retry up to 3 times — newly created PRs can take a few seconds to appear in the API
-              for (let attempt = 0; attempt < 3 && !found; attempt++) {
-                if (attempt > 0) await new Promise(r => setTimeout(r, 3000));
-                let raw = '';
-                try {
-                  raw = await execAsync(`gh pr list --head "${meta.branch}" --repo ${ghSlug} --json number,url,state --limit 1`, { timeout: 15000, windowsHide: true });
-                  const parsed = JSON.parse(raw || '[]');
-                  const hits = Array.isArray(parsed) ? parsed : [];
-                  if (hits.length > 0 && hits[0].state === 'OPEN') {
-                    found = { prNumber: hits[0].number, url: hits[0].url };
-                  } else if (attempt === 2) {
-                    log('warn', `Auto-link fallback: no open PR found on branch ${meta.branch} after 3 attempts (raw: ${(raw || '').slice(0, 200)})`);
-                  }
-                } catch (err) {
-                  if (attempt === 2) {
-                    const rawSuffix = raw ? ` (raw: ${raw.slice(0, 200)})` : '';
-                    log('warn', `Auto-link fallback: gh pr list lookup failed on branch ${meta.branch} after 3 attempts: ${err.message}${rawSuffix}`);
-                  }
-                }
-              }
-            }
-          } else if (host === 'ado') {
-            found = await require('./ado').findOpenPrOnBranch(projectObj, meta.branch);
-          } else {
-            log('debug', `Skipping branch PR lookup for unsupported repo host "${host}" on ${projectObj.name}`);
-          }
-          if (found) {
-            const fullId = shared.getCanonicalPrId(projectObj, found.prNumber, found.url);
-            const prPath = shared.projectPrPath(projectObj);
-            mutateJsonFileLocked(prPath, prs => {
-              if (!Array.isArray(prs)) prs = [];
-              const existingPr = prs.find(p => p.id === fullId);
-              if (existingPr) {
-                if (meta.item?.id) {
-                  if (!Array.isArray(existingPr.prdItems)) existingPr.prdItems = [];
-                  if (!existingPr.prdItems.includes(meta.item.id)) existingPr.prdItems.push(meta.item.id);
-                }
-                return prs;
-              }
-              prs.push({
-                id: fullId, prNumber: found.prNumber, title: meta.item?.title || '',
-                agent: agentId, branch: meta.branch, reviewStatus: 'pending',
-                status: PR_STATUS.ACTIVE, created: ts(), url: found.url,
-                prdItems: meta.item?.id ? [meta.item.id] : [],
-                sourcePlan: meta.item?.sourcePlan || '', itemType: meta.item?.itemType || '',
-              });
-              return prs;
-            });
-            log('info', `Auto-linked existing PR ${fullId} on branch ${meta.branch} for ${meta.item?.id}`);
-            existingPrFound = true;
-          }
-        } catch (e) { log('warn', `PR lookup for branch ${meta.branch}: ${e.message}`); }
-      }
-    }
-    if (!existingPrFound) {
-      const noPrWiPath = resolveWorkItemPath(meta);
-      if (noPrWiPath) {
-        const hasOutput = stdout && stdout.length > 500;
-        let action = null;
-        mutateJsonFileLocked(noPrWiPath, data => {
-          if (!Array.isArray(data)) return data;
-          const w = data.find(i => i.id === meta.item.id);
-          if (!w) return data;
-          const retries = w._retryCount || 0;
-          if (!hasOutput && retries < ENGINE_DEFAULTS.maxRetries) {
-            w.status = WI_STATUS.PENDING;
-            w._retryCount = retries + 1;
-            delete w.dispatched_at;
-            delete w.dispatched_to;
-            delete w.failReason;
-            delete w.noPr;
-            action = { type: 'retry', retries: retries + 1 };
-          } else if (hasOutput) {
-            w.status = WI_STATUS.DONE;
-            w.completedAt = ts();
-            w._noPr = true;
-            w._noPrReason = 'Agent completed without creating a PR (changes may already exist or not be needed)';
-            delete w.failReason;
-            action = { type: 'done' };
-          } else {
-            w.status = WI_STATUS.NEEDS_REVIEW;
-            w._noPr = true;
-            w.failReason = 'Completed without output or PR after ' + ENGINE_DEFAULTS.maxRetries + ' attempts';
-            action = { type: 'needs-review' };
-          }
-          return data;
-        }, { skipWriteIfUnchanged: true });
-        if (action?.type === 'retry') {
-          log('info', `Auto-retry ${action.retries}/${ENGINE_DEFAULTS.maxRetries} for ${meta.item.id} (no output, no PR)`);
-        } else if (action?.type === 'done') {
-          log('info', `${meta.item.id} completed without PR — marking done (agent produced output)`);
-        } else if (action?.type === 'needs-review') {
-          log('warn', `${meta.item.id} needs review — no output after ${ENGINE_DEFAULTS.maxRetries} retries`);
-        }
-      }
-    }
-  }
-
   // Old plan-to-prd PRD check removed — moved before updateWorkItemStatus(DONE) to fix #893
   // (retryCount was being deleted by done-marking before the check could read it)
   // Review verdict check similarly moved before updateWorkItemStatus(DONE) — same root cause.
@@ -2046,7 +2046,8 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
     }
   }
   checkForLearnings(agentId, config.agents[agentId], dispatchItem.task);
-  if (effectiveSuccess) {
+  const finalResult = completionContractFailure ? DISPATCH_RESULT.ERROR : (effectiveSuccess ? DISPATCH_RESULT.SUCCESS : DISPATCH_RESULT.ERROR);
+  if (finalResult === DISPATCH_RESULT.SUCCESS) {
     extractSkillsFromOutput(stdout, agentId, dispatchItem, config);
     // Also scan inbox notes for skill blocks — agents often write skills to inbox, not stdout
     try {
@@ -2061,7 +2062,6 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
       }
     } catch {}
   }
-  const finalResult = effectiveSuccess ? DISPATCH_RESULT.SUCCESS : DISPATCH_RESULT.ERROR;
   updateAgentHistory(agentId, dispatchItem, finalResult);
   // Don't count auto-retries as errors in metrics — only count final outcomes
   const isAutoRetry = !effectiveSuccess && meta?.item?.id && (meta.item._retryCount || 0) < ENGINE_DEFAULTS.maxRetries;
@@ -2074,7 +2074,7 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
     teams.teamsNotifyCompletion(dispatchItem, finalResult, agentId).catch(() => {});
   } catch {}
 
-  return { resultSummary, taskUsage, autoRecovered, structuredCompletion };
+  return { resultSummary, taskUsage, autoRecovered, structuredCompletion, completionContractFailure };
 }
 
 // ─── PR → PRD Status Sync ─────────────────────────────────────────────────────

package/engine/shared.js

@@ -1896,6 +1896,80 @@ function addPrLink(prId, itemId, { project = null, url = '', prNumber = null } =
   });
 }
 
+/**
+ * Canonical PR-producing work contract helper.
+ *
+ * Dashboard rendering derives work-item PR columns from PR.prdItems (with
+ * engine/pr-links.json as a compatibility fallback). Any path that discovers or
+ * manually records a PR for a work item must use this helper so the PR record
+ * and the canonical work-item attachment are created together and idempotently.
+ */
+function upsertPullRequestRecord(prPath, entry, { project = null, itemId = null, itemIds = null, beforeInsert = null } = {}) {
+  if (!prPath) throw new Error('prPath required');
+  if (!entry || typeof entry !== 'object') throw new Error('entry required');
+
+  const linkedItemIds = normalizePrLinkItems([
+    ...(Array.isArray(entry.prdItems) ? entry.prdItems : []),
+    ...(Array.isArray(itemIds) ? itemIds : [itemId]),
+  ]);
+  const prNumber = getPrNumber(entry.prNumber ?? entry.id ?? entry.url);
+  const canonicalId = getCanonicalPrId(project, entry.prNumber ?? entry.id ?? entry.url ?? prNumber, entry.url || '');
+  if (!canonicalId) throw new Error('PR id required');
+  const normalizedEntry = {
+    ...entry,
+    id: canonicalId,
+    prNumber: prNumber ?? entry.prNumber ?? null,
+    prdItems: linkedItemIds,
+  };
+
+  let created = false;
+  let linked = false;
+  let skipped = false;
+  let record = null;
+
+  mutatePullRequests(prPath, (prs) => {
+    normalizePrRecords(prs, project);
+    let target = findPrRecord(prs, normalizedEntry, project);
+    if (!target && typeof beforeInsert === 'function' && beforeInsert(prs, normalizedEntry) === false) {
+      skipped = true;
+      return prs;
+    }
+    if (!target) {
+      target = normalizedEntry;
+      prs.push(target);
+      created = true;
+    } else {
+      target.id = canonicalId;
+      if (prNumber != null) target.prNumber = prNumber;
+      for (const key of ['url', 'title', 'description', 'agent', 'branch', 'reviewStatus', 'status', 'created', 'sourcePlan', 'itemType']) {
+        if (normalizedEntry[key] != null && normalizedEntry[key] !== '' && (target[key] == null || target[key] === '')) {
+          target[key] = normalizedEntry[key];
+        }
+      }
+      for (const key of ['_manual', '_contextOnly', '_autoObserve', '_context']) {
+        if (normalizedEntry[key] != null) target[key] = normalizedEntry[key];
+      }
+    }
+    target.prdItems = normalizePrLinkItems(target.prdItems || []);
+    for (const linkedItemId of linkedItemIds) {
+      if (!target.prdItems.includes(linkedItemId)) {
+        target.prdItems.push(linkedItemId);
+        linked = true;
+      }
+    }
+    record = { ...target, prdItems: [...target.prdItems] };
+    return prs;
+  });
+
+  if (!skipped) {
+    for (const linkedItemId of linkedItemIds) {
+      addPrLink(canonicalId, linkedItemId, { project, prNumber, url: normalizedEntry.url || '' });
+    }
+  }
+
+  return { id: canonicalId, prNumber, created, linked, skipped, record };
+}
+
 // ─── Cross-Platform Process Kill Helpers ─────────────────────────────────────
 
 function killGracefully(proc, graceMs = 5000) {
@@ -2203,6 +2277,7 @@ module.exports = {
   findPrRecord,
   normalizePrRecord,
   normalizePrRecords,
+  upsertPullRequestRecord,
   nextWorkItemId,
   getAdoOrgBase,
   sanitizePath,

package/engine.js

@@ -1268,15 +1268,19 @@ async function spawnAgent(dispatchItem, config) {
     }
 
     // Parse output and run all post-completion hooks
-    const { resultSummary, autoRecovered } = await runPostCompletionHooks(dispatchItem, agentId, code, stdout, config);
+    const { resultSummary, autoRecovered, completionContractFailure } = await runPostCompletionHooks(dispatchItem, agentId, code, stdout, config);
 
     // Move from active to completed in dispatch (single source of truth for agent status)
     // autoRecovered: agent failed after creating PRs — treat as success
-    const effectiveResult = (code === 0 || autoRecovered) ? DISPATCH_RESULT.SUCCESS : DISPATCH_RESULT.ERROR;
-    const completeOpts = effectiveResult === DISPATCH_RESULT.ERROR && failureClass ? { failureClass } : {};
+    const effectiveResult = completionContractFailure ? DISPATCH_RESULT.ERROR : ((code === 0 || autoRecovered) ? DISPATCH_RESULT.SUCCESS : DISPATCH_RESULT.ERROR);
+    const completeOpts = completionContractFailure
+      ? { processWorkItemFailure: false }
+      : (effectiveResult === DISPATCH_RESULT.ERROR && failureClass ? { failureClass } : {});
     // Extract last 5 non-empty stderr lines as error context when exit code is non-zero
     let errorReason = '';
-    if (effectiveResult === DISPATCH_RESULT.ERROR) {
+    if (completionContractFailure) {
+      errorReason = completionContractFailure.reason || 'PR attachment contract failed';
+    } else if (effectiveResult === DISPATCH_RESULT.ERROR) {
       errorReason = stderr.split('\n').filter(l => l.trim()).slice(-5).join(' | ').trim().slice(0, 300);
       // W-mo3zul9pirjb — when claude CLI exits in <3s with code 1 and no output (the
       // "silent crash" pattern seen during scheduled tasks when the box went to sleep

package/package.json

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