@polymorphism-tech/morph-spec 4.21.0 → 5.0.1

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

@@ -0,0 +1,512 @@
+/**
+ * Implementation Mandate Generator
+ *
+ * Synthesizes all spec phase outputs (spec.md, contracts, plan.md, tasks.md,
+ * decisions.md) into a single task-structured implementation mandate.
+ *
+ * The mandate is the primary context artifact for the implement phase —
+ * each task section is self-contained with acceptance criteria, contracts,
+ * file paths, and architectural constraints.
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * v5: parseTaskFromMarkdown lived in sprint-contract-generator. Inlined here.
+ */
+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 };
+}
+
+/**
+ * Extract all FR sections from spec.md.
+ *
+ * @param {string} specContent - Full spec.md content
+ * @returns {Map<string, { title: string, content: string, criteria: string[] }>}
+ */
+export function parseFRSections(specContent) {
+  const sections = new Map();
+  const frPattern = /^##\s+(FR\d+)[:\s—–-]+(.+?)$/gm;
+  let match;
+  const matches = [];
+
+  while ((match = frPattern.exec(specContent)) !== null) {
+    matches.push({
+      id: match[1],
+      title: match[2].trim(),
+      start: match.index,
+      headerEnd: match.index + match[0].length,
+    });
+  }
+
+  for (let i = 0; i < matches.length; i++) {
+    const current = matches[i];
+    const nextStart = i + 1 < matches.length ? matches[i + 1].start : specContent.length;
+    const body = specContent.slice(current.headerEnd, nextStart).trim();
+
+    // Extract bullet points as acceptance criteria
+    const criteria = [];
+    const bulletPattern = /^[\s]*[-*]\s+(.+)/gm;
+    let bulletMatch;
+    while ((bulletMatch = bulletPattern.exec(body)) !== null) {
+      criteria.push(bulletMatch[1].trim());
+    }
+
+    sections.set(current.id, {
+      title: current.title,
+      content: body,
+      criteria,
+    });
+  }
+
+  return sections;
+}
+
+/**
+ * Extract contract types/interfaces from contracts file content.
+ * Matches C# records, classes, interfaces and TypeScript types/interfaces.
+ *
+ * @param {string} contractsContent - Full contracts.cs or contracts.ts content
+ * @returns {Map<string, string>} Map of type name → definition
+ */
+export function parseContracts(contractsContent) {
+  const types = new Map();
+
+  // C# sealed records: sealed record Foo(...)
+  const csRecordPattern = /^\s*((?:public\s+)?sealed\s+record\s+\w+\([^)]*\)\s*;)/gm;
+  let match;
+  while ((match = csRecordPattern.exec(contractsContent)) !== null) {
+    const nameMatch = match[1].match(/record\s+(\w+)/);
+    if (nameMatch) {
+      types.set(nameMatch[1], match[1].trim());
+    }
+  }
+
+  // C# interfaces: public interface IFoo { ... }
+  const csInterfacePattern = /^\s*((?:public\s+)?interface\s+\w+\s*\{[^}]*\})/gms;
+  while ((match = csInterfacePattern.exec(contractsContent)) !== null) {
+    const nameMatch = match[1].match(/interface\s+(\w+)/);
+    if (nameMatch) {
+      types.set(nameMatch[1], match[1].trim());
+    }
+  }
+
+  // TypeScript types/interfaces
+  const tsTypePattern = /^\s*(export\s+(?:type|interface)\s+\w+[\s\S]*?(?:\};?|=[^;]+;))/gm;
+  while ((match = tsTypePattern.exec(contractsContent)) !== null) {
+    const nameMatch = match[1].match(/(?:type|interface)\s+(\w+)/);
+    if (nameMatch) {
+      types.set(nameMatch[1], match[1].trim());
+    }
+  }
+
+  return types;
+}
+
+/**
+ * Extract file paths per task from plan.md.
+ * Looks for task references followed by file paths.
+ *
+ * @param {string} planContent - Full plan.md content
+ * @param {string} taskId - Task ID (e.g., 'T001')
+ * @returns {string[]} File paths
+ */
+export function extractTaskFilePaths(planContent, taskId) {
+  const paths = [];
+
+  // Look for task section in plan
+  const taskSectionPattern = new RegExp(
+    `(?:^|\\n).*${taskId}[^\\n]*\\n([\\s\\S]*?)(?=\\n(?:#+\\s|$)|$)`,
+    'i'
+  );
+  const sectionMatch = planContent.match(taskSectionPattern);
+  if (!sectionMatch) return paths;
+
+  const section = sectionMatch[1];
+  // Extract file paths (common patterns)
+  const filePatterns = [
+    /`([^`]+\.\w{1,6})`/g,                          // backtick-wrapped paths
+    /(?:^|\s)([\w/.]+\.(?:cs|ts|tsx|js|jsx|json|md|yaml|yml|csproj))/gm,  // bare paths
+  ];
+
+  for (const pattern of filePatterns) {
+    let fileMatch;
+    while ((fileMatch = pattern.exec(section)) !== null) {
+      const filePath = fileMatch[1].trim();
+      if (filePath.length > 3 && !paths.includes(filePath)) {
+        paths.push(filePath);
+      }
+    }
+  }
+
+  return paths;
+}
+
+/**
+ * Extract architectural constraints from decisions.md.
+ *
+ * @param {string} decisionsContent - Full decisions.md content
+ * @returns {string[]} One-line constraint summaries
+ */
+export function parseDecisions(decisionsContent) {
+  const constraints = [];
+  const adrPattern = /^###?\s+(ADR-\d+)[:\s—–-]+(.+?)$/gm;
+  let match;
+
+  while ((match = adrPattern.exec(decisionsContent)) !== null) {
+    constraints.push(`${match[1]}: ${match[2].trim()}`);
+  }
+
+  return constraints;
+}
+
+/**
+ * Extract all task IDs from tasks.md in order.
+ *
+ * @param {string} tasksContent - Full tasks.md content
+ * @returns {string[]} Task IDs in order (e.g., ['T001', 'T002', ...])
+ */
+export function extractTaskIds(tasksContent) {
+  const ids = [];
+  const pattern = /^##\s+(T\d+)[:\s]/gm;
+  let match;
+  while ((match = pattern.exec(tasksContent)) !== null) {
+    if (!ids.includes(match[1])) {
+      ids.push(match[1]);
+    }
+  }
+  return ids;
+}
+
+/**
+ * Find contract types relevant to an FR or task.
+ * Matches by: type name in content, or FR title keywords in type name.
+ *
+ * @param {string} searchText - FR content + task title/description
+ * @param {Map<string, string>} contracts - Parsed contracts
+ * @returns {string[]} Matching contract definitions
+ */
+function findRelevantContracts(searchText, contracts) {
+  const relevant = [];
+  const searchLower = searchText.toLowerCase();
+
+  for (const [typeName, definition] of contracts) {
+    // Direct match: type name appears in the search text
+    if (searchText.includes(typeName)) {
+      relevant.push(definition);
+      continue;
+    }
+    // Keyword match: split type name into words (e.g., UserRegisterRequest → user, register, request)
+    // and check if the significant words appear in the search text
+    const typeWords = typeName
+      .replace(/([a-z])([A-Z])/g, '$1 $2')
+      .toLowerCase()
+      .split(/\s+/)
+      .filter(w => w.length > 3 && !['request', 'response', 'result'].includes(w));
+    if (typeWords.length > 0 && typeWords.every(w => searchLower.includes(w))) {
+      relevant.push(definition);
+    }
+  }
+  return relevant;
+}
+
+/**
+ * Generate an implementation mandate from spec phase outputs.
+ *
+ * @param {string} projectPath - Project root
+ * @param {string} featureName - Feature name
+ * @returns {{ mandate: string, stats: { frCount: number, taskCount: number, totalChars: number } }|null}
+ */
+export function generateMandate(projectPath, featureName) {
+  const featureDir = join(projectPath, '.morph/features', featureName);
+
+  // Read required files
+  const tasksPath = join(featureDir, '2-plan/tasks.md');
+  const specPath = join(featureDir, '2-plan/spec.md');
+
+  if (!existsSync(tasksPath) || !existsSync(specPath)) return null;
+
+  const tasksContent = readFileSync(tasksPath, 'utf-8');
+  const specContent = readFileSync(specPath, 'utf-8');
+
+  // Read optional files
+  const contractsPaths = [
+    join(featureDir, '2-plan/contracts.cs'),
+    join(featureDir, '2-plan/contracts.ts'),
+  ];
+  let contractsContent = '';
+  for (const cp of contractsPaths) {
+    if (existsSync(cp)) {
+      contractsContent += readFileSync(cp, 'utf-8') + '\n';
+    }
+  }
+
+  const planPath = join(featureDir, '2-plan/plan.md');
+  const planContent = existsSync(planPath) ? readFileSync(planPath, 'utf-8') : '';
+
+  const decisionsPath = join(featureDir, '2-plan/decisions.md');
+  const decisionsContent = existsSync(decisionsPath) ? readFileSync(decisionsPath, 'utf-8') : '';
+
+  const proposalPath = join(featureDir, '0-proposal/proposal.md');
+  const proposalContent = existsSync(proposalPath) ? readFileSync(proposalPath, 'utf-8') : '';
+
+  // Read project config
+  let stack = '';
+  let architecture = '';
+  let workflow = '';
+  try {
+    const configPath = join(projectPath, '.morph/config/config.json');
+    if (existsSync(configPath)) {
+      const config = JSON.parse(readFileSync(configPath, 'utf-8'));
+      stack = config?.project?.stack || '';
+      architecture = config?.architecture?.style || '';
+      workflow = config?.workflow || '';
+    }
+  } catch { /* ignore */ }
+
+  // Parse all inputs
+  const frSections = parseFRSections(specContent);
+  const contracts = parseContracts(contractsContent);
+  const decisions = parseDecisions(decisionsContent);
+  const taskIds = extractTaskIds(tasksContent);
+
+  // Build mandate
+  const lines = [];
+
+  // Header
+  lines.push(`# Implementation Mandate: ${featureName}`);
+  lines.push('');
+  lines.push(`**Generated:** ${new Date().toISOString().split('T')[0]} | **FRs:** ${frSections.size} | **Tasks:** ${taskIds.length}`);
+  if (stack || architecture) {
+    lines.push(`**Stack:** ${stack || 'unspecified'} | **Architecture:** ${architecture || 'unspecified'}`);
+  }
+
+  // Overview from proposal
+  if (proposalContent) {
+    lines.push('');
+    lines.push('## Overview');
+    // Extract first paragraph after the title
+    const paragraphs = proposalContent
+      .split(/\n\n+/)
+      .filter(p => p.trim() && !p.trim().startsWith('#'))
+      .slice(0, 1);
+    if (paragraphs.length > 0) {
+      lines.push(paragraphs[0].trim());
+    }
+  }
+
+  // Architectural constraints
+  if (decisions.length > 0) {
+    lines.push('');
+    lines.push('## Architectural Constraints');
+    for (const d of decisions) {
+      lines.push(`- ${d}`);
+    }
+  }
+
+  // Task sections
+  for (const taskId of taskIds) {
+    const task = parseTaskFromMarkdown(tasksContent, taskId);
+    if (!task) continue;
+
+    lines.push('');
+    lines.push('---');
+    lines.push('');
+    lines.push(`## ${taskId}: ${task.title}`);
+
+    // Metadata line
+    const metaParts = [];
+    if (task.frs.length > 0) metaParts.push(`**FRs:** ${task.frs.join(', ')}`);
+    const filePaths = planContent ? extractTaskFilePaths(planContent, taskId) : [];
+    if (filePaths.length > 0) metaParts.push(`**Files:** ${filePaths.join(', ')}`);
+    if (metaParts.length > 0) lines.push(metaParts.join(' | '));
+
+    // Acceptance criteria from FR sections
+    const allCriteria = [];
+    const allFRContracts = [];
+    for (const frId of task.frs) {
+      const fr = frSections.get(frId);
+      if (fr) {
+        allCriteria.push(...fr.criteria);
+        // Search for contracts in FR content + task title for broader matching
+        const searchText = `${fr.title} ${fr.content} ${task.title} ${task.description}`;
+        allFRContracts.push(...findRelevantContracts(searchText, contracts));
+      }
+    }
+
+    if (allCriteria.length > 0) {
+      lines.push('');
+      lines.push('### Acceptance Criteria');
+      for (const c of allCriteria) {
+        lines.push(`- [ ] ${c}`);
+      }
+    }
+
+    // Contracts
+    const uniqueContracts = [...new Set(allFRContracts)];
+    if (uniqueContracts.length > 0) {
+      lines.push('');
+      lines.push('### Contracts');
+      lines.push('```');
+      lines.push(uniqueContracts.join('\n'));
+      lines.push('```');
+    }
+
+    // Task description as notes
+    if (task.description) {
+      lines.push('');
+      lines.push('### Notes');
+      lines.push(task.description);
+    }
+  }
+
+  // Verification summary
+  lines.push('');
+  lines.push('---');
+  lines.push('');
+  lines.push('## Verification');
+  lines.push('```bash');
+  if (stack.includes('dotnet')) {
+    lines.push('dotnet build');
+    lines.push('dotnet test');
+  } else {
+    lines.push('npm run build');
+    lines.push('npm test');
+  }
+  lines.push('```');
+
+  const mandate = lines.join('\n');
+
+  return {
+    mandate,
+    stats: {
+      frCount: frSections.size,
+      taskCount: taskIds.length,
+      totalChars: mandate.length,
+    },
+  };
+}
+
+/**
+ * Extract a single task's section from a generated mandate.
+ *
+ * @param {string} mandateContent - Full mandate.md content
+ * @param {string} taskId - Task ID (e.g., 'T003')
+ * @returns {string|null} Task section text or null if not found
+ */
+export function extractTaskSection(mandateContent, taskId) {
+  // Find the start of this task's section
+  const headerPattern = new RegExp(`^## ${taskId}:`, 'm');
+  const headerMatch = headerPattern.exec(mandateContent);
+  if (!headerMatch) return null;
+
+  const start = headerMatch.index;
+
+  // Find the end: next task header, Verification section, or end of content
+  const rest = mandateContent.slice(start + 1);
+  const endPatterns = [
+    /\n## T\d+:/,
+    /\n## Verification/,
+  ];
+
+  let end = mandateContent.length;
+  for (const pattern of endPatterns) {
+    const endMatch = pattern.exec(rest);
+    if (endMatch) {
+      const candidate = start + 1 + endMatch.index;
+      if (candidate < end) end = candidate;
+    }
+  }
+
+  // Extract and trim, removing trailing --- separators
+  let section = mandateContent.slice(start, end).trim();
+  section = section.replace(/\n---\s*$/, '').trim();
+
+  return section;
+}
+
+/**
+ * Extract multiple task sections (for agent dispatch).
+ *
+ * @param {string} mandateContent - Full mandate.md content
+ * @param {string[]} taskIds - Task IDs (e.g., ['T001', 'T002', 'T003'])
+ * @returns {string} Combined task sections
+ */
+export function extractTaskSections(mandateContent, taskIds) {
+  const sections = [];
+  for (const taskId of taskIds) {
+    const section = extractTaskSection(mandateContent, taskId);
+    if (section) sections.push(section);
+  }
+  return sections.join('\n\n---\n\n');
+}
+
+/**
+ * Generate a mandate overview (for session start injection).
+ * Shows FR list with task mapping and completion status.
+ *
+ * @param {string} mandateContent - Full mandate.md content
+ * @param {Object} taskStatus - Map of taskId → status ('completed'|'in_progress'|'pending')
+ * @returns {string} Overview text
+ */
+export function generateMandateOverview(mandateContent, taskStatus = {}) {
+  const lines = [];
+
+  // Extract task-to-FR mapping from mandate
+  const taskFRMap = new Map();
+  const frTaskMap = new Map();
+
+  const taskPattern = /^## (T\d+): .+$/gm;
+  const frLinePattern = /^\*\*FRs:\*\*\s+(.+?)(?:\s*\||$)/gm;
+
+  let match;
+  let lastTaskId = null;
+
+  while ((match = taskPattern.exec(mandateContent)) !== null) {
+    lastTaskId = match[1];
+    // Look for FRs line right after task header
+    const afterHeader = mandateContent.slice(match.index + match[0].length, match.index + match[0].length + 200);
+    const frMatch = afterHeader.match(/\*\*FRs:\*\*\s+([^\n|]+)/);
+    if (frMatch) {
+      const frs = frMatch[1].split(',').map(f => f.trim()).filter(Boolean);
+      taskFRMap.set(lastTaskId, frs);
+      for (const fr of frs) {
+        if (!frTaskMap.has(fr)) frTaskMap.set(fr, []);
+        frTaskMap.get(fr).push(lastTaskId);
+      }
+    }
+  }
+
+  // Build overview
+  lines.push('Implementation Mandate Overview:');
+
+  for (const [frId, taskIds] of frTaskMap) {
+    const taskStatuses = taskIds.map(tid => {
+      const status = taskStatus[tid] || 'pending';
+      if (status === 'completed') return `${tid} ✓`;
+      if (status === 'in_progress') return `${tid} →`;
+      return tid;
+    });
+    lines.push(`  ${frId} → ${taskStatuses.join(', ')}`);
+  }
+
+  // Next task
+  const allTaskIds = [...taskFRMap.keys()];
+  const nextTask = allTaskIds.find(tid => {
+    const status = taskStatus[tid];
+    return status === 'in_progress' || !status || status === 'pending';
+  });
+  if (nextTask) {
+    const status = taskStatus[nextTask];
+    const verb = status === 'in_progress' ? 'In progress' : 'Next';
+    lines.push(`  ${verb}: ${nextTask}`);
+  }
+
+  return lines.join('\n');
+}

package/src/lib/generators/metadata-extractor.js

@@ -308,7 +308,7 @@ export function extractTasksMetadata(tasksPath) {
       byStatus: {
         pending: regularTasks.filter(t => t.status === 'pending').length,
         inProgress: regularTasks.filter(t => t.status === 'in_progress').length,
-        done: regularTasks.filter(t => t.status === 'done').length,
+        completed: regularTasks.filter(t => t.status === 'completed').length,
         blocked: regularTasks.filter(t => t.status === 'blocked').length
       },
 

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

@@ -4,7 +4,7 @@
  * Auto-generates recap.md from real project data: state.json, contract compliance,
  * validation results, and decisions. Replaces manual template filling.
  *
- * MORPH-SPEC 3.0 - Phase B: Spec-Driven Pipeline
+ * MORPH-SPEC 5.0 - Recap Generator
  */
 
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
@@ -98,10 +98,9 @@ function getTasksSummary(feature) {
     };
   }
 
-  // v3: feature.tasks is a counter object {total, completed, inProgress, pending}
-  // Use feature.taskList for individual items if available
+  // v3-v4 legacy: feature.tasks is a counter object {total, completed, inProgress, pending}
   const counters = feature.tasks || {};
-  const items = feature.taskList || [];
+  const items = [];
   const total = counters.total || items.length || 0;
   const completedCount = counters.completed ?? items.filter(t => t.status === 'completed').length;
   const pendingCount = counters.pending ?? items.filter(t => t.status === 'pending').length;