@polymorphism-tech/morph-spec 4.8.19 → 4.10.0

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

@@ -1,404 +0,0 @@
-/**
- * @fileoverview Hierarchical Agent Teams Orchestrator
- *
- * 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
- */
-
-import fs from 'fs/promises';
-import path from 'path';
-import { fileURLToPath } from 'url';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-
-/**
- * Load agents.json with hierarchical structure
- * @param {string} projectPath - Root path of the project
- * @returns {Promise<Object>} Parsed agents configuration
- */
-async function loadAgentsConfig(projectPath) {
-  const agentsPath = path.join(projectPath, '.morph/framework/agents.json');
-  const content = await fs.readFile(agentsPath, 'utf8');
-  return JSON.parse(content);
-}
-
-/**
- * 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 {{ mode: 'single'|'subagents'|'agent-teams', reason: string }}
- */
-export function shouldSpawnAgentTeam(options) {
-  const { activeAgents = [], complexity, estimatedFiles = 0, multiDomain = false } = options;
-
-  // Never parallelize for trivial/low complexity
-  if (complexity === 'trivial' || complexity === 'low') {
-    return {
-      mode: 'single',
-      reason: 'Complexity too low — single session sufficient',
-    };
-  }
-
-  // Agent Teams for critical complexity (max parallelization needed)
-  if (complexity === 'critical') {
-    return {
-      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`,
-    };
-  }
-
-  // Subagents for multi-domain below agent-teams threshold
-  if (multiDomain) {
-    return {
-      mode: 'subagents',
-      reason: 'Multi-domain feature — parallel subagents recommended',
-    };
-  }
-
-  // Subagents for high file count
-  if (estimatedFiles >= 15) {
-    return {
-      mode: 'subagents',
-      reason: `High file count (${estimatedFiles}) — parallel subagents recommended`,
-    };
-  }
-
-  // Subagents when 5+ specialists are active
-  if (activeAgents.length >= 5) {
-    return {
-      mode: 'subagents',
-      reason: `${activeAgents.length} specialists active — subagents beneficial`,
-    };
-  }
-
-  // Default: single session for medium complexity
-  return {
-    mode: 'single',
-    reason: 'Medium complexity — single session with subagents OK',
-  };
-}
-
-/**
- * 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, validators
- */
-export function buildTeamHierarchy(activeAgentIds, agentsConfig) {
-  const agents = agentsConfig.agents;
-  const activeAgents = activeAgentIds
-    .filter(id => !id.startsWith('_comment') && agents[id])
-    .map(id => ({ id, ...agents[id] }));
-
-  // Tier 1: Orchestrator (Team Lead)
-  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 (direct teammates in Agent Teams)
-  const domainLeaders = activeAgents.filter(a => a.tier === 2 && a.role === 'domain-leader');
-
-  // 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 for spawn prompt inclusion
-  const squads = {};
-  domainLeaders.forEach(leader => {
-    const squadMembers = specialists.filter(specialist => {
-      return specialist.relationships?.reports_to === leader.id;
-    });
-
-    squads[leader.id] = {
-      leader,
-      members: squadMembers,
-    };
-  });
-
-  return {
-    teamLead,
-    squads,
-    validators, // Run as hooks, not teammates
-    // Teammates = lead + domain leaders only (not tier-3 specialists)
-    totalTeammates: 1 + domainLeaders.length,
-  };
-}
-
-/**
- * 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 {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 = [];
-  const { teamLead, squads } = teamHierarchy;
-
-  // Add Team Lead (standards-architect in delegate mode)
-  if (teamLead && teamLead.teammate) {
-    teammates.push({
-      id: teamLead.id,
-      tier: teamLead.tier,
-      role: teamLead.teammate.role,
-      icon: teamLead.teammate.icon,
-      spawnPrompt: `${teamLead.teammate.spawn_prompt}
-
-Feature: ${featureName}
-Phase: ${phase}
-
-Your Domain Leaders:
-${Object.values(squads).map(s => `- ${s.leader.title} (${s.leader.id})`).join('\n')}
-
-DO NOT implement code yourself. Coordinate Domain Leaders, resolve conflicts, synthesize results.`
-    });
-  }
-
-  // Add Domain Leaders + their squad members
-  Object.entries(squads).forEach(([leaderId, squad]) => {
-    const leader = squad.leader;
-
-    if (leader.teammate) {
-      teammates.push({
-        id: leader.id,
-        tier: leader.tier,
-        role: leader.teammate.role,
-        icon: leader.teammate.icon,
-        spawnPrompt: `${leader.teammate.spawn_prompt}
-
-Feature: ${featureName}
-Phase: ${phase}
-
-Your Squad (${squad.members.length} specialists):
-${squad.members.map(m => `- ${m.title} (${m.id})`).join('\n')}
-
-Coordinate your specialists. Escalate conflicts to ${leader.relationships.escalates_to}.`
-      });
-    }
-
-    squad.members.forEach(specialist => {
-      if (specialist.teammate) {
-        teammates.push({
-          id: specialist.id,
-          tier: specialist.tier,
-          role: specialist.teammate.role,
-          icon: specialist.teammate.icon,
-          spawnPrompt: `${specialist.teammate.spawn_prompt}
-
-Feature: ${featureName}
-Phase: ${phase}
-
-Reports to: ${specialist.relationships.reports_to}
-Escalate to: ${specialist.relationships.escalates_to}
-
-${specialist.relationships.collaborates_with ?
-  `Collaborate with: ${specialist.relationships.collaborates_with.join(', ')}` : ''}`
-        });
-      }
-    });
-  });
-
-  return teammates;
-}
-
-/**
- * @deprecated Use generateTeamInstructions() instead.
- * Kept for backward compatibility — will be removed in a future version.
- */
-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 use Agent Teams vs subagents.
- *
- * @param {Object} options
- * @param {string} options.projectPath - Project root path
- * @param {string} options.featureName - Feature name
- * @param {string} options.phase - MORPH phase
- * @param {string[]} options.activeAgents - Active agent IDs
- * @param {string} options.complexity - Complexity level
- * @param {number} options.estimatedFiles - Estimated file count
- * @param {boolean} options.multiDomain - Multi-domain feature?
- * @returns {Promise<Object>} Team orchestration result
- */
-export async function orchestrateTeam(options) {
-  const {
-    projectPath,
-    featureName,
-    phase,
-    activeAgents = [],
-    complexity,
-    estimatedFiles = 0,
-    multiDomain = false,
-  } = options;
-
-  // Step 1: Decide mode
-  const modeDecision = shouldSpawnAgentTeam({
-    activeAgents,
-    complexity,
-    estimatedFiles,
-    multiDomain,
-  });
-
-  if (modeDecision.mode === 'single') {
-    return {
-      mode: 'single',
-      reason: modeDecision.reason,
-      recommendation: 'Use single session — sequential implementation',
-    };
-  }
-
-  // Step 2: Load agents config and build hierarchy
-  const agentsConfig = await loadAgentsConfig(projectPath);
-  const teamHierarchy = buildTeamHierarchy(activeAgents, agentsConfig);
-
-  if (modeDecision.mode === 'agent-teams') {
-    // Step 3a: Generate natural language Agent Teams instructions
-    const teamInstructions = generateTeamInstructions(teamHierarchy, featureName, phase);
-
-    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 {
-    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),
-    },
-    teammates,
-    recommendation: `Dispatch ${teammates.length} Task subagents in parallel`,
-  };
-}
-
-/**
- * Get agent squad assignments (for informational purposes)
- * @param {Object} agentsConfig - Loaded agents.json
- * @returns {Object} Squad information
- */
-export function getSquadInfo(agentsConfig) {
-  return agentsConfig.squads || {};
-}

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

@@ -1,243 +0,0 @@
-/**
- * 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,
-  };
-}