@polymorphism-tech/morph-spec 7.1.1 → 7.3.0

package/src/lib/phase-chain/phase-validator.js

@@ -1,359 +0,0 @@
-/**
- * Phase Validator — centralized phase validation and eligibility checking.
- *
- * Exports: PHASES, validatePhase, computePassRate, checkPhaseEligibility
- *
- * Callers:
- *   - src/commands/state/advance-phase.js
- *   - src/commands/state/phase-runner.js
- *   - src/commands/project/status.js
- */
-
-import fs from 'fs';
-import path, { join } from 'path';
-import { loadState, derivePhase, getFeature } from '../../core/state/state-manager.js';
-import { getWorkflowConfig } from '../../core/workflows/workflow-detector.js';
-
-// v5: trust-manager removed. Auto-approval is no longer a CLI feature —
-// approval gates are handled by Claude presenting the gate via skill template
-// and the user responding. Stub to keep legacy callers happy.
-const shouldAutoApprove = () => false;
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Phase definitions (from validate-phase.js)
-// ─────────────────────────────────────────────────────────────────────────────
-
-export const PHASES = {
-  'proposal': {
-    order: 0,
-    name: 'FASE 0: PROPOSAL',
-    requiredOutputs: [],
-    description: 'Initial proposal and agent detection'
-  },
-  'uiux': {
-    order: 1,
-    name: 'FASE 1: UI/UX DESIGN',
-    requiredOutputs: ['proposal.md'],
-    optionalOutputs: ['design-system.md', 'mockups.md', 'components.md', 'flows.md'],
-    description: 'UI/UX design (conditional - only if frontend)',
-    optional: true
-  },
-  'plan': {
-    order: 2,
-    name: 'FASE 2: PLAN',
-    requiredOutputs: ['proposal.md'],
-    description: 'Technical specification, implementation plan, task breakdown, and mandate'
-  },
-  'implement': {
-    order: 3,
-    name: 'FASE 3: IMPLEMENT',
-    requiredOutputs: ['proposal.md', 'spec.md', 'tasks.md'],
-    description: 'Execute tasks and implement code'
-  },
-  'review': {
-    order: 4,
-    name: 'FASE 4: REVIEW',
-    requiredOutputs: ['proposal.md', 'spec.md', 'mandate.md', 'tasks.md', 'recap.md', 'review-report.md'],
-    description: 'Post-implementation quality review against mandate'
-  }
-};
-
-// Map output filenames to their phase subfolders (v5)
-const OUTPUT_PHASE_MAP = {
-  'proposal.md': '0-proposal',
-  'stack-scan.md': '0-proposal',
-  'migration-plan.md': '0-proposal',
-  'spec.md': '2-plan',
-  'mandate.md': '2-plan',
-  'decisions.md': '2-plan',
-  'design-system.md': '1-design',
-  'mockups.md': '1-design',
-  'components.md': '1-design',
-  'flows.md': '1-design',
-  'tasks.md': '2-plan',
-  'recap.md': '3-implement',
-  'review-report.md': '4-review'
-};
-
-function checkOutput(featurePath, outputFile) {
-  const phaseDir = OUTPUT_PHASE_MAP[outputFile] || '';
-  const filePath = path.join(featurePath, phaseDir, outputFile);
-  if (fs.existsSync(filePath)) return true;
-  // Fallback: check feature root (some generators place files there instead of phase subdirs)
-  if (phaseDir) {
-    return fs.existsSync(path.join(featurePath, outputFile));
-  }
-  return false;
-}
-
-/**
- * Validate phase prerequisites for a feature.
- * Used by advance-phase.js before advancing.
- */
-export function validatePhase(featureName, targetPhase) {
-  const featurePath = path.join(process.cwd(), '.morph/features', featureName);
-
-  if (!fs.existsSync(featurePath)) {
-    return {
-      valid: false,
-      error: `Feature directory not found: ${featurePath}`,
-      suggestion: `Run 'morph-spec state init ${featureName}' to start`,
-      missingOutputs: [],
-      phase: null
-    };
-  }
-
-  const phaseDefinition = PHASES[targetPhase];
-  if (!phaseDefinition) {
-    return {
-      valid: false,
-      error: `Unknown phase: ${targetPhase}`,
-      validPhases: Object.keys(PHASES),
-      missingOutputs: [],
-      phase: null
-    };
-  }
-
-  // Workflow-aware: only require outputs that the workflow declares as required.
-  // Fast-track skips design/plan, so spec.md and plan.md won't exist.
-  let requiredOutputs = phaseDefinition.requiredOutputs;
-  try {
-    const feature = getFeature(featureName);
-    if (feature?.workflow && feature.workflow !== 'auto') {
-      const wfConfig = getWorkflowConfig(feature.workflow);
-      if (wfConfig?.outputs?.required) {
-        const workflowRequired = new Set(wfConfig.outputs.required);
-        requiredOutputs = requiredOutputs.filter(o => workflowRequired.has(o));
-      }
-    }
-  } catch {
-    // Fall through to default requiredOutputs
-  }
-
-  const missingOutputs = [];
-  for (const output of requiredOutputs) {
-    if (!checkOutput(featurePath, output)) {
-      missingOutputs.push(output);
-    }
-  }
-
-  // Special validation: implement phase requires tasks.md to have actual tasks
-  if (targetPhase === 'implement') {
-    const tasksFilePath = path.join(featurePath, '2-plan', 'tasks.md');
-    if (fs.existsSync(tasksFilePath)) {
-      const content = fs.readFileSync(tasksFilePath, 'utf-8');
-      const taskCount = (content.match(/^###\s+T\d+/gm) || []).length;
-      if (taskCount === 0) {
-        missingOutputs.push(`tasks.md exists but has no task entries — add ### T001: Task title entries`);
-      }
-    }
-  }
-
-  // Warn if skipping phases
-  let stateWarning = null;
-  try {
-    const feature = getFeature(featureName);
-    if (feature) {
-      const currentPhaseOrder = PHASES[feature.phase]?.order ?? -1;
-      const targetPhaseOrder = phaseDefinition.order;
-      if (targetPhaseOrder > currentPhaseOrder + 1) {
-        stateWarning = `Skipping phases: current is '${feature.phase}' (order ${currentPhaseOrder}), target is '${targetPhase}' (order ${targetPhaseOrder})`;
-      }
-    }
-  } catch {
-    // State file may not exist
-  }
-
-  return {
-    valid: missingOutputs.length === 0,
-    error: null,
-    missingOutputs,
-    phase: phaseDefinition,
-    featurePath,
-    stateWarning
-  };
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Phase eligibility
-// ─────────────────────────────────────────────────────────────────────────────
-
-const PHASE_ORDER = ['proposal', 'uiux', 'plan', 'implement', 'review'];
-
-function getNextPhase(currentPhase, featureName) {
-  const idx = PHASE_ORDER.indexOf(currentPhase);
-  if (idx === -1 || idx >= PHASE_ORDER.length - 1) return null;
-
-  // Workflow-aware: skip phases not in the workflow's run list
-  let workflowConfig = null;
-  if (featureName) {
-    try {
-      const feature = getFeature(featureName);
-      if (feature?.workflow && feature.workflow !== 'auto') {
-        workflowConfig = getWorkflowConfig(feature.workflow);
-      }
-    } catch { /* fall through */ }
-  }
-
-  for (let i = idx + 1; i < PHASE_ORDER.length; i++) {
-    const candidate = PHASE_ORDER[i];
-    if (workflowConfig?.phases?.run && !workflowConfig.phases.run.includes(candidate)) {
-      continue;
-    }
-    return candidate;
-  }
-  return null;
-}
-
-/**
- * Compute overall validation pass rate from validationHistory.
- * Returns null when no history exists.
- */
-export function computePassRate(validationHistory) {
-  if (!validationHistory || Object.keys(validationHistory).length === 0) return null;
-  const entries = Object.values(validationHistory);
-  const passed = entries.filter(e => e.status === 'passed').length;
-  return entries.length > 0 ? passed / entries.length : null;
-}
-
-// Map output type names to file paths for eligibility checks (v5)
-const OUTPUT_PATH_MAP = {
-  'proposal': '0-proposal/proposal.md',
-  'stackScan': '0-proposal/stack-scan.md',
-  'migrationPlan': '0-proposal/migration-plan.md',
-  'spec': '2-plan/spec.md',
-  'mandate': '2-plan/mandate.md',
-  'tasks': '2-plan/tasks.md',
-  'decisions': '2-plan/decisions.md',
-  'recap': '3-implement/recap.md',
-  'reviewReport': '4-review/review-report.md',
-};
-
-function getMissingRequiredOutputs(featureName, phase, projectPath) {
-  const phaseDef = PHASES[phase];
-  if (!phaseDef?.requiredOutputs) return [];
-
-  const missing = [];
-  const featureBase = join(projectPath, '.morph', 'features', featureName);
-
-  for (const output of phaseDef.requiredOutputs) {
-    const relPath = OUTPUT_PATH_MAP[output];
-    if (relPath && !fs.existsSync(join(featureBase, relPath))) {
-      missing.push(output);
-    }
-  }
-
-  return missing;
-}
-
-function getBlockedTasks(feature) {
-  const history = feature.validationHistory || {};
-  return Object.entries(history)
-    .filter(([, entry]) => entry.status === 'blocked')
-    .map(([taskId]) => taskId);
-}
-
-/**
- * Check whether a feature is eligible to auto-advance to the next phase.
- * Used by phase-runner.js.
- */
-export function checkPhaseEligibility(featureName, opts = {}) {
-  const projectPath = opts.projectPath || process.cwd();
-
-  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,
-    };
-  }
-
-  const featureFolderPath = join(projectPath, '.morph', 'features', featureName);
-  const currentPhase = feature.phase || derivePhase(featureFolderPath);
-  const nextPhase = getNextPhase(currentPhase, featureName);
-
-  if (!nextPhase) {
-    return {
-      eligible: false,
-      blockers: [{ type: 'state_error', items: ['Feature is at the final phase'] }],
-      currentPhase,
-      nextPhase: null,
-      passRate: null,
-    };
-  }
-
-  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
-    : workflowConfig?.eligibility?.minPassRate ?? 0.80;
-
-  const blockers = [];
-
-  const missingOutputs = getMissingRequiredOutputs(featureName, currentPhase, projectPath);
-  if (missingOutputs.length > 0) {
-    blockers.push({ type: 'missing_outputs', items: missingOutputs });
-  }
-
-  const blockedTasks = getBlockedTasks(feature);
-  if (blockedTasks.length > 0) {
-    blockers.push({ type: 'blocked_tasks', items: blockedTasks });
-  }
-
-  const passRate = computePassRate(feature.validationHistory);
-  if (passRate !== null && passRate < minPassRate) {
-    blockers.push({
-      type: 'low_pass_rate',
-      current: passRate,
-      required: minPassRate,
-    });
-  }
-
-  try {
-    const requiredGateMap = { plan: 'plan', uiux: 'uiux', review: 'review' };
-    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
-  }
-
-  return {
-    eligible: blockers.length === 0,
-    blockers,
-    currentPhase,
-    nextPhase,
-    passRate,
-  };
-}

package/src/lib/validators/content/cross-phase-validator.js

@@ -1,281 +0,0 @@
-/**
- * Cross-Phase Validator
- *
- * Validates consistency across morph-spec phase outputs:
- * - FR coverage: every spec FR is referenced by at least one task
- * - Mandate integrity: mandate includes all task IDs with acceptance criteria
- * - Contract alignment: entities in spec Data Model appear in contracts
- * - Dependency ordering: task dependencies are topologically valid
- */
-
-import { readFileSync, existsSync } from 'fs';
-import { join } from 'path';
-import { parseFRSections, parseContracts, extractTaskIds } from '../../generators/mandate-generator.js';
-import { getAbsoluteOutputPath } from '../../../core/paths/output-schema.js';
-
-/**
- * v5: parseTaskFromMarkdown lived in sprint-contract-generator. Inlined here as
- * a minimal parser that extracts FR references from a task block.
- */
-function parseTaskFromMarkdown(tasksContent, taskId) {
-  const headingRe = new RegExp(`^### ${taskId}\\b[^\\n]*\\n([\\s\\S]*?)(?=^### |\\Z)`, 'm');
-  const match = tasksContent.match(headingRe);
-  if (!match) return null;
-  const block = match[1];
-  const frRefs = [...block.matchAll(/\bFR-?\d+\b/g)].map(m => m[0]);
-  return { id: taskId, frs: [...new Set(frRefs)], block };
-}
-
-/**
- * Compute FR coverage — how well tasks.md covers spec.md FRs.
- *
- * @param {string} specContent - Full spec.md content
- * @param {string} tasksContent - Full tasks.md content
- * @returns {{ ratio: number, coveredFRs: string[], uncoveredFRs: string[], taskFRRefs: Map<string, string[]> }}
- */
-export function computeFRCoverage(specContent, tasksContent) {
-  const frSections = parseFRSections(specContent);
-  const taskIds = extractTaskIds(tasksContent);
-
-  // Collect all FR references from tasks
-  const allReferencedFRs = new Set();
-  const taskFRRefs = new Map();
-
-  for (const taskId of taskIds) {
-    const task = parseTaskFromMarkdown(tasksContent, taskId);
-    if (task && task.frs.length > 0) {
-      taskFRRefs.set(taskId, task.frs);
-      for (const fr of task.frs) {
-        allReferencedFRs.add(fr);
-      }
-    }
-  }
-
-  const specFRIds = [...frSections.keys()];
-  const coveredFRs = specFRIds.filter(fr => allReferencedFRs.has(fr));
-  const uncoveredFRs = specFRIds.filter(fr => !allReferencedFRs.has(fr));
-
-  return {
-    ratio: specFRIds.length > 0 ? coveredFRs.length / specFRIds.length : 1,
-    coveredFRs,
-    uncoveredFRs,
-    taskFRRefs,
-  };
-}
-
-/**
- * Check mandate integrity — does the mandate include all tasks with acceptance criteria?
- *
- * @param {string} mandateContent - Full mandate.md content
- * @param {string} tasksContent - Full tasks.md content
- * @returns {{ complete: boolean, ratio: number, missingTasks: string[], tasksWithCriteria: string[], tasksWithoutCriteria: string[] }}
- */
-export function checkMandateIntegrity(mandateContent, tasksContent) {
-  const taskIds = extractTaskIds(tasksContent);
-  const missingTasks = [];
-  const tasksWithCriteria = [];
-  const tasksWithoutCriteria = [];
-
-  for (const taskId of taskIds) {
-    const taskPattern = new RegExp(`^## ${taskId}:`, 'm');
-    if (!taskPattern.test(mandateContent)) {
-      missingTasks.push(taskId);
-      continue;
-    }
-
-    // Check if this task section has acceptance criteria
-    const sectionStart = mandateContent.indexOf(`## ${taskId}:`);
-    const nextSection = mandateContent.slice(sectionStart + 1).search(/\n## /);
-    const sectionEnd = nextSection === -1 ? mandateContent.length : sectionStart + 1 + nextSection;
-    const section = mandateContent.slice(sectionStart, sectionEnd);
-
-    if (/### Acceptance Criteria/i.test(section) && /- \[[ x]\]/.test(section)) {
-      tasksWithCriteria.push(taskId);
-    } else {
-      tasksWithoutCriteria.push(taskId);
-    }
-  }
-
-  const includedCount = taskIds.length - missingTasks.length;
-  return {
-    complete: missingTasks.length === 0,
-    ratio: taskIds.length > 0 ? includedCount / taskIds.length : 1,
-    missingTasks,
-    tasksWithCriteria,
-    tasksWithoutCriteria,
-  };
-}
-
-/**
- * Check contract alignment — do entities in spec Data Model appear in contracts?
- *
- * @param {string} specContent - Full spec.md content
- * @param {string} contractsContent - Full contracts file content (CS or TS)
- * @returns {{ aligned: boolean, ratio: number, matchedEntities: string[], unmatchedEntities: string[] }}
- */
-export function checkContractAlignment(specContent, contractsContent) {
-  // Extract entity names from Data Model section in spec
-  const dataModelMatch = specContent.match(
-    /^##\s+(?:\d+\.?\s+)?Data Model\s*\n([\s\S]*?)(?=\n##\s|$)/im
-  );
-
-  if (!dataModelMatch) {
-    return { aligned: true, ratio: 1, matchedEntities: [], unmatchedEntities: [] };
-  }
-
-  const dataModelSection = dataModelMatch[1];
-  // Look for entity names: typically bold, backticked, or in headings
-  const entityPatterns = [
-    /\*\*(\w+)\*\*/g,            // **Entity**
-    /`(\w+)`/g,                   // `Entity`
-    /^###\s+(\w+)/gm,            // ### Entity
-  ];
-
-  const entities = new Set();
-  for (const pattern of entityPatterns) {
-    let match;
-    while ((match = pattern.exec(dataModelSection)) !== null) {
-      const name = match[1];
-      // Filter out common non-entity words
-      if (name.length > 2 && !/^(The|This|Each|All|and|for|with|from|that|has|can|will|not|are)$/i.test(name)) {
-        entities.add(name);
-      }
-    }
-  }
-
-  if (entities.size === 0) {
-    return { aligned: true, ratio: 1, matchedEntities: [], unmatchedEntities: [] };
-  }
-
-  const contracts = parseContracts(contractsContent);
-  const contractNames = [...contracts.keys()];
-  const contractNamesLower = contractNames.map(n => n.toLowerCase());
-
-  const matchedEntities = [];
-  const unmatchedEntities = [];
-
-  for (const entity of entities) {
-    const entityLower = entity.toLowerCase();
-    // Check if entity appears in any contract name (partial match)
-    const found = contractNamesLower.some(cn => cn.includes(entityLower) || entityLower.includes(cn));
-    if (found) {
-      matchedEntities.push(entity);
-    } else {
-      unmatchedEntities.push(entity);
-    }
-  }
-
-  return {
-    aligned: unmatchedEntities.length === 0,
-    ratio: entities.size > 0 ? matchedEntities.length / entities.size : 1,
-    matchedEntities,
-    unmatchedEntities,
-  };
-}
-
-/**
- * Check dependency ordering — are task dependencies topologically valid?
- *
- * @param {string} tasksContent - Full tasks.md content
- * @returns {{ valid: boolean, errors: string[] }}
- */
-export function checkDependencyOrdering(tasksContent) {
-  const taskIds = extractTaskIds(tasksContent);
-  const errors = [];
-
-  // Build dependency graph
-  const depPattern = /\*\*Dependenc(?:y|ies):\*\*\s*([T\d, ]+)/gi;
-  const taskIdSet = new Set(taskIds);
-  const taskOrder = new Map(taskIds.map((id, i) => [id, i]));
-
-  // Parse each task's dependencies
-  for (const taskId of taskIds) {
-    const task = parseTaskFromMarkdown(tasksContent, taskId);
-    if (!task) continue;
-
-    // Extract dependencies from task description
-    const depMatches = [...task.description.matchAll(depPattern)];
-    for (const depMatch of depMatches) {
-      const deps = depMatch[1].split(/[,\s]+/).filter(s => /^T\d{3}$/.test(s));
-      for (const dep of deps) {
-        if (!taskIdSet.has(dep)) {
-          errors.push(`${taskId} depends on ${dep} which does not exist`);
-        } else if (taskOrder.get(dep) >= taskOrder.get(taskId)) {
-          errors.push(`${taskId} depends on ${dep} which comes after it (ordering issue)`);
-        }
-      }
-    }
-  }
-
-  return {
-    valid: errors.length === 0,
-    errors,
-  };
-}
-
-/**
- * Run full cross-phase validation on a feature's outputs.
- *
- * @param {string} projectPath - Project root
- * @param {string} featureName - Feature name
- * @returns {Object} Full validation result with scores per dimension
- */
-export function validateCrossPhase(projectPath, featureName) {
-  const specPath  = getAbsoluteOutputPath(projectPath, featureName, 'spec');
-  const tasksPath = getAbsoluteOutputPath(projectPath, featureName, 'tasks');
-
-  const result = {
-    valid: true,
-    errors: [],
-    warnings: [],
-    dimensions: {},
-  };
-
-  // Require at minimum spec and tasks
-  if (!existsSync(specPath) || !existsSync(tasksPath)) {
-    result.valid = false;
-    if (!existsSync(specPath)) result.errors.push('spec.md not found');
-    if (!existsSync(tasksPath)) result.errors.push('tasks.md not found');
-    return result;
-  }
-
-  const specContent = readFileSync(specPath, 'utf-8');
-  const tasksContent = readFileSync(tasksPath, 'utf-8');
-
-  // 1. FR Coverage
-  const frCoverage = computeFRCoverage(specContent, tasksContent);
-  result.dimensions.frCoverage = frCoverage;
-  if (frCoverage.uncoveredFRs.length > 0) {
-    result.warnings.push(`Uncovered FRs: ${frCoverage.uncoveredFRs.join(', ')}`);
-  }
-  if (frCoverage.ratio < 0.9) {
-    result.errors.push(`FR coverage too low: ${(frCoverage.ratio * 100).toFixed(0)}% (threshold: 90%)`);
-    result.valid = false;
-  }
-
-  // 2. Mandate integrity (if mandate exists)
-  const mandatePath = getAbsoluteOutputPath(projectPath, featureName, 'mandate');
-  if (existsSync(mandatePath)) {
-    const mandateContent = readFileSync(mandatePath, 'utf-8');
-    const mandateIntegrity = checkMandateIntegrity(mandateContent, tasksContent);
-    result.dimensions.mandateIntegrity = mandateIntegrity;
-    if (mandateIntegrity.missingTasks.length > 0) {
-      result.errors.push(`Mandate missing tasks: ${mandateIntegrity.missingTasks.join(', ')}`);
-      result.valid = false;
-    }
-  }
-
-  // 3. Contract alignment removed in v5 — contracts live in spec.md (NLH model).
-  //    See morph-implement skill for source-level contract checks.
-
-  // 4. Dependency ordering
-  const depOrdering = checkDependencyOrdering(tasksContent);
-  result.dimensions.dependencyOrdering = depOrdering;
-  if (!depOrdering.valid) {
-    for (const err of depOrdering.errors) {
-      result.warnings.push(`Dependency issue: ${err}`);
-    }
-  }
-
-  return result;
-}