@polymorphism-tech/morph-spec 4.12.0 → 4.13.0

package/src/commands/project/doctor.js

@@ -94,40 +94,20 @@ const REQUIRED_COMMAND_FILES = [
   'src/lib/scope/impact-analyzer.js'
 ];
 
-// framework standards
+// framework standards (stack-relevant only)
 const FRAMEWORK_STANDARDS = [
-  'framework/standards/observability/monitoring.md',
-  'framework/standards/observability/logging.md',
-  'framework/standards/observability/tracing.md',
-  'framework/standards/observability/metrics.md',
-  'framework/standards/integration/event-driven/service-bus.md',
-  'framework/standards/integration/event-driven/cqrs.md',
-  'framework/standards/integration/event-driven/event-sourcing.md',
+  'framework/standards/architecture/vertical-slice/vertical-slice.md',
   'framework/standards/data/nosql/cosmos-db.md',
   'framework/standards/data/nosql/cache/redis.md',
-  'framework/standards/data/nosql/blob-storage.md',
-  'framework/standards/integration/api/rest-design.md',
-  'framework/standards/integration/api/graphql.md',
-  'framework/standards/integration/api/grpc.md',
-  'framework/standards/architecture/ddd/aggregates.md',
-  'framework/standards/architecture/ddd/entities.md',
-  'framework/standards/architecture/ddd/value-objects.md',
-  'framework/standards/architecture/vertical-slice/vertical-slice.md',
-  'framework/standards/data/vector-search/azure-ai-search.md',
   'framework/standards/data/vector-search/rag-chunking.md',
-  'framework/standards/context/priming.md',
-  'framework/standards/context/bundles.md',
-  'framework/standards/context/analytics.md',
+  'framework/standards/integration/mcp/mcp-tools.md',
   'framework/standards/workflows/thread-management.md',
   'framework/standards/workflows/parallel-execution.md'
 ];
 
 // required agents expected in agents.json
 const REQUIRED_AGENTS = [
-  'vector-search-expert',
-  'thread-orchestrator',
-  'context-optimizer',
-  'observability-expert'
+  'vector-search-expert'
 ];
 
 /**
@@ -585,7 +565,7 @@ export async function doctorCommand(options = {}) {
       }
 
       // Check 2: required tier-2 agents present
-      const requiredTier2 = ['standards-architect', 'dotnet-senior', 'infra-architect', 'domain-architect'];
+      const requiredTier2 = ['standards-architect', 'dotnet-senior', 'infra-architect'];
       const missingTier2 = requiredTier2.filter(id => !agentsData.agents[id]);
       if (missingTier2.length > 0) {
         checks.push({
@@ -671,15 +651,13 @@ export async function doctorCommand(options = {}) {
   const standardsPath = join(morphPath, 'framework', 'standards');
   const frameworkStdsRoot = join(import.meta.dirname, '..', '..', '..', 'framework', 'standards');
   if (await pathExists(standardsPath)) {
-    // Check for core standards in hierarchy (copied by init) or flat layout
-    const codingStd = await pathExists(join(standardsPath, 'core', 'coding.md')) ||
-                      await pathExists(join(standardsPath, 'coding.md'));
-    const archStd   = await pathExists(join(standardsPath, 'core', 'architecture.md')) ||
-                      await pathExists(join(standardsPath, 'architecture.md'));
-    if (codingStd && archStd) {
+    // Check for VSA standard (core to the framework)
+    const vsaStd = await pathExists(join(standardsPath, 'architecture', 'vertical-slice', 'vertical-slice.md')) ||
+                   await pathExists(join(standardsPath, 'vertical-slice.md'));
+    if (vsaStd) {
       checks.push({ name: 'standards/', status: 'ok' });
     } else {
-      checks.push({ name: 'standards/', status: 'warn', msg: 'core standards missing — run morph-spec init' });
+      checks.push({ name: 'standards/', status: 'warn', msg: 'VSA standard missing — run morph-spec init' });
       hasWarnings = true;
     }
   } else if (await pathExists(frameworkStdsRoot)) {

package/src/commands/project/init.js

@@ -365,6 +365,18 @@ export async function initCommand(options) {
       logger.dim('\nSkipped MCP setup (--skip-mcp flag)');
     }
 
+    // Auto-generate architecture context (non-blocking on failure)
+    spinner.text = 'Generating architecture context...';
+    try {
+      const { scanArchitecture, renderArchitectureContext } = await import('../../lib/generators/architecture-scanner.js');
+      const scanResult = await scanArchitecture(targetPath);
+      await renderArchitectureContext(targetPath, scanResult);
+      spinner.succeed('Architecture context generated');
+    } catch {
+      // Non-fatal: placeholder README.md remains
+      spinner.warn('Architecture context generation skipped');
+    }
+
     spinner.succeed('MORPH-SPEC installed successfully!');
 
     // Show next steps

package/src/commands/project/status.js

@@ -31,13 +31,12 @@ const PHASE_SYMBOLS = {
  */
 const PHASE_ORDER = [
   { key: 'proposal', name: 'FASE 0: PROPOSAL', order: 0 },
-  { key: 'setup', name: 'FASE 1: SETUP', order: 1 },
-  { key: 'uiux', name: 'FASE 1.5: UI/UX', order: 2, optional: true },
-  { key: 'design', name: 'FASE 2: DESIGN', order: 3 },
-  { key: 'clarify', name: 'FASE 3: CLARIFY', order: 4 },
-  { key: 'tasks', name: 'FASE 4: TASKS', order: 5 },
-  { key: 'implement', name: 'FASE 5: IMPLEMENT', order: 6 },
-  { key: 'sync', name: 'FASE 6: SYNC', order: 7, optional: true }
+  { key: 'uiux', name: 'FASE 1: UI/UX', order: 1, optional: true },
+  { key: 'design', name: 'FASE 2: DESIGN', order: 2 },
+  { key: 'plan', name: 'FASE 3: PLAN', order: 3 },
+  { key: 'tasks', name: 'FASE 4: TASKS', order: 4 },
+  { key: 'implement', name: 'FASE 5: IMPLEMENT', order: 5 },
+  { key: 'sync', name: 'FASE 6: SYNC', order: 6, optional: true }
 ];
 
 /**
@@ -69,7 +68,6 @@ function checkPhaseOutputs(phaseKey, feature) {
     proposal: ['proposal'],
     uiux: ['uiDesignSystem', 'uiMockups', 'uiComponents', 'uiFlows'],
     design: ['spec', 'contracts', 'schemaAnalysis', 'decisions'],
-    clarify: ['clarifications'],
     tasks: ['tasks']
   };
 
@@ -107,7 +105,6 @@ function formatPhase(phaseKey, currentPhase, feature, options = {}) {
       proposal: ['proposal'],
       uiux: ['uiDesignSystem', 'uiMockups', 'uiComponents', 'uiFlows'],
       design: ['spec', 'contracts', 'schemaAnalysis', 'decisions'],
-      clarify: ['clarifications'],
       tasks: ['tasks'],
       implement: ['recap']
     };
@@ -145,10 +142,8 @@ function getNextSteps(feature) {
   // Check for pending approvals relevant to current phase
   const phaseApprovalMap = {
     proposal: 'proposal',
-    setup: 'proposal',
     uiux: 'uiux',
     design: 'design',
-    clarify: 'design',
     tasks: 'tasks',
     implement: 'tasks'
   };
@@ -168,7 +163,6 @@ function getNextSteps(feature) {
   const phaseOutputMap = {
     proposal: ['proposal'],
     design: ['spec', 'contracts'],
-    clarify: ['clarifications'],
     tasks: ['tasks'],
     implement: ['recap']
   };

package/src/commands/scaffold/scaffold.js

@@ -0,0 +1,131 @@
+/**
+ * Scaffold Command - Generate feature files from templates.
+ *
+ * Sub-commands:
+ * - scaffold dotnet <feature> <slice-name> — VSA feature slice (.NET)
+ * - scaffold nextjs <feature> — Feature page + components (Next.js)
+ */
+
+import chalk from 'chalk';
+import { relative } from 'path';
+import { logger } from '../../utils/logger.js';
+import {
+  scaffoldDotnetSlice,
+  scaffoldNextjsFeature,
+  detectNamespace,
+} from '../../lib/generators/scaffold-generator.js';
+
+const KEBAB_REGEX = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+
+/**
+ * Validate that a name is valid kebab-case.
+ * @param {string} name
+ * @param {string} label
+ */
+function validateKebabCase(name, label) {
+  if (!KEBAB_REGEX.test(name)) {
+    logger.error(`Invalid ${label}: "${name}"`);
+    logger.dim('Must be kebab-case (e.g., "book", "create-user", "user-profile")');
+    process.exit(1);
+  }
+}
+
+/**
+ * Log the result of a scaffold operation.
+ * @param {Array<{path: string, skipped: boolean}>} files
+ * @param {string} outputDir
+ */
+function logResult(files, outputDir) {
+  let created = 0;
+  let skipped = 0;
+
+  for (const file of files) {
+    const rel = relative(outputDir, file.path);
+    if (file.skipped) {
+      logger.dim(`⊘ ${rel} (already exists)`);
+      skipped++;
+    } else {
+      logger.success(rel);
+      created++;
+    }
+  }
+
+  logger.blank();
+  const parts = [`${created} files generated`];
+  if (skipped > 0) parts.push(`${skipped} skipped`);
+  logger.info(parts.join(', '));
+}
+
+/**
+ * Scaffold .NET VSA feature slice.
+ */
+export async function scaffoldDotnetCommand(feature, sliceName, options) {
+  validateKebabCase(feature, 'feature name');
+  validateKebabCase(sliceName, 'slice name');
+
+  const outputDir = options.outputDir || process.cwd();
+
+  // Detect or use provided namespace
+  const namespace = options.namespace || detectNamespace(outputDir);
+  if (!namespace) {
+    logger.error('Could not detect namespace');
+    logger.dim('No .csproj or .morph/config.json found. Use --namespace <ns> to specify.');
+    process.exit(1);
+  }
+
+  const pascalFeature = feature.split('-').map(w => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase()).join('');
+  const pascalSlice = sliceName.split('-').map(w => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase()).join('');
+
+  logger.header('Scaffolding .NET VSA Slice');
+  logger.dim(`Feature:   ${pascalFeature}`);
+  logger.dim(`Slice:     ${pascalSlice}`);
+  logger.dim(`Namespace: ${namespace}`);
+  if (options.dryRun) logger.info(chalk.cyan('DRY RUN — files will NOT be written'));
+  logger.blank();
+
+  try {
+    const result = scaffoldDotnetSlice({
+      feature,
+      sliceName,
+      namespace,
+      outputDir,
+      dryRun: options.dryRun || false,
+    });
+
+    logResult(result.files, outputDir);
+  } catch (error) {
+    logger.error(`Scaffold failed: ${error.message}`);
+    if (options.verbose) console.error(error.stack);
+    process.exit(1);
+  }
+}
+
+/**
+ * Scaffold Next.js feature page with components and hooks.
+ */
+export async function scaffoldNextjsCommand(feature, options) {
+  validateKebabCase(feature, 'feature name');
+
+  const outputDir = options.outputDir || process.cwd();
+
+  const pascalFeature = feature.split('-').map(w => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase()).join('');
+
+  logger.header('Scaffolding Next.js Feature');
+  logger.dim(`Feature: ${pascalFeature}`);
+  if (options.dryRun) logger.info(chalk.cyan('DRY RUN — files will NOT be written'));
+  logger.blank();
+
+  try {
+    const result = scaffoldNextjsFeature({
+      featureName: feature,
+      outputDir,
+      dryRun: options.dryRun || false,
+    });
+
+    logResult(result.files, outputDir);
+  } catch (error) {
+    logger.error(`Scaffold failed: ${error.message}`);
+    if (options.verbose) console.error(error.stack);
+    process.exit(1);
+  }
+}

package/src/commands/scope/escalate.js

@@ -51,7 +51,7 @@ export async function escalateScope(featureName, options) {
   }
 
   // Read spec.md (optional — not all features have it)
-  const specPath = join(process.cwd(), '.morph', 'features', featureName, '1-design', 'spec.md');
+  const specPath = join(process.cwd(), '.morph', 'features', featureName, '2-design', 'spec.md');
   let specMd = '';
   try { specMd = readFileSync(specPath, 'utf-8'); } catch { /* ok */ }
 

package/src/commands/state/advance-phase.js

@@ -28,7 +28,7 @@ import { emitValidatorDispatch } from '../../lib/validators/shared/emit-validato
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
 // Phase order for advancing (skips optional phases unless active)
-const PHASE_ORDER = ['proposal', 'setup', 'uiux', 'design', 'clarify', 'plan', 'tasks', 'implement', 'sync'];
+const PHASE_ORDER = ['proposal', 'uiux', 'design', 'plan', 'tasks', 'implement', 'sync'];
 
 /**
  * Phases that require an explicit approval gate before advancing.
@@ -59,7 +59,7 @@ function getNextPhase(currentPhase, feature, skipOptional, featureName) {
   }
 
   // Agents that justify the uiux phase (wireframes, design system).
-  // Implementation-only agents (blazor-builder, nextjs-expert) are NOT included —
+  // Implementation-only agents (nextjs-expert) are NOT included —
   // they build components from existing designs but don't create the design artifacts.
   const uiDesignAgents = ['uiux-designer', 'ui-ux-designer', 'ui-designer'];
 
@@ -189,8 +189,15 @@ export async function advancePhaseCommand(feature, options = {}) {
   console.log(chalk.gray('Next Phase:'), nextPhaseDef.name);
 
   // === GATE 1: State Machine Validation ===
-  // Ensure phase transition is valid (no skipping required phases)
-  if (!options.force) {
+  // When a workflow config defines which phases to run, getNextPhase()
+  // is authoritative for phase navigation. The state machine's
+  // adjacent-only transitions would reject legitimate workflow skips
+  // (e.g., fast-track: proposal → tasks).
+  const activeWorkflowConfig = featureData.workflow && featureData.workflow !== 'auto'
+    ? getWorkflowConfig(featureData.workflow)
+    : null;
+
+  if (!options.force && !activeWorkflowConfig) {
     try {
       validateTransition(currentPhase, nextPhase);
     } catch (error) {
@@ -261,7 +268,7 @@ export async function advancePhaseCommand(feature, options = {}) {
 
   // === GATE 4: Content Validation ===
   // Validate spec.md and contracts.cs when advancing from design phase
-  if (currentPhase === 'design' && (nextPhase === 'clarify' || nextPhase === 'tasks')) {
+  if (currentPhase === 'design' && nextPhase === 'plan') {
     // Check spec.md structure and content (filesystem-based)
     const specAbsPath = getAbsoluteOutputPath(process.cwd(), feature, 'spec');
     if (existsSync(specAbsPath)) {
@@ -334,19 +341,6 @@ export async function advancePhaseCommand(feature, options = {}) {
     }
   }
 
-  // === GATE 6: Clarifications Required ===
-  // When advancing FROM clarify, clarifications.md must exist.
-  // This enforces that morph-phase-clarify was actually run (not just skipped).
-  if (currentPhase === 'clarify') {
-    const clarPath = join(process.cwd(), '.morph', 'features', feature, '1-design', 'clarifications.md');
-    if (!existsSync(clarPath)) {
-      console.log(chalk.red('\n✗ Cannot advance from clarify — clarifications.md is missing'));
-      console.log(chalk.yellow('  Run the phase-clarify skill first: /morph-phase-clarify'));
-      console.log(chalk.gray('  Output expected at: .morph/features/' + feature + '/1-design/clarifications.md\n'));
-      process.exit(1);
-    }
-  }
-
   // Gate: Check design system when advancing to implement with UI agents
   if (nextPhase === 'implement') {
     const gateResult = designSystemGate(feature, process.cwd());
@@ -373,7 +367,7 @@ export async function advancePhaseCommand(feature, options = {}) {
 
   // Create the target phase directory so derivePhase() reflects the new phase
   const PHASE_DIR_MAP = {
-    'proposal': '0-proposal', 'design': '1-design', 'uiux': '2-ui',
+    'proposal': '0-proposal', 'design': '2-design', 'uiux': '1-ui',
     'plan': '3-plan', 'tasks': '4-tasks', 'implement': '5-implement',
   };
   const targetDir = PHASE_DIR_MAP[nextPhase];
@@ -488,10 +482,6 @@ export async function advancePhaseCommand(feature, options = {}) {
  */
 function getPhaseGuidance(phase, feature) {
   const guides = {
-    'setup': [
-      `Resume spec pipeline: /morph-proposal ${feature}`,
-      'Auto-continues from setup phase'
-    ],
     'uiux': [
       `Resume spec pipeline: /morph-proposal ${feature}`,
       'Provide layout references and preferences',
@@ -505,10 +495,6 @@ function getPhaseGuidance(phase, feature) {
         isDotnet ? 'Approve spec.md and contracts.cs' : 'Approve spec.md and contracts.ts (TypeScript + Zod schemas)'
       ];
     })(),
-    'clarify': [
-      `Resume spec pipeline: /morph-proposal ${feature}`,
-      'Resolve edge cases and unknowns'
-    ],
     'plan': [
       `Resume spec pipeline: /morph-proposal ${feature}`,
       'Review implementation plan for completeness',
@@ -559,7 +545,7 @@ function designSystemGate(feature, projectPath = '.') {
     blocked: true,
     message: 'Cannot advance to implementation — UI agents are active but no design system found',
     solution: [
-      'Design system is required when UI agents (blazor-builder, ui-designer, css-specialist) are active',
+      'Design system is required when UI agents (ui-designer, css-specialist) are active',
       '',
       'Create a design system with one of these options:',
       '  1. Project-level: .morph/context/design-system.md (shared across features)',
@@ -567,7 +553,7 @@ function designSystemGate(feature, projectPath = '.') {
       '  3. Run /morph-phase-uiux skill to auto-generate from existing codebase',
       '',
       'Or remove UI agents if they are not needed:',
-      `  morph-spec state remove-agent ${feature} blazor-builder`
+      `  morph-spec state remove-agent ${feature} css-specialist`
     ]
   };
 }

package/src/commands/state/state.js

@@ -15,7 +15,7 @@ import { derivePhase } from '../../core/state/state-manager.js';
 // Phase Resolution
 // ============================================================================
 
-const PHASE_ORDER_LIST = ['setup', 'proposal', 'uiux', 'design', 'clarify', 'plan', 'tasks', 'implement', 'sync', 'archived'];
+const PHASE_ORDER_LIST = ['proposal', 'uiux', 'design', 'plan', 'tasks', 'implement', 'sync', 'archived'];
 
 /**
  * Resolve the effective phase: pick whichever is further ahead between the
@@ -38,7 +38,7 @@ function resolvePhase(storedPhase, derivedPhase) {
  * These phases must be reached through `morph-spec phase advance` which enforces
  * all validation gates (approval, output requirements, spec content, etc.).
  *
- * Lightweight phases (proposal, setup, clarify, sync) are not in this list
+ * Lightweight phases (proposal, sync) are not in this list
  * because they have no approval gates and are safe to set directly.
  */
 export const PROTECTED_PHASES = ['design', 'tasks', 'uiux', 'implement'];
@@ -244,13 +244,29 @@ async function setCommand(featureName, key, value, options) {
       } else {
         logger.warn(`Direct phase override — validation gates may be bypassed.`);
         logger.dim(`  The actual phase is derived from filesystem subdirectories`);
-        logger.dim(`  (0-proposal/, 1-design/, 4-tasks/, 5-implement/). This sets a state.json`);
-        logger.dim(`  override used only for lightweight phases (setup, clarify, sync).`);
+        logger.dim(`  (0-proposal/, 2-design/, 4-tasks/, 5-implement/). This sets a state.json`);
+        logger.dim(`  override used only for lightweight phases (proposal, sync).`);
         logger.dim(`  Recommended: morph-spec phase advance ${featureName}`);
       }
       logger.blank();
     }
 
+    // Validate workflow values
+    if (key === 'workflow') {
+      try {
+        const { listWorkflows } = await import('../../core/workflows/workflow-detector.js');
+        const validIds = listWorkflows().map(w => w.id).concat(['auto']);
+        if (!validIds.includes(value)) {
+          logger.error(`Invalid workflow: "${value}"`);
+          logger.dim(`  Valid workflows: ${validIds.join(', ')}`);
+          logger.blank();
+          process.exit(1);
+        }
+      } catch {
+        // Workflow detector unavailable — skip validation
+      }
+    }
+
     const spinner = ora('Updating state...').start();
 
     // Parse value automatically (JSON, number, boolean)
@@ -401,7 +417,6 @@ async function markOutputCommand(featureName, outputType, options) {
     logger.dim('  Valid types:');
     logger.dim('    Proposal:  proposal');
     logger.dim('    Design:    schemaAnalysis, spec, contracts, contractsVsa, decisions');
-    logger.dim('    Clarify:   clarifications');
     logger.dim('    Tasks:     tasks');
     logger.dim('    UI/UX:     uiDesignSystem, uiMockups, uiComponents, uiFlows');
     logger.dim('    Implement: recap');

package/src/commands/tasks/task.js

@@ -52,7 +52,6 @@ export async function taskDoneCommand(featureName, taskIds, options) {
   }
 }
 
-/**
 /**
  * Start task command
  */
@@ -66,23 +65,6 @@ export async function taskStartCommand(featureName, taskId, options) {
   }
 }
 
-/**
- * Bulk-start tasks command
- */
-export async function taskBulkStartCommand(featureName, range, options) {
-  try {
-    const args = ['bulk-start', featureName];
-    if (range) args.push(range);
-    if (options.all) args.push('--all');
-    if (options.from) args.push('--from', options.from);
-    if (options.to) args.push('--to', options.to);
-    await executeTaskManager(args);
-  } catch (error) {
-    console.error(chalk.red(`Error: ${error.message}`));
-    process.exit(1);
-  }
-}
-
 /**
  * Bulk-done tasks command
  */
@@ -118,15 +100,3 @@ export async function taskAnnotateCommand(featureName, taskId, text, options) {
   }
 }
 
-/**
- * Get next task command
- */
-export async function taskNextCommand(featureName, options) {
-  try {
-    const args = ['next', featureName];
-    await executeTaskManager(args);
-  } catch (error) {
-    console.error(chalk.red(`Error: ${error.message}`));
-    process.exit(1);
-  }
-}

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

@@ -51,10 +51,6 @@ const OUTPUT_SECTIONS = {
     required: ['T001', 'category', 'dependencies'],
     optional: ['CHECKPOINT', 'estimatedMinutes']
   },
-  'clarifications.md': {
-    required: ['Q1', 'Answer', 'Edge Cases'],
-    optional: ['Assumptions', 'Business Rules']
-  }
 };
 
 /**
@@ -62,10 +58,8 @@ const OUTPUT_SECTIONS = {
  */
 const PHASE_OUTPUTS = {
   proposal: ['proposal.md'],
-  setup: ['proposal.md'],
-  uiux: ['ui-design-system.md', 'ui-mockups.md', 'ui-components.md', 'ui-flows.md'],
+  uiux: ['design-system.md', 'mockups.md', 'components.md', 'flows.md'],
   design: ['spec.md', 'contracts.cs', 'schema-analysis.md', 'decisions.md'],
-  clarify: ['spec.md', 'clarifications.md'],
   tasks: ['tasks.md'],
   implement: ['spec.md', 'contracts.cs', 'tasks.md']
 };
@@ -75,9 +69,8 @@ const PHASE_OUTPUTS = {
  */
 const PHASE_FOLDERS = {
   proposal: '0-proposal',
-  uiux: '2-ui',
-  design: '1-design',
-  clarify: '1-design',
+  uiux: '1-ui',
+  design: '2-design',
   plan: '3-plan',
   tasks: '4-tasks',
   implement: '5-implement',

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

@@ -17,26 +17,25 @@ import { join } from 'path';
  *
  * Fields:
  *   filename     - The file's basename (e.g. 'spec.md')
- *   phaseDir     - Subdirectory within .morph/features/{feature}/ (e.g. '1-design')
+ *   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: '1-design',    phase: 'design',    protected: true,  approvalGate: 'design' },
-  spec:          { filename: 'spec.md',             phaseDir: '1-design',    phase: 'design',    protected: true,  approvalGate: 'design' },
-  clarifications:{ filename: 'clarifications.md',  phaseDir: '1-design',    phase: 'clarify',   protected: false },
-  contracts:     { filename: 'contracts.cs',        phaseDir: '1-design',    phase: 'design',    protected: true,  approvalGate: 'design' },
-  contractsTs:   { filename: 'contracts.ts',        phaseDir: '1-design',    phase: 'design',    protected: true,  approvalGate: 'design' },
-  contractsVsa:  { filename: 'contracts-vsa.cs',    phaseDir: '1-design',    phase: 'design',    protected: true,  approvalGate: 'design' },
+  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: '2-ui',        phase: 'uiux',      protected: true,  approvalGate: 'uiux' },
-  uiMockups:     { filename: 'mockups.md',          phaseDir: '2-ui',        phase: 'uiux',      protected: true,  approvalGate: 'uiux' },
-  uiComponents:  { filename: 'components.md',       phaseDir: '2-ui',        phase: 'uiux',      protected: true,  approvalGate: 'uiux' },
-  uiFlows:       { filename: 'flows.md',            phaseDir: '2-ui',        phase: 'uiux',      protected: true,  approvalGate: 'uiux' },
-  decisions:     { filename: 'decisions.md',        phaseDir: '1-design',    phase: 'design',    protected: false },
+  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 },
 };
 
@@ -50,7 +49,7 @@ export const OUTPUT_SCHEMA = {
  *
  * @param {string} featureName - The feature name
  * @param {string} outputType  - camelCase output type key from OUTPUT_SCHEMA
- * @returns {string} e.g. ".morph/features/my-feature/1-design/spec.md"
+ * @returns {string} e.g. ".morph/features/my-feature/2-design/spec.md"
  */
 export function getOutputPath(featureName, outputType) {
   const entry = OUTPUT_SCHEMA[outputType];