@yemi33/minions 0.1.2193 → 0.1.2194

package/dashboard.js

@@ -7363,19 +7363,20 @@ const server = http.createServer(async (req, res) => {
         return data;
       }, { defaultValue: {} });
 
-      // W-mqacrzis0003df4a — Fresh source-plan staleness check. Approve is the
-      // last gate before materialization, and the diff-aware regen block below
-      // gates on `wasStale`. The persisted `data.planStale` flag lags by an
-      // engine tick (~10s); without this fresh stat a fast user can Approve
-      // within the tick window, `wasStale` stays false, the diff-aware regen
-      // is silently skipped, and items materialize from the OLD PRD. Mirrors
-      // the staleness logic in engine/queries.js#getPrdInfo + the /api/plans
-      // handler above so all three readers agree.
+      // W-mqacrzis0003df4a + W-mqfevwr60018bd09 — Fresh source-plan
+      // staleness check (content-hash gated). Approve is the last gate
+      // before materialization, and the diff-aware regen block below gates
+      // on `wasStale`. The persisted `data.planStale` flag lags by an
+      // engine tick (~10s); without this fresh stat a fast user can
+      // Approve within the tick window, `wasStale` stays false, the
+      // diff-aware regen is silently skipped, and items materialize from
+      // the OLD PRD. The content-hash gate (W-mqfevwr60018bd09) also
+      // ensures path-only repoints don't fire the destructive diff-aware
+      // regen — Mirrors the staleness logic in engine/queries.js#getPrdInfo
+      // and the /api/plans handler above so all three readers agree.
       if (!wasStale && plan && plan.source_plan && plan.sourcePlanModifiedAt) {
         try {
-          const sourceMtime = Math.floor(fs.statSync(path.join(PLANS_DIR, plan.source_plan)).mtimeMs);
-          const recorded = new Date(plan.sourcePlanModifiedAt).getTime();
-          if (recorded && sourceMtime > recorded) wasStale = true;
+          if (shared.isSourcePlanContentStale(PLANS_DIR, plan).stale) wasStale = true;
         } catch { /* source plan may have been deleted/renamed — fall through with wasStale=false */ }
       }
 

package/engine/queries.js

@@ -1892,13 +1892,14 @@ function getPrdInfo(config) {
           }
           if (!plan || !plan.missing_features) continue;
 
-          // Staleness: compare source plan mtime to recorded sourcePlanModifiedAt
+          // Staleness: gate on actual source-plan content change rather
+          // than mtime alone (W-mqfevwr60018bd09). Pure path / pure mtime
+          // drifts return stale=false here so a repointed source_plan
+          // doesn't masquerade as a real revision in the cached PRD info.
           let planStale = false;
           if (!archived && plan.source_plan) {
             try {
-              const sourceMtime = Math.floor(fs.statSync(path.join(PLANS_DIR, plan.source_plan)).mtimeMs);
-              const recorded = plan.sourcePlanModifiedAt ? new Date(plan.sourcePlanModifiedAt).getTime() : null;
-              if (recorded && sourceMtime > recorded) planStale = true;
+              planStale = shared.isSourcePlanContentStale(PLANS_DIR, plan).stale;
             } catch { /* optional */ }
           }
           existingPrds.push({

package/engine/shared.js

@@ -657,6 +657,103 @@ function safeReadDir(dir) {
   try { return fs.readdirSync(dir); } catch { return []; }
 }
 
+// ── PRD source-plan resolution & content hashing (W-mqfevwr60018bd09) ────────
+//
+// Repointing a PRD's `source_plan` field (e.g. plans/foo.md →
+// plans/archive/foo.md, or any operator edit that touches mtime without
+// changing the markdown body) used to trigger the diff-aware PRD resync as
+// if the plan content had changed — destroying / re-materializing work
+// items even though only the POINTER moved. These helpers gate the
+// destructive resync on actual *content* change via a sha256 hash, and
+// also fall back to plans/archive/<basename> so a silently-relocated
+// source plan no longer spams ENOENT warnings on every tick.
+
+/**
+ * Resolve a PRD's `source_plan` field to an absolute file path under
+ * `plansDir`. Tries the direct join first; falls back to
+ * plansDir/archive/<basename(source_plan)> when the direct path is
+ * missing. Returns null when neither location resolves to a regular file.
+ */
+function resolveSourcePlanPath(plansDir, sourcePlan) {
+  if (!plansDir || !sourcePlan || typeof sourcePlan !== 'string') return null;
+  const direct = path.join(plansDir, sourcePlan);
+  try { if (fs.statSync(direct).isFile()) return direct; } catch { /* miss */ }
+  const archived = path.join(plansDir, 'archive', path.basename(sourcePlan));
+  try { if (fs.statSync(archived).isFile()) return archived; } catch { /* miss */ }
+  return null;
+}
+
+/**
+ * Compute a deterministic sha256 hex digest of a source plan markdown
+ * file. Returns null when the file cannot be read. Used to gate the
+ * destructive PRD resync on actual content change rather than mtime
+ * or path drift.
+ */
+function computeSourcePlanContentHash(absPath) {
+  if (!absPath || typeof absPath !== 'string') return null;
+  try {
+    const buf = fs.readFileSync(absPath);
+    return crypto.createHash('sha256').update(buf).digest('hex');
+  } catch { return null; }
+}
+
+/**
+ * Decide whether a PRD's source plan has *actually* changed since the
+ * last sync, gating the destructive diff-aware resync on content change
+ * rather than mtime or path drift.
+ *
+ * Returns:
+ *   {
+ *     stale: boolean,           // true → callers should treat the PRD as stale
+ *     contentChanged: boolean,  // true iff we have BOTH hashes AND they differ
+ *     currentHash: string|null, // computed only when mtime advanced
+ *     resolvedPath: string|null,// absolute path of the resolved markdown
+ *     sourceMtime: number|null, // floor(ms) mtime of the resolved file
+ *   }
+ *
+ * `stale` is true only when:
+ *   - the resolved file exists, AND
+ *   - mtime advanced past plan.sourcePlanModifiedAt, AND
+ *   - either no _sourcePlanContentHash was recorded on the PRD (legacy
+ *     fallback to mtime — preserves pre-fix behavior on first encounter),
+ *     OR the recorded hash differs from the current file's hash.
+ *
+ * `contentChanged` is true only when both the recorded hash and the
+ * current hash exist AND differ. Pure-pointer / pure-mtime drifts leave
+ * `contentChanged` false so callers can silently re-baseline
+ * `sourcePlanModifiedAt` (and `_sourcePlanContentHash` for legacy PRDs)
+ * without triggering the destructive resync pipeline.
+ */
+function isSourcePlanContentStale(plansDir, plan) {
+  const out = {
+    stale: false, contentChanged: false,
+    currentHash: null, resolvedPath: null, sourceMtime: null,
+  };
+  if (!plan || typeof plan !== 'object' || !plan.source_plan) return out;
+  const resolved = resolveSourcePlanPath(plansDir, plan.source_plan);
+  out.resolvedPath = resolved;
+  if (!resolved) return out;
+  let mtime;
+  try { mtime = Math.floor(fs.statSync(resolved).mtimeMs); } catch { return out; }
+  out.sourceMtime = mtime;
+  const recorded = plan.sourcePlanModifiedAt ? new Date(plan.sourcePlanModifiedAt).getTime() : null;
+  if (!recorded || mtime <= recorded) return out;
+  // mtime advanced — verify the content actually differs before flagging.
+  out.currentHash = computeSourcePlanContentHash(resolved);
+  const recordedHash = plan._sourcePlanContentHash || null;
+  if (recordedHash && out.currentHash) {
+    out.contentChanged = recordedHash !== out.currentHash;
+    out.stale = out.contentChanged;
+  } else {
+    // Legacy PRD with no recorded hash — fall back to mtime semantics so
+    // we don't silently ignore real revisions made before the hash field
+    // existed. The engine sweep records the fresh hash on this pass so
+    // subsequent mtime-only drifts no longer trigger resync.
+    out.stale = true;
+  }
+  return out;
+}
+
 // ── SQL-routing shim for migrated state files ──────────────────────────────
 //
 // Phase 9 (post-Phase 8 cleanup): every state file that has a SQL backing
@@ -8211,6 +8308,9 @@ module.exports = {
   getProjectOrg,
   getAdoOrgBase,
   sanitizePath,
+  resolveSourcePlanPath, // W-mqfevwr60018bd09 — PRD staleness: resolve source_plan to absolute path (archive-aware)
+  computeSourcePlanContentHash, // W-mqfevwr60018bd09 — sha256 of source plan markdown body
+  isSourcePlanContentStale, // W-mqfevwr60018bd09 — gate destructive PRD resync on actual content change
   sanitizeBranch,
   getOperatorLogin,
   deriveWorkItemBranchName,

package/engine.js

@@ -5348,34 +5348,72 @@ function materializePlansAsWorkItems(config) {
       }
     } catch (e) { log('warn', `Sequential ID remapping failed for ${file}: ${e.message}`); }
 
-    // Plan staleness: if source_plan .md was modified since last sync, auto-clean and re-sync
+    // Plan staleness: if source_plan markdown content was modified since
+    // last sync, auto-clean and re-sync. W-mqfevwr60018bd09 — gate the
+    // destructive resync on a sha256 content hash rather than mtime alone
+    // so a path-only repoint (e.g. operator changes `source_plan` from
+    // `plans/foo.md` to `plans/archive/foo.md` to silence ENOENT warnings)
+    // no longer destroys work items when the markdown body is identical.
     if (plan.source_plan) {
-      const sourcePlanPath = path.join(PLANS_DIR, plan.source_plan);
+      const staleness = shared.isSourcePlanContentStale(PLANS_DIR, plan);
+      const resolved = staleness.resolvedPath;
+      const sourceMtime = staleness.sourceMtime;
+      const recorded = plan.sourcePlanModifiedAt ? new Date(plan.sourcePlanModifiedAt).getTime() : null;
       try {
-        const sourceMtime = Math.floor(fs.statSync(sourcePlanPath).mtimeMs); // floor to strip sub-ms Windows precision
-        const recorded = plan.sourcePlanModifiedAt ? new Date(plan.sourcePlanModifiedAt).getTime() : null;
-        if (!recorded) {
-          // First time seeing this plan — record baseline mtime (no clean needed)
+        if (!resolved) {
+          // Neither plans/<source_plan> nor plans/archive/<basename> exists.
+          // Stay quiet — emitting an ENOENT warn every tick was the original
+          // noise that prompted operators to repoint source_plan and trigger
+          // the destructive resync (see W-mqfevwr60018bd09 repro).
+        } else if (!recorded) {
+          // First time seeing this plan — baseline both the mtime and the
+          // content hash so future ticks can distinguish path-only drift
+          // from a real revision.
+          const baselineHash = staleness.currentHash || shared.computeSourcePlanContentHash(resolved);
           plan = mutatePrdLocked(file, plan, (current) => {
             if (!current.sourcePlanModifiedAt) current.sourcePlanModifiedAt = new Date(sourceMtime).toISOString();
+            if (!current._sourcePlanContentHash && baselineHash) current._sourcePlanContentHash = baselineHash;
             return current;
           }, { skipWriteIfUnchanged: true });
-        } else if (sourceMtime > recorded) {
-          // Source plan changed — auto-clean pending/failed items so they re-materialize with updated data
+        } else if (staleness.stale) {
+          // mtime advanced AND content actually changed (or this is a
+          // legacy PRD with no recorded hash — see isSourcePlanContentStale).
+          // Run the destructive resync as before.
           log('info', `Source plan ${plan.source_plan} updated — re-syncing PRD ${file}`);
           autoCleanPrdWorkItems(file, config);
 
-          // Handle PRD based on current status
           const prdStatus = plan.status || (plan.requires_approval ? 'awaiting-approval' : null);
+          const refreshedHash = staleness.currentHash || shared.computeSourcePlanContentHash(resolved);
 
           plan = mutatePrdLocked(file, plan, (current) => {
             current.sourcePlanModifiedAt = new Date(sourceMtime).toISOString();
+            if (refreshedHash) current._sourcePlanContentHash = refreshedHash;
             current.lastSyncedFromPlan = ts();
             const currentPrdStatus = current.status || (current.requires_approval ? 'awaiting-approval' : null);
             if (currentPrdStatus) current.planStale = true;
             return current;
           });
           if (prdStatus) log('info', `PRD ${file} flagged as stale (plan revised while ${prdStatus}) — user can regenerate from dashboard`);
+        } else if (sourceMtime > recorded) {
+          // mtime drifted forward but content hash matches — silently
+          // re-baseline the tracking fields so we don't keep recomputing
+          // the hash on every tick. No resync, no planStale flip.
+          const refreshedHash = staleness.currentHash || shared.computeSourcePlanContentHash(resolved);
+          plan = mutatePrdLocked(file, plan, (current) => {
+            current.sourcePlanModifiedAt = new Date(sourceMtime).toISOString();
+            if (refreshedHash && !current._sourcePlanContentHash) current._sourcePlanContentHash = refreshedHash;
+            return current;
+          }, { skipWriteIfUnchanged: true });
+        } else if (!plan._sourcePlanContentHash) {
+          // Steady state but no hash recorded yet (PRD pre-dates this fix).
+          // Backfill silently so the very next path-only repoint is a no-op.
+          const baselineHash = shared.computeSourcePlanContentHash(resolved);
+          if (baselineHash) {
+            plan = mutatePrdLocked(file, plan, (current) => {
+              if (!current._sourcePlanContentHash) current._sourcePlanContentHash = baselineHash;
+              return current;
+            }, { skipWriteIfUnchanged: true });
+          }
         }
       } catch (e) { log('warn', 'plan staleness check: ' + e.message); }
     }

package/package.json

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