@sienklogic/plan-build-run 2.18.1 → 2.19.1

package/plugins/pbr/scripts/lib/suggest-next.js

@@ -0,0 +1,435 @@
+/**
+ * lib/suggest-next.cjs -- Deterministic routing decision tree for Plan-Build-Run.
+ *
+ * Encapsulates the priority-based routing logic used by status, continue,
+ * and resume skills. Scans project state and returns a JSON recommendation
+ * for the next command to run.
+ *
+ * Priority hierarchy (first match wins):
+ *   1. Paused work (.continue-here.md)
+ *   2. UAT blocker (STATE.md blockers)
+ *   3. Active checkpoint (STATE.md active_checkpoint)
+ *   4. Verification gaps (VERIFICATION.md with gaps_found)
+ *   5. Built not verified (SUMMARY exists, no VERIFICATION)
+ *   6. Planned not built (PLAN exists, no SUMMARY)
+ *   7. Building in progress (some SUMMARYs, not all)
+ *   8. All verified, more phases (unstarted phases in ROADMAP)
+ *   9. All milestones complete (status === milestone-complete)
+ *  10. Empty phases (phase dirs with no PLAN)
+ *  11. No project (no .planning/)
+ *
+ * Called by: `node pbr-tools.js suggest-next`
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { parseYamlFrontmatter, findFiles } = require('./core');
+const { configLoad } = require('./config');
+
+// ---- Helpers ----
+
+function safeReadFile(filePath) {
+  try {
+    return fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : null;
+  } catch (_e) {
+    return null;
+  }
+}
+
+function safeParseFrontmatter(content) {
+  if (!content) return {};
+  try {
+    return parseYamlFrontmatter(content) || {};
+  } catch (_e) {
+    return {};
+  }
+}
+
+function countFilesIn(dirPath, filterFn) {
+  if (!fs.existsSync(dirPath)) return 0;
+  try {
+    const entries = fs.readdirSync(dirPath);
+    return filterFn ? entries.filter(filterFn).length : entries.length;
+  } catch (_e) {
+    return 0;
+  }
+}
+
+// ---- Phase scanning (lightweight, focused on routing) ----
+
+function scanPhasesForRouting(planningDir) {
+  const phasesDir = path.join(planningDir, 'phases');
+  if (!fs.existsSync(phasesDir)) return [];
+
+  const phases = [];
+  let entries;
+  try {
+    entries = fs.readdirSync(phasesDir, { withFileTypes: true });
+  } catch (_e) {
+    return [];
+  }
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const match = entry.name.match(/^(\d+)-(.+)/);
+    if (!match) continue;
+
+    const phaseNum = parseInt(match[1], 10);
+    const phaseName = match[2].replace(/-/g, ' ');
+    const phaseDir = path.join(phasesDir, entry.name);
+
+    const plans = findFiles(phaseDir, /^PLAN.*\.md$/i);
+    const summaries = findFiles(phaseDir, /^SUMMARY.*\.md$/i);
+    const verificationPath = path.join(phaseDir, 'VERIFICATION.md');
+    let hasVerification = false;
+    let verificationResult = null;
+
+    if (fs.existsSync(verificationPath)) {
+      hasVerification = true;
+      const vContent = safeReadFile(verificationPath);
+      if (vContent) {
+        const fm = safeParseFrontmatter(vContent);
+        verificationResult = fm.result || null;
+      }
+    }
+
+    // Check for .continue-here.md in phase dir
+    const hasContinueHere = fs.existsSync(path.join(phaseDir, '.continue-here.md'));
+
+    // Determine status
+    let status = 'empty';
+    if (hasVerification && verificationResult === 'passed') {
+      status = 'verified';
+    } else if (hasVerification && verificationResult === 'gaps_found') {
+      status = 'gaps_found';
+    } else if (summaries.length > 0 && summaries.length >= plans.length && plans.length > 0) {
+      status = 'built';
+    } else if (summaries.length > 0) {
+      status = 'building';
+    } else if (plans.length > 0) {
+      status = 'planned';
+    }
+
+    phases.push({
+      number: phaseNum,
+      name: phaseName,
+      status,
+      plans_total: plans.length,
+      plans_complete: summaries.length,
+      has_verification: hasVerification,
+      verification_result: verificationResult,
+      has_continue_here: hasContinueHere,
+      dir_name: entry.name
+    });
+  }
+
+  phases.sort((a, b) => a.number - b.number);
+  return phases;
+}
+
+// ---- Config helper ----
+
+function loadConfig(planningDir) {
+  try {
+    return configLoad(planningDir) || {};
+  } catch (_e) {
+    return {};
+  }
+}
+
+// ---- Milestone boundary detection ----
+
+/**
+ * Parse ROADMAP.md for milestone sections and detect if a phase is the
+ * last phase in its milestone.
+ *
+ * @param {string} planningDir - Path to .planning/ directory
+ * @param {number} phaseNum - Phase number to check
+ * @returns {boolean} True if phaseNum is the last phase in its milestone section
+ */
+function isLastPhaseInMilestone(planningDir, phaseNum) {
+  const roadmapContent = safeReadFile(path.join(planningDir, 'ROADMAP.md'));
+  if (!roadmapContent) return false;
+
+  const lines = roadmapContent.replace(/\r\n/g, '\n').split('\n');
+  const milestones = []; // { startLine, phases: [] }
+  let current = null;
+
+  for (const line of lines) {
+    const milestoneMatch = line.match(/^##\s+Milestone[:\s]/i);
+    if (milestoneMatch) {
+      if (current) milestones.push(current);
+      current = { phases: [] };
+      continue;
+    }
+    if (current) {
+      // Match phase references: ### Phase N, | N. Name |, or checkbox format
+      const phaseMatch = line.match(/###\s+Phase\s+(\d+)/i);
+      if (phaseMatch) {
+        current.phases.push(parseInt(phaseMatch[1], 10));
+        continue;
+      }
+      const tableMatch = line.match(/^\|\s*(\d+)\.\s/);
+      if (tableMatch) {
+        current.phases.push(parseInt(tableMatch[1], 10));
+        continue;
+      }
+      // Checkbox format: - [x] Phase N or - [ ] Phase N
+      const checkboxMatch = line.match(/^-\s*\[.\]\s*(?:Phase\s+)?(\d+)/i);
+      if (checkboxMatch) {
+        current.phases.push(parseInt(checkboxMatch[1], 10));
+      }
+    }
+  }
+  if (current) milestones.push(current);
+
+  // Find which milestone contains phaseNum and check if it's the last
+  for (const ms of milestones) {
+    if (ms.phases.includes(phaseNum)) {
+      const maxPhase = Math.max(...ms.phases);
+      return phaseNum === maxPhase;
+    }
+  }
+  return false;
+}
+
+// ---- Main suggest-next function ----
+
+/**
+ * Determine the recommended next command based on project state.
+ *
+ * @param {string} planningDir - Path to .planning/ directory
+ * @returns {object} Routing recommendation with command, args, reason, alternatives, context
+ */
+function suggestNext(planningDir) {
+  // Priority 11: No project
+  if (!fs.existsSync(planningDir)) {
+    return {
+      command: '/pbr:begin',
+      args: '',
+      reason: 'No .planning/ directory found',
+      alternatives: [],
+      context: {
+        current_phase: null,
+        phase_status: null,
+        plans_total: 0,
+        plans_complete: 0
+      }
+    };
+  }
+
+  // Load state and config
+  const stateContent = safeReadFile(path.join(planningDir, 'STATE.md'));
+  const stateFm = safeParseFrontmatter(stateContent);
+  const phases = scanPhasesForRouting(planningDir);
+  const config = loadConfig(planningDir);
+
+  // Count todos and notes for alternatives
+  const todosPending = countFilesIn(
+    path.join(planningDir, 'todos', 'pending'),
+    f => f.endsWith('.md')
+  );
+  const notesActive = countFilesIn(
+    path.join(planningDir, 'notes'),
+    f => f.endsWith('.md')
+  );
+
+  // Build alternatives list
+  const alternatives = [];
+  if (todosPending > 0) {
+    alternatives.push({
+      command: '/pbr:todo list',
+      reason: `${todosPending} pending todo${todosPending > 1 ? 's' : ''}`
+    });
+  }
+  if (notesActive > 0) {
+    alternatives.push({
+      command: '/pbr:note list',
+      reason: `${notesActive} active note${notesActive > 1 ? 's' : ''} to review`
+    });
+  }
+  alternatives.push({
+    command: '/pbr:quick',
+    reason: 'Run an ad-hoc task'
+  });
+
+  // Helper to build result
+  function result(command, args, reason, phase) {
+    return {
+      command,
+      args: args || '',
+      reason,
+      alternatives,
+      context: {
+        current_phase: phase ? phase.number : (stateFm.current_phase || null),
+        phase_status: phase ? phase.status : (stateFm.status || null),
+        plans_total: phase ? phase.plans_total : 0,
+        plans_complete: phase ? phase.plans_complete : 0
+      }
+    };
+  }
+
+  // Priority 1: Paused work (.continue-here.md in phases or project root)
+  const rootContinueHere = path.join(planningDir, '..', '.continue-here.md');
+  const phaseContinueHere = phases.find(p => p.has_continue_here);
+  if (fs.existsSync(rootContinueHere) || phaseContinueHere) {
+    const phase = phaseContinueHere || null;
+    return result('/pbr:resume', '', 'Paused work detected', phase);
+  }
+
+  // Priority 2: UAT blocker
+  if (stateFm.blockers && Array.isArray(stateFm.blockers)) {
+    const uatBlocker = stateFm.blockers.find(b =>
+      typeof b === 'string' ? /uat/i.test(b) : (b && /uat/i.test(b.text || b.description || ''))
+    );
+    if (uatBlocker) {
+      const currentPhaseNum = stateFm.current_phase;
+      const phase = phases.find(p => p.number === currentPhaseNum);
+      return result('/pbr:review', String(currentPhaseNum || ''), 'UAT blocker requires review', phase);
+    }
+  }
+
+  // Priority 3: Active checkpoint (YAML "null" parses as string "null", not JS null)
+  if (stateFm.active_checkpoint && stateFm.active_checkpoint !== 'null') {
+    const currentPhaseNum = stateFm.current_phase;
+    const phase = phases.find(p => p.number === currentPhaseNum);
+    return result('/pbr:build', String(currentPhaseNum || ''), 'Active checkpoint needs resolution', phase);
+  }
+
+  // Priority 4: Verification gaps
+  const gapsPhase = phases.find(p => p.status === 'gaps_found');
+  if (gapsPhase) {
+    return result('/pbr:plan', `${gapsPhase.number} --gaps`, `Phase ${gapsPhase.number} has verification gaps`, gapsPhase);
+  }
+
+  // Priority 5: Built not verified (config-aware: validate_phase routing)
+  const builtPhase = phases.find(p => p.status === 'built');
+  if (builtPhase) {
+    const useValidatePhase = !(config.workflow && config.workflow.validate_phase === false);
+    const cmd = useValidatePhase ? '/pbr:validate-phase' : '/pbr:review';
+    return result(cmd, String(builtPhase.number), `Phase ${builtPhase.number} built but not verified`, builtPhase);
+  }
+
+  // Priority 6: Planned not built
+  const plannedPhase = phases.find(p => p.status === 'planned');
+  if (plannedPhase) {
+    return result(
+      '/pbr:build', String(plannedPhase.number),
+      `Phase ${plannedPhase.number} planned, ready to build (${plannedPhase.plans_total} plan${plannedPhase.plans_total > 1 ? 's' : ''})`,
+      plannedPhase
+    );
+  }
+
+  // Priority 7: Building in progress
+  const buildingPhase = phases.find(p => p.status === 'building');
+  if (buildingPhase) {
+    return result(
+      '/pbr:build', String(buildingPhase.number),
+      `Phase ${buildingPhase.number} build in progress (${buildingPhase.plans_complete}/${buildingPhase.plans_total} plans done)`,
+      buildingPhase
+    );
+  }
+
+  // Priority 7b: Milestone boundary detection
+  // If the highest-numbered verified phase is the last in its milestone, suggest milestone completion
+  const verifiedPhases = phases.filter(p => p.status === 'verified');
+  if (verifiedPhases.length > 0) {
+    const highestVerified = verifiedPhases[verifiedPhases.length - 1]; // sorted by number
+    if (isLastPhaseInMilestone(planningDir, highestVerified.number)) {
+      // Only suggest milestone if there are no unfinished phases (built/planned/building/empty)
+      const unfinished = phases.filter(p =>
+        p.status !== 'verified' && p.status !== 'gaps_found'
+      );
+      if (unfinished.length === 0) {
+        return result('/pbr:milestone', '', 'All phases in current milestone verified', highestVerified);
+      }
+    }
+  }
+
+  // Priority 8: All verified, more phases in ROADMAP
+  const verified = phases.filter(p => p.status === 'verified');
+  const allVerified = phases.length > 0 && verified.length === phases.length;
+  if (allVerified) {
+    // Check ROADMAP for unstarted phases
+    const roadmapContent = safeReadFile(path.join(planningDir, 'ROADMAP.md'));
+    if (roadmapContent) {
+      // Look for phase references in roadmap that don't have phase dirs yet
+      const roadmapPhaseNums = [];
+      const lines = roadmapContent.replace(/\r\n/g, '\n').split('\n');
+      for (const line of lines) {
+        const phaseMatch = line.match(/###\s+Phase\s+(\d+)/i);
+        if (phaseMatch) roadmapPhaseNums.push(parseInt(phaseMatch[1], 10));
+        const tableMatch = line.match(/^\|\s*(\d+)\.\s/);
+        if (tableMatch) roadmapPhaseNums.push(parseInt(tableMatch[1], 10));
+      }
+      const existingNums = new Set(phases.map(p => p.number));
+      const unstarted = roadmapPhaseNums.filter(n => !existingNums.has(n));
+      if (unstarted.length > 0) {
+        const nextPhase = Math.min(...unstarted);
+        return result('/pbr:plan', String(nextPhase), `All current phases verified, plan phase ${nextPhase}`, null);
+      }
+    }
+  }
+
+  // Priority 9: All milestones complete
+  if (stateFm.status === 'milestone-complete') {
+    return result('/pbr:new-milestone', '', 'Milestone complete, start next milestone', null);
+  }
+
+  // Priority 10: Empty phases exist
+  const emptyPhase = phases.find(p => p.status === 'empty');
+  if (emptyPhase) {
+    return result('/pbr:plan', String(emptyPhase.number), `Phase ${emptyPhase.number} needs planning`, emptyPhase);
+  }
+
+  // Priority 10b: Status-based routing fallback
+  if (stateFm.status) {
+    const currentPhase = stateFm.current_phase;
+    const currentPhaseStr = String(currentPhase || '');
+    const nextPhaseStr = String((currentPhase || 0) + 1);
+
+    switch (stateFm.status) {
+      case 'not_started':
+      case 'discussed':
+      case 'ready_to_plan':
+        return result('/pbr:plan', currentPhaseStr, `Status: ${stateFm.status}`, null);
+      case 'planning':
+        return result('/pbr:plan', currentPhaseStr, 'Planning in progress', null);
+      case 'planned':
+      case 'ready_to_execute':
+      case 'building':
+      case 'partial':
+        return result('/pbr:build', currentPhaseStr, `Status: ${stateFm.status}`, null);
+      case 'built': {
+        const useVP = !(config.workflow && config.workflow.validate_phase === false);
+        const builtCmd = useVP ? '/pbr:validate-phase' : '/pbr:review';
+        return result(builtCmd, currentPhaseStr, 'Status: built', null);
+      }
+      case 'verified':
+      case 'complete':
+      case 'skipped':
+        return result('/pbr:plan', nextPhaseStr, `Status: ${stateFm.status}, advance to next phase`, null);
+      case 'needs_fixes':
+        return result('/pbr:plan', `${currentPhaseStr} --gaps`, 'Status: needs_fixes', null);
+      // milestone-complete already handled by Priority 9
+    }
+  }
+
+  // No phases at all
+  if (phases.length === 0) {
+    if (stateFm.current_phase != null) {
+      return result('/pbr:plan', '', 'No phases found, start planning', null);
+    }
+    return result('/pbr:begin', '', 'No project initialized', null);
+  }
+
+  // Fallback: all verified, no unstarted phases found
+  if (allVerified) {
+    return result('/pbr:new-milestone', '', 'All phases verified, ready for next milestone', null);
+  }
+
+  // True fallback
+  return result('/pbr:status', '', 'Review current project state', null);
+}
+
+module.exports = { suggestNext };

package/plugins/pbr/scripts/lib/team-composer.js

@@ -0,0 +1,87 @@
+// STATUS: Library module — not wired into hooks/gates. Available when parallelization.use_teams is enabled.
+
+/**
+ * lib/team-composer.cjs — Dynamic team assembly for Plan-Build-Run.
+ *
+ * Analyzes task requirements and selects appropriate agent roles
+ * to form a team for execution.
+ * Part of Phase 13: Multi-Agent Evolution (experimental).
+ */
+
+const { TeamCoordinator } = require('./team-coordinator');
+
+class TeamComposer {
+  /**
+   * Create a TeamComposer instance.
+   *
+   * @param {object} opts
+   * @param {string} [opts.planningDir] - Path to .planning directory
+   * @param {object} [opts.config] - Pre-loaded config object
+   */
+  constructor({ planningDir, config } = {}) {
+    this.config = config || {};
+    this.planningDir = planningDir;
+  }
+
+  /**
+   * Select agent roles based on task analysis criteria.
+   *
+   * @param {object} analysis - Task analysis data
+   * @param {string} analysis.taskType - Type of task (e.g., 'implementation', 'refactor')
+   * @param {string} [analysis.riskLevel] - Risk level ('low', 'medium', 'high')
+   * @param {string[]} [analysis.files] - Files to be modified
+   * @param {number} [analysis.discovery] - Discovery level (1-3)
+   * @returns {object[]} Array of { role } objects
+   * @private
+   */
+  _selectRoles({ taskType, riskLevel, files = [], discovery } = {}) {
+    const team = [{ role: 'executor' }];
+
+    if (riskLevel === 'high' || files.length > 5) {
+      team.push({ role: 'verifier' });
+    }
+
+    if (discovery >= 2) {
+      team.push({ role: 'researcher' });
+    }
+
+    if (taskType === 'refactor' && files.length > 3) {
+      team.push({ role: 'plan-checker' });
+    }
+
+    return team;
+  }
+
+  /**
+   * Compose a team of agents for a given task.
+   * Analyzes task requirements and builds TeamCoordinator task definitions.
+   *
+   * @param {object} opts
+   * @param {string} opts.taskType - Type of task
+   * @param {string} [opts.riskLevel] - Risk level
+   * @param {string[]} [opts.files] - Files to modify
+   * @param {number} [opts.discovery] - Discovery level
+   * @param {string} [opts.planId] - Plan identifier
+   * @returns {{ skipped: boolean, reason?: string, team?: object[], taskDefinitions?: object[] }}
+   */
+  composeTeam({ taskType, riskLevel, files = [], discovery, planId } = {}) {
+    const features = this.config.features || {};
+    if (!features.dynamic_teams) {
+      return { skipped: true, reason: 'dynamic_teams disabled' };
+    }
+
+    const team = this._selectRoles({ taskType, riskLevel, files, discovery });
+
+    const tc = new TeamCoordinator({ config: this.config });
+    const agents = team.map(t => t.role);
+    const spawnResult = tc.spawnTeam({ agents, planId });
+
+    return {
+      skipped: false,
+      team,
+      taskDefinitions: spawnResult.tasks || []
+    };
+  }
+}
+
+module.exports = { TeamComposer };

package/plugins/pbr/scripts/lib/team-coordinator.js

@@ -0,0 +1,153 @@
+// STATUS: Library module — imported by team-composer.js and hypothesis-runner.js. Not directly used by hooks/gates.
+
+/**
+ * lib/team-coordinator.cjs — Multi-agent team coordination for Plan-Build-Run.
+ *
+ * Provides worktree-isolated agent spawning and result merging for parallel
+ * multi-agent workflows. When `features.agent_teams` is enabled in the project
+ * config, the build skill can run multiple specialist agents simultaneously —
+ * each in its own git worktree so they don't step on each other's changes.
+ *
+ * Part of Phase 13: Multi-Agent Evolution (experimental).
+ *
+ * @module team-coordinator
+ *
+ * @example
+ * const { TeamCoordinator } = require('./lib/team-coordinator');
+ *
+ * // Instantiate with an explicit planning directory
+ * const coordinator = new TeamCoordinator({ planningDir: '.planning' });
+ *
+ * // Build task definitions for executor + verifier running in parallel
+ * const result = coordinator.spawnTeam({
+ *   agents: ['executor', 'verifier'],
+ *   planId: '13-01',
+ *   context: 'Focus on the API layer changes in src/api/'
+ * });
+ *
+ * if (!result.skipped) {
+ *   // result.tasks is an array of task definition objects ready for Task() calls
+ *   console.log(`Spawning ${result.tasks.length} agents for plan ${planId}`);
+ * }
+ */
+
+'use strict';
+
+const { configLoad } = require('./config');
+
+/**
+ * Coordinates a team of agents running in parallel worktree isolation.
+ *
+ * The coordinator acts as a planner/dispatcher: it builds task definitions
+ * that the build skill then passes to `Task()` calls. This keeps agent
+ * spawning logic separate from the skill's orchestration loop.
+ *
+ * Configuration key: `features.agent_teams` (boolean) in `.planning/config.json`.
+ * When false (the default), all `spawnTeam()` calls return `{ skipped: true }`.
+ */
+class TeamCoordinator {
+  /**
+   * Create a TeamCoordinator instance.
+   *
+   * @param {object} [opts={}] - Constructor options
+   * @param {string} [opts.planningDir] - Path to the `.planning` directory.
+   *   Used to locate `config.json` when no pre-loaded config is provided.
+   *   Defaults to the current working directory's `.planning` folder via
+   *   `configLoad()`.
+   * @param {object} [opts.config] - Pre-loaded config object. When provided,
+   *   `planningDir` is ignored and no disk read is performed. Useful in tests
+   *   or when the caller already has the config in memory.
+   */
+  constructor({ planningDir, config } = {}) {
+    this.config = config || configLoad(planningDir) || {};
+  }
+
+  /**
+   * Build task definitions for a team of agents to run in worktree isolation.
+   *
+   * Does NOT spawn agents directly — returns task definitions for the caller
+   * (the build skill) to execute via `Task()`. This separation lets the skill
+   * interleave team spawning with its normal wave-execution loop without
+   * importing agent-spawning concerns into this library.
+   *
+   * Task definition shape:
+   * ```json
+   * {
+   *   "agentType": "executor",
+   *   "isolation": "worktree",
+   *   "planId": "13-01",
+   *   "context": "optional extra instructions"
+   * }
+   * ```
+   *
+   * @param {object} [opts={}] - Spawn options
+   * @param {string[]} [opts.agents=[]] - Agent types to include.
+   *   Standard values: `'executor'`, `'verifier'`, `'integration-checker'`.
+   *   Each entry produces one task definition in the returned array.
+   * @param {string} opts.planId - Plan identifier (e.g., `'13-01'`).
+   *   Passed through to each task definition so agents can locate their
+   *   PLAN.md and SUMMARY.md artifacts.
+   * @param {string} [opts.context] - Optional freeform context string to
+   *   include in every task definition. Agents receive this as extra
+   *   instructions appended to their standard prompt.
+   * @returns {{ skipped: boolean, reason?: string, tasks?: object[] }}
+   *   - `skipped: true` when `features.agent_teams` is disabled; includes a
+   *     human-readable `reason` string.
+   *   - `skipped: false` with a `tasks` array when the feature is active.
+   */
+  spawnTeam({ agents = [], planId, context } = {}) {
+    const features = this.config.features || {};
+    if (!features.agent_teams) {
+      return { skipped: true, reason: 'agent_teams disabled' };
+    }
+
+    const tasks = agents.map(agentType => ({
+      agentType,
+      isolation: 'worktree',
+      planId,
+      context: context || undefined
+    }));
+
+    return { skipped: false, tasks };
+  }
+
+  /**
+   * Merge results from multiple agent executions into a single summary object.
+   *
+   * Intended for use after all Task() calls from a `spawnTeam()` batch have
+   * completed. The caller collects each agent's result object and passes them
+   * as an array; this method aggregates pass/fail status and the de-duplicated
+   * set of files touched across all agents.
+   *
+   * @param {object[]} [agentResults=[]] - Array of agent result objects.
+   *   Each element should describe one agent's outcome.
+   * @param {string} agentResults[].agentType - The agent type identifier
+   *   (e.g., `'executor'`). Used to populate `failedAgents`.
+   * @param {string} agentResults[].status - Outcome string. `'success'`
+   *   indicates the agent completed without errors; any other value (e.g.,
+   *   `'failed'`, `'partial'`) is treated as a failure.
+   * @param {string[]} [agentResults[].files] - List of file paths created or
+   *   modified by this agent. May be omitted if unknown.
+   * @returns {{
+   *   results: object[],
+   *   allSucceeded: boolean,
+   *   failedAgents: string[],
+   *   filesModified: string[]
+   * }}
+   *   - `results` — the original input array, passed through unchanged.
+   *   - `allSucceeded` — `true` only when every agent reported `'success'`.
+   *   - `failedAgents` — array of `agentType` values for non-successful agents.
+   *   - `filesModified` — de-duplicated union of all `files` arrays.
+   */
+  mergeResults(agentResults = []) {
+    const allSucceeded = agentResults.every(r => r.status === 'success');
+    const failedAgents = agentResults
+      .filter(r => r.status !== 'success')
+      .map(r => r.agentType);
+    const filesModified = [...new Set(agentResults.flatMap(r => r.files || []))];
+
+    return { results: agentResults, allSucceeded, failedAgents, filesModified };
+  }
+}
+
+module.exports = { TeamCoordinator };