@paths.design/caws-cli 7.0.3 → 8.0.0

package/dist/scaffold/git-hooks.js

@@ -6,6 +6,7 @@
 
 const fs = require('fs-extra');
 const path = require('path');
+const { getTodoAnalyzerSuggestion } = require('../utils/project-analysis');
 
 /**
  * Scaffold git hooks for CAWS provenance tracking
@@ -39,7 +40,7 @@ async function scaffoldGitHooks(projectDir, options = {}) {
       name: 'pre-commit',
       description: 'Pre-commit validation and quality checks',
       enabled: validation || qualityGates,
-      content: generatePreCommitHook({ validation, qualityGates }),
+      content: generatePreCommitHook({ validation, qualityGates, projectDir }),
     },
     {
       name: 'post-commit',
@@ -120,7 +121,10 @@ async function scaffoldGitHooks(projectDir, options = {}) {
  * Implements fallback chain: Node script → CLI → Python scripts → Skip gracefully
  */
 function generatePreCommitHook(options) {
-  const { qualityGates = true, stagedOnly = true } = options;
+  const { qualityGates = true, stagedOnly = true, projectDir = process.cwd() } = options;
+
+  // Get language-agnostic suggestions based on runtime availability
+  const todoSuggestion = getTodoAnalyzerSuggestion(projectDir);
 
   return `#!/bin/bash
 # CAWS Pre-commit Hook
@@ -144,13 +148,13 @@ if [ -f ".git/index.lock" ]; then
   LOCK_AGE_MINUTES=$((LOCK_AGE / 60))
   
   if [ $LOCK_AGE_MINUTES -gt 5 ]; then
-    echo "⚠️  Stale git lock detected (${LOCK_AGE_MINUTES} minutes old)"
+    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 "⚠️  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
@@ -162,7 +166,7 @@ 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)
+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
@@ -326,42 +330,49 @@ fi
 if [ "$QUALITY_GATES_RAN" = true ]; then
   echo "🔍 Checking for hidden TODOs in staged files..."
   
-  # Find TODO analyzer .mjs file (preferred - no Python dependency)
-  TODO_ANALYZER=""
+  TODO_CHECK_RAN=false
   
-  # Try quality gates package TODO analyzer (published package)
-  if [ -f "node_modules/@paths.design/quality-gates/todo-analyzer.mjs" ]; then
-    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
-    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"
+  # Option 1: Find TODO analyzer .mjs file (if installed locally)
+  if [ "$TODO_CHECK_RAN" = false ]; then
+    TODO_ANALYZER=""
+    
+    # Try quality gates package TODO analyzer (published package)
+    if [ -f "node_modules/@paths.design/quality-gates/todo-analyzer.mjs" ]; then
+      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
+      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"
+        TODO_CHECK_RAN=true
+      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
+    fi
   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 (deprecated - will be removed)
-  elif command -v python3 >/dev/null 2>&1 && [ -f "scripts/v3/analysis/todo_analyzer.py" ]; then
+  # Option 2: Fallback to legacy Python analyzer (deprecated - will be removed)
+  if [ "$TODO_CHECK_RAN" = false ] && 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"
+      TODO_CHECK_RAN=true
     else
       echo "❌ Critical hidden TODOs detected in staged files - commit blocked"
       echo "💡 Fix stub implementations and placeholder code before committing"
@@ -371,9 +382,16 @@ if [ "$QUALITY_GATES_RAN" = true ]; then
       python3 scripts/v3/analysis/todo_analyzer.py --staged-only --min-confidence 0.8
       exit 1
     fi
-  else
+  fi
+  
+  # Option 3: No analyzer available - show language-aware suggestions
+  if [ "$TODO_CHECK_RAN" = false ]; then
     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"
+    echo "💡 Available options for TODO analysis:"
+${todoSuggestion
+  .split('\n')
+  .map((line) => `    echo "${line.replace(/"/g, '\\"')}"`)
+  .join('\n')}
   fi
 fi
 
@@ -444,8 +462,8 @@ for arg in "$@"; do
     echo "💡 To fix issues locally:"
     echo "   1. Run: caws validate"
     echo "   2. Fix reported issues"
-    echo "   3. Commit fixes: git commit --no-verify (allowed)"
-    echo "   4. Push again: git push (no --no-verify)"
+    echo "   3. Commit fixes: git commit --no-verify \\(allowed\\)"
+    echo "   4. Push again: git push \\(no --no-verify\\)"
     exit 1
   fi
 done
@@ -508,13 +526,13 @@ if command -v caws >/dev/null 2>&1; then
       echo "   No active waivers found"
       echo ""
       echo "💡 If this is infrastructure/setup work, you can create a waiver:"
-      echo "   caws waivers create \\"
-      echo "     --title='Initial CAWS setup' \\"
-      echo "     --reason=infrastructure_limitation \\"
-      echo "     --gates=contracts \\"
-      echo "     --expires-at='2024-12-31T23:59:59Z' \\"
-      echo "     --approved-by='@your-team' \\"
-      echo "     --impact-level=low \\"
+      echo "   caws waivers create \\\\"
+      echo "     --title='Initial CAWS setup' \\\\"
+      echo "     --reason=infrastructure_limitation \\\\"
+      echo "     --gates=contracts \\\\"
+      echo "     --expires-at='2024-12-31T23:59:59Z' \\\\"
+      echo "     --approved-by='@your-team' \\\\"
+      echo "     --impact-level=low \\\\"
       echo "     --mitigation-plan='Contracts will be added as features are developed'"
     fi
     
@@ -523,43 +541,121 @@ if command -v caws >/dev/null 2>&1; then
     echo "Next Steps:"
     echo "   1. Review errors above"
     echo "   2. Fix issues in .caws/working-spec.yaml"
-    echo "   3. Run: caws validate (to verify fixes)"
-    echo "   4. Commit fixes: git commit --no-verify (allowed)"
+    echo "   3. Run: caws validate \\(to verify fixes\\)"
+    echo "   4. Commit fixes: git commit --no-verify \\(allowed\\)"
     echo "   5. Push again: git push"
     echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
     exit 1
   fi
 fi
 
-# Run security checks
+# Run full pre-push checks (full test suite required before push)
+# Note: Pre-commit uses filtered tests for speed, but push requires full suite
+echo ""
+echo "⚡ Running full pre-push checks (full test suite required)..."
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+QUICK_CHECKS_FAILED=false
+
+# 1. Linting (fast)
+if [ -f "package.json" ]; then
+  if command -v npm >/dev/null 2>&1; then
+    if grep -q '"lint"' package.json; then
+      echo "🔍 Running linting..."
+      if npm run lint >/dev/null 2>&1; then
+        echo "✅ Linting passed"
+      else
+        echo "❌ Linting failed"
+        echo "💡 Fix lint errors: npm run lint"
+        QUICK_CHECKS_FAILED=true
+      fi
+    fi
+  fi
+fi
+
+# 2. Type checking (fast for TypeScript/JavaScript)
+if [ -f "package.json" ]; then
+  if command -v npm >/dev/null 2>&1; then
+    if grep -q '"typecheck"' package.json; then
+      echo "🔍 Running type checking..."
+      if npm run typecheck >/dev/null 2>&1; then
+        echo "✅ Type checking passed"
+      else
+        echo "❌ Type checking failed"
+        echo "💡 Fix type errors: npm run typecheck"
+        QUICK_CHECKS_FAILED=true
+      fi
+    fi
+  fi
+fi
+
+# 3. Run FULL test suite (required for push) - no filtering
+# Pre-commit uses filtered tests for speed, but push requires full suite
+if [ -f "package.json" ]; then
+  if command -v npm >/dev/null 2>&1 && grep -q '"test"' package.json; then
+    echo "🧪 Running FULL test suite (required for push)..."
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    if npm test 2>&1 | tee /tmp/pre-push-test-full.log; then
+      echo "✅ Full test suite passed"
+      rm -f /tmp/pre-push-test-full.log
+    else
+      FULL_TEST_EXIT_CODE=\${PIPESTATUS[0]}
+      echo "❌ Full test suite failed (exit code: \${FULL_TEST_EXIT_CODE})"
+      echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+      echo "Test output (last 100 lines):"
+      tail -100 /tmp/pre-push-test-full.log 2>/dev/null || echo "No test output captured"
+      echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+      echo "💡 Fix test failures before pushing: npm test"
+      rm -f /tmp/pre-push-test-full.log
+      QUICK_CHECKS_FAILED=true
+    fi
+  fi
+fi
+
+# 4. Security checks (non-blocking warnings)
+echo ""
 echo "🔒 Running security checks..."
 if [ -f "package.json" ]; then
-  # Check for vulnerabilities
   if command -v npm >/dev/null 2>&1; then
     echo "🔍 Checking for vulnerabilities..."
     if npm audit --audit-level moderate >/dev/null 2>&1; then
       echo "✅ Security audit passed"
     else
-      echo "⚠️  Security vulnerabilities found"
+      echo "⚠️  Security vulnerabilities found (non-blocking)"
       echo "💡 Review with: npm audit"
-      # Don't fail on warnings, just warn
     fi
   fi
 elif [ -f "requirements.txt" ] || [ -f "pyproject.toml" ]; then
-  # Python project security checks
   if command -v pip-audit >/dev/null 2>&1; then
     echo "🔍 Checking Python vulnerabilities..."
-    pip-audit --desc 2>/dev/null || echo "⚠️  Install pip-audit for vulnerability checks: pip install pip-audit"
+    pip-audit --desc 2>/dev/null || echo "⚠️  Install pip-audit: pip install pip-audit"
   fi
 elif [ -f "Cargo.toml" ]; then
-  # Rust project security checks
   if command -v cargo-audit >/dev/null 2>&1; then
     echo "🔍 Checking Rust vulnerabilities..."
-    cargo audit 2>/dev/null || echo "⚠️  Install cargo-audit for vulnerability checks: cargo install cargo-audit"
+    cargo audit 2>/dev/null || echo "⚠️  Install cargo-audit: cargo install cargo-audit"
   fi
 fi
 
-echo "🎉 Pre-push checks completed!"
+# Fail if any checks failed
+if [ "$QUICK_CHECKS_FAILED" = true ]; then
+  echo ""
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  echo "❌ Pre-push checks failed"
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  echo "All checks (linting/type checking/full test suite) must pass before push."
+  echo ""
+  echo "💡 Fix failures before pushing:"
+  echo "   - Linting: npm run lint"
+  echo "   - Type checking: npm run typecheck"
+  echo "   - Tests: npm test"
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  exit 1
+fi
+
+echo ""
+echo "✅ Pre-push checks completed!"
+echo "💡 All quality gates passed - ready to push"
 `;
 }
 
@@ -583,7 +679,7 @@ fi
 
 # Basic commit message validation
 if [ \${#COMMIT_MSG} -lt 10 ]; then
-  echo "❌ Commit message too short (minimum 10 characters)"
+  echo "❌ Commit message too short \\(minimum 10 characters\\)"
   echo "💡 Write descriptive commit messages"
   exit 1
 fi
@@ -700,4 +796,9 @@ module.exports = {
   scaffoldGitHooks,
   removeGitHooks,
   checkGitHooksStatus,
+  // Export generator functions for testing
+  generatePrePushHook,
+  generatePreCommitHook,
+  generatePostCommitHook,
+  generateCommitMsgHook,
 };

package/dist/scaffold/index.js

@@ -735,7 +735,7 @@ async function scaffoldProject(options) {
     }
 
     // Update .gitignore to exclude CAWS local runtime files
-    const gitignoreUpdated = await updateGitignore(targetDir);
+    const gitignoreUpdated = await updateGitignore(currentDir);
     if (gitignoreUpdated) {
       console.log(chalk.green('\n✅ Updated .gitignore to exclude CAWS local runtime files'));
       console.log(

package/dist/templates/.caws/tools/README.md

@@ -18,3 +18,4 @@ node .caws/tools/scope-guard.js check .caws/working-spec.yaml
 
 The `.cursor/hooks/scope-guard.sh` hook automatically uses this tool to validate file attachments against working spec scope boundaries.
 
+

package/dist/utils/git-lock.js

@@ -116,3 +116,4 @@ module.exports = {
   formatGitLockError,
 };
 
+

package/dist/utils/project-analysis.js

@@ -111,9 +111,7 @@ function detectsPublishing(cwd = process.cwd()) {
   // Check package.json for npm publishing
   if (files.includes('package.json')) {
     try {
-      const packageJson = JSON.parse(
-        fs.readFileSync(path.join(cwd, 'package.json'), 'utf8')
-      );
+      const packageJson = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf8'));
 
       // Indicators of publishing:
       // - Has publishConfig
@@ -123,9 +121,7 @@ function detectsPublishing(cwd = process.cwd()) {
       const hasPublishConfig = packageJson.publishConfig;
       const hasPublishScript =
         packageJson.scripts &&
-        Object.keys(packageJson.scripts).some((key) =>
-          key.toLowerCase().includes('publish')
-        );
+        Object.keys(packageJson.scripts).some((key) => key.toLowerCase().includes('publish'));
       const hasScopedName = packageJson.name && packageJson.name.startsWith('@');
       const hasRepository = packageJson.repository;
 
@@ -140,16 +136,13 @@ function detectsPublishing(cwd = process.cwd()) {
   // Check pyproject.toml for PyPI publishing
   if (files.includes('pyproject.toml')) {
     try {
-      const pyprojectContent = fs.readFileSync(
-        path.join(cwd, 'pyproject.toml'),
-        'utf8'
-      );
+      const pyprojectContent = fs.readFileSync(path.join(cwd, 'pyproject.toml'), 'utf8');
 
       // Check for build system and project metadata (indicates publishable package)
       const hasBuildSystem = pyprojectContent.includes('[build-system]');
       const hasProjectMetadata = pyprojectContent.includes('[project]');
-      const hasToolPublish = pyprojectContent.includes('[tool.publish]') ||
-                            pyprojectContent.includes('[tool.twine]');
+      const hasToolPublish =
+        pyprojectContent.includes('[tool.publish]') || pyprojectContent.includes('[tool.twine]');
 
       if ((hasBuildSystem && hasProjectMetadata) || hasToolPublish) {
         return true;
@@ -177,10 +170,7 @@ function detectsPublishing(cwd = process.cwd()) {
       const workflowFiles = fs.readdirSync(workflowsPath);
       for (const workflowFile of workflowFiles) {
         if (workflowFile.endsWith('.yml') || workflowFile.endsWith('.yaml')) {
-          const workflowContent = fs.readFileSync(
-            path.join(workflowsPath, workflowFile),
-            'utf8'
-          );
+          const workflowContent = fs.readFileSync(path.join(workflowsPath, workflowFile), 'utf8');
           // Check for common publishing actions/commands
           if (
             workflowContent.includes('npm publish') ||
@@ -201,8 +191,178 @@ function detectsPublishing(cwd = process.cwd()) {
   return false;
 }
 
+/**
+ * Detect primary programming language(s) used in project
+ * @param {string} cwd - Current working directory
+ * @returns {Object} Language detection result with primary language and indicators
+ */
+function detectProjectLanguage(cwd = process.cwd()) {
+  const files = fs.readdirSync(cwd);
+  const indicators = {
+    javascript: false,
+    typescript: false,
+    python: false,
+    rust: false,
+    go: false,
+    java: false,
+    csharp: false,
+    php: false,
+  };
+
+  // JavaScript/TypeScript indicators
+  if (files.includes('package.json')) {
+    indicators.javascript = true;
+    try {
+      const packageJson = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf8'));
+      const allDeps = {
+        ...(packageJson.dependencies || {}),
+        ...(packageJson.devDependencies || {}),
+      };
+      if ('typescript' in allDeps || files.includes('tsconfig.json')) {
+        indicators.typescript = true;
+        indicators.javascript = false; // TypeScript supersedes JavaScript
+      }
+    } catch (e) {
+      // Ignore parse errors
+    }
+  }
+
+  // Python indicators
+  if (
+    files.includes('requirements.txt') ||
+    files.includes('pyproject.toml') ||
+    files.includes('setup.py') ||
+    files.includes('Pipfile') ||
+    files.includes('poetry.lock') ||
+    files.some((f) => f.endsWith('.py'))
+  ) {
+    indicators.python = true;
+  }
+
+  // Rust indicators
+  if (files.includes('Cargo.toml') || files.some((f) => f.endsWith('.rs'))) {
+    indicators.rust = true;
+  }
+
+  // Go indicators
+  if (
+    files.includes('go.mod') ||
+    files.includes('go.sum') ||
+    files.some((f) => f.endsWith('.go'))
+  ) {
+    indicators.go = true;
+  }
+
+  // Java indicators
+  if (
+    files.includes('pom.xml') ||
+    files.includes('build.gradle') ||
+    files.some((f) => f.endsWith('.java'))
+  ) {
+    indicators.java = true;
+  }
+
+  // C# indicators
+  if (
+    files.some((f) => f.endsWith('.csproj')) ||
+    files.some((f) => f.endsWith('.sln')) ||
+    files.some((f) => f.endsWith('.cs'))
+  ) {
+    indicators.csharp = true;
+  }
+
+  // PHP indicators
+  if (
+    files.includes('composer.json') ||
+    files.includes('composer.lock') ||
+    files.some((f) => f.endsWith('.php'))
+  ) {
+    indicators.php = true;
+  }
+
+  // Determine primary language (priority order)
+  let primaryLanguage = 'unknown';
+  if (indicators.typescript) {
+    primaryLanguage = 'typescript';
+  } else if (indicators.javascript) {
+    primaryLanguage = 'javascript';
+  } else if (indicators.python) {
+    primaryLanguage = 'python';
+  } else if (indicators.rust) {
+    primaryLanguage = 'rust';
+  } else if (indicators.go) {
+    primaryLanguage = 'go';
+  } else if (indicators.java) {
+    primaryLanguage = 'java';
+  } else if (indicators.csharp) {
+    primaryLanguage = 'csharp';
+  } else if (indicators.php) {
+    primaryLanguage = 'php';
+  }
+
+  return {
+    primary: primaryLanguage,
+    indicators,
+    hasNodeJs: indicators.javascript || indicators.typescript,
+    hasPython: indicators.python,
+  };
+}
+
+/**
+ * Get language-agnostic suggestion for TODO analyzer installation
+ * Focuses on runtime availability (Node.js/npx) rather than project language
+ * @param {string} cwd - Current working directory
+ * @returns {string} Installation suggestion message
+ */
+function getTodoAnalyzerSuggestion(cwd = process.cwd()) {
+  // Check runtime availability (language-agnostic)
+  let hasNodeJs = false;
+  let hasNpx = false;
+  try {
+    const { execSync } = require('child_process');
+    execSync('command -v node', { encoding: 'utf8', stdio: 'ignore' });
+    hasNodeJs = true;
+    execSync('command -v npx', { encoding: 'utf8', stdio: 'ignore' });
+    hasNpx = true;
+  } catch (e) {
+    // Node.js/npx not available
+  }
+
+  const suggestions = [];
+
+  if (hasNpx) {
+    // npx available - works for any language, no installation needed
+    suggestions.push(
+      '   • Use npx (no installation required): npx --yes @paths.design/quality-gates'
+    );
+    suggestions.push('   • Install package: npm install --save-dev @paths.design/quality-gates');
+  } else if (hasNodeJs) {
+    // Node.js available but npx not found (unusual)
+    suggestions.push('   • Install package: npm install --save-dev @paths.design/quality-gates');
+    suggestions.push(
+      '   • Install npx: npm install -g npx (then use: npx --yes @paths.design/quality-gates)'
+    );
+  } else {
+    // Node.js not available - suggest installation
+    suggestions.push(
+      '   • Install Node.js: https://nodejs.org/ (then use: npx --yes @paths.design/quality-gates)'
+    );
+    suggestions.push('   • Use CAWS MCP server: caws quality-gates (via MCP)');
+  }
+
+  // Check for project-specific scripts (language-agnostic - if they exist, suggest them)
+  const pythonScript = path.join(cwd, 'scripts', 'v3', 'analysis', 'todo_analyzer.py');
+  if (fs.existsSync(pythonScript)) {
+    suggestions.push(`   • Use project script: python3 ${pythonScript}`);
+  }
+
+  return suggestions.join('\n');
+}
+
 module.exports = {
   detectProjectType,
   shouldInitInCurrentDirectory,
   detectsPublishing,
+  detectProjectLanguage,
+  getTodoAnalyzerSuggestion,
 };

package/dist/utils/quality-gates.js

@@ -11,6 +11,7 @@ const fs = require('fs');
 const path = require('path');
 const yaml = require('js-yaml');
 const { execSync } = require('child_process');
+const { getTodoAnalyzerSuggestion } = require('./project-analysis');
 
 /**
  * Quality Gate Configuration
@@ -229,17 +230,17 @@ function checkHiddenTodos(stagedFiles) {
 
     if (!analyzerPath) {
       console.warn('⚠️  TODO analyzer not found - skipping TODO analysis');
-      console.warn(
-        '💡 Install @paths.design/quality-gates: npm install --save-dev @paths.design/quality-gates'
-      );
+      const suggestion = getTodoAnalyzerSuggestion(process.cwd());
+      console.warn('💡 Available options for TODO analysis:');
+      console.warn(suggestion);
       return { todos: [], blocking: 0, total: 0 };
     }
 
     if (usePython) {
       console.warn('⚠️  Using legacy Python TODO analyzer (deprecated)');
-      console.warn(
-        '💡 Install @paths.design/quality-gates for Node.js version: npm install --save-dev @paths.design/quality-gates'
-      );
+      const suggestion = getTodoAnalyzerSuggestion(process.cwd());
+      console.warn('💡 Consider upgrading to Node.js version:');
+      console.warn(suggestion);
     }
 
     // Run the TODO analyzer with staged files

package/dist/utils/spec-resolver.js

@@ -512,6 +512,10 @@ async function suggestMigration() {
 function suggestFeatureBreakdown(legacySpec) {
   const features = [];
 
+  if (!legacySpec) {
+    return features;
+  }
+
   if (legacySpec.acceptance && legacySpec.acceptance.length > 0) {
     // Group acceptance criteria by logical features
     const criteriaByFeature = {};

package/dist/utils/yaml-validation.js

@@ -153,3 +153,4 @@ module.exports = {
   formatYamlError,
 };
 
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paths.design/caws-cli",
-  "version": "7.0.3",
+  "version": "8.0.0",
   "description": "CAWS CLI - Coding Agent Workflow System command line tools",
   "main": "dist/index.js",
   "bin": {

package/templates/.caws/tools/README.md

@@ -18,3 +18,4 @@ node .caws/tools/scope-guard.js check .caws/working-spec.yaml
 
 The `.cursor/hooks/scope-guard.sh` hook automatically uses this tool to validate file attachments against working spec scope boundaries.
 
+