@polymorphism-tech/morph-spec 4.22.0 → 5.0.1

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

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

package/src/lib/validators/content/index.js

@@ -5,3 +5,4 @@
  */
 
 export * from './content-validator.js';
+export * from './cross-phase-validator.js';

package/src/lib/validators/shared/emit-validator-dispatch.js

@@ -1,64 +1,14 @@
 /**
- * Shared utility: emit a VALIDATION DISPATCH block to stdout.
- *
- * Both `advance-phase.js` and `task-manager.js` call this so that the
- * PostToolUse dispatch hook can parse the JSON via strategy 1 (from
- * tool_result) without falling back to a subprocess.
+ * Stub: validation dispatch was driven by tier-4 agents in v4.
+ * In v5, validation is handled by morph-eval skill invoked directly
+ * by the Evaluator role. This function is kept for call-site compatibility.
  *
  * @module emit-validator-dispatch
  */
 
-import chalk from 'chalk';
-import { readFileSync } from 'fs';
-import { join, dirname } from 'path';
-import { fileURLToPath } from 'url';
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-
 /**
- * Emit a VALIDATION DISPATCH block to stdout for the PostToolUse hook.
- *
- * Non-blocking — fails silently on any error.
- *
- * @param {string} featureName - Feature name
- * @param {string} phase - Current phase
- * @param {string} cwd - Project root
+ * No-op in v5. Validation dispatch is now handled by morph-eval skill.
  */
-export async function emitValidatorDispatch(featureName, phase, cwd) {
-  try {
-    const { buildDispatchConfig } = await import('../../../commands/agents/dispatch-agents.js');
-    const config = await buildDispatchConfig(cwd, featureName, phase, { mode: 'validate' });
-    const validators = config.agents?.filter(a => a.tier === 4);
-    if (!validators || validators.length === 0) return;
-
-    const agentsPath = join(__dirname, '..', '..', '..', '..', 'framework', 'agents.json');
-    const agentsData = JSON.parse(readFileSync(agentsPath, 'utf8'));
-    const allAgents = agentsData.agents || {};
-
-    const validatorEntries = validators.map(v => {
-      const agentData = allAgents[v.id];
-      return {
-        id: v.id,
-        title: v.title,
-        severity: agentData?.hook_behavior?.severity || 'error',
-        blocksOnFail: agentData?.hook_behavior?.blocks_on_fail ?? true,
-        checks: agentData?.hook_behavior?.validates || [],
-        taskPrompt: v.taskPrompt,
-      };
-    });
-
-    const dispatch = {
-      validationRequired: true,
-      phase,
-      feature: featureName,
-      validators: validatorEntries,
-      instruction: 'Dispatch these validators as READ-ONLY subagents before continuing. Each must output { "passed": boolean, "issues": [] }. Blocking validators (blocksOnFail: true) must pass before marking phase complete.',
-    };
-
-    console.log(chalk.cyan('\n--- VALIDATION DISPATCH ---'));
-    console.log(JSON.stringify(dispatch, null, 2));
-    console.log(chalk.cyan('--- END VALIDATION DISPATCH ---\n'));
-  } catch {
-    // Non-blocking — fail silently
-  }
+export async function emitValidatorDispatch(_featureName, _phase, _cwd) {
+  // v5: evaluation driven by morph-eval skill, not CLI dispatch
 }

package/src/scripts/global-install.js

@@ -2,7 +2,7 @@
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { homedir, platform } from 'os';
-import { mkdir, copyFile, readFile, writeFile } from 'fs/promises';
+import { mkdir, readFile, writeFile } from 'fs/promises';
 import { existsSync } from 'fs';
 import { execSync } from 'child_process';
 import { installGlobalStatusline } from '../utils/hooks-installer.js';
@@ -10,24 +10,6 @@ import { installGlobalStatusline } from '../utils/hooks-installer.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const FRAMEWORK_DIR = join(__dirname, '..', '..', 'framework');
 
-/**
- * Install morph-init skill to a Claude global skills directory.
- * @param {string} claudeDir - target ~/.claude dir (defaults to real ~/.claude)
- */
-export async function installGlobalSkill(claudeDir = join(homedir(), '.claude')) {
-  const src = join(FRAMEWORK_DIR, 'skills', 'level-0-meta', 'morph-init', 'SKILL.md');
-  const destDir = join(claudeDir, 'skills', 'morph-init');
-  const dest = join(destDir, 'SKILL.md');
-
-  if (!existsSync(src)) {
-    console.warn(`morph-init skill not found at ${src} — skipping global install`);
-    return;
-  }
-
-  await mkdir(destDir, { recursive: true });
-  await copyFile(src, dest);
-}
-
 /**
  * Ensure the npm global bin directory is in the user's PATH on Windows.
  * Adds it to the PowerShell $PROFILE so new terminals find `morph-spec`.
@@ -80,19 +62,12 @@ if (process.argv[1] === fileURLToPath(import.meta.url)) {
   const { readFileSync } = await import('fs');
   const pkg = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
 
-  const [skillResult, statuslineResult, pathResult] = await Promise.allSettled([
-    installGlobalSkill(),
+  const [statuslineResult, pathResult] = await Promise.allSettled([
     installGlobalStatusline(HOOKS_SRC),
     ensureNpmGlobalInPath(),
   ]);
 
   const results = [
-    {
-      ok: skillResult.status === 'fulfilled',
-      label: 'morph-init skill',
-      path: '~/.claude/skills/',
-      error: skillResult.reason?.message,
-    },
     {
       ok: statuslineResult.status === 'fulfilled',
       label: 'statusline',