@yemi33/minions 0.1.2195 → 0.1.2197

package/engine/lifecycle.js

@@ -790,6 +790,19 @@ function reconcilePrdStatuses(config) {
 
 // ─── PR Sync from Output ─────────────────────────────────────────────────────
 
+const ONE_SHOT_CONTEXT_PR_TYPES = new Set([
+  WORK_TYPE.REVIEW,
+  WORK_TYPE.ASK,
+  WORK_TYPE.EXPLORE,
+]);
+
+function shouldSyncPrAsContextOnly(meta) {
+  const item = meta?.item;
+  if (!item?.oneShot || item.skipPr) return false;
+  const type = String(item.type || item.itemType || '').trim();
+  return ONE_SHOT_CONTEXT_PR_TYPES.has(type);
+}
+
 function syncPrsFromOutput(output, agentId, meta, config, opts = {}) {
   const { structuredCompletion = null } = opts;
   const outputText = String(output || '');
@@ -996,13 +1009,14 @@ function syncPrsFromOutput(output, agentId, meta, config, opts = {}) {
       url: prUrl,
       prdItems: meta?.item?.id ? [meta.item.id] : [],
       sourcePlan: meta?.item?.sourcePlan || '',
-      itemType: meta?.item?.itemType || ''
+      itemType: meta?.item?.itemType || '',
+      contextOnly: shouldSyncPrAsContextOnly(meta),
     };
     applyScheduleContextToPrEntry(entry, meta?.item, config);
-    // Issue #1772: one-off dispatches (e.g. human-initiated "review this PR" via CC)
-    // must not enroll the discovered PR into the auto eval loop. Tag _contextOnly so
-    // discoverFromPrs skips it for review/fix dispatch (still polled for status/comments).
-    if (meta?.item?.oneShot) entry._contextOnly = true;
+    // Issue #1772: explicit one-off review/ask/explore dispatches (for example,
+    // "review this PR" via CC) must stay reference-only. QA-session setup and
+    // other oneShot+skipPr PR-targeted work are operational context, not an
+    // observe toggle, so they must not demote a real tracked PR.
     newPrsByPath.get(prPath).entries.push({ prId, fullId, entry });
   }
 
@@ -1145,7 +1159,7 @@ function _existingPrRecordForCanonicalId(canonicalPrId) {
  * can render the real merged/abandoned status instead of a perpetual blue ○.
  *
  * Idempotent: returns `{ enrolled: false, reason: 'already_tracked' }` if a row
- * already exists. Marks new records with `_contextOnly: true` so the engine
+ * already exists. Marks new records with `contextOnly: true` so the engine
  * doesn't try to manage them (no re-dispatch of fix/review loops). Live state
  * is fetched via `gh pr view` for GitHub; ADO enrollment is best-effort with
  * a conservative ACTIVE default.
@@ -1259,7 +1273,7 @@ async function enrollPrFromCanonicalId(canonicalPrId, project, opts = {}) {
     url,
     prdItems: opts.itemId ? [opts.itemId] : [],
     _attachedAt: ts(),
-    _contextOnly: true,
+    contextOnly: true,
     _enrolledBy: 'enrollPrFromCanonicalId',
   };
   if (liveState && liveState.mergedAt) entry.mergedAt = liveState.mergedAt;
@@ -5144,7 +5158,13 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
       const itemId = meta.item.id;
       const schedRunsPath = path.join(ENGINE_DIR, 'schedule-runs.json');
       mutateJsonFileLocked(schedRunsPath, (runs) => {
+        // P-c549d07e — preserve existing fields (esp. recentWorkItemIds ring
+        // populated at dispatch time by engine/scheduler.writeScheduleRunEntry).
+        // The literal-object replacement that lived here previously silently
+        // clobbered the ring on every successful completion.
+        const existing = typeof runs[scheduleId] === 'object' && runs[scheduleId] ? runs[scheduleId] : {};
         runs[scheduleId] = {
+          ...existing,
           lastRun: typeof runs[scheduleId] === 'string' ? runs[scheduleId] : (runs[scheduleId]?.lastRun || ts()),
           lastWorkItemId: itemId,
           lastResult: effectiveSuccess ? DISPATCH_RESULT.SUCCESS : DISPATCH_RESULT.ERROR,

package/engine/pipeline.js

@@ -427,6 +427,12 @@ function executeTaskStage(stage, stageState, run, config, pipeline = {}) {
           ...(wiBranch ? { branch: wiBranch } : {}),
           _pipelineRun: run.runId,
           _pipelineStage: stage.id,
+          // P-c549d07e — back-link to the dispatcher (pipeline:<id>) so the
+          // WI detail modal can render a clickable chip via openArtifact()
+          // → openPipelineDetail. Kept alongside the existing createdBy /
+          // _pipelineRun / _pipelineStage fields so we don't disturb any
+          // existing readers — meta.spawnedBy is purely additive.
+          meta: { spawnedBy: 'pipeline:' + run.pipelineId },
         });
         return workItems;
       });
@@ -561,6 +567,8 @@ async function executePlanStage(stage, stageState, run, config, pipeline = {}) {
               planFile: existingPlanFile, created: ts(), createdBy: 'pipeline:' + run.pipelineId,
               // W-mp8ho6w500034a58: PLAN_TO_PRD is read-only — no branch needed.
               _pipelineRun: run.runId, _pipelineStage: stage.id,
+              // P-c549d07e — back-link chip (see executeTaskStage above).
+              meta: { spawnedBy: 'pipeline:' + run.pipelineId },
               ...(project ? { project: project.name } : {}),
             });
           }
@@ -657,6 +665,8 @@ async function executePlanStage(stage, stageState, run, config, pipeline = {}) {
           // W-mp8ho6w500034a58: PLAN_TO_PRD is read-only — no branch needed.
           _pipelineRun: run.runId,
           _pipelineStage: stage.id,
+          // P-c549d07e — back-link chip (see executeTaskStage above).
+          meta: { spawnedBy: 'pipeline:' + run.pipelineId },
           ...(project ? { project: project.name } : {}),
         });
       }

package/engine/queries.js

@@ -496,6 +496,72 @@ function getInboxFiles() {
   try { return fs.readdirSync(INBOX_DIR).filter(f => f.endsWith('.md')); } catch { return []; }
 }
 
+// P-34fa5d79 — Note ↔ Work Item ↔ KB Entry linkage.
+//
+// Parse the YAML frontmatter from a note body and return the parsed fields.
+// Same minimal contract as engine/kb-sweep.js#_parseFrontmatter — a single
+// shared regex would have been nicer but importing kb-sweep from queries
+// would form a circular dep with lifecycle (queries → kb-sweep → … →
+// queries), so we keep a local copy of the four-line parser.
+function _parseNoteFrontmatter(content) {
+  const m = String(content || '').match(/^---\n([\s\S]*?)\n---\n?/);
+  if (!m) return null;
+  const fm = {};
+  for (const line of m[1].split('\n')) {
+    const lm = line.match(/^([\w-]+):\s*(.*)$/);
+    if (lm) fm[lm[1]] = lm[2].trim();
+  }
+  return fm;
+}
+
+// Extract the WI id that a note's frontmatter cites, or null. Accepts the
+// three field-name conventions used across the repo today:
+//   - `work_item:` (dallas fix-summary template, the common case)
+//   - `wi:` (terser variant, used in a handful of newer notes)
+//   - `sourceItem:` (engine-emitted notes such as pr-auto-link-unverified)
+// `id:` itself is the note's own NOTE-… id and is intentionally NOT matched —
+// it would never carry a WI value in any existing convention.
+function _wiIdFromNoteFrontmatter(fm) {
+  if (!fm) return null;
+  return fm.work_item || fm.wi || fm.sourceItem || null;
+}
+
+// Build a wiId → [filename, ...] map by scanning the inbox + archive dirs.
+// Archive entries are prefixed with `archive:` so the dashboard renderer can
+// tell them apart (matches the convention already used by _artifacts.notes).
+// Pure-function helper exposed for testing.
+function _buildNotesByWiMap() {
+  const out = Object.create(null);
+  const addNote = (wiId, token) => {
+    if (!wiId || !token) return;
+    if (!out[wiId]) out[wiId] = [];
+    if (!out[wiId].includes(token)) out[wiId].push(token);
+  };
+  for (const f of safeReadDir(INBOX_DIR)) {
+    if (!f.endsWith('.md')) continue;
+    const fm = _parseNoteFrontmatter(safeRead(path.join(INBOX_DIR, f)));
+    const wiId = _wiIdFromNoteFrontmatter(fm);
+    if (wiId) addNote(wiId, f);
+  }
+  for (const f of safeReadDir(ARCHIVE_DIR)) {
+    if (!f.endsWith('.md')) continue;
+    const fm = _parseNoteFrontmatter(safeRead(path.join(ARCHIVE_DIR, f)));
+    const wiId = _wiIdFromNoteFrontmatter(fm);
+    if (wiId) addNote(wiId, 'archive:' + f);
+  }
+  return out;
+}
+
+// Public lookup — return the array of note tokens (filenames or
+// `archive:<filename>`) whose frontmatter cites this WI id. Returns [] when
+// nothing matches. Scans inbox + archive each call; for the bulk WI list
+// payload getWorkItems() pre-builds the map once per cache cycle.
+function notesForWorkItem(wiId) {
+  if (!wiId) return [];
+  const map = _buildNotesByWiMap();
+  return map[wiId] || [];
+}
+
 function getInbox() {
   return safeReadDir(INBOX_DIR)
     .filter(f => f.endsWith('.md'))
@@ -1745,6 +1811,9 @@ function getWorkItems(config) {
   // Use snapshot — sync access; cold start before any async warm returns [].
   // Best-effort enrichment for work item _artifacts.notes, not correctness-critical.
   const _kbEntries = getKnowledgeBaseEntriesSnapshot();
+  // P-34fa5d79 — pre-build the wiId → notes map so each item's _notes lookup
+  // is O(1) instead of re-scanning inbox+archive per item.
+  const _notesByWi = _buildNotesByWiMap();
   for (const item of allItems) {
     const arts = shared.isPlainObject(item._artifacts) ? { ...item._artifacts } : {};
     const agentId = item.dispatched_to || item.agent;
@@ -1779,6 +1848,13 @@ function getWorkItems(config) {
     else if (item.planFile) arts.plan = item.planFile;
     if (item._pr) arts.pr = item._pr;
     if (Object.keys(arts).length > 0) item._artifacts = arts;
+    // P-34fa5d79 — Note ↔ WI ↔ KB linkage. Slim string[] field of note
+    // filenames whose YAML frontmatter cites this WI. Archive notes are
+    // prefixed with `archive:` so the dashboard chip renderer can pick the
+    // right open path. Field is left undefined (not []) when empty so the
+    // /api/work-items JSON stays compact for the common no-notes case.
+    const mentions = _notesByWi[item.id];
+    if (mentions && mentions.length > 0) item._notes = mentions;
   }
 
   const statusOrder = {
@@ -2897,6 +2973,11 @@ module.exports = {
 
   // Inbox
   getInboxFiles, getInbox,
+  // P-34fa5d79 — Note ↔ Work Item ↔ KB Entry linkage.
+  notesForWorkItem,
+  _parseNoteFrontmatter, // exported for testing
+  _wiIdFromNoteFrontmatter, // exported for testing
+  _buildNotesByWiMap, // exported for testing
 
   // Agents
   getAgentStatus, getAgentCharter, getAgents, getAgentDetail,

package/engine/scheduler.js

@@ -328,6 +328,12 @@ function createScheduledWorkItem(sched) {
     ...(sched.agentLock === true || sched.hardAgent === true ? { agentLock: true } : {}),
     project: sched.project || null,
     _scheduleId: sched.id,
+    // P-c549d07e — back-link to the schedule that spawned this WI. The WI
+    // detail modal renders this as a clickable chip via renderArtifactLink
+    // so the operator can navigate back to the dispatcher. Kept alongside
+    // _scheduleId (used by queries / lifecycle / consolidation) so we don't
+    // disturb the existing readers — meta.spawnedBy is purely additive.
+    meta: { spawnedBy: 'schedule:' + sched.id },
   };
   // Walk every string-valued field on the work item so vars embedded in
   // nested fields (e.g. _harness.rubric added by callers, references[].url,
@@ -339,7 +345,19 @@ function createScheduledWorkItem(sched) {
 
 function writeScheduleRunEntry(runs, scheduleId, workItemId, extra) {
   const existing = typeof runs[scheduleId] === 'object' && runs[scheduleId] ? runs[scheduleId] : {};
-  runs[scheduleId] = { ...existing, lastRun: ts(), lastWorkItemId: workItemId, ...(extra || {}) };
+  // P-c549d07e — maintain a recentWorkItemIds ring (newest first, hard cap 5,
+  // deduplicated). Surfaces "Recent dispatches" chips in the schedule modal
+  // without forcing the dashboard to scan every WI for _scheduleId matches.
+  // Empty / falsy workItemId leaves the ring untouched (defensive — callers
+  // always pass a real id today, but the engine should never pollute the
+  // history with blanks if a future caller slips up).
+  let recent = Array.isArray(existing.recentWorkItemIds) ? existing.recentWorkItemIds.slice() : [];
+  if (workItemId) {
+    recent = recent.filter((id) => id !== workItemId);
+    recent.unshift(workItemId);
+    if (recent.length > 5) recent = recent.slice(0, 5);
+  }
+  runs[scheduleId] = { ...existing, lastRun: ts(), lastWorkItemId: workItemId, recentWorkItemIds: recent, ...(extra || {}) };
   return runs[scheduleId];
 }
 

package/engine/shared.js

@@ -6348,6 +6348,15 @@ function applyPrFieldDelta(target, before, after) {
 function normalizePrRecord(pr, project = null) {
   if (!pr || typeof pr !== 'object') return false;
   let changed = false;
+  const hasCanonicalContextOnly = Object.prototype.hasOwnProperty.call(pr, 'contextOnly');
+  if (hasCanonicalContextOnly) {
+    for (const legacyKey of ['_contextOnly', '_autoObserve', '_manual']) {
+      if (Object.prototype.hasOwnProperty.call(pr, legacyKey)) {
+        delete pr[legacyKey];
+        changed = true;
+      }
+    }
+  }
   const prNumber = getPrNumber(pr.prNumber ?? pr.id ?? pr.url);
   if (prNumber != null && pr.prNumber !== prNumber) {
     pr.prNumber = prNumber;
@@ -6386,17 +6395,19 @@ function normalizePrLinkItems(value) {
   return [...new Set(items.filter(item => typeof item === 'string' && item))];
 }
 
-// W-mq5s5ttx000j7ab8-a — canonical `contextOnly` gate. The 6-clause legacy
-// body (prdItems / _autoObserve / sourcePlan / itemType / agent-heuristic) is
-// replaced by a single read of the canonical field. The one-shot boot
-// migration (migratePrGateFlags) projects the legacy signals onto
-// `contextOnly` so every on-disk record has the canonical value before any
-// tick fires. Anything new written via upsertPullRequestRecord (and the
-// dashboard link/observe paths consolidated in PR #3137 / `-c`) also lands
-// on `contextOnly` directly. See W-mq5rs2eq000da8a9 for the bug repro that
-// motivated consolidating onto a single helper.
+// W-mq5s5ttx000j7ab8-a / W-mqerisvz000n3901 — canonical `contextOnly` gate
+// with a legacy bridge. Canonical `contextOnly` wins whenever it exists; legacy
+// `_contextOnly` is only a fallback for pre-migration/raw records. This keeps
+// observe toggles (`contextOnly:false`) from being overridden by stale legacy
+// contamination while still treating old context-only rows as reference-only.
+function isContextOnlyPrRecord(pr) {
+  if (!pr || typeof pr !== 'object') return false;
+  if (typeof pr.contextOnly === 'boolean') return pr.contextOnly;
+  return pr._contextOnly === true;
+}
+
 function isAutoManagedPrRecord(pr) {
-  return !!pr && typeof pr === 'object' && pr.contextOnly !== true;
+  return !!pr && typeof pr === 'object' && !isContextOnlyPrRecord(pr);
 }
 
 function mergePrLinkItems(links, prId, itemIds) {
@@ -6548,6 +6559,13 @@ function upsertPullRequestRecord(prPath, entry, { project = null, itemId = null,
     prNumber: prNumber ?? entry.prNumber ?? null,
     prdItems: linkedItemIds,
   };
+  const normalizedEntryContextOnly = normalizedEntry.contextOnly != null
+    ? normalizedEntry.contextOnly
+    : normalizedEntry._contextOnly;
+  if (normalizedEntryContextOnly != null) {
+    normalizedEntry.contextOnly = normalizedEntryContextOnly === true;
+    delete normalizedEntry._contextOnly;
+  }
 
   let created = false;
   let linked = false;
@@ -6568,7 +6586,8 @@ function upsertPullRequestRecord(prPath, entry, { project = null, itemId = null,
     } else {
       target.id = canonicalId;
       if (prNumber != null) target.prNumber = prNumber;
-      const targetWasAutoManaged = isAutoManagedPrRecord(target);
+      const targetWasAutoManaged = isAutoManagedPrRecord(target)
+        || (target.contextOnly == null && target._contextOnly === true && _prRecordIsLegacyManaged(target));
       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];
@@ -6591,7 +6610,10 @@ function upsertPullRequestRecord(prPath, entry, { project = null, itemId = null,
         : normalizedEntry._contextOnly;
       if (incomingContextOnly != null) {
         const wouldDemoteManagedPr = incomingContextOnly === true && targetWasAutoManaged;
-        if (!wouldDemoteManagedPr) target.contextOnly = incomingContextOnly === true;
+        target.contextOnly = wouldDemoteManagedPr ? false : incomingContextOnly === true;
+        delete target._contextOnly;
+        delete target._autoObserve;
+        delete target._manual;
       }
     }
     target.prdItems = normalizePrLinkItems(target.prdItems || []);
@@ -8298,7 +8320,7 @@ module.exports = {
   normalizePrRecords,
   normalizePrLinkItems, // exported for testing
   mergePrLinkItems, // exported for testing
-  isAutoManagedPrRecord,
+  isContextOnlyPrRecord,
   upsertPullRequestRecord,
   isAutoManagedPrRecord, // W-mq5s5ttx000j7ab8-a — exported for engine + watch-plugin gate consolidation
   migratePrGateFlags, // W-mq5s5ttx000j7ab8-a — boot migration wired from engine/cli.js

package/engine.js

@@ -6043,7 +6043,7 @@ async function discoverFromPrs(config, project) {
 
   for (const pr of prs) {
     if (pr.status !== PR_STATUS.ACTIVE) continue;
-    if (pr._contextOnly) {
+    if (shared.isContextOnlyPrRecord(pr)) {
       _logPrDispatchSkipOnce(pr, 'context-only');
       continue;
     }
@@ -6057,11 +6057,9 @@ async function discoverFromPrs(config, project) {
       log('info', `Branch mutex: skipping PR ${pr.id} dispatch — branch ${prBranchForMutex} locked by another agent`);
       continue;
     }
-    // Auto-managed gate: single source of truth in engine/shared.js.
-    // Honors prdItems, _autoObserve, sourcePlan/itemType, and any non-empty
-    // non-'human' agent author. See W-mq5rs2eq000da8a9 for the bug fix —
-    // the prior inline `knownAgents.has(...) || prdItems || (_manual && !_contextOnly)`
-    // silently dropped PRs with `_autoObserve: true` + human author.
+    // Auto-managed gate: single source of truth in engine/shared.js. Canonical
+    // `contextOnly` wins over stale legacy flags; legacy `_contextOnly` is only
+    // a fallback for raw pre-migration records.
     if (!shared.isAutoManagedPrRecord(pr)) {
       _logPrDispatchSkipOnce(pr, 'not-auto-managed');
       continue;

package/package.json

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