@polymorphism-tech/morph-spec 7.1.1 → 7.3.0

package/src/commands/validation/validate-feature.js

@@ -1,287 +1,315 @@
-/**
- * MORPH-SPEC Feature Validation Command
- *
- * Content-aware validation of feature outputs at each phase.
- * Checks section presence, schema consistency, and contract correctness.
- *
- * Usage:
- *   morph-spec validate <feature-name> [--phase <phase>] [--json] [--verbose]
- *
- * Example:
- *   morph-spec validate user-portal --phase design
- *   morph-spec validate user-portal --json
- */
-
-import fs from 'fs';
-import path from 'path';
-import chalk from 'chalk';
-import { getFeature } from '../../core/state/state-manager.js';
-
-/**
- * Expected sections per output file
- */
-const OUTPUT_SECTIONS = {
-  'proposal.md': {
-    required: ['Overview', 'Problem', 'Solution', 'Scope'],
-    optional: ['Agents', 'Stack', 'Risks']
-  },
-  'spec.md': {
-    required: [
-      'Overview', 'Functional Requirements', 'Non-Functional Requirements',
-      'Technical Architecture', 'Data Model'
-    ],
-    optional: [
-      'Infrastructure', 'Testing Strategy', 'Security',
-      'Performance', 'Edge Cases', 'Clarifications'
-    ]
-  },
-  'mandate.md': {
-    required: ['Stack', 'Standards', 'Done'],
-    optional: ['Patterns proibidos', 'Riscos']
-  },
-  'decisions.md': {
-    required: ['ADR', 'Status', 'Context', 'Decision'],
-    optional: ['Consequences', 'Alternatives', 'Costs']
-  },
-  'tasks.md': {
-    required: ['T001', 'category', 'dependencies'],
-    optional: ['CHECKPOINT', 'estimatedMinutes']
-  },
-  'review-report.md': {
-    required: ['Scores', 'Recommendation'],
-    optional: ['Blockers', 'Improvements']
-  },
-};
-
-/**
- * Phase-to-output mapping (v5 NLH)
- */
-const PHASE_OUTPUTS = {
-  proposal: ['proposal.md'],
-  uiux: ['design-system.md', 'mockups.md', 'components.md', 'flows.md'],
-  plan: ['spec.md', 'mandate.md', 'tasks.md'],
-  implement: ['recap.md'],
-  review: ['review-report.md'],
-};
-
-/**
- * Phase-to-folder mapping (v5 filesystem convention)
- */
-const PHASE_FOLDERS = {
-  proposal: '0-proposal',
-  uiux: '1-design',
-  plan: '2-plan',
-  implement: '3-implement',
-  review: '4-review',
-};
-
-/**
- * Validate a single output file
- */
-function validateOutput(featurePath, outputFile) {
-  const filePath = path.join(featurePath, outputFile);
-  const result = {
-    file: outputFile,
-    exists: false,
-    sections: { found: [], missing: [], optional: [] },
-    warnings: [],
-    errors: [],
-    lineCount: 0
-  };
-
-  if (!fs.existsSync(filePath)) {
-    result.errors.push(`File not found: ${outputFile}`);
-    return result;
-  }
-
-  result.exists = true;
-  const content = fs.readFileSync(filePath, 'utf8');
-  result.lineCount = content.split('\n').length;
-
-  // Skip section checks for files without defined sections
-  const sections = OUTPUT_SECTIONS[outputFile];
-  if (!sections) {
-    return result;
-  }
-
-  // v5: only markdown outputs — contracts moved into spec.md
-  validateMarkdownSections(content, sections, result);
-
-  // Size warnings
-  if (result.lineCount < 10) {
-    result.warnings.push(`File is very short (${result.lineCount} lines) — may be incomplete`);
-  }
-
-  return result;
-}
-
-/**
- * Validate markdown sections
- */
-function validateMarkdownSections(content, sections, result) {
-  const contentLower = content.toLowerCase();
-
-  for (const section of sections.required) {
-    if (contentLower.includes(section.toLowerCase())) {
-      result.sections.found.push(section);
-    } else {
-      result.sections.missing.push(section);
-      result.errors.push(`Missing required section: "${section}"`);
-    }
-  }
-
-  for (const section of (sections.optional || [])) {
-    if (contentLower.includes(section.toLowerCase())) {
-      result.sections.optional.push(section);
-    }
-  }
-}
-
-/**
- * Main validate command
- */
-export async function validateFeatureCommand(featureName, options = {}) {
-  if (!featureName) {
-    console.error(chalk.red('Error: Feature name required'));
-    console.error(chalk.gray('Usage: morph-spec validate <feature-name> [--phase <phase>]'));
-    process.exit(1);
-  }
-
-  const featurePath = path.join(process.cwd(), '.morph/features', featureName);
-
-  if (!fs.existsSync(featurePath)) {
-    console.error(chalk.red(`Error: Feature directory not found: ${featurePath}`));
-    process.exit(1);
-  }
-
-  // Determine which outputs to validate
-  const phase = options.phase || null;
-  let outputFiles;
-
-  if (phase) {
-    outputFiles = PHASE_OUTPUTS[phase];
-    if (!outputFiles) {
-      console.error(chalk.red(`Unknown phase: ${phase}`));
-      console.error(chalk.gray(`Valid phases: ${Object.keys(PHASE_OUTPUTS).join(', ')}`));
-      process.exit(1);
-    }
-  } else {
-    // Validate all existing outputs across all phase folders
-    outputFiles = [];
-    const entries = fs.readdirSync(featurePath, { withFileTypes: true });
-    for (const entry of entries) {
-      if (entry.isDirectory()) {
-        const subDir = path.join(featurePath, entry.name);
-        const files = fs.readdirSync(subDir).filter(f => f.endsWith('.md') || f.endsWith('.cs'));
-        outputFiles.push(...files.map(f => ({ file: f, dir: subDir })));
-      } else if (entry.name.endsWith('.md') || entry.name.endsWith('.cs')) {
-        outputFiles.push({ file: entry.name, dir: featurePath });
-      }
-    }
-  }
-
-  // Resolve phase folder for path lookup
-  const phaseFolder = phase ? PHASE_FOLDERS[phase] : null;
-  const searchPath = phaseFolder ? path.join(featurePath, phaseFolder) : featurePath;
-
-  // Run validation
-  const results = phase
-    ? outputFiles.map(file => validateOutput(searchPath, file))
-    : outputFiles.map(({ file, dir }) => validateOutput(dir, file));
-  const schemaWarnings = []; // v5: cross-validation removed (contracts in spec.md)
-
-  // Aggregate results
-  const totalErrors = results.reduce((sum, r) => sum + r.errors.length, 0);
-  const totalWarnings = results.reduce((sum, r) => sum + r.warnings.length, 0) + schemaWarnings.length;
-  const totalFound = results.reduce((sum, r) => sum + r.sections.found.length, 0);
-
-  // JSON output mode
-  if (options.json) {
-    const output = {
-      feature: featureName,
-      phase: phase || 'all',
-      valid: totalErrors === 0,
-      summary: {
-        files: results.length,
-        errors: totalErrors,
-        warnings: totalWarnings,
-        sectionsFound: totalFound
-      },
-      results: results.map(r => ({
-        file: r.file,
-        exists: r.exists,
-        lineCount: r.lineCount,
-        errors: r.errors,
-        warnings: r.warnings,
-        sectionsFound: r.sections.found,
-        sectionsMissing: r.sections.missing
-      })),
-      schemaWarnings
-    };
-    console.log(JSON.stringify(output, null, 2));
-    return;
-  }
-
-  // Visual output
-  console.log(chalk.cyan('\n┌────────────────────────────────────────────────────────────┐'));
-  console.log(chalk.cyan('│                MORPH-SPEC FEATURE VALIDATOR                │'));
-  console.log(chalk.cyan('└────────────────────────────────────────────────────────────┘\n'));
-
-  console.log(chalk.white.bold(`Feature: ${featureName}`));
-  if (phase) console.log(chalk.gray(`Phase: ${phase}`));
-  console.log('');
-
-  // File-by-file results
-  for (const result of results) {
-    const symbol = result.exists
-      ? (result.errors.length === 0 ? '✅' : '❌')
-      : '⬜';
-    const name = result.exists
-      ? (result.errors.length === 0 ? chalk.green(result.file) : chalk.red(result.file))
-      : chalk.gray(result.file);
-
-    console.log(`${symbol} ${name}${result.exists ? chalk.gray(` (${result.lineCount} lines)`) : ''}`);
-
-    // Sections found
-    if (result.sections.found.length > 0 && (options.verbose || result.errors.length > 0)) {
-      result.sections.found.forEach(s => {
-        console.log(chalk.green(`   ✓ ${s}`));
-      });
-    }
-
-    // Errors
-    result.errors.forEach(err => {
-      console.log(chalk.red(`   ✗ ${err}`));
-    });
-
-    // Warnings
-    result.warnings.forEach(warn => {
-      console.log(chalk.yellow(`   ⚠ ${warn}`));
-    });
-  }
-
-  // Schema cross-validation
-  if (schemaWarnings.length > 0) {
-    console.log(chalk.yellow('\nSchema Cross-Validation:'));
-    schemaWarnings.forEach(w => {
-      console.log(chalk.yellow(`  ⚠ ${w}`));
-    });
-  }
-
-  // Summary
-  console.log('');
-  console.log(chalk.gray('─'.repeat(60)));
-
-  if (totalErrors === 0) {
-    console.log(chalk.green(`\n✓ VALIDATION PASSED — ${results.filter(r => r.exists).length} files validated`));
-    if (totalWarnings > 0) {
-      console.log(chalk.yellow(`  ${totalWarnings} warning(s) — review recommended`));
-    }
-  } else {
-    console.log(chalk.red(`\n✗ VALIDATION FAILED — ${totalErrors} error(s), ${totalWarnings} warning(s)`));
-    console.log(chalk.yellow('  Fix errors before advancing to the next phase'));
-  }
-  console.log('');
-}
-
-export default validateFeatureCommand;
+/**
+ * MORPH-SPEC Feature Validation Command
+ *
+ * Content-aware validation of feature outputs at each phase.
+ * Checks section presence, schema consistency, and contract correctness.
+ *
+ * Usage:
+ *   morph-spec validate <feature-name> [--phase <phase>] [--json] [--verbose]
+ *
+ * Example:
+ *   morph-spec validate user-portal --phase design
+ *   morph-spec validate user-portal --json
+ */
+
+import fs from 'fs';
+import path from 'path';
+import chalk from 'chalk';
+import { getFeature } from '../../core/state/state-manager.js';
+import { validateTasksJson } from '../../lib/tasks/tasks-json-parser.js';
+
+/**
+ * Expected sections per output file
+ */
+const OUTPUT_SECTIONS = {
+  'proposal.md': {
+    required: ['Overview', 'Problem', 'Solution', 'Scope'],
+    optional: ['Agents', 'Stack', 'Risks']
+  },
+  'spec.md': {
+    required: [
+      'Overview', 'Functional Requirements', 'Non-Functional Requirements',
+      'Technical Architecture', 'Data Model'
+    ],
+    optional: [
+      'Infrastructure', 'Testing Strategy', 'Security',
+      'Performance', 'Edge Cases', 'Clarifications'
+    ]
+  },
+  'mandate.md': {
+    required: ['Stack', 'Standards', 'Done'],
+    optional: ['Patterns proibidos', 'Riscos']
+  },
+  'decisions.md': {
+    required: ['ADR', 'Status', 'Context', 'Decision'],
+    optional: ['Consequences', 'Alternatives', 'Costs']
+  },
+  'review-report.md': {
+    required: ['Scores', 'Recommendation'],
+    optional: ['Blockers', 'Improvements']
+  },
+};
+
+/**
+ * Phase-to-output mapping (v5 NLH)
+ */
+const PHASE_OUTPUTS = {
+  proposal: ['proposal.md'],
+  uiux: ['design-system.md', 'mockups.md', 'components.md', 'flows.md'],
+  plan: ['spec.md', 'mandate.md', 'tasks.json'],
+  implement: ['recap.md'],
+  review: ['review-report.md'],
+};
+
+/**
+ * Phase-to-folder mapping (v5 filesystem convention)
+ */
+const PHASE_FOLDERS = {
+  proposal: '0-proposal',
+  uiux: '1-design',
+  plan: '2-plan',
+  implement: '3-implement',
+  review: '4-review',
+};
+
+/**
+ * Validate a single output file
+ */
+function validateOutput(featurePath, outputFile) {
+  const filePath = path.join(featurePath, outputFile);
+  const result = {
+    file: outputFile,
+    exists: false,
+    sections: { found: [], missing: [], optional: [] },
+    warnings: [],
+    errors: [],
+    lineCount: 0
+  };
+
+  if (!fs.existsSync(filePath)) {
+    result.errors.push(`File not found: ${outputFile}`);
+    return result;
+  }
+
+  result.exists = true;
+  const content = fs.readFileSync(filePath, 'utf8');
+  result.lineCount = content.split('\n').length;
+
+  // tasks.json: structural validation against the schema, not markdown sections.
+  if (outputFile === 'tasks.json') {
+    validateTasksJsonOutput(content, result);
+    return result;
+  }
+
+  // Skip section checks for files without defined sections
+  const sections = OUTPUT_SECTIONS[outputFile];
+  if (!sections) {
+    return result;
+  }
+
+  // v5: only markdown outputs — contracts moved into spec.md
+  validateMarkdownSections(content, sections, result);
+
+  // Size warnings
+  if (result.lineCount < 10) {
+    result.warnings.push(`File is very short (${result.lineCount} lines) — may be incomplete`);
+  }
+
+  return result;
+}
+
+/**
+ * Validate tasks.json structurally: parseable JSON + conforms to the schema +
+ * has at least one task.
+ */
+function validateTasksJsonOutput(content, result) {
+  let data;
+  try {
+    data = JSON.parse(content);
+  } catch (err) {
+    result.errors.push(`tasks.json is not valid JSON: ${err.message}`);
+    return;
+  }
+  const { valid, errors } = validateTasksJson(data);
+  if (!valid) {
+    for (const e of errors) result.errors.push(e);
+    return;
+  }
+  if (data.tasks.length === 0) {
+    result.errors.push('tasks.json has no task entries');
+    return;
+  }
+  result.sections.found.push(`${data.tasks.length} task(s)`);
+}
+
+/**
+ * Validate markdown sections
+ */
+function validateMarkdownSections(content, sections, result) {
+  const contentLower = content.toLowerCase();
+
+  for (const section of sections.required) {
+    if (contentLower.includes(section.toLowerCase())) {
+      result.sections.found.push(section);
+    } else {
+      result.sections.missing.push(section);
+      result.errors.push(`Missing required section: "${section}"`);
+    }
+  }
+
+  for (const section of (sections.optional || [])) {
+    if (contentLower.includes(section.toLowerCase())) {
+      result.sections.optional.push(section);
+    }
+  }
+}
+
+/**
+ * Main validate command
+ */
+export async function validateFeatureCommand(featureName, options = {}) {
+  if (!featureName) {
+    console.error(chalk.red('Error: Feature name required'));
+    console.error(chalk.gray('Usage: morph-spec validate <feature-name> [--phase <phase>]'));
+    process.exit(1);
+  }
+
+  const featurePath = path.join(process.cwd(), '.morph/features', featureName);
+
+  if (!fs.existsSync(featurePath)) {
+    console.error(chalk.red(`Error: Feature directory not found: ${featurePath}`));
+    process.exit(1);
+  }
+
+  // Determine which outputs to validate
+  const phase = options.phase || null;
+  let outputFiles;
+
+  if (phase) {
+    outputFiles = PHASE_OUTPUTS[phase];
+    if (!outputFiles) {
+      console.error(chalk.red(`Unknown phase: ${phase}`));
+      console.error(chalk.gray(`Valid phases: ${Object.keys(PHASE_OUTPUTS).join(', ')}`));
+      process.exit(1);
+    }
+  } else {
+    // Validate all existing outputs across all phase folders
+    outputFiles = [];
+    const entries = fs.readdirSync(featurePath, { withFileTypes: true });
+    const isOutput = name => name.endsWith('.md') || name.endsWith('.cs') || name === 'tasks.json';
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        const subDir = path.join(featurePath, entry.name);
+        const files = fs.readdirSync(subDir).filter(isOutput);
+        outputFiles.push(...files.map(f => ({ file: f, dir: subDir })));
+      } else if (isOutput(entry.name)) {
+        outputFiles.push({ file: entry.name, dir: featurePath });
+      }
+    }
+  }
+
+  // Resolve phase folder for path lookup
+  const phaseFolder = phase ? PHASE_FOLDERS[phase] : null;
+  const searchPath = phaseFolder ? path.join(featurePath, phaseFolder) : featurePath;
+
+  // Run validation
+  const results = phase
+    ? outputFiles.map(file => validateOutput(searchPath, file))
+    : outputFiles.map(({ file, dir }) => validateOutput(dir, file));
+  const schemaWarnings = []; // v5: cross-validation removed (contracts in spec.md)
+
+  // Aggregate results
+  const totalErrors = results.reduce((sum, r) => sum + r.errors.length, 0);
+  const totalWarnings = results.reduce((sum, r) => sum + r.warnings.length, 0) + schemaWarnings.length;
+  const totalFound = results.reduce((sum, r) => sum + r.sections.found.length, 0);
+
+  // JSON output mode
+  if (options.json) {
+    const output = {
+      feature: featureName,
+      phase: phase || 'all',
+      valid: totalErrors === 0,
+      summary: {
+        files: results.length,
+        errors: totalErrors,
+        warnings: totalWarnings,
+        sectionsFound: totalFound
+      },
+      results: results.map(r => ({
+        file: r.file,
+        exists: r.exists,
+        lineCount: r.lineCount,
+        errors: r.errors,
+        warnings: r.warnings,
+        sectionsFound: r.sections.found,
+        sectionsMissing: r.sections.missing
+      })),
+      schemaWarnings
+    };
+    console.log(JSON.stringify(output, null, 2));
+    return;
+  }
+
+  // Visual output
+  console.log(chalk.cyan('\n┌────────────────────────────────────────────────────────────┐'));
+  console.log(chalk.cyan('│                MORPH-SPEC FEATURE VALIDATOR                │'));
+  console.log(chalk.cyan('└────────────────────────────────────────────────────────────┘\n'));
+
+  console.log(chalk.white.bold(`Feature: ${featureName}`));
+  if (phase) console.log(chalk.gray(`Phase: ${phase}`));
+  console.log('');
+
+  // File-by-file results
+  for (const result of results) {
+    const symbol = result.exists
+      ? (result.errors.length === 0 ? '✅' : '❌')
+      : '⬜';
+    const name = result.exists
+      ? (result.errors.length === 0 ? chalk.green(result.file) : chalk.red(result.file))
+      : chalk.gray(result.file);
+
+    console.log(`${symbol} ${name}${result.exists ? chalk.gray(` (${result.lineCount} lines)`) : ''}`);
+
+    // Sections found
+    if (result.sections.found.length > 0 && (options.verbose || result.errors.length > 0)) {
+      result.sections.found.forEach(s => {
+        console.log(chalk.green(`   ✓ ${s}`));
+      });
+    }
+
+    // Errors
+    result.errors.forEach(err => {
+      console.log(chalk.red(`   ✗ ${err}`));
+    });
+
+    // Warnings
+    result.warnings.forEach(warn => {
+      console.log(chalk.yellow(`   ⚠ ${warn}`));
+    });
+  }
+
+  // Schema cross-validation
+  if (schemaWarnings.length > 0) {
+    console.log(chalk.yellow('\nSchema Cross-Validation:'));
+    schemaWarnings.forEach(w => {
+      console.log(chalk.yellow(`  ⚠ ${w}`));
+    });
+  }
+
+  // Summary
+  console.log('');
+  console.log(chalk.gray('─'.repeat(60)));
+
+  if (totalErrors === 0) {
+    console.log(chalk.green(`\n✓ VALIDATION PASSED — ${results.filter(r => r.exists).length} files validated`));
+    if (totalWarnings > 0) {
+      console.log(chalk.yellow(`  ${totalWarnings} warning(s) — review recommended`));
+    }
+  } else {
+    console.log(chalk.red(`\n✗ VALIDATION FAILED — ${totalErrors} error(s), ${totalWarnings} warning(s)`));
+    console.log(chalk.yellow('  Fix errors before advancing to the next phase'));
+  }
+  console.log('');
+}
+
+export default validateFeatureCommand;

package/src/core/paths/output-schema.js

@@ -20,6 +20,11 @@ import { join } from 'path';
  *   phase        - The morph-spec phase that produces this output
  *   protected    - Whether the file requires an approval gate before editing
  *   approvalGate - (optional) Which gate protects this file
+ *   mutableFields- (optional) For protected JSON files: top-level array-item
+ *                  field names that MAY still change after the gate is approved.
+ *                  Lets the implement phase update task progress without
+ *                  unfreezing the plan contract. When present, the protect
+ *                  hook does a semantic diff instead of a blanket block.
  */
 export const OUTPUT_SCHEMA = {
   // 0-proposal/
@@ -36,7 +41,7 @@ export const OUTPUT_SCHEMA = {
   // 2-plan/
   spec:           { filename: 'spec.md',               phaseDir: '2-plan',      phase: 'plan',      protected: true,  approvalGate: 'plan' },
   mandate:        { filename: 'mandate.md',            phaseDir: '2-plan',      phase: 'plan',      protected: true,  approvalGate: 'plan' },
-  tasks:          { filename: 'tasks.json',            phaseDir: '2-plan',      phase: 'plan',      protected: true,  approvalGate: 'plan' },
+  tasks:          { filename: 'tasks.json',            phaseDir: '2-plan',      phase: 'plan',      protected: true,  approvalGate: 'plan', mutableFields: ['status', 'outputs', 'notes'] },
   decisions:      { filename: 'decisions.md',          phaseDir: '2-plan',      phase: 'plan',      protected: false },
 
   // 3-implement/
@@ -119,6 +124,18 @@ export const PROTECTED_SPEC_FILES = Object.fromEntries(
     .map(([, entry]) => [entry.filename, entry.approvalGate])
 );
 
+/**
+ * For protected files that carry mutable progress fields: filename → the
+ * top-level array-item fields that may change after the gate is approved.
+ * The protect-spec-files hook uses this to allow progress updates (e.g.
+ * task status) while still freezing the plan contract.
+ */
+export const MUTABLE_SPEC_FIELDS = Object.fromEntries(
+  Object.entries(OUTPUT_SCHEMA)
+    .filter(([, entry]) => entry.protected && entry.approvalGate && entry.mutableFields)
+    .map(([, entry]) => [entry.filename, entry.mutableFields])
+);
+
 // ============================================================================
 // Backwards-compat shim (will be removed in v5.1)
 // ============================================================================