@polymorphism-tech/morph-spec 4.10.6 → 4.10.8

package/src/lib/agents/agents-manager.js

@@ -0,0 +1,349 @@
+/**
+ * agents-manager.js — Core logic for agent CRUD operations
+ *
+ * Pure functions that accept agentsData object. File I/O only in
+ * loadAgentsFile / saveAgentsFile. All other functions are testable
+ * with fixture data.
+ *
+ * @module agents-manager
+ */
+
+import { existsSync, readFileSync, writeFileSync, renameSync } from 'node:fs';
+import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+// ── Constants ──────────────────────────────────────────────────────────────────
+
+/** Known valid phases for active_phases validation */
+export const KNOWN_PHASES = [
+  'proposal', 'setup', 'uiux', 'design',
+  'clarify', 'plan', 'tasks', 'implement',
+];
+
+/** Tier labels for display and validation */
+export const TIER_LABELS = {
+  1: 'orchestrator',
+  2: 'leader',
+  3: 'specialist',
+  4: 'validator',
+};
+
+/** Tier metadata key names in agents.json */
+export const TIER_KEYS = {
+  1: 'tier_1_orchestrators',
+  2: 'tier_2_leaders',
+  3: 'tier_3_specialists',
+  4: 'tier_4_validators',
+};
+
+/** Agent ID pattern: kebab-case starting with a letter */
+export const AGENT_ID_PATTERN = /^[a-z][a-z0-9-]*$/;
+
+// ── Validation ─────────────────────────────────────────────────────────────────
+
+/**
+ * Validate agent fields.
+ * @param {string} id
+ * @param {object} fields
+ * @param {string[]} existingIds - IDs already in agents.json (for uniqueness check)
+ * @param {string[]} [knownGroups] - Known group names (for warnings)
+ * @param {object} [allAgents] - Full agents map (for circular reports_to check)
+ * @returns {{ valid: boolean, errors: string[], warnings: string[] }}
+ */
+export function validateAgent(id, fields, existingIds = [], knownGroups = [], allAgents = {}) {
+  const errors = [];
+  const warnings = [];
+
+  // ID validation
+  if (!AGENT_ID_PATTERN.test(id)) {
+    errors.push('Agent ID must be kebab-case (lowercase letters, numbers, hyphens) and start with a letter');
+  }
+  if (existingIds.includes(id)) {
+    errors.push(`Agent ID '${id}' is not unique — already exists in agents.json`);
+  }
+
+  // Tier
+  const tier = fields.tier;
+  if (tier == null || !Number.isInteger(tier) || tier < 1 || tier > 4) {
+    errors.push('Tier must be 1 (orchestrator), 2 (leader), 3 (specialist), or 4 (validator)');
+  }
+
+  // Title
+  if (!fields.title || typeof fields.title !== 'string' || fields.title.trim() === '') {
+    errors.push('Title is required');
+  }
+
+  // Group
+  if (!fields.group || typeof fields.group !== 'string' || fields.group.trim() === '') {
+    errors.push('Group is required');
+  } else if (knownGroups.length > 0 && !knownGroups.includes(fields.group)) {
+    warnings.push(`Unknown group '${fields.group}' — known groups: ${knownGroups.join(', ')}`);
+  }
+
+  // Active phases
+  if (fields.active_phases) {
+    const phases = fields.active_phases;
+    if (!Array.isArray(phases)) {
+      errors.push('active_phases must be an array');
+    } else if (phases.length === 1 && phases[0] === '*') {
+      // wildcard — valid
+    } else {
+      for (const p of phases) {
+        if (!KNOWN_PHASES.includes(p)) {
+          errors.push(`Invalid phase '${p}' — valid: ${KNOWN_PHASES.join(', ')}`);
+        }
+      }
+    }
+  }
+
+  // reports_to — circular check
+  if (fields.reports_to) {
+    if (fields.reports_to === id) {
+      errors.push('Agent cannot report to itself');
+    } else if (fields.reports_to !== 'user' && allAgents && Object.keys(allAgents).length > 0) {
+      // Walk the chain to detect cycles
+      const visited = new Set([id]);
+      let current = fields.reports_to;
+      while (current && current !== 'user') {
+        if (visited.has(current)) {
+          errors.push(`Circular reports_to chain detected: ${[...visited, current].join(' \u2192 ')}`);
+          break;
+        }
+        visited.add(current);
+        current = allAgents[current]?.reports_to;
+      }
+    }
+  }
+
+  // spawn_prompt required for tier >= 3
+  if (Number.isInteger(tier) && tier >= 3) {
+    const hasPrompt = fields.teammate?.spawn_prompt ||
+      (typeof fields.spawn_prompt === 'string' && fields.spawn_prompt.trim());
+    if (!hasPrompt) {
+      errors.push('spawn_prompt is required for tier 3+ agents');
+    }
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}
+
+// ── Metadata Sync ──────────────────────────────────────────────────────────────
+
+/**
+ * Recalculate total_agents and tier counts.
+ * @param {object} agentsData - Full agents.json data
+ * @returns {object} Updated agentsData (mutated in place + returned)
+ */
+export function syncMetadata(agentsData) {
+  const agents = agentsData.agents || {};
+  const entries = Object.values(agents);
+
+  agentsData.total_agents = entries.length;
+  agentsData.tiers = {
+    tier_1_orchestrators: entries.filter(a => a.tier === 1).length,
+    tier_2_leaders: entries.filter(a => a.tier === 2).length,
+    tier_3_specialists: entries.filter(a => a.tier === 3).length,
+    tier_4_validators: entries.filter(a => a.tier === 4).length,
+  };
+
+  return agentsData;
+}
+
+// ── List + Show ────────────────────────────────────────────────────────────────
+
+/**
+ * List agents with optional filters.
+ * @param {object} agentsData
+ * @param {{ group?: string, tier?: number }} [filters]
+ * @returns {{ agents: Array, groupCounts: Record<string, number>, total: number }}
+ */
+export function listAgents(agentsData, filters = {}) {
+  const agents = agentsData.agents || {};
+  let entries = Object.entries(agents).map(([id, data]) => ({ id, ...data }));
+
+  if (filters.group) {
+    entries = entries.filter(a => a.group === filters.group);
+  }
+  if (filters.tier != null) {
+    entries = entries.filter(a => a.tier === filters.tier);
+  }
+
+  entries.sort((a, b) => a.tier - b.tier || a.id.localeCompare(b.id));
+
+  // groupCounts over ALL agents (not filtered)
+  const groupCounts = {};
+  for (const a of Object.values(agents)) {
+    groupCounts[a.group] = (groupCounts[a.group] || 0) + 1;
+  }
+
+  return {
+    agents: entries.map(a => ({
+      id: a.id,
+      tier: a.tier,
+      title: a.title,
+      group: a.group,
+      phases: Array.isArray(a.active_phases) ? a.active_phases.join(',') : '*',
+      keywords: (a.keywords || []).join(', ') || '\u2014',
+    })),
+    groupCounts,
+    total: entries.length,
+  };
+}
+
+/**
+ * Show detailed info for a single agent.
+ * @param {object} agentsData
+ * @param {string} id
+ * @returns {object|null}
+ */
+export function showAgent(agentsData, id) {
+  return agentsData.agents?.[id] ?? null;
+}
+
+// ── Mutations ──────────────────────────────────────────────────────────────────
+
+/**
+ * Add a new agent.
+ * @param {object} agentsData
+ * @param {string} id
+ * @param {object} fields
+ * @returns {{ success: boolean, data?: object, changes?: string[], errors?: string[], warnings?: string[] }}
+ */
+export function addAgent(agentsData, id, fields) {
+  const existingIds = Object.keys(agentsData.agents || {});
+  const knownGroups = [...new Set(Object.values(agentsData.agents || {}).map(a => a.group))];
+  const validation = validateAgent(id, fields, existingIds, knownGroups, agentsData.agents);
+
+  if (!validation.valid) {
+    return { success: false, errors: validation.errors, warnings: validation.warnings };
+  }
+
+  const entry = {
+    tier: fields.tier,
+    title: fields.title,
+    group: fields.group,
+    active_phases: fields.active_phases || ['implement'],
+    reports_to: fields.reports_to || 'user',
+    domains: fields.domains || [],
+    keywords: fields.keywords || [],
+    validators: fields.validators || [],
+    standards: fields.standards || [],
+  };
+
+  if (fields.stacks) entry.stacks = fields.stacks;
+  if (fields.teammate) entry.teammate = fields.teammate;
+
+  agentsData.agents[id] = entry;
+  syncMetadata(agentsData);
+
+  return {
+    success: true,
+    data: agentsData,
+    changes: [`Added agent '${id}' (tier ${fields.tier}, group '${fields.group}')`],
+    warnings: validation.warnings,
+  };
+}
+
+/**
+ * Edit existing agent fields.
+ * @param {object} agentsData
+ * @param {string} id
+ * @param {object} changes
+ * @returns {{ success: boolean, data?: object, changes?: string[], errors?: string[] }}
+ */
+export function editAgent(agentsData, id, changes) {
+  const agent = agentsData.agents?.[id];
+  if (!agent) {
+    return { success: false, errors: [`Agent '${id}' not found`] };
+  }
+
+  const changedFields = [];
+
+  // Handle spawn_prompt shortcut -> nested teammate
+  if (changes.spawn_prompt) {
+    if (!agent.teammate) {
+      agent.teammate = { role: 'specialist', icon: '\u{1F527}', spawn_prompt: changes.spawn_prompt };
+    } else {
+      agent.teammate.spawn_prompt = changes.spawn_prompt;
+    }
+    changedFields.push('teammate.spawn_prompt');
+    delete changes.spawn_prompt;
+  }
+
+  // Apply direct field changes
+  for (const [key, value] of Object.entries(changes)) {
+    if (value !== undefined && agent[key] !== value) {
+      changedFields.push(key);
+      agent[key] = value;
+    }
+  }
+
+  if (changedFields.length === 0) {
+    return { success: true, data: agentsData, changes: ['No changes detected'] };
+  }
+
+  syncMetadata(agentsData);
+  return { success: true, data: agentsData, changes: changedFields.map(f => `${f} updated`) };
+}
+
+/**
+ * Remove an agent.
+ * @param {object} agentsData
+ * @param {string} id
+ * @returns {{ success: boolean, data?: object, dependents?: string[], errors?: string[] }}
+ */
+export function removeAgent(agentsData, id) {
+  if (!agentsData.agents?.[id]) {
+    return { success: false, errors: [`Agent '${id}' not found`] };
+  }
+
+  // Find dependents
+  const dependents = Object.entries(agentsData.agents)
+    .filter(([aid, a]) => aid !== id && a.reports_to === id)
+    .map(([aid]) => aid);
+
+  delete agentsData.agents[id];
+  syncMetadata(agentsData);
+
+  return { success: true, data: agentsData, dependents };
+}
+
+// ── File I/O ───────────────────────────────────────────────────────────────────
+
+/**
+ * Load and parse agents.json.
+ * @param {string} filePath
+ * @returns {object}
+ * @throws {Error} If file not found or invalid JSON
+ */
+export function loadAgentsFile(filePath) {
+  if (!existsSync(filePath)) {
+    throw new Error(`agents.json not found at ${filePath}. Run 'morph-spec doctor' to diagnose.`);
+  }
+
+  try {
+    const content = readFileSync(filePath, 'utf8');
+    return JSON.parse(content);
+  } catch (err) {
+    if (err instanceof SyntaxError) {
+      throw new Error(`Failed to parse agents.json: ${err.message}. Run 'morph-spec doctor' to diagnose.`);
+    }
+    throw err;
+  }
+}
+
+/**
+ * Write agents.json atomically (write to .tmp, then rename).
+ * @param {string} filePath
+ * @param {object} agentsData
+ */
+export function saveAgentsFile(filePath, agentsData) {
+  const dir = dirname(filePath);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+
+  const tmpPath = `${filePath}.tmp.${process.pid}`;
+  writeFileSync(tmpPath, JSON.stringify(agentsData, null, 2) + '\n', 'utf8');
+  renameSync(tmpPath, filePath);
+}

package/src/lib/agents/metrics-calculator.js

@@ -0,0 +1,125 @@
+/**
+ * Agent Metrics Calculator — Pure computation, no I/O.
+ *
+ * Calculates per-agent performance metrics from dispatch log entries.
+ */
+
+/**
+ * Calculate per-agent metrics from dispatch log entries.
+ * @param {Array} dispatchLog - Array of dispatch entries
+ * @returns {{ agents: Array, summary: Object }}
+ */
+export function calculateMetrics(dispatchLog) {
+  if (!Array.isArray(dispatchLog) || dispatchLog.length === 0) {
+    return {
+      agents: [],
+      summary: { totalDispatches: 0, totalTasks: 0, completedTasks: 0, completionRate: 0, avgTaskDurationMs: null }
+    };
+  }
+
+  const agentMap = new Map();
+
+  for (const entry of dispatchLog) {
+    for (const agent of entry.agents || []) {
+      if (!agentMap.has(agent.id)) {
+        agentMap.set(agent.id, { dispatches: 0, tasksAssigned: 0, tasksCompleted: 0, durations: [] });
+      }
+      const acc = agentMap.get(agent.id);
+      acc.dispatches += 1;
+      acc.tasksAssigned += (agent.tasks || []).length;
+      acc.tasksCompleted += (agent.tasksCompleted || []).length;
+
+      if (agent.startedAt && agent.completedAt) {
+        const start = new Date(agent.startedAt).getTime();
+        const end = new Date(agent.completedAt).getTime();
+        if (!isNaN(start) && !isNaN(end) && end >= start) {
+          acc.durations.push(end - start);
+        }
+      }
+    }
+  }
+
+  const agents = [];
+  let totalDurationAll = 0;
+  let agentsWithDuration = 0;
+
+  for (const [id, acc] of agentMap) {
+    const totalDurationMs = acc.durations.length > 0
+      ? acc.durations.reduce((s, d) => s + d, 0)
+      : null;
+    const avgDurationMs = acc.durations.length > 0
+      ? Math.round(totalDurationMs / acc.durations.length)
+      : null;
+
+    if (totalDurationMs !== null) {
+      totalDurationAll += totalDurationMs;
+      agentsWithDuration++;
+    }
+
+    agents.push({
+      id,
+      dispatches: acc.dispatches,
+      tasksAssigned: acc.tasksAssigned,
+      tasksCompleted: acc.tasksCompleted,
+      completionRate: acc.tasksAssigned > 0 ? acc.tasksCompleted / acc.tasksAssigned : 0,
+      avgDurationMs,
+      totalDurationMs
+    });
+  }
+
+  agents.sort((a, b) => b.tasksCompleted - a.tasksCompleted);
+
+  const totalTasks = agents.reduce((s, a) => s + a.tasksAssigned, 0);
+  const completedTasks = agents.reduce((s, a) => s + a.tasksCompleted, 0);
+
+  return {
+    agents,
+    summary: {
+      totalDispatches: dispatchLog.length,
+      totalTasks,
+      completedTasks,
+      completionRate: totalTasks > 0 ? completedTasks / totalTasks : 0,
+      avgTaskDurationMs: completedTasks > 0 && totalDurationAll > 0
+        ? Math.round(totalDurationAll / completedTasks)
+        : null
+    }
+  };
+}
+
+/**
+ * Format milliseconds as human-readable duration.
+ * @param {number|null} ms
+ * @returns {string}
+ */
+export function formatDuration(ms) {
+  if (ms == null || ms < 0) return '\u2014';
+  if (ms === 0) return '0s';
+
+  const totalSeconds = Math.floor(ms / 1000);
+  const hours = Math.floor(totalSeconds / 3600);
+  const minutes = Math.floor((totalSeconds % 3600) / 60);
+  const seconds = totalSeconds % 60;
+
+  if (hours > 0) return `${hours}h ${minutes}m`;
+  if (minutes > 0) return `${minutes}m`;
+  return `${seconds}s`;
+}
+
+/**
+ * Calculate cross-feature aggregated metrics.
+ * @param {Object} features - state.features object
+ * @returns {{ agents: Array, summary: Object, featureCount: number }}
+ */
+export function calculateAggregatedMetrics(features) {
+  const allEntries = [];
+  let featureCount = 0;
+
+  for (const feature of Object.values(features || {})) {
+    featureCount++;
+    const log = feature.dispatchLog || [];
+    allEntries.push(...log);
+  }
+
+  const result = calculateMetrics(allEntries);
+  return { ...result, featureCount };
+}

package/src/lib/agents/output-collector.js

@@ -0,0 +1,75 @@
+/**
+ * output-collector — Collect phase output files for multi-source agent detection
+ *
+ * Reads all existing phase outputs for a feature and returns them as
+ * weighted TextSource[] for use in detectAgents().
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { OUTPUT_SCHEMA, getAbsoluteOutputPath } from '../../core/paths/output-schema.js';
+
+/**
+ * Default source weights per output type.
+ * Keys match OUTPUT_SCHEMA keys (camelCase).
+ */
+export const SOURCE_WEIGHTS = {
+  proposal:       1.0,
+  schemaAnalysis: 1.0,
+  spec:           1.5,
+  contracts:      1.0,
+  contractsTs:    1.0,
+  contractsVsa:   1.0,
+  clarifications: 1.0,
+  decisions:      1.0,
+  plan:           1.2,
+  tasks:          1.3,
+  uiDesignSystem: 1.0,
+  uiMockups:      1.0,
+  uiComponents:   1.0,
+  uiFlows:        1.0,
+  recap:          1.0,
+};
+
+/** Phase order for sorting collected outputs */
+const PHASE_ORDER = ['proposal', 'uiux', 'design', 'clarify', 'plan', 'tasks', 'implement'];
+
+/**
+ * Collect all existing phase output files for a feature.
+ *
+ * @param {string} projectRoot - Absolute path to project root
+ * @param {string} featureName - Feature name
+ * @returns {Array<{source: string, content: string, weight: number}>}
+ */
+export function collectPhaseOutputs(projectRoot, featureName) {
+  const results = [];
+
+  for (const [key, entry] of Object.entries(OUTPUT_SCHEMA)) {
+    const absPath = getAbsoluteOutputPath(projectRoot, featureName, key);
+    if (!existsSync(absPath)) continue;
+
+    try {
+      const content = readFileSync(absPath, 'utf8');
+      if (!content.trim()) continue; // Skip empty files
+
+      results.push({
+        source: entry.filename,
+        content,
+        weight: SOURCE_WEIGHTS[key] ?? 1.0,
+        _phase: entry.phase,
+      });
+    } catch {
+      // Skip unreadable files — fail-open
+      continue;
+    }
+  }
+
+  // Sort by phase order
+  results.sort((a, b) => {
+    const orderA = PHASE_ORDER.indexOf(a._phase);
+    const orderB = PHASE_ORDER.indexOf(b._phase);
+    return (orderA === -1 ? 99 : orderA) - (orderB === -1 ? 99 : orderB);
+  });
+
+  // Remove internal _phase field
+  return results.map(({ source, content, weight }) => ({ source, content, weight }));
+}

package/src/lib/generators/context-generator.js

@@ -15,6 +15,7 @@ import fs from 'fs/promises';
 import path from 'path';
 import { existsSync } from 'fs';
 import { getOutputPath } from '../../core/paths/output-schema.js';
+import { tierToRole } from '../../utils/tier-helpers.js';
 
 /**
  * Resolve a template path: check .morph/framework/templates/ first, then framework/templates/.
@@ -259,7 +260,7 @@ export async function generateProjectContext(projectPath) {
       .map(([id, agent]) => ({
         id,
         title: agent.title,
-        always_active: agent.always_active
+        always_active: Array.isArray(agent.active_phases) ? agent.active_phases.includes('*') : !!agent.always_active
       })),
     TIER_2_AGENTS: Object.entries(agents?.agents || {})
       .filter(([id, agent]) => !id.startsWith('_') && agent.tier === 2)
@@ -273,7 +274,7 @@ export async function generateProjectContext(projectPath) {
       .map(([id, agent]) => ({
         id,
         title: agent.title,
-        reports_to: agent.relationships?.reports_to || 'N/A'
+        reports_to: agent.reports_to || agent.relationships?.reports_to || 'N/A'
       })),
 
     // Agent Teams config
@@ -381,10 +382,10 @@ export async function generateFeatureContext(projectPath, featureName) {
     .map(id => ({ id, ...agents.agents[id] }));
 
   // Group by tier and build squads
-  const teamLead = activeAgents.find(a => a.tier === 1 && a.role === 'orchestrator');
-  const domainLeaders = activeAgents.filter(a => a.tier === 2 && a.role === 'domain-leader');
-  const specialists = activeAgents.filter(a => a.tier === 3 && a.role === 'specialist');
-  const validators = activeAgents.filter(a => a.tier === 4 && a.role === 'validator');
+  const teamLead = activeAgents.find(a => tierToRole(a.tier) === 'orchestrator');
+  const domainLeaders = activeAgents.filter(a => tierToRole(a.tier) === 'leader');
+  const specialists = activeAgents.filter(a => tierToRole(a.tier) === 'specialist');
+  const validators = activeAgents.filter(a => tierToRole(a.tier) === 'validator');
 
   const squads = domainLeaders.map(leader => ({
     leader: {
@@ -392,7 +393,7 @@ export async function generateFeatureContext(projectPath, featureName) {
       title: leader.title
     },
     members: specialists
-      .filter(s => s.relationships?.reports_to === leader.id)
+      .filter(s => (s.reports_to || s.relationships?.reports_to) === leader.id)
       .map(s => ({
         id: s.id,
         title: s.title