@yemi33/minions 0.1.948 → 0.1.949

package/CHANGELOG.md

@@ -1,8 +1,9 @@
 # Changelog
 
-## 0.1.948 (2026-04-14)
+## 0.1.949 (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

package/engine/ado-status.js

@@ -0,0 +1,143 @@
+#!/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 { 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 getConfig() {
+  // Avoid pulling in queries.js to keep startup fast; read config directly.
+  const configPath = path.join(__dirname, '..', 'config.json');
+  try { return JSON.parse(require('fs').readFileSync(configPath, 'utf8')); }
+  catch { return {}; }
+}
+
+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() {
+  const config = getConfig();
+  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) {
+    // Fast path: read engine-maintained pull-requests.json
+    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: call ADO API via ado.js (handles auth, retry, circuit breaking)
+  const ado = require('./ado');
+
+  // Try each project until we find the PR
+  for (const project of projects) {
+    try {
+      const result = await ado.fetchSinglePrBuildStatus(project, prNumber);
+      if (result) { console.log(JSON.stringify(result, null, 2)); return; }
+    } catch (e) {
+      // 404 or similar — PR not in this project, try the next one
+      if (!e.message?.includes('404') && !e.message?.includes('not found')) {
+        console.error(`Error querying ${project.name}: ${e.message}`);
+      }
+    }
+  }
+
+  // Live lookup failed — fall back to cache
+  const cached = findInCache(projects);
+  if (cached) {
+    cached._liveFailed = true;
+    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

@@ -782,6 +782,84 @@ 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 prData = await adoFetch(`${repoBase}/pullrequests/${prNumber}?api-version=7.1`, token);
+  if (!prData) return null;
+
+  const mergeCommitId = prData.lastMergeCommit?.commitId;
+  let buildStatus = 'none';
+  let buildErrorLog = null;
+
+  if (mergeCommitId) {
+    try {
+      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`;
+      const buildsData = await adoFetch(buildsUrl, token);
+      const prBuilds = (buildsData?.value || []).filter(b => b.sourceVersion === mergeCommitId);
+
+      if (prBuilds.length > 0) {
+        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';
+          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();
+          for (const fb of failedBuilds.slice(0, 3)) {
+            const errorLog = await fetchAdoBuildErrorLog(orgBase, project, fb, token, { id: `PR-${prNumber}` }, seenBuildIds);
+            if (errorLog) logParts.push(errorLog);
+          }
+          if (logParts.length > 0) buildErrorLog = logParts.join('\n\n');
+        } else if (allDone && allPassed) {
+          buildStatus = 'passing';
+        } else if (hasRunning) {
+          buildStatus = 'running';
+        }
+      }
+    } catch (e) { log('warn', `fetchSinglePrBuildStatus build query for PR #${prNumber}: ${e.message}`); }
+  }
+
+  const votes = (prData.reviewers || []).map(r => r.vote);
+  let reviewStatus = 'pending';
+  if (votes.some(v => v === -10)) reviewStatus = 'changes-requested';
+  else if (votes.some(v => v >= 5)) reviewStatus = 'approved';
+  else if (votes.some(v => v === -5)) reviewStatus = 'waiting';
+
+  // Reconstruct a human-readable PR URL from the API URL
+  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,
+    buildStatus,
+    buildErrorLog: buildErrorLog || undefined,
+    mergeConflict: prData.mergeStatus === 'conflicts',
+    url: prUrl,
+    project: project.name,
+    source: 'live',
+  };
+}
+
 module.exports = {
   getAdoToken,
   adoFetch,
@@ -792,5 +870,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.949",
   "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.