@paths.design/caws-cli 7.0.2 → 7.0.3

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/specs.js

@@ -202,7 +202,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();

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

@@ -23,9 +23,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();
 

package/dist/config/index.js

@@ -49,15 +49,19 @@ function initializeGlobalSetup() {
 function loadProvenanceTools() {
   if (provenanceTools) return provenanceTools; // Already loaded
 
-  // Try multiple possible locations for provenance tools
+  // Provenance tools are now handled by CLI command (caws provenance)
+  // Legacy tool loading removed - use CLI instead
+  // Try multiple possible locations for provenance tools (legacy support)
   const possiblePaths = [
-    // 1. Bundled templates in CLI package (for global installs)
-    path.join(__dirname, '../../templates/apps/tools/caws/provenance.js'),
-    // 2. Local project templates
+    // 1. New location (if someone manually adds it)
+    path.join(process.cwd(), '.caws/tools/provenance.js'),
+    // 2. Legacy location (for backward compatibility)
     path.join(process.cwd(), 'apps/tools/caws/provenance.js'),
-    // 3. Template package in monorepo
+    // 3. Bundled templates in CLI package (legacy)
+    path.join(__dirname, '../../templates/.caws/tools/provenance.js'),
+    // 4. Template package in monorepo (legacy)
     path.join(__dirname, '../../../caws-template/apps/tools/caws/provenance.js'),
-    // 4. Detected setup template directory
+    // 5. Detected setup template directory
     null, // Will be set from setup if available
   ];
 
@@ -65,7 +69,7 @@ function loadProvenanceTools() {
   try {
     const setup = cawsSetup || initializeGlobalSetup();
     if (setup?.hasTemplateDir && setup?.templateDir) {
-      possiblePaths[3] = path.join(setup.templateDir, 'apps/tools/caws/provenance.js');
+      possiblePaths[4] = path.join(setup.templateDir, '.caws/tools/provenance.js');
     }
   } catch (setupError) {
     // Continue without detected setup
@@ -97,8 +101,13 @@ function initializeLanguageSupport() {
   if (languageSupport) return languageSupport;
 
   try {
-    // Try multiple possible locations for language support
+    // Language support tools removed - use CLI instead
+    // Try multiple possible locations for language support (legacy support)
     const possiblePaths = [
+      // New location (if someone manually adds it)
+      path.join(process.cwd(), '.caws/tools/language-support.js'),
+      // Legacy locations
+      path.join(process.cwd(), 'apps/tools/caws/language-support.js'),
       path.join(__dirname, '../../../caws-template/apps/tools/caws/language-support.js'),
       path.join(__dirname, '../../../../caws-template/apps/tools/caws/language-support.js'),
       path.join(process.cwd(), 'packages/caws-template/apps/tools/caws/language-support.js'),

package/dist/generators/working-spec.js

@@ -42,16 +42,28 @@ function generateWorkingSpec(answers) {
         .split(',')
         .map((s) => s.trim())
         .filter((s) => s),
-      out: (answers.scopeOut || 'node_modules/, dist/')
+      out: (answers.scopeOut || 'node_modules/, dist/, build/')
         .split(',')
         .map((s) => s.trim())
-        .filter((s) => s),
+        .filter((s) => s)
+        // Remove glob patterns - scope.out should only contain directory paths
+        .filter((s) => !s.includes('*') && !s.includes('?'))
+        // Ensure paths end with / for directories or are explicit file paths
+        .map((s) => {
+          // If it's a directory pattern without trailing slash, add it
+          if (!s.includes('.') && !s.endsWith('/')) {
+            return s + '/';
+          }
+          return s;
+        }),
     },
     invariants: (answers.projectInvariants || 'System maintains data consistency')
       .split('\n')
       .map((i) => i.trim())
       .filter((i) => i),
-    acceptance: (answers.acceptanceCriteria || 'Given current state, when action occurs, then expected result')
+    acceptance: (
+      answers.acceptanceCriteria || 'Given current state, when action occurs, then expected result'
+    )
       .split('\n')
       .filter((a) => a.trim())
       .map((criteria, index) => {
@@ -107,7 +119,7 @@ function generateWorkingSpec(answers) {
           },
         ];
       }
-      
+
       // For Tier 1 & 2, provide minimal project_setup contract if none specified
       const riskTier = answers.riskTier || 2;
       if (riskTier === 1 || riskTier === 2) {
@@ -115,11 +127,12 @@ function generateWorkingSpec(answers) {
           {
             type: 'project_setup',
             path: '.caws/working-spec.yaml',
-            description: 'Project-level CAWS configuration. Feature-specific contracts will be added as features are developed.',
+            description:
+              'Project-level CAWS configuration. Feature-specific contracts will be added as features are developed.',
           },
         ];
       }
-      
+
       // Tier 3 doesn't require contracts
       return [];
     })(),

package/dist/scaffold/git-hooks.js

@@ -138,6 +138,100 @@ if [ ! -d ".caws" ]; then
   exit 0
 fi
 
+# Check for git locks before proceeding
+if [ -f ".git/index.lock" ]; then
+  LOCK_AGE=$(($(date +%s) - $(stat -f %m .git/index.lock 2>/dev/null || stat -c %Y .git/index.lock 2>/dev/null || echo 0)))
+  LOCK_AGE_MINUTES=$((LOCK_AGE / 60))
+  
+  if [ $LOCK_AGE_MINUTES -gt 5 ]; then
+    echo "⚠️  Stale git lock detected (${LOCK_AGE_MINUTES} minutes old)"
+    echo "💡 This may indicate a crashed git process"
+    echo "💡 Remove stale lock: rm .git/index.lock"
+    echo "⚠️  Warning: Check for running git/editor processes before removing"
+    exit 1
+  else
+    echo "⚠️  Git lock detected (${LOCK_AGE_MINUTES} minutes old)"
+    echo "💡 Another git process may be running"
+    echo "💡 Wait for the other process to complete, or check for running processes"
+    exit 1
+  fi
+fi
+
+# Validate YAML syntax for all CAWS spec files
+echo "🔍 Validating YAML syntax for CAWS spec files..."
+YAML_VALIDATION_FAILED=false
+
+# Find all staged .yaml/.yml files in .caws directory
+STAGED_YAML_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.caws/.*\.(yaml|yml)$' || true)
+
+if [ -n "$STAGED_YAML_FILES" ]; then
+  # Use Node.js to validate YAML if available
+  if command -v node >/dev/null 2>&1; then
+    # Try to use CAWS CLI for validation
+    if command -v caws >/dev/null 2>&1; then
+      for file in $STAGED_YAML_FILES; do
+        if [ -f "$file" ]; then
+          # Use Node.js to validate YAML syntax
+          if ! node -e "
+            const yaml = require('js-yaml');
+            const fs = require('fs');
+            try {
+              const content = fs.readFileSync('$file', 'utf8');
+              yaml.load(content);
+              process.exit(0);
+            } catch (error) {
+              console.error('❌ Invalid YAML in $file');
+              console.error('   Error:', error.message);
+              if (error.mark) {
+                console.error('   Line:', error.mark.line + 1, 'Column:', error.mark.column + 1);
+                if (error.mark.snippet) console.error('   ' + error.mark.snippet);
+              }
+              process.exit(1);
+            }
+          " 2>&1; then
+            YAML_VALIDATION_FAILED=true
+          fi
+        fi
+      done
+    else
+      # Fallback: use node directly with js-yaml
+      for file in $STAGED_YAML_FILES; do
+        if [ -f "$file" ]; then
+          if ! node -e "
+            const yaml = require('js-yaml');
+            const fs = require('fs');
+            try {
+              const content = fs.readFileSync('$file', 'utf8');
+              yaml.load(content);
+              process.exit(0);
+            } catch (error) {
+              console.error('❌ Invalid YAML in $file');
+              console.error('   Error:', error.message);
+              if (error.mark) {
+                console.error('   Line:', error.mark.line + 1, 'Column:', error.mark.column + 1);
+                if (error.mark.snippet) console.error('   ' + error.mark.snippet);
+              }
+              process.exit(1);
+            }
+          " 2>&1; then
+            YAML_VALIDATION_FAILED=true
+          fi
+        fi
+      done
+    fi
+  else
+    echo "⚠️  Node.js not available - skipping YAML validation"
+    echo "💡 Install Node.js to enable YAML syntax validation"
+  fi
+fi
+
+if [ "$YAML_VALIDATION_FAILED" = true ]; then
+  echo "❌ YAML syntax validation failed - commit blocked"
+  echo "💡 Fix YAML syntax errors above before committing"
+  echo "💡 Consider using 'caws specs create <id>' instead of manual creation"
+  exit 1
+fi
+
 # Fallback chain for quality gates:
 # 1. Try Node.js script (if exists)
 # 2. Try CAWS CLI
@@ -231,38 +325,41 @@ fi
 # Run hidden TODO analysis on staged files only (if available)
 if [ "$QUALITY_GATES_RAN" = true ]; then
   echo "🔍 Checking for hidden TODOs in staged files..."
-  # Try quality gates package TODO analyzer first (published package)
+  
+  # Find TODO analyzer .mjs file (preferred - no Python dependency)
+  TODO_ANALYZER=""
+  
+  # Try quality gates package TODO analyzer (published package)
   if [ -f "node_modules/@paths.design/quality-gates/todo-analyzer.mjs" ]; then
-    if command -v node >/dev/null 2>&1; then
-      if node node_modules/@paths.design/quality-gates/todo-analyzer.mjs --staged-only --ci-mode --min-confidence 0.8 >/dev/null 2>&1; then
-        echo "✅ No critical hidden TODOs found in staged files"
-      else
-        echo "❌ Critical hidden TODOs detected in staged files - commit blocked"
-        echo "💡 Fix stub implementations and placeholder code before committing"
-        echo "📖 See docs/PLACEHOLDER-DETECTION-GUIDE.md for classification"
-        echo ""
-        echo "🔍 Running detailed analysis on staged files..."
-        node node_modules/@paths.design/quality-gates/todo-analyzer.mjs --staged-only --min-confidence 0.8
-        exit 1
-      fi
-    fi
+    TODO_ANALYZER="node_modules/@paths.design/quality-gates/todo-analyzer.mjs"
   # Try quality gates package TODO analyzer (monorepo/local copy)
   elif [ -f "node_modules/@caws/quality-gates/todo-analyzer.mjs" ]; then
-    if command -v node >/dev/null 2>&1; then
-      if node node_modules/@caws/quality-gates/todo-analyzer.mjs --staged-only --ci-mode --min-confidence 0.8 >/dev/null 2>&1; then
-        echo "✅ No critical hidden TODOs found in staged files"
-      else
-        echo "❌ Critical hidden TODOs detected in staged files - commit blocked"
-        echo "💡 Fix stub implementations and placeholder code before committing"
-        echo "📖 See docs/PLACEHOLDER-DETECTION-GUIDE.md for classification"
-        echo ""
-        echo "🔍 Running detailed analysis on staged files..."
-        node node_modules/@caws/quality-gates/todo-analyzer.mjs --staged-only --min-confidence 0.8
-        exit 1
-      fi
+    TODO_ANALYZER="node_modules/@caws/quality-gates/todo-analyzer.mjs"
+  # Try monorepo structure (development)
+  elif [ -f "packages/quality-gates/todo-analyzer.mjs" ]; then
+    TODO_ANALYZER="packages/quality-gates/todo-analyzer.mjs"
+  # Try local copy in scripts directory (if scaffolded)
+  elif [ -f "scripts/todo-analyzer.mjs" ]; then
+    TODO_ANALYZER="scripts/todo-analyzer.mjs"
+  fi
+  
+  # Run TODO analyzer if found
+  if [ -n "$TODO_ANALYZER" ] && command -v node >/dev/null 2>&1; then
+    if node "$TODO_ANALYZER" --staged-only --ci-mode --min-confidence 0.8 >/dev/null 2>&1; then
+      echo "✅ No critical hidden TODOs found in staged files"
+    else
+      echo "❌ Critical hidden TODOs detected in staged files - commit blocked"
+      echo "💡 Fix stub implementations and placeholder code before committing"
+      echo "📖 See docs/PLACEHOLDER-DETECTION-GUIDE.md for classification"
+      echo ""
+      echo "🔍 Running detailed analysis on staged files..."
+      node "$TODO_ANALYZER" --staged-only --min-confidence 0.8
+      exit 1
     fi
-  # Fallback to legacy Python analyzer
+  # Fallback to legacy Python analyzer (deprecated - will be removed)
   elif command -v python3 >/dev/null 2>&1 && [ -f "scripts/v3/analysis/todo_analyzer.py" ]; then
+    echo "⚠️  Using legacy Python TODO analyzer (deprecated)"
+    echo "💡 Install @paths.design/quality-gates for Node.js version: npm install --save-dev @paths.design/quality-gates"
     if python3 scripts/v3/analysis/todo_analyzer.py --staged-only --ci-mode --min-confidence 0.8 >/dev/null 2>&1; then
       echo "✅ No critical hidden TODOs found in staged files"
     else
@@ -274,8 +371,9 @@ if [ "$QUALITY_GATES_RAN" = true ]; then
       python3 scripts/v3/analysis/todo_analyzer.py --staged-only --min-confidence 0.8
       exit 1
     fi
-  elif command -v python3 >/dev/null 2>&1; then
-    echo "⚠️  Python3 found but TODO analyzer not available - skipping"
+  else
+    echo "⚠️  TODO analyzer not available - skipping hidden TODO check"
+    echo "💡 Install @paths.design/quality-gates for TODO analysis: npm install --save-dev @paths.design/quality-gates"
   fi
 fi