@polymorphism-tech/morph-spec 4.21.0 → 5.0.1

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

@@ -1,151 +1,133 @@
-/**
- * Output Schema — Single Source of Truth
- *
- * ALL output type definitions live here. Edit ONLY this file to add, rename,
- * or relocate output types. Derived constants and generated files (phase-utils.js)
- * are automatically updated by: node scripts/generate-refs.js
- */
-
-import { join } from 'path';
-
-// ============================================================================
-// Schema Definition
-// ============================================================================
-
-/**
- * Complete schema for all 12 output types produced by morph-spec phases.
- *
- * Fields:
- *   filename     - The file's basename (e.g. 'spec.md')
- *   phaseDir     - Subdirectory within .morph/features/{feature}/ (e.g. '2-design')
- *   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
- */
-export const OUTPUT_SCHEMA = {
-  proposal:      { filename: 'proposal.md',        phaseDir: '0-proposal',  phase: 'proposal',  protected: false },
-  schemaAnalysis:{ filename: 'schema-analysis.md', phaseDir: '2-design',    phase: 'design',    protected: true,  approvalGate: 'design' },
-  spec:          { filename: 'spec.md',             phaseDir: '2-design',    phase: 'design',    protected: true,  approvalGate: 'design' },
-  contracts:     { filename: 'contracts.cs',        phaseDir: '2-design',    phase: 'design',    protected: true,  approvalGate: 'design' },
-  contractsTs:   { filename: 'contracts.ts',        phaseDir: '2-design',    phase: 'design',    protected: true,  approvalGate: 'design' },
-  contractsVsa:  { filename: 'contracts-vsa.cs',    phaseDir: '2-design',    phase: 'design',    protected: true,  approvalGate: 'design' },
-  plan:          { filename: 'plan.md',             phaseDir: '3-plan',      phase: 'plan',      protected: true,  approvalGate: 'plan' },
-  tasks:         { filename: 'tasks.md',            phaseDir: '4-tasks',     phase: 'tasks',     protected: true,  approvalGate: 'tasks' },
-  uiDesignSystem:{ filename: 'design-system.md',   phaseDir: '1-ui',        phase: 'uiux',      protected: true,  approvalGate: 'uiux' },
-  uiMockups:     { filename: 'mockups.md',          phaseDir: '1-ui',        phase: 'uiux',      protected: true,  approvalGate: 'uiux' },
-  uiComponents:  { filename: 'components.md',       phaseDir: '1-ui',        phase: 'uiux',      protected: true,  approvalGate: 'uiux' },
-  uiFlows:       { filename: 'flows.md',            phaseDir: '1-ui',        phase: 'uiux',      protected: true,  approvalGate: 'uiux' },
-  decisions:     { filename: 'decisions.md',        phaseDir: '2-design',    phase: 'design',    protected: false },
-  recap:         { filename: 'recap.md',            phaseDir: '5-implement', phase: 'implement', protected: false },
-};
-
-// ============================================================================
-// Builder Functions (Windows-safe via path.join)
-// ============================================================================
-
-/**
- * Get the morph-relative path for a specific output type of a feature.
- * Returns forward-slash paths suitable for state.json storage.
- *
- * @param {string} featureName - The feature name
- * @param {string} outputType  - camelCase output type key from OUTPUT_SCHEMA
- * @returns {string} e.g. ".morph/features/my-feature/2-design/spec.md"
- */
-export function getOutputPath(featureName, outputType) {
-  const entry = OUTPUT_SCHEMA[outputType];
-  if (!entry) {
-    throw new Error(`Unknown output type: "${outputType}". Valid types: ${Object.keys(OUTPUT_SCHEMA).join(', ')}`);
-  }
-  // Use path.join for OS-safe construction, then normalise to forward slashes
-  return join('.morph', 'features', featureName, entry.phaseDir, entry.filename)
-    .replace(/\\/g, '/');
-}
-
-/**
- * Get the absolute filesystem path for a specific output type.
- *
- * @param {string} projectRoot - Absolute project root (e.g. process.cwd())
- * @param {string} featureName - The feature name
- * @param {string} outputType  - camelCase output type key from OUTPUT_SCHEMA
- * @returns {string} Absolute path using OS path separator
- */
-export function getAbsoluteOutputPath(projectRoot, featureName, outputType) {
-  const entry = OUTPUT_SCHEMA[outputType];
-  if (!entry) {
-    throw new Error(`Unknown output type: "${outputType}". Valid types: ${Object.keys(OUTPUT_SCHEMA).join(', ')}`);
-  }
-  return join(projectRoot, '.morph', 'features', featureName, entry.phaseDir, entry.filename);
-}
-
-/**
- * Get the feature base directory (morph-relative, forward slashes).
- *
- * @param {string} featureName
- * @returns {string} e.g. ".morph/features/my-feature"
- */
-export function getFeatureDir(featureName) {
-  return join('.morph', 'features', featureName).replace(/\\/g, '/');
-}
-
-/**
- * Get all output paths for a feature, ready for use in state.json `outputs` block.
- * Returns an object shaped like the state.json outputs for a single feature.
- *
- * @param {string} featureName
- * @returns {Object} e.g. { proposal: { created: false, path: '...' }, ... }
- */
-export function getAllOutputPaths(featureName) {
-  const outputs = {};
-  for (const [key] of Object.entries(OUTPUT_SCHEMA)) {
-    outputs[key] = {
-      created: false,
-      path: getOutputPath(featureName, key),
-    };
-  }
-  return outputs;
-}
-
-// ============================================================================
-// Derived Constants (for direct import without calling functions)
-// ============================================================================
-
-/**
- * Map filename → output type (camelCase)
- * e.g. { 'spec.md': 'spec', 'contracts.cs': 'contracts', ... }
- */
-export const FILENAME_TO_OUTPUT = Object.fromEntries(
-  Object.entries(OUTPUT_SCHEMA).map(([key, entry]) => [entry.filename, key])
-);
-
-/**
- * Map output type (camelCase) → phase that produces it
- * e.g. { spec: 'design', tasks: 'tasks', ... }
- */
-export const OUTPUT_PHASE_MAP = Object.fromEntries(
-  Object.entries(OUTPUT_SCHEMA).map(([key, entry]) => [key, entry.phase])
-);
-
-/**
- * Protected spec files and the approval gate that locks them.
- * Only includes files where protected === true.
- * e.g. { 'spec.md': 'design', 'tasks.md': 'tasks', ... }
- */
-export const PROTECTED_SPEC_FILES = Object.fromEntries(
-  Object.entries(OUTPUT_SCHEMA)
-    .filter(([, entry]) => entry.protected && entry.approvalGate)
-    .map(([, entry]) => [entry.filename, entry.approvalGate])
-);
-
-// ============================================================================
-// Stack-aware Helpers
-// ============================================================================
-
-/**
- * Resolve the correct contracts output type key for a given stack.
- * @param {string|null} stack
- * @returns {'contracts'|'contractsTs'}
- */
-export function resolveContractsOutputType(stack) {
-  const NEXTJS_STACKS = new Set(['nextjs', 'next', 'next.js']);
-  return NEXTJS_STACKS.has(stack?.toLowerCase?.()) ? 'contractsTs' : 'contracts';
-}
+/**
+ * Output Schema — Single Source of Truth (v5)
+ *
+ * ALL output type definitions live here. Edit ONLY this file to add, rename,
+ * or relocate output types.
+ */
+
+import { join } from 'path';
+
+// ============================================================================
+// Schema Definition
+// ============================================================================
+
+/**
+ * Schema for output types produced by morph-spec NLH phases.
+ *
+ * Fields:
+ *   filename     - The file's basename (e.g. 'spec.md')
+ *   phaseDir     - Subdirectory within .morph/features/{feature}/
+ *   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
+ */
+export const OUTPUT_SCHEMA = {
+  // 0-proposal/
+  proposal:       { filename: 'proposal.md',           phaseDir: '0-proposal',  phase: 'proposal',  protected: false },
+  stackScan:      { filename: 'stack-scan.md',         phaseDir: '0-proposal',  phase: 'proposal',  protected: false },
+  migrationPlan:  { filename: 'migration-plan.md',     phaseDir: '0-proposal',  phase: 'proposal',  protected: false },
+
+  // 1-ui/ (optional)
+  uiDesignSystem: { filename: 'design-system.md',      phaseDir: '1-ui',        phase: 'uiux',      protected: true,  approvalGate: 'uiux' },
+  uiMockups:      { filename: 'mockups.md',            phaseDir: '1-ui',        phase: 'uiux',      protected: true,  approvalGate: 'uiux' },
+  uiComponents:   { filename: 'components.md',         phaseDir: '1-ui',        phase: 'uiux',      protected: true,  approvalGate: 'uiux' },
+  uiFlows:        { filename: 'flows.md',              phaseDir: '1-ui',        phase: 'uiux',      protected: true,  approvalGate: 'uiux' },
+
+  // 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.md',              phaseDir: '2-plan',      phase: 'plan',      protected: true,  approvalGate: 'plan' },
+  decisions:      { filename: 'decisions.md',          phaseDir: '2-plan',      phase: 'plan',      protected: false },
+
+  // 3-implement/
+  recap:          { filename: 'recap.md',              phaseDir: '3-implement', phase: 'implement', protected: false },
+
+  // 4-review/
+  reviewReport:   { filename: 'review-report.md',      phaseDir: '4-review',    phase: 'review',    protected: false },
+};
+
+// ============================================================================
+// Builder Functions (Windows-safe via path.join)
+// ============================================================================
+
+/**
+ * Get the morph-relative path for a specific output type of a feature.
+ *
+ * @param {string} featureName
+ * @param {string} outputType  - camelCase output type key from OUTPUT_SCHEMA
+ * @returns {string} e.g. ".morph/features/my-feature/2-plan/spec.md"
+ */
+export function getOutputPath(featureName, outputType) {
+  const entry = OUTPUT_SCHEMA[outputType];
+  if (!entry) {
+    throw new Error(`Unknown output type: "${outputType}". Valid types: ${Object.keys(OUTPUT_SCHEMA).join(', ')}`);
+  }
+  return join('.morph', 'features', featureName, entry.phaseDir, entry.filename)
+    .replace(/\\/g, '/');
+}
+
+/**
+ * Get the absolute filesystem path for a specific output type.
+ */
+export function getAbsoluteOutputPath(projectRoot, featureName, outputType) {
+  const entry = OUTPUT_SCHEMA[outputType];
+  if (!entry) {
+    throw new Error(`Unknown output type: "${outputType}". Valid types: ${Object.keys(OUTPUT_SCHEMA).join(', ')}`);
+  }
+  return join(projectRoot, '.morph', 'features', featureName, entry.phaseDir, entry.filename);
+}
+
+/**
+ * Get the feature base directory (morph-relative, forward slashes).
+ */
+export function getFeatureDir(featureName) {
+  return join('.morph', 'features', featureName).replace(/\\/g, '/');
+}
+
+/**
+ * Get all output paths for a feature, ready for state.json `outputs` block.
+ */
+export function getAllOutputPaths(featureName) {
+  const outputs = {};
+  for (const [key] of Object.entries(OUTPUT_SCHEMA)) {
+    outputs[key] = {
+      created: false,
+      path: getOutputPath(featureName, key),
+    };
+  }
+  return outputs;
+}
+
+// ============================================================================
+// Derived Constants
+// ============================================================================
+
+export const FILENAME_TO_OUTPUT = Object.fromEntries(
+  Object.entries(OUTPUT_SCHEMA).map(([key, entry]) => [entry.filename, key])
+);
+
+export const OUTPUT_PHASE_MAP = Object.fromEntries(
+  Object.entries(OUTPUT_SCHEMA).map(([key, entry]) => [key, entry.phase])
+);
+
+/**
+ * Protected spec files and the approval gate that locks them.
+ */
+export const PROTECTED_SPEC_FILES = Object.fromEntries(
+  Object.entries(OUTPUT_SCHEMA)
+    .filter(([, entry]) => entry.protected && entry.approvalGate)
+    .map(([, entry]) => [entry.filename, entry.approvalGate])
+);
+
+// ============================================================================
+// Backwards-compat shim (will be removed in v5.1)
+// ============================================================================
+
+/**
+ * v4 had separate contracts.cs / contracts.ts / contracts-vsa.cs output types.
+ * In v5 contracts live inside spec.md (or in source files for VSA). This
+ * function keeps callers happy until they're updated.
+ */
+export function resolveContractsOutputType() {
+  return 'spec';
+}

package/src/core/state/phase-state-machine.js

@@ -10,13 +10,11 @@
  * Each phase can only transition to specific next phases
  */
 const VALID_TRANSITIONS = {
-  'proposal': ['uiux', 'design'], // Can skip UI/UX if no frontend
-  'uiux': ['design'],
-  'design': ['plan'],
-  'plan': ['tasks'],
-  'tasks': ['implement'],
-  'implement': ['sync', 'archived'], // Can skip sync
-  'sync': ['archived']
+  'proposal': ['uiux', 'plan'],
+  'uiux': ['plan'],
+  'plan': ['implement'],
+  'implement': ['review'],
+  'review': []
 };
 
 /**
@@ -25,18 +23,15 @@ const VALID_TRANSITIONS = {
 const PHASE_NAMES = {
   'proposal': 'Proposal (Phase 0)',
   'uiux': 'UI/UX Design (Phase 1)',
-  'design': 'Design (Phase 2)',
-  'plan': 'Plan (Phase 3)',
-  'tasks': 'Tasks (Phase 4)',
-  'implement': 'Implement (Phase 5)',
-  'sync': 'Sync (Phase 6)',
-  'archived': 'Archived'
+  'plan': 'Plan (Phase 2)',
+  'implement': 'Implement (Phase 3)',
+  'review': 'Quality Review (Phase 4)'
 };
 
 /**
  * Optional phases that can be skipped
  */
-const OPTIONAL_PHASES = ['uiux', 'sync'];
+const OPTIONAL_PHASES = ['uiux'];
 
 /**
  * Validate if a phase transition is allowed
@@ -116,16 +111,7 @@ export function validateTransition(fromPhase, toPhase) {
  * @returns {string[]} Ordered list of phases
  */
 export function getPhaseSequence() {
-  return [
-    'proposal',
-    'uiux',     // optional
-    'design',
-    'plan',
-    'tasks',
-    'implement',
-    'sync',     // optional
-    'archived'
-  ];
+  return ['proposal', 'uiux', 'plan', 'implement', 'review'];
 }
 
 /**

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

@@ -27,14 +27,13 @@ export function getStatePath() {
  * Returns the phase corresponding to the highest-numbered folder present.
  *
  * @param {string} featurePath - Absolute path to .morph/features/{feature}/
- * @returns {string} Phase name: 'implement' | 'tasks' | 'plan' | 'uiux' | 'design' | 'proposal'
+ * @returns {string} Phase name: 'review' | 'implement' | 'plan' | 'uiux' | 'proposal'
  */
 export function derivePhase(featurePath) {
   const phaseMap = [
-    ['5-implement', 'implement'],
-    ['4-tasks', 'tasks'],
-    ['3-plan', 'plan'],
-    ['2-design', 'design'],
+    ['4-review', 'review'],
+    ['3-implement', 'implement'],
+    ['2-plan', 'plan'],
     ['1-ui', 'uiux'],
     ['0-proposal', 'proposal'],
   ];
@@ -79,7 +78,7 @@ export function loadState(throwOnError = true) {
 
   if (!existsSync(statePath)) {
     if (throwOnError) {
-      throw new Error(`State file not found: ${statePath}\nRun 'morph-spec state init' first.`);
+      throw new Error(`State file not found: ${statePath}\nRun 'morph-spec init' to initialize MORPH in this project.`);
     }
     return null;
   }
@@ -297,6 +296,7 @@ async function ensureFeature(featureName, options = {}) {
         workflowDetection.matchedKeywords = detection.matchedKeywords;
         workflowDetection.estimatedComplexity = detection.estimatedComplexity;
         workflowDetection.reasoning = detection.reasoning;
+        workflowDetection.warnings = detection.warnings || [];
       } catch (err) {
         // If detection fails, fall back to auto
         console.warn('Workflow detection failed:', err.message);
@@ -313,8 +313,8 @@ async function ensureFeature(featureName, options = {}) {
       approvalGates: {
         proposal: { approved: false, timestamp: null, approvedBy: null },
         uiux: { approved: false, timestamp: null, approvedBy: null },
-        design: { approved: false, timestamp: null, approvedBy: null },
-        tasks: { approved: false, timestamp: null, approvedBy: null }
+        plan: { approved: false, timestamp: null, approvedBy: null },
+        review: { approved: false, timestamp: null, approvedBy: null }
       },
       tasks: {
         total: 0,
@@ -491,7 +491,7 @@ export function logDispatch(featureName, entry) {
 /**
  * Normalize output type from kebab-case to camelCase (BUG-002 fix - Enhanced)
  * Supports both kebab-case and camelCase input formats for all output types
- * @param {string} type - Output type (e.g., 'ui-design-system', 'schema-analysis', or 'uiDesignSystem')
+ * @param {string} type - Output type (e.g., 'ui-design-system', 'stack-scan', or 'uiDesignSystem')
  * @returns {string} Normalized type in camelCase
  */
 function normalizeOutputType(type) {
@@ -502,7 +502,7 @@ function normalizeOutputType(type) {
 
   // Convert kebab-case to camelCase automatically
   // Example: 'ui-design-system' → 'uiDesignSystem'
-  // Example: 'schema-analysis' → 'schemaAnalysis'
+  // Example: 'stack-scan' → 'stackScan'
   const camelCase = type.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
 
   return camelCase;
@@ -582,7 +582,7 @@ function findClosestMatch(inputType, validTypes) {
 /**
  * Mark output as created
  * @param {string} featureName - Feature name
- * @param {string} outputType - Output type (proposal, spec, contracts, etc.)
+ * @param {string} outputType - Output type (proposal, spec, mandate, etc.)
  */
 export async function markOutput(featureName, outputType) {
   await ensureFeature(featureName);
@@ -618,7 +618,7 @@ export async function markOutput(featureName, outputType) {
 
     errorMsg += `\n\nValid types:\n`;
     errorMsg += `  ${validCamelCaseTypes.join(', ')}\n`;
-    errorMsg += `\nNote: UI types also accept kebab-case (e.g., 'ui-design-system', 'schema-analysis')`;
+    errorMsg += `\nNote: kebab-case is also accepted (e.g., 'ui-design-system', 'stack-scan')`;
 
     throw new Error(errorMsg);
   }
@@ -769,7 +769,7 @@ export function getSummary() {
 /**
  * Set approval gate status
  * @param {string} featureName - Feature name
- * @param {string} gate - Gate name (proposal, uiux, design, tasks)
+ * @param {string} gate - Gate name (proposal, uiux, plan, review)
  * @param {boolean} approved - Approval status
  * @param {Object} metadata - Additional metadata (approvedBy, reason, etc.)
  */
@@ -781,8 +781,8 @@ export async function setApprovalGate(featureName, gate, approved, metadata = {}
     feature.approvalGates = {
       proposal: { approved: false, timestamp: null, approvedBy: null },
       uiux: { approved: false, timestamp: null, approvedBy: null },
-      design: { approved: false, timestamp: null, approvedBy: null },
-      tasks: { approved: false, timestamp: null, approvedBy: null }
+      plan: { approved: false, timestamp: null, approvedBy: null },
+      review: { approved: false, timestamp: null, approvedBy: null }
     };
   }
 
@@ -831,8 +831,8 @@ export function isPendingApproval(featureName) {
 
   // Check if current phase has an approval gate
   const phaseGateMap = {
-    'design': 'design',
-    'tasks': 'tasks',
+    'plan': 'plan',
+    'review': 'review',
     'uiux': 'uiux'
   };