@polymorphism-tech/morph-spec 3.1.0 → 3.2.0

package/docs/troubleshooting.md

@@ -0,0 +1,269 @@
+# Troubleshooting - CLI Auto Context Detection
+
+Common issues and solutions for MORPH-SPEC auto-detection.
+
+## Claude Code Issues
+
+### Issue: "Claude Code environment not detected"
+
+**Cause**: Auto-detection requires Claude Code CLI to be installed and active.
+
+**Solutions**:
+
+1. **Use wizard mode** (recommended for first-time setup):
+   ```bash
+   morph-spec init --wizard
+   ```
+
+2. **Install Claude Code** and retry:
+   - Download from https://claude.ai/claude-code
+   - Ensure `claude` command is in PATH
+   - Retry `morph-spec init`
+
+3. **Skip auto-detection** and configure manually later:
+   ```bash
+   morph-spec init --skip-detection
+   # Later: morph-spec update --wizard
+   ```
+
+### Issue: "LLM analysis timeout"
+
+**Cause**: Analysis taking longer than 60 seconds (default timeout for interactive mode).
+
+**Solutions**:
+
+1. **Clean project before analysis**:
+   ```bash
+   rm -rf node_modules dist build .next
+   morph-spec init
+   ```
+
+2. **Use wizard mode** (instant):
+   ```bash
+   morph-spec init --wizard
+   ```
+
+3. **Check Claude Code performance**:
+   - Restart Claude Code
+   - Check system resources (CPU, memory)
+
+## LLM Analysis Errors
+
+### Issue: "Schema validation failed"
+
+**Cause**: LLM returned JSON that doesn't match the expected schema.
+
+**Diagnosis**:
+```bash
+# Enable debug mode to see LLM response
+DEBUG=1 morph-spec init
+```
+
+**Solutions**:
+
+1. **Use wizard mode** to provide manual input:
+   ```bash
+   morph-spec init --wizard
+   ```
+
+2. **Report issue** if recurring:
+   - Include project type in issue report
+   - Share anonymized `package.json` or `.csproj` structure
+
+### Issue: "LLM response is not valid JSON"
+
+**Cause**: LLM returned malformed JSON (rare).
+
+**Solutions**:
+
+1. **Retry** - may be a one-time error:
+   ```bash
+   morph-spec init
+   ```
+
+2. **Use wizard mode**:
+   ```bash
+   morph-spec init --wizard
+   ```
+
+## File System Issues
+
+### Issue: "Permission denied" when creating .morph/
+
+**Cause**: Insufficient permissions in project directory.
+
+**Solutions**:
+
+1. **Run with correct permissions**:
+   ```bash
+   sudo morph-spec init  # Unix/Mac
+   # Or run as administrator on Windows
+   ```
+
+2. **Check directory ownership**:
+   ```bash
+   ls -la .  # Should show your user as owner
+   ```
+
+### Issue: Config files getting overwritten
+
+**Cause**: Running `morph-spec update` without reviewing changes.
+
+**Protection**: Auto-detection creates backups:
+- `.morph/project.md.YYYY-MM-DDTHH-MM-SS.backup`
+- `.morph/config/config.json.YYYY-MM-DDTHH-MM-SS.backup`
+
+**Solutions**:
+
+1. **Review diff before approving**:
+   - Auto-detection shows diff when updating
+   - Choose "Edit" to modify before saving
+
+2. **Restore from backup** if needed:
+   ```bash
+   cp .morph/project.md.2026-02-14T10-30-00.backup .morph/project.md
+   ```
+
+3. **Skip auto-detection** during update:
+   ```bash
+   morph-spec update --skip-detection
+   ```
+
+## Detection Accuracy Issues
+
+### Issue: Wrong project type detected
+
+**Example**: Monorepo detected as `nextjs` instead of `monorepo`.
+
+**Solutions**:
+
+1. **Use wizard mode** for accurate manual input:
+   ```bash
+   morph-spec init --wizard
+   ```
+
+2. **Edit config after generation**:
+   - Choose "Edit" during review
+   - Manually correct `type` field in config.json
+
+3. **Report detection issue**:
+   - Helps improve LLM prompt and examples
+
+### Issue: Missing dependencies detected
+
+**Cause**: Auto-detection only reads whitelisted files (package.json, .csproj).
+
+**Solution**:
+
+- This is by design (privacy/security)
+- If critical dependency is missed, manually edit `.morph/project.md`
+
+### Issue: Low confidence score (<70%)
+
+**Cause**: Project structure is unclear or non-standard.
+
+**Solutions**:
+
+1. **Add README.md or CLAUDE.md** with project description
+2. **Use wizard mode** for manual configuration
+3. **Accept low confidence** - configs can be edited later
+
+## Edge Case Handling
+
+### Empty Project (no package.json or .csproj)
+
+**Behavior**: Auto-fallback to wizard mode.
+
+**Solution**: Answer 7 wizard questions to configure manually.
+
+### Monorepo with Multiple Stacks
+
+**Behavior**: Detects all stacks, sets `type: "monorepo"`.
+
+**Example Output**:
+```json
+{
+  "type": "monorepo",
+  "stack": {
+    "frontend": { "tech": "Next.js", "version": "15" },
+    "backend": { "tech": ".NET", "version": "10" }
+  }
+}
+```
+
+### Project with No Database
+
+**Behavior**: `stack.database` set to `null`.
+
+**Warning**: May show "Database technology not detected" in warnings.
+
+### Git Repo Without Remote
+
+**Behavior**: `gitRemote` set to `null`.
+
+**Not an error** - local repos are valid.
+
+## Privacy & Security Concerns
+
+### Question: What data is sent to LLM?
+
+**Answer**: Only sanitized, whitelisted data:
+- package.json (dependencies only, secrets removed)
+- .csproj filenames (not contents)
+- First 500 chars of README.md and CLAUDE.md
+- Directory structure (folder names only)
+- Infrastructure file counts (not contents)
+
+**Never sent**:
+- `.env` files
+- Secrets/passwords/API keys
+- File contents (except whitelisted files)
+- node_modules/
+- Source code
+
+### Question: Is data sent to Anthropic servers?
+
+**Answer**: No. LLM analysis runs locally in Claude Code. No external API calls.
+
+### Question: What if sensitive data is detected?
+
+**Behavior**: Secret redaction removes:
+- API keys (10+ patterns detected)
+- Passwords in connection strings
+- Bearer tokens
+- Private keys (PEM format)
+- GitHub/NPM tokens
+
+**Verification**: Review sanitized context in debug mode:
+```bash
+DEBUG=1 morph-spec init
+```
+
+## Getting Help
+
+### Enable Debug Mode
+
+```bash
+DEBUG=1 morph-spec init
+```
+
+Shows:
+- Full LLM prompts
+- Raw LLM responses
+- Schema validation errors
+- File read operations
+
+### Report Issues
+
+GitHub: https://github.com/polymorphism-tech/morph-spec-framework/issues
+
+Include:
+- MORPH-SPEC version (`morph-spec --version`)
+- Claude Code version
+- Project type (Next.js, Blazor, etc.)
+- Error message (with DEBUG=1 output if possible)
+- Anonymized `package.json` or `.csproj` structure
+
+---
+
+**Need more help?** Check the [CLI Auto Detection Guide](./cli-auto-detection.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polymorphism-tech/morph-spec",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "MORPH-SPEC v3: AI-First development framework with validation pipeline, .NET 10, Microsoft Agent Framework, and Fluent UI Blazor",
   "keywords": [
     "claude-code",
@@ -52,8 +52,12 @@
     "ajv-formats": "^3.0.1",
     "chalk": "^5.3.0",
     "commander": "^12.0.0",
+    "diff": "^5.2.0",
     "fs-extra": "^11.2.0",
     "glob": "^10.3.0",
+    "handlebars": "^4.7.8",
+    "inquirer": "^9.2.0",
+    "minimatch": "^9.0.5",
     "ora": "^8.0.0",
     "yaml": "^2.3.4"
   },

package/src/commands/advance-phase.js

@@ -10,10 +10,12 @@
  */
 
 import chalk from 'chalk';
-import { loadState, saveState, getFeature } from '../lib/state-manager.js';
+import { loadState, saveState, getFeature, getApprovalGate } from '../lib/state-manager.js';
 import { PHASES, validatePhase } from './validate-phase.js';
 import { detectDesignSystem, hasUIAgentsActive } from '../lib/design-system-detector.js';
 import { validateSpec } from '../lib/spec-validator.js';
+import { validateTransition, getPhaseDisplayName } from '../lib/phase-state-machine.js';
+import { validateSpecContent, validateTasksContent, validateFeatureOutputs } from '../lib/validators/content-validator.js';
 
 // Phase order for advancing (skips optional phases unless active)
 const PHASE_ORDER = ['proposal', 'setup', 'uiux', 'design', 'clarify', 'tasks', 'implement', 'sync'];
@@ -96,6 +98,42 @@ export async function advancePhaseCommand(feature, options = {}) {
   const nextPhaseDef = PHASES[nextPhase];
   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) {
+    try {
+      validateTransition(currentPhase, nextPhase);
+    } catch (error) {
+      console.log(chalk.red('\n✗ Invalid phase transition'));
+      console.log(chalk.yellow(error.message));
+      console.log(chalk.gray('\nUse --force to override (not recommended)\n'));
+      process.exit(1);
+    }
+  }
+
+  // === GATE 2: Approval Gate Check ===
+  // Check if current phase requires approval before advancing
+  const approvalGateMap = {
+    'design': 'design',
+    'tasks': 'tasks',
+    'uiux': 'uiux'
+  };
+
+  const requiredGate = approvalGateMap[currentPhase];
+  if (requiredGate && !options.skipApproval) {
+    const gateStatus = getApprovalGate(feature, requiredGate);
+
+    if (!gateStatus || !gateStatus.approved) {
+      console.log(chalk.red(`\n✗ Phase "${currentPhase}" requires approval before advancing`));
+      console.log(chalk.yellow(`\nRun: morph-spec approve ${feature} ${requiredGate}`));
+      console.log(chalk.gray('Or use --skip-approval to bypass (not recommended)\n'));
+      process.exit(1);
+    }
+
+    console.log(chalk.green(`✓ Approval gate "${requiredGate}" passed`));
+  }
+
+  // === GATE 3: Output Requirements ===
   // Validate that current phase requirements are met before advancing
   const validation = validatePhase(feature, nextPhase);
 
@@ -112,8 +150,34 @@ export async function advancePhaseCommand(feature, options = {}) {
     console.log(chalk.yellow(`\n⚠️  ${validation.stateWarning}`));
   }
 
-  // Gate: Validate spec.md and contracts.cs when advancing from design phase
+  // === GATE 4: Content Validation ===
+  // Validate spec.md and contracts.cs when advancing from design phase
   if (currentPhase === 'design' && (nextPhase === 'clarify' || nextPhase === 'tasks')) {
+    // Check spec.md structure and content
+    if (featureData.outputs?.spec?.created) {
+      const specContentValidation = validateSpecContent(featureData.outputs.spec.path);
+
+      if (!specContentValidation.valid) {
+        console.log(chalk.red('\n✗ Spec content validation failed:'));
+        specContentValidation.missing.forEach(section => {
+          console.log(chalk.red(`  - Missing section: ${section}`));
+        });
+        specContentValidation.errors.forEach(error => {
+          console.log(chalk.red(`  - ${error}`));
+        });
+        console.log('');
+        process.exit(1);
+      }
+
+      if (specContentValidation.warnings?.length > 0 && !options.skipWarnings) {
+        console.log(chalk.yellow('\n⚠️  Spec content warnings:'));
+        specContentValidation.warnings.forEach(warning => {
+          console.log(chalk.yellow(`  - ${warning}`));
+        });
+      }
+    }
+
+    // Run existing spec validator (anti-patterns, IaC checks)
     const specValidation = await validateSpec('.', feature);
 
     if (specValidation.errors > 0) {
@@ -135,6 +199,33 @@ export async function advancePhaseCommand(feature, options = {}) {
     }
   }
 
+  // === GATE 5: Tasks Content Validation ===
+  // Validate tasks.json structure when advancing to implement
+  if (currentPhase === 'tasks' && nextPhase === 'implement') {
+    if (featureData.outputs?.tasks?.created) {
+      const tasksContentValidation = validateTasksContent(featureData.outputs.tasks.path);
+
+      if (!tasksContentValidation.valid) {
+        console.log(chalk.red('\n✗ Tasks content validation failed:'));
+        tasksContentValidation.errors.forEach(error => {
+          console.log(chalk.red(`  - ${error}`));
+        });
+        console.log('');
+        process.exit(1);
+      }
+
+      if (tasksContentValidation.warnings?.length > 0 && !options.skipWarnings) {
+        console.log(chalk.yellow('\n⚠️  Tasks content warnings:'));
+        tasksContentValidation.warnings.forEach(warning => {
+          console.log(chalk.yellow(`  - ${warning}`));
+        });
+      }
+
+      // Show tasks stats
+      console.log(chalk.green(`\n✓ Tasks validated: ${tasksContentValidation.stats.totalTasks} total (${tasksContentValidation.stats.regularTasks} tasks + ${tasksContentValidation.stats.checkpoints} checkpoints)`));
+    }
+  }
+
   // Gate: Check design system when advancing to implement with UI agents
   if (nextPhase === 'implement') {
     const gateResult = designSystemGate(feature);

package/src/commands/approve.js

@@ -0,0 +1,221 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { getFeature, setApprovalGate, getApprovalGate, getApprovalHistory } from '../lib/state-manager.js';
+
+/**
+ * Approval Commands - Manage approval gates for MORPH workflow
+ *
+ * Commands:
+ * - approve: Mark a gate as approved
+ * - reject: Reject a gate with reason
+ * - approval-status: Show approval status for all gates
+ */
+
+const program = new Command();
+
+/**
+ * Valid approval gate names
+ */
+const VALID_GATES = ['proposal', 'uiux', 'design', 'tasks'];
+
+/**
+ * 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
+    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);
+
+/**
+ * Reject action function - Reject a gate with optional reason
+ */
+export async function rejectCommand(featureName, gateName, reason, 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);
+    }
+
+    // Set rejection
+    setApprovalGate(featureName, gateName, false, {
+      rejectedBy: process.env.USER || process.env.USERNAME || 'user',
+      rejectedAt: new Date().toISOString(),
+      reason: reason || 'No reason provided'
+    });
+
+    console.log(chalk.red(`\n❌ Gate "${gateName}" rejected for feature: ${featureName}`));
+    if (reason) {
+      console.log(chalk.gray(`Reason: ${reason}`));
+    }
+    console.log(chalk.yellow(`\n⚠️  Address the concerns and request approval again\n`));
+
+  } catch (error) {
+    console.error(chalk.red(`\n❌ Error rejecting gate: ${error.message}\n`));
+    process.exit(1);
+  }
+}
+
+/**
+ * Reject command - Reject a gate with optional reason
+ */
+program
+  .command('reject <feature> <gate> [reason]')
+  .description('Reject a phase gate with optional reason')
+  .action(rejectCommand);
+
+/**
+ * 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;