@polymorphism-tech/morph-spec 4.21.0 → 5.0.1

package/src/lib/stack/stack-profile.js

@@ -1,91 +1,74 @@
-import { readFileSync, existsSync } from 'fs';
-import { join } from 'path';
-
-/** @typedef {'nextjs'|'dotnet'|'nodejs-cli'|'unknown'} StackName */
-
-/**
- * @typedef {Object} StackProfile
- * @property {StackName} stack
- * @property {boolean} isDotnet
- * @property {boolean} isNextjs
- * @property {string[]} defaultValidators
- * @property {string[]} checkpointValidators
- * @property {'contracts'|'contractsTs'} contractsOutputType
- * @property {'contracts.cs'|'contracts.ts'} contractsFilename
- * @property {'csharp'|'typescript'} contractsLanguage
- */
-
-const DOTNET_STACKS = new Set(['dotnet', 'aspnet']);
-const NEXTJS_STACKS = new Set(['nextjs', 'next', 'next.js']);
-const NO_VALIDATOR_STACKS = new Set(['nodejs-cli', 'node-cli', 'cli']);
-
-const PROFILES = {
-  dotnet: {
-    isDotnet: true, isNextjs: false,
-    defaultValidators: ['architecture', 'packages'],
-    checkpointValidators: ['architecture', 'packages', 'design-system', 'security'],
-    buildCommand: 'dotnet build --no-restore',
-    contractsOutputType: 'contracts',
-    contractsFilename: 'contracts.cs',
-    contractsLanguage: 'csharp',
-  },
-  nextjs: {
-    isDotnet: false, isNextjs: true,
-    defaultValidators: ['nextjs-component'],
-    checkpointValidators: ['nextjs-component', 'css'],
-    buildCommand: 'npx tsc --noEmit',
-    contractsOutputType: 'contractsTs',
-    contractsFilename: 'contracts.ts',
-    contractsLanguage: 'typescript',
-  },
-  empty: {
-    isDotnet: false, isNextjs: false,
-    defaultValidators: [],
-    checkpointValidators: [],
-    buildCommand: null,
-    contractsOutputType: 'contracts',
-    contractsFilename: 'contracts.cs',
-    contractsLanguage: 'csharp',
-  },
-};
-
-/**
- * Read project stack from .morph/config/config.json.
- * @param {string} cwd - Project root
- * @returns {string|null}
- */
-function readStack(cwd) {
-  const configPath = join(cwd, '.morph', 'config', 'config.json');
-  if (!existsSync(configPath)) return null;
-  try {
-    return JSON.parse(readFileSync(configPath, 'utf8')).project?.stack ?? null;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Get the StackProfile for the current project.
- * @param {string} [cwd] - Project root. Defaults to process.cwd().
- * @param {string} [stackOverride] - Skip config read and use this stack directly.
- * @returns {StackProfile}
- */
-export function getStackProfile(cwd, stackOverride) {
-  const root = cwd ?? process.cwd();
-  const raw = stackOverride ?? readStack(root);
-  const stack = raw?.toLowerCase() ?? 'unknown';
-
-  let profile;
-  if (NEXTJS_STACKS.has(stack)) {
-    profile = PROFILES.nextjs;
-  } else if (NO_VALIDATOR_STACKS.has(stack)) {
-    profile = PROFILES.empty;
-  } else if (DOTNET_STACKS.has(stack) || stack === 'unknown') {
-    profile = PROFILES.dotnet;
-  } else {
-    // Unknown non-.NET stack → empty validators, dotnet contracts (backward compat)
-    profile = PROFILES.empty;
-  }
-
-  return { stack, ...profile };
-}
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+
+/** @typedef {'nextjs'|'dotnet'|'nodejs-cli'|'unknown'} StackName */
+
+/**
+ * @typedef {Object} StackProfile
+ * @property {StackName} stack
+ * @property {boolean} isDotnet
+ * @property {boolean} isNextjs
+ * @property {string[]} defaultValidators
+ * @property {string[]} checkpointValidators
+ * @property {string|null} buildCommand
+ */
+
+const DOTNET_STACKS = new Set(['dotnet', 'aspnet']);
+const NEXTJS_STACKS = new Set(['nextjs', 'next', 'next.js']);
+const NO_VALIDATOR_STACKS = new Set(['nodejs-cli', 'node-cli', 'cli']);
+
+const PROFILES = {
+  dotnet: {
+    isDotnet: true, isNextjs: false,
+    defaultValidators: ['architecture', 'packages'],
+    checkpointValidators: ['architecture', 'packages', 'design-system', 'security'],
+    buildCommand: 'dotnet build --no-restore',
+  },
+  nextjs: {
+    isDotnet: false, isNextjs: true,
+    defaultValidators: ['nextjs-component'],
+    checkpointValidators: ['nextjs-component', 'css'],
+    buildCommand: 'npx tsc --noEmit',
+  },
+  empty: {
+    isDotnet: false, isNextjs: false,
+    defaultValidators: [],
+    checkpointValidators: [],
+    buildCommand: null,
+  },
+};
+
+/**
+ * Read project stack from .morph/config/config.json.
+ */
+function readStack(cwd) {
+  const configPath = join(cwd, '.morph', 'config', 'config.json');
+  if (!existsSync(configPath)) return null;
+  try {
+    return JSON.parse(readFileSync(configPath, 'utf8')).project?.stack ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get the StackProfile for the current project.
+ */
+export function getStackProfile(cwd, stackOverride) {
+  const root = cwd ?? process.cwd();
+  const raw = stackOverride ?? readStack(root);
+  const stack = raw?.toLowerCase() ?? 'unknown';
+
+  let profile;
+  if (NEXTJS_STACKS.has(stack)) {
+    profile = PROFILES.nextjs;
+  } else if (NO_VALIDATOR_STACKS.has(stack)) {
+    profile = PROFILES.empty;
+  } else if (DOTNET_STACKS.has(stack) || stack === 'unknown') {
+    profile = PROFILES.dotnet;
+  } else {
+    profile = PROFILES.empty;
+  }
+
+  return { stack, ...profile };
+}

package/src/lib/tasks/task-parser.js

@@ -114,7 +114,7 @@ export function parseAndGroupTasks(tasksPath) {
  * @returns {Promise<Array<{id, title, status, dependencies, files, checkpoint}>>}
  */
 export async function parseTasksMd(featureName, cwd = process.cwd()) {
-  const tasksPath = join(cwd, `.morph/features/${featureName}/4-tasks/tasks.md`);
+  const tasksPath = join(cwd, `.morph/features/${featureName}/2-plan/tasks.md`);
   let content = '';
   try {
     content = await readFile(tasksPath, 'utf-8');

package/src/lib/tasks/wave-resolver.js

@@ -0,0 +1,353 @@
+/**
+ * @fileoverview Wave Resolver — Dependency-aware task grouping into execution waves.
+ *
+ * Pure algorithm module (no I/O, no state access). Takes parsed task lists and
+ * returns wave assignments. Tasks within a wave have no interdependencies and
+ * don't touch the same files, so they can safely run in parallel.
+ *
+ * @module wave-resolver
+ */
+
+/**
+ * Validate that all dependency references point to existing task IDs.
+ *
+ * @param {Array<{id: string, dependencies: string[]}>} taskList
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validateDependencies(taskList) {
+  const ids = new Set(taskList.map(t => t.id));
+  const errors = [];
+
+  for (const task of taskList) {
+    for (const dep of task.dependencies || []) {
+      if (dep === task.id) {
+        errors.push(`${task.id} depends on itself`);
+      } else if (!ids.has(dep)) {
+        errors.push(`${task.id} depends on ${dep} which does not exist`);
+      }
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Detect circular dependencies using Kahn's algorithm.
+ * Returns the cycle path if found, or null if acyclic.
+ *
+ * @param {Array<{id: string, dependencies: string[]}>} taskList
+ * @returns {{ hasCycle: boolean, cycle: string[]|null }}
+ */
+export function detectCircularDeps(taskList) {
+  const ids = new Set(taskList.map(t => t.id));
+  const inDegree = new Map();
+  const adjacency = new Map(); // dependency → dependents
+
+  for (const task of taskList) {
+    inDegree.set(task.id, 0);
+    if (!adjacency.has(task.id)) adjacency.set(task.id, []);
+  }
+
+  for (const task of taskList) {
+    for (const dep of task.dependencies || []) {
+      if (!ids.has(dep)) continue; // skip invalid refs (caught by validateDependencies)
+      inDegree.set(task.id, (inDegree.get(task.id) || 0) + 1);
+      if (!adjacency.has(dep)) adjacency.set(dep, []);
+      adjacency.get(dep).push(task.id);
+    }
+  }
+
+  // BFS: process zero-in-degree nodes
+  const queue = [];
+  for (const [id, deg] of inDegree) {
+    if (deg === 0) queue.push(id);
+  }
+
+  const processed = new Set();
+  while (queue.length > 0) {
+    const node = queue.shift();
+    processed.add(node);
+    for (const dependent of adjacency.get(node) || []) {
+      inDegree.set(dependent, inDegree.get(dependent) - 1);
+      if (inDegree.get(dependent) === 0) queue.push(dependent);
+    }
+  }
+
+  if (processed.size === taskList.length) {
+    return { hasCycle: false, cycle: null };
+  }
+
+  // Extract cycle from unprocessed nodes via DFS
+  const unprocessed = taskList.filter(t => !processed.has(t.id));
+  const depMap = new Map(taskList.map(t => [t.id, t.dependencies || []]));
+  const visiting = new Set();
+  const path = [];
+
+  function dfs(nodeId) {
+    if (visiting.has(nodeId)) {
+      const cycleStart = path.indexOf(nodeId);
+      return path.slice(cycleStart).concat(nodeId);
+    }
+    if (processed.has(nodeId)) return null;
+
+    visiting.add(nodeId);
+    path.push(nodeId);
+
+    for (const dep of depMap.get(nodeId) || []) {
+      if (!ids.has(dep)) continue;
+      const cycle = dfs(dep);
+      if (cycle) return cycle;
+    }
+
+    visiting.delete(nodeId);
+    path.pop();
+    return null;
+  }
+
+  for (const task of unprocessed) {
+    const cycle = dfs(task.id);
+    if (cycle) return { hasCycle: true, cycle };
+  }
+
+  // Fallback: cycle exists but couldn't extract path
+  return { hasCycle: true, cycle: unprocessed.map(t => t.id) };
+}
+
+/**
+ * Assign a wave level to each task via topological sort.
+ * Tasks with no dependencies go to wave 0. Tasks whose dependencies
+ * are all in wave N go to wave N+1.
+ *
+ * @param {Array<{id: string, dependencies: string[], status?: string}>} taskList
+ * @param {{ includeCompleted?: boolean }} options
+ * @returns {Array<{ waveIndex: number, tasks: string[] }>}
+ */
+export function resolveWaves(taskList, options = {}) {
+  // Filter tasks
+  const activeTasks = options.includeCompleted
+    ? taskList
+    : taskList.filter(t => t.status !== 'completed' && t.status !== 'expanded');
+
+  if (activeTasks.length === 0) return [];
+
+  const ids = new Set(activeTasks.map(t => t.id));
+  const completedIds = new Set(
+    taskList.filter(t => t.status === 'completed' || t.status === 'expanded').map(t => t.id)
+  );
+
+  // Assign levels via BFS
+  const level = new Map();
+  const inDegree = new Map();
+  const adjacency = new Map();
+
+  for (const task of activeTasks) {
+    inDegree.set(task.id, 0);
+    adjacency.set(task.id, []);
+    level.set(task.id, 0);
+  }
+
+  for (const task of activeTasks) {
+    for (const dep of task.dependencies || []) {
+      if (!ids.has(dep)) continue; // dep is completed or doesn't exist → satisfied
+      inDegree.set(task.id, inDegree.get(task.id) + 1);
+      adjacency.get(dep).push(task.id);
+    }
+  }
+
+  // BFS with level tracking
+  const queue = [];
+  for (const [id, deg] of inDegree) {
+    if (deg === 0) {
+      queue.push(id);
+      level.set(id, 0);
+    }
+  }
+
+  while (queue.length > 0) {
+    const node = queue.shift();
+    const nodeLevel = level.get(node);
+
+    for (const dependent of adjacency.get(node)) {
+      const newDeg = inDegree.get(dependent) - 1;
+      inDegree.set(dependent, newDeg);
+
+      // Level = max of all dependency levels + 1
+      const candidateLevel = nodeLevel + 1;
+      if (candidateLevel > level.get(dependent)) {
+        level.set(dependent, candidateLevel);
+      }
+
+      if (newDeg === 0) queue.push(dependent);
+    }
+  }
+
+  // Group by level
+  const waveMap = new Map();
+  for (const [id, lvl] of level) {
+    if (!waveMap.has(lvl)) waveMap.set(lvl, []);
+    waveMap.get(lvl).push(id);
+  }
+
+  // Sort waves and task IDs within waves
+  const waves = [...waveMap.entries()]
+    .sort((a, b) => a[0] - b[0])
+    .map(([idx, tasks]) => ({
+      waveIndex: idx,
+      tasks: tasks.sort()
+    }));
+
+  return waves;
+}
+
+/**
+ * Parse file paths from a task's deliverables/steps section.
+ * Looks for backtick-wrapped paths in deliverable lines.
+ *
+ * @param {string} taskBlock - The markdown block for a single task
+ * @returns {string[]} Array of file paths (deduplicated, normalized to forward slashes)
+ */
+export function parseTaskFiles(taskBlock) {
+  const files = new Set();
+
+  // Match: - [ ] Create/Update/Modify/Delete: `path/to/file`
+  const deliverableRe = /- \[[ x]\]\s*(?:Create|Update|Modify|Delete|Add|Edit|Remove):\s*`([^`]+)`/gi;
+  let match;
+  while ((match = deliverableRe.exec(taskBlock)) !== null) {
+    files.add(match[1].replace(/\\/g, '/'));
+  }
+
+  // Also match: **Files:** `path1`, `path2`
+  const filesFieldRe = /\*\*Files?:\*\*\s*(.+)/i;
+  const filesMatch = filesFieldRe.exec(taskBlock);
+  if (filesMatch) {
+    const backtickRe = /`([^`]+)`/g;
+    let fMatch;
+    while ((fMatch = backtickRe.exec(filesMatch[1])) !== null) {
+      files.add(fMatch[1].replace(/\\/g, '/'));
+    }
+  }
+
+  return [...files];
+}
+
+/**
+ * Detect file conflicts within each wave and redistribute conflicting
+ * tasks to later waves.
+ *
+ * @param {Array<{ waveIndex: number, tasks: string[] }>} waves
+ * @param {Map<string, string[]>} taskFileMap - taskId → file paths
+ * @returns {Array<{ waveIndex: number, tasks: string[] }>}
+ */
+export function resolveFileConflicts(waves, taskFileMap) {
+  if (!taskFileMap || taskFileMap.size === 0) return waves;
+
+  // Deep copy to avoid mutation
+  let result = waves.map(w => ({ waveIndex: w.waveIndex, tasks: [...w.tasks] }));
+  const maxIterations = waves.reduce((sum, w) => sum + w.tasks.length, 0) + 1;
+
+  for (let iter = 0; iter < maxIterations; iter++) {
+    let changed = false;
+
+    for (let wi = 0; wi < result.length; wi++) {
+      const wave = result[wi];
+      const fileOwner = new Map(); // file → first taskId
+      const toDefer = [];
+
+      for (const taskId of wave.tasks) {
+        const files = taskFileMap.get(taskId) || [];
+        let hasConflict = false;
+
+        for (const file of files) {
+          if (fileOwner.has(file)) {
+            hasConflict = true;
+            break;
+          }
+        }
+
+        if (hasConflict) {
+          toDefer.push(taskId);
+        } else {
+          for (const file of files) {
+            fileOwner.set(file, taskId);
+          }
+        }
+      }
+
+      if (toDefer.length > 0) {
+        changed = true;
+        wave.tasks = wave.tasks.filter(t => !toDefer.includes(t));
+
+        // Push to next wave or create one
+        const nextWi = wi + 1;
+        if (nextWi < result.length) {
+          result[nextWi].tasks.push(...toDefer);
+          result[nextWi].tasks.sort();
+        } else {
+          result.push({ waveIndex: result.length, tasks: toDefer.sort() });
+        }
+      }
+    }
+
+    if (!changed) break;
+  }
+
+  // Remove empty waves and re-index
+  result = result.filter(w => w.tasks.length > 0);
+  result.forEach((w, i) => { w.waveIndex = i; });
+
+  return result;
+}
+
+/**
+ * Full resolution pipeline: validate → detect cycles → resolve waves → resolve conflicts.
+ *
+ * @param {Array<{id: string, title?: string, status?: string, dependencies: string[]}>} taskList
+ * @param {Map<string, string[]>} taskFileMap - Optional file map for conflict detection
+ * @returns {{ waves: Array<{ waveIndex: number, tasks: string[] }>, errors: string[], warnings: string[] }}
+ */
+export function resolveWavePlan(taskList, taskFileMap = new Map()) {
+  const errors = [];
+  const warnings = [];
+
+  if (!taskList || taskList.length === 0) {
+    return { waves: [], errors: [], warnings: ['No tasks to resolve'] };
+  }
+
+  // Step 1: Validate dependencies
+  const validation = validateDependencies(taskList);
+  if (!validation.valid) {
+    errors.push(...validation.errors);
+    return { waves: [], errors, warnings };
+  }
+
+  // Step 2: Detect circular dependencies
+  const cycleCheck = detectCircularDeps(taskList);
+  if (cycleCheck.hasCycle) {
+    errors.push(`Circular dependency detected: ${cycleCheck.cycle.join(' → ')}`);
+    return { waves: [], errors, warnings };
+  }
+
+  // Step 3: Resolve waves from dependencies
+  let waves = resolveWaves(taskList);
+
+  // Step 4: Resolve file conflicts
+  if (taskFileMap.size > 0) {
+    const before = waves.map(w => w.tasks.length);
+    waves = resolveFileConflicts(waves, taskFileMap);
+    const after = waves.map(w => w.tasks.length);
+
+    // Report redistributions
+    if (JSON.stringify(before) !== JSON.stringify(after)) {
+      warnings.push('Some tasks were moved to later waves due to file conflicts');
+    }
+  }
+
+  // Report skipped tasks
+  const activeTasks = taskList.filter(t => t.status !== 'completed' && t.status !== 'expanded');
+  const skipped = taskList.length - activeTasks.length;
+  if (skipped > 0) {
+    warnings.push(`${skipped} completed/expanded task(s) excluded from wave plan`);
+  }
+
+  return { waves, errors, warnings };
+}

package/src/lib/validators/checkpoint-persistence.js

@@ -3,7 +3,7 @@
  *
  * Persists checkpoint validation results to disk for traceability.
  * Each checkpoint writes a JSON file to:
- *   .morph/features/{feature}/5-implement/validations/checkpoint-{N}.json
+ *   .morph/features/{feature}/3-implement/validations/checkpoint-{N}.json
  */
 
 import { mkdirSync, writeFileSync } from 'fs';
@@ -18,7 +18,7 @@ import { join } from 'path';
  * @returns {string} Path to the saved JSON file
  */
 export function persistCheckpointValidation(projectPath, featureName, result) {
-  const dir = join(projectPath, `.morph/features/${featureName}/5-implement/validations`);
+  const dir = join(projectPath, `.morph/features/${featureName}/3-implement/validations`);
   mkdirSync(dir, { recursive: true });
 
   const filename = `checkpoint-${result.checkpointNum}.json`;