@yemi33/minions 0.1.1866 → 0.1.1868

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.1.1868 (2026-05-11)
+
+### Other
+- docs(shared): JSDoc + tests for getCanonicalPrId (#2339)
+
 ## 0.1.1866 (2026-05-11)
 
 ### Other

package/engine/cooldown.js

@@ -236,7 +236,9 @@ module.exports = {
   loadCooldowns,
   saveCooldowns,
   isOnCooldown,
+  normalizePrHeadForCooldown, // exported for testing
   getPrReviewHead,
+  getPrReviewCooldownBase, // exported for testing
   getPrReviewCooldownKey,
   clearLegacyPrReviewCooldown,
   setCooldown,

package/engine/lifecycle.js

@@ -2929,9 +2929,40 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
   // Must run BEFORE updateWorkItemStatus(DONE) — otherwise _retryCount is deleted and retries never advance
   if (effectiveSuccess && type === WORK_TYPE.PLAN_TO_PRD && meta?.item?.id) {
     let prdFound = false;
+    let resolvedPrdFilename = null;
     const expectedFile = meta.item._prdFilename;
     if (expectedFile) {
-      prdFound = fs.existsSync(path.join(PRD_DIR, expectedFile));
+      // Inline `fs.existsSync(path.join(PRD_DIR, expectedFile))` is the literal
+      // substring pinned by source-text regression test (test/unit.test.js#893).
+      // Do not refactor into a temp variable without updating that assertion.
+      if (fs.existsSync(path.join(PRD_DIR, expectedFile))) {
+        // Defense-in-depth (W-mozkn1bb001j66fd): a near-simultaneous plan-to-prd
+        // dispatch for a different plan may have clobbered our pinned filename.
+        // Verify the file's source_plan matches our planFile before accepting it.
+        // Without this check we'd mark the WI done against ANOTHER plan's PRD.
+        if (meta.item.planFile) {
+          try {
+            const prd = safeJson(path.join(PRD_DIR, expectedFile));
+            if (prd && prd.source_plan === meta.item.planFile) {
+              prdFound = true;
+              resolvedPrdFilename = expectedFile;
+            } else {
+              log('warn', `plan-to-prd ${meta.item.id}: file "${expectedFile}" exists but source_plan="${prd?.source_plan ?? '(unknown)'}" doesn't match expected planFile="${meta.item.planFile}" — possible collision, scanning by source_plan`);
+            }
+          } catch (e) {
+            // Unparseable PRD file — log and accept (legacy behavior). A real
+            // collision could hide behind a parse error, so the warn keeps the
+            // anomaly visible for follow-up rather than failing silently.
+            log('warn', `plan-to-prd ${meta.item.id}: file "${expectedFile}" exists but failed to parse (${e.message}) — accepting as legacy behavior; manual inspection recommended if this recurs`);
+            prdFound = true;
+            resolvedPrdFilename = expectedFile;
+          }
+        } else {
+          // No planFile to verify against — fall back to legacy existence check.
+          prdFound = true;
+          resolvedPrdFilename = expectedFile;
+        }
+      }
     }
     if (!prdFound && meta.item.planFile) {
       try {
@@ -2939,11 +2970,38 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
           if (!f.endsWith('.json')) continue;
           try {
             const prd = safeJson(path.join(PRD_DIR, f));
-            if (prd && prd.source_plan === meta.item.planFile) { prdFound = true; break; }
+            if (prd && prd.source_plan === meta.item.planFile) {
+              prdFound = true;
+              resolvedPrdFilename = f;
+              break;
+            }
           } catch {}
         }
       } catch {}
     }
+    // Migrate _prdFilename when the source_plan scan found our PRD under a
+    // different on-disk filename (e.g. agent bumped past a clobbered name, or
+    // a previous tick pinned a stale name). Future readers (artifacts, dashboard
+    // links) need to point at the actual file.
+    if (prdFound && resolvedPrdFilename && resolvedPrdFilename !== expectedFile) {
+      const wiPath = resolveWorkItemPath(meta);
+      if (wiPath) {
+        try {
+          mutateJsonFileLocked(wiPath, data => {
+            if (!Array.isArray(data)) return data;
+            const w = data.find(i => i.id === meta.item.id);
+            if (!w) return data;
+            w._prdFilename = resolvedPrdFilename;
+            if (w._artifacts && typeof w._artifacts === 'object') {
+              w._artifacts.prd = resolvedPrdFilename;
+            }
+            return data;
+          }, { skipWriteIfUnchanged: true });
+          meta.item._prdFilename = resolvedPrdFilename;
+          log('info', `plan-to-prd ${meta.item.id}: migrated _prdFilename "${expectedFile}" → "${resolvedPrdFilename}" (matched by source_plan, likely collision)`);
+        } catch (err) { log('warn', `plan-to-prd _prdFilename migration: ${err.message}`); }
+      }
+    }
     if (!prdFound) {
       skipDoneStatus = true;
       const wiPath = resolveWorkItemPath(meta);

package/engine/meeting.js

@@ -910,6 +910,19 @@ module.exports = {
   // getMeetings/discoverMeetingWork/collectMeetingFindings/checkMeetingTimeouts,
   // never these helpers directly.
   resolveMeetingNoteArtifactPath,
+  readMeetingNoteArtifact,
+  isTerminalMeetingStatus,
+  expectedMeetingStatusForRound,
+  roundKeyFor,
+  getRoundFailures,
+  hasRoundFailure,
+  hasRoundSuccess,
+  hasRoundTerminalOutcome,
+  isEmptyMeetingContent,
+  isSuccessfulStructuredCompletion,
+  getStructuredNoteArtifacts,
+  formatMeetingContributions,
+  stripMeetingSummaryMarkdown,
   cleanMeetingSummaryText,
   splitMeetingSummaryFragments,
   truncateMeetingSummary,

package/engine/shared.js

@@ -2751,6 +2751,34 @@ function isPrCompatibleWithProject(project, prRef, url = '') {
   return !getPrProjectScopeMismatch(project, prRef, url);
 }
 
+/**
+ * Build a canonical, repository-scoped PR identifier.
+ *
+ * Disambiguates PR numbers across hosts/repos by prefixing with the host scope
+ * derived from `url` (if it parses as a known host PR URL) or otherwise from
+ * the `project` config. The `url` always wins when present so that a PR
+ * record carrying a foreign-host URL is not mis-scoped to its current
+ * project.
+ *
+ * Output shapes:
+ *   - GitHub project: `github:<owner>/<repo>#<prNumber>`        (e.g. `github:yemi33/minions#1234`)
+ *   - ADO project:    `ado:<org>/<adoProject>/<repo>#<prNumber>` (e.g. `ado:office/office/Office#5134010`)
+ *   - No usable scope but numeric prRef: `PR-<prNumber>` (legacy fallback)
+ *   - Unparseable: returns the raw id string (may be empty)
+ *
+ * @param {object|null} project - Project config; uses `repoHost`, `adoOrg`,
+ *   `adoProject`, `repoName`, and `prUrlBase` to derive the scope. May be null
+ *   when only `url` provides scope.
+ *   .
+ * @param {number|string|object} prRef - PR reference. Accepts a numeric id,
+ *   a numeric string, an existing canonical id (`github:owner/repo#42`),
+ *   a host PR URL, or a PR-record object with `id`/`url`/`prNumber` fields.
+ * @param {string} [url=''] - Full PR URL used for host disambiguation
+ *   (primary signal for ADO vs GitHub when `prRef` is bare-numeric and the
+ *   project config disagrees with the URL host).
+ * @returns {string} Canonical PR id string (see shapes above), or the raw id
+ *   when no scope and no number can be derived.
+ */
 function getCanonicalPrId(project, prRef, url = '') {
   const isObjectRef = !!prRef && typeof prRef === 'object';
   const rawId = isObjectRef ? (prRef.id || '') : String(prRef || '');

package/engine.js

@@ -3985,7 +3985,16 @@ function discoverCentralWorkItems(config) {
           }
         }
         if (!prdFilename) {
-          // Generate unique PRD filename — check prd/ and prd/archive/ for collisions
+          // Generate unique PRD filename — check prd/, prd/archive/, AND any
+          // _prdFilename already pinned by sibling work items (W-mozkn1bb001j66fd):
+          //   - on-disk PRDs (prd/ + prd/archive/)
+          //   - other items in the central work-items list whose _prdFilename was
+          //     pinned by a previous tick (their PRD may not be on disk yet if
+          //     the agent hasn't completed)
+          //   - other items being prepared this same tick (mutations Map)
+          // Without these in-memory scopes two near-simultaneous plan-to-prd
+          // dispatches both pinned the same filename and the second agent
+          // silently overwrote the first PRD on disk.
           const prdBase = vars.project_filename_slug + '-' + dateStamp();
           prdFilename = prdBase + '.json';
           shared.sanitizePath(prdFilename, PRD_DIR);
@@ -3993,6 +4002,22 @@ function discoverCentralWorkItems(config) {
             ...prdFiles,
             ...safeReadDir(path.join(PRD_DIR, 'archive')).filter(f => f.endsWith('.json')),
           ]);
+          for (const otherItem of items) {
+            if (!otherItem || otherItem.id === item.id) continue;
+            if (otherItem._prdFilename && otherItem.planFile !== item.planFile) {
+              prdExisting.add(otherItem._prdFilename);
+            }
+          }
+          for (const [otherId, m] of mutations) {
+            if (otherId === item.id) continue;
+            // ORDERING NOTE: this loop reads m._prdFilename from the mutations
+            // Map; it works only because each item writes its pinned filename
+            // into mutations BEFORE the next iteration of the outer item loop
+            // reaches this code (see the mutations.set call ~5 lines below).
+            // A future refactor that batches Map writes after the per-item
+            // loop would silently break Layer 1 of the W-mozkn1bb001j66fd fix.
+            if (m && m._prdFilename) prdExisting.add(m._prdFilename);
+          }
           let prdCounter = 2;
           while (prdExisting.has(prdFilename)) { prdFilename = prdBase + '-' + prdCounter + '.json'; prdCounter++; }
         }

package/package.json

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