@paths.design/caws-cli 7.0.2 → 8.0.0

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

@@ -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
@@ -138,6 +142,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,40 +329,50 @@ 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)
-  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
+  
+  TODO_CHECK_RAN=false
+  
+  # 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
-  # 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
+    
+    # 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 node_modules/@caws/quality-gates/todo-analyzer.mjs --staged-only --min-confidence 0.8
+        node "$TODO_ANALYZER" --staged-only --min-confidence 0.8
         exit 1
       fi
     fi
-  # Fallback to legacy Python analyzer
-  elif command -v python3 >/dev/null 2>&1 && [ -f "scripts/v3/analysis/todo_analyzer.py" ]; then
+  fi
+  
+  # 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)"
     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"
@@ -274,8 +382,16 @@ 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"
+  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 "💡 Available options for TODO analysis:"
+${todoSuggestion
+  .split('\n')
+  .map((line) => `    echo "${line.replace(/"/g, '\\"')}"`)
+  .join('\n')}
   fi
 fi
 
@@ -346,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
@@ -410,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
     
@@ -425,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"
 `;
 }
 
@@ -485,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
@@ -602,4 +796,9 @@ module.exports = {
   scaffoldGitHooks,
   removeGitHooks,
   checkGitHooksStatus,
+  // Export generator functions for testing
+  generatePrePushHook,
+  generatePreCommitHook,
+  generatePostCommitHook,
+  generateCommitMsgHook,
 };

package/dist/scaffold/index.js

@@ -14,6 +14,7 @@ const { detectsPublishing } = require('../utils/project-analysis');
 
 // Import git hooks scaffolding
 const { scaffoldGitHooks } = require('./git-hooks');
+const { updateGitignore } = require('../utils/gitignore-updater');
 
 // CLI version from package.json
 const CLI_VERSION = require('../../package.json').version;
@@ -31,20 +32,20 @@ const CLI_VERSION = require('../../package.json').version;
 function findTemplateDir() {
   // Find package root using shared utility
   const packageRoot = findPackageRoot(__dirname);
-  
+
   // Try templates relative to package root first (works in both dev and global install)
   const possiblePaths = [
     path.join(packageRoot, 'templates'),
     path.resolve(__dirname, '../../templates'), // Dev fallback
     path.resolve(__dirname, '../templates'), // Legacy fallback
   ];
-  
+
   for (const testPath of possiblePaths) {
     if (fs.existsSync(testPath)) {
       return testPath;
     }
   }
-  
+
   return null;
 }
 
@@ -301,12 +302,32 @@ async function scaffoldProject(options) {
     // Determine what enhancements to add based on setup type and options
     const enhancements = [];
 
-    // Add CAWS tools directory structure (matches test expectations)
+    // Add CAWS tools to .caws/ directory (keeps all CAWS files together)
     enhancements.push({
-      name: 'apps/tools/caws',
+      name: '.caws/tools',
       description: 'CAWS tools directory',
       required: true,
     });
+    enhancements.push({
+      name: '.caws/schemas',
+      description: 'CAWS JSON schemas',
+      required: true,
+    });
+    enhancements.push({
+      name: '.caws/templates',
+      description: 'CAWS templates',
+      required: true,
+    });
+    enhancements.push({
+      name: '.caws/waivers.yml',
+      description: 'CAWS waivers configuration',
+      required: false,
+    });
+    enhancements.push({
+      name: '.caws/tools-allow.json',
+      description: 'CAWS tools allowlist',
+      required: false,
+    });
 
     // Add codemods if requested or not minimal
     if (options.withCodemods || (!options.minimal && !options.withCodemods)) {
@@ -457,6 +478,19 @@ async function scaffoldProject(options) {
             console.log(
               chalk.gray('   For now, quality gates will work via CAWS CLI or local scripts')
             );
+
+            // Copy todo-analyzer.mjs locally as fallback if available
+            const qualityGatesPath = path.resolve(__dirname, '../../../quality-gates');
+            const todoAnalyzerSource = path.join(qualityGatesPath, 'todo-analyzer.mjs');
+            if (fs.existsSync(todoAnalyzerSource)) {
+              const scriptsDir = path.join(currentDir, 'scripts');
+              await fs.ensureDir(scriptsDir);
+              const todoAnalyzerDest = path.join(scriptsDir, 'todo-analyzer.mjs');
+              await fs.copy(todoAnalyzerSource, todoAnalyzerDest);
+              console.log(
+                chalk.green('✅ Copied todo-analyzer.mjs to scripts/ directory (local fallback)')
+              );
+            }
           }
         } else {
           // No package.json - suggest global install or manual setup
@@ -601,12 +635,14 @@ async function scaffoldProject(options) {
           try {
             // Check if the enhancement name looks like a file (has extension)
             const hasExtension = path.extname(enhancement.name).length > 0;
-            
+
             if (hasExtension) {
               // Create an empty file for file-like enhancements
               await fs.ensureDir(path.dirname(destPath));
               await fs.writeFile(destPath, '');
-              console.log(chalk.yellow(`⚠️  Created empty ${enhancement.description} (template not found)`));
+              console.log(
+                chalk.yellow(`⚠️  Created empty ${enhancement.description} (template not found)`)
+              );
               console.log(chalk.gray(`   Template expected at: ${sourcePath}`));
             } else {
               // Create directory for directory-like enhancements
@@ -698,6 +734,16 @@ async function scaffoldProject(options) {
       console.log(chalk.yellow('\n⚠️  Force mode was used - review changes carefully'));
     }
 
+    // Update .gitignore to exclude CAWS local runtime files
+    const gitignoreUpdated = await updateGitignore(currentDir);
+    if (gitignoreUpdated) {
+      console.log(chalk.green('\n✅ 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)'));
+    }
+
     // Save provenance manifest if tools are available
     const tools = loadProvenanceTools && loadProvenanceTools();
     if (tools && typeof tools.saveProvenance === 'function') {

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

@@ -0,0 +1,21 @@
+# CAWS Tools
+
+This directory contains CAWS-specific tools that aren't available in the CLI.
+
+## scope-guard.js
+
+Enforces that experimental code stays within designated sandbox areas. Used by Cursor hooks for scope validation.
+
+```bash
+# Validate experimental code containment
+node .caws/tools/scope-guard.js validate
+
+# Check containment status
+node .caws/tools/scope-guard.js check .caws/working-spec.yaml
+```
+
+**Usage in Cursor Hooks:**
+
+The `.cursor/hooks/scope-guard.sh` hook automatically uses this tool to validate file attachments against working spec scope boundaries.
+
+