@polymorphism-tech/morph-spec 8.38.0 → 8.40.0

package/src/core/state/phase-state-machine.js

@@ -1,197 +0,0 @@
-/**
- * Phase State Machine - Enforces valid phase transitions
- *
- * Prevents invalid workflow jumps and ensures sequential phase progression.
- * Based on the MORPH 5-phase workflow.
- */
-
-/**
- * Valid phase transitions map
- * Each phase can only transition to specific next phases
- */
-const VALID_TRANSITIONS = {
-  'proposal': ['uiux', 'plan'],
-  'uiux': ['plan'],
-  'plan': ['implement'],
-  'implement': ['review'],
-  'review': []
-};
-
-/**
- * Phase display names for error messages
- */
-const PHASE_NAMES = {
-  'proposal': 'Proposal (Phase 0)',
-  'uiux': 'UI/UX Design (Phase 1)',
-  'plan': 'Plan (Phase 2)',
-  'implement': 'Implement (Phase 3)',
-  'review': 'Quality Review (Phase 4)'
-};
-
-/**
- * Optional phases that can be skipped
- */
-const OPTIONAL_PHASES = ['uiux'];
-
-/**
- * Validate if a phase transition is allowed
- * @param {string} fromPhase - Current phase
- * @param {string} toPhase - Target phase
- * @returns {boolean} True if transition is valid
- */
-export function isValidTransition(fromPhase, toPhase) {
-  if (!fromPhase || !toPhase) {
-    return false;
-  }
-
-  const validNextPhases = VALID_TRANSITIONS[fromPhase];
-  return validNextPhases ? validNextPhases.includes(toPhase) : false;
-}
-
-/**
- * Get list of valid next phases for a given phase
- * @param {string} currentPhase - Current phase
- * @returns {string[]} Array of valid next phase names
- */
-export function getValidNextPhases(currentPhase) {
-  return VALID_TRANSITIONS[currentPhase] || [];
-}
-
-/**
- * Get display name for a phase
- * @param {string} phase - Phase identifier
- * @returns {string} Human-readable phase name
- */
-export function getPhaseDisplayName(phase) {
-  return PHASE_NAMES[phase] || phase;
-}
-
-/**
- * Check if a phase is optional
- * @param {string} phase - Phase identifier
- * @returns {boolean} True if phase is optional
- */
-export function isOptionalPhase(phase) {
-  return OPTIONAL_PHASES.includes(phase);
-}
-
-/**
- * Validate transition and throw error if invalid
- * @param {string} fromPhase - Current phase
- * @param {string} toPhase - Target phase
- * @throws {Error} If transition is invalid
- */
-export function validateTransition(fromPhase, toPhase) {
-  if (!fromPhase) {
-    throw new Error('Current phase is undefined. Cannot validate transition.');
-  }
-
-  if (!toPhase) {
-    throw new Error('Target phase is undefined. Cannot validate transition.');
-  }
-
-  if (!isValidTransition(fromPhase, toPhase)) {
-    const validPhases = getValidNextPhases(fromPhase);
-    const fromDisplay = getPhaseDisplayName(fromPhase);
-    const toDisplay = getPhaseDisplayName(toPhase);
-
-    throw new Error(
-      `Invalid phase transition: ${fromDisplay} → ${toDisplay}\n\n` +
-      `Valid next phases from ${fromDisplay}:\n` +
-      validPhases.map(p => `  • ${getPhaseDisplayName(p)}`).join('\n') +
-      '\n\n' +
-      'You cannot skip phases in the MORPH workflow.\n' +
-      'To override this check, use the --force flag (not recommended).'
-    );
-  }
-}
-
-/**
- * Get the sequential order of phases
- * @returns {string[]} Ordered list of phases
- */
-export function getPhaseSequence() {
-  return ['proposal', 'uiux', 'plan', 'implement', 'review'];
-}
-
-/**
- * Get phase order index (for comparison)
- * @param {string} phase - Phase identifier
- * @returns {number} Index in sequence (-1 if not found)
- */
-export function getPhaseOrder(phase) {
-  return getPhaseSequence().indexOf(phase);
-}
-
-/**
- * Check if target phase is ahead of current phase
- * @param {string} currentPhase - Current phase
- * @param {string} targetPhase - Target phase
- * @returns {boolean} True if target is ahead
- */
-export function isPhaseAhead(currentPhase, targetPhase) {
-  return getPhaseOrder(targetPhase) > getPhaseOrder(currentPhase);
-}
-
-/**
- * Check if target phase is behind current phase (rollback scenario)
- * @param {string} currentPhase - Current phase
- * @param {string} targetPhase - Target phase
- * @returns {boolean} True if target is behind
- */
-export function isPhaseRollback(currentPhase, targetPhase) {
-  return getPhaseOrder(targetPhase) < getPhaseOrder(currentPhase);
-}
-
-/**
- * Get all skipped phases between two phases
- * @param {string} fromPhase - Starting phase
- * @param {string} toPhase - Ending phase
- * @returns {string[]} Array of skipped phases
- */
-export function getSkippedPhases(fromPhase, toPhase) {
-  const sequence = getPhaseSequence();
-  const fromIndex = sequence.indexOf(fromPhase);
-  const toIndex = sequence.indexOf(toPhase);
-
-  if (fromIndex === -1 || toIndex === -1 || toIndex <= fromIndex) {
-    return [];
-  }
-
-  return sequence.slice(fromIndex + 1, toIndex);
-}
-
-/**
- * Validate that no required phases were skipped
- * @param {string} fromPhase - Starting phase
- * @param {string} toPhase - Ending phase
- * @throws {Error} If required phases were skipped
- */
-export function validateNoRequiredPhasesSkipped(fromPhase, toPhase) {
-  const skipped = getSkippedPhases(fromPhase, toPhase);
-  const requiredSkipped = skipped.filter(p => !isOptionalPhase(p));
-
-  if (requiredSkipped.length > 0) {
-    throw new Error(
-      `Cannot skip required phases:\n` +
-      requiredSkipped.map(p => `  • ${getPhaseDisplayName(p)}`).join('\n') +
-      '\n\nYou must complete each required phase in sequence.'
-    );
-  }
-}
-
-/**
- * Get comprehensive phase information
- * @param {string} phase - Phase identifier
- * @returns {Object} Phase metadata
- */
-export function getPhaseInfo(phase) {
-  return {
-    id: phase,
-    displayName: getPhaseDisplayName(phase),
-    order: getPhaseOrder(phase),
-    isOptional: isOptionalPhase(phase),
-    validNextPhases: getValidNextPhases(phase),
-    canTransitionTo: (targetPhase) => isValidTransition(phase, targetPhase)
-  };
-}

package/src/dashboard/app/hooks/useDetailPanel.js

@@ -1,15 +0,0 @@
-import { useState, useCallback } from 'react';
-
-export function useDetailPanel() {
-  const [panel, setPanel] = useState({ open: false, title: '', content: null });
-
-  const openPanel = useCallback((title, content) => {
-    setPanel({ open: true, title, content });
-  }, []);
-
-  const closePanel = useCallback(() => {
-    setPanel((prev) => ({ ...prev, open: false }));
-  }, []);
-
-  return { panel, openPanel, closePanel };
-}

package/src/dashboard/app/pages/LiveState.jsx

@@ -1,206 +0,0 @@
-import morphData from 'virtual:morph-data';
-
-// ─── Constants ────────────────────────────────────────────────────────────────
-
-const PHASE_ORDER = ['proposal', 'uiux', 'plan', 'implement', 'review'];
-
-const STATUS_BADGE = {
-  in_progress: { label: 'In Progress', bg: 'bg-blue-900/60', border: 'border-blue-600', text: 'text-blue-300' },
-  completed:   { label: 'Completed',   bg: 'bg-green-900/60', border: 'border-green-600', text: 'text-green-300' },
-  draft:       { label: 'Draft',        bg: 'bg-gray-800',    border: 'border-gray-600', text: 'text-gray-400' },
-};
-
-const TASK_STATUS_ICON = {
-  completed:   { icon: '✓', color: 'text-green-400' },
-  in_progress: { icon: '►', color: 'text-blue-400' },
-  pending:     { icon: '○', color: 'text-gray-600' },
-};
-
-// ─── Sub Components ───────────────────────────────────────────────────────────
-
-function StatusBadge({ status }) {
-  const s = STATUS_BADGE[status] || STATUS_BADGE.draft;
-  return (
-    <span className={`px-2 py-0.5 rounded text-xs font-medium border ${s.bg} ${s.border} ${s.text}`}>
-      {s.label}
-    </span>
-  );
-}
-
-function PhaseProgressBar({ currentPhase, approvals }) {
-  const approvedSet = new Set(Object.keys(approvals || {}));
-  const currentIdx = PHASE_ORDER.indexOf(currentPhase);
-
-  return (
-    <div className="flex gap-1 mt-2">
-      {PHASE_ORDER.map((phase, idx) => {
-        const isCurrent = phase === currentPhase;
-        const isApproved = approvedSet.has(phase);
-        const isPast = idx < currentIdx && !isCurrent;
-        const isFuture = idx > currentIdx;
-
-        let bg, text, extra;
-        if (isApproved) {
-          bg = 'bg-green-800 border-green-600';
-          text = 'text-green-300';
-          extra = '✓';
-        } else if (isCurrent) {
-          bg = 'bg-blue-800 border-blue-500';
-          text = 'text-blue-100 font-bold';
-          extra = null;
-        } else if (isFuture) {
-          bg = 'bg-gray-800 border-gray-700';
-          text = 'text-gray-600';
-          extra = null;
-        } else {
-          // Past but not approved
-          bg = 'bg-gray-700 border-gray-600';
-          text = 'text-gray-400';
-          extra = null;
-        }
-
-        return (
-          <div
-            key={phase}
-            className={`flex-1 px-1 py-1 rounded border text-center text-[9px] leading-tight ${bg} ${text}`}
-            title={phase}
-          >
-            <div className="truncate">{phase}</div>
-            {extra && <div className="text-[8px] mt-0.5">{extra}</div>}
-          </div>
-        );
-      })}
-    </div>
-  );
-}
-
-function TaskList({ taskList }) {
-  if (!taskList?.length) return <p className="text-gray-600 text-xs italic">No tasks</p>;
-
-  return (
-    <div className="space-y-1">
-      {taskList.map((task, i) => {
-        const status = task.status || 'pending';
-        const { icon, color } = TASK_STATUS_ICON[status] || TASK_STATUS_ICON.pending;
-        return (
-          <div key={i} className="flex items-start gap-2 text-xs">
-            <span className={`${color} font-mono flex-shrink-0 mt-0.5 w-3 text-center`}>{icon}</span>
-            <span className={`flex-1 leading-snug ${status === 'completed' ? 'text-gray-500' : 'text-gray-300'}`}>
-              {task.text || task.description || String(task)}
-            </span>
-            {task.agent && (
-              <span className="text-gray-600 text-[10px] font-mono flex-shrink-0 ml-1">{task.agent}</span>
-            )}
-          </div>
-        );
-      })}
-    </div>
-  );
-}
-
-function FeatureCard({ featureId, feature }) {
-  const status = feature.status || 'draft';
-  const phase = feature.phase || feature.currentPhase || PHASE_ORDER[0];
-  const approvals = feature.approvals || {};
-  const taskList = Array.isArray(feature.taskList)
-    ? feature.taskList
-    : typeof feature.taskList === 'object' && feature.taskList !== null
-      ? Object.values(feature.taskList)
-      : [];
-
-  return (
-    <div className="bg-gray-900 border border-gray-700 rounded-xl p-4 space-y-3">
-      {/* Header */}
-      <div className="flex items-center justify-between gap-3">
-        <h3 className="text-white font-semibold text-sm truncate">{featureId}</h3>
-        <div className="flex items-center gap-1.5 flex-shrink-0">
-          {feature._worktree && (
-            <span
-              className="px-2 py-0.5 rounded text-xs font-medium border bg-purple-900/60 border-purple-600 text-purple-300"
-              title={`In progress in .worktrees/${feature._worktree}`}
-            >
-              worktree
-            </span>
-          )}
-          <StatusBadge status={status} />
-        </div>
-      </div>
-
-      {/* Phase progress */}
-      <div>
-        <p className="text-gray-500 text-[10px] uppercase tracking-wide mb-1">Phase Progress</p>
-        <PhaseProgressBar currentPhase={phase} approvals={approvals} />
-      </div>
-
-      {/* Task list */}
-      {taskList.length > 0 && (
-        <div>
-          <p className="text-gray-500 text-[10px] uppercase tracking-wide mb-1.5">
-            Tasks ({taskList.length})
-          </p>
-          <TaskList taskList={taskList} />
-        </div>
-      )}
-    </div>
-  );
-}
-
-// ─── Main Page ────────────────────────────────────────────────────────────────
-
-export default function LiveState() {
-  const { liveState } = morphData;
-
-  if (!liveState) {
-    return (
-      <div className="flex items-center justify-center h-full">
-        <div className="text-center space-y-3">
-          <div className="text-4xl text-gray-700">○</div>
-          <p className="text-gray-400 text-lg font-medium">No active project</p>
-          <p className="text-gray-600 text-sm">
-            Run <code className="px-1.5 py-0.5 bg-gray-800 border border-gray-700 rounded font-mono text-gray-300">morph-spec init</code> to get started
-          </p>
-        </div>
-      </div>
-    );
-  }
-
-  const features = liveState.features || {};
-  const featureEntries = Object.entries(features);
-
-  return (
-    <div className="flex flex-col h-full">
-      {/* Header */}
-      <div className="px-6 py-4 border-b border-gray-800 flex-shrink-0 flex items-center justify-between">
-        <div>
-          <h1 className="text-white text-xl font-bold">Live State</h1>
-          <p className="text-gray-400 text-sm mt-0.5">
-            {liveState.project?.name || 'Project'} · state v{liveState.version}
-          </p>
-        </div>
-        <div className="flex items-center gap-4 text-xs text-gray-400">
-          <span>{featureEntries.length} feature{featureEntries.length !== 1 ? 's' : ''}</span>
-          {liveState.project?.stack && (
-            <span className="px-2 py-0.5 bg-gray-800 border border-gray-700 rounded font-mono">
-              {liveState.project.stack}
-            </span>
-          )}
-        </div>
-      </div>
-
-      {/* Feature list */}
-      <div className="flex-1 overflow-y-auto px-6 py-5">
-        {featureEntries.length === 0 ? (
-          <div className="flex items-center justify-center h-48">
-            <p className="text-gray-500 text-sm">No features tracked yet</p>
-          </div>
-        ) : (
-          <div className="grid grid-cols-1 xl:grid-cols-2 gap-4">
-            {featureEntries.map(([featureId, feature]) => (
-              <FeatureCard key={featureId} featureId={featureId} feature={feature} />
-            ))}
-          </div>
-        )}
-      </div>
-    </div>
-  );
-}

package/src/dashboard/scanner/squads-scanner.js

@@ -1,13 +0,0 @@
-import { readFileSync, readdirSync, existsSync } from 'fs';
-import { join } from 'path';
-
-export function scanSquads(frameworkDir) {
-  const dir = join(frameworkDir, 'squad-templates');
-  if (!existsSync(dir)) return [];
-  return readdirSync(dir).filter(f => f.endsWith('.json')).map(f => {
-    const d = JSON.parse(readFileSync(join(dir, f), 'utf8'));
-    return { id: d.id, name: d.name, description: d.description || '',
-      parallel: d.parallel || false, coordination: d.coordination || null,
-      agents: d.agents || [], agentTeam: d.agent_team || null };
-  });
-}

package/src/dashboard/scanner/state-scanner.js

@@ -1,85 +0,0 @@
-import { readFileSync, existsSync, readdirSync } from 'fs';
-import { join } from 'path';
-import { WORKTREE_DIR_NAMES } from '../../commands/project/worktree.js';
-
-export function scanState(projectDir) {
-  const statePath = join(projectDir, '.morph', 'state.json');
-  let state = null;
-  if (existsSync(statePath)) {
-    try { state = JSON.parse(readFileSync(statePath, 'utf8')); } catch { state = null; }
-  }
-
-  // Hydrate full feature objects from the authoritative per-feature files. The
-  // root state.json is now a thin, derivable index (status + updatedAt only), so
-  // the dashboard must read .morph/features/{name}/feature.json for full data.
-  const featuresDir = join(projectDir, '.morph', 'features');
-  if (existsSync(featuresDir)) {
-    let names = [];
-    try {
-      names = readdirSync(featuresDir, { withFileTypes: true })
-        .filter((e) => e.isDirectory())
-        .map((e) => e.name);
-    } catch { names = []; }
-    for (const name of names) {
-      const fjPath = join(featuresDir, name, 'feature.json');
-      if (!existsSync(fjPath)) continue;
-      try {
-        const fj = JSON.parse(readFileSync(fjPath, 'utf8'));
-        state = state || { features: {} };
-        state.features = state.features || {};
-        state.features[name] = fj;
-      } catch { /* skip a corrupt feature.json */ }
-    }
-  }
-
-  // Aggregate in-progress features that only exist inside a feature worktree
-  // (worktrees/{wt}/.morph/features/*/feature.json). In the v8 multi-instance
-  // model a feature's authoritative feature.json is committed on its
-  // `morph/{feature}` branch and only lands in the root .morph/features/ after
-  // `morph-spec finish`. This is read-only visibility for the dashboard — root
-  // features (the merged, authoritative state) always take precedence, and
-  // worktree-sourced entries are tagged with `_worktree` so the UI can
-  // distinguish them.
-  //
-  // BOTH directory names are scanned: this scanner resolves worktrees by
-  // CONVENTION (unlike fleet/finish, which read `git worktree list`), so it is
-  // the one that would otherwise go blind to pre-C1 `.worktrees/` checkouts.
-  const worktreeDirs = WORKTREE_DIR_NAMES
-    .map((name) => join(projectDir, name))
-    .filter((dir) => existsSync(dir));
-
-  for (const worktreesDir of worktreeDirs) {
-    let worktreeNames = [];
-    try {
-      worktreeNames = readdirSync(worktreesDir, { withFileTypes: true })
-        .filter((e) => e.isDirectory())
-        .map((e) => e.name);
-    } catch { worktreeNames = []; }
-
-    for (const wt of worktreeNames) {
-      const wtFeaturesDir = join(worktreesDir, wt, '.morph', 'features');
-      if (!existsSync(wtFeaturesDir)) continue;
-      let wtFeatureNames = [];
-      try {
-        wtFeatureNames = readdirSync(wtFeaturesDir, { withFileTypes: true })
-          .filter((e) => e.isDirectory())
-          .map((e) => e.name);
-      } catch { continue; }
-
-      for (const name of wtFeatureNames) {
-        state = state || { features: {} };
-        state.features = state.features || {};
-        if (state.features[name]) continue; // root feature already present — it wins
-
-        const fjPath = join(wtFeaturesDir, name, 'feature.json');
-        if (!existsSync(fjPath)) continue;
-        try {
-          const fj = JSON.parse(readFileSync(fjPath, 'utf8'));
-          state.features[name] = { ...fj, _worktree: wt };
-        } catch { /* skip a corrupt feature.json */ }
-      }
-    }
-  }
-
-  return state;
-}

package/src/lib/generators/index.js

@@ -1,10 +0,0 @@
-/**
- * Code Generators
- *
- * Code and documentation generation utilities.
- */
-
-export * from './design-system-generator.js';
-export * from './handoff-generator.js';
-export * from './architecture-scanner.js';
-export * from './scaffold-generator.js';

package/src/lib/hooks/hook-executor.js

@@ -1,167 +0,0 @@
-/**
- * Hook Executor — Agent Teams hook validation
- *
- * Executes validation hooks triggered by Claude Code agent-teams events:
- *   TeammateIdle, TaskCompleted, PhaseAdvanced
- *
- * Reads agents.json to find validators with matching hook_triggers,
- * then runs each validator's checks against the current project state.
- *
- * @module hook-executor
- */
-
-import { readFileSync, existsSync } from 'fs';
-import { join } from 'path';
-
-// ============================================================================
-// Loaders
-// ============================================================================
-
-function loadAgents(projectPath) {
-  const agentPaths = [
-    join(projectPath, '.morph/framework/agents.json'),
-  ];
-
-  const allAgents = {};
-  for (const agentPath of agentPaths) {
-    if (existsSync(agentPath)) {
-      try {
-        const data = JSON.parse(readFileSync(agentPath, 'utf8'));
-        Object.assign(allAgents, data.agents || {});
-      } catch (e) { /* skip malformed files */ }
-    }
-  }
-  return allAgents;
-}
-
-function loadStateFeature(projectPath, featureName) {
-  const statePath = join(projectPath, '.morph/state.json');
-  if (!existsSync(statePath)) return null;
-
-  const state = JSON.parse(readFileSync(statePath, 'utf8'));
-  const features = state.features;
-
-  // Support both object format { featureName: {...} } and array format [{name, ...}]
-  if (Array.isArray(features)) {
-    return features.find(f => f.name === featureName) || null;
-  }
-  return features[featureName] || null;
-}
-
-// ============================================================================
-// Main Executor
-// ============================================================================
-
-/**
- * Execute agent-teams hook validation
- * @param {string} projectPath - Absolute path to project root
- * @param {string} featureName - Feature to validate
- * @param {string} hookEvent - Event name (TeammateIdle, TaskCompleted, PhaseAdvanced)
- * @param {Object} [opts]
- * @param {boolean} [opts.dryRun=false] - Identify validators without running them
- * @param {boolean} [opts.verbose=true] - Print results to console
- * @returns {Promise<Object>} { passed, blocked, errors, warnings }
- */
-export async function executeHook(projectPath, featureName, hookEvent, opts = {}) {
-  const { dryRun = false } = opts;
-
-  // Load feature state
-  const feature = loadStateFeature(projectPath, featureName);
-  if (!feature) {
-    return {
-      passed: false,
-      blocked: true,
-      errors: [`Feature not found: ${featureName}`],
-      warnings: []
-    };
-  }
-
-  // Load all available agents
-  const agents = loadAgents(projectPath);
-
-  // Filter: agents that run in hooks AND trigger on this event
-  const hookValidators = Object.entries(agents)
-    .filter(([, agent]) =>
-      agent.relationships?.runs_in === 'hooks' &&
-      Array.isArray(agent.relationships?.hook_triggers) &&
-      agent.relationships.hook_triggers.includes(hookEvent)
-    )
-    .map(([agentId, agent]) => ({ agentId, ...agent }));
-
-  // No validators configured for this event, or dry run — pass immediately
-  if (hookValidators.length === 0 || dryRun) {
-    return { passed: true, blocked: false, errors: [], warnings: [] };
-  }
-
-  // Run validators
-  // In production, each validator would execute its actual checks.
-  // This implementation returns pass since real validation requires external tooling.
-  const errors = [];
-  const warnings = [];
-
-  const passed = errors.length === 0;
-  const blocked = errors.some(e => typeof e === 'object' && e.blocksOnFail !== false);
-
-  return { passed, blocked, errors, warnings };
-}
-
-// ============================================================================
-// Formatter
-// ============================================================================
-
-/**
- * Format hook execution results as a human-readable string
- * @param {Object} results - Result from executeHook
- * @param {string} hookEvent - Event name
- * @returns {string} Formatted output
- */
-export function formatHookResults(results, hookEvent) {
-  const { passed, blocked, errors = [], warnings = [] } = results;
-  const lines = [];
-
-  if (!passed && errors.length > 0) {
-    lines.push(`❌ Hook: ${hookEvent}`);
-    lines.push('FAILED');
-    lines.push('ERRORS (blocking):');
-
-    for (const err of errors) {
-      if (err.issues && Array.isArray(err.issues)) {
-        for (const issue of err.issues) {
-          lines.push(`  ${issue.message}`);
-          if (issue.file && issue.line !== undefined) {
-            lines.push(`  ${issue.file}:${issue.line}`);
-          }
-        }
-      } else if (err.error) {
-        lines.push(`  Error: ${err.error}`);
-      } else if (typeof err === 'string') {
-        lines.push(`  ${err}`);
-      }
-    }
-
-    if (blocked) {
-      lines.push('BLOCKED');
-    }
-  } else if (warnings.length === 0) {
-    lines.push(`✅ Hook: ${hookEvent}`);
-    lines.push('All validators passed');
-  }
-
-  if (warnings.length > 0) {
-    lines.push(`⚠️ Hook: ${hookEvent}`);
-    lines.push('WARNINGS (non-blocking):');
-
-    for (const warn of warnings) {
-      if (warn.issues && Array.isArray(warn.issues)) {
-        for (const issue of warn.issues) {
-          lines.push(`  ${issue.message}`);
-          if (issue.file && issue.line !== undefined) {
-            lines.push(`  ${issue.file}:${issue.line}`);
-          }
-        }
-      }
-    }
-  }
-
-  return lines.join('\n');
-}