@polymorphism-tech/morph-spec 8.43.0 → 8.45.0

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

@@ -1,209 +1,209 @@
-/**
- * Task Parser — Shared utilities for reading, parsing, and grouping tasks.
- *
- * Extracted from bin/task-manager.cjs and dispatch-agents.js so all
- * consumers share the same parsing logic without duplication.
- */
-
-import { readFile } from 'fs/promises';
-import { readFileSync, existsSync } from 'fs';
-import { join } from 'path';
-
-// ============================================================================
-// TASK_CATEGORY_TO_GROUP — maps task categories to parallel groups
-// ============================================================================
-
-const TASK_CATEGORY_TO_GROUP = {
-  'domain': 'backend',
-  'domain-bc': 'backend',
-  'infrastructure': 'backend',
-  'application': 'backend',
-  'presentation': 'frontend',
-  'tests': 'tests',
-  'infra': 'infra',
-  'docs': 'docs',
-};
-
-// ============================================================================
-// parseTaskList — structured task parsing with error reporting
-// ============================================================================
-
-/**
- * Parse tasks.md content into structured task objects with error reporting.
- *
- * @param {string} content - Raw tasks.md content
- * @returns {{ tasks: ParsedTask[], errors: TaskParseError[], groups: Object<string, string[]> }}
- */
-export function parseTaskList(content) {
-  const tasks = [];
-  const errors = [];
-  const groups = {};
-
-  const taskHeadingRe = /^###\s+(T\d{3,})\s*[—–:\-]\s*(.+)$/gm;
-  const groupRe = /(?:\*\*Group\*\*\s*:\s*`?([a-z-]+)`?|- \*\*Group:\*\*\s*`?([a-z-]+)`?)/i;
-  const categoryRe = /(?:\*\*category\*\*\s*:\s*`?([a-z-]+)`?|category:\s*([a-z-]+))/i;
-
-  let headingMatch;
-  const taskPositions = [];
-
-  while ((headingMatch = taskHeadingRe.exec(content)) !== null) {
-    taskPositions.push({ id: headingMatch[1], title: headingMatch[2].trim(), pos: headingMatch.index });
-  }
-
-  for (let i = 0; i < taskPositions.length; i++) {
-    const { id, title, pos } = taskPositions[i];
-    const end = i + 1 < taskPositions.length ? taskPositions[i + 1].pos : content.length;
-    const block = content.slice(pos, end);
-
-    // Try group field first (v4), fall back to category field (v3)
-    const grpMatch = groupRe.exec(block);
-    const catMatch = categoryRe.exec(block);
-    let group;
-    if (grpMatch) {
-      group = (grpMatch[1] || grpMatch[2]).toLowerCase();
-    } else if (catMatch) {
-      const category = (catMatch[1] || catMatch[2]).toLowerCase();
-      group = TASK_CATEGORY_TO_GROUP[category] || 'backend';
-    } else {
-      group = 'backend';
-    }
-
-    tasks.push({ id, title, group });
-
-    if (!groups[group]) groups[group] = [];
-    groups[group].push(id);
-  }
-
-  return { tasks, errors, groups };
-}
-
-// ============================================================================
-// parseAndGroupTasks — drop-in replacement for dispatch-agents.js
-// ============================================================================
-
-/**
- * Parse tasks.md and return a map of { group -> taskId[] }.
- * Gracefully returns {} if the file doesn't exist or is unparseable.
- *
- * @param {string} tasksPath - Absolute path to tasks.md
- * @returns {Object<string, string[]>}
- */
-export function parseAndGroupTasks(tasksPath) {
-  if (!existsSync(tasksPath)) return {};
-
-  try {
-    const content = readFileSync(tasksPath, 'utf8');
-    return parseTaskList(content).groups;
-  } catch {
-    return {};
-  }
-}
-
-// ============================================================================
-// parseTasksMd
-// ============================================================================
-
-/**
- * Parse tasks.md to extract task stubs for the v3 state format.
- * Accepts headings in either format:
- *   ### T001 — Task title   (em-dash / en-dash / hyphen)
- *   ### T001: Task title    (colon)
- *
- * @param {string} featureName
- * @param {string} [cwd] - Project root (defaults to process.cwd())
- * @returns {Promise<Array<{id, title, status, dependencies, files, checkpoint}>>}
- */
-export async function parseTasksMd(featureName, cwd = process.cwd()) {
-  const tasksPath = join(cwd, `.morph/features/${featureName}/2-plan/tasks.md`);
-  let content = '';
-  try {
-    content = await readFile(tasksPath, 'utf-8');
-  } catch {
-    return [];
-  }
-
-  // Phase 1: collect heading positions
-  const headingRe = /^###\s+(T\d+)\s*[—–:\-]\s*(.+)$/gm;
-  const depRe = /\*\*Dependenc(?:y|ies):\*\*\s*(.+)/i;
-  const positions = [];
-  let match;
-  while ((match = headingRe.exec(content)) !== null) {
-    positions.push({ id: match[1], title: match[2].trim(), pos: match.index });
-  }
-
-  // Phase 2: extract body and parse dependencies
-  const tasks = [];
-  for (let i = 0; i < positions.length; i++) {
-    const { id, title, pos } = positions[i];
-    const end = i + 1 < positions.length ? positions[i + 1].pos : content.length;
-    const block = content.slice(pos, end);
-
-    let dependencies = [];
-    const depMatch = depRe.exec(block);
-    if (depMatch) {
-      const val = depMatch[1].trim();
-      if (val.toLowerCase() !== 'none') {
-        dependencies = val.split(/[,\s]+/).filter(s => /^T\d+$/.test(s));
-      }
-    }
-
-    tasks.push({ id, title, status: 'pending', dependencies, files: [], checkpoint: null });
-  }
-  return tasks;
-}
-
-// ============================================================================
-// ensureTaskList
-// ============================================================================
-
-/**
- * Ensure feature.taskList exists (array of individual task objects).
- *
- * In v3 state, feature.tasks is a counter object {total, completed, …}.
- * Individual task objects live in feature.taskList.
- *
- * @param {Object} feature - Feature state object (mutated in place)
- * @param {string} featureName
- * @param {string} [cwd]
- * @returns {Promise<Array>} The task list
- */
-export async function ensureTaskList(feature, featureName, cwd = process.cwd()) {
-  if (Array.isArray(feature.tasks)) {
-    // v2 format: tasks IS the array
-    return feature.tasks;
-  }
-  // v3 format: use taskList or build from tasks.md
-  if (!feature.taskList || feature.taskList.length === 0) {
-    feature.taskList = await parseTasksMd(featureName, cwd);
-  }
-  return feature.taskList;
-}
-
-// ============================================================================
-// syncCounters
-// ============================================================================
-
-/**
- * After modifying taskList, sync the counter fields back to feature.tasks.
- * tasks.total is derived from the actual taskList length (not trusted from state).
- *
- * @deprecated Prefer reading directly from feature.taskList. Counter fields
- * (feature.tasks) duplicate native Claude Code task tracking. This function
- * is kept for backward compatibility but will be removed in a future version.
- *
- * @param {Object} feature - Feature state object (mutated in place)
- */
-export function syncCounters(feature) {
-  if (Array.isArray(feature.tasks)) return; // v2 format — nothing to sync
-  // Safety: ensure feature.tasks is an object (may be undefined after migration or corruption)
-  if (!feature.tasks || typeof feature.tasks !== 'object') {
-    feature.tasks = { total: 0, completed: 0, inProgress: 0, pending: 0 };
-  }
-  const list = feature.taskList || [];
-  // Exclude expanded tasks — they are replaced by their sub-tasks
-  const active = list.filter(t => t.status !== 'expanded');
-  feature.tasks.total = active.length;
-  feature.tasks.completed = active.filter(t => t.status === 'completed').length;
-  feature.tasks.inProgress = active.filter(t => t.status === 'in_progress').length;
-  feature.tasks.pending = active.filter(t => t.status === 'pending').length;
-}
+/**
+ * Task Parser — Shared utilities for reading, parsing, and grouping tasks.
+ *
+ * Extracted from bin/task-manager.cjs and dispatch-agents.js so all
+ * consumers share the same parsing logic without duplication.
+ */
+
+import { readFile } from 'fs/promises';
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+
+// ============================================================================
+// TASK_CATEGORY_TO_GROUP — maps task categories to parallel groups
+// ============================================================================
+
+const TASK_CATEGORY_TO_GROUP = {
+  'domain': 'backend',
+  'domain-bc': 'backend',
+  'infrastructure': 'backend',
+  'application': 'backend',
+  'presentation': 'frontend',
+  'tests': 'tests',
+  'infra': 'infra',
+  'docs': 'docs',
+};
+
+// ============================================================================
+// parseTaskList — structured task parsing with error reporting
+// ============================================================================
+
+/**
+ * Parse tasks.md content into structured task objects with error reporting.
+ *
+ * @param {string} content - Raw tasks.md content
+ * @returns {{ tasks: ParsedTask[], errors: TaskParseError[], groups: Object<string, string[]> }}
+ */
+export function parseTaskList(content) {
+  const tasks = [];
+  const errors = [];
+  const groups = {};
+
+  const taskHeadingRe = /^###\s+(T\d{3,})\s*[—–:\-]\s*(.+)$/gm;
+  const groupRe = /(?:\*\*Group\*\*\s*:\s*`?([a-z-]+)`?|- \*\*Group:\*\*\s*`?([a-z-]+)`?)/i;
+  const categoryRe = /(?:\*\*category\*\*\s*:\s*`?([a-z-]+)`?|category:\s*([a-z-]+))/i;
+
+  let headingMatch;
+  const taskPositions = [];
+
+  while ((headingMatch = taskHeadingRe.exec(content)) !== null) {
+    taskPositions.push({ id: headingMatch[1], title: headingMatch[2].trim(), pos: headingMatch.index });
+  }
+
+  for (let i = 0; i < taskPositions.length; i++) {
+    const { id, title, pos } = taskPositions[i];
+    const end = i + 1 < taskPositions.length ? taskPositions[i + 1].pos : content.length;
+    const block = content.slice(pos, end);
+
+    // Try group field first (v4), fall back to category field (v3)
+    const grpMatch = groupRe.exec(block);
+    const catMatch = categoryRe.exec(block);
+    let group;
+    if (grpMatch) {
+      group = (grpMatch[1] || grpMatch[2]).toLowerCase();
+    } else if (catMatch) {
+      const category = (catMatch[1] || catMatch[2]).toLowerCase();
+      group = TASK_CATEGORY_TO_GROUP[category] || 'backend';
+    } else {
+      group = 'backend';
+    }
+
+    tasks.push({ id, title, group });
+
+    if (!groups[group]) groups[group] = [];
+    groups[group].push(id);
+  }
+
+  return { tasks, errors, groups };
+}
+
+// ============================================================================
+// parseAndGroupTasks — drop-in replacement for dispatch-agents.js
+// ============================================================================
+
+/**
+ * Parse tasks.md and return a map of { group -> taskId[] }.
+ * Gracefully returns {} if the file doesn't exist or is unparseable.
+ *
+ * @param {string} tasksPath - Absolute path to tasks.md
+ * @returns {Object<string, string[]>}
+ */
+export function parseAndGroupTasks(tasksPath) {
+  if (!existsSync(tasksPath)) return {};
+
+  try {
+    const content = readFileSync(tasksPath, 'utf8');
+    return parseTaskList(content).groups;
+  } catch {
+    return {};
+  }
+}
+
+// ============================================================================
+// parseTasksMd
+// ============================================================================
+
+/**
+ * Parse tasks.md to extract task stubs for the v3 state format.
+ * Accepts headings in either format:
+ *   ### T001 — Task title   (em-dash / en-dash / hyphen)
+ *   ### T001: Task title    (colon)
+ *
+ * @param {string} featureName
+ * @param {string} [cwd] - Project root (defaults to process.cwd())
+ * @returns {Promise<Array<{id, title, status, dependencies, files, checkpoint}>>}
+ */
+export async function parseTasksMd(featureName, cwd = process.cwd()) {
+  const tasksPath = join(cwd, `.morph/features/${featureName}/2-plan/tasks.md`);
+  let content = '';
+  try {
+    content = await readFile(tasksPath, 'utf-8');
+  } catch {
+    return [];
+  }
+
+  // Phase 1: collect heading positions
+  const headingRe = /^###\s+(T\d+)\s*[—–:\-]\s*(.+)$/gm;
+  const depRe = /\*\*Dependenc(?:y|ies):\*\*\s*(.+)/i;
+  const positions = [];
+  let match;
+  while ((match = headingRe.exec(content)) !== null) {
+    positions.push({ id: match[1], title: match[2].trim(), pos: match.index });
+  }
+
+  // Phase 2: extract body and parse dependencies
+  const tasks = [];
+  for (let i = 0; i < positions.length; i++) {
+    const { id, title, pos } = positions[i];
+    const end = i + 1 < positions.length ? positions[i + 1].pos : content.length;
+    const block = content.slice(pos, end);
+
+    let dependencies = [];
+    const depMatch = depRe.exec(block);
+    if (depMatch) {
+      const val = depMatch[1].trim();
+      if (val.toLowerCase() !== 'none') {
+        dependencies = val.split(/[,\s]+/).filter(s => /^T\d+$/.test(s));
+      }
+    }
+
+    tasks.push({ id, title, status: 'pending', dependencies, files: [], checkpoint: null });
+  }
+  return tasks;
+}
+
+// ============================================================================
+// ensureTaskList
+// ============================================================================
+
+/**
+ * Ensure feature.taskList exists (array of individual task objects).
+ *
+ * In v3 state, feature.tasks is a counter object {total, completed, …}.
+ * Individual task objects live in feature.taskList.
+ *
+ * @param {Object} feature - Feature state object (mutated in place)
+ * @param {string} featureName
+ * @param {string} [cwd]
+ * @returns {Promise<Array>} The task list
+ */
+export async function ensureTaskList(feature, featureName, cwd = process.cwd()) {
+  if (Array.isArray(feature.tasks)) {
+    // v2 format: tasks IS the array
+    return feature.tasks;
+  }
+  // v3 format: use taskList or build from tasks.md
+  if (!feature.taskList || feature.taskList.length === 0) {
+    feature.taskList = await parseTasksMd(featureName, cwd);
+  }
+  return feature.taskList;
+}
+
+// ============================================================================
+// syncCounters
+// ============================================================================
+
+/**
+ * After modifying taskList, sync the counter fields back to feature.tasks.
+ * tasks.total is derived from the actual taskList length (not trusted from state).
+ *
+ * @deprecated Prefer reading directly from feature.taskList. Counter fields
+ * (feature.tasks) duplicate native Claude Code task tracking. This function
+ * is kept for backward compatibility but will be removed in a future version.
+ *
+ * @param {Object} feature - Feature state object (mutated in place)
+ */
+export function syncCounters(feature) {
+  if (Array.isArray(feature.tasks)) return; // v2 format — nothing to sync
+  // Safety: ensure feature.tasks is an object (may be undefined after migration or corruption)
+  if (!feature.tasks || typeof feature.tasks !== 'object') {
+    feature.tasks = { total: 0, completed: 0, inProgress: 0, pending: 0 };
+  }
+  const list = feature.taskList || [];
+  // Exclude expanded tasks — they are replaced by their sub-tasks
+  const active = list.filter(t => t.status !== 'expanded');
+  feature.tasks.total = active.length;
+  feature.tasks.completed = active.filter(t => t.status === 'completed').length;
+  feature.tasks.inProgress = active.filter(t => t.status === 'in_progress').length;
+  feature.tasks.pending = active.filter(t => t.status === 'pending').length;
+}

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

@@ -103,16 +103,15 @@ export function validateTasksJson(data) {
         errors.push(`${ctx}.agent must be the bare persona id — no "morph-" prefix (got "${task.agent}")`);
       }
     }
-    // Optional: veredito de reuso carimbado por morph-plan §2b. Type-check e
-    // enum apenas — quem cobra o veredito contra o código que foi escrito é o
-    // reuse-validator, no `morph-spec verify`, e não este parser.
+    // Type-check e enum apenas: quem cobra o veredito contra o código é o
+    // reuse-validator, no `morph-spec verify`.
     if (task.reuse !== undefined) {
       if (!Array.isArray(task.reuse)) {
-        errors.push(`${ctx}.reuse must be an array of { concept, verdict, target? }`);
+        errors.push(`${ctx}.reuse must be an array of { concept, verdict, target?, why? }`);
       } else {
         task.reuse.forEach((entry, j) => {
           if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
-            errors.push(`${ctx}.reuse[${j}] must be an object { concept, verdict, target? }`);
+            errors.push(`${ctx}.reuse[${j}] must be an object { concept, verdict, target?, why? }`);
             return;
           }
           if (typeof entry.concept !== 'string' || !entry.concept.trim()) {
@@ -124,6 +123,9 @@ export function validateTasksJson(data) {
           if (entry.target !== undefined && typeof entry.target !== 'string') {
             errors.push(`${ctx}.reuse[${j}].target must be a string path`);
           }
+          if (entry.why !== undefined && typeof entry.why !== 'string') {
+            errors.push(`${ctx}.reuse[${j}].why must be a string`);
+          }
         });
       }
     }

package/src/lib/tasks/test-nodes.js

@@ -572,7 +572,7 @@ export function morphConfigPath(projectPath = '.') {
  * only writer is `verify --record-baseline`, and it writes what a real, green
  * run measured. A hand-typed number describes what someone believed; the
  * divergence between belief and the suite is exactly the failure the rule was
- * written after ("mandate afirmando 2366 quando já eram 2375").
+ * written after.
  *
  * The write is a POINTED mutation: read → set one field per declared node →
  * atomic `tmp.{pid}` + rename via `atomicWriteJson` (the same door

package/src/lib/tasks/test-runner.js

@@ -734,7 +734,7 @@ export function isZeroTestRun(output, runner, exitCode) {
  * RISES is the normal life of a suite that grows with every task. A symmetric
  * rule would turn each new test into a red gate and would teach the agent to
  * delete tests in order to "fix" it — the lesson MORPH.md already paid for
- * ("mandate afirmando 2366 quando já eram 2375").
+ * (a typed number goes stale on the first task).
  *
  * @param {number|null} count - Executed count; null is UNKNOWN
  * @param {number|null} expectedCount - Recorded baseline; null is "none recorded"

package/src/lib/validators/contracts/contract-compliance-validator.js

@@ -1,56 +1,21 @@
-/**
- * Contract Compliance Validator
- *
- * Parses contracts.cs from feature outputs and verifies that the project code
- * actually implements all defined interfaces, methods, DTOs, and enums.
- *
- * MORPH-SPEC 3.0 - Phase A: Active Validation Pipeline
- */
-
 import { readFileSync, existsSync } from 'fs';
 import { join } from 'path';
 import { glob } from 'glob';
 import chalk from 'chalk';
 import { getAbsoluteOutputPath, resolveContractsOutputType } from '../../../core/paths/output-schema.js';
 
-/**
- * Validate that contracts.cs interfaces are implemented in project code
- *
- * @param {string} projectPath - Project root path
- * @param {string} featureName - Feature name
- * @param {Object} options - Options
- * @returns {Object} { status, errors, warnings, issues, coverage }
- */
 export async function validateContracts(projectPath, featureName, options = {}) {
-  // `'contracts'` is not an output type — `getAbsoluteOutputPath` threw
-  // "Unknown output type" on every call. The runner already resolves this the
-  // right way before deciding to schedule this validator
-  // (`resolveContractsOutputType()`); using the same resolver here is what
-  // keeps the two from disagreeing again.
   const contractsPath = getAbsoluteOutputPath(projectPath, featureName, resolveContractsOutputType());
 
-  if (!existsSync(contractsPath)) {
-    return {
-      status: 'ok',
-      errors: 0,
-      warnings: 0,
-      issues: [],
-      coverage: null,
-      message: 'No contracts.cs found — skipping'
-    };
-  }
+  const skipped = (message) => ({ status: 'ok', errors: 0, warnings: 0, issues: [], coverage: null, message });
+
+  if (!existsSync(contractsPath)) return skipped('No spec.md found — skipping');
 
   const contractsContent = readFileSync(contractsPath, 'utf-8');
   const contracts = parseContracts(contractsContent);
 
   if (contracts.interfaces.length === 0 && contracts.records.length === 0 && contracts.enums.length === 0) {
-    return {
-      status: 'ok',
-      errors: 0,
-      warnings: 1,
-      issues: [{ level: 'warning', message: 'contracts.cs exists but no interfaces/records/enums found' }],
-      coverage: null
-    };
+    return skipped('spec.md declares no interfaces/records/enums — skipping');
   }
 
   // Find all .cs files in the project (excluding .morph outputs, bin, obj)
@@ -168,9 +133,6 @@ export async function validateContracts(projectPath, featureName, options = {})
   };
 }
 
-/**
- * Parse contracts.cs content and extract interfaces, records, and enums
- */
 function parseContracts(content) {
   const interfaces = [];
   const records = [];