@yemi33/minions 0.1.2222 → 0.1.2224

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/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/pr-action.js

@@ -155,7 +155,7 @@ function buildCreatePrFollowups({ project, branch, contextOnly = false } = {}) {
   if (!proj) return [];
   const br = branch && String(branch).trim() ? String(branch).trim() : '';
   const branchClause = br
-    ? `on the current branch ${br}`
+    ? `(the working tree is on branch ${br}; if ${br} is the project's default/main branch, create a new well-named branch off it and commit there rather than committing to ${br} directly)`
     : 'on a new well-named branch off the project main branch';
   const linkBody = contextOnly
     ? `{"url":"<new PR url>","project":"${proj}","contextOnly":true}`
@@ -163,11 +163,18 @@ function buildCreatePrFollowups({ project, branch, contextOnly = false } = {}) {
   const trackNote = contextOnly
     ? 'so it is tracked but not auto-reviewed'
     : 'so the engine auto-manages it (review -> fix -> re-review -> auto-merge)';
+  // The original branch CC must return to once the PR is open, so the new PR
+  // branch is never left checked out in the shared operator working tree.
+  const restoreClause = br
+    ? `switch the working tree back to the ORIGINAL branch (${br})`
+    : 'switch the working tree back to the original branch it started on';
   const message =
     `Create a PR from the local changes you just made in the ${proj} project. ` +
-    `Steps: (1) in that project's working tree, stage and commit the modified files ${branchClause} with a clear conventional-commit message; ` +
+    (br ? `Remember the working tree's current branch (${br}) as the ORIGINAL branch to return to when done. ` : '') +
+    `Steps: (1) in that project's working tree, stage and commit the modified files with a clear conventional-commit message ${branchClause}; ` +
     `(2) push the branch; (3) open a PR against the project's main branch using the right CLI for the repo host (gh for GitHub, az repos for ADO); ` +
-    `(4) link it to the tracker by calling POST /api/pull-requests/link with ${linkBody} ${trackNote}. ` +
+    `(4) link it to the tracker by calling POST /api/pull-requests/link with ${linkBody} ${trackNote}; ` +
+    `(5) finally, ${restoreClause} — do not leave the new PR branch checked out. ` +
     `Then show me the PR URL.`;
   return [{ kind: CREATE_PR_FOLLOWUP.kind, label: CREATE_PR_FOLLOWUP.label, project: proj, branch: br || null, message }];
 }

package/engine/shared.js

@@ -7053,6 +7053,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 +8807,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.2222",
+  "version": "0.1.2224",
   "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"

package/prompts/cc-system.md

@@ -96,7 +96,7 @@ curl -s -X POST http://localhost:{{dashboard_port}}/api/pr-action/offer-create-p
   -H 'Content-Type: application/json' -H 'X-CC-Turn-Id: {{cc_turn_id}}' \
   -d '{"project":"<project name>"}'
 ```
-This checks the project's working tree (`git status --porcelain`) and, when there are uncommitted changes, returns a **`[Create PR]`** follow-up chip to the user (same chip mechanism as the `pr-action` `[Comment]`/`[Fix once]`/`[Track for auto-fix]` chips). When the user clicks it, you'll receive a turn instructing you to commit → push → open the PR → link it to the tracker. Pass `"contextOnly":true` if the PR should be tracked-but-not-auto-reviewed; omit it to have the engine auto-manage the PR (review → fix → re-review → auto-merge). If `hasChanges` is `false`, there's nothing to PR — skip the offer. Don't commit/push on your own initiative; surface the chip and let the user decide.
+This checks the project's working tree (`git status --porcelain`) and, when there are uncommitted changes, returns a **`[Create PR]`** follow-up chip to the user (same chip mechanism as the `pr-action` `[Comment]`/`[Fix once]`/`[Track for auto-fix]` chips). When the user clicks it, you'll receive a turn instructing you to commit → push → open the PR → link it to the tracker → switch the working tree back to the original branch (never leave the new PR branch checked out in the shared operator tree). Pass `"contextOnly":true` if the PR should be tracked-but-not-auto-reviewed; omit it to have the engine auto-manage the PR (review → fix → re-review → auto-merge). If `hasChanges` is `false`, there's nothing to PR — skip the offer. Don't commit/push on your own initiative; surface the chip and let the user decide.
 
 ## When to dispatch vs answer inline