@yemi33/minions 0.1.2280 → 0.1.2282

package/docs/timeouts-and-liveness.md

@@ -39,6 +39,12 @@ Orphan declaration requires four checks (all must pass):
 3. `isOsPidAliveForDispatch` returns false.
 4. Full-log re-scan still shows no completion.
 
+**Minimum-alive guard (M004).** `ENGINE_DEFAULTS.minAliveBeforeOrphanMs` (default 30s, configurable via
+`config.engine.minAliveBeforeOrphanMs`) is checked before the four-check ladder. A dispatch that
+hasn't been alive for that duration is skipped — prevents false-positive orphan declarations for
+short-duration agents (e.g. verify agents that complete within ~20s before process tracking catches up).
+Bypassed when `canReapDeadProcess` is true (confirmed-dead at restart).
+
 After engine restart, gated on `engineRestartGraceUntil` (default
 20 min) — see [engine-restart.md](engine-restart.md).
 

package/docs/workspace-manifests.md

@@ -56,7 +56,7 @@ A config that never mentions `workspace_manifest` produces the exact same dispat
 | **Dispatch — repo gate** | `engine.js spawnAgent()` (right after project resolution) | Calls `shared.agentCanUseRepo(agent, project)`. Mismatch → `completeDispatch(... FAILURE_CLASS.WORKSPACE_MANIFEST_REPO, agentRetryable: false)` and `cleanupTempAgent` runs. Non-retryable because the structural answer is "widen the manifest or pick a different agent". |
 | **Spawn — tool merge** | `engine.js spawnAgent()` → `_buildAgentSpawnFlags(..., allowedTools)` | `shared.mergeManifestAllowedTools(claudeConfig.allowedTools, manifest.allowed_tools)` produces the intersection of the runtime baseline and the manifest list. Result is passed as `--allowedTools <csv>` to Claude / Copilot / Codex, so the CLI itself enforces the narrowed surface. Empty manifest list (`[]`) = deny-all. Same merge runs on the steering-resume codepath. |
 | **Agent context** | Future work (playbook.js) | Manifest can be surfaced into the agent prompt so the agent sees its declared scope. Today, `shared.resolveAgentManifest(agent)` returns the resolved struct any caller can read. |
-| **URL fetch** | Advisory today | `shared.agentCanFetchUrl(agent, url)` is available for runtime intercepts. Minions itself does not currently intercept `web_fetch` inside the spawned CLI subprocess; a future runtime adapter hook can wire this. |
+| **URL fetch** | Advisory today | `allowed_external_urls` is validated at config load. No runtime helper function — a future runtime adapter hook can wire URL-fetch intercepts against the manifest. |
 | **Memory scope** | Advisory today | `shared.agentMemoryScope(agent)` is available for consolidation / playbook / inbox callers. Semantics: `private` = agent only sees its own `knowledge/agents/<id>.md`; `shared` = full team knowledge (current default); `read-only-shared` = reads shared memory but should not write inbox/notes. |
 
 ## Helpers (in `engine/shared.js`)
@@ -64,15 +64,13 @@ A config that never mentions `workspace_manifest` produces the exact same dispat
 ```js
 const { MEMORY_SCOPES, WORKSPACE_MANIFEST_DEFAULTS,
         validateWorkspaceManifest, resolveAgentManifest,
-        agentCanUseRepo, agentCanUseTool, agentCanFetchUrl, agentMemoryScope,
+        agentCanUseRepo, agentMemoryScope,
         mergeManifestAllowedTools, formatManifestRejection } = require('./engine/shared');
 ```
 
 - `validateWorkspaceManifest(manifest)` → `{ ok, errors }`. `null`/`undefined` is valid (uses defaults).
 - `resolveAgentManifest(agent, config?)` → fresh copy of `WORKSPACE_MANIFEST_DEFAULTS` overlaid with the agent's `workspace_manifest`. Malformed manifest silently falls back to defaults; surface the error via `validateWorkspaceManifest` at config-load time.
 - `agentCanUseRepo(agent, projectOrString)` → `bool`. Accepts a project object or a string identifier (`github:owner/repo`, `ado:org/proj/repo`, or bare `owner/repo`). Case-insensitive.
-- `agentCanUseTool(agent, toolName)` → `bool`. Case-sensitive.
-- `agentCanFetchUrl(agent, url)` → `bool`. Wildcard `*.example.com` matches subdomains **and** apex.
 - `agentMemoryScope(agent)` → one of `MEMORY_SCOPES`. Unknown values fall back to `'shared'`.
 - `mergeManifestAllowedTools(baselineCsv, manifestArray)` → merged CSV. Intersection semantics: `null` manifest = baseline unchanged; empty array = deny-all; empty baseline + manifest = manifest as ceiling.
 - `formatManifestRejection({ agentId, kind, target, allowed })` → structured human-readable rejection string used by the dispatch repo gate.

package/engine/ado.js

@@ -942,7 +942,13 @@ async function getAdoToken(opts = {}) {
   }
 }
 
+// Test seam — overrides adoFetch for unit tests only. Must be null in production.
+let _adoFetchOverride = null;
+function _setAdoFetchForTest(fn) { _adoFetchOverride = fn; }
+function _resetAdoFetchForTest() { _adoFetchOverride = null; }
+
 async function adoFetch(url, token, opts = {}) {
+  if (_adoFetchOverride) return _adoFetchOverride(url, token, opts);
   const _retryCount = typeof opts === 'number' ? opts : (opts._retryCount || 0); // backward compat
   const method = (typeof opts === 'object' && opts.method) || 'GET';
   const body = (typeof opts === 'object' && opts.body) || undefined;
@@ -1642,13 +1648,16 @@ async function pollPrStatus(config) {
           if (prBuilds.length > 0) {
             buildStatus = classifyBuildStatus(prBuilds);
             if (buildStatus === BUILD_STATUS.FAILING) {
-              const failed = prBuilds.find(b => b.result === 'failed');
+              // M005: count all failed builds for build-fix-complex routing
+              const failedBuilds = prBuilds.filter(b => b.result === 'failed');
+              const failed = failedBuilds[0];
               buildFailReason = failed?.definition?.name || 'Build failed';
               buildFailureSignature = shared.safeSlugComponent([
                 failed?.definition?.name,
                 failed?.result,
                 failed?.status,
               ].filter(Boolean).join('\n') || buildFailReason, 80);
+              pr._failedCheckCount = failedBuilds.length;
             }
           } else if (allBuilds.length > 0) {
             // Stale merge-commit classification (Issue #2747). ADO returned
@@ -1738,6 +1747,7 @@ async function pollPrStatus(config) {
           if (buildStatus === BUILD_STATUS.PASSING) {
             delete pr.buildErrorLog;
             delete pr.buildFailureSignature;
+            delete pr._failedCheckCount; // M005: clear on recovery
             // Reset build fix retry counter on recovery — allows fresh auto-fix cycles if build breaks again
             if (pr.buildFixAttempts) { delete pr.buildFixAttempts; }
           }
@@ -2945,6 +2955,8 @@ module.exports = {
   _resetAdoThrottle, // exported for testing
   _setAdoThrottleForTest, // exported for testing
   _setAdoTokenForTest, // exported for testing
+  _setAdoFetchForTest, // exported for testing
+  _resetAdoFetchForTest, // exported for testing
   // Exported for unit tests — engine code MUST go through pollPrStatus / reconcilePrs.
   decodeUrlSegment,
   stripGitSuffix,

package/engine/cleanup.js

@@ -1643,7 +1643,7 @@ function runPeriodicWorktreeSweep(config) {
   // null" claim is true for the dispatch-end GC but NOT for this registry-derived
   // periodic sweep.)
   const projects = allProjects.filter(p => {
-    try { return !shared.isLiveCheckoutProject(p); } catch { return true; }
+    try { return !shared.isLiveCheckoutProject(p); } catch { return false; } // W-mquoe8fu000w9383: fail-CLOSED — exclude from GC when checkout mode cannot be determined
   });
   const liveSkipped = allProjects.length - projects.length;
   if (projects.length === 0) {

package/engine/dispatch.js

@@ -1,6 +1,20 @@
 /**
  * engine/dispatch.js — Dispatch queue management: add, complete, mutate, alerts.
  * Extracted from engine.js for modularity. No logic changes.
+ *
+ * ## Dispatch meta schema — optional fields (M006)
+ *
+ * Dispatch items carry a free-form `meta` object. The following optional fields
+ * are part of the typed handoff envelope contract (added in M006):
+ *
+ *   meta.from_agent      {string} — agent id of the completing agent that queued
+ *                                   this follow-up (e.g. 'lambert', 'temp-abc123').
+ *   meta.from_conclusion {string} — 1–3 sentence structured summary of what the
+ *                                   completing agent concluded before handing off.
+ *
+ * These fields are optional and additive. Dispatches without them are unaffected.
+ * When present, engine/playbook.js injects a "Handoff Context" section into the
+ * rendered prompt so the receiving agent has explicit orientation.
  */
 
 const fs = require('fs');

package/engine/github.js

@@ -1037,7 +1037,9 @@ async function pollPrStatus(config) {
 
           if (hasFailed) {
             buildStatus = BUILD_STATUS.FAILING;
-            const failed = runs.find(r => r.conclusion === 'failure' || r.conclusion === 'timed_out' || r.conclusion === 'startup_failure');
+            // M005: count all failing runs for build-fix-complex routing
+            const failedRuns = runs.filter(r => r.conclusion === 'failure' || r.conclusion === 'timed_out' || r.conclusion === 'startup_failure');
+            const failed = failedRuns[0];
             buildFailReason = failed?.name || 'Check failed';
             buildFailureSignature = shared.safeSlugComponent([
               failed?.name,
@@ -1046,6 +1048,7 @@ async function pollPrStatus(config) {
               failed?.output?.summary,
               failed?.output?.text,
             ].filter(Boolean).join('\n') || buildFailReason, 80);
+            pr._failedCheckCount = failedRuns.length;
           } else if (allDone && allPassed) {
             buildStatus = BUILD_STATUS.PASSING;
           } else if (allDone) {
@@ -1079,6 +1082,7 @@ async function pollPrStatus(config) {
             if (buildStatus === BUILD_STATUS.PASSING) {
               delete pr.buildErrorLog;
               delete pr.buildFailureSignature;
+              delete pr._failedCheckCount; // M005: clear on recovery
               // Reset build fix retry counter on recovery — allows fresh auto-fix cycles if build breaks again
               if (pr.buildFixAttempts) { delete pr.buildFixAttempts; }
             }

package/engine/lifecycle.js

@@ -4765,7 +4765,7 @@ function handleHarnessIterationResult(stdout, structuredCompletion, meta, config
  *   - All RMW on dispatch.json goes through addToDispatch (mutateDispatch), per
  *     the concurrency rules in CLAUDE.md.
  */
-function dispatchReReviewForFix(fixDispatchItem, meta, config) {
+function dispatchReReviewForFix(fixDispatchItem, meta, config, opts = {}) {
   const addressesReviewWi = meta?.addresses_review_wi || meta?.item?.meta?.addresses_review_wi || null;
   if (!addressesReviewWi) return null;
   const pr = meta?.pr;
@@ -4814,6 +4814,15 @@ function dispatchReReviewForFix(fixDispatchItem, meta, config) {
   const projMeta = project;
   const headSha = String(livePr.headSha || livePr._adoSourceCommit || livePr._adoHeadCommit || pr.headSha || '').trim();
   const reReviewKey = `rereview-${project?.name || 'default'}-${shared.getPrDisplayId ? shared.getPrDisplayId(livePr) : pr.id}-${headSha ? headSha.slice(0, 8) : 'nohead'}`;
+  // M006 — typed handoff envelope: stamp from_agent / from_conclusion on the
+  // re-review meta so the reviewer agent sees who fixed the PR and what they
+  // concluded. from_agent is the fix agent id; from_conclusion is a 1-sentence
+  // summary derived from the fix resultSummary (capped to avoid bloating the
+  // dispatch queue). Both are optional — the reviewer playbook degrades to
+  // standard orientation when they are absent.
+  const fromAgent = opts.agentId || fixDispatchItem?.agent || '';
+  const rawConclusion = opts.resultSummary || fixDispatchItem?.resultSummary || '';
+  const fromConclusion = rawConclusion ? String(rawConclusion).slice(0, 300) : '';
   const rereviewMeta = {
     dispatchKey: reReviewKey,
     source: 'pr',
@@ -4822,6 +4831,8 @@ function dispatchReReviewForFix(fixDispatchItem, meta, config) {
     project: projMeta,
     rereview_of: fixDispatchItem?.id || null,
     addresses_review_wi: addressesReviewWi,
+    ...(fromAgent ? { from_agent: fromAgent } : {}),
+    ...(fromConclusion ? { from_conclusion: fromConclusion } : {}),
   };
   const extraVars = {
     pr_id: livePr.id, pr_number: prNumber, pr_title: livePr.title || '', pr_branch: prBranch,
@@ -5686,7 +5697,7 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
     // reviewer. See engine/ado.js:resetReviewerNegativeVote for the verdict-
     // flip reset that fires on the resulting APPROVE.
     try {
-      dispatchReReviewForFix(dispatchItem, meta, config);
+      dispatchReReviewForFix(dispatchItem, meta, config, { agentId, resultSummary });
     } catch (err) {
       log('warn', `Re-review auto-dispatch for ${meta?.pr?.id || 'unknown PR'}: ${err.message}`);
     }

package/engine/pipeline.js

@@ -530,7 +530,7 @@ function _findExistingPrdForPlan(planFile, prdDir) {
     // safeJsonNoRestore: PRDs are terminal artifacts — never restore archived
     // PRDs from a stale .backup sidecar (W-mouptdh1000h9f39).
     const prd = safeJsonNoRestore(path.join(prdDir, pf));
-    if (prd?.source_plan === planFile) return pf;
+    if (prd?.source_plan && path.basename(String(prd.source_plan)) === planFile) return pf;
   }
   return null;
 }
@@ -928,7 +928,7 @@ function isStageComplete(stage, stageState, run, config) {
         for (const pf of prdFiles) {
           // safeJsonNoRestore — see _findExistingPrdForPlan above (W-mouptdh1000h9f39).
           const prd = safeJsonNoRestore(path.join(prdDir, pf));
-          if (prd?.source_plan === planFile && !(artifacts.prds || []).includes(pf) && !discoveredPrds.includes(pf)) {
+          if (prd?.source_plan && path.basename(String(prd.source_plan)) === planFile && !(artifacts.prds || []).includes(pf) && !discoveredPrds.includes(pf)) {
             discoveredPrds.push(pf);
           }
         }

package/engine/playbook.js

@@ -386,12 +386,21 @@ const PLAYBOOK_OPTIONAL_VARS = new Set([
   // produce matches. Optional for the same reason as the review-only alias.
   'project_skills_block',
   'skip_project_skills',
+  // M006 — typed handoff envelope fields. Set on a follow-up dispatch meta
+  // when lifecycle.js queues the item after a completing agent so the
+  // receiving agent has explicit context about who handed off and why.
+  // from_agent: agent id of the completing agent (e.g. 'lambert')
+  // from_conclusion: 1–3 sentence structured summary of what that agent concluded
+  // Both are optional; playbooks that don't reference them receive empty strings.
+  'from_agent',
+  'from_conclusion',
 ]);
 
 const PLAYBOOK_REQUIRED_VARS = {
   'implement':            ['item_id', 'item_name', 'branch_name', 'project_path'],
   'implement-shared':     ['item_id', 'item_name', 'branch_name', 'worktree_path'],
   'fix':                  ['pr_id', 'pr_branch'],
+  'build-fix-complex':    ['pr_id', 'pr_branch'],
   'review':               ['pr_id', 'pr_branch'],
   'build-and-test':       ['pr_id', 'pr_branch', 'project_path'],
   'explore':              ['task_description'],
@@ -570,6 +579,25 @@ function buildQaValidateContextBlock({ runId, runbook, target, artifactsDir }) {
 }
 
 
+// ─── M006 — Handoff Context Block ────────────────────────────────────────────
+
+/**
+ * Build a "Handoff Context" appendix section for follow-up dispatches.
+ * Called when vars.from_agent or vars.from_conclusion is truthy so the
+ * receiving agent knows who handed off and what they concluded.
+ *
+ * @param {{ fromAgent?: string, fromConclusion?: string }} opts
+ * @returns {string} markdown section, or '' when both fields are falsy
+ */
+function buildHandoffContextBlock({ fromAgent, fromConclusion } = {}) {
+  if (!fromAgent && !fromConclusion) return '';
+  const lines = ['\n\n---\n\n## Handoff Context (from previous agent)\n'];
+  if (fromAgent) lines.push(`**Previous agent:** \`${fromAgent}\``);
+  if (fromConclusion) lines.push(`\n**Conclusion:** ${fromConclusion}`);
+  return lines.join('\n');
+}
+
+
 // ─── Playbook Renderer ──────────────────────────────────────────────────────
 
 /**
@@ -823,7 +851,7 @@ function renderPlaybook(type, vars) {
   // (of liveValidation.type) runs the full build on the live environment after
   // the PR lands. When autoDispatch is false the agent is responsible for its own
   // inline validation (may fail in isolated worktrees — documented limitation).
-  const LIVE_VALIDATION_PLAYBOOKS = new Set(['implement', 'fix', 'docs', 'decompose']);
+  const LIVE_VALIDATION_PLAYBOOKS = new Set(['implement', 'fix', 'build-fix-complex', 'docs', 'decompose']);
   if (LIVE_VALIDATION_PLAYBOOKS.has(type)) {
     const lv = matchedProject && matchedProject.liveValidation;
     if (lv && lv.autoDispatch === true) {
@@ -838,6 +866,18 @@ function renderPlaybook(type, vars) {
     }
   }
 
+  // M006 — typed handoff envelope: inject from_agent/from_conclusion context
+  // when the dispatch was queued as a follow-up from a completing agent. Only
+  // fires when at least one field is truthy so unrelated dispatches stay clean.
+  if (vars.from_agent || vars.from_conclusion) {
+    try {
+      const block = buildHandoffContextBlock({
+        fromAgent: vars.from_agent,
+        fromConclusion: vars.from_conclusion,
+      });
+      if (block) inertAppendices.push(block);
+    } catch (e) { log('warn', `handoff-context inject failed: ${e.message}`); }
+  }
   // Inject KB guardrail
   content += `\n\n---\n\n## Knowledge Base Rules\n\n`;
   content += `**Never delete, move, or overwrite files in \`knowledge/\`.** The sweep (consolidation engine) is the only process that writes to \`knowledge/\`. If you think a KB file is wrong, note it in your learnings file — do not touch \`knowledge/\` directly.\n`;
@@ -1266,6 +1306,9 @@ function selectPlaybook(workType, item) {
   if (workType === WORK_TYPE.FIX && hasPrContext) {
     return 'fix';
   }
+  if (workType === WORK_TYPE.BUILD_FIX_COMPLEX && hasPrContext) {
+    return 'build-fix-complex';
+  }
   const typeSpecificPlaybooks = ['explore', 'review', 'test', 'plan-to-prd', 'plan', 'ask', 'verify', 'decompose', 'docs', 'setup', 'meeting-investigate', 'meeting-debate', 'meeting-conclude'];
   return typeSpecificPlaybooks.includes(workType) ? workType : 'work-item';
 }
@@ -1295,7 +1338,10 @@ function buildPrDispatch(agentId, config, project, pr, type, extraVars, taskLabe
     ...extraVars,
     task_id: dispatchId,
   };
-  const playbookName = type === WORK_TYPE.TEST ? 'build-and-test' : (type === WORK_TYPE.REVIEW ? 'review' : 'fix');
+  // M005: use selectPlaybook for routing rather than a hardcoded ternary so
+  // new work types (e.g. BUILD_FIX_COMPLEX → 'build-fix-complex') are picked
+  // up automatically. TEST keeps its legacy alias ('build-and-test' ≠ 'test').
+  const playbookName = type === WORK_TYPE.TEST ? 'build-and-test' : selectPlaybook(type, extraVars || {});
   const prompt = renderPlaybook(playbookName, vars);
   if (!prompt) return null;
   return {

package/engine/shared.js

@@ -3795,6 +3795,14 @@ const WORK_TYPE = {
   // so callers don't need to also set skipPr:true. Still worktree-requiring
   // and still project-required (mirrors implement/fix HTTP-validate path).
   SETUP: 'setup',
+  // BUILD_FIX_COMPLEX (M005 / SHERLOC): engine-dispatched two-phase build-fix
+  // variant for multi-file or multi-test failures. Phase 1 (Localization)
+  // requires the agent to document fault files, root-cause hypothesis, and
+  // proposed repair before making any edits. Phase 2 (Implementation) executes
+  // the plan. Dispatched automatically by the engine when a PR's build failure
+  // spans more than one file/test. Always operates on a PR branch (PR context
+  // required at dispatch time, same as FIX).
+  BUILD_FIX_COMPLEX: 'build-fix-complex',
 };
 
 // Work types whose dispatch path requires a per-project git worktree. The
@@ -3828,6 +3836,10 @@ const WORKTREE_REQUIRING_TYPES = new Set([
   // worktree resolver falls back to MINIONS_DIR's parent and collapses to a
   // drive root on installs where MINIONS_DIR sits one level below the root.
   WORK_TYPE.SETUP,
+  // BUILD_FIX_COMPLEX (M005): runs on the PR's source branch (like FIX) so a
+  // real project worktree is required. Without a project the worktree resolver
+  // falls back to MINIONS_DIR's parent and can collapse to a drive root.
+  WORK_TYPE.BUILD_FIX_COMPLEX,
   WORK_TYPE.DOCS,
 ]);
 
@@ -3848,6 +3860,7 @@ const VALID_WORK_TYPES = new Set([
   WORK_TYPE.TEST,
   WORK_TYPE.DOCS,
   WORK_TYPE.SETUP,
+  WORK_TYPE.BUILD_FIX_COMPLEX,
 ]);
 
 // Match a leading "Type: <word>" line in a description (handles both bare

package/engine.js

@@ -7206,7 +7206,11 @@ async function discoverFromPrs(config, project) {
         }
       } catch (e) { log('warn', `Pre-dispatch build check for ${pr.id}: ${e.message} — skipping dispatch`); continue; }
 
-      const agentId = resolveAgent('fix', config, { authorAgent: pr.agent });
+      // M005 (SHERLOC): route to build-fix-complex when multiple checks failed;
+      // single-check failures stay on the fast 'fix' path.
+      const isComplexBuildFailure = (pr._failedCheckCount != null ? pr._failedCheckCount : 1) > 1;
+      const buildFixWorkType = isComplexBuildFailure ? WORK_TYPE.BUILD_FIX_COMPLEX : WORK_TYPE.FIX;
+      const agentId = resolveAgent(buildFixWorkType, config, { authorAgent: pr.agent });
       if (!agentId) continue;
       const prBranch = ensurePrBranchForDispatch(project, pr, 'build-fix');
       if (!prBranch) continue;
@@ -7225,7 +7229,7 @@ async function discoverFromPrs(config, project) {
         pr.url ? `PR URL: ${pr.url}` : '',
       ].filter(Boolean).join('\n');
 
-      const item = buildPrDispatch(agentId, config, project, pr, 'fix', {
+      const item = buildPrDispatch(agentId, config, project, pr, buildFixWorkType, {
         pr_id: pr.id, pr_branch: prBranch,
         review_note: reviewNote,
       }, `Fix build failure on ${pr.id}: ${pr.title || ''}`, { dispatchKey: key, cooldownKey: key, automationCauseKey: buildCauseKey, source: 'pr', pr, branch: prBranch, project: projMeta });
@@ -7614,6 +7618,12 @@ function renderProjectWorkItemPromptForAgent(item, workType, agentId, config, pr
     // Either flag suppresses both blocks on the dispatch.
     skip_project_review_skills: !!(item.meta && item.meta.skipProjectReviewSkills),
     skip_project_skills: !!(item.meta && (item.meta.skipProjectSkills || item.meta.skipProjectReviewSkills)),
+    // M006 — typed handoff envelope. Set on follow-up dispatch metas by
+    // lifecycle.js when queuing an item after a completing agent. The
+    // renderPlaybook path injects a "Handoff Context" section when truthy
+    // so the receiving agent sees who handed off and what they concluded.
+    from_agent: (item.meta && item.meta.from_agent) ? String(item.meta.from_agent) : '',
+    from_conclusion: (item.meta && item.meta.from_conclusion) ? String(item.meta.from_conclusion) : '',
   };
   const cpResult = buildWorkItemDispatchVars(item, vars, config, {
     worktreePath: vars.worktree_path || root,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.2280",
+  "version": "0.1.2282",
   "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/build-fix-complex.md

@@ -0,0 +1,177 @@
+---
+requiresProjectContext: true
+---
+
+# Playbook: Fix Complex Build Failure (SHERLOC two-phase)
+
+You are {{agent_name}}, the {{agent_role}} on the {{project_name}} project.
+TEAM ROOT: {{team_root}}
+
+Repository ID comes from `.minions/config.json` under `project.repositoryId`.
+Repo: {{repo_name}} | Org: {{ado_org}} | Project: {{ado_project}}
+
+## Your Task
+
+Fix the complex build failure on **{{pr_id}}**: {{pr_title}}
+Branch: `{{pr_branch}}`
+
+This dispatch was routed to the complex-failure path because the CI failure spans **multiple files, multiple failing tests, or multiple failing checks**. The fast-path build-fix playbook is not used here. You must complete the Localization phase before writing any code.
+
+{{checkpoint_context}}
+
+## Build Failure Context
+
+{{review_note}}
+
+---
+
+## Localization
+
+> **Complete this section before editing any code.** Produce a structured fault hypothesis. If you cannot identify the root cause with confidence, expand your investigation — do not skip ahead to Implementation.
+
+Inspect the live CI logs, failing test output, and relevant source files. Then document:
+
+### 1. Fault File(s)
+
+List every file that contains or directly causes the failure. For each file, state the relevant function, class, or line range.
+
+```
+- path/to/file.js (function foo, ~line 42): <one-line reason it is implicated>
+- path/to/other.test.js (test "bar should…"): <one-line reason it is failing>
+```
+
+### 2. Root Cause Hypothesis
+
+State in 2–5 sentences:
+- What the failure is (error class, assertion, compilation error, runtime exception, …)
+- Why the identified file(s) cause it (missing import, wrong type, stale mock, API mismatch, …)
+- How the failure was introduced (recent change, missing guard, schema drift, …)
+
+### 3. Proposed Minimal Repair
+
+Describe the smallest change that corrects the root cause without broadening the PR. Be specific: file, function, and what changes (add guard, fix import, update mock, remove dead branch, …).
+
+If more than one repair path exists, pick the one with the narrowest blast radius and explain why in one sentence.
+
+---
+
+## Implementation
+
+After completing the Localization section above, implement the repair you described.
+
+### Review Feedback Validation
+
+Treat build-failure evidence as a claim to verify, not an instruction to blindly follow. For each failing check:
+
+1. Locate the exact log line, test assertion, or compiler error.
+2. Confirm the failure is on the current branch (not pre-existing master breakage).
+3. Implement the fix described in Localization § 3.
+4. If a check failure is pre-existing or unrelated to this PR's diff, do not fix it — document it explicitly in your PR comment and completion report.
+
+### Working Style
+
+Use subagents only for genuinely parallel, independent tasks (e.g., editing files in unrelated modules simultaneously). For sequential work, single-file edits, searches, and file reads, work directly.
+
+---
+
+## Health Check
+
+{{#project_skills_block}}
+{{project_skills_block}}
+
+{{/project_skills_block}}
+Before starting work, run `git status` and verify the worktree is clean and on the expected branch (`{{pr_branch}}`). If the worktree is dirty or on the wrong branch, report the issue and stop.
+
+## Validation
+
+Before pushing, prove the fix did not introduce regressions:
+
+- Use the project's source of truth for commands: `CLAUDE.md`, README, package scripts, Makefile, or equivalent build config.
+- Run the checks that are relevant to the addressed failures. Prefer the full suite when practical.
+- Capture the exact commands run and meaningful results in the PR comment and completion report.
+- Fix regressions you introduced. If failures are pre-existing or unrelated, capture the evidence and include it in the PR comment.
+- Do not push code that breaks existing tests or the build because of your changes.
+
+Long builds, dependency installs, and tests may be quiet for several minutes. Let the normal CLI command run naturally; do not add artificial heartbeat output or split commands just to show progress.
+
+## Publish & Comment on PR
+
+After the fix is validated or any unavoidable limitation is clearly documented, commit only relevant files and push:
+
+```bash
+git add <specific files>
+git commit -m "fix: resolve complex build failure on {{pr_id}}"
+git push
+```
+
+Do NOT remove the worktree — the engine handles cleanup automatically.
+
+{{pr_comment_instructions}}
+- pullRequestId: `{{pr_number}}`
+- content: Include the completed Localization hypothesis (fault files, root cause, repair), what was changed (file:line), and build/test validation results.
+- Sign: `Fixed by [Minions](https://icy-water-0224cc51e.2.azurestaticapps.net/minions) ({{agent_name}} — {{agent_role}} · {{agent_model}})`
+
+## PR description audit (mandatory unless `meta.skipDescriptionAudit`)
+
+<!-- Inlined from playbooks/_pr-description-audit.md — keep in sync (enforced by test/unit/config-and-playbooks.test.js). -->
+
+{{#skip_description_audit}}
+> **Audit suppressed.** This dispatch was invoked with `meta.skipDescriptionAudit: true`.
+> Record `meta.descriptionAudit = { ran: false, result: "skipped:meta-flag" }` in your completion report
+> and skip the audit steps below entirely.
+{{/skip_description_audit}}
+
+After you push commits to the PR's source branch and BEFORE you mark the work item done, audit the PR description and refresh it to match the new diff. Skip the audit when you pushed no commits this dispatch or when the dispatch is a no-op completion; record the skip in `meta.descriptionAudit`.
+
+**Audit steps**
+
+1. Fetch the current PR description.
+   - GitHub: `gh pr view <num> --repo <owner>/<repo> --json body --jq .body`
+   - Azure DevOps: `az repos pr show --id <num> --query description -o tsv`
+2. Compute the diff for the commits you just pushed: `git log --stat <baseline>..HEAD` where `<baseline>` is `origin/<branch>@{1}` for follow-up pushes (or `origin/main` for the very first push).
+3. For each section of the description, evaluate whether the new diff invalidates anything it claims. Focus on: feature lists / "what changed" bullets, config/option tables, file or path lists, line counts, before/after metrics, ASCII diagrams, and embedded markdown image refs.
+4. **No drift** → record `meta.descriptionAudit = { ran: true, result: "no-changes-needed" }` and stop.
+5. **Drift detected** → build a patched body. **Preserve prose voice.** Edit only the stale parts. Do NOT rewrite. Do NOT add new sections. Do NOT change the PR title. Do NOT toggle draft state. Do NOT post a separate PR comment narrating the description change.
+6. Push the patched description.
+   - GitHub: write the new body to a temp file, then `gh pr edit <num> --repo <owner>/<repo> --body-file <file>`.
+   - Azure DevOps: `az repos pr update --id <num> --description "$(Get-Content -Raw <file>)"`. If the body exceeds ~4 KB, fall back to `az rest --method patch` against `…/pullRequests/<id>?api-version=7.1` with `{ "description": "<body>" }`.
+7. GET-verify the description post-patch by re-running step 1 and confirming the body matches what you sent.
+
+**Out-of-scope guardrails**
+
+- Don't add screenshots that weren't already there. Refresh only.
+- Don't rewrite description prose beyond the targeted stale edits.
+- Don't modify the PR title; don't toggle draft state, close/reopen the PR.
+- Don't post a separate PR comment summarizing the description change.
+- Don't fail the work item on a screenshot or attachment failure — degrade gracefully and record the skip.
+- Screenshots NEVER land in the repo. `agents/<id>/screenshots/` only; never `git add` a PNG.
+
+**Completion-report shape**
+
+When the audit ran (whether it edited the description or no-op'd), include this in the completion JSON (full schema: `docs/completion-reports.md` → "PR description audit"):
+
+```json
+{
+  "meta": {
+    "descriptionAudit": {
+      "ran": true,
+      "result": "description-patched",
+      "oldScreenshots": [],
+      "newScreenshots": [],
+      "patchedSections": ["feature-bullets", "config-table"]
+    }
+  }
+}
+```
+
+Omit `meta.descriptionAudit` entirely when the audit did not run (no commits pushed, no-op completion). When `meta.skipDescriptionAudit` suppressed the audit, set `ran: false` and `result: "skipped:meta-flag"`.
+
+## When to Stop
+
+Your task is complete when: the Localization hypothesis is documented, the fix is implemented and validated, the branch is pushed, and the PR is commented. Do NOT continue into unrelated improvements.
+
+**NEVER run `gh pr merge` or any merge command on this PR.** The engine handles merging after review approval.
+
+## Completion
+
+After finishing, write the JSON completion report described in the shared rules (schema: `docs/completion-reports.md`). Include the completed Localization section (fault files, root cause, repair) in your `summary` field. A fenced ` ```completion ` block in stdout is accepted only as a compatibility fallback — do not duplicate the schema here.

package/routing.md

@@ -11,6 +11,7 @@ How the engine decides who handles what. Parsed by engine.js — keep the table
 | implement:large | rebecca | dallas |
 | review | ripley | lambert |
 | fix | _author_ | _any_ |
+| build-fix-complex | _author_ | dallas |
 | plan | ripley | rebecca |
 | plan-to-prd | lambert | rebecca |
 | explore | ripley | rebecca |
@@ -30,6 +31,7 @@ Notes:
 - `_author_` means route to the PR author
 - `_any_` means route to any available idle agent (lowest error rate first)
 - `implement:large` is for items with `estimated_complexity: "large"`
+- `build-fix-complex` is for multi-file failures, more than one failing test, or multiple failing checks; simple 1-file-1-test failures use the `fix` work type (fast path)
 - Engine falls back to any idle agent if both preferred and fallback are busy
 - Routing selects an owner; it should not narrow the user's task contract. The assigned agent should behave like the user typed the same task directly into a CLI, with Minions adding only safety, status, and review guardrails.
 - `fix` review-feedback routing sends work to the PR author for context, but the author must still validate review comments as claims before editing and push back with evidence when the comment is invalid, stale, already addressed, out of scope, or harmful.