@yemi33/minions 0.1.58 → 0.1.60

package/engine.js

@@ -123,516 +123,17 @@ const { getConfig, getControl, getDispatch, getNotes,
   collectSkillFiles, getSkillIndex, getKnowledgeBaseIndex,
   getPrs, SKILLS_DIR } = queries;
 
-function getRouting() {
-  return safeRead(ROUTING_PATH);
-}
-
-// ─── Routing Parser ─────────────────────────────────────────────────────────
-
-let _routingCache = null;
-let _routingCacheMtime = 0;
-
-function parseRoutingTable() {
-  const content = getRouting();
-  const routes = {};
-  const lines = content.split('\n');
-  let inTable = false;
-
-  for (const line of lines) {
-    if (line.startsWith('| Work Type')) { inTable = true; continue; }
-    if (line.startsWith('|---')) continue;
-    if (!inTable || !line.startsWith('|')) {
-      if (inTable && !line.startsWith('|')) inTable = false;
-      continue;
-    }
-    const cells = line.split('|').map(c => c.trim()).filter(Boolean);
-    if (cells.length >= 3) {
-      routes[cells[0].toLowerCase()] = {
-        preferred: cells[1].toLowerCase(),
-        fallback: cells[2].toLowerCase()
-      };
-    }
-  }
-  return routes;
-}
-
-function getRoutingTableCached() {
-  let mtime = 0;
-  try { mtime = fs.statSync(ROUTING_PATH).mtimeMs; } catch {}
-  if (_routingCache && _routingCacheMtime === mtime) return _routingCache;
-  _routingCache = parseRoutingTable();
-  _routingCacheMtime = mtime;
-  return _routingCache;
-}
-
-function getMonthlySpend(agentId) {
-  const metrics = safeJson(path.join(ENGINE_DIR, 'metrics.json')) || {};
-  const daily = metrics._daily || {};
-  const now = new Date();
-  const monthPrefix = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}`;
-  let total = 0;
-  for (const [date, data] of Object.entries(daily)) {
-    if (date.startsWith(monthPrefix)) {
-      total += (data.perAgent?.[agentId]?.costUsd || 0);
-    }
-  }
-  // Fallback: if no per-agent daily data, use cumulative (less accurate for monthly)
-  if (total === 0 && metrics[agentId]?.totalCostUsd) {
-    // Can't distinguish monthly from cumulative — treat as monthly estimate
-    // This path is for backward compat before per-agent daily tracking was added
-  }
-  return total;
-}
-
-function getAgentErrorRate(agentId) {
-  const metricsPath = path.join(ENGINE_DIR, 'metrics.json');
-  const metrics = safeJson(metricsPath) || {};
-  const m = metrics[agentId];
-  if (!m) return 0;
-  const total = m.tasksCompleted + m.tasksErrored;
-  return total > 0 ? m.tasksErrored / total : 0;
-}
-
-function isAgentIdle(agentId) {
-  // Dispatch queue is the single source of truth for agent availability
-  const dispatch = safeJson(DISPATCH_PATH) || {};
-  return !(dispatch.active || []).some(d => d.agent === agentId);
-}
-
-// Track agents claimed during a single discovery pass to distribute work
-const _claimedAgents = new Set();
-function resetClaimedAgents() { _claimedAgents.clear(); }
-
-function resolveAgent(workType, config, authorAgent = null) {
-  const routes = getRoutingTableCached();
-  const route = routes[workType] || routes['implement'];
-  const agents = config.agents || {};
-
-  // Resolve _author_ token
-  let preferred = route.preferred === '_author_' ? authorAgent : route.preferred;
-  let fallback = route.fallback === '_author_' ? authorAgent : route.fallback;
-
-  const isAvailable = (id) => {
-    if (!agents[id] || !isAgentIdle(id) || _claimedAgents.has(id)) return false;
-    // Budget check — no budget means infinite (no limit)
-    const budget = agents[id].monthlyBudgetUsd;
-    if (budget && budget > 0) {
-      if (getMonthlySpend(id) >= budget) return false;
-    }
-    return true;
-  };
-
-  // Check preferred and fallback first (routing table order)
-  if (preferred && isAvailable(preferred)) { _claimedAgents.add(preferred); return preferred; }
-  if (fallback && isAvailable(fallback)) { _claimedAgents.add(fallback); return fallback; }
-
-  // Fall back to any idle agent, preferring lower error rates
-  const idle = Object.keys(agents)
-    .filter(id => id !== preferred && id !== fallback && isAvailable(id))
-    .sort((a, b) => getAgentErrorRate(a) - getAgentErrorRate(b));
-
-  if (idle[0]) { _claimedAgents.add(idle[0]); return idle[0]; }
-
-  // No idle configured agent — try temp agent if enabled
-  if (config.engine?.allowTempAgents) {
-    const tempId = `temp-${shared.uid()}`;
-    _claimedAgents.add(tempId);
-    tempAgents.set(tempId, { name: `Temp-${tempId.slice(5, 9)}`, role: 'Temporary Agent', createdAt: ts() });
-    log('info', `Spawning temp agent ${tempId} — all permanent agents busy`);
-    return tempId;
-  }
-
-  // No idle agent available — return null, item stays pending until next tick
-  return null;
-}
-
-// ─── Task Context Resolution ────────────────────────────────────────────────
-// Resolves implicit references in task descriptions (e.g., "ripley's plan",
-// "dallas's PR") to actual artifacts and injects their content.
-
-function resolveTaskContext(item, config) {
-  const title = (item.title || '').toLowerCase();
-  const desc = (item.description || '').toLowerCase();
-  const text = title + ' ' + desc;
-  const agentNames = Object.entries(config.agents || {}).map(([id, a]) => ({
-    id,
-    name: (a.name || id).toLowerCase(),
-  }));
-  const resolved = { additionalContext: '', referencedFiles: [] };
-
-  // Match agent references: "ripley's plan", "dallas's pr", "lambert's output", etc.
-  for (const agent of agentNames) {
-    const patterns = [
-      new RegExp(`${agent.name}(?:'s|s)?\\s+plan`, 'i'),
-      new RegExp(`${agent.id}(?:'s|s)?\\s+plan`, 'i'),
-      new RegExp(`plan\\s+(?:created|made|written|generated)\\s+by\\s+${agent.name}`, 'i'),
-      new RegExp(`plan\\s+(?:created|made|written|generated)\\s+by\\s+${agent.id}`, 'i'),
-    ];
-    const matchesPlan = patterns.some(p => p.test(text));
-    if (matchesPlan) {
-      // Find plans created by this agent (check work items for plan tasks dispatched to this agent)
-      try {
-        const plans = fs.readdirSync(path.join(MINIONS_DIR, 'plans')).filter(f => f.endsWith('.md') || f.endsWith('.json'));
-        // Check work-items to find which plan file this agent created
-        const workItems = safeJson(path.join(MINIONS_DIR, 'work-items.json')) || [];
-        const agentPlanItems = workItems.filter(w =>
-          w.type === 'plan' && w.dispatched_to === agent.id && w.status === 'done' && w._planFileName
-        ).sort((a, b) => (b.completedAt || '').localeCompare(a.completedAt || ''));
-
-        if (agentPlanItems.length > 0) {
-          const planFile = agentPlanItems[0]._planFileName;
-          const planPath = path.join(MINIONS_DIR, 'plans', planFile);
-          try {
-            const content = safeRead(planPath);
-            resolved.additionalContext += `\n\n## Referenced Plan: ${planFile} (created by ${agent.name})\n\n${content}`;
-            resolved.referencedFiles.push(planPath);
-            log('info', `Context resolution: found plan "${planFile}" by ${agent.name} for work item ${item.id}`);
-          } catch {}
-        } else if (plans.length > 0) {
-          // Fallback: try to find a plan file with the agent's name or ID in it
-          const match = plans.find(f => f.toLowerCase().includes(agent.id) || f.toLowerCase().includes(agent.name));
-          if (match) {
-            const planPath = path.join(MINIONS_DIR, 'plans', match);
-            try {
-              const content = safeRead(planPath);
-              resolved.additionalContext += `\n\n## Referenced Plan: ${match}\n\n${content}`;
-              resolved.referencedFiles.push(planPath);
-              log('info', `Context resolution: found plan "${match}" (name match) for work item ${item.id}`);
-            } catch {}
-          }
-        }
-      } catch {}
-    }
+// ─── Routing (extracted to engine/routing.js) ───────────────────────────────
 
-    // Match agent output/notes references
-    const outputPatterns = [
-      new RegExp(`${agent.name}(?:'s|s)?\\s+(?:output|findings|notes|results)`, 'i'),
-      new RegExp(`(?:output|findings|notes|results)\\s+(?:from|by)\\s+${agent.name}`, 'i'),
-    ];
-    if (outputPatterns.some(p => p.test(text))) {
-      // Find the agent's latest inbox notes
-      try {
-        const inboxDir = path.join(MINIONS_DIR, 'notes', 'inbox');
-        const files = fs.readdirSync(inboxDir)
-          .filter(f => f.startsWith(agent.id + '-'))
-          .sort().reverse();
-        if (files.length > 0) {
-          const content = safeRead(path.join(inboxDir, files[0]));
-          resolved.additionalContext += `\n\n## Referenced Notes by ${agent.name}: ${files[0]}\n\n${content.slice(0, 5000)}`;
-          resolved.referencedFiles.push(path.join(inboxDir, files[0]));
-          log('info', `Context resolution: found notes "${files[0]}" by ${agent.name} for work item ${item.id}`);
-        }
-      } catch {}
-    }
-  }
+const { getRouting, parseRoutingTable, getRoutingTableCached, getMonthlySpend,
+  getAgentErrorRate, isAgentIdle, resolveAgent, resetClaimedAgents,
+  tempAgents } = require('./engine/routing');
 
-  // If no specific reference was resolved but the text mentions "the plan" or "latest plan",
-  // find the most recent plan
-  if (!resolved.additionalContext && /\b(the|latest|last|recent)\s+plan\b/i.test(text)) {
-    try {
-      const plans = fs.readdirSync(path.join(MINIONS_DIR, 'plans'))
-        .filter(f => f.endsWith('.md') || f.endsWith('.json'))
-        .sort().reverse();
-      if (plans.length > 0) {
-        const planPath = path.join(MINIONS_DIR, 'plans', plans[0]);
-        const content = safeRead(planPath);
-        resolved.additionalContext += `\n\n## Referenced Plan (latest): ${plans[0]}\n\n${content}`;
-        resolved.referencedFiles.push(planPath);
-        log('info', `Context resolution: using latest plan "${plans[0]}" for work item ${item.id}`);
-      }
-    } catch {}
-  }
+// ─── Playbook, system prompt, agent context (extracted to engine/playbook.js) ─
 
-  return resolved;
-}
-
-// ─── Playbook Renderer ──────────────────────────────────────────────────────
-
-function renderPlaybook(type, vars) {
-  const pbPath = path.join(PLAYBOOKS_DIR, `${type}.md`);
-  let content;
-  try { content = fs.readFileSync(pbPath, 'utf8'); } catch {
-    log('warn', `Playbook not found: ${type}`);
-    return null;
-  }
-
-  // Inject pinned context (always visible to agents) — capped at 4KB
-  let pinnedContent = '';
-  try { pinnedContent = fs.readFileSync(path.join(MINIONS_DIR, 'pinned.md'), 'utf8'); } catch {}
-  if (pinnedContent) {
-    if (pinnedContent.length > 4096) pinnedContent = pinnedContent.slice(0, 4096) + '\n\n_...pinned.md truncated (read full file if needed)_';
-    content += '\n\n---\n\n## Pinned Context (CRITICAL — READ FIRST)\n\n' + pinnedContent;
-  }
-
-  // Inject team notes (single injection point — not in buildAgentContext) — capped at 8KB
-  let notes = getNotes();
-  if (notes) {
-    if (notes.length > 8192) {
-      const sections = notes.split(/(?=^### )/m);
-      const recent = sections.slice(-10).join('');
-      notes = recent.length > 8192 ? recent.slice(0, 8192) + '\n\n_...notes truncated_' : recent;
-      notes += '\n\n_' + Math.max(0, sections.length - 10) + ' older entries in `notes.md` — Read if needed._';
-    }
-    content += '\n\n---\n\n## Team Notes (MUST READ)\n\n' + notes;
-  }
-
-  // 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`;
-
-  // Inject learnings requirement
-  content += `\n\n---\n\n## REQUIRED: Write Learnings\n\n`;
-  content += `After completing your task, you MUST write a findings/learnings file to:\n`;
-  content += `\`${MINIONS_DIR}/notes/inbox/${vars.agent_id || 'agent'}-${dateStamp()}.md\`\n\n`;
-  content += `Include:\n`;
-  content += `- What you learned about the codebase\n`;
-  content += `- Patterns you discovered or established\n`;
-  content += `- Gotchas or warnings for future agents\n`;
-  content += `- Conventions to follow\n`;
-  content += `- **SOURCE REFERENCES for every finding** — file paths with line numbers, PR URLs, API endpoints, config keys. Format: \`(source: path/to/file.ts:42)\` or \`(source: PR-12345)\`. Without references, findings cannot be verified.\n\n`;
-  content += `### Skill Extraction (IMPORTANT)\n\n`;
-  content += `If during this task you discovered a **repeatable workflow** — a multi-step procedure, workaround, build process, or pattern that other agents should follow in similar situations — output it as a fenced skill block. The engine will automatically extract it.\n\n`;
-  content += `Format your skill as a fenced code block with the \`skill\` language tag:\n\n`;
-  content += '````\n```skill\n';
-  content += `---\nname: short-descriptive-name\ndescription: One-line description of what this skill does\nallowed-tools: Bash, Read, Edit\ntrigger: when should an agent use this\nscope: minions\nproject: any\n---\n\n# Skill Title\n\n## Steps\n1. ...\n2. ...\n\n## Notes\n...\n`;
-  content += '```\n````\n\n';
-  content += `- Set \`scope: minions\` for cross-project skills (engine writes to ~/.claude/skills/ automatically)\n`;
-  content += `- Set \`scope: project\` + \`project: <name>\` for repo-specific skills (engine queues a PR to <project>/.claude/skills/)\n`;
-  content += `- Only output a skill block if you genuinely discovered something reusable — don't force it\n`;
-
-  // Inject project-level variables from config
-  const config = getConfig();
-  const projects = getProjects(config);
-  // Find the specific project being dispatched (match by repo_id or repo_name from vars)
-  const dispatchProject = (vars.repo_id && projects.find(p => p.repositoryId === vars.repo_id))
-    || (vars.repo_name && projects.find(p => p.repoName === vars.repo_name))
-    || projects[0] || {};
-  const projectVars = {
-    project_name: dispatchProject.name || 'Unknown Project',
-    ado_org: dispatchProject.adoOrg || 'Unknown',
-    ado_project: dispatchProject.adoProject || 'Unknown',
-    repo_name: dispatchProject.repoName || 'Unknown',
-    pr_create_instructions: getPrCreateInstructions(dispatchProject),
-    pr_comment_instructions: getPrCommentInstructions(dispatchProject),
-    pr_fetch_instructions: getPrFetchInstructions(dispatchProject),
-    pr_vote_instructions: getPrVoteInstructions(dispatchProject),
-    repo_host_label: getRepoHostLabel(dispatchProject),
-  };
-  const allVars = { ...projectVars, ...vars };
-
-  // Substitute variables
-  for (const [key, val] of Object.entries(allVars)) {
-    content = content.replace(new RegExp(`\\{\\{${key}\\}\\}`, 'g'), String(val));
-  }
-
-  return content;
-}
-
-// ─── Repo Host Helpers ──────────────────────────────────────────────────────
-
-function getRepoHost(project) {
-  return project?.repoHost || 'ado';
-}
-
-function getPrCreateInstructions(project) {
-  const host = getRepoHost(project);
-  const repoId = project?.repositoryId || '';
-  if (host === 'github') {
-    const org = project?.adoOrg || '';
-    const repo = project?.repoName || '';
-    const mainBranch = project?.mainBranch || 'main';
-    return `Use \`gh pr create\` to create a pull request:\n` +
-      `- \`gh pr create --base ${mainBranch} --head <your-branch> --title "PR title" --body "PR description" --repo ${org}/${repo}\`\n` +
-      `- Always set --base to \`${mainBranch}\` (the main branch)\n` +
-      `- Always set --repo to \`${org}/${repo}\` to target the correct repository\n` +
-      `- Use --head to specify your feature branch name\n` +
-      `- Include a meaningful --title and --body describing the changes`;
-  }
-  // Default: Azure DevOps
-  return `Use \`mcp__azure-ado__repo_create_pull_request\`:\n- repositoryId: \`${repoId}\``;
-}
-
-function getPrCommentInstructions(project) {
-  const host = getRepoHost(project);
-  const repoId = project?.repositoryId || '';
-  if (host === 'github') {
-    const org = project?.adoOrg || '';
-    const repo = project?.repoName || '';
-    return `Use \`gh pr comment\` to post a comment on the PR:\n` +
-      `- \`gh pr comment <number> --body "Your comment text" --repo ${org}/${repo}\`\n` +
-      `- Replace <number> with the PR number\n` +
-      `- Always set --repo to \`${org}/${repo}\` to target the correct repository\n` +
-      `- Use --body to provide the comment text (supports Markdown)`;
-  }
-  return `Use \`mcp__azure-ado__repo_create_pull_request_thread\`:\n- repositoryId: \`${repoId}\``;
-}
-
-function getPrFetchInstructions(project) {
-  const host = getRepoHost(project);
-  if (host === 'github') {
-    const org = project?.adoOrg || '';
-    const repo = project?.repoName || '';
-    const mainBranch = project?.mainBranch || 'main';
-    return `Use \`gh pr view\` to fetch PR status:\n` +
-      `- \`gh pr view <number> --json number,title,state,mergeable,reviewDecision,headRefName,baseRefName,statusCheckRollup --repo ${org}/${repo}\`\n` +
-      `- This returns JSON with PR state, mergeability, review decision, and check statuses\n` +
-      `- To fetch the PR branch locally:\n` +
-      `  1. \`git fetch origin <branch-name>\`\n` +
-      `  2. \`git checkout <branch-name>\`\n` +
-      `- Or use \`gh pr checkout <number> --repo ${org}/${repo}\` to fetch and checkout in one step\n` +
-      `- The base branch is \`${mainBranch}\``;
-  }
-  return `Use \`mcp__azure-ado__repo_get_pull_request_by_id\` to fetch PR status.`;
-}
-
-function getPrVoteInstructions(project) {
-  const host = getRepoHost(project);
-  const repoId = project?.repositoryId || '';
-  if (host === 'github') {
-    const org = project?.adoOrg || '';
-    const repo = project?.repoName || '';
-    return `Use \`gh pr review\` to submit a review on the PR:\n` +
-      `- Approve: \`gh pr review <number> --approve --body "Approval comment" --repo ${org}/${repo}\`\n` +
-      `- Request changes: \`gh pr review <number> --request-changes --body "What needs to change" --repo ${org}/${repo}\`\n` +
-      `- Comment only: \`gh pr review <number> --comment --body "Review comment" --repo ${org}/${repo}\`\n` +
-      `- Replace <number> with the PR number\n` +
-      `- Always set --repo to \`${org}/${repo}\` to target the correct repository\n` +
-      `- Use --body to provide a review summary (supports Markdown)`;
-  }
-  return `Use \`mcp__azure-ado__repo_update_pull_request_reviewers\`:\n- repositoryId: \`${repoId}\`\n- Set your reviewer vote on the PR (10=approve, 5=approve-with-suggestions, -10=reject)`;
-}
-
-function getRepoHostLabel(project) {
-  const host = getRepoHost(project);
-  if (host === 'github') return 'GitHub';
-  return 'Azure DevOps';
-}
-
-function getRepoHostToolRule(project) {
-  const host = getRepoHost(project);
-  if (host === 'github') return 'Use GitHub MCP tools or `gh` CLI for PR operations';
-  return 'Use Azure DevOps MCP tools (mcp__azure-ado__*) for PR operations — NEVER use gh CLI';
-}
-
-// ─── System Prompt Builder ──────────────────────────────────────────────────
-
-// Lean system prompt: agent identity + rules only (~2-4KB, never grows)
-function buildSystemPrompt(agentId, config, project) {
-  const agent = config.agents[agentId] || tempAgents.get(agentId) || { name: agentId, role: 'Temporary Agent', skills: [] };
-  const charter = getAgentCharter(agentId); // returns '' for temp agents (no charter file)
-  project = project || getProjects(config)[0] || {};
-
-  let prompt = '';
-
-  // Agent identity
-  prompt += `# You are ${agent.name} (${agent.role})\n\n`;
-  prompt += `Agent ID: ${agentId}\n`;
-  prompt += `Skills: ${(agent.skills || []).join(', ')}\n\n`;
-
-  // Charter (detailed instructions — typically 1-2KB)
-  if (charter) {
-    prompt += `## Your Charter\n\n${charter}\n\n`;
-  }
-
-  // Project context (fixed size)
-  prompt += `## Project: ${project.name || 'Unknown Project'}\n\n`;
-  prompt += `- Repo: ${project.repoName || 'Unknown'} (${project.adoOrg || 'Unknown'}/${project.adoProject || 'Unknown'})\n`;
-  prompt += `- Repo ID: ${project.repositoryId || ''}\n`;
-  prompt += `- Repo host: ${getRepoHostLabel(project)}\n`;
-  prompt += `- Main branch: ${project.mainBranch || 'main'}\n\n`;
-
-  // Critical rules (fixed size)
-  prompt += `## Critical Rules\n\n`;
-  prompt += `1. Use git worktrees — NEVER checkout on main working tree\n`;
-  prompt += `2. ${getRepoHostToolRule(project)}\n`;
-  prompt += `3. Follow the project conventions in CLAUDE.md if present\n`;
-  prompt += `4. Write learnings to: ${MINIONS_DIR}/notes/inbox/${agentId}-${dateStamp()}.md\n`;
-  prompt += `5. Agent status is managed by the engine via dispatch.json — agents do not need to track their own status\n`;
-  prompt += `6. If you discover a repeatable workflow, output it as a \\\`\\\`\\\`skill fenced block — the engine auto-extracts it to ~/.claude/skills/\n\n`;
-
-  return prompt;
-}
-
-// Bulk context: history, notes, conventions, skills — prepended to user/task prompt.
-// This is the content that grows over time and would bloat the system prompt.
-function buildAgentContext(agentId, config, project) {
-  project = project || getProjects(config)[0] || {};
-  let context = '';
-
-  // Agent history — last 5 tasks only (keeps it relevant, avoids 37KB dumps)
-  const history = safeRead(path.join(AGENTS_DIR, agentId, 'history.md'));
-  if (history && history.trim() !== '# Agent History') {
-    const entries = history.split(/(?=^### )/m);
-    const header = entries[0].startsWith('#') && !entries[0].startsWith('### ') ? entries.shift() : '';
-    const recent = entries.slice(-5);
-    const trimmed = (header ? header + '\n' : '') + recent.join('');
-    context += `## Your Recent History (last 5 tasks)\n\n${trimmed}\n\n`;
-  }
-
-  // Project conventions (from CLAUDE.md) — always relevant for code quality
-  if (project.localPath) {
-    const claudeMd = safeRead(path.join(project.localPath, 'CLAUDE.md'));
-    if (claudeMd && claudeMd.trim()) {
-      const truncated = claudeMd.length > 8192 ? claudeMd.slice(0, 8192) + '\n\n...(truncated)' : claudeMd;
-      context += `## Project Conventions (from CLAUDE.md)\n\n${truncated}\n\n`;
-    }
-  }
-
-  // KB and skills: NOT injected — agents can Glob/Read when needed
-  // This saves ~27KB per dispatch. Reference note so agents know they exist:
-  context += `## Reference Files\n\nKnowledge base entries are in \`knowledge/{category}/*.md\`. Skills are in \`skills/*.md\` and \`.claude/skills/\`. Use Glob/Read to browse when relevant.\n\n`;
-
-  // Minions awareness: what's in flight, who's doing what
-  const dispatch = getDispatch();
-  const activeItems = (dispatch.active || []).map(d =>
-    `- **${d.agent}**: ${d.type} — ${(d.task || '').slice(0, 100)}${d.agent === agentId ? ' ← (you)' : ''}`
-  );
-  if (activeItems.length > 0) {
-    context += `## Active Agents\n\n${activeItems.join('\n')}\n\n`;
-  }
-
-  // Recent completions (last 5, not 10)
-  const recentCompleted = (dispatch.completed || []).slice(-5).reverse().map(d =>
-    `- **${d.agent}** ${d.result === 'success' ? 'completed' : 'failed'}: ${(d.task || '').slice(0, 80)}${d.resultSummary ? ' — ' + d.resultSummary.slice(0, 100) : ''}`
-  );
-  if (recentCompleted.length > 0) {
-    context += `## Recently Completed\n\n${recentCompleted.join('\n')}\n\n`;
-  }
-
-  // Active + linked PRs across projects — coordination awareness
-  const projects = getProjects(config);
-  const allPrs = [];
-  for (const p of projects) {
-    const prs = getPrs(p).filter(pr => pr.status === 'active' || pr.status === 'linked');
-    for (const pr of prs) allPrs.push({ ...pr, _project: p.name });
-  }
-  // Also check central pull-requests.json
-  try {
-    const centralPrs = safeJson(path.join(MINIONS_DIR, 'pull-requests.json')) || [];
-    for (const pr of centralPrs.filter(pr => pr.status === 'active' || pr.status === 'linked')) {
-      if (!allPrs.some(p => p.id === pr.id)) allPrs.push({ ...pr, _project: 'central' });
-    }
-  } catch {}
-  if (allPrs.length > 0) {
-    const prLines = allPrs.map(pr =>
-      `- **${pr.id}** (${pr._project}): ${(pr.title || '').slice(0, 80)} [${pr.status === 'linked' ? 'context-only' : (pr.reviewStatus || 'pending')}${pr.buildStatus === 'failing' ? ', BUILD FAILING' : ''}]${pr.branch ? ' branch: `' + pr.branch + '`' : ''}${pr._context ? ' — ' + pr._context.slice(0, 100) : ''}`
-    );
-    context += `## Active Pull Requests\n\n${prLines.join('\n')}\n\n`;
-  }
-
-  // Pending work items
-  const pendingItems = (dispatch.pending || []).slice(0, 10).map(d =>
-    `- ${d.type}: ${(d.task || '').slice(0, 80)}`
-  );
-  if (pendingItems.length > 0) {
-    context += `## Pending Work Queue (${(dispatch.pending || []).length} items)\n\n${pendingItems.join('\n')}${(dispatch.pending || []).length > 10 ? '\n- ... and ' + ((dispatch.pending || []).length - 10) + ' more' : ''}\n\n`;
-  }
-
-  // Team notes injected via renderPlaybook (single injection point, with truncation)
-  // Not duplicated here to avoid double-injection and token waste
-
-  return context;
-}
+const { renderPlaybook, buildSystemPrompt, buildAgentContext, selectPlaybook,
+  buildBaseVars, buildPrDispatch, resolveTaskContext,
+  getRepoHostLabel, getRepoHostToolRule } = require('./engine/playbook');
 
 // sanitizeBranch imported from shared.js
 
@@ -645,7 +146,7 @@ const { runPostCompletionHooks, updateWorkItemStatus, syncPrdItemStatus, handleP
 // ─── Agent Spawner ──────────────────────────────────────────────────────────
 
 const activeProcesses = new Map(); // dispatchId → { proc, agentId, startedAt }
-const tempAgents = new Map(); // tempAgentId → { name, role, createdAt }
+// tempAgents imported from engine/routing.js
 let engineRestartGraceUntil = 0; // timestamp — suppress orphan detection until this time
 
 // Resolve dependency plan item IDs to their PR branches
@@ -703,7 +204,7 @@ function findExistingWorktree(repoDir, branchName) {
         }
       }
     }
-  } catch {}
+  } catch (e) { log('warn', 'git: ' + e.message); }
   return null;
 }
 
@@ -727,7 +228,7 @@ function removeStaleIndexLock(rootDir) {
         log('warn', `Removed stale index.lock (${Math.round(age / 1000)}s old) in ${rootDir}`);
       }
     }
-  } catch {}
+  } catch (e) { log('warn', 'git: ' + e.message); }
 }
 
 function runWorktreeAdd(rootDir, worktreePath, args, gitOpts, worktreeCreateRetries) {
@@ -736,7 +237,7 @@ function runWorktreeAdd(rootDir, worktreePath, args, gitOpts, worktreeCreateRetr
   for (let attempt = 0; attempt <= retries; attempt++) {
     try {
       if (attempt > 0) {
-        try { exec('git worktree prune', { ...gitOpts, cwd: rootDir, timeout: 15000 }); } catch {}
+        try { exec('git worktree prune', { ...gitOpts, cwd: rootDir, timeout: 15000 }); } catch (e) { log('warn', 'git: ' + e.message); }
         removeStaleIndexLock(rootDir);
         log('warn', `Retrying git worktree add (attempt ${attempt + 1}/${retries + 1}) for ${path.basename(worktreePath)}`);
       }
@@ -795,8 +296,8 @@ function spawnAgent(dispatchItem, config) {
     if (existingWt) {
       worktreePath = existingWt;
       log('info', `Reusing existing worktree for ${branchName}: ${existingWt}`);
-      try { exec(`git fetch origin "${branchName}"`, { ..._gitOpts, cwd: rootDir }); } catch {}
-      try { exec(`git pull origin "${branchName}"`, { ..._gitOpts, cwd: existingWt }); } catch {}
+      try { exec(`git fetch origin "${branchName}"`, { ..._gitOpts, cwd: rootDir }); } catch (e) { log('warn', 'git: ' + e.message); }
+      try { exec(`git pull origin "${branchName}"`, { ..._gitOpts, cwd: existingWt }); } catch (e) { log('warn', 'git: ' + e.message); }
     } else if (type !== 'implement') {
       // Only implement tasks may create new worktrees.
       // Other task types are reuse-only: if no existing worktree, run in rootDir.
@@ -808,13 +309,13 @@ function spawnAgent(dispatchItem, config) {
         if (!fs.existsSync(worktreePath)) {
           const isSharedBranch = meta?.branchStrategy === 'shared-branch' || meta?.useExistingBranch;
           // Prune stale worktree entries before creating (handles leftover entries from crashed runs)
-          try { exec(`git worktree prune`, { ..._gitOpts, cwd: rootDir, timeout: 10000 }); } catch {}
+          try { exec(`git worktree prune`, { ..._gitOpts, cwd: rootDir, timeout: 10000 }); } catch (e) { log('warn', 'git: ' + e.message); }
           // Remove stale index.lock before creating worktree (Windows crashes can leave this behind)
           removeStaleIndexLock(rootDir);
 
           if (isSharedBranch) {
             log('info', `Creating worktree for shared branch: ${worktreePath} on ${branchName}`);
-            try { exec(`git fetch origin "${branchName}"`, { ..._gitOpts, cwd: rootDir }); } catch {}
+            try { exec(`git fetch origin "${branchName}"`, { ..._gitOpts, cwd: rootDir }); } catch (e) { log('warn', 'git: ' + e.message); }
             try {
               runWorktreeAdd(rootDir, worktreePath, `"${branchName}"`, _worktreeGitOpts, worktreeCreateRetries);
             } catch (eShared) {
@@ -832,7 +333,7 @@ function spawnAgent(dispatchItem, config) {
               runWorktreeAdd(rootDir, worktreePath, `-b "${branchName}" ${sanitizeBranch(project.mainBranch || 'main')}`, _worktreeGitOpts, worktreeCreateRetries);
             } catch (e1) {
               // Branch already exists or checked out elsewhere — try without -b
-              try { exec(`git fetch origin "${branchName}"`, { ..._gitOpts, cwd: rootDir }); } catch {}
+              try { exec(`git fetch origin "${branchName}"`, { ..._gitOpts, cwd: rootDir }); } catch (e) { log('warn', 'git: ' + e.message); }
               try {
                 runWorktreeAdd(rootDir, worktreePath, `"${branchName}"`, _worktreeGitOpts, worktreeCreateRetries);
                 log('info', `Reusing existing branch: ${branchName}`);
@@ -859,12 +360,12 @@ function spawnAgent(dispatchItem, config) {
                   } else if (existingWtPath && !fs.existsSync(existingWtPath)) {
                     // Directory gone but git still tracks it — prune and recreate
                     log('warn', `Branch ${branchName} tracked in missing dir ${existingWtPath} — pruning and recreating`);
-                    try { exec(`git worktree prune`, { ..._gitOpts, cwd: rootDir, timeout: 10000 }); } catch {}
+                    try { exec(`git worktree prune`, { ..._gitOpts, cwd: rootDir, timeout: 10000 }); } catch (e) { log('warn', 'git: ' + e.message); }
                     runWorktreeAdd(rootDir, worktreePath, `"${branchName}"`, _worktreeGitOpts, worktreeCreateRetries);
                     log('info', `Recovered worktree for ${branchName} after stale entry prune`);
                   } else {
                     // Can't find the worktree at all — prune and retry
-                    try { exec(`git worktree prune`, { ..._gitOpts, cwd: rootDir, timeout: 10000 }); } catch {}
+                    try { exec(`git worktree prune`, { ..._gitOpts, cwd: rootDir, timeout: 10000 }); } catch (e) { log('warn', 'git: ' + e.message); }
                     runWorktreeAdd(rootDir, worktreePath, `"${branchName}"`, _worktreeGitOpts, worktreeCreateRetries);
                   }
                 } else {
@@ -875,7 +376,7 @@ function spawnAgent(dispatchItem, config) {
           }
         } else if (meta?.branchStrategy === 'shared-branch') {
           log('info', `Pulling latest on shared branch ${branchName}`);
-          try { exec(`git pull origin "${branchName}"`, { ..._gitOpts, cwd: worktreePath }); } catch {}
+          try { exec(`git pull origin "${branchName}"`, { ..._gitOpts, cwd: worktreePath }); } catch (e) { log('warn', 'git: ' + e.message); }
         }
       } catch (err) {
         if (recoverPartialWorktree(rootDir, worktreePath, branchName, _gitOpts)) {
@@ -956,7 +457,7 @@ function spawnAgent(dispatchItem, config) {
           log('info', `Resuming session ${sessionFile.sessionId} for ${agentId} on branch ${branchName} (age: ${Math.round(sessionAge / 60000)}min)`);
         }
       }
-    } catch {}
+    } catch (e) { log('warn', 'session resume lookup: ' + e.message); }
   }
 
   // MCP servers: agents inherit from ~/.claude.json directly as Claude Code processes.
@@ -997,14 +498,14 @@ function spawnAgent(dispatchItem, config) {
     const silentMs = Date.now() - lastOutputAt;
     if (silentMs < 30000) return;
     const silentSec = Math.round(silentMs / 1000);
-    try { fs.appendFileSync(liveOutputPath, `[heartbeat] running — no output for ${silentSec}s\n`); } catch {}
+    try { fs.appendFileSync(liveOutputPath, `[heartbeat] running — no output for ${silentSec}s\n`); } catch { /* optional */ }
   }, 30000);
 
   proc.stdout.on('data', (data) => {
     const chunk = data.toString();
     lastOutputAt = Date.now();
     if (stdout.length < MAX_OUTPUT) stdout += chunk.slice(0, MAX_OUTPUT - stdout.length);
-    try { fs.appendFileSync(liveOutputPath, chunk); } catch {}
+    try { fs.appendFileSync(liveOutputPath, chunk); } catch { /* optional */ }
 
     // Capture sessionId early for mid-session steering
     const procInfo = activeProcesses.get(id);
@@ -1021,7 +522,7 @@ function spawnAgent(dispatchItem, config) {
             break;
           }
         }
-      } catch {}
+      } catch { /* JSON parse — output may not be valid JSON */ }
     }
   });
 
@@ -1029,7 +530,7 @@ function spawnAgent(dispatchItem, config) {
     const chunk = data.toString();
     lastOutputAt = Date.now();
     if (stderr.length < MAX_OUTPUT) stderr += chunk.slice(0, MAX_OUTPUT - stderr.length);
-    try { fs.appendFileSync(liveOutputPath, '[stderr] ' + chunk); } catch {}
+    try { fs.appendFileSync(liveOutputPath, '[stderr] ' + chunk); } catch { /* optional */ }
   });
 
   function onAgentClose(code) {
@@ -1077,13 +578,13 @@ function spawnAgent(dispatchItem, config) {
         const chunk = data.toString();
         lastOutputAt = Date.now();
         if (stdout.length < MAX_OUTPUT) stdout += chunk.slice(0, MAX_OUTPUT - stdout.length);
-        try { fs.appendFileSync(liveOutputPath, chunk); } catch {}
+        try { fs.appendFileSync(liveOutputPath, chunk); } catch { /* optional */ }
       });
       resumeProc.stderr.on('data', (data) => {
         const chunk = data.toString();
         lastOutputAt = Date.now();
         if (stderr.length < MAX_OUTPUT) stderr += chunk.slice(0, MAX_OUTPUT - stderr.length);
-        try { fs.appendFileSync(liveOutputPath, '[stderr] ' + chunk); } catch {}
+        try { fs.appendFileSync(liveOutputPath, '[stderr] ' + chunk); } catch { /* optional */ }
       });
 
       // Re-wire close handler for the resumed process
@@ -1106,9 +607,9 @@ function spawnAgent(dispatchItem, config) {
     const stillActive = (dispatchNow.active || []).some(d => d.id === id);
     if (!stillActive) {
       log('info', `Agent ${agentId} (${id}) close event ignored — dispatch already completed elsewhere`);
-      try { fs.unlinkSync(sysPromptPath); } catch {}
-      try { fs.unlinkSync(promptPath); } catch {}
-      try { fs.unlinkSync(promptPath.replace(/prompt-/, 'pid-').replace(/\.md$/, '.pid')); } catch {}
+      try { fs.unlinkSync(sysPromptPath); } catch { /* cleanup */ }
+      try { fs.unlinkSync(promptPath); } catch { /* cleanup */ }
+      try { fs.unlinkSync(promptPath.replace(/prompt-/, 'pid-').replace(/\.md$/, '.pid')); } catch { /* cleanup */ }
       return;
     }
 
@@ -1124,9 +625,9 @@ function spawnAgent(dispatchItem, config) {
       const errMsg = stderr.includes('claude-code') ? stderr.trim() : 'Configuration error — Claude Code CLI not found. Install with: npm install -g @anthropic-ai/claude-code';
       log('error', `Agent ${agentId} (${id}) failed: ${errMsg}`);
       completeDispatch(id, 'error', errMsg, '');
-      try { fs.unlinkSync(sysPromptPath); } catch {}
-      try { fs.unlinkSync(promptPath); } catch {}
-      try { fs.unlinkSync(promptPath.replace(/prompt-/, 'pid-').replace(/\.md$/, '.pid')); } catch {}
+      try { fs.unlinkSync(sysPromptPath); } catch { /* cleanup */ }
+      try { fs.unlinkSync(promptPath); } catch { /* cleanup */ }
+      try { fs.unlinkSync(promptPath.replace(/prompt-/, 'pid-').replace(/\.md$/, '.pid')); } catch { /* cleanup */ }
       return;
     }
 
@@ -1137,9 +638,9 @@ function spawnAgent(dispatchItem, config) {
     completeDispatch(id, code === 0 ? 'success' : 'error', '', resultSummary);
 
     // Cleanup temp files (including PID file now that dispatch is complete)
-    try { fs.unlinkSync(sysPromptPath); } catch {}
-    try { fs.unlinkSync(promptPath); } catch {}
-    try { fs.unlinkSync(promptPath.replace(/prompt-/, 'pid-').replace(/\.md$/, '.pid')); } catch {}
+    try { fs.unlinkSync(sysPromptPath); } catch { /* cleanup */ }
+    try { fs.unlinkSync(promptPath); } catch { /* cleanup */ }
+    try { fs.unlinkSync(promptPath.replace(/prompt-/, 'pid-').replace(/\.md$/, '.pid')); } catch { /* cleanup */ }
 
     log('info', `Agent ${agentId} completed. Output saved to ${archivePath}`);
 
@@ -1151,7 +652,7 @@ function spawnAgent(dispatchItem, config) {
         // Keep output archive but remove temp agent directory (live-output.log etc.)
         fs.rmSync(agentDir, { recursive: true, force: true });
         log('info', `Temp agent ${agentId} cleaned up`);
-      } catch {}
+      } catch { /* cleanup */ }
     }
   }
 
@@ -1287,7 +788,7 @@ function completeDispatch(id, result = 'success', reason = '', resultSummary = '
           const wi = items.find(i => i.id === item.meta.item.id);
           if (wi) retries = wi._retryCount || 0;
         }
-      } catch {}
+      } catch (e) { log('warn', 'read retry count: ' + e.message); }
       if (retryableFailure && retries < 3) {
         log('info', `Dispatch error for ${item.meta.item.id} — auto-retry ${retries + 1}/3`);
         updateWorkItemStatus(item.meta, 'pending', '');
@@ -1298,7 +799,7 @@ function completeDispatch(id, result = 'success', reason = '', resultSummary = '
               dp.completed = Array.isArray(dp.completed) ? dp.completed.filter(d => d.meta?.dispatchKey !== item.meta.dispatchKey) : [];
               return dp;
             });
-          } catch {}
+          } catch (e) { log('warn', 'clear dispatch for retry: ' + e.message); }
         }
         // Increment retry counter on the source work item
         try {
@@ -1320,7 +821,7 @@ function completeDispatch(id, result = 'success', reason = '', resultSummary = '
               safeWrite(wiPath, items);
             }
           }
-        } catch {}
+        } catch (e) { log('warn', 'increment retry counter: ' + e.message); }
       } else {
         const finalReason = !retryableFailure
           ? `Non-retryable failure: ${reason || 'Unknown error'}`
@@ -1349,7 +850,7 @@ function completeDispatch(id, result = 'success', reason = '', resultSummary = '
                 `These items cannot dispatch until \`${failedId}\` is fixed and reset to \`pending\`.\n`
               : `No downstream items are blocked.\n`)
           );
-        } catch {}
+        } catch (e) { log('warn', 'write failure alert: ' + e.message); }
       }
     }
   }
@@ -1370,7 +871,7 @@ function areDependenciesMet(item, config) {
     try {
       const wi = safeJson(projectWorkItemsPath(p)) || [];
       allWorkItems = allWorkItems.concat(wi);
-    } catch {}
+    } catch (e) { log('warn', 'read project work items for deps: ' + e.message); }
   }
   // PRD item statuses that count as "done" for dep resolution
   const PRD_MET_STATUSES = new Set(['done', 'in-pr', 'implemented', 'complete']);
@@ -1383,7 +884,7 @@ function areDependenciesMet(item, config) {
         const plan = safeJson(path.join(PRD_DIR, sourcePlan));
         const prdItem = (plan?.missing_features || []).find(f => f.id === depId);
         if (prdItem && PRD_MET_STATUSES.has(prdItem.status)) continue; // PRD says done — treat as met
-      } catch {}
+      } catch (e) { log('warn', 'check PRD dep status: ' + e.message); }
       log('warn', `Dependency ${depId} not found for ${item.id} (plan: ${sourcePlan}) — treating as unmet`);
       return false;
     }
@@ -1419,7 +920,7 @@ function writeInboxAlert(slug, content) {
     const existing = safeReadDir(INBOX_DIR).find(f => f.startsWith(`engine-alert-${slug}-${dateStamp()}`));
     if (existing) return;
     safeWrite(file, content);
-  } catch {}
+  } catch (e) { log('warn', 'write inbox alert: ' + e.message); }
 }
 
 // Reconciles work items against known PRs.
@@ -1526,7 +1027,7 @@ function checkSteering(config) {
     if (!fs.existsSync(steerPath)) continue;
 
     const message = safeRead(steerPath);
-    try { fs.unlinkSync(steerPath); } catch {}
+    try { fs.unlinkSync(steerPath); } catch { /* cleanup */ }
     if (!message) continue;
 
     const sessionId = info.sessionId;
@@ -1538,7 +1039,7 @@ function checkSteering(config) {
     log('info', `Steering: killing ${info.agentId} (${id}) for session resume with human message`);
 
     // Kill current process
-    try { info.proc.kill('SIGTERM'); } catch {}
+    try { info.proc.kill('SIGTERM'); } catch { /* process may be dead */ }
 
     // Store steering context for re-spawn on close
     info._steeringMessage = message;
@@ -1558,9 +1059,9 @@ function checkTimeouts(config) {
     const elapsed = Date.now() - new Date(info.startedAt).getTime();
     if (elapsed > itemTimeout) {
       log('warn', `Agent ${info.agentId} (${id}) hit hard timeout after ${Math.round(elapsed / 1000)}s — killing`);
-      try { info.proc.kill('SIGTERM'); } catch {}
+      try { info.proc.kill('SIGTERM'); } catch { /* process may be dead */ }
       setTimeout(() => {
-        try { info.proc.kill('SIGKILL'); } catch {}
+        try { info.proc.kill('SIGKILL'); } catch { /* process may be dead */ }
       }, 5000);
     }
   }
@@ -1581,7 +1082,7 @@ function checkTimeouts(config) {
     try {
       const stat = fs.statSync(liveLogPath);
       lastActivity = Math.max(lastActivity, stat.mtimeMs);
-    } catch {}
+    } catch { /* optional */ }
 
     const silentMs = Date.now() - lastActivity;
     const silentSec = Math.round(silentMs / 1000);
@@ -1605,7 +1106,7 @@ function checkTimeouts(config) {
             const result = JSON.parse(resultLine);
             safeWrite(outputLogPath, `# Output for dispatch ${item.id}\n# Exit code: ${isSuccess ? 0 : 1}\n# Completed: ${ts()}\n# Detected via output scan\n\n## Result\n${result.result || '(no text)'}\n`);
           }
-        } catch {}
+        } catch (e) { log('warn', 'parse output result: ' + e.message); }
 
         completeDispatch(item.id, isSuccess ? 'success' : 'error', 'Completed (detected from output)');
 
@@ -1613,12 +1114,12 @@ function checkTimeouts(config) {
         runPostCompletionHooks(item, item.agent, isSuccess ? 0 : 1, liveLog, config);
 
         if (hasProcess) {
-          try { activeProcesses.get(item.id)?.proc.kill('SIGTERM'); } catch {}
+          try { activeProcesses.get(item.id)?.proc.kill('SIGTERM'); } catch { /* process may be dead */ }
           activeProcesses.delete(item.id);
         }
         continue; // Skip orphan/hung detection — we handled it
       }
-    } catch {}
+    } catch (e) { log('warn', 'output completion detection: ' + e.message); }
 
     // Check if agent is in a blocking tool call (TaskOutput block:true, Bash with long timeout, etc.)
     // These tools produce no stdout for extended periods — don't kill them prematurely
@@ -1652,13 +1153,13 @@ function checkTimeouts(config) {
                 isBlocking = true;
               }
               break; // only check the most recent tool_use
-            } catch {}
+            } catch { /* JSON parse — line may not be valid JSON */ }
           }
           if (isBlocking) {
             log('info', `Agent ${item.agent} (${item.id}) is in a blocking tool call — extended timeout to ${Math.round(blockingTimeout / 1000)}s (silent for ${silentSec}s)`);
           }
         }
-      } catch {}
+      } catch (e) { log('warn', 'blocking tool detection: ' + e.message); }
     }
 
     const effectiveTimeout = isBlocking ? blockingTimeout : heartbeatTimeout;
@@ -1672,8 +1173,8 @@ function checkTimeouts(config) {
       log('warn', `Hung agent: ${item.agent} (${item.id}) — process exists but no output for ${silentSec}s${isBlocking ? ' (blocking timeout exceeded)' : ''}`);
       const procInfo = activeProcesses.get(item.id);
       if (procInfo) {
-        try { procInfo.proc.kill('SIGTERM'); } catch {}
-        setTimeout(() => { try { procInfo.proc.kill('SIGKILL'); } catch {} }, 5000);
+        try { procInfo.proc.kill('SIGTERM'); } catch { /* process may be dead */ }
+        setTimeout(() => { try { procInfo.proc.kill('SIGKILL'); } catch { /* process may be dead */ } }, 5000);
         activeProcesses.delete(item.id);
       }
       deadItems.push({ item, reason: `Hung — no output for ${silentSec}s` });
@@ -1752,11 +1253,11 @@ function runCleanup(config, verbose = false) {
               fs.unlinkSync(fp);
               cleaned.tempFiles++;
             }
-          } catch {}
+          } catch { /* cleanup */ }
         }
       }
     }
-  } catch {}
+  } catch (e) { log('warn', 'cleanup temp files: ' + e.message); }
 
   // 2. Clean live-output.log for idle agents (not currently working)
   for (const [agentId] of Object.entries(config.agents || {})) {
@@ -1770,7 +1271,7 @@ function runCleanup(config, verbose = false) {
             fs.unlinkSync(livePath);
             cleaned.liveOutputs++;
           }
-        } catch {}
+        } catch { /* cleanup */ }
       }
     }
   }
@@ -1835,7 +1336,7 @@ function runCleanup(config, verbose = false) {
             if (ageMs > 7200000 && !isReferenced) { // 2 hours
               shouldClean = true;
             }
-          } catch {}
+          } catch { /* optional */ }
         }
 
         // Skip worktrees for active shared-branch plans (check both prd/ and plans/ for .json PRDs)
@@ -1859,7 +1360,7 @@ function runCleanup(config, verbose = false) {
               }
               if (isProtected) break;
             }
-          } catch {}
+          } catch (e) { log('warn', 'check shared-branch protection: ' + e.message); }
         }
 
         wtEntries.push({ dir, wtPath, mtime, shouldClean, isProtected });
@@ -1889,7 +1390,7 @@ function runCleanup(config, verbose = false) {
           }
         }
       }
-    } catch {}
+    } catch (e) { log('warn', 'cleanup worktrees: ' + e.message); }
   }
 
   // 4. Kill zombie claude processes not tracked by the engine
@@ -1905,15 +1406,15 @@ function runCleanup(config, verbose = false) {
     const activeIds = new Set((dispatch.active || []).map(d => d.id));
     for (const [id, info] of activeProcesses.entries()) {
       if (!activeIds.has(id)) {
-        try { if (info.proc) info.proc.kill('SIGTERM'); } catch {}
+        try { if (info.proc) info.proc.kill('SIGTERM'); } catch { /* process may be dead */ }
         activeProcesses.delete(id);
         cleaned.zombies++;
       }
     }
-  } catch {}
+  } catch (e) { log('warn', 'cleanup zombie processes: ' + e.message); }
 
   // 5. Clean spawn-debug.log
-  try { fs.unlinkSync(path.join(ENGINE_DIR, 'spawn-debug.log')); } catch {}
+  try { fs.unlinkSync(path.join(ENGINE_DIR, 'spawn-debug.log')); } catch { /* cleanup */ }
 
   // 6. Prune old output archive files (keep last 30 per agent)
   for (const agentId of Object.keys(config.agents || {})) {
@@ -1925,9 +1426,9 @@ function runCleanup(config, verbose = false) {
         .map(f => ({ name: f, mtime: fs.statSync(path.join(agentDir, f)).mtimeMs }))
         .sort((a, b) => b.mtime - a.mtime);
       for (const old of outputFiles.slice(30)) {
-        try { fs.unlinkSync(path.join(agentDir, old.name)); cleaned.files++; } catch {}
+        try { fs.unlinkSync(path.join(agentDir, old.name)); cleaned.files++; } catch { /* cleanup */ }
       }
-    } catch {}
+    } catch (e) { log('warn', 'prune output archives: ' + e.message); }
   }
 
   // 7. Prune orphaned dispatch entries — items whose source work item no longer exists
@@ -1939,12 +1440,12 @@ function runCleanup(config, verbose = false) {
     try {
       const central = safeJson(path.join(MINIONS_DIR, 'work-items.json')) || [];
       central.forEach(w => allWiIds.add(w.id));
-    } catch {}
+    } catch (e) { log('warn', 'read central work items for orphan check: ' + e.message); }
     for (const project of projects) {
       try {
         const projItems = safeJson(projectWorkItemsPath(project)) || [];
         projItems.forEach(w => allWiIds.add(w.id));
-      } catch {}
+      } catch (e) { log('warn', 'read project work items for orphan check: ' + e.message); }
     }
 
     let changed = false;
@@ -1974,7 +1475,7 @@ function runCleanup(config, verbose = false) {
         }
       });
     }
-  } catch {}
+  } catch (e) { log('warn', 'prune orphaned dispatches: ' + e.message); }
 
   if (cleaned.tempFiles + cleaned.liveOutputs + cleaned.worktrees + cleaned.zombies + (cleaned.files || 0) + cleaned.orphanedDispatches > 0) {
     log('info', `Cleanup: ${cleaned.tempFiles} temp, ${cleaned.liveOutputs} live outputs, ${cleaned.worktrees} worktrees, ${cleaned.zombies} zombies, ${cleaned.files || 0} archives, ${cleaned.orphanedDispatches} orphaned dispatches`);
@@ -1993,10 +1494,10 @@ function runCleanup(config, verbose = false) {
             if (!cleaned.sweptKb) cleaned.sweptKb = 0;
             cleaned.sweptKb++;
           }
-        } catch {}
+        } catch { /* cleanup */ }
       }
     }
-  } catch {}
+  } catch (e) { log('warn', 'cleanup swept KB files: ' + e.message); }
 
   // 9. KB watchdog — restore deleted KB files from git if count dropped vs checkpoint
   try {
@@ -2024,7 +1525,7 @@ function runCleanup(config, verbose = false) {
         }
       }
     }
-  } catch {}
+  } catch (e) { log('warn', 'KB watchdog check: ' + e.message); }
 
   // 6. Migrate legacy work-item statuses to canonical values
   // in-pr, implemented, complete → done (one-time correction per item)
@@ -2044,7 +1545,7 @@ function runCleanup(config, verbose = false) {
         safeWrite(wiPath, items);
         log('info', `Migrated ${migrated} legacy status(es) → done in ${project.name} work items`);
       }
-    } catch {}
+    } catch (e) { log('warn', 'migrate legacy statuses: ' + e.message); }
   }
   // Central work items
   try {
@@ -2061,7 +1562,7 @@ function runCleanup(config, verbose = false) {
       safeWrite(centralPath, centralItems);
       log('info', `Migrated ${migrated} legacy status(es) → done in central work items`);
     }
-  } catch {}
+  } catch (e) { log('warn', 'migrate central legacy statuses: ' + e.message); }
   // PRD items (missing_features[].status)
   try {
     const prdFiles = fs.readdirSync(PRD_DIR).filter(f => f.endsWith('.json'));
@@ -2081,101 +1582,16 @@ function runCleanup(config, verbose = false) {
         log('info', `Migrated ${migrated} legacy PRD item status(es) → done in ${pf}`);
       }
     }
-  } catch {}
+  } catch (e) { log('warn', 'migrate PRD legacy statuses: ' + e.message); }
 
   return cleaned;
 }
 
-// ─── Work Discovery ─────────────────────────────────────────────────────────
-
-const COOLDOWN_PATH = path.join(ENGINE_DIR, 'cooldowns.json');
-const dispatchCooldowns = new Map(); // key → { timestamp, failures }
-
-function loadCooldowns() {
-  const saved = safeJson(COOLDOWN_PATH);
-  if (!saved) return;
-  const now = Date.now();
-  for (const [k, v] of Object.entries(saved)) {
-    // Prune entries older than 24 hours
-    if (now - v.timestamp < 24 * 60 * 60 * 1000) {
-      dispatchCooldowns.set(k, v);
-    }
-  }
-  log('info', `Loaded ${dispatchCooldowns.size} cooldowns from disk`);
-}
-
-let _cooldownWriteTimer = null;
-function saveCooldowns() {
-  // Debounce: reset timer on each call so latest state is always written
-  if (_cooldownWriteTimer) clearTimeout(_cooldownWriteTimer);
-  _cooldownWriteTimer = setTimeout(() => {
-    _cooldownWriteTimer = null;
-    // Prune expired entries (>24h) before saving
-    const now = Date.now();
-    for (const [k, v] of dispatchCooldowns) {
-      if (now - v.timestamp > 24 * 60 * 60 * 1000) dispatchCooldowns.delete(k);
-    }
-    const obj = Object.fromEntries(dispatchCooldowns);
-    safeWrite(COOLDOWN_PATH, obj);
-  }, 1000); // debounce — write at most once per second
-}
-
-function isOnCooldown(key, cooldownMs) {
-  const entry = dispatchCooldowns.get(key);
-  if (!entry) return false;
-  const backoff = Math.min(Math.pow(2, entry.failures || 0), 8);
-  return (Date.now() - entry.timestamp) < (cooldownMs * backoff);
-}
-
-function setCooldown(key) {
-  const existing = dispatchCooldowns.get(key);
-  dispatchCooldowns.set(key, { timestamp: Date.now(), failures: existing?.failures || 0 });
-  saveCooldowns();
-}
-
-function setCooldownWithContext(key, context) {
-  const existing = dispatchCooldowns.get(key);
-  const pendingContexts = existing?.pendingContexts || [];
-  if (context) pendingContexts.push(context);
-  dispatchCooldowns.set(key, {
-    timestamp: Date.now(),
-    failures: existing?.failures || 0,
-    pendingContexts
-  });
-  saveCooldowns();
-}
-
-function getCoalescedContexts(key) {
-  const entry = dispatchCooldowns.get(key);
-  const contexts = entry?.pendingContexts || [];
-  if (contexts.length > 0 && entry) {
-    entry.pendingContexts = []; // Clear after retrieval
-  }
-  return contexts;
-}
+// ─── Cooldowns (extracted to engine/cooldown.js) ─────────────────────────────
 
-function setCooldownFailure(key) {
-  const existing = dispatchCooldowns.get(key);
-  const failures = (existing?.failures || 0) + 1;
-  dispatchCooldowns.set(key, { timestamp: Date.now(), failures });
-  if (failures >= 3) {
-    log('warn', `${key} has failed ${failures} times — cooldown is now ${Math.min(Math.pow(2, failures), 8)}x`);
-  }
-  saveCooldowns();
-}
-
-function isAlreadyDispatched(key) {
-  const dispatch = getDispatch();
-  // Check pending and active
-  const inFlight = [...dispatch.pending, ...(dispatch.active || [])];
-  if (inFlight.some(d => d.meta?.dispatchKey === key)) return true;
-  // Also check recently completed (last hour) to prevent re-dispatch
-  const oneHourAgo = Date.now() - 3600000;
-  const recentCompleted = (dispatch.completed || []).filter(d =>
-    d.completed_at && new Date(d.completed_at).getTime() > oneHourAgo
-  );
-  return recentCompleted.some(d => d.meta?.dispatchKey === key);
-}
+const { COOLDOWN_PATH, dispatchCooldowns, loadCooldowns, saveCooldowns,
+  isOnCooldown, setCooldown, setCooldownWithContext, getCoalescedContexts,
+  setCooldownFailure, isAlreadyDispatched } = require('./engine/cooldown');
 
 
 
@@ -2204,7 +1620,7 @@ function autoCleanPrdWorkItems(prdFile, config) {
         return true;
       });
       if (filtered.length < items.length) safeWrite(wiPath, filtered);
-    } catch {}
+    } catch (e) { log('warn', 'auto-clean PRD work items: ' + e.message); }
   }
   if (deletedIds.length > 0) {
     const deletedSet = new Set(deletedIds);
@@ -2214,7 +1630,7 @@ function autoCleanPrdWorkItems(prdFile, config) {
 }
 
 function materializePlansAsWorkItems(config) {
-  if (!fs.existsSync(PRD_DIR)) { try { fs.mkdirSync(PRD_DIR, { recursive: true }); } catch {} }
+  if (!fs.existsSync(PRD_DIR)) { try { fs.mkdirSync(PRD_DIR, { recursive: true }); } catch (e) { log('warn', 'create PRD directory: ' + e.message); } }
 
   // Enforce: PRDs must be .json — auto-rename .md files that contain valid PRD JSON
   // Check both prd/ and plans/ (agents may still write JSON to plans/)
@@ -2231,12 +1647,12 @@ function materializePlansAsWorkItems(config) {
           if (parsed.missing_features) {
             const jsonName = mf.replace(/\.md$/, '.json');
             safeWrite(path.join(PRD_DIR, jsonName), parsed);
-            try { fs.unlinkSync(path.join(checkDir, mf)); } catch {}
+            try { fs.unlinkSync(path.join(checkDir, mf)); } catch { /* cleanup */ }
             log('info', `Plan enforcement: moved ${mf} → prd/${jsonName} (PRDs must be .json in prd/)`);
           }
         } catch {} // Not JSON — it's a proper plan .md, leave it
       }
-    } catch {}
+    } catch (e) { log('warn', 'scan .md files for PRD enforcement: ' + e.message); }
     // Also migrate any .json PRD files from plans/ to prd/
     if (checkDir === PLANS_DIR) {
       try {
@@ -2246,12 +1662,12 @@ function materializePlansAsWorkItems(config) {
             const parsed = safeJson(path.join(PLANS_DIR, jf));
             if (parsed?.missing_features) {
               safeWrite(path.join(PRD_DIR, jf), parsed);
-              try { fs.unlinkSync(path.join(PLANS_DIR, jf)); } catch {}
+              try { fs.unlinkSync(path.join(PLANS_DIR, jf)); } catch { /* cleanup */ }
               log('info', `Auto-migrated PRD ${jf} from plans/ to prd/`);
             }
-          } catch {}
+          } catch (e) { log('warn', 'migrate PRD from plans: ' + e.message); }
         }
-      } catch {}
+      } catch (e) { log('warn', 'scan JSON in plans dir: ' + e.message); }
     }
   }
 
@@ -2303,7 +1719,7 @@ function materializePlansAsWorkItems(config) {
               : '';
 
             // Delete old PRD — agent will write replacement at same path
-            try { fs.unlinkSync(path.join(PRD_DIR, file)); } catch {}
+            try { fs.unlinkSync(path.join(PRD_DIR, file)); } catch { /* cleanup */ }
 
             // Queue plan-to-prd regeneration
             const planContent = safeRead(path.join(PLANS_DIR, plan.source_plan));
@@ -2341,7 +1757,7 @@ function materializePlansAsWorkItems(config) {
 
           safeWrite(path.join(PRD_DIR, file), plan);
         }
-      } catch {}
+      } catch (e) { log('warn', 'plan staleness check: ' + e.message); }
     }
 
     // Human approval gate: plans start as 'awaiting-approval' and must be approved before work begins
@@ -2507,50 +1923,7 @@ function materializePlansAsWorkItems(config) {
   }
 }
 
-// ─── Work Discovery Helpers ──────────────────────────────────────────────────
-
-function buildBaseVars(agentId, config, project) {
-  return {
-    agent_id: agentId,
-    agent_name: config.agents[agentId]?.name || agentId,
-    agent_role: config.agents[agentId]?.role || 'Agent',
-    team_root: MINIONS_DIR,
-    repo_id: project?.repositoryId || '',
-    project_name: project?.name || 'Unknown Project',
-    ado_org: project?.adoOrg || 'Unknown',
-    ado_project: project?.adoProject || 'Unknown',
-    repo_name: project?.repoName || 'Unknown',
-    main_branch: project?.mainBranch || 'main',
-    date: dateStamp(),
-  };
-}
-
-function selectPlaybook(workType, item) {
-  if (item?.branchStrategy === 'shared-branch' && (workType === 'implement' || workType === 'implement:large')) {
-    return 'implement-shared';
-  }
-  if (workType === 'review' && !item?._pr && !item?.pr_id) {
-    return 'work-item';
-  }
-  const typeSpecificPlaybooks = ['explore', 'review', 'test', 'plan-to-prd', 'plan', 'ask', 'verify', 'decompose'];
-  return typeSpecificPlaybooks.includes(workType) ? workType : 'work-item';
-}
-
-function buildPrDispatch(agentId, config, project, pr, type, extraVars, taskLabel, meta) {
-  const vars = { ...buildBaseVars(agentId, config, project), ...extraVars };
-  const playbookName = type === 'test' ? 'build-and-test' : (type === 'review' ? 'review' : 'fix');
-  const prompt = renderPlaybook(playbookName, vars);
-  if (!prompt) return null;
-  return {
-    type,
-    agent: agentId,
-    agentName: config.agents[agentId]?.name,
-    agentRole: config.agents[agentId]?.role,
-    task: `[${project?.name || 'project'}] ${taskLabel}`,
-    prompt,
-    meta,
-  };
-}
+// buildBaseVars, selectPlaybook, buildPrDispatch extracted to engine/playbook.js
 
 function clearPendingHumanFeedbackFlag(projectMeta, prId) {
   if (!prId) return;
@@ -2561,7 +1934,7 @@ function clearPendingHumanFeedbackFlag(projectMeta, prId) {
     if (!target?.humanFeedback?.pendingFix) return;
     target.humanFeedback.pendingFix = false;
     safeWrite(prsPath, prs);
-  } catch {}
+  } catch (e) { log('warn', 'clear pending human feedback flag: ' + e.message); }
 }
 
 /**
@@ -2681,7 +2054,7 @@ function discoverFromPrs(config, project) {
             target._buildFailNotified = true;
             safeWrite(prPath, prs);
           }
-        } catch {}
+        } catch (e) { log('warn', 'mark build fail notified: ' + e.message); }
       }
     }
 
@@ -2747,7 +2120,7 @@ function discoverFromWorkItems(config, project) {
         return dp.completed.length !== before ? dp : undefined;
       });
       dispatchCooldowns.delete(key);
-    } catch {}
+    } catch (e) { log('warn', 'self-heal dispatch state: ' + e.message); }
     // Cooldown bypass for resumed items — clear in-memory cooldown so they dispatch immediately
     if (item._resumedAt) {
       dispatchCooldowns.delete(key);
@@ -2809,7 +2182,7 @@ function discoverFromWorkItems(config, project) {
       commit_message: item.commitMessage || `feat: ${item.title || item.id}`,
       notes_content: '',
     };
-    try { vars.notes_content = fs.readFileSync(path.join(MINIONS_DIR, 'notes.md'), 'utf8'); } catch {}
+    try { vars.notes_content = fs.readFileSync(path.join(MINIONS_DIR, 'notes.md'), 'utf8'); } catch { /* optional */ }
 
     // Inject references and acceptance criteria
     const refs = (item.references || []).filter(r => r && r.url).map(r =>
@@ -2824,7 +2197,7 @@ function discoverFromWorkItems(config, project) {
       vars.question = item.title + (item.description ? '\n\n' + item.description : '');
       vars.task_id = item.id;
       vars.notes_content = '';
-      try { vars.notes_content = fs.readFileSync(path.join(MINIONS_DIR, 'notes.md'), 'utf8'); } catch {}
+      try { vars.notes_content = fs.readFileSync(path.join(MINIONS_DIR, 'notes.md'), 'utf8'); } catch { /* optional */ }
     }
 
     // Resolve implicit context references (e.g., "ripley's plan", "the latest plan")
@@ -2954,7 +2327,7 @@ function materializeSpecsAsWorkItems(config, project) {
           recentSpecs.push({ file: line.trim(), ...currentCommit });
         }
       }
-    } catch {}
+    } catch (e) { log('warn', 'git: ' + e.message); }
   }
 
   if (recentSpecs.length === 0) return;
@@ -3118,7 +2491,7 @@ function discoverCentralWorkItems(config) {
           vars.question = item.title + (item.description ? '\n\n' + item.description : '');
           vars.task_id = item.id;
           vars.notes_content = '';
-          try { vars.notes_content = fs.readFileSync(path.join(MINIONS_DIR, 'notes.md'), 'utf8'); } catch {}
+          try { vars.notes_content = fs.readFileSync(path.join(MINIONS_DIR, 'notes.md'), 'utf8'); } catch { /* optional */ }
         }
 
         const resolvedCtx = resolveTaskContext(item, config);
@@ -3179,7 +2552,7 @@ function discoverCentralWorkItems(config) {
         project_path: firstProject?.localPath || '',
         notes_content: '',
       };
-      try { vars.notes_content = fs.readFileSync(path.join(MINIONS_DIR, 'notes.md'), 'utf8'); } catch {}
+      try { vars.notes_content = fs.readFileSync(path.join(MINIONS_DIR, 'notes.md'), 'utf8'); } catch { /* optional */ }
 
       // Inject references and acceptance criteria
       const normRefs = (item.references || []).filter(r => r && r.url).map(r =>
@@ -3199,7 +2572,7 @@ function discoverCentralWorkItems(config) {
         vars.plan_file = planFileName;
         vars.task_description = item.title;
         vars.notes_content = '';
-        try { vars.notes_content = fs.readFileSync(path.join(MINIONS_DIR, 'notes.md'), 'utf8'); } catch {}
+        try { vars.notes_content = fs.readFileSync(path.join(MINIONS_DIR, 'notes.md'), 'utf8'); } catch { /* optional */ }
         // Track expected plan filename in meta for chainPlanToPrd
         item._planFileName = planFileName;
       }
@@ -3228,7 +2601,7 @@ function discoverCentralWorkItems(config) {
         vars.question = item.title + (item.description ? '\n\n' + item.description : '');
         vars.task_id = item.id;
         vars.notes_content = '';
-        try { vars.notes_content = fs.readFileSync(path.join(MINIONS_DIR, 'notes.md'), 'utf8'); } catch {}
+        try { vars.notes_content = fs.readFileSync(path.join(MINIONS_DIR, 'notes.md'), 'utf8'); } catch { /* optional */ }
       }
 
       // Resolve implicit context references
@@ -3321,7 +2694,7 @@ function discoverWork(config) {
       }
       if (added > 0) safeWrite(centralPath, items);
     }
-  } catch {}
+  } catch (e) { log('warn', 'discover scheduled work: ' + e.message); }
 
   // Gate reviews and fixes: do not dispatch until all implement items are complete
   const hasIncompleteImplements = projects.some(project => {
@@ -3381,7 +2754,7 @@ async function tickInner() {
   }
 
   // Write heartbeat so dashboard can detect stale engine
-  try { safeWrite(CONTROL_PATH, { ...control, heartbeat: Date.now() }); } catch {}
+  try { safeWrite(CONTROL_PATH, { ...control, heartbeat: Date.now() }); } catch (e) { log('warn', 'write heartbeat: ' + e.message); }
 
   const config = getConfig();
   tickCount++;
@@ -3480,7 +2853,7 @@ async function tickInner() {
                       dp.completed = dp.completed.filter(d => d.meta?.dispatchKey !== key);
                       if (dp.completed.length !== before) return dp;
                     });
-                  } catch {}
+                  } catch (e) { log('warn', 'stall recovery clear dispatch: ' + e.message); }
 
                 // Clear cooldown so item isn't blocked by exponential backoff
                 try {
@@ -3489,7 +2862,7 @@ async function tickInner() {
                     dispatchCooldowns.delete(key);
                     saveCooldowns();
                   }
-                } catch {}
+                } catch (e) { log('warn', 'stall recovery clear cooldown: ' + e.message); }
               }
             }
 
@@ -3513,14 +2886,14 @@ async function tickInner() {
                       mutateDispatch((dp) => {
                         dp.completed = dp.completed.filter(d => d.meta?.dispatchKey !== key);
                       });
-                    } catch {}
+                    } catch (e) { log('warn', 'stall recovery clear dependent dispatch: ' + e.message); }
                   }
                 }
               }
             }
 
             if (changed) safeWrite(wiPath, items);
-          } catch {}
+          } catch (e) { log('warn', 'stall recovery process project: ' + e.message); }
         }
       }
     } catch (err) { log('warn', `Stall detection error: ${err?.message || err}`); }