@yemi33/minions 0.1.2297 → 0.1.2298

package/docs/completion-reports.md

@@ -81,6 +81,7 @@ Do **not** invent, regenerate, or share the nonce across dispatches — each spa
 | `noop` | boolean | Canonical no-op signal. See [No-op semantics](#no-op-semantics). |
 | `noopReason` | string | Human-readable rationale shown when `noop: true`. Falls back to `summary` if absent. |
 | `files_changed` | string \| array | Comma-separated list (or array) of key files changed. |
+| `affected_files` | string[] | Optional array of relative file paths this dispatch touched or plans to touch. Used by the dispatcher to emit a conflict warning (`WI <new-id> may conflict with in-progress <existing-id> on files: [list]`) when a new WI's `affected_files` overlaps with an in-progress WI's `affected_files`. Logging-only — dispatch is never blocked. Stored back onto the work item after completion so re-dispatches can also participate in overlap detection. |
 | `tests` | string | `pass`, `fail`, `skipped`, `N/A`, or a free-form note like `skipped — relying on PR pipeline`. |
 | `pending` | string | Any remaining work, or `none`. |
 | `followups` | array | Optional. PR-comment follow-up work items the agent dispatched via `POST /api/work-items` with `meta.pr_followup` set. Each entry: `{wi_id, title, reason, parent_comment_id}`. See [PR-comment follow-ups](#pr-comment-follow-ups). |

package/engine/dispatch.js

@@ -166,6 +166,36 @@ function getBranchDispatchLockKey(entry) {
   return `${projectKey}:${normalizedBranch}`;
 }
 
+// ─── File-Overlap Conflict Detection (P-mqyp000ab028c9d0) ───────────────────
+//
+// Logging-only warning surfaced when a new WI declares affected_files that
+// overlap with files declared by a currently in-progress (active) WI. No
+// blocking — dispatch always proceeds. Goal: surface silent parallel edit
+// races before they become merge conflicts.
+
+function _getItemAffectedFiles(dispatchItem) {
+  const files = dispatchItem?.meta?.item?.affected_files;
+  if (!Array.isArray(files) || files.length === 0) return null;
+  const set = new Set(files.filter(f => typeof f === 'string' && f.length > 0));
+  return set.size > 0 ? set : null;
+}
+
+// Called inside addToDispatch (before push) to emit one log line per active
+// dispatch that shares at least one file with the incoming item.
+function _warnFileOverlap(newItem, activeDispatches) {
+  const newFiles = _getItemAffectedFiles(newItem);
+  if (!newFiles) return;
+  const newWiId = newItem.meta?.item?.id || newItem.id;
+  for (const existing of activeDispatches) {
+    const existingFiles = _getItemAffectedFiles(existing);
+    if (!existingFiles) continue;
+    const overlap = [...newFiles].filter(f => existingFiles.has(f));
+    if (overlap.length === 0) continue;
+    const existingWiId = existing.meta?.item?.id || existing.id;
+    log('warn', `WI ${newWiId} may conflict with in-progress ${existingWiId} on files: ${overlap.join(', ')}`);
+  }
+}
+
 function findActivePrOrBranchLock(dispatch, item) {
   const active = dispatch.active || [];
 
@@ -238,6 +268,7 @@ function addToDispatch(item) {
       log('info', `Dedup: skipping ${item.id} — ${activeLock.reason} already in ${activeLock.existing.id}`);
       return dispatch;
     }
+    _warnFileOverlap(item, dispatch.active || []);
     dispatch.pending.push(item);
     added = true;
     return dispatch;

package/engine/lifecycle.js

@@ -495,25 +495,25 @@ function checkPlanCompletion(meta, config) {
 function archivePlan(planFile, plan, projects, config) {
   const planPath = path.join(PRD_DIR, planFile);
 
-  // Archive PRD .json to prd/archive/
-  const prdArchiveDir = path.join(PRD_DIR, 'archive');
-  if (!fs.existsSync(prdArchiveDir)) fs.mkdirSync(prdArchiveDir, { recursive: true });
+  // Phase 10 — archive the PRD IN PLACE: flag it (archived/status/archivedAt)
+  // where it sits, rather than MOVING it to prd/archive/. This matches the
+  // canonical dashboard (_archivePrdPostProcess, #533) + watch-action archive
+  // paths. The legacy move was the LAST path still physically relocating a PRD,
+  // and it reintroduced the live↔archive basename-collision class (footgun #7)
+  // that the in-place flag model retired — plus it needed a .backup neutralize
+  // that is moot now that prd/*.json never gets a .backup sidecar at all (#570).
+  // mutateJsonFileLocked dual-writes the flag into SQL via the chokepoint; the
+  // archived-PRD scanner guards (#530) already treat status:'archived' correctly.
   try {
     if (fs.existsSync(planPath)) {
-      // DATA-LOSS GUARD: moveFileNoClobber dedupes + retries so a same-basename
-      // collision can't silently overwrite a previously-archived PRD (+ its
-      // completed work-item history). renameSync clobbers on Windows.
-      const prdDest = shared.moveFileNoClobber(planPath, prdArchiveDir, planFile);
-      log('info', `Archived completed PRD: prd/archive/${path.basename(prdDest)}`);
-    }
-    // Remove .backup sidecar — if left behind, safeJson() would restore the pre-completion
-    // snapshot (status: approved, no _completionNotified) on engine restart, re-triggering
-    // plan completion and spawning duplicate verify tasks for already-archived plans.
-    // On Windows, the unlink can fail due to file locking; overwrite with archived status
-    // as a fallback so a restored backup is inert even if deletion fails.
-    const backupCleanup = shared.neutralizeJsonBackupSidecar(planPath);
-    if (!backupCleanup.ok) {
-      log('warn', `Archive backup cleanup failed for ${planFile}: unlink failed (${backupCleanup.unlinkError}); fallback neutralize failed (${backupCleanup.writeError})`);
+      mutateJsonFileLocked(planPath, (data) => {
+        if (!data || Array.isArray(data) || typeof data !== 'object') data = {};
+        data.status = 'archived';
+        data.archived = true;
+        data.archivedAt = new Date().toISOString();
+        return data;
+      }, { defaultValue: {} });
+      log('info', `Archived PRD in place: ${planFile} (archived flag set)`);
     }
   } catch (err) {
     log('warn', `Failed to archive PRD ${planFile}: ${err.message}`);
@@ -777,6 +777,27 @@ function updateWorkItemStatus(meta, status, reason) {
   syncPrdItemStatus(itemId, status, meta.item?.sourcePlan);
 }
 
+// P-mqyp000ab028c9d0 — persist affected_files from a completion report onto the
+// work item for future file-overlap checks. Runs only when the completion report
+// declares a non-empty string[] for `affected_files`; no-ops otherwise.
+function storeAffectedFilesFromCompletion(meta, structuredCompletion) {
+  const raw = structuredCompletion?.affected_files;
+  if (!Array.isArray(raw) || raw.length === 0) return;
+  const files = raw.filter(f => typeof f === 'string' && f.length > 0);
+  if (files.length === 0) return;
+  const itemId = meta?.item?.id;
+  if (!itemId) return;
+  const wiPath = resolveWorkItemPath(meta);
+  if (!wiPath) return;
+  mutateJsonFileLocked(wiPath, (items) => {
+    if (!Array.isArray(items)) return items;
+    const target = items.find(i => i.id === itemId);
+    if (!target) return items;
+    target.affected_files = files;
+    return items;
+  }, { skipWriteIfUnchanged: true });
+}
+
 const _VALID_PRD_STATUSES = new Set([...Object.values(WI_STATUS), 'missing']);
 // (#984) PRD statuses that are stale when the work item is actually done
 const _STALE_PRD_STATUSES = new Set([WI_STATUS.DISPATCHED, WI_STATUS.FAILED, WI_STATUS.PENDING]);
@@ -5426,6 +5447,10 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
       meta._noopReason = noopRationale.slice(0, 500);
     }
     updateWorkItemStatus(meta, WI_STATUS.DONE, '');
+    // P-mqyp000ab028c9d0 — persist affected_files from the completion report
+    // onto the work item so future dispatches of the same WI can participate in
+    // the file-overlap conflict detection in dispatch.js#_warnFileOverlap.
+    try { storeAffectedFilesFromCompletion(meta, structuredCompletion); } catch (err) { log('warn', `storeAffectedFilesFromCompletion: ${err.message}`); }
     // W-mqtplpk6001oe6d5 — back-stamp workItemId onto the PRD item now that WI is done.
     if (meta.item.sourcePlan) {
       try { stampPrdItemWorkItemId(meta.item.id, meta.item.sourcePlan); } catch (err) { log('warn', `stampPrdItemWorkItemId: ${err.message}`); }

package/engine.js

@@ -5762,15 +5762,6 @@ function safePrdProjectSlug(projectName) {
   return slug || 'project';
 }
 
-function safePrdFilenameForProject(projectName, suffix) {
-  const fileName = `${safePrdProjectSlug(projectName)}-${suffix}.json`;
-  const resolved = shared.sanitizePath(fileName, PRD_DIR);
-  if (path.dirname(resolved) !== path.resolve(PRD_DIR)) {
-    throw new Error('invalid PRD filename: nested paths are not allowed');
-  }
-  return path.basename(resolved);
-}
-
 /**
  * Atomically reserve a unique PRD filename in `prdDir` (P-9b7e5d3c).
  *
@@ -10570,7 +10561,7 @@ module.exports = {
 
   // Shared helpers (used by lifecycle.js and tests)
   reconcileItemsWithPrs, detectDependencyCycles,
-  safePrdProjectSlug, safePrdFilenameForProject, // exported for testing (W-mqyn7joo0004079f)
+  safePrdProjectSlug, // exported for testing (W-mqyn7joo0004079f)
   isSoftFixDispatch, // exported for testing (W-mqyn7joo0004079f)
   areDependenciesMet, // exported for testing (P-bf04-decompose-zero-children)
   parseConflictFiles, pruneAncestorDeps, preflightMergeSimulation, // exported for testing

package/package.json

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