@polymorphism-tech/morph-spec 7.3.0 → 7.4.0

package/src/commands/state/approve.js

@@ -1,213 +1,251 @@
-import { Command } from 'commander';
-import chalk from 'chalk';
-import { getFeature, setApprovalGate, getApprovalGate, getApprovalHistory } from '../../core/state/state-manager.js';
-
-/**
- * Unapprove action function - Revoke a previously approved gate
- */
-export async function unapproveCommand(featureName, gateName, options = {}) {
-  try {
-    if (!VALID_GATES.includes(gateName)) {
-      console.error(chalk.red(`\n❌ Invalid gate: ${gateName}`));
-      console.log(chalk.gray(`Valid gates: ${VALID_GATES.join(', ')}\n`));
-      process.exit(1);
-    }
-
-    const feature = getFeature(featureName);
-    if (!feature) {
-      console.error(chalk.red(`\n❌ Feature not found: ${featureName}\n`));
-      process.exit(1);
-    }
-
-    const currentStatus = getApprovalGate(featureName, gateName);
-    if (!currentStatus?.approved) {
-      console.log(chalk.yellow(`\n⚠️  Gate "${gateName}" is not currently approved — nothing to revoke\n`));
-      return;
-    }
-
-    await setApprovalGate(featureName, gateName, false, {
-      revokedBy: options.revoker || process.env.USER || process.env.USERNAME || 'user',
-      revokedAt: new Date().toISOString(),
-      reason: options.reason
-    });
-
-    console.log(chalk.yellow(`\n↩️  Gate "${gateName}" approval revoked for feature: ${featureName}`));
-    console.log(chalk.gray(`Workflow is now blocked at the ${gateName} gate\n`));
-
-  } catch (error) {
-    console.error(chalk.red(`\n❌ Error revoking gate: ${error.message}\n`));
-    process.exit(1);
-  }
-}
-
-/**
- * Approval Commands - Manage approval gates for MORPH workflow
- *
- * Commands:
- * - approve: Mark a gate as approved
- * - unapprove: Revoke a gate approval
- * - approval-status: Show approval status for all gates
- */
-
-const program = new Command();
-
-/**
- * Valid approval gate names
- */
-const VALID_GATES = ['proposal', 'uiux', 'plan', 'review'];
-
-/**
- * Approve action function - Mark a gate as approved
- */
-export async function approveCommand(featureName, gateName, options = {}) {
-  try {
-    // Validate gate name
-    if (!VALID_GATES.includes(gateName)) {
-      console.error(chalk.red(`\n❌ Invalid gate: ${gateName}`));
-      console.log(chalk.gray(`Valid gates: ${VALID_GATES.join(', ')}\n`));
-      process.exit(1);
-    }
-
-    // Get feature state
-    const feature = getFeature(featureName);
-    if (!feature) {
-      console.error(chalk.red(`\n❌ Feature not found: ${featureName}\n`));
-      process.exit(1);
-    }
-
-    // Check if already approved
-    const currentStatus = getApprovalGate(featureName, gateName);
-    if (currentStatus?.approved) {
-      console.log(chalk.yellow(`\n⚠️  Gate "${gateName}" is already approved`));
-      console.log(chalk.gray(`Approved at: ${currentStatus.timestamp}`));
-      console.log(chalk.gray(`Approved by: ${currentStatus.approvedBy || 'Unknown'}\n`));
-      return;
-    }
-
-    // Set approval
-    await setApprovalGate(featureName, gateName, true, {
-      approvedBy: options.approver || process.env.USER || process.env.USERNAME || 'user',
-      approvedAt: new Date().toISOString(),
-      notes: options.notes
-    });
-
-    console.log(chalk.green(`\n✅ Gate "${gateName}" approved for feature: ${featureName}`));
-    console.log(chalk.gray(`Workflow can now proceed past ${gateName} phase\n`));
-
-  } catch (error) {
-    console.error(chalk.red(`\n❌ Error approving gate: ${error.message}\n`));
-    process.exit(1);
-  }
-}
-
-/**
- * Approve command - Mark a gate as approved
- */
-program
-  .command('approve <feature> <gate>')
-  .description('Approve a phase gate to allow workflow progression')
-  .action(approveCommand);
-
-/**
- * Approval status action function - Show all gates and their status
- */
-export async function approvalStatusCommand(featureName, options = {}) {
-  try {
-    // Get feature state
-    const feature = getFeature(featureName);
-    if (!feature) {
-      console.error(chalk.red(`\n❌ Feature not found: ${featureName}\n`));
-      process.exit(1);
-    }
-
-    // JSON output
-    if (options.json) {
-      const status = {
-        feature: featureName,
-        phase: feature.phase,
-        status: feature.status,
-        gates: {}
-      };
-
-      for (const gateName of VALID_GATES) {
-        status.gates[gateName] = getApprovalGate(featureName, gateName) || { approved: false };
-      }
-
-      console.log(JSON.stringify(status, null, 2));
-      return;
-    }
-
-    console.log(chalk.bold(`\n📋 Approval Status for: ${featureName}`));
-    console.log('━'.repeat(60));
-
-    // Show current phase
-    console.log(chalk.cyan(`\nCurrent Phase: ${feature.phase || 'unknown'}`));
-    console.log(chalk.gray(`Feature Status: ${feature.status || 'unknown'}\n`));
-
-    // Show each gate
-    console.log(chalk.bold('Approval Gates:'));
-
-    for (const gateName of VALID_GATES) {
-      const gateStatus = getApprovalGate(featureName, gateName);
-
-      if (!gateStatus) {
-        console.log(`  ${chalk.gray('○')} ${gateName}: ${chalk.gray('Not yet evaluated')}`);
-        continue;
-      }
-
-      if (gateStatus.approved) {
-        console.log(`  ${chalk.green('✓')} ${gateName}: ${chalk.green('Approved')}`);
-        if (gateStatus.timestamp) {
-          console.log(chalk.gray(`      Approved at: ${gateStatus.timestamp}`));
-        }
-        if (gateStatus.approvedBy) {
-          console.log(chalk.gray(`      Approved by: ${gateStatus.approvedBy}`));
-        }
-      } else {
-        console.log(`  ${chalk.red('✗')} ${gateName}: ${chalk.red('Rejected / Not Approved')}`);
-        if (gateStatus.reason) {
-          console.log(chalk.gray(`      Reason: ${gateStatus.reason}`));
-        }
-        if (gateStatus.timestamp) {
-          console.log(chalk.gray(`      Rejected at: ${gateStatus.timestamp}`));
-        }
-      }
-    }
-
-    // Show approval history if available
-    const history = getApprovalHistory(featureName);
-    if (history && history.length > 0) {
-      console.log(chalk.bold('\nApproval History:'));
-      history.slice(-5).forEach(entry => {
-        const status = entry.approved ? chalk.green('✓ Approved') : chalk.red('✗ Rejected');
-        console.log(`  ${status} ${entry.gate} - ${entry.timestamp}`);
-      });
-    }
-
-    console.log('\n' + '━'.repeat(60) + '\n');
-
-  } catch (error) {
-    console.error(chalk.red(`\n❌ Error showing approval status: ${error.message}\n`));
-    process.exit(1);
-  }
-}
-
-/**
- * Approval status command - Show all gates and their status
- */
-program
-  .command('approval-status <feature>')
-  .alias('status')
-  .description('Show approval status for all gates')
-  .action(approvalStatusCommand);
-
-// Only parse if run directly (not imported as module)
-if (import.meta.url === `file://${process.argv[1]}`) {
-  if (process.argv.length > 2) {
-    program.parse(process.argv);
-  } else {
-    program.help();
-  }
-}
-
-export default program;
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { getFeature, setApprovalGate, getApprovalGate, getApprovalHistory } from '../../core/state/state-manager.js';
+
+/**
+ * Unapprove action function - Revoke a previously approved gate
+ */
+export async function unapproveCommand(featureName, gateName, options = {}) {
+  try {
+    if (!VALID_GATES.includes(gateName)) {
+      console.error(chalk.red(`\n❌ Invalid gate: ${gateName}`));
+      console.log(chalk.gray(`Valid gates: ${VALID_GATES.join(', ')}\n`));
+      process.exit(1);
+    }
+
+    const feature = getFeature(featureName);
+    if (!feature) {
+      console.error(chalk.red(`\n❌ Feature not found: ${featureName}\n`));
+      process.exit(1);
+    }
+
+    const currentStatus = getApprovalGate(featureName, gateName);
+    if (!currentStatus?.approved) {
+      console.log(chalk.yellow(`\n⚠️  Gate "${gateName}" is not currently approved — nothing to revoke\n`));
+      return;
+    }
+
+    // Same honesty rule as approveCommand: don't pretend a human revoked
+    // the gate when there's no interactive shell behind the invocation.
+    let revokedBy;
+    if (options.revoker) {
+      revokedBy = options.revoker;
+    } else if (options.mode === 'auto') {
+      revokedBy = 'auto';
+    } else if (process.stdin.isTTY) {
+      revokedBy = process.env.USER || process.env.USERNAME || 'user';
+    } else {
+      revokedBy = 'auto';
+    }
+
+    await setApprovalGate(featureName, gateName, false, {
+      revokedBy,
+      revokedAt: new Date().toISOString(),
+      reason: options.reason
+    });
+
+    console.log(chalk.yellow(`\n↩️  Gate "${gateName}" approval revoked for feature: ${featureName}`));
+    console.log(chalk.gray(`Workflow is now blocked at the ${gateName} gate\n`));
+
+  } catch (error) {
+    console.error(chalk.red(`\n❌ Error revoking gate: ${error.message}\n`));
+    process.exit(1);
+  }
+}
+
+/**
+ * Approval Commands - Manage approval gates for MORPH workflow
+ *
+ * Commands:
+ * - approve: Mark a gate as approved
+ * - unapprove: Revoke a gate approval
+ * - approval-status: Show approval status for all gates
+ */
+
+const program = new Command();
+
+/**
+ * Valid approval gate names
+ */
+const VALID_GATES = ['proposal', 'uiux', 'plan', 'review'];
+
+/**
+ * Approve action function - Mark a gate as approved
+ */
+export async function approveCommand(featureName, gateName, options = {}) {
+  try {
+    // Validate gate name
+    if (!VALID_GATES.includes(gateName)) {
+      console.error(chalk.red(`\n❌ Invalid gate: ${gateName}`));
+      console.log(chalk.gray(`Valid gates: ${VALID_GATES.join(', ')}\n`));
+      process.exit(1);
+    }
+
+    // Get feature state
+    const feature = getFeature(featureName);
+    if (!feature) {
+      console.error(chalk.red(`\n❌ Feature not found: ${featureName}\n`));
+      process.exit(1);
+    }
+
+    // Check if already approved
+    const currentStatus = getApprovalGate(featureName, gateName);
+    if (currentStatus?.approved) {
+      console.log(chalk.yellow(`\n⚠️  Gate "${gateName}" is already approved`));
+      console.log(chalk.gray(`Approved at: ${currentStatus.timestamp}`));
+      console.log(chalk.gray(`Approved by: ${currentStatus.approvedBy || 'Unknown'}\n`));
+      return;
+    }
+
+    // Set approval.
+    //
+    // approvedBy resolution (most explicit wins):
+    //   1. --approver flag (CLI caller signalled who approved)
+    //   2. --mode auto  → "auto" (intentionally non-human signature)
+    //   3. interactive shell (TTY on stdin) → $USER / $USERNAME (a real
+    //      human is at the terminal; their name is the honest answer)
+    //   4. non-interactive (no TTY) → "auto"
+    //
+    // The TTY check exists because morph-spec is increasingly invoked
+    // from headless contexts (claude -p subprocesses, CI, the
+    // morph-e2e-tester). Stamping the host's $USERNAME on a gate that
+    // no human actually approved is misleading — it lies to the audit
+    // trail. "auto" reads as what it is: a deterministic policy gate,
+    // not a human signing off.
+    let approvedBy;
+    if (options.approver) {
+      approvedBy = options.approver;
+    } else if (options.mode === 'auto') {
+      approvedBy = 'auto';
+    } else if (process.stdin.isTTY) {
+      approvedBy = process.env.USER || process.env.USERNAME || 'user';
+    } else {
+      approvedBy = 'auto';
+    }
+
+    await setApprovalGate(featureName, gateName, true, {
+      approvedBy,
+      approvedAt: new Date().toISOString(),
+      notes: options.notes
+    });
+
+    console.log(chalk.green(`\n✅ Gate "${gateName}" approved for feature: ${featureName}`));
+    console.log(chalk.gray(`Workflow can now proceed past ${gateName} phase\n`));
+
+  } catch (error) {
+    console.error(chalk.red(`\n❌ Error approving gate: ${error.message}\n`));
+    process.exit(1);
+  }
+}
+
+/**
+ * Approve command - Mark a gate as approved
+ */
+program
+  .command('approve <feature> <gate>')
+  .description('Approve a phase gate to allow workflow progression')
+  .action(approveCommand);
+
+/**
+ * Approval status action function - Show all gates and their status
+ */
+export async function approvalStatusCommand(featureName, options = {}) {
+  try {
+    // Get feature state
+    const feature = getFeature(featureName);
+    if (!feature) {
+      console.error(chalk.red(`\n❌ Feature not found: ${featureName}\n`));
+      process.exit(1);
+    }
+
+    // JSON output
+    if (options.json) {
+      const status = {
+        feature: featureName,
+        phase: feature.phase,
+        status: feature.status,
+        gates: {}
+      };
+
+      for (const gateName of VALID_GATES) {
+        status.gates[gateName] = getApprovalGate(featureName, gateName) || { approved: false };
+      }
+
+      console.log(JSON.stringify(status, null, 2));
+      return;
+    }
+
+    console.log(chalk.bold(`\n📋 Approval Status for: ${featureName}`));
+    console.log('━'.repeat(60));
+
+    // Show current phase
+    console.log(chalk.cyan(`\nCurrent Phase: ${feature.phase || 'unknown'}`));
+    console.log(chalk.gray(`Feature Status: ${feature.status || 'unknown'}\n`));
+
+    // Show each gate
+    console.log(chalk.bold('Approval Gates:'));
+
+    for (const gateName of VALID_GATES) {
+      const gateStatus = getApprovalGate(featureName, gateName);
+
+      if (!gateStatus) {
+        console.log(`  ${chalk.gray('○')} ${gateName}: ${chalk.gray('Not yet evaluated')}`);
+        continue;
+      }
+
+      if (gateStatus.approved) {
+        console.log(`  ${chalk.green('✓')} ${gateName}: ${chalk.green('Approved')}`);
+        if (gateStatus.timestamp) {
+          console.log(chalk.gray(`      Approved at: ${gateStatus.timestamp}`));
+        }
+        if (gateStatus.approvedBy) {
+          console.log(chalk.gray(`      Approved by: ${gateStatus.approvedBy}`));
+        }
+      } else {
+        console.log(`  ${chalk.red('✗')} ${gateName}: ${chalk.red('Rejected / Not Approved')}`);
+        if (gateStatus.reason) {
+          console.log(chalk.gray(`      Reason: ${gateStatus.reason}`));
+        }
+        if (gateStatus.timestamp) {
+          console.log(chalk.gray(`      Rejected at: ${gateStatus.timestamp}`));
+        }
+      }
+    }
+
+    // Show approval history if available
+    const history = getApprovalHistory(featureName);
+    if (history && history.length > 0) {
+      console.log(chalk.bold('\nApproval History:'));
+      history.slice(-5).forEach(entry => {
+        const status = entry.approved ? chalk.green('✓ Approved') : chalk.red('✗ Rejected');
+        console.log(`  ${status} ${entry.gate} - ${entry.timestamp}`);
+      });
+    }
+
+    console.log('\n' + '━'.repeat(60) + '\n');
+
+  } catch (error) {
+    console.error(chalk.red(`\n❌ Error showing approval status: ${error.message}\n`));
+    process.exit(1);
+  }
+}
+
+/**
+ * Approval status command - Show all gates and their status
+ */
+program
+  .command('approval-status <feature>')
+  .alias('status')
+  .description('Show approval status for all gates')
+  .action(approvalStatusCommand);
+
+// Only parse if run directly (not imported as module)
+if (import.meta.url === `file://${process.argv[1]}`) {
+  if (process.argv.length > 2) {
+    program.parse(process.argv);
+  } else {
+    program.help();
+  }
+}
+
+export default program;

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

@@ -19,34 +19,61 @@ import { getFeature } from '../../core/state/state-manager.js';
 import { validateTasksJson } from '../../lib/tasks/tasks-json-parser.js';
 
 /**
- * Expected sections per output file
+ * Expected sections per output file.
+ *
+ * Each section entry can be a string (single substring to match) or an array
+ * of acceptable substrings (any-of match). This lets pt-BR and English
+ * coexist — e.g. "Problem" matches both "Problem" and "Problema", but
+ * "Scope" needs to be paired with "Escopo" explicitly.
+ *
+ * The matcher (`validateMarkdownSections`) does case-insensitive substring
+ * matching against the whole file content.
  */
 const OUTPUT_SECTIONS = {
   'proposal.md': {
-    required: ['Overview', 'Problem', 'Solution', 'Scope'],
-    optional: ['Agents', 'Stack', 'Risks']
+    required: [
+      'Overview',
+      'Problem',                       // also matches Problema
+      ['Solution', 'Solução'],
+      ['Scope', 'Escopo']
+    ],
+    optional: ['Agents', 'Stack', ['Risks', 'Riscos']]
   },
   'spec.md': {
     required: [
-      'Overview', 'Functional Requirements', 'Non-Functional Requirements',
-      'Technical Architecture', 'Data Model'
+      'Overview',
+      ['Functional Requirements', 'Requisitos Funcionais'],
+      ['Non-Functional Requirements', 'Requisitos Não-Funcionais', 'Requisitos Nao-Funcionais'],
+      ['Technical Architecture', 'Arquitetura'],
+      ['Data Model', 'Modelo de Dados', 'Contratos']
     ],
     optional: [
-      'Infrastructure', 'Testing Strategy', 'Security',
-      'Performance', 'Edge Cases', 'Clarifications'
+      ['Infrastructure', 'Infraestrutura'],
+      ['Testing Strategy', 'Estratégia de Testes', 'Testes'],
+      ['Security', 'Segurança'],
+      'Performance',
+      ['Edge Cases', 'Casos Limite'],
+      ['Clarifications', 'Esclarecimentos']
     ]
   },
   'mandate.md': {
-    required: ['Stack', 'Standards', 'Done'],
-    optional: ['Patterns proibidos', 'Riscos']
+    required: ['Stack', 'Standards', ['Done', 'Pronto']],
+    optional: [
+      ['Patterns proibidos', 'Padrões proibidos', 'Forbidden Patterns'],
+      ['Riscos', 'Risks']
+    ]
   },
   'decisions.md': {
-    required: ['ADR', 'Status', 'Context', 'Decision'],
-    optional: ['Consequences', 'Alternatives', 'Costs']
+    required: ['ADR', 'Status', ['Context', 'Contexto'], ['Decision', 'Decisão']],
+    optional: [
+      ['Consequences', 'Consequências', 'Implicações'],
+      ['Alternatives', 'Alternativas'],
+      ['Costs', 'Custos']
+    ]
   },
   'review-report.md': {
-    required: ['Scores', 'Recommendation'],
-    optional: ['Blockers', 'Improvements']
+    required: [['Scores', 'Pontuação', 'Scoring'], ['Recommendation', 'Recomendação']],
+    optional: [['Blockers', 'Bloqueantes'], ['Improvements', 'Melhorias']]
   },
 };
 
@@ -143,24 +170,38 @@ function validateTasksJsonOutput(content, result) {
 }
 
 /**
- * Validate markdown sections
+ * Validate markdown sections.
+ *
+ * Each `section` entry can be:
+ *   - a string  → must appear as a substring (case-insensitive)
+ *   - an array  → any-of: at least one of the strings must appear
+ *
+ * The any-of form supports bilingual content (e.g. ['Scope', 'Escopo']).
  */
 function validateMarkdownSections(content, sections, result) {
   const contentLower = content.toLowerCase();
+  const matches = (entry) => {
+    const candidates = Array.isArray(entry) ? entry : [entry];
+    const hit = candidates.find(c => contentLower.includes(c.toLowerCase()));
+    return { hit, label: candidates[0] };
+  };
 
-  for (const section of sections.required) {
-    if (contentLower.includes(section.toLowerCase())) {
-      result.sections.found.push(section);
+  for (const entry of sections.required) {
+    const { hit, label } = matches(entry);
+    if (hit) {
+      result.sections.found.push(hit);
     } else {
-      result.sections.missing.push(section);
-      result.errors.push(`Missing required section: "${section}"`);
+      result.sections.missing.push(label);
+      const acceptable = Array.isArray(entry)
+        ? entry.map(s => `"${s}"`).join(' or ')
+        : `"${entry}"`;
+      result.errors.push(`Missing required section: ${acceptable}`);
     }
   }
 
-  for (const section of (sections.optional || [])) {
-    if (contentLower.includes(section.toLowerCase())) {
-      result.sections.optional.push(section);
-    }
+  for (const entry of (sections.optional || [])) {
+    const { hit } = matches(entry);
+    if (hit) result.sections.optional.push(hit);
   }
 }
 

package/src/core/state/state-manager.js

@@ -22,22 +22,32 @@ export function getStatePath() {
   return join(process.cwd(), STATE_FILE_NAME);
 }
 /**
- * Derive current phase from filesystem — checks for phase folders in descending order.
- * Returns the phase corresponding to the highest-numbered folder present.
+ * Derive current phase from filesystem.
+ *
+ * Walks the phase map in descending order and returns the first phase whose
+ * CANONICAL ARTIFACT exists. An empty folder is not enough — `mkdir 2-plan/`
+ * does not count as "in plan phase" until `spec.md` (the first canonical
+ * plan-phase output) lands. If no canonical artifact is found anywhere,
+ * returns `'proposal'` (the starting phase).
+ *
+ * This avoids the chicken-and-egg problem where the agent pre-creates all
+ * phase folders, the derived phase jumps to the highest one, and
+ * `enforce-phase-writes` then blocks the agent from writing back to the
+ * prior phase folder.
  *
  * @param {string} featurePath - Absolute path to .morph/features/{feature}/
  * @returns {string} Phase name: 'review' | 'implement' | 'plan' | 'uiux' | 'proposal'
  */
 export function derivePhase(featurePath) {
   const phaseMap = [
-    ['4-review', 'review'],
-    ['3-implement', 'implement'],
-    ['2-plan', 'plan'],
-    ['1-design', 'uiux'],
-    ['0-proposal', 'proposal'],
+    ['4-review',    'review',    'review-report.md'],
+    ['3-implement', 'implement', 'recap.md'],
+    ['2-plan',      'plan',      'spec.md'],
+    ['1-design',    'uiux',      'design-system.md'],
+    ['0-proposal',  'proposal',  'proposal.md'],
   ];
-  for (const [folder, phase] of phaseMap) {
-    if (existsSync(join(featurePath, folder))) return phase;
+  for (const [folder, phase, canonical] of phaseMap) {
+    if (existsSync(join(featurePath, folder, canonical))) return phase;
   }
   return 'proposal';
 }

package/src/lib/risk-detector.js

@@ -8,12 +8,12 @@
  * Signals checked (in order):
  *   - designSystemDivergence: boolean — conflicting design sources detected
  *   - standardsViolations: string[]   — violations of mandate.md proibições
- *   - evalScore: number               — morph-eval score (pause if < 8)
+ *   - evalScore: number               — morph-eval score (pause if < 9)
  *   - taskCount: number               — total tasks (pause if > 20)
  */
 
 const SCOPE_TASK_THRESHOLD = 20;
-const MIN_EVAL_SCORE = 8;
+const MIN_EVAL_SCORE = 9;
 
 /**
  * @param {object} config - .morph/config/config.json contents (uses `trust`)