@paths.design/caws-cli 7.0.2 → 8.0.0

package/dist/budget-derivation.js

@@ -196,10 +196,11 @@ async function deriveBudget(spec, projectRoot = process.cwd(), options = {}) {
             '   This may be a path resolution or caching issue\n'
         );
       } else {
-        console.warn(
-          '⚠️  Policy file not found: .caws/policy.yaml\n' +
-            '   Using default policy. Run "caws init" to create policy.yaml'
-        );
+        // Policy.yaml is optional - defaults work fine, so don't warn unnecessarily
+        // Only show info message if user explicitly wants to see it
+        if (options.showPolicyInfo !== false) {
+          // Silent by default - policy.yaml is optional
+        }
       }
     }
 

package/dist/commands/diagnose.js

@@ -240,41 +240,44 @@ async function checkTestFiles() {
  * @returns {Promise<Object>} Check result
  */
 async function checkCAWSTools() {
-  const toolsPath = 'apps/tools/caws';
+  // Check new location first, then legacy location for backward compatibility
+  const toolsPath = '.caws/tools';
+  const legacyToolsPath = 'apps/tools/caws';
 
-  if (!(await fs.pathExists(toolsPath))) {
+  if (!(await fs.pathExists(toolsPath)) && !(await fs.pathExists(legacyToolsPath))) {
     return {
-      passed: false,
-      severity: 'low',
-      message: 'CAWS tools directory not found',
-      fix: 'Scaffold tools: caws scaffold',
+      passed: true,
+      severity: 'info',
+      message: 'CAWS tools directory not found (optional - use CLI commands instead)',
+      fix: 'Core functionality available via: caws validate, caws quality-gates, caws provenance',
       autoFixable: false,
     };
   }
 
-  // Check for essential tools
-  const essentialTools = ['validate.js', 'gates.js', 'provenance.js'];
-  let missingTools = [];
+  // Tools directory exists - check for specialized tools (not core CLI duplicates)
+  const specializedTools = ['flake-detector.ts', 'spec-test-mapper.ts', 'perf-budgets.ts'];
+  const foundTools = [];
 
-  for (const tool of essentialTools) {
-    if (!(await fs.pathExists(path.join(toolsPath, tool)))) {
-      missingTools.push(tool);
+  for (const tool of specializedTools) {
+    if (await fs.pathExists(path.join(toolsPath, tool))) {
+      foundTools.push(tool);
     }
   }
 
-  if (missingTools.length > 0) {
+  if (foundTools.length === 0) {
     return {
-      passed: false,
-      severity: 'medium',
-      message: `Missing ${missingTools.length} essential tools`,
-      fix: 'Re-scaffold tools: caws scaffold --force',
+      passed: true,
+      severity: 'info',
+      message: 'No specialized tools found (optional - use CLI commands for core functionality)',
+      fix: 'Core functionality available via: caws validate, caws quality-gates, caws provenance',
       autoFixable: false,
     };
   }
 
   return {
     passed: true,
-    message: 'All essential CAWS tools present',
+    message: `Found ${foundTools.length} specialized tool(s): ${foundTools.join(', ')}`,
+    note: 'Core functionality (validate, quality-gates, provenance) available via CLI commands',
   };
 }
 
@@ -484,7 +487,9 @@ async function diagnoseCommand(options = {}) {
       console.log(chalk.blue('   • Run: caws status --visual to view project health'));
       console.log(chalk.blue('   • Run: caws validate to check working spec'));
       console.log(chalk.blue('   • Optional: Create .caws/policy.yaml for custom budgets'));
-      console.log(chalk.blue('   • Start implementing: caws iterate --current-state "Ready to begin"'));
+      console.log(
+        chalk.blue('   • Start implementing: caws iterate --current-state "Ready to begin"')
+      );
     }
   } catch (error) {
     console.error(chalk.red('\n❌ Error running diagnosis:'), error.message);

package/dist/commands/init.js

@@ -17,6 +17,7 @@ const { generateWorkingSpec } = require('../generators/working-spec');
 const { finalizeProject } = require('../utils/finalization');
 const { scaffoldCursorHooks } = require('../scaffold/cursor-hooks');
 const { scaffoldIDEIntegrations } = require('../scaffold/index');
+const { updateGitignore } = require('../utils/gitignore-updater');
 
 /**
  * Initialize a new project with CAWS
@@ -361,6 +362,18 @@ async function initProject(projectName, options) {
       await fs.writeFile(path.join('.caws', 'working-spec.yaml'), specContent);
       console.log(chalk.green('✅ Created .caws/working-spec.yaml'));
 
+      // Optionally create policy.yaml (optional - defaults work fine)
+      const policyPath = path.join('.caws', 'policy.yaml');
+      if (!fs.existsSync(policyPath)) {
+        const { PolicyManager } = require('../policy/PolicyManager');
+        const policyManager = new PolicyManager();
+        const defaultPolicy = policyManager.getDefaultPolicy();
+        const yaml = require('js-yaml');
+        const policyContent = yaml.dump(defaultPolicy, { indent: 2 });
+        await fs.writeFile(policyPath, policyContent);
+        console.log(chalk.green('✅ Created .caws/policy.yaml (optional - defaults work fine)'));
+      }
+
       // Generate additional files if requested
       if (answers.generateExamples) {
         console.log(chalk.blue('📝 Generating example files...'));
@@ -409,6 +422,17 @@ Happy coding! 🎯
       console.log(chalk.blue('🎨 Setting up IDE integrations...'));
       await scaffoldIDEIntegrations(process.cwd(), { force: false });
 
+      // Update .gitignore to exclude CAWS local runtime files
+      console.log(chalk.blue('📝 Updating .gitignore...'));
+      const gitignoreUpdated = await updateGitignore(process.cwd());
+      if (gitignoreUpdated) {
+        console.log(chalk.green('✅ Updated .gitignore to exclude CAWS local runtime files'));
+        console.log(
+          chalk.gray('   Tracked: Specs, policy, waivers, provenance, plans (shared with team)')
+        );
+        console.log(chalk.gray('   Ignored: Agent runtime, temp files, logs (local-only)'));
+      }
+
       // Finalize project
       await finalizeProject(projectName, options, answers);
     } else {
@@ -456,7 +480,7 @@ Happy coding! 🎯
         experimentalSandbox: '',
         aiConfidence: 0.8,
         uncertaintyAreas: '',
-        complexityFactors: ''
+        complexityFactors: '',
       };
 
       const specContent = generateWorkingSpec(defaultAnswers);
@@ -464,6 +488,18 @@ Happy coding! 🎯
       await fs.writeFile(path.join('.caws', 'working-spec.yaml'), specContent);
       console.log(chalk.green('✅ Created .caws/working-spec.yaml'));
 
+      // Optionally create policy.yaml (optional - defaults work fine)
+      const policyPath = path.join('.caws', 'policy.yaml');
+      if (!fs.existsSync(policyPath)) {
+        const { PolicyManager } = require('../policy/PolicyManager');
+        const policyManager = new PolicyManager();
+        const defaultPolicy = policyManager.getDefaultPolicy();
+        const yaml = require('js-yaml');
+        const policyContent = yaml.dump(defaultPolicy, { indent: 2 });
+        await fs.writeFile(policyPath, policyContent);
+        console.log(chalk.green('✅ Created .caws/policy.yaml (optional - defaults work fine)'));
+      }
+
       // Setup Cursor hooks by default in non-interactive mode
       console.log(chalk.blue('🎯 Setting up Cursor hooks...'));
       await scaffoldCursorHooks(process.cwd());
@@ -472,6 +508,17 @@ Happy coding! 🎯
       console.log(chalk.blue('🎨 Setting up IDE integrations...'));
       await scaffoldIDEIntegrations(process.cwd(), { force: false });
 
+      // Update .gitignore to exclude CAWS local runtime files
+      console.log(chalk.blue('📝 Updating .gitignore...'));
+      const gitignoreUpdated = await updateGitignore(process.cwd());
+      if (gitignoreUpdated) {
+        console.log(chalk.green('✅ Updated .gitignore to exclude CAWS local runtime files'));
+        console.log(
+          chalk.gray('   Tracked: Specs, policy, waivers, provenance, plans (shared with team)')
+        );
+        console.log(chalk.gray('   Ignored: Agent runtime, temp files, logs (local-only)'));
+      }
+
       // Finalize project
       await finalizeProject(projectName, options, defaultAnswers);
     }
@@ -481,7 +528,7 @@ Happy coding! 🎯
     console.log(chalk.blue('\nNext steps:'));
     console.log('1. Review .caws/working-spec.yaml');
     console.log('2. Customize the specification for your needs');
-    
+
     // Show contract requirements if Tier 1 or 2
     // Use answers if available (interactive mode), otherwise default to 2
     const riskTier = answers?.riskTier || 2;
@@ -495,7 +542,7 @@ Happy coding! 🎯
       console.log(chalk.gray('       description: "Project-level CAWS configuration"'));
       console.log('   Or use "chore" mode for maintenance work (mode: chore)');
     }
-    
+
     console.log('\n📋 Recommended Setup Workflow:');
     console.log('   1. Review .caws/working-spec.yaml');
     console.log('   2. Run: caws scaffold (adds tools and templates)');
@@ -511,7 +558,7 @@ Happy coding! 🎯
     if (error.stack) {
       console.error(chalk.gray(error.stack));
     }
-    
+
     // Cleanup on error (only for new directory creation)
     if (projectName && projectName !== '.' && fs.existsSync(projectName)) {
       try {

package/dist/commands/quality-gates.js

@@ -44,14 +44,66 @@ async function qualityGatesCommand(options = {}) {
       const packagesDir = path.dirname(cliPackageDir);
       const monorepoRunner = path.join(packagesDir, 'quality-gates', 'run-quality-gates.mjs');
 
-      // Option 2: Check VS Code extension bundled (if running from extension context)
+      // Option 2: Check globally installed CLI for bundled quality gates
+      let globalCliPath = null;
+      try {
+        const { execSync } = require('child_process');
+        const whichCaws = execSync('which caws', { encoding: 'utf8', stdio: 'pipe' }).trim();
+        if (whichCaws) {
+          // Resolve symlink to actual path
+          const realPath = fs.realpathSync(whichCaws);
+          const globalCliDir = path.dirname(realPath);
+          // Check for bundled quality gates in global CLI installation
+          const possibleBundledPaths = [
+            path.join(
+              globalCliDir,
+              '..',
+              'lib',
+              'node_modules',
+              '@paths.design',
+              'caws-cli',
+              'node_modules',
+              '@paths.design',
+              'quality-gates',
+              'run-quality-gates.mjs'
+            ),
+            path.join(
+              globalCliDir,
+              '..',
+              'lib',
+              'node_modules',
+              '@paths.design',
+              'quality-gates',
+              'run-quality-gates.mjs'
+            ),
+            path.join(
+              globalCliDir,
+              '..',
+              'node_modules',
+              '@paths.design',
+              'quality-gates',
+              'run-quality-gates.mjs'
+            ),
+          ];
+          for (const bundledPath of possibleBundledPaths) {
+            if (fs.existsSync(bundledPath)) {
+              globalCliPath = bundledPath;
+              break;
+            }
+          }
+        }
+      } catch (e) {
+        // Ignore errors finding global CLI
+      }
+
+      // Option 3: Check VS Code extension bundled (if running from extension context)
       const vscodeExtensionPath =
         process.env.VSCODE_EXTENSION_PATH || process.env.VSCODE_EXTENSION_DIR;
       const bundledRunner = vscodeExtensionPath
         ? path.join(vscodeExtensionPath, 'bundled', 'quality-gates', 'run-quality-gates.mjs')
         : null;
 
-      // Option 3: Check node_modules for quality-gates package (prioritize published package)
+      // Option 4: Check node_modules for quality-gates package (prioritize published package)
       const nodeModulesPaths = [
         // Published npm package (priority)
         path.join(
@@ -69,6 +121,8 @@ async function qualityGatesCommand(options = {}) {
       // Try all possible paths in order
       if (fs.existsSync(monorepoRunner)) {
         qualityGatesRunner = monorepoRunner;
+      } else if (globalCliPath) {
+        qualityGatesRunner = globalCliPath;
       } else if (bundledRunner && fs.existsSync(bundledRunner)) {
         qualityGatesRunner = bundledRunner;
       } else {
@@ -132,14 +186,98 @@ async function qualityGatesCommand(options = {}) {
         }
       }
 
-      // If still no runner found, provide helpful error
+      // Option 5: Try npx (no installation required) - works if Node.js is available
       if (!qualityGatesRunner) {
-        const suggestions = [
-          'Install quality gates package: npm install -g @paths.design/quality-gates',
-          'Use Python script (if available): python3 scripts/simple_gates.py all --tier 2 --profile backend-api',
-          'Use Makefile target (if available): make caws-gates',
-          'Run from CAWS monorepo root',
-        ];
+        try {
+          const { execSync } = require('child_process');
+          // Check if npx is available
+          execSync('command -v npx', { encoding: 'utf8', stdio: 'ignore' });
+
+          Output.info('Using npx to run quality gates (no installation required)...');
+
+          // Build npx command - the package exposes 'caws-quality-gates' bin command
+          // Use npx to download and run without installing
+          const npxArgs = ['npx', '--yes', '@paths.design/quality-gates'];
+
+          // Map CLI options to runner options
+          if (options.ci) {
+            npxArgs.push('--ci');
+          }
+          if (options.json) {
+            npxArgs.push('--json');
+          }
+          if (options.gates && options.gates.trim()) {
+            npxArgs.push('--gates', options.gates.trim());
+          }
+          if (options.fix) {
+            npxArgs.push('--fix');
+          }
+
+          Output.progress('Executing quality gates via npx...');
+          Output.info(`Command: ${npxArgs.join(' ')}`);
+
+          // Execute via npx
+          const { execSync: execSyncNpx } = require('child_process');
+          execSyncNpx(npxArgs.join(' '), {
+            stdio: 'inherit',
+            cwd: projectRoot,
+            env: {
+              ...process.env,
+              CAWS_CLI_INTEGRATION: 'true',
+              CAWS_CLI_VERSION: require(path.join(cliPackageDir, 'package.json')).version,
+            },
+          });
+
+          Output.success('Quality gates completed successfully');
+          return;
+        } catch (npxError) {
+          // npx not available or failed - continue to error message
+        }
+      }
+
+      // If still no runner found, provide helpful error with language-agnostic suggestions
+      if (!qualityGatesRunner) {
+        // Check if Node.js/npx is available (language-agnostic check)
+        let hasNodeJs = false;
+        try {
+          const { execSync } = require('child_process');
+          execSync('command -v node', { encoding: 'utf8', stdio: 'ignore' });
+          execSync('command -v npx', { encoding: 'utf8', stdio: 'ignore' });
+          hasNodeJs = true;
+        } catch (e) {
+          // Node.js/npx not available
+        }
+
+        const suggestions = [];
+
+        if (hasNodeJs) {
+          // Node.js available - suggest npx (works for any language, no installation)
+          suggestions.push(
+            'Use npx (no installation required): npx --yes @paths.design/quality-gates'
+          );
+          suggestions.push('Install globally: npm install -g @paths.design/quality-gates');
+          suggestions.push('Install locally: npm install --save-dev @paths.design/quality-gates');
+        } else {
+          // Node.js not available - suggest installation or alternatives
+          suggestions.push('Install Node.js to use quality gates: https://nodejs.org/');
+          suggestions.push(
+            'Then use: npx --yes @paths.design/quality-gates (no installation required)'
+          );
+          suggestions.push('Or install globally: npm install -g @paths.design/quality-gates');
+        }
+
+        // Language-agnostic fallback options (if they exist)
+        const pythonScript = path.join(projectRoot, 'scripts', 'simple_gates.py');
+        const makefile = path.join(projectRoot, 'Makefile');
+
+        if (fs.existsSync(pythonScript)) {
+          suggestions.push(`Use project script: python3 ${pythonScript} all --tier 2`);
+        }
+        if (fs.existsSync(makefile)) {
+          suggestions.push('Use Makefile target: make caws-gates');
+        }
+
+        suggestions.push('Run from CAWS monorepo root (if developing CAWS itself)');
 
         throw new Error(
           'Quality gates runner not found.\n\n' +

package/dist/commands/specs.js

@@ -154,9 +154,13 @@ async function createSpec(id, options = {}) {
         console.log(chalk.blue('ℹ️  Spec creation canceled.'));
         return null;
       } else if (answer === 'rename') {
-        // Generate new name with timestamp suffix
-        const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, -5);
-        const newId = `${id}-${timestamp}`;
+        // Generate new name with valid PREFIX-NUMBER format
+        // Extract prefix from existing ID or use default
+        const prefixMatch = id.match(/^([A-Z]+)-\d+$/);
+        const prefix = prefixMatch ? prefixMatch[1] : 'FEAT';
+        // Generate sequential number based on timestamp
+        const number = Date.now().toString().slice(-6); // Last 6 digits of timestamp
+        const newId = `${prefix}-${number}`;
         console.log(chalk.blue(`📝 Creating spec with new name: ${newId}`));
         return await createSpec(newId, { ...options, interactive: false });
       } else if (answer === 'merge') {
@@ -183,9 +187,10 @@ async function createSpec(id, options = {}) {
   // Ensure specs directory exists
   await fs.ensureDir(SPECS_DIR);
 
-  // Generate spec content
-  const specContent = {
-    id,
+  // Generate spec content with all required fields
+  // Merge template carefully to preserve required fields and structure
+  const defaultSpec = {
+    id, // Always use the provided id parameter
     type,
     title,
     status: 'draft',
@@ -193,8 +198,64 @@ async function createSpec(id, options = {}) {
     mode,
     created_at: new Date().toISOString(),
     updated_at: new Date().toISOString(),
-    acceptance_criteria: [],
+    // Required fields for validation
+    blast_radius: {
+      modules: [],
+      data_migration: false,
+    },
+    operational_rollback_slo: '5m',
+    scope: {
+      in: ['src/', 'tests/'],
+      out: ['node_modules/', 'dist/', 'build/'],
+    },
+    invariants: ['System maintains data consistency'],
+    acceptance: [], // Note: validation expects 'acceptance', not 'acceptance_criteria'
+    acceptance_criteria: [], // Keep for backward compatibility
+    non_functional: {
+      a11y: [],
+      perf: {},
+      security: [],
+    },
+    contracts: [],
+  };
+
+  // Merge template, but preserve required structure
+  // Map template.criteria to acceptance if present
+  const templateAcceptance = template?.criteria || template?.acceptance;
+
+  const specContent = {
+    ...defaultSpec,
     ...(template || {}),
+    // Always preserve these critical fields
+    id, // Never allow template to override id
+    // Map criteria to acceptance if template uses criteria
+    acceptance: templateAcceptance || defaultSpec.acceptance,
+    acceptance_criteria: templateAcceptance || defaultSpec.acceptance_criteria,
+    // Deep merge scope if template provides it
+    scope: template?.scope
+      ? {
+          in: template.scope.in || defaultSpec.scope.in,
+          out: template.scope.out || defaultSpec.scope.out,
+        }
+      : defaultSpec.scope,
+    // Deep merge blast_radius if template provides it
+    blast_radius: template?.blast_radius
+      ? {
+          modules: template.blast_radius.modules || defaultSpec.blast_radius.modules,
+          data_migration:
+            template.blast_radius.data_migration !== undefined
+              ? template.blast_radius.data_migration
+              : defaultSpec.blast_radius.data_migration,
+        }
+      : defaultSpec.blast_radius,
+    // Deep merge non_functional if template provides it
+    non_functional: template?.non_functional
+      ? {
+          a11y: template.non_functional.a11y || defaultSpec.non_functional.a11y,
+          perf: template.non_functional.perf || defaultSpec.non_functional.perf,
+          security: template.non_functional.security || defaultSpec.non_functional.security,
+        }
+      : defaultSpec.non_functional,
   };
 
   // Create file path
@@ -202,7 +263,46 @@ async function createSpec(id, options = {}) {
   const filePath = path.join(SPECS_DIR, fileName);
 
   // Write spec file
-  await fs.writeFile(filePath, yaml.dump(specContent, { indent: 2 }));
+  const yamlContent = yaml.dump(specContent, { indent: 2 });
+  await fs.writeFile(filePath, yamlContent);
+
+  // Validate written file (YAML syntax and structure)
+  try {
+    const writtenContent = await fs.readFile(filePath, 'utf8');
+    const parsed = yaml.load(writtenContent);
+
+    // Validate YAML syntax was preserved
+    if (!parsed || typeof parsed !== 'object') {
+      await fs.remove(filePath);
+      throw new Error('Failed to parse written spec file - invalid YAML structure');
+    }
+
+    // Validate spec structure using CAWS validation
+    const { validateWorkingSpec } = require('../validation/spec-validation');
+    const validation = validateWorkingSpec(parsed);
+
+    if (!validation.valid) {
+      await fs.remove(filePath);
+      const errorMessages = validation.errors
+        .map((e) => `${e.instancePath}: ${e.message}`)
+        .join('; ');
+      throw new Error(`Spec validation failed: ${errorMessages}`);
+    }
+  } catch (error) {
+    // Clean up invalid file if it exists
+    if (await fs.pathExists(filePath)) {
+      await fs.remove(filePath);
+    }
+
+    // Re-throw with helpful message
+    if (error.message.includes('YAMLException') || error.message.includes('yaml')) {
+      throw new Error(
+        `Failed to create valid spec: YAML syntax error. ${error.message}\n` +
+          '💡 Consider using the interactive mode: caws specs create <id> --interactive'
+      );
+    }
+    throw error;
+  }
 
   // Update registry
   const registry = await loadSpecsRegistry();
@@ -403,9 +503,10 @@ function displaySpecDetails(spec) {
 /**
  * Migrate from legacy working-spec.yaml to feature-specific specs
  * @param {Object} options - Migration options
+ * @param {Function} [createSpecFn] - Function to create specs (for testing)
  * @returns {Promise<Object>} Migration result
  */
-async function migrateFromLegacy(options = {}) {
+async function migrateFromLegacy(options = {}, createSpecFn = createSpec) {
   const fs = require('fs-extra');
   const path = require('path');
   const yaml = require('js-yaml');
@@ -422,6 +523,14 @@ async function migrateFromLegacy(options = {}) {
   const legacyContent = await fs.readFile(legacyPath, 'utf8');
   const legacySpec = yaml.load(legacyContent);
 
+  if (!legacySpec) {
+    throw new Error('Legacy working-spec.yaml is empty or invalid');
+  }
+
+  if (!legacySpec.acceptance || !Array.isArray(legacySpec.acceptance)) {
+    throw new Error('Legacy working-spec.yaml must have an acceptance array');
+  }
+
   // Suggest feature breakdown based on acceptance criteria
   const features = suggestFeatureBreakdown(legacySpec);
 
@@ -441,15 +550,32 @@ async function migrateFromLegacy(options = {}) {
   }
 
   if (options.features && options.features.length > 0) {
+    // Filter by original feature IDs (before transformation)
     selectedFeatures = features.filter((f) => options.features.includes(f.id));
-    console.log(chalk.blue(`\n📋 Migrating selected features: ${options.features.join(', ')}`));
+    if (selectedFeatures.length === 0) {
+      const errorMsg = `No features found matching: ${options.features.join(', ')}. Available features: ${features.map((f) => f.id).join(', ')}`;
+      console.log(chalk.yellow(`⚠️  ${errorMsg}`));
+      throw new Error(errorMsg);
+    } else {
+      console.log(chalk.blue(`\n📋 Migrating selected features: ${options.features.join(', ')}`));
+    }
   }
 
   // Create each feature spec
   const createdSpecs = [];
+  let featureCounter = 1;
   for (const feature of selectedFeatures) {
     try {
-      await createSpec(feature.id, {
+      // Transform feature ID to proper format (PREFIX-NUMBER) if needed
+      let specId = feature.id;
+      if (!/^[A-Z]+-\d+$/.test(specId)) {
+        // Convert 'auth' -> 'FEAT-001', 'payment' -> 'FEAT-002', etc.
+        const prefix = specId.toUpperCase().replace(/[^A-Z0-9]/g, '');
+        specId = `${prefix || 'FEAT'}-${String(featureCounter).padStart(3, '0')}`;
+        featureCounter++;
+      }
+
+      await createSpecFn(specId, {
         type: 'feature',
         title: feature.title,
         risk_tier: 'T3', // Default tier
@@ -457,10 +583,14 @@ async function migrateFromLegacy(options = {}) {
         template: feature,
       });
 
-      createdSpecs.push(feature.id);
-      console.log(chalk.green(`   ✅ Created spec: ${feature.id}`));
+      createdSpecs.push(specId);
+      console.log(chalk.green(`   ✅ Created spec: ${specId}`));
     } catch (error) {
+      // Log full error details for debugging
       console.log(chalk.red(`   ❌ Failed to create spec ${feature.id}: ${error.message}`));
+      if (process.env.DEBUG_MIGRATION) {
+        console.log(chalk.gray(`   Error details: ${error.stack}`));
+      }
     }
   }
 
@@ -589,7 +719,11 @@ async function specsCommand(action, options = {}) {
         }
 
         case 'migrate': {
-          const result = await migrateFromLegacy(options);
+          // Allow tests to inject createSpec function
+          const createSpecFn = options._createSpecFn || createSpec;
+          const migrationOptions = { ...options };
+          delete migrationOptions._createSpecFn; // Remove test-only option
+          const result = await migrateFromLegacy(migrationOptions, createSpecFn);
 
           return outputResult({
             command: 'specs migrate',

package/dist/commands/status.js

@@ -182,10 +182,10 @@ async function loadWaiverStatus() {
  */
 async function checkQualityGates() {
   // For now, return a placeholder
-  // In full implementation, this would run actual gate checks
+  // Quality gates are available via CLI or MCP
   return {
     checked: false,
-    message: 'Run: node apps/tools/caws/gates.js for full gate status',
+    message: 'Run: caws quality-gates or use MCP tool caws_quality_gates_run for full gate status',
   };
 }
 

package/dist/commands/tool.js

@@ -4,7 +4,6 @@
  * @author @darianrosebrook
  */
 
-const path = require('path');
 const { commandWrapper, Output } = require('../utils/command-wrapper');
 
 // Import tool system
@@ -23,9 +22,8 @@ async function initializeToolSystem() {
   if (toolLoader) return toolLoader;
 
   try {
-    toolLoader = new ToolLoader({
-      toolsDir: path.join(process.cwd(), 'apps/tools/caws'),
-    });
+    // ToolLoader now checks .caws/tools first, then falls back to legacy location
+    toolLoader = new ToolLoader();
 
     toolValidator = new ToolValidator();