@yemi33/minions 0.1.948 → 0.1.950

package/CHANGELOG.md

@@ -1,8 +1,9 @@
 # Changelog
 
-## 0.1.948 (2026-04-14)
+## 0.1.950 (2026-04-14)
 
 ### Features
+- add PR/build status CLI shim and agent guidance
 -  make ADO poll frequency configurable and ungate reconcilePrs
 - update render-work-items.js output viewer to use renderAgentOutput
 - update detail-panel.js Output Log tab to use renderAgentOutput
@@ -22,7 +23,6 @@
 - fix stall recovery nested lock violation (#965)
 - fix pending-rebases.json race condition with file locking (#964)
 - add missing resolveWorkItemPath import in engine.js (#963)
-- bump plan-to-prd max turns from 20 to 35
 
 ### Fixes
 - tighten build query guard to require mergeCommitId
@@ -47,6 +47,7 @@
 - prioritize error_max_turns over permission-blocked in classifyFailure (#1001)
 
 ### Other
+- refactor(ado): simplify ado-status and extract build/review status helpers
 - refactor(ado): extract stripRefsHeads helper, deduplicate refs/heads/ stripping
 - refactor(ado): simplify comments, fix declaration order, promote ado import
 - refactor(ado): move PR enrichment fetch into fetchAdoPrMetadata helper

package/engine/ado-status.js

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+/**
+ * engine/ado-status.js — CLI shim for querying PR and build status.
+ *
+ * Agents steered to "check on the builds" or "is CI green for PR #123" should
+ * use this instead of raw curl + azureauth calls. All ADO auth and retry logic
+ * is handled by ado.js internally.
+ *
+ * Usage:
+ *   node engine/ado-status.js <prNumber>
+ *   node engine/ado-status.js <prNumber> --live
+ *   node engine/ado-status.js <prNumber> --project MyProject
+ *   node engine/ado-status.js <prNumber> --live --project MyProject
+ *
+ * Output: JSON to stdout. Exit 0 on success, 1 on error/not-found.
+ *
+ * Cached (default): reads pull-requests.json maintained by the engine (~3 min stale).
+ * Live (--live):    makes fresh ADO API calls — use when engine isn't running or you
+ *                   just pushed and need up-to-the-moment build status.
+ */
+
+'use strict';
+
+const path = require('path');
+const shared = require('./shared');
+const { safeJson, safeJsonArr, projectPrPath, getProjects } = shared;
+
+// ── Arg parsing ──────────────────────────────────────────────────────────────
+
+const args = process.argv.slice(2);
+const prNumberArg = args.find(a => /^\d+$/.test(a));
+const live = args.includes('--live');
+const projectIdx = args.indexOf('--project');
+const projectName = projectIdx >= 0 ? args[projectIdx + 1] : null;
+
+if (!prNumberArg) {
+  console.error([
+    'Usage: node engine/ado-status.js <prNumber> [--live] [--project <name>]',
+    '',
+    '  <prNumber>          PR number to look up (required)',
+    '  --live              Make a fresh ADO API call instead of reading cached state',
+    '  --project <name>    Scope search to one project (optional)',
+    '',
+    'Output: JSON with fields: prNumber, title, branch, status, reviewStatus,',
+    '        buildStatus, buildErrorLog (if failing), mergeConflict, url, project, source',
+    '',
+    'buildStatus values: passing | failing | running | none',
+    'reviewStatus values: approved | changes-requested | waiting | pending',
+  ].join('\n'));
+  process.exit(1);
+}
+
+const prNumber = parseInt(prNumberArg, 10);
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function findInCache(projects) {
+  for (const project of projects) {
+    const prs = safeJsonArr(projectPrPath(project));
+    const pr = prs.find(p => p.prNumber === prNumber || p.id === `PR-${prNumber}`);
+    if (!pr) continue;
+    const out = {
+      prNumber: pr.prNumber || prNumber,
+      id: pr.id,
+      title: pr.title || '',
+      branch: pr.branch || '',
+      status: pr.status || 'unknown',
+      reviewStatus: pr.reviewStatus || 'pending',
+      buildStatus: pr.buildStatus || 'none',
+      url: pr.url || '',
+      project: project.name,
+      source: 'cached',
+    };
+    if (pr.buildErrorLog) out.buildErrorLog = pr.buildErrorLog;
+    if (pr._mergeConflict) out.mergeConflict = true;
+    return out;
+  }
+  return null;
+}
+
+// ── Main ─────────────────────────────────────────────────────────────────────
+
+async function main() {
+  // Use safeJson directly — pulling in queries.js would load all cached state unnecessarily
+  const config = safeJson(path.join(__dirname, '..', 'config.json')) || {};
+  const allProjects = getProjects(config).filter(p => p.repoHost === 'ado' || !p.repoHost);
+  const projects = projectName
+    ? allProjects.filter(p => p.name === projectName)
+    : allProjects;
+
+  if (projects.length === 0) {
+    const msg = projectName
+      ? `Project "${projectName}" not found in config.json`
+      : 'No ADO projects configured in config.json';
+    console.error(msg);
+    process.exit(1);
+  }
+
+  if (!live) {
+    const result = findInCache(projects);
+    if (result) { console.log(JSON.stringify(result, null, 2)); return; }
+    console.error(`PR #${prNumber} not found in cached pull-requests.json`);
+    console.error('Tip: try --live for a fresh ADO API call, or check the PR number is correct.');
+    process.exit(1);
+  }
+
+  // Live path: query all projects in parallel, return first match
+  const ado = require('./ado');
+  const settled = await Promise.allSettled(
+    projects.map(p => ado.fetchSinglePrBuildStatus(p, prNumber))
+  );
+
+  const found = settled.find(r => r.status === 'fulfilled' && r.value);
+  if (found) { console.log(JSON.stringify(found.value, null, 2)); return; }
+
+  // Log unexpected errors (not 404s — those just mean PR isn't in that project)
+  for (const { status, reason } of settled) {
+    if (status === 'rejected' && !reason?.message?.includes('404') && !reason?.message?.includes('not found')) {
+      console.error(`ADO query error: ${reason.message}`);
+    }
+  }
+
+  // Fall back to cache with a note that live lookup failed
+  const cached = findInCache(projects);
+  if (cached) {
+    cached.source = 'cached (live lookup failed — check ADO auth)';
+    console.log(JSON.stringify(cached, null, 2));
+    return;
+  }
+
+  console.error(`PR #${prNumber} not found (tried live ADO API and cached pull-requests.json).`);
+  process.exit(1);
+}
+
+main().catch(e => { console.error(e.message); process.exit(1); });

package/engine/ado.js

@@ -18,6 +18,30 @@ function engine() {
 
 const stripRefsHeads = s => (s || '').replace('refs/heads/', '');
 
+// ── Build/Review Status Helpers ───────────────────────────────────────────────
+
+/** Classify an array of ADO build records into a single status string. */
+function classifyBuildStatus(prBuilds) {
+  if (!prBuilds.length) return 'none';
+  // partiallySucceeded = warnings, not failures — counts as passing
+  const hasFailed = prBuilds.some(b => b.result === 'failed' || b.result === 'canceled');
+  const allDone = prBuilds.every(b => b.status === 'completed');
+  const allPassed = prBuilds.every(b => b.result === 'succeeded' || b.result === 'partiallySucceeded');
+  const hasRunning = prBuilds.some(b => b.status === 'inProgress' || b.status === 'notStarted');
+  if (hasFailed && allDone) return 'failing';
+  if (allDone && allPassed) return 'passing';
+  if (hasRunning) return 'running';
+  return 'none';
+}
+
+/** Map ADO reviewer vote array to a review status string. */
+function votesToReviewStatus(votes) {
+  if (votes.some(v => v === -10)) return 'changes-requested';
+  if (votes.some(v => v >= 5)) return 'approved';
+  if (votes.some(v => v === -5)) return 'waiting';
+  return 'pending';
+}
+
 // ─── ADO Token Cache ─────────────────────────────────────────────────────────
 
 let _adoTokenCache = { token: null, expiresAt: 0 };
@@ -390,14 +414,8 @@ async function pollPrStatus(config) {
         const prBuilds = (buildsData?.value || []).filter(b => b.sourceVersion === mergeCommitId);
 
         if (prBuilds.length > 0) {
-          // partiallySucceeded = warnings, not failures — counts as passing
-          const hasFailed = prBuilds.some(b => b.result === 'failed' || b.result === 'canceled');
-          const allDone = prBuilds.every(b => b.status === 'completed');
-          const allPassed = prBuilds.every(b => b.result === 'succeeded' || b.result === 'partiallySucceeded');
-          const hasRunning = prBuilds.some(b => b.status === 'inProgress' || b.status === 'notStarted');
-
-          if (hasFailed && allDone) {
-            buildStatus = 'failing';
+          buildStatus = classifyBuildStatus(prBuilds);
+          if (buildStatus === 'failing') {
             const failed = prBuilds.find(b => b.result === 'failed');
             buildFailReason = failed?.definition?.name || 'Build failed';
             // Build fake status objects for error log fetching
@@ -405,10 +423,6 @@ async function pollPrStatus(config) {
               state: 'failed', targetUrl: `${orgBase}/${project.adoProject}/_build/results?buildId=${b.id}`,
               _buildId: String(b.id),
             }));
-          } else if (allDone && allPassed) {
-            buildStatus = 'passing';
-          } else if (hasRunning) {
-            buildStatus = 'running';
           }
         }
       } catch (e) { log('warn', `ADO build query for ${pr.id}: ${e.message}`); }
@@ -758,10 +772,7 @@ async function checkLiveReviewStatus(pr, project) {
     const prData = JSON.parse(result);
     const votes = (prData.reviewers || []).map(r => r.vote).filter(v => v !== undefined);
     if (votes.length === 0) return 'pending';
-    if (votes.some(v => v === -10)) return 'changes-requested';
-    if (votes.some(v => v >= 5)) return 'approved';
-    if (votes.some(v => v === -5)) return 'waiting';
-    return 'pending';
+    return votesToReviewStatus(votes);
   } catch (e) {
     log('warn', `Live review check for ${pr.id}: ${e.message}`);
     return null;
@@ -782,6 +793,71 @@ async function fetchAdoPrMetadata(prNum, adoOrg, adoProj, adoRepo) {
   };
 }
 
+/**
+ * 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.
+ * Returns { prNumber, title, branch, status, reviewStatus, buildStatus, buildErrorLog?,
+ *           mergeConflict, url, project } or null on auth failure.
+ */
+async function fetchSinglePrBuildStatus(project, prNumber) {
+  const token = await getAdoToken();
+  if (!token) return null;
+
+  const orgBase = getAdoOrgBase(project);
+  const repoBase = `${orgBase}/${project.adoProject}/_apis/git/repositories/${project.repositoryId}`;
+  const mergeRef = encodeURIComponent(`refs/pull/${prNumber}/merge`);
+  const buildsUrl = `${orgBase}/${project.adoProject}/_apis/build/builds?branchName=${mergeRef}&repositoryId=${project.repositoryId}&repositoryType=TfsGit&$top=25&api-version=7.1`;
+
+  // Fetch PR metadata and builds in parallel
+  const [prData, buildsData] = await Promise.all([
+    adoFetch(`${repoBase}/pullrequests/${prNumber}?api-version=7.1`, token),
+    adoFetch(buildsUrl, token).catch(() => null),
+  ]);
+  if (!prData) return null;
+
+  const mergeCommitId = prData.lastMergeCommit?.commitId;
+  const prBuilds = mergeCommitId
+    ? (buildsData?.value || []).filter(b => b.sourceVersion === mergeCommitId)
+    : [];
+
+  let buildStatus = classifyBuildStatus(prBuilds);
+  let buildErrorLog = null;
+
+  if (buildStatus === 'failing') {
+    try {
+      const failedBuilds = prBuilds.filter(b => b.result === 'failed').map(b => ({
+        state: 'failed', _buildId: String(b.id),
+        targetUrl: `${orgBase}/${project.adoProject}/_build/results?buildId=${b.id}`,
+      }));
+      const logParts = [];
+      const seenBuildIds = new Set();
+      const pr = { id: `PR-${prNumber}`, branch: stripRefsHeads(prData.sourceRefName) };
+      for (const fb of failedBuilds.slice(0, 3)) {
+        const errorLog = await fetchAdoBuildErrorLog(orgBase, project, fb, token, pr, seenBuildIds);
+        if (errorLog) logParts.push(errorLog);
+      }
+      if (logParts.length > 0) buildErrorLog = logParts.join('\n\n');
+    } catch (e) { log('warn', `fetchSinglePrBuildStatus error log for PR #${prNumber}: ${e.message}`); }
+  }
+
+  const votes = (prData.reviewers || []).map(r => r.vote);
+  const prUrl = `https://dev.azure.com/${project.adoOrg}/${project.adoProject}/_git/${project.repositoryId}/pullrequest/${prNumber}`;
+
+  return {
+    prNumber,
+    title: prData.title || '',
+    branch: stripRefsHeads(prData.sourceRefName),
+    status: prData.status || 'unknown',
+    reviewStatus: votesToReviewStatus(votes),
+    buildStatus,
+    ...(buildErrorLog ? { buildErrorLog } : {}),
+    mergeConflict: prData.mergeStatus === 'conflicts',
+    url: prUrl,
+    project: project.name,
+    source: 'live',
+  };
+}
+
 module.exports = {
   getAdoToken,
   adoFetch,
@@ -792,5 +868,6 @@ module.exports = {
   needsAdoPollRetry,
   isAdoAuthError, // exported for testing
   fetchAdoPrMetadata,
+  fetchSinglePrBuildStatus,
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.948",
+  "version": "0.1.950",
   "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/playbooks/shared-rules.md

@@ -32,3 +32,25 @@ Your context window may be compacted or summarized mid-task by Claude's automati
   ````
   The `name` and `description` fields are required. `scope` defaults to `minions` (global). Use `scope: project` + `project: ProjectName` for project-specific skills.
 - Do TDD where it makes sense — write failing tests first, then implement, then verify tests pass. Especially for bug fixes (write a test that reproduces the bug) and new utility functions.
+
+## Checking PR and Build Status
+
+When asked to check build status, CI results, or review state for a PR:
+
+**Preferred — read cached state (always fresh within ~3 min when engine is running):**
+Find the PR in `projects/<project-name>/pull-requests.json` by `prNumber`. Key fields:
+- `buildStatus` — `passing` | `failing` | `running` | `none`
+- `buildErrorLog` — compiler/pipeline errors when `buildStatus` is `failing`
+- `reviewStatus` — `approved` | `changes-requested` | `waiting` | `pending`
+- `status` — `active` | `merged` | `abandoned`
+- `url` — link to the PR in ADO
+
+**Live status (when engine isn't running or you need up-to-the-moment results):**
+```bash
+node engine/ado-status.js <prNumber>              # reads cached pull-requests.json
+node engine/ado-status.js <prNumber> --live       # fresh ADO API call
+node engine/ado-status.js <prNumber> --live --project MyProject
+```
+Output is JSON with the same fields. Exit 0 on success, 1 if not found.
+
+**Never make raw `curl` calls to ADO APIs directly.** Use `node engine/ado-status.js` which routes through `ado.js` — authenticated, retried, circuit-broken. Raw `azureauth` + curl bypasses all of that.