@polymorphism-tech/morph-spec 4.8.12 → 4.8.15

package/src/lib/orchestration/team-orchestrator.js

@@ -1,11 +1,13 @@
 /**
  * @fileoverview Hierarchical Agent Teams Orchestrator
  *
- * Builds Agent Teams using 4-tier hierarchy:
- * - Tier 1: Orchestrators (Team Lead in delegate mode)
- * - Tier 2: Domain Leaders (Squad Leaders)
- * - Tier 3: Specialists (Domain experts)
- * - Tier 4: Validators (Run in hooks, not teammates)
+ * Builds Agent Teams using flattened 2-tier hierarchy:
+ * - Lead: standards-architect (in delegate mode, quality gate)
+ * - Teammates: Tier-2 domain leaders (each with specialists in their spawn prompt)
+ *
+ * NOTE: Agent Teams does NOT support nested teams (a teammate cannot spawn
+ * teammates). Therefore Tier-3 specialists are described in domain leader
+ * spawn prompts, not as separate teammates.
  *
  * @module team-orchestrator
  */
@@ -29,75 +31,87 @@ async function loadAgentsConfig(projectPath) {
 }
 
 /**
- * Detect if Agent Teams should be spawned based on complexity
+ * Detect whether Agent Teams, subagents, or a single session should be used.
+ *
+ * Returns one of three modes:
+ * - 'agent-teams': complexity=critical OR (multiDomain AND estimatedFiles>=15)
+ * - 'subagents': shouldDispatch=true but below agent-teams threshold
+ * - 'single': trivial/low complexity or no parallelization benefit
+ *
  * @param {Object} options
  * @param {string[]} options.activeAgents - Agent IDs detected for feature
  * @param {string} options.complexity - Complexity level (trivial|low|medium|high|critical)
  * @param {number} options.estimatedFiles - Estimated files to modify
  * @param {boolean} options.multiDomain - Does feature span multiple domains?
- * @returns {Object} { shouldSpawn: boolean, reason: string, recommendedMode: string }
+ * @returns {{ mode: 'single'|'subagents'|'agent-teams', reason: string }}
  */
 export function shouldSpawnAgentTeam(options) {
   const { activeAgents = [], complexity, estimatedFiles = 0, multiDomain = false } = options;
 
-  // Never spawn for trivial/low complexity
+  // Never parallelize for trivial/low complexity
   if (complexity === 'trivial' || complexity === 'low') {
     return {
-      shouldSpawn: false,
-      reason: 'Complexity too low - single session sufficient',
-      recommendedMode: 'single'
+      mode: 'single',
+      reason: 'Complexity too low — single session sufficient',
     };
   }
 
-  // Always spawn for critical complexity
+  // Agent Teams for critical complexity (max parallelization needed)
   if (complexity === 'critical') {
     return {
-      shouldSpawn: true,
-      reason: 'Critical complexity - parallel coordination essential',
-      recommendedMode: 'tmux'
+      mode: 'agent-teams',
+      reason: 'Critical complexity — Agent Teams with plan approval essential',
+    };
+  }
+
+  // Agent Teams for large multi-domain features (backend + frontend need contract coordination)
+  if (multiDomain && estimatedFiles >= 15) {
+    return {
+      mode: 'agent-teams',
+      reason: `Multi-domain feature with ${estimatedFiles}+ files — Agent Teams for contract coordination`,
     };
   }
 
-  // Spawn if multi-domain (backend + frontend + infra)
+  // Subagents for multi-domain below agent-teams threshold
   if (multiDomain) {
     return {
-      shouldSpawn: true,
-      reason: 'Multi-domain feature - benefits from parallel squads',
-      recommendedMode: 'auto'
+      mode: 'subagents',
+      reason: 'Multi-domain feature — parallel subagents recommended',
     };
   }
 
-  // Spawn if 3+ independent modules (high file count)
+  // Subagents for high file count
   if (estimatedFiles >= 15) {
     return {
-      shouldSpawn: true,
-      reason: 'High file count - parallel implementation recommended',
-      recommendedMode: 'auto'
+      mode: 'subagents',
+      reason: `High file count (${estimatedFiles}) — parallel subagents recommended`,
     };
   }
 
-  // Spawn if 5+ specialists active (indicates complex coordination)
+  // Subagents when 5+ specialists are active
   if (activeAgents.length >= 5) {
     return {
-      shouldSpawn: true,
-      reason: '5+ specialists active - team coordination beneficial',
-      recommendedMode: 'auto'
+      mode: 'subagents',
+      reason: `${activeAgents.length} specialists active — subagents beneficial`,
     };
   }
 
   // Default: single session for medium complexity
   return {
-    shouldSpawn: false,
-    reason: 'Medium complexity - single session with subagents OK',
-    recommendedMode: 'single'
+    mode: 'single',
+    reason: 'Medium complexity — single session with subagents OK',
   };
 }
 
 /**
- * Build hierarchical team structure from active agents
+ * Build hierarchical team structure from active agents.
+ * Flattened to 2 tiers for Agent Teams compatibility:
+ * - Lead: standards-architect
+ * - Teammates: Tier-2 domain leaders (specialists are in their spawn prompts)
+ *
  * @param {string[]} activeAgentIds - Agent IDs to include in team
  * @param {Object} agentsConfig - Loaded agents.json
- * @returns {Object} Team structure with lead, domain leaders, specialists
+ * @returns {Object} Team structure with lead, domain leaders, specialists, validators
  */
 export function buildTeamHierarchy(activeAgentIds, agentsConfig) {
   const agents = agentsConfig.agents;
@@ -109,45 +123,112 @@ export function buildTeamHierarchy(activeAgentIds, agentsConfig) {
   const orchestrators = activeAgents.filter(a => a.tier === 1 && a.role === 'orchestrator');
   const teamLead = orchestrators.find(a => a.id === 'standards-architect') || orchestrators[0];
 
-  // Tier 2: Domain Leaders
+  // Tier 2: Domain Leaders (direct teammates in Agent Teams)
   const domainLeaders = activeAgents.filter(a => a.tier === 2 && a.role === 'domain-leader');
 
-  // Tier 3: Specialists (group by domain)
+  // Tier 3: Specialists (grouped under domain leaders, NOT separate teammates)
   const specialists = activeAgents.filter(a => a.tier === 3 && a.role === 'specialist');
 
   // Tier 4: Validators (run in hooks, NOT teammates)
   const validators = activeAgents.filter(a => a.tier === 4 && a.role === 'validator');
 
-  // Group specialists under their Domain Leaders
+  // Group specialists under their Domain Leaders for spawn prompt inclusion
   const squads = {};
   domainLeaders.forEach(leader => {
     const squadMembers = specialists.filter(specialist => {
-      // Check if specialist reports to this leader
       return specialist.relationships?.reports_to === leader.id;
     });
 
-    if (squadMembers.length > 0) {
-      squads[leader.id] = {
-        leader,
-        members: squadMembers
-      };
-    }
+    squads[leader.id] = {
+      leader,
+      members: squadMembers,
+    };
   });
 
   return {
     teamLead,
     squads,
-    validators, // Not in teammates, run as hooks
-    totalTeammates: 1 + domainLeaders.length + specialists.length // Lead + Leaders + Specialists
+    validators, // Run as hooks, not teammates
+    // Teammates = lead + domain leaders only (not tier-3 specialists)
+    totalTeammates: 1 + domainLeaders.length,
   };
 }
 
 /**
- * Generate teammate spawn instructions for Agent Teams
+ * Generate natural-language Agent Team creation prompt.
+ *
+ * Returns a string ready to be sent to Claude as instructions to create
+ * an agent team. Domain leaders are teammates; their tier-3 specialists
+ * are described within each leader's spawn context.
+ *
  * @param {Object} teamHierarchy - Output from buildTeamHierarchy
  * @param {string} featureName - Feature name
  * @param {string} phase - Current MORPH phase
- * @returns {Object[]} Array of teammate configs for Agent Teams
+ * @returns {string} Natural language team creation instructions
+ */
+export function generateAgentTeamPrompt(teamHierarchy, featureName, phase) {
+  const { teamLead, squads } = teamHierarchy;
+  const squadEntries = Object.entries(squads);
+
+  if (squadEntries.length === 0) {
+    return `No multi-domain squad found for feature '${featureName}'. Use single session or subagents instead.`;
+  }
+
+  const teammateCount = squadEntries.length + 1; // domain leaders + quality lead
+  const lines = [
+    `Create an agent team to implement feature '${featureName}' with ${teammateCount} teammates:`,
+    '',
+  ];
+
+  for (const [leaderId, squad] of squadEntries) {
+    const leader = squad.leader;
+    const domain = leader.domains?.[0] || leaderId;
+    const specialistList = squad.members.length > 0
+      ? squad.members.map(m => m.title || m.id).join(', ')
+      : 'none';
+
+    lines.push(`- ${leader.title || leaderId} teammate (${leaderId}): Implement ${domain} tasks.`);
+    lines.push(`  Context: spec.md, contracts.cs, standards/${domain}/`);
+    if (squad.members.length > 0) {
+      lines.push(`  Specialists to coordinate (in your spawn prompt): ${specialistList}`);
+    }
+    lines.push(`  Restriction: Modify ONLY files in the ${domain} domain.`);
+    lines.push('');
+  }
+
+  const leadId = teamLead?.id || 'standards-architect';
+  lines.push(`- Quality teammate (${leadId}): Review each teammate's output and run validate-feature.`);
+  lines.push('  Require plan approval before implementing. Only approve plans that match contracts.cs.');
+  lines.push('');
+  lines.push('Coordination protocol:');
+  lines.push('  - Backend must signal when contracts.cs/DTOs are stable before frontend implements API calls.');
+  lines.push('  - If teammates need to share interfaces, send a direct message to coordinate first.');
+  lines.push('  - Escalate contract conflicts to the quality teammate to resolve.');
+
+  return lines.join('\n');
+}
+
+/**
+ * Generate team instructions as natural language (renamed from generateSpawnCommand).
+ * Use this for Agent Teams mode.
+ *
+ * @param {Object} teamHierarchy - Output from buildTeamHierarchy
+ * @param {string} featureName - Feature name
+ * @param {string} phase - Current MORPH phase
+ * @returns {string} Natural language team creation instructions
+ */
+export function generateTeamInstructions(teamHierarchy, featureName, phase) {
+  return generateAgentTeamPrompt(teamHierarchy, featureName, phase);
+}
+
+/**
+ * Generate teammate spawn configs for subagent dispatch (unchanged from v1).
+ * Use this for 'subagents' mode (not Agent Teams).
+ *
+ * @param {Object} teamHierarchy - Output from buildTeamHierarchy
+ * @param {string} featureName - Feature name
+ * @param {string} phase - Current MORPH phase
+ * @returns {Object[]} Array of teammate configs for Task tool subagents
  */
 export function generateTeammateConfigs(teamHierarchy, featureName, phase) {
   const teammates = [];
@@ -176,7 +257,6 @@ DO NOT implement code yourself. Coordinate Domain Leaders, resolve conflicts, sy
   Object.entries(squads).forEach(([leaderId, squad]) => {
     const leader = squad.leader;
 
-    // Add Domain Leader
     if (leader.teammate) {
       teammates.push({
         id: leader.id,
@@ -195,7 +275,6 @@ Coordinate your specialists. Escalate conflicts to ${leader.relationships.escala
       });
     }
 
-    // Add Specialists in this squad
     squad.members.forEach(specialist => {
       if (specialist.teammate) {
         teammates.push({
@@ -222,33 +301,22 @@ ${specialist.relationships.collaborates_with ?
 }
 
 /**
- * Generate Agent Teams command for spawning
- * @param {Object[]} teammates - Output from generateTeammateConfigs
- * @param {string} displayMode - 'auto' | 'in-process' | 'tmux'
- * @returns {string} Command to spawn Agent Teams
+ * @deprecated Use generateTeamInstructions() instead.
+ * Kept for backward compatibility — will be removed in a future version.
  */
-export function generateSpawnCommand(teammates, displayMode = 'auto') {
-  // Agent Teams are spawned via Claude Code's Task tool with subagent_type="general-purpose"
-  // and special teammate configs. This is a conceptual representation.
-
-  const command = {
-    tool: 'Task',
-    subagent_type: 'general-purpose',
-    agent_teams_enabled: true,
-    display_mode: displayMode,
-    teammates: teammates.map(t => ({
-      id: t.id,
-      role: t.role,
-      icon: t.icon,
-      prompt: t.spawnPrompt
-    }))
-  };
-
-  return JSON.stringify(command, null, 2);
+export function generateSpawnCommand(teammates, _displayMode = 'auto') {
+  // Returns legacy JSON format for any code still calling the old signature.
+  // New code should call generateTeamInstructions(teamHierarchy, featureName, phase).
+  return JSON.stringify({
+    _deprecated: true,
+    _message: 'Use generateTeamInstructions() for Agent Teams mode.',
+    teammates: teammates.map(t => ({ id: t.id, role: t.role })),
+  }, null, 2);
 }
 
 /**
- * Main orchestration function - decides if/when to spawn Agent Teams
+ * Main orchestration function — decides if/when to use Agent Teams vs subagents.
+ *
  * @param {Object} options
  * @param {string} options.projectPath - Project root path
  * @param {string} options.featureName - Feature name
@@ -267,22 +335,22 @@ export async function orchestrateTeam(options) {
     activeAgents = [],
     complexity,
     estimatedFiles = 0,
-    multiDomain = false
+    multiDomain = false,
   } = options;
 
-  // Step 1: Decide if Agent Teams should spawn
-  const spawnDecision = shouldSpawnAgentTeam({
+  // Step 1: Decide mode
+  const modeDecision = shouldSpawnAgentTeam({
     activeAgents,
     complexity,
     estimatedFiles,
-    multiDomain
+    multiDomain,
   });
 
-  if (!spawnDecision.shouldSpawn) {
+  if (modeDecision.mode === 'single') {
     return {
-      useAgentTeams: false,
-      reason: spawnDecision.reason,
-      recommendation: 'Use single session with Task tool for subagents'
+      mode: 'single',
+      reason: modeDecision.reason,
+      recommendation: 'Use single session — sequential implementation',
     };
   }
 
@@ -290,25 +358,39 @@ export async function orchestrateTeam(options) {
   const agentsConfig = await loadAgentsConfig(projectPath);
   const teamHierarchy = buildTeamHierarchy(activeAgents, agentsConfig);
 
-  // Step 3: Generate teammate configs
-  const teammates = generateTeammateConfigs(teamHierarchy, featureName, phase);
+  if (modeDecision.mode === 'agent-teams') {
+    // Step 3a: Generate natural language Agent Teams instructions
+    const teamInstructions = generateTeamInstructions(teamHierarchy, featureName, phase);
 
-  // Step 4: Generate spawn command
-  const spawnCommand = generateSpawnCommand(teammates, spawnDecision.recommendedMode);
+    return {
+      mode: 'agent-teams',
+      reason: modeDecision.reason,
+      teamHierarchy: {
+        teamLead: teamHierarchy.teamLead?.id,
+        squads: Object.keys(teamHierarchy.squads),
+        totalTeammates: teamHierarchy.totalTeammates,
+        validators: teamHierarchy.validators.map(v => v.id),
+      },
+      teamInstructions,
+      recommendation: `Create Agent Team with ${teamHierarchy.totalTeammates} teammates (lead + domain leaders). Require plan approval before implementation.`,
+    };
+  }
+
+  // mode === 'subagents'
+  // Step 3b: Generate Task tool subagent configs
+  const teammates = generateTeammateConfigs(teamHierarchy, featureName, phase);
 
   return {
-    useAgentTeams: true,
-    reason: spawnDecision.reason,
-    displayMode: spawnDecision.recommendedMode,
+    mode: 'subagents',
+    reason: modeDecision.reason,
     teamHierarchy: {
       teamLead: teamHierarchy.teamLead?.id,
       squads: Object.keys(teamHierarchy.squads),
       totalTeammates: teamHierarchy.totalTeammates,
-      validators: teamHierarchy.validators.map(v => v.id)
+      validators: teamHierarchy.validators.map(v => v.id),
     },
     teammates,
-    spawnCommand,
-    recommendation: `Spawn ${teamHierarchy.totalTeammates} teammates in ${spawnDecision.recommendedMode} mode`
+    recommendation: `Dispatch ${teammates.length} Task subagents in parallel`,
   };
 }
 

package/src/lib/phase-chain/eligibility-checker.js

@@ -0,0 +1,243 @@
+/**
+ * Phase Eligibility Checker
+ *
+ * Determines whether a feature is eligible to auto-advance to the next phase.
+ * Used by phase-runner.js and the dispatch.js PostToolUse hook.
+ *
+ * Eligibility criteria (all must pass):
+ *   1. Required outputs for the current phase exist on disk
+ *   2. No tasks in state with status = 'blocked'
+ *   3. validationHistory passRate >= minPassRate (from workflow config)
+ *   4. Trust level meets the workflow's trustLevel requirement
+ */
+
+import { existsSync } from 'fs';
+import { join } from 'path';
+import { loadState } from '../../core/state/state-manager.js';
+import { getWorkflowConfig } from '../../core/workflows/workflow-detector.js';
+import { derivePhase } from '../../core/state/state-manager.js';
+import { PHASES } from '../../commands/state/validate-phase.js';
+import { shouldAutoApprove } from '../trust/trust-manager.js';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types (JSDoc)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * @typedef {Object} EligibilityBlocker
+ * @property {'missing_outputs'|'blocked_tasks'|'low_pass_rate'|'trust_too_low'|'state_error'} type
+ * @property {string[]} [items] - Specific items causing the block
+ * @property {number} [current] - Current value (for rate/level comparisons)
+ * @property {number|string} [required] - Required value
+ */
+
+/**
+ * @typedef {Object} EligibilityResult
+ * @property {boolean} eligible
+ * @property {EligibilityBlocker[]} blockers
+ * @property {string} currentPhase
+ * @property {string|null} nextPhase
+ * @property {number|null} passRate - Current validation pass rate (null if no data)
+ */
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Phase order (canonical from advance-phase.js) */
+const PHASE_ORDER = ['proposal', 'setup', 'uiux', 'design', 'clarify', 'tasks', 'implement', 'sync'];
+
+/**
+ * Get the next phase in the standard sequence.
+ * Returns null when at the last phase.
+ */
+function getNextPhase(currentPhase) {
+  const idx = PHASE_ORDER.indexOf(currentPhase);
+  if (idx === -1 || idx >= PHASE_ORDER.length - 1) return null;
+  return PHASE_ORDER[idx + 1];
+}
+
+/**
+ * Compute the overall validation pass rate from validationHistory.
+ * Returns null when no history exists.
+ *
+ * @param {Object} validationHistory - feature.validationHistory
+ * @returns {number|null}
+ */
+export function computePassRate(validationHistory) {
+  if (!validationHistory || Object.keys(validationHistory).length === 0) return null;
+
+  const entries = Object.values(validationHistory);
+  const total = entries.length;
+  const passed = entries.filter(e => e.status === 'passed').length;
+
+  return total > 0 ? passed / total : null;
+}
+
+/**
+ * Check if required outputs exist on disk for the given phase.
+ *
+ * @param {string} featureName
+ * @param {string} phase
+ * @param {string} projectPath
+ * @returns {string[]} Array of missing output descriptions
+ */
+function getMissingRequiredOutputs(featureName, phase, projectPath) {
+  const phaseDef = PHASES[phase];
+  if (!phaseDef?.requiredOutputs) return [];
+
+  const missing = [];
+  const featureBase = join(projectPath, '.morph', 'features', featureName);
+
+  // Map output type names to common file paths
+  const outputPathMap = {
+    'proposal': '0-proposal/proposal.md',
+    'spec': '1-design/spec.md',
+    'contracts': '1-design/contracts.cs',
+    'tasks': '3-tasks/tasks.md',
+    'schemaAnalysis': '1-design/schema-analysis.md',
+  };
+
+  for (const output of phaseDef.requiredOutputs) {
+    const relPath = outputPathMap[output];
+    if (relPath && !existsSync(join(featureBase, relPath))) {
+      missing.push(output);
+    }
+  }
+
+  return missing;
+}
+
+/**
+ * Get tasks that are blocked (attempt >= 3, no resolution).
+ *
+ * @param {Object} feature - Feature state object
+ * @returns {string[]} Array of blocked task IDs
+ */
+function getBlockedTasks(feature) {
+  const history = feature.validationHistory || {};
+  return Object.entries(history)
+    .filter(([, entry]) => entry.status === 'blocked')
+    .map(([taskId]) => taskId);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Main export
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Check whether a feature is eligible to auto-advance to the next phase.
+ *
+ * @param {string} featureName
+ * @param {Object} [opts]
+ * @param {string} [opts.projectPath] - Project root (defaults to cwd)
+ * @param {boolean} [opts.dryRun] - Only compute, don't enforce
+ * @returns {EligibilityResult}
+ */
+export function checkPhaseEligibility(featureName, opts = {}) {
+  const projectPath = opts.projectPath || process.cwd();
+
+  // ── Load state ────────────────────────────────────────────────────────────
+  const state = loadState(false);
+  if (!state) {
+    return {
+      eligible: false,
+      blockers: [{ type: 'state_error', items: ['state.json not found'] }],
+      currentPhase: 'unknown',
+      nextPhase: null,
+      passRate: null,
+    };
+  }
+
+  const feature = state.features?.[featureName];
+  if (!feature) {
+    return {
+      eligible: false,
+      blockers: [{ type: 'state_error', items: [`Feature '${featureName}' not found in state.json`] }],
+      currentPhase: 'unknown',
+      nextPhase: null,
+      passRate: null,
+    };
+  }
+
+  // ── Derive current phase ──────────────────────────────────────────────────
+  const featureFolderPath = join(projectPath, '.morph', 'features', featureName);
+  const currentPhase = feature.phase || derivePhase(featureFolderPath);
+  const nextPhase = getNextPhase(currentPhase);
+
+  if (!nextPhase) {
+    return {
+      eligible: false,
+      blockers: [{ type: 'state_error', items: ['Feature is at the final phase'] }],
+      currentPhase,
+      nextPhase: null,
+      passRate: null,
+    };
+  }
+
+  // ── Load workflow config ──────────────────────────────────────────────────
+  let workflowConfig = null;
+  if (feature.workflow && feature.workflow !== 'auto') {
+    try {
+      workflowConfig = getWorkflowConfig(feature.workflow);
+    } catch {
+      // Non-blocking: fall through to defaults
+    }
+  }
+
+  const minPassRate = workflowConfig?.phaseChain?.pauseOn
+    ? 0.80  // Default minimum
+    : workflowConfig?.eligibility?.minPassRate ?? 0.80;
+
+  const blockers = [];
+
+  // ── Check 1: Missing required outputs ────────────────────────────────────
+  const missingOutputs = getMissingRequiredOutputs(featureName, currentPhase, projectPath);
+  if (missingOutputs.length > 0) {
+    blockers.push({ type: 'missing_outputs', items: missingOutputs });
+  }
+
+  // ── Check 2: Blocked tasks ────────────────────────────────────────────────
+  const blockedTasks = getBlockedTasks(feature);
+  if (blockedTasks.length > 0) {
+    blockers.push({ type: 'blocked_tasks', items: blockedTasks });
+  }
+
+  // ── Check 3: Validation pass rate ────────────────────────────────────────
+  const passRate = computePassRate(feature.validationHistory);
+  if (passRate !== null && passRate < minPassRate) {
+    blockers.push({
+      type: 'low_pass_rate',
+      current: passRate,
+      required: minPassRate,
+    });
+  }
+
+  // ── Check 4: Trust level ─────────────────────────────────────────────────
+  try {
+    const requiredGateMap = { design: 'design', tasks: 'tasks', uiux: 'uiux' };
+    const gate = requiredGateMap[currentPhase];
+    if (gate) {
+      const trustResult = shouldAutoApprove(featureName, gate);
+      if (!trustResult.autoApprove) {
+        const gateStatus = feature.approvalGates?.[gate];
+        if (!gateStatus?.approved) {
+          blockers.push({
+            type: 'trust_too_low',
+            items: [`Gate '${gate}' requires trust level ${trustResult.level || 'medium+'}`],
+          });
+        }
+      }
+    }
+  } catch {
+    // Trust manager unavailable — non-blocking, don't add blocker
+  }
+
+  return {
+    eligible: blockers.length === 0,
+    blockers,
+    currentPhase,
+    nextPhase,
+    passRate,
+  };
+}