@polymorphism-tech/morph-spec 3.1.0 → 3.2.0

package/bin/morph-spec.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 import { program } from 'commander';
 import chalk from 'chalk';
@@ -32,6 +32,13 @@ import { validatePhaseCommand } from '../src/commands/validate-phase.js';
 import { sessionSummaryCommand } from '../src/commands/session-summary.js';
 import { rollbackPhaseCommand } from '../src/commands/rollback-phase.js';
 import { advancePhaseCommand } from '../src/commands/advance-phase.js';
+import { approveCommand, rejectCommand, approvalStatusCommand } from '../src/commands/approve.js';
+import { spawnTeamCommand } from '../src/commands/spawn-team.js';
+import capturePatternProgram from '../src/commands/capture-pattern.js';
+import searchPatternsProgram from '../src/commands/search-patterns.js';
+import { generateMetadataCommand } from '../src/commands/generate.js';
+import migrateStateProgram from '../src/commands/migrate-state.js';
+import upgradeProgram from '../src/commands/upgrade.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
@@ -189,6 +196,13 @@ generateCommand
     await generateContextCommand('.', feature);
   });
 
+generateCommand
+  .command('metadata <feature>')
+  .description('Generate metadata.json summary from markdown outputs')
+  .option('--output <path>', 'Custom output path')
+  .option('--verbose', 'Show detailed extraction info')
+  .action((feature, options) => generateMetadataCommand(feature, options));
+
 // Validation commands (Sprint 4: Continuous Validation)
 program
   .command('validate [validator]')
@@ -365,6 +379,41 @@ program
   .option('-v, --verbose', 'Show detailed output')
   .action(rollbackPhaseCommand);
 
+// Approval workflow commands (MORPH-SPEC 3.0)
+program
+  .command('approve <feature> <gate>')
+  .description('Approve a phase gate (design, tasks, uiux, proposal)')
+  .option('--approver <name>', 'Name of approver (default: current user)')
+  .option('--notes <notes>', 'Approval notes')
+  .action((feature, gate, options) => approveCommand(feature, gate, options));
+
+program
+  .command('reject <feature> <gate> [reason]')
+  .description('Reject a phase gate with optional reason')
+  .action((feature, gate, reason, options) => rejectCommand(feature, gate, reason, options));
+
+program
+  .command('approval-status <feature>')
+  .description('Show approval status for all gates')
+  .option('--json', 'Output as JSON')
+  .action((feature, options) => approvalStatusCommand(feature, options));
+
+// Agent team spawning (MORPH-SPEC 3.0)
+program
+  .command('spawn-team <feature>')
+  .description('Generate agent team configuration for Task tool')
+  .option('--json', 'Output as JSON')
+  .option('--verbose', 'Show detailed team configuration')
+  .action((feature, options) => spawnTeamCommand(feature, options));
+
+// Pattern learning system (MORPH-SPEC 3.0) - Add as subcommands
+program.addCommand(capturePatternProgram);
+program.addCommand(searchPatternsProgram);
+
+// Migration and upgrade commands (MORPH-SPEC 3.0) - Add as subcommands
+program.addCommand(migrateStateProgram);
+program.addCommand(upgradeProgram);
+
 // Wire global --stack flag to stack-resolver before any command executes
 program.hook('preAction', () => {
   const opts = program.opts();

package/bin/render-template.js

@@ -19,6 +19,7 @@ import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
 import { resolveConfigDir } from '../src/lib/stack-resolver.js';
+import { getAllTemplatePlaceholders } from '../src/lib/template-data-sources.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -111,7 +112,7 @@ function transformCase(str) {
 /**
  * Render template by replacing placeholders
  */
-function renderTemplate(templatePath, variables) {
+function renderTemplate(templatePath, variables, mcpData = null) {
   if (!fs.existsSync(templatePath)) {
     throw new Error(`Template file not found: ${templatePath}`);
   }
@@ -121,8 +122,8 @@ function renderTemplate(templatePath, variables) {
   // Get default variables
   const defaults = getDefaultVariables();
 
-  // Merge with provided variables (provided takes precedence)
-  const allVariables = { ...defaults, ...variables };
+  // Merge: defaults → MCP data → provided variables (rightmost takes precedence)
+  const allVariables = { ...defaults, ...(mcpData || {}), ...variables };
 
   // Auto-generate case transformations for FEATURE_NAME if provided
   if (allVariables.FEATURE_NAME) {
@@ -205,9 +206,29 @@ ${colors.green}Example:${colors.reset}
     '{"FEATURE_NAME":"scheduled-reports","STACK":"Blazor"}'
 
 ${colors.green}Flags:${colors.reset}
-  --help, -h       Show this help message
-  --verbose, -v    Show detailed replacement information
-  --dry-run, -d    Preview output without writing file
+  --help, -h           Show this help message
+  --verbose, -v        Show detailed replacement information
+  --dry-run, -d        Preview output without writing file
+  --with-mcp-data      Inject dynamic MCP data (project stats, compliance, activity)
+
+${colors.green}MCP Data Placeholders:${colors.reset} (Available with --with-mcp-data flag)
+  {{MCP_PROJECT_FILES}}            - Total files in project
+  {{MCP_TEST_COVERAGE}}            - Test coverage percentage (or N/A)
+  {{MCP_COMPLIANCE_SCORE}}         - Overall compliance score (0-100)
+  {{MCP_LAST_FEATURE}}             - Name of last feature worked on
+  {{MCP_LAST_COMMIT}}              - Last git commit message
+  {{MCP_LAST_COMMIT_AUTHOR}}       - Author of last commit
+  {{MCP_LAST_COMMIT_TIME}}         - Relative time of last commit
+  {{MCP_CS_FILES}}                 - Number of .cs files
+  {{MCP_RAZOR_FILES}}              - Number of .razor files
+  {{MCP_TS_FILES}}                 - Number of .ts files
+  {{MCP_JS_FILES}}                 - Number of .js files
+  {{MCP_NUGET_PACKAGES}}           - Number of NuGet packages
+  {{MCP_NPM_PACKAGES}}             - Number of npm packages
+  {{MCP_ARCHITECTURE_VIOLATIONS}}  - Architecture validator errors
+  {{MCP_PACKAGE_CONFLICTS}}        - Package conflict count
+  {{MCP_SECURITY_ISSUES}}          - Security validator issues
+  {{MCP_RECENT_BRANCHES}}          - Recent git branches (up to 3)
 
 ${colors.yellow}Note:${colors.reset} DATE, YEAR, AUTHOR, PROJECT_NAME, STACK, NAMESPACE are auto-populated from config.json
   `);
@@ -216,7 +237,7 @@ ${colors.yellow}Note:${colors.reset} DATE, YEAR, AUTHOR, PROJECT_NAME, STACK, NA
 /**
  * Main CLI logic
  */
-function main() {
+async function main() {
   const args = process.argv.slice(2);
 
   // Check for help flag
@@ -228,9 +249,10 @@ function main() {
   // Parse flags
   const verbose = args.includes('--verbose') || args.includes('-v');
   const dryRun = args.includes('--dry-run') || args.includes('-d');
+  const withMcpData = args.includes('--with-mcp-data');
 
   // Filter out flags
-  const flags = ['--verbose', '-v', '--dry-run', '-d', '--help', '-h'];
+  const flags = ['--verbose', '-v', '--dry-run', '-d', '--help', '-h', '--with-mcp-data'];
   const cleanArgs = args.filter(arg => !flags.includes(arg));
 
   // Validate arguments
@@ -253,10 +275,31 @@ function main() {
   }
 
   try {
+    // Get MCP data if requested
+    let mcpData = null;
+    if (withMcpData) {
+      try {
+        console.log(`${colors.cyan}🔍 Gathering MCP data from project...${colors.reset}`);
+        mcpData = await getAllTemplatePlaceholders(process.cwd());
+
+        if (verbose) {
+          console.log(`${colors.green}✅ MCP data loaded:${colors.reset}`);
+          console.log(`   Files: ${mcpData.MCP_PROJECT_FILES}`);
+          console.log(`   Coverage: ${mcpData.MCP_TEST_COVERAGE}`);
+          console.log(`   Compliance: ${mcpData.MCP_COMPLIANCE_SCORE}%`);
+          console.log(`   Last Feature: ${mcpData.MCP_LAST_FEATURE}\n`);
+        }
+      } catch (error) {
+        console.error(`${colors.yellow}⚠️  Warning: Failed to load MCP data - ${error.message}${colors.reset}`);
+        console.error(`   Continuing with standard placeholders only...\n`);
+      }
+    }
+
     // Render template
     const { content, replacedPlaceholders, unreplacedPlaceholders } = renderTemplate(
       templatePath,
-      variables
+      variables,
+      mcpData
     );
 
     // Dry run: just preview
@@ -300,4 +343,7 @@ function main() {
 }
 
 // Run CLI
-main();
+main().catch(error => {
+  console.error(`${colors.red}❌ Fatal error: ${error.message}${colors.reset}`);
+  process.exit(1);
+});

package/bin/task-manager.cjs

@@ -138,6 +138,9 @@ class TaskManager {
     // Save state
     await this.saveState(state);
 
+    // Auto-generate metadata.json (for quick LLM access)
+    await this.generateMetadata(featureName, feature);
+
     // Display progress
     this.displayProgress(feature);
 
@@ -230,10 +233,40 @@ class TaskManager {
    * Auto-checkpoint every 3 tasks (includes validation summary)
    */
   async autoCheckpoint(feature, tasks, featureName) {
+    const tasksCompleted = feature.tasks?.completed || tasks.length;
+    const checkpointNum = Math.floor(tasksCompleted / 3);
+
+    console.log(chalk.magenta(`\n🔍 CHECKPOINT ${checkpointNum} - Running automated validation...`));
+
+    let checkpointResult = null;
     let validationNote = '';
 
-    // Run validation and include summary in checkpoint
-    if (featureName) {
+    // Run checkpoint hooks (new enhanced validation system)
+    try {
+      const { runCheckpointHooks, shouldRunCheckpoint } = await import('../src/lib/checkpoint-hooks.js');
+
+      if (shouldRunCheckpoint(tasksCompleted, 3)) {
+        checkpointResult = await runCheckpointHooks(featureName, checkpointNum);
+
+        if (checkpointResult.passed) {
+          validationNote = ' | ✓ All validations passed';
+        } else {
+          validationNote = ` | ✗ ${checkpointResult.summary.errors} errors, ${checkpointResult.summary.warnings} warnings`;
+
+          // Check if we should block progress
+          const config = await this.loadCheckpointConfig();
+          if (config.checkpoints?.onFailure?.blockProgress && checkpointResult.summary.errors > 0) {
+            console.log(chalk.red('\n❌ Checkpoint FAILED - Fix violations before proceeding'));
+            throw new Error('Checkpoint validation failed');
+          }
+        }
+      }
+    } catch (error) {
+      if (error.message === 'Checkpoint validation failed') {
+        throw error; // Re-throw to block task completion
+      }
+      // Fallback to old validation if checkpoint-hooks not available
+      console.log(chalk.yellow('⚠️  Checkpoint hooks not available, using legacy validation'));
       try {
         const { runValidation } = await import('../src/lib/validation-runner.js');
         const result = await runValidation('.', featureName, { verbose: false });
@@ -241,23 +274,84 @@ class TaskManager {
           ? ' | Validation: PASSED'
           : ` | Validation: ${result.errors.length} errors, ${result.warnings.length} warnings`;
       } catch {
-        // Validation not available, skip
+        // No validation available
       }
     }
 
+    // Create checkpoint record
     const checkpoint = {
       id: `CHECKPOINT_AUTO_${Date.now()}`,
       timestamp: new Date().toISOString(),
       tasksCompleted: tasks.map(t => t.id),
-      note: `Auto-checkpoint: ${tasks.length} tasks completed${validationNote}`
+      note: `Auto-checkpoint: ${tasks.length} tasks completed${validationNote}`,
+      validationResults: checkpointResult?.results || null
     };
 
     feature.checkpoints = feature.checkpoints || [];
     feature.checkpoints.push(checkpoint);
 
-    console.log(chalk.magenta(`\n🎉 Auto-checkpoint reached! ${tasks.length} tasks completed`));
-    if (validationNote) {
-      console.log(chalk.gray(`   ${validationNote.trim().replace(/^ \| /, '')}`));
+    if (checkpointResult?.passed) {
+      console.log(chalk.green(`\n✅ Checkpoint ${checkpointNum} PASSED`));
+    } else if (checkpointResult) {
+      console.log(chalk.yellow(`\n⚠️  Checkpoint ${checkpointNum} completed with warnings`));
+    } else {
+      console.log(chalk.magenta(`\n🎉 Auto-checkpoint ${checkpointNum} reached!`));
+    }
+  }
+
+  /**
+   * Load checkpoint configuration from llm-interaction.json
+   */
+  async loadCheckpointConfig() {
+    try {
+      const configPath = path.join(process.cwd(), '.morph/config/llm-interaction.json');
+      const content = await fs.readFile(configPath, 'utf-8');
+      return JSON.parse(content);
+    } catch {
+      // Return defaults if config doesn't exist
+      return {
+        checkpoints: {
+          frequency: 3,
+          autoValidate: true,
+          onFailure: {
+            blockProgress: false
+          }
+        }
+      };
+    }
+  }
+
+  /**
+   * Auto-generate metadata.json after task completion
+   */
+  async generateMetadata(featureName, feature) {
+    try {
+      const config = await this.loadCheckpointConfig();
+
+      // Check if auto-generation is enabled
+      if (!config.metadata?.autoGenerate) {
+        return;
+      }
+
+      const { extractFeatureMetadata } = await import('../src/lib/metadata-extractor.js');
+      const metadata = extractFeatureMetadata(feature);
+
+      const outputPath = path.join(
+        process.cwd(),
+        `.morph/project/outputs/${featureName}/metadata.json`
+      );
+
+      // Ensure directory exists
+      const outputDir = path.dirname(outputPath);
+      await fs.mkdir(outputDir, { recursive: true });
+
+      // Write metadata
+      await fs.writeFile(outputPath, JSON.stringify(metadata, null, 2), 'utf-8');
+
+      console.log(chalk.gray(`   📊 Metadata updated: ${path.relative(process.cwd(), outputPath)}`));
+    } catch (error) {
+      // Don't block task completion if metadata generation fails
+      console.log(chalk.yellow(`   ⚠️  Metadata generation failed: ${error.message}`));
     }
   }
 

package/docs/cli-auto-detection.md

@@ -0,0 +1,219 @@
+# CLI Auto Context Detection
+
+The MORPH-SPEC CLI now includes intelligent auto-detection that analyzes your project and automatically generates accurate configuration files.
+
+## Features
+
+- **🤖 LLM-Powered Analysis**: Uses Claude Code's embedded LLM to analyze your project
+- **📊 Multi-Stack Support**: Detects Next.js, Blazor, .NET APIs, monorepos, and more
+- **🔒 Privacy-First**: All data stays local (no external API calls)
+- **🎯 90%+ Accuracy**: Few-shot learning with real project examples
+- **🛡️ Secret Sanitization**: Automatically redacts API keys, passwords, and sensitive data
+- **🧙 Fallback Wizard**: Manual 7-question wizard if auto-detection fails
+
+## Usage
+
+### New Projects
+
+```bash
+# Initialize MORPH with auto-detection
+morph-spec init
+
+# Skip auto-detection (manual config later)
+morph-spec init --skip-detection
+
+# Force wizard mode (skip LLM)
+morph-spec init --wizard
+```
+
+### Existing Projects
+
+```bash
+# Re-analyze and update configs
+morph-spec update
+
+# Skip auto-detection during update
+morph-spec update --skip-detection
+
+# Force wizard mode
+morph-spec update --wizard
+```
+
+## How It Works
+
+### 1. Project Scanning
+
+Scans your project for:
+- `package.json` (dependencies, scripts)
+- `.csproj` and `.sln` files
+- `README.md` and `CLAUDE.md`
+- Directory structure (src/, frontend/, backend/, etc.)
+- Infrastructure files (Dockerfile, *.bicep, CI/CD pipelines)
+- Git remote URL
+
+### 2. Context Sanitization
+
+Removes sensitive data before LLM analysis:
+- **Whitelisted files**: Only reads safe files (package.json, README, etc.)
+- **Blacklisted directories**: Never scans node_modules/, .git/, bin/, obj/
+- **Secret redaction**: Removes API keys, passwords, connection strings
+- **File truncation**: Limits README/CLAUDE.md to first 500 chars
+
+### 3. LLM Analysis
+
+Uses Claude Code's LLM with few-shot learning:
+- 3 example projects (Next.js, Blazor, Monorepo)
+- Structured JSON output
+- Schema validation with Ajv
+- Confidence scoring (0-100%)
+
+### 4. User Review
+
+Interactive preview with options:
+- ✅ **Approve** - Save configs as-is
+- ✏️ **Edit** - Open in $EDITOR before saving
+- ❌ **Cancel** - Abort without changes
+
+Shows diff if updating existing configs.
+
+### 5. Fallback to Wizard
+
+If LLM fails (no Claude Code, timeout, invalid response):
+- Automatically launches 7-question interactive wizard
+- Asks: name, description, type, frontend, backend, database, infrastructure
+- Generates valid config from manual input
+
+## Requirements
+
+- **Claude Code CLI**: Auto-detection requires Claude Code environment
+- **Node.js 18+**: For running the CLI
+- **Git (optional)**: For remote URL detection
+
+## Configuration Files Generated
+
+### `.morph/project.md`
+
+Human-readable project overview:
+- Stack summary table
+- Architecture pattern
+- Code conventions
+- Infrastructure (Azure, Docker, CI/CD)
+- LLM confidence score
+- Warnings (if any)
+
+### `.morph/config/config.json`
+
+Machine-readable config for agents:
+- Project name, type, description
+- Stack (frontend, backend, database, hosting)
+- Architecture pattern
+- Infrastructure flags
+- Generated metadata (timestamp, confidence)
+
+## Supported Project Types
+
+| Type | Detection Criteria | Example |
+|------|-------------------|---------|
+| `nextjs` | package.json has `next` dependency | Next.js app |
+| `blazor-server` | .csproj with Blazor.Server | Blazor Server app |
+| `dotnet-api` | .csproj without Blazor | .NET Web API |
+| `cli-tool` | package.json with `bin` field | CLI tool |
+| `monorepo` | frontend/ and backend/ directories | Full-stack monorepo |
+| `other` | Fallback for unknown projects | Custom setups |
+
+## Troubleshooting
+
+### "Claude Code environment not detected"
+
+Auto-detection requires Claude Code CLI. Options:
+1. Run `morph-spec init --wizard` for manual configuration
+2. Install Claude Code and retry
+3. Use `--skip-detection` to configure later
+
+### "LLM analysis timeout"
+
+Default timeout is 60 seconds for interactive use. If analysis takes too long:
+1. Reduce project size (clean node_modules, dist)
+2. Use `--wizard` for manual configuration
+3. Check Claude Code performance
+
+### "Schema validation failed"
+
+LLM returned invalid JSON. Possible causes:
+- Project structure too complex
+- Missing critical files (no package.json or .csproj)
+- Solution: Use `--wizard` mode
+
+### Configs overwriting customizations
+
+Auto-detection creates backups:
+- `.morph/project.md.YYYY-MM-DDTHH-MM-SS.backup`
+- `.morph/config/config.json.YYYY-MM-DDTHH-MM-SS.backup`
+
+Review diffs before approving updates.
+
+## Edge Cases
+
+| Edge Case | Behavior |
+|-----------|----------|
+| Empty project (no files) | Falls back to wizard |
+| Large project (1000+ files) | Only whitelisted files read |
+| Monorepo with multiple stacks | Detects all stacks, shows in config |
+| No database detected | `stack.database` set to `null` |
+| No frontend detected | `stack.frontend` set to `null` |
+| Git repo without remote | `gitRemote` set to `null` |
+| User cancels (Ctrl+C) | Clean exit, no files modified |
+
+## Privacy & Security
+
+✅ **Local-only processing**: LLM runs in Claude Code (no external API calls)
+✅ **Secret redaction**: 10+ secret patterns detected and removed
+✅ **Whitelist-only reads**: Only safe files are analyzed
+✅ **No telemetry**: No data sent to Anthropic or third parties
+
+## Examples
+
+### Example 1: Next.js + Supabase
+
+**Detected:**
+```json
+{
+  "name": "my-nextjs-app",
+  "type": "nextjs",
+  "stack": {
+    "frontend": { "tech": "Next.js", "version": "15" },
+    "backend": { "tech": "Supabase", "version": "latest" },
+    "database": { "tech": "PostgreSQL", "version": "16" }
+  },
+  "confidence": 95
+}
+```
+
+### Example 2: Blazor + Azure SQL
+
+**Detected:**
+```json
+{
+  "name": "MyApp",
+  "type": "blazor-server",
+  "stack": {
+    "frontend": { "tech": "Blazor", "version": "10" },
+    "backend": { "tech": ".NET", "version": "10" },
+    "database": { "tech": "Azure SQL", "version": "latest" }
+  },
+  "hasAzure": true,
+  "confidence": 98
+}
+```
+
+## Command Flags
+
+| Flag | Description |
+|------|-------------|
+| `--skip-detection` | Skip auto-detection (manual config) |
+| `--wizard` | Force interactive wizard mode |
+| `--force` | Overwrite existing configs without prompt |
+
+---
+
+For more help, see the [Troubleshooting Guide](./troubleshooting.md).