@yemi33/minions 0.1.2193 → 0.1.2195

package/dashboard/js/command-center.js

@@ -476,6 +476,8 @@ function ccAbort() {
 
 function toggleCommandCenter() {
   _ccOpen = !_ccOpen;
+  // Opening CC means the operator found it — retire the first-use coachmark.
+  if (_ccOpen && typeof dismissCcHint === 'function') dismissCcHint();
   var drawer = document.getElementById('cc-drawer');
   var overlay = document.getElementById('cc-overlay');
   if (_ccOpen) ccApplySavedWidth();

package/dashboard/js/fre.js

@@ -188,4 +188,128 @@ function renderFre(statusOrProjects) {
     '</div>';
 }
 
-window.MinionsFre = { renderFre, dismissFre, openSettingsToDefaultCli, _freReset, FRE_DISMISS_KEY };
+// ── Command Center first-use coachmark ──────────────────────────────────────
+// A small popup anchored under the Command Center header button, shown to
+// brand-new operators who have never used CC. Teaches the primary entry point:
+// "prompt the Command Center to ask it to dispatch work." Self-contained and
+// idempotent — safe to call renderCcHint() every refresh tick.
+//
+// Trigger: NOT dismissed AND the operator has never sent a CC message (no
+// 'cc-tabs' entry carries any messages). Auto-suppressed while the CC drawer
+// is open. Dismissed permanently when the user opens CC (see
+// toggleCommandCenter in command-center.js) or clicks "Got it".
+
+const CC_HINT_DISMISS_KEY = 'minions_cc_hint_dismissed';
+const CC_HINT_MOUNT_ID = 'cc-hint-coachmark';
+
+function _ccHintIsDismissed() {
+  try { return localStorage.getItem(CC_HINT_DISMISS_KEY) === '1'; } catch { return false; }
+}
+
+// "Brand new" = the operator has never sent a Command Center message. Reads the
+// same 'cc-tabs' localStorage key command-center.js persists; any tab carrying
+// at least one message means CC has been used and the hint has served its
+// purpose. Absent/empty/parse-error all read as new (fail toward showing).
+function _ccHintUserIsNew() {
+  try {
+    const raw = localStorage.getItem('cc-tabs');
+    if (!raw) return true;
+    const tabs = JSON.parse(raw);
+    if (!Array.isArray(tabs) || tabs.length === 0) return true;
+    return !tabs.some(function(t) { return t && Array.isArray(t.messages) && t.messages.length > 0; });
+  } catch { return true; }
+}
+
+function _ccHintRemove() {
+  const mount = document.getElementById(CC_HINT_MOUNT_ID);
+  if (mount && mount.parentNode) mount.parentNode.removeChild(mount);
+}
+
+function dismissCcHint() {
+  try { localStorage.setItem(CC_HINT_DISMISS_KEY, '1'); } catch { /* expected */ }
+  _ccHintRemove();
+}
+
+// Reset helper (exposed for tests / debugging only). Not wired to UI.
+function _ccHintReset() {
+  try { localStorage.removeItem(CC_HINT_DISMISS_KEY); } catch { /* expected */ }
+}
+
+// Open the Command Center from the coachmark CTA, then dismiss the hint.
+function openCcFromHint() {
+  dismissCcHint();
+  if (typeof toggleCommandCenter === 'function' && !window._ccOpen) {
+    try { toggleCommandCenter(); } catch { /* drawer not mounted yet */ }
+  }
+}
+
+// Re-anchor the coachmark under the CC button. Called on render and on resize.
+function _ccHintPosition() {
+  const mount = document.getElementById(CC_HINT_MOUNT_ID);
+  const btn = document.getElementById('cc-toggle-btn');
+  if (!mount || !btn) return;
+  const rect = btn.getBoundingClientRect();
+  mount.style.top = (rect.bottom + 10) + 'px';
+  // Right-align the card to the button's right edge.
+  mount.style.right = Math.max(8, window.innerWidth - rect.right) + 'px';
+  // Point the caret at the button's horizontal centre.
+  const arrow = document.getElementById('cc-hint-arrow');
+  if (arrow) arrow.style.right = Math.max(12, (rect.width / 2) - 6) + 'px';
+}
+
+let _ccHintResizeBound = false;
+
+// Render the coachmark into document.body. Idempotent — bails out (and removes
+// any stale mount) when dismissed, when CC has been used, when the header
+// button isn't mounted yet, or while the drawer is open.
+function renderCcHint() {
+  if (_ccHintIsDismissed() || !_ccHintUserIsNew()) {
+    _ccHintRemove();
+    return;
+  }
+  const btn = document.getElementById('cc-toggle-btn');
+  if (!btn) return; // header not assembled yet
+  const drawer = document.getElementById('cc-drawer');
+  if (drawer && drawer.style.display === 'flex') {
+    // User already found CC — don't hover the hint over the open drawer.
+    _ccHintRemove();
+    return;
+  }
+
+  let mount = document.getElementById(CC_HINT_MOUNT_ID);
+  if (!mount) {
+    mount = document.createElement('div');
+    mount.id = CC_HINT_MOUNT_ID;
+    mount.style.cssText = [
+      'position:fixed',
+      'z-index:330',
+      'width:260px',
+      'padding:14px 16px',
+      'background:var(--surface)',
+      'border:1px solid var(--blue)',
+      'border-radius:var(--radius-lg)',
+      'box-shadow:var(--shadow-md)',
+      'color:var(--text)',
+      'font-size:var(--text-md)',
+      'line-height:1.5',
+    ].join(';');
+    document.body.appendChild(mount);
+    // eslint-disable-next-line no-unsanitized/property -- reason: static string literal — no user-controlled data is interpolated
+    mount.innerHTML =
+      '<div id="cc-hint-arrow" style="position:absolute;top:-7px;width:12px;height:12px;background:var(--surface);border-left:1px solid var(--blue);border-top:1px solid var(--blue);transform:rotate(45deg)"></div>' +
+      '<div style="font-weight:700;color:var(--blue);margin-bottom:4px">&#x1F44B; Start here</div>' +
+      '<div style="color:var(--text)">Prompt your <strong>Command Center</strong> here to ask it to dispatch work.</div>' +
+      '<div style="display:flex;gap:8px;margin-top:12px">' +
+        '<button onclick="openCcFromHint()" class="btn-primary-solid" style="padding:5px 12px;font-size:var(--text-sm)">Open Command Center</button>' +
+        '<button onclick="dismissCcHint()" style="padding:5px 12px;font-size:var(--text-sm);background:transparent;color:var(--muted);border:1px solid var(--border);border-radius:var(--radius-sm);cursor:pointer">Got it</button>' +
+      '</div>';
+  }
+  _ccHintPosition();
+  if (!_ccHintResizeBound) {
+    _ccHintResizeBound = true;
+    window.addEventListener('resize', _ccHintPosition);
+  }
+}
+
+window.MinionsFre = { renderFre, dismissFre, openSettingsToDefaultCli, _freReset, FRE_DISMISS_KEY,
+  renderCcHint, dismissCcHint, openCcFromHint, _ccHintReset, _ccHintUserIsNew, CC_HINT_DISMISS_KEY };

package/dashboard/js/refresh.js

@@ -612,6 +612,12 @@ function _processStatusUpdate(data, opts) {
   if (typeof renderFre === 'function') {
     _safeRender('fre', function() { renderFre(data); });
   }
+  // Command Center first-use coachmark — anchored under the CC header button
+  // for brand-new operators who have never sent a CC message. Idempotent +
+  // cheap; self-suppresses once CC is used or dismissed.
+  if (typeof renderCcHint === 'function') {
+    _safeRender('ccHint', function() { renderCcHint(); });
+  }
   // Notes file (notes.md) is now sourced from /state/notes.md. Same shape
   // as the legacy /api/status notes slice ({ content, updatedAt }); the
   // ETag mtime is parsed out of the response header for updatedAt.

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.2195",
   "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"