@yemi33/minions 0.1.2223 → 0.1.2225

package/dashboard.js

@@ -512,7 +512,64 @@ function inferActionPrRecord(action, prs, project = null) {
   return findPrRecordReferencedByText(prs, text, project);
 }
 
-function copyWorkItemPrFields(item, input, pr = null) {
+// issue #246 — verify a LOOSE (description/title-scanned) PR ref points at a
+// real pull request before `copyWorkItemPrFields` promotes it to structured
+// targetPr/pr_id/prNumber fields. GitHub & ADO issues share the PR number
+// namespace, so a bare `owner/repo#244` / `#244` can be an ISSUE. Stamping an
+// issue mints a phantom pull-requests.json record (agent 'human', goes
+// abandoned) AND routes the dispatch through the PR-fix path instead of
+// implement-and-open-a-fresh-PR.
+//
+// Resolution order (cheap → expensive, fail-safe):
+//   1. An already-tracked PR record for the ref ⇒ it's a known PR ⇒ true (no net).
+//   2. Host existence check (gh/ado prExists) ⇒ true | false | null.
+// Returns true only when a PR is positively confirmed; false / null / unknown
+// all mean "do not stamp" (prefer a fresh PR over a phantom one).
+const _PR_REF_VERIFY_TTL_MS = 5 * 60 * 1000;
+const _prRefVerifyCache = new Map(); // cacheKey → { value: boolean, at: ms }
+let _prRefVerifierOverride = null;   // test seam
+
+// Test seam (issue #246) — inject a fake verifier so handler tests can assert
+// the stamp decision without a live gh/ado call. The override receives
+// (prRef, project) and returns true | false | null.
+function _setPrRefVerifierForTest(fn) { _prRefVerifierOverride = (typeof fn === 'function') ? fn : null; }
+
+function _findTrackedPrRecord(prRef, project) {
+  if (!project) return null;
+  try {
+    const prs = shared.safeJsonArr(shared.projectPrPath(project));
+    return shared.findPrRecord(prs, prRef, project);
+  } catch { return null; }
+}
+
+async function verifyLoosePrRefIsPr(prRef, project) {
+  if (_prRefVerifierOverride) {
+    try { return (await _prRefVerifierOverride(prRef, project)) === true; }
+    catch { return false; }
+  }
+  // 1. Known PR record ⇒ definitely a PR (no network call needed).
+  if (_findTrackedPrRecord(prRef, project)) return true;
+  // 2. Host existence check.
+  const info = shared.classifyPrRefForVerification(prRef, project);
+  if (!info) return false; // can't resolve host/number → fail-safe, do not stamp
+  const cacheKey = info.host === 'github'
+    ? `github:${info.slug}#${info.prNumber}`
+    : `ado:${info.adoOrg}/${info.adoProject}/${info.adoRepo}#${info.prNumber}`;
+  const cached = _prRefVerifyCache.get(cacheKey);
+  if (cached && (Date.now() - cached.at) < _PR_REF_VERIFY_TTL_MS) return cached.value;
+  let verdict = null;
+  try {
+    verdict = info.host === 'github'
+      ? await gh.prExists(info.slug, info.prNumber)
+      : await ado.prExists(info.adoOrg, info.adoProject, info.adoRepo, info.prNumber);
+  } catch { verdict = null; }
+  const value = verdict === true;
+  // Only cache a definitive answer; an unknown (null) may resolve next time.
+  if (verdict === true || verdict === false) _prRefVerifyCache.set(cacheKey, { value, at: Date.now() });
+  return value;
+}
+
+async function copyWorkItemPrFields(item, input, pr = null, opts = {}) {
   // W-mqbaby2a000pa8ee: Gate the LOOSE description/title scan in
   // `shared.extractWorkItemPrRef` on `type: "fix"`. Without this gate,
   // an implement/explore/test WI that merely mentions an existing PR
@@ -526,13 +583,30 @@ function copyWorkItemPrFields(item, input, pr = null) {
   // operator intent — they stamp on EVERY type. An explicit `pr` record
   // (caller already resolved the PR) also bypasses the gate. Only the
   // last-resort description/title regex scan is type-gated.
-  if (!pr) {
+  //
+  // issue #246: a loose `github:owner/repo#NNN` / `#NNN` token can be an
+  // ISSUE — issues and PRs share one number namespace. Before stamping a
+  // loose ref we verify it points at a real PR (already-tracked record or a
+  // gh/ado existence check); structured refs are trusted without a network
+  // call. Fail-safe: if existence can't be confirmed, do NOT stamp — the WI
+  // then dispatches as a normal fix that opens a fresh PR.
+  let prRef;
+  if (pr) {
+    prRef = getWorkItemPrRef(input);
+  } else {
     const structuredRef = shared.extractStructuredWorkItemPrRef(input);
-    if (!structuredRef && String(item?.type || '').toLowerCase() !== WORK_TYPE.FIX) {
-      return;
+    if (structuredRef) {
+      prRef = structuredRef; // explicit operator intent — trusted, no verification
+    } else {
+      if (String(item?.type || '').toLowerCase() !== WORK_TYPE.FIX) return;
+      const looseRef = getWorkItemPrRef(input);
+      if (!looseRef) return;
+      // issue #246 — confirm the loose ref is a PR (not an issue) before stamping.
+      const confirmed = await verifyLoosePrRefIsPr(looseRef, opts.project || null);
+      if (!confirmed) return; // issue / unverifiable → dispatch as a fresh fix
+      prRef = looseRef;
     }
   }
-  const prRef = getWorkItemPrRef(input);
   if (!prRef && !pr) return;
   const prNumber = pr ? shared.getPrNumber(pr) : shared.getPrNumber(prRef);
   item.targetPr = pr?.id || prRef;
@@ -6361,7 +6435,7 @@ const server = http.createServer(async (req, res) => {
       const originWi = extractMinionsOriginWiHeader(req);
       if (originAgent) item._originAgent = originAgent;
       if (originWi) item._originWi = originWi;
-      copyWorkItemPrFields(item, body);
+      await copyWorkItemPrFields(item, body, null, { project: targetProject });
       // W-mq5wfh1v000e0da9 — Auto-enroll the PR into pull-requests.json when
       // this is a `type: fix` WI carrying a structured PR pointer and the PR
       // isn't tracked yet. Without this, the engine's `pr_not_found` gate
@@ -13857,6 +13931,7 @@ function _installCrashHandlers() {
 // Production entry points use the closures directly; tests import via require('./dashboard').
 module.exports = {
   getMcpServers,
+  _setPrRefVerifierForTest, // issue #246 — inject a fake loose-PR-ref verifier in handler tests
   _parseClaudeMcpListLine,
   _parseCopilotMcpListJson,
   _readWorkspaceMcpServers,

package/docs/branch-derivation.md

@@ -56,6 +56,40 @@ PR-fix dispatch path, fail the PR-branch lookup, and stick in
 (`targetPr` / `prUrl` / `references[].url` / etc.) still stamps on
 every type — only the loose regex scan is gated.
 
+## Loose refs are PR-verified before stamping (issue #246)
+
+A loose `github:owner/repo#NNN` / `ado:org/proj/repo#NNN` / bare `#NNN` token
+carries **no issue-vs-PR discriminator** — GitHub issues and PRs share one
+number namespace, and ADO work items share theirs. Before this guard, a
+`type: "fix"` WI titled `Fix github:owner/repo#244: …` where **#244 is an
+issue** got `targetPr` / `pr_id` / `prNumber` stamped by
+`dashboard.js#copyWorkItemPrFields`, which then (a) minted a phantom
+`pull-requests.json` record (`agent: 'human'`, went abandoned, polluted the PR
+count) via `shared.autoEnrollPrFromFixWorkItem`, and (b) routed the dispatch
+through the PR-fix path (`targetPr`/`pr_id`/`prNumber`) instead of
+implement-and-open-a-fresh-PR.
+
+`copyWorkItemPrFields` now verifies a **loose** ref points at a real PR before
+stamping:
+
+1. **Structured refs are trusted** — `targetPr` / `prUrl` / `references[].url`
+   / `meta.pr_followup.parent_pr_url` are explicit operator intent and stamp
+   with **no** network call.
+2. **Loose (description/title-scanned) refs on a fix WI** are confirmed via:
+   - an already-tracked `pull-requests.json` record for the ref (cheap, no
+     network), else
+   - a host existence check — `engine/github.js#prExists` (`gh api
+     repos/:owner/:repo/pulls/NNN`; 404 ⇒ issue) or `engine/ado.js#prExists`
+     (`…/pullrequests/NNN`), routed via `engine/gh-token.js` per-account token.
+   `shared.classifyPrRefForVerification(prRef, project)` does the pure host/slug
+   /number routing; the result is TTL-cached.
+3. **Fail-safe:** when existence can't be confirmed (issue, 404, network/auth
+   error, unresolvable host) the ref is **not** stamped — the WI dispatches as a
+   normal fix that opens a NEW PR. Prefer a fresh PR over a phantom one.
+
+The `type: "fix"` gate from W-mqbaby2a000pa8ee still applies first: non-fix WIs
+are never stamped from loose prose.
+
 ## Structured-vs-loose split (W-mq18ec6h000p7b87)
 
 The PR-ref extractor has **two** variants — pick the right one for the

package/docs/deprecated.json

@@ -119,8 +119,8 @@
       { "file": "engine.js", "note": "discoverFromPrs reads canonical `pr.contextOnly` only." }
     ],
     "deprecated": "2026-06-08",
-    "targetRemovalDate": "2026-06-16",
-    "notes": "The write side already shipped out — there is no dual-write to retire. What remains is the read-fallback (`_contextOnly === true`) plus the one-shot boot migration migratePrGateFlags (engine/shared.js:6833) that copies + deletes the alias from any pre-migration on-disk record. Pair this entry's removal with `pr-record-autoObserve-underscore-alias`, `pr-record-manual-underscore-alias`, and `pr-link-autoObserve-body-param` — they share the same boot migration. Removal scope (DEFERRED — gated on a positive signal that every live pull-requests.json has been swept of underscore keys, not on the expired calendar date): delete the `_contextOnly` read-fallback in engine/shared.js and the migratePrGateFlags handling of it."
+    "targetRemovalDate": "2026-06-25",
+    "notes": "The write side already shipped out — there is no dual-write to retire. What remains is the read-fallback (`_contextOnly === true`) plus the one-shot boot migration migratePrGateFlags (engine/shared.js:6833) that copies + deletes the alias from any pre-migration on-disk record. Pair this entry's removal with `pr-record-autoObserve-underscore-alias`, `pr-record-manual-underscore-alias`, and `pr-link-autoObserve-body-param` — they share the same boot migration. Removal scope (DEFERRED — gated on a positive signal that every live pull-requests.json has been swept of underscore keys, not on the expired calendar date): delete the `_contextOnly` read-fallback in engine/shared.js and the migratePrGateFlags handling of it. On-disk sweep confirmed CLEAN on 2026-06-18: grep of every live projects/*/pull-requests.json (budget-test-project, constellation, minions-opg, office-bohemia) for the `_contextOnly`/`_autoObserve`/`_manual` record keys returned zero matches, so the deferral gate is now cleared and a deliberate, human-reviewed code removal can be scheduled (this calendar bump 2026-06-16 → 2026-06-25 is the docs-only consistency half; the MEDIUM/>3-file code removal stays a separate PR)."
   },
   {
     "id": "pr-record-autoObserve-underscore-alias",
@@ -130,8 +130,8 @@
       { "file": "dashboard.js", "note": "Zero `_autoObserve` references — link/observe handlers accept the canonical `contextOnly` body param and write no underscore alias onto the record." }
     ],
     "deprecated": "2026-06-08",
-    "targetRemovalDate": "2026-06-16",
-    "notes": "The write side already shipped out — there is no dual-write to retire. Removal is paired with `pr-record-contextOnly-underscore-alias` — same boot migration, same read-bridge. Removal scope (DEFERRED — gated on a sweep confirming no live record retains `_autoObserve`, not on the expired calendar date): delete the `_autoObserve === true` read in _prRecordIsLegacyManaged (engine/shared.js:6823) and the migratePrGateFlags handling of it."
+    "targetRemovalDate": "2026-06-25",
+    "notes": "The write side already shipped out — there is no dual-write to retire. Removal is paired with `pr-record-contextOnly-underscore-alias` — same boot migration, same read-bridge. Removal scope (DEFERRED — gated on a sweep confirming no live record retains `_autoObserve`, not on the expired calendar date): delete the `_autoObserve === true` read in _prRecordIsLegacyManaged (engine/shared.js:6823) and the migratePrGateFlags handling of it. On-disk sweep confirmed CLEAN on 2026-06-18: grep of every live projects/*/pull-requests.json (budget-test-project, constellation, minions-opg, office-bohemia) for the `_contextOnly`/`_autoObserve`/`_manual` record keys returned zero matches, so the deferral gate is now cleared and a deliberate, human-reviewed code removal can be scheduled (this calendar bump 2026-06-16 → 2026-06-25 is the docs-only consistency half; the MEDIUM/>3-file code removal stays a separate PR)."
   },
   {
     "id": "pr-record-manual-underscore-alias",
@@ -142,8 +142,8 @@
       { "file": "dashboard.js", "note": "Zero `_manual` references — the link handler no longer writes the provenance alias onto the record." }
     ],
     "deprecated": "2026-06-08",
-    "targetRemovalDate": "2026-06-16",
-    "notes": "Disambiguation: this entry covers ONLY the PR-record `_manual` flag (engine/<scope>/pull-requests.json). Other `_manual`-named flags elsewhere in the engine (work items, dispatch records, etc.) are NOT covered by this entry and remain in active use. The write side already shipped out — there is no write site or dashboard badge left to remove. Removal scope (DEFERRED — gated on a sweep confirming no live record retains `_manual`, not on the expired calendar date): drop the `_manual` handling in normalizePrRecord and migratePrGateFlags (engine/shared.js) once the on-disk sweep is confirmed."
+    "targetRemovalDate": "2026-06-25",
+    "notes": "Disambiguation: this entry covers ONLY the PR-record `_manual` flag (engine/<scope>/pull-requests.json). Other `_manual`-named flags elsewhere in the engine (work items, dispatch records, etc.) are NOT covered by this entry and remain in active use. The write side already shipped out — there is no write site or dashboard badge left to remove. Removal scope (DEFERRED — gated on a sweep confirming no live record retains `_manual`, not on the expired calendar date): drop the `_manual` handling in normalizePrRecord and migratePrGateFlags (engine/shared.js) once the on-disk sweep is confirmed. On-disk sweep confirmed CLEAN on 2026-06-18: grep of every live projects/*/pull-requests.json (budget-test-project, constellation, minions-opg, office-bohemia) for the `_contextOnly`/`_autoObserve`/`_manual` record keys returned zero matches, so the deferral gate is now cleared and a deliberate, human-reviewed code removal can be scheduled (this calendar bump 2026-06-16 → 2026-06-25 is the docs-only consistency half; the MEDIUM/>3-file code removal stays a separate PR)."
   },
   {
     "id": "pr-link-autoObserve-body-param",
@@ -152,8 +152,8 @@
       { "file": "dashboard.js", "note": "linkPullRequestForTracking resolves `contextOnly` from `body.contextOnly` when boolean, else `autoObserve === undefined ? false : !autoObserve` (dashboard.js:1055-1057). Route registry params string still lists `autoObserve?` (dashboard.js:12680)." }
     ],
     "deprecated": "2026-06-08",
-    "targetRemovalDate": "2026-06-16",
-    "notes": "Unlike the three record-field aliases, nothing is written here — this is purely an input read-fallback. Removal scope (DEFERRED — gated on confirming no client still POSTs `autoObserve`, not on the expired calendar date): drop the `!body.autoObserve` fallback in the link handler in dashboard.js, drop `autoObserve?` from the route registry `params` string, and update any client (dashboard JS, ops scripts) that still POSTs `autoObserve`. After removal, callers that still send `autoObserve` will see their value silently ignored."
+    "targetRemovalDate": "2026-06-25",
+    "notes": "Unlike the three record-field aliases, nothing is written here — this is purely an input read-fallback. Removal scope (DEFERRED — gated on confirming no client still POSTs `autoObserve`, not on the expired calendar date): drop the `!body.autoObserve` fallback in the link handler in dashboard.js, drop `autoObserve?` from the route registry `params` string, and update any client (dashboard JS, ops scripts) that still POSTs `autoObserve`. After removal, callers that still send `autoObserve` will see their value silently ignored. On-disk sweep confirmed CLEAN on 2026-06-18: grep of every live projects/*/pull-requests.json (budget-test-project, constellation, minions-opg, office-bohemia) for the `_contextOnly`/`_autoObserve`/`_manual` record keys returned zero matches, so the deferral gate is now cleared and a deliberate, human-reviewed removal can be scheduled (this calendar bump 2026-06-16 → 2026-06-25 is the docs-only consistency half; the actual code removal stays a separate human-reviewed PR)."
   },
   {
     "id": "worktreemode-field-rename",

package/engine/ado.js

@@ -2511,6 +2511,25 @@ async function fetchAdoPrMetadata(prNum, adoOrg, adoProj, adoRepo) {
   };
 }
 
+/**
+ * issue #246 — confirm a number points at a real ADO PULL REQUEST. ADO work
+ * items (issues) live in a different namespace, so a non-PR number 404s on the
+ * pullrequests endpoint. `adoFetch` can't distinguish 404 from auth/network
+ * failure, so a missing/erroring PR returns null (not false) — and the caller
+ * treats both false and null as "do not stamp" (fail-safe). Returns true only
+ * on a positively-fetched PR.
+ */
+async function prExists(adoOrg, adoProject, adoRepo, prNumber) {
+  const n = parseInt(prNumber, 10);
+  if (!adoOrg || !adoProject || !adoRepo || !Number.isInteger(n) || n <= 0) return null;
+  try {
+    const meta = await fetchAdoPrMetadata(n, adoOrg, adoProject, adoRepo);
+    return meta ? true : null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Fetch live PR and build status for a single PR number.
  * Used by engine/ado-status.js so agents can check CI without raw curl calls.
@@ -2918,6 +2937,7 @@ module.exports = {
   getAdoThrottleState,
   getAdoThrottleStateAll,
   fetchAdoPrMetadata,
+  prExists, // issue #246 — confirm a loose ref points at a PR (not a work item) before stamping
   fetchSinglePrBuildStatus,
   findOpenPrOnBranch,
   applyAdoPrMetadata, // #3079 — exported for unit tests of targetRefName + retarget reset

package/engine/github.js

@@ -400,6 +400,23 @@ async function ghApi(endpoint, slug, opts = {}) {
   }
 }
 
+/**
+ * issue #246 — confirm a number points at a real PULL REQUEST (GitHub issues
+ * and PRs share one number namespace, so `owner/repo#244` may be an issue).
+ * Hits GET /repos/{slug}/pulls/{n}, which 404s for issue numbers. Returns:
+ *   true  — the PR exists
+ *   false — 404 (the number is an issue or doesn't exist)
+ *   null  — could not determine (network / auth / throttle) → caller fail-safe
+ */
+async function prExists(slug, prNumber, opts = {}) {
+  const n = parseInt(prNumber, 10);
+  if (!slug || !Number.isInteger(n) || n <= 0) return null;
+  const result = await ghApi(`/pulls/${n}`, slug, opts);
+  if (result === GH_NOT_FOUND) return false;
+  if (result && typeof result === 'object' && result._notFound !== true) return true;
+  return null;
+}
+
 const BUILD_ERROR_LOG_MAX_LINES = 150;
 
 /**
@@ -1885,6 +1902,7 @@ module.exports = {
   isGhThrottled,
   getGhThrottleState,
   ghApi, // P-8c1b6e45 — used by engine/shared-branch-pr-reconcile.js to list open PRs on a feature branch
+  prExists, // issue #246 — confirm a loose ref points at a PR (not an issue) before stamping
   // Exported for testing
   isGitHub,
   getRepoSlug,

package/engine/shared.js

@@ -6163,15 +6163,11 @@ function parsePrUrl(url) {
 // `isPrTargeted` paths intact and prevents PR-feedback fix WIs from being
 // dispatched on a fresh `work/<wi-id>` branch when only the description /
 // references[] carried the PR pointer (issue #2999).
-function _trimTrailingPrRefPunctuation(value) {
-  return String(value || '').replace(/[),.;:]+$/g, '');
-}
-
 function extractPrRefFromText(value) {
   const text = String(value || '');
   if (!text.trim()) return null;
   const urlMatch = text.match(/https?:\/\/[^\s<>()]+(?:\/pull\/\d+|\/pullrequest\/\d+)[^\s<>()]*/i);
-  if (urlMatch) return _trimTrailingPrRefPunctuation(urlMatch[0]);
+  if (urlMatch) return String(urlMatch[0] || '').replace(/[),.;:]+$/g, '');
   const canonicalMatch = text.match(/\b(?:github|ado):[^\s#]+#\d+\b/i);
   if (canonicalMatch) return canonicalMatch[0];
   const legacyMatch = text.match(/\bPR-(\d+)\b/i);
@@ -7053,6 +7049,38 @@ function deriveUrlForPrRef(prRef, project) {
   return null;
 }
 
+// issue #246 — classify a PR ref into the host + identifiers needed to verify
+// it actually points at a PULL REQUEST (not an ISSUE, which shares the number
+// namespace on GitHub and is a distinct endpoint on ADO). Pure: no network.
+//
+// Resolution: prefer the scope embedded in the ref (canonical `github:…#N` /
+// `ado:…#N` id, or a PR URL); fall back to the project's own scope for a bare
+// `#N` / `PR-N` / number ref. Returns null when the ref can't be resolved to a
+// concrete host + number — the caller treats null as "cannot verify" and, per
+// the fail-safe contract, declines to stamp.
+//
+// Returns one of:
+//   { host: 'github', slug: 'owner/repo', prNumber }
+//   { host: 'ado', adoOrg, adoProject, adoRepo, prNumber }
+//   null
+function classifyPrRefForVerification(prRef, project = null) {
+  const scoped = getPrScopeInfo(prRef);
+  let scope = scoped?.scope || '';
+  const prNumber = scoped?.prNumber ?? getPrNumber(prRef);
+  if (!scope && project) scope = getProjectPrScope(project);
+  if (!scope || prNumber == null) return null;
+  if (scope.startsWith('github:')) {
+    const slug = scope.slice('github:'.length);
+    return slug.includes('/') ? { host: 'github', slug, prNumber } : null;
+  }
+  if (scope.startsWith('ado:')) {
+    const parts = scope.slice('ado:'.length).split('/');
+    if (parts.length < 3 || !parts[0] || !parts[1] || !parts[2]) return null;
+    return { host: 'ado', adoOrg: parts[0], adoProject: parts[1], adoRepo: parts[2], prNumber };
+  }
+  return null;
+}
+
 // W-mq5wfh1v000e0da9 — Auto-enroll a PR into pull-requests.json when a
 // `type: fix` work item is created with a structured PR pointer. Without
 // this, fix WIs against untracked PRs bypass the polling / review / build
@@ -8775,6 +8803,7 @@ module.exports = {
   migratePrGateFlags, // W-mq5s5ttx000j7ab8-a — boot migration wired from engine/cli.js
   autoEnrollPrFromFixWorkItem,
   deriveUrlForPrRef, // exported for testing
+  classifyPrRefForVerification, // issue #246 — host routing for loose PR-ref verification
   nextWorkItemId,
   getProjectOrg,
   getAdoOrgBase,

package/package.json

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