@paths.design/caws-cli 8.1.0 → 8.2.0

package/README.md

@@ -13,7 +13,7 @@ The CAWS CLI serves as the central control point for:
 - **Agent Integration**: Programmatic APIs for AI agents to evaluate and guide development
 - **Waiver Management**: Fast-lane escape hatches with full audit trails
 - **CI/CD Optimization**: Pipeline generation and optimization tools
-- **Experimental Features**: Dry-run capabilities for cutting-edge functionality
+- **Experimental Features**: Dry-run capabilities for experimental functionality
 
 ## Installation
 
@@ -157,15 +157,14 @@ caws-cli/
         │                       │
         └───────────────────────┘
                 │
-        ┌─────────────────┐    ┌──────────────────┐
-        │ caws-mcp-server │────│ caws-vscode-ext  │
-        │ (Agent Bridge)  │    │   (IDE Integration)
-        └─────────────────┘    └──────────────────┘
+        ┌─────────────────┐
+        │ caws-mcp-server │
+        │ (Agent Bridge)  │
+        └─────────────────┘
 ```
 
 - **caws-template**: Provides the tools and configurations that CLI manages
 - **caws-mcp-server**: Exposes CLI functionality to AI agents via MCP protocol
-- **caws-vscode-extension**: Provides IDE integration using CLI capabilities
 
 ### Quality Gates Integration
 

package/dist/commands/archive.d.ts

@@ -22,7 +22,7 @@ export function validateAcceptanceCriteria(workingSpec: any): Promise<any>;
  * @param {string} changeId - Change identifier
  * @returns {Promise<Object>} Quality gate result
  */
-export function validateQualityGates(changeId: string): Promise<any>;
+export function validateQualityGates(_changeId: any): Promise<any>;
 /**
  * Generate change summary for archival
  * @param {Object} change - Change data

package/dist/commands/archive.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"archive.d.ts","sourceRoot":"","sources":["../../src/commands/archive.js"],"names":[],"mappings":"AA0VA;;;;GAIG;AACH,yCAHW,MAAM,+BAqGhB;AAjbD;;;;GAIG;AACH,qCAHW,MAAM,GACJ,OAAO,CAAC,MAAO,IAAI,CAAC,CAgChC;AAED;;;;GAIG;AACH,8DAFa,OAAO,KAAQ,CA8B3B;AAED;;;;;GAKG;AACH,+CAHW,MAAM,GACJ,OAAO,KAAQ,CAmH3B;AAED;;;;GAIG;AACH,oDAFa,OAAO,CAAC,MAAM,CAAC,CAgC3B;AAED;;;;GAIG;AACH,4CAFa,OAAO,CAAC,IAAI,CAAC,CAazB;AAED;;;;GAIG;AACH,+CAFa,OAAO,CAAC,IAAI,CAAC,CAoCzB;AAED;;;;;GAKG;AACH,6FAiCC"}
+{"version":3,"file":"archive.d.ts","sourceRoot":"","sources":["../../src/commands/archive.js"],"names":[],"mappings":"AA0VA;;;;GAIG;AACH,yCAHW,MAAM,+BAqGhB;AAjbD;;;;GAIG;AACH,qCAHW,MAAM,GACJ,OAAO,CAAC,MAAO,IAAI,CAAC,CAgChC;AAED;;;;GAIG;AACH,8DAFa,OAAO,KAAQ,CA8B3B;AAED;;;;;GAKG;AACH,sDAFa,OAAO,KAAQ,CAmH3B;AAED;;;;GAIG;AACH,oDAFa,OAAO,CAAC,MAAM,CAAC,CAgC3B;AAED;;;;GAIG;AACH,4CAFa,OAAO,CAAC,IAAI,CAAC,CAazB;AAED;;;;GAIG;AACH,+CAFa,OAAO,CAAC,IAAI,CAAC,CAoCzB;AAED;;;;;GAKG;AACH,6FAiCC"}

package/dist/commands/init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.js"],"names":[],"mappings":"AAqBA;;GAEG;AACH,2EAwiBC"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.js"],"names":[],"mappings":"AAwBA;;GAEG;AACH,2EA6mBC"}

package/dist/commands/init.js

@@ -18,6 +18,15 @@ const { finalizeProject } = require('../utils/finalization');
 const { scaffoldCursorHooks } = require('../scaffold/cursor-hooks');
 const { scaffoldIDEIntegrations } = require('../scaffold/index');
 const { updateGitignore } = require('../utils/gitignore-updater');
+const { getLiteScopeDefaults } = require('../config/lite-scope');
+const { scaffoldClaudeHooks } = require('../scaffold/claude-hooks');
+const { setCurrentMode } = require('../config/modes');
+const {
+  IDE_REGISTRY,
+  detectActiveIDEs,
+  getRecommendedIDEs,
+  parseIDESelection,
+} = require('../utils/ide-detection');
 
 /**
  * Initialize a new project with CAWS
@@ -115,8 +124,9 @@ async function initProject(projectName, options) {
     const cawsSetup = detectCAWSSetup(targetDir);
     const originalTemplateDir = cawsSetup?.hasTemplateDir ? cawsSetup.templateDir : null;
 
-    // Check for existing agents.md/caws.md in target directory
-    const existingAgentsMd = fs.existsSync(path.join(targetDir, 'agents.md'));
+    // Check for existing AGENTS.md/agents.md/caws.md in target directory
+    const existingAgentsMd = fs.existsSync(path.join(targetDir, 'AGENTS.md')) ||
+      fs.existsSync(path.join(targetDir, 'agents.md'));
     const existingCawsMd = fs.existsSync(path.join(targetDir, 'caws.md'));
 
     // Create project directory and change to it (unless already in current directory)
@@ -137,55 +147,45 @@ async function initProject(projectName, options) {
       await fs.ensureDir('.agent');
       console.log(chalk.blue('ℹ️  Created basic CAWS structure'));
 
-      // Copy agents.md guide if templates are available
+      // Copy AGENTS.md guide if templates are available
       if (originalTemplateDir) {
         try {
-          const agentsMdSource = path.join(originalTemplateDir, 'agents.md');
-          let targetFile = 'agents.md';
+          const agentsMdSource = path.join(originalTemplateDir, 'AGENTS.md');
+          let targetFile = 'AGENTS.md';
 
           if (fs.existsSync(agentsMdSource)) {
-            // Use the pre-checked values for conflicts
             if (existingAgentsMd) {
-              // Conflict: user already has agents.md
               if (options.interactive && !options.nonInteractive) {
-                // Interactive mode: ask user
                 const overwriteAnswer = await inquirer.prompt([
                   {
                     type: 'confirm',
                     name: 'overwrite',
-                    message: '⚠️  agents.md already exists. Overwrite with CAWS guide?',
+                    message: 'AGENTS.md already exists. Overwrite with CAWS guide?',
                     default: false,
                   },
                 ]);
 
-                if (overwriteAnswer.overwrite) {
-                  targetFile = 'agents.md';
-                } else {
+                if (!overwriteAnswer.overwrite) {
                   targetFile = 'caws.md';
                 }
               } else {
-                // Non-interactive mode: use caws.md instead
                 targetFile = 'caws.md';
-                console.log(chalk.blue('ℹ️  agents.md exists, using caws.md for CAWS guide'));
+                console.log(chalk.blue('AGENTS.md exists, using caws.md for CAWS guide'));
               }
             }
 
-            // If caws.md also exists and that's our target, skip
             if (targetFile === 'caws.md' && existingCawsMd) {
               console.log(
-                chalk.yellow('⚠️  Both agents.md and caws.md exist, skipping guide copy')
+                chalk.yellow('Both AGENTS.md and caws.md exist, skipping guide copy')
               );
             } else {
               const agentsMdDest = path.join(process.cwd(), targetFile);
               await fs.copyFile(agentsMdSource, agentsMdDest);
-              console.log(chalk.green(`✅ Added ${targetFile} guide`));
+              console.log(chalk.green(`Added ${targetFile} guide`));
             }
           }
         } catch (templateError) {
-          console.warn(chalk.yellow('⚠️  Could not copy agents guide:'), templateError.message);
-          console.warn(
-            chalk.blue('💡 You can manually copy the guide from the caws-template package')
-          );
+          console.warn(chalk.yellow('Could not copy agents guide:'), templateError.message);
         }
       }
     } else {
@@ -193,12 +193,92 @@ async function initProject(projectName, options) {
       console.log(chalk.green('✅ CAWS project detected - skipping template copy'));
     }
 
+    // Handle lite mode init path
+    if (options.mode === 'lite') {
+      console.log(chalk.magenta('🛡️  CAWS Lite Mode — guardrails without YAML specs'));
+
+      // Detect allowed directories
+      const detectedDirs = [];
+      const commonDirs = ['src/', 'lib/', 'app/', 'tests/', 'test/', 'docs/'];
+      for (const dir of commonDirs) {
+        if (fs.existsSync(path.join(process.cwd(), dir.replace(/\/$/, '')))) {
+          detectedDirs.push(dir);
+        }
+      }
+
+      let allowedDirs = detectedDirs.length > 0 ? detectedDirs : ['src/', 'tests/', 'docs/'];
+
+      if (options.interactive && !options.nonInteractive) {
+        const liteAnswers = await inquirer.prompt([
+          {
+            type: 'input',
+            name: 'projectName',
+            message: '📝 Project name:',
+            default: path.basename(process.cwd()),
+          },
+          {
+            type: 'input',
+            name: 'allowedDirs',
+            message: '📁 Allowed directories (comma-separated):',
+            default: allowedDirs.join(', '),
+          },
+        ]);
+        allowedDirs = liteAnswers.allowedDirs.split(',').map((d) => d.trim()).filter(Boolean);
+      }
+
+      // Generate .caws/scope.json
+      await fs.ensureDir('.caws');
+      const scopeConfig = getLiteScopeDefaults();
+      scopeConfig.allowedDirectories = allowedDirs;
+      await fs.writeFile(
+        path.join('.caws', 'scope.json'),
+        JSON.stringify(scopeConfig, null, 2)
+      );
+      console.log(chalk.green('✅ Created .caws/scope.json'));
+
+      // Set mode to lite
+      await setCurrentMode('lite');
+      console.log(chalk.green('✅ Set mode to lite in .caws/mode.json'));
+
+      // Scaffold hooks: block-dangerous + scope-guard + lite-sprawl-check + simplification-guard
+      const liteIDEs = options.ide ? parseIDESelection(options.ide) : ['claude'];
+      if (liteIDEs.includes('claude')) {
+        console.log(chalk.blue('🔧 Setting up lite-mode hooks...'));
+        await scaffoldClaudeHooks(process.cwd(), ['safety', 'scope', 'lite']);
+      }
+
+      // Update .gitignore
+      console.log(chalk.blue('📝 Updating .gitignore...'));
+      await updateGitignore(process.cwd());
+
+      // Success
+      console.log(chalk.green('\n🎉 CAWS Lite mode initialized!'));
+      console.log(chalk.blue('\nGuardrails active:'));
+      console.log('  - Destructive command blocking (git push --force, rm -rf, etc.)');
+      console.log('  - Scope fencing (edits outside allowed directories require confirmation)');
+      console.log('  - File sprawl detection (banned patterns like *-enhanced.*, *-final.*)');
+      console.log('  - Simplification guard (prevents stubbing out implementations)');
+      console.log(chalk.blue('\nNext steps:'));
+      console.log('  1. Review .caws/scope.json and customize for your project');
+      console.log('  2. Start coding — hooks will protect against common AI mistakes');
+      console.log('  3. Use `caws worktree create <name>` for isolated agent workspaces');
+      return;
+    }
+
     // Handle interactive wizard or template-based setup
     if (options.interactive && !options.nonInteractive) {
       console.log(chalk.cyan('🎯 CAWS Interactive Setup Wizard'));
       console.log(chalk.blue('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
       console.log(chalk.gray('This wizard will guide you through creating a CAWS working spec\n'));
 
+      // Detect active IDEs for pre-selecting the IDE prompt
+      const detectedIDEs = detectActiveIDEs();
+      const recommendedIDEs = getRecommendedIDEs();
+      if (detectedIDEs.length > 0) {
+        console.log(chalk.blue(`Detected IDE: ${detectedIDEs.map((id) => IDE_REGISTRY[id].name).join(', ')}`));
+        console.log(chalk.gray('   (Pre-selected based on your environment)\n'));
+      }
+
       // Detect project type
       const detectedType = detectProjectType(process.cwd());
       console.log(chalk.blue(`📦 Detected project type: ${chalk.cyan(detectedType)}`));
@@ -337,10 +417,65 @@ async function initProject(projectName, options) {
           },
         },
         {
-          type: 'confirm',
-          name: 'useCursorHooks',
-          message: '🎯 Enable Cursor IDE hooks for real-time quality gates?',
-          default: true,
+          type: 'checkbox',
+          name: 'selectedIDEs',
+          message: 'Which IDE integrations do you want to install?',
+          choices: [
+            {
+              name: `Cursor (hooks, rules, audit) - AI-first IDE`,
+              value: 'cursor',
+              checked: options.ide
+                ? parseIDESelection(options.ide).includes('cursor')
+                : recommendedIDEs.includes('cursor'),
+            },
+            {
+              name: `Claude Code (safety hooks, settings)`,
+              value: 'claude',
+              checked: options.ide
+                ? parseIDESelection(options.ide).includes('claude')
+                : recommendedIDEs.includes('claude'),
+            },
+            {
+              name: `VS Code (settings, debug configs)`,
+              value: 'vscode',
+              checked: options.ide
+                ? parseIDESelection(options.ide).includes('vscode')
+                : recommendedIDEs.includes('vscode'),
+            },
+            {
+              name: `IntelliJ IDEA (run configurations)`,
+              value: 'intellij',
+              checked: options.ide
+                ? parseIDESelection(options.ide).includes('intellij')
+                : recommendedIDEs.includes('intellij'),
+            },
+            {
+              name: `Windsurf (CAWS workflow)`,
+              value: 'windsurf',
+              checked: options.ide
+                ? parseIDESelection(options.ide).includes('windsurf')
+                : recommendedIDEs.includes('windsurf'),
+            },
+            {
+              name: `GitHub Copilot (instructions)`,
+              value: 'copilot',
+              checked: options.ide
+                ? parseIDESelection(options.ide).includes('copilot')
+                : recommendedIDEs.includes('copilot'),
+            },
+            {
+              name: `JetBrains Junie (AI agent guidelines)`,
+              value: 'junie',
+              checked: options.ide
+                ? parseIDESelection(options.ide).includes('junie')
+                : recommendedIDEs.includes('junie'),
+            },
+            new inquirer.Separator(),
+            {
+              name: 'All IDEs (install everything)',
+              value: 'all',
+            },
+          ],
         },
         {
           type: 'confirm',
@@ -412,15 +547,20 @@ Happy coding! 🎯
         console.log(chalk.green('✅ Created test and docs directories'));
       }
 
-      // Setup Cursor hooks if requested
-      if (answers.useCursorHooks) {
-        console.log(chalk.blue('🎯 Setting up Cursor hooks...'));
+      // Setup selected IDE integrations
+      const selectedIDEs = parseIDESelection(answers.selectedIDEs || []);
+
+      if (selectedIDEs.includes('cursor')) {
+        console.log(chalk.blue('Setting up Cursor hooks...'));
         await scaffoldCursorHooks(process.cwd());
       }
 
-      // Setup IDE integrations for comprehensive development experience
-      console.log(chalk.blue('🎨 Setting up IDE integrations...'));
-      await scaffoldIDEIntegrations(process.cwd(), { force: false });
+      if (selectedIDEs.length > 0) {
+        console.log(chalk.blue('Setting up IDE integrations...'));
+        await scaffoldIDEIntegrations(process.cwd(), { force: false, ides: selectedIDEs });
+      } else {
+        console.log(chalk.gray('Skipping IDE setup (none selected, run `caws scaffold --ide <ides>` later)'));
+      }
 
       // Update .gitignore to exclude CAWS local runtime files
       console.log(chalk.blue('📝 Updating .gitignore...'));
@@ -500,13 +640,18 @@ Happy coding! 🎯
         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());
+      // Setup IDE integrations based on --ide flag or auto-detection
+      const selectedIDEs = options.ide ? parseIDESelection(options.ide) : getRecommendedIDEs();
 
-      // Setup IDE integrations by default in non-interactive mode
-      console.log(chalk.blue('🎨 Setting up IDE integrations...'));
-      await scaffoldIDEIntegrations(process.cwd(), { force: false });
+      if (selectedIDEs.includes('cursor')) {
+        console.log(chalk.blue('Setting up Cursor hooks...'));
+        await scaffoldCursorHooks(process.cwd());
+      }
+
+      if (selectedIDEs.length > 0) {
+        console.log(chalk.blue(`Setting up IDE integrations: ${selectedIDEs.map((id) => IDE_REGISTRY[id].name).join(', ')}...`));
+        await scaffoldIDEIntegrations(process.cwd(), { force: false, ides: selectedIDEs });
+      }
 
       // Update .gitignore to exclude CAWS local runtime files
       console.log(chalk.blue('📝 Updating .gitignore...'));
@@ -549,8 +694,9 @@ Happy coding! 🎯
     console.log('   3. Run: caws validate (verify setup)');
     console.log('   4. Run: caws diagnose (check health)');
     console.log('   5. Optional: Create .caws/policy.yaml for custom budgets');
-    if (answers?.useCursorHooks || options.interactive === false) {
-      console.log('   6. Restart Cursor IDE to activate quality gates');
+    const finalIDEs = answers?.selectedIDEs || [];
+    if (finalIDEs.includes('cursor') || finalIDEs.includes('claude') || options.interactive === false) {
+      console.log('   6. Restart your IDE to activate quality gates');
     }
     console.log('\n💡 Quick start: caws scaffold && caws validate && caws diagnose');
   } catch (error) {

package/dist/commands/mode.d.ts

@@ -8,8 +8,9 @@ import { getCurrentMode } from "../config/modes";
 import { setCurrentMode } from "../config/modes";
 /**
  * Display current mode status
+ * @param {string} currentMode - The current mode to display
  */
-export function displayCurrentMode(): void;
+export function displayCurrentMode(currentMode: string): void;
 /**
  * Display mode details
  * @param {string} mode - Mode to display

package/dist/commands/mode.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mode.d.ts","sourceRoot":"","sources":["../../src/commands/mode.js"],"names":[],"mappings":"AAuHA;;;;GAIG;AACH,oCAHW,MAAM,+BAgIhB;;;AAvOD;;GAEG;AACH,2CAOC;AAED;;;GAGG;AACH,yCAFW,MAAM,QA+ChB;AAED;;;GAGG;AACH,4CAFa,OAAO,CAAC,MAAM,CAAC,CAkC3B"}
+{"version":3,"file":"mode.d.ts","sourceRoot":"","sources":["../../src/commands/mode.js"],"names":[],"mappings":"AA0IA;;;;GAIG;AACH,oCAHW,MAAM,+BAuHhB;;;AAjPD;;;GAGG;AACH,gDAFW,MAAM,QA2BhB;AAED;;;GAGG;AACH,yCAFW,MAAM,QA+ChB;AAED;;;GAGG;AACH,4CAFa,OAAO,CAAC,MAAM,CAAC,CAkC3B"}

package/dist/commands/provenance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provenance.d.ts","sourceRoot":"","sources":["../../src/commands/provenance.js"],"names":[],"mappings":"AAYA;;;;GAIG;AACH,8CAHW,MAAM,8BA+BhB;AAED;;;GAGG;AACH,8DA4EC;AAED;;;GAGG;AACH,4DAyEC;AAED;;;GAGG;AACH,8DA8CC;AA6iBD;;;GAGG;AACH,4DAmEC;AAzcD;;;GAGG;AACH,0DAwEC"}
+{"version":3,"file":"provenance.d.ts","sourceRoot":"","sources":["../../src/commands/provenance.js"],"names":[],"mappings":"AA2CA;;;;GAIG;AACH,8CAHW,MAAM,8BA+BhB;AAED;;;GAGG;AACH,8DAuEC;AAED;;;GAGG;AACH,4DAyEC;AAED;;;GAGG;AACH,8DA8CC;AAgnBD;;;GAGG;AACH,4DAmEC;AA/cD;;;GAGG;AACH,0DAwEC"}

package/dist/commands/specs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"specs.d.ts","sourceRoot":"","sources":["../../src/commands/specs.js"],"names":[],"mappings":"AAipBA;;;;GAIG;AACH,qCAHW,MAAM,+BA+LhB;AA3zBD;;;GAGG;AACH,qCAFa,OAAO,KAAQ,CAqB3B;AAED;;;;GAIG;AACH,kDAFa,OAAO,CAAC,IAAI,CAAC,CAMzB;AAED;;;GAGG;AACH,iCAFa,OAAO,OAAO,CAmC1B;AAED;;;;;GAKG;AACH,+BAJW,MAAM,kBAEJ,OAAO,KAAQ,CAkO3B;AAED;;;;GAIG;AACH,6BAHW,MAAM,GACJ,OAAO,CAAC,MAAO,IAAI,CAAC,CAiBhC;AAED;;;;;GAKG;AACH,+BAJW,MAAM,kBAEJ,OAAO,CAAC,OAAO,CAAC,CA6B5B;AAED;;;;GAIG;AACH,+BAHW,MAAM,GACJ,OAAO,CAAC,OAAO,CAAC,CAmB5B;AAED;;;GAGG;AACH,sDA2CC;AAED;;;GAGG;AACH,oDAoCC;AAoHD;;;GAGG;AACH,yCAFa,OAAO,CAAC,MAAM,CAAC,CAqC3B;AA9nBD;;GAEG;AACH,wBAAkB,aAAa,CAAC;AAChC,6BAAuB,2BAA2B,CAAC"}
+{"version":3,"file":"specs.d.ts","sourceRoot":"","sources":["../../src/commands/specs.js"],"names":[],"mappings":"AAm0BA;;;;GAIG;AACH,qCAHW,MAAM,+BA+LhB;AA7+BD;;;GAGG;AACH,qCAFa,OAAO,KAAQ,CAqB3B;AAED;;;;GAIG;AACH,kDAFa,OAAO,CAAC,IAAI,CAAC,CAMzB;AAED;;;GAGG;AACH,iCAFa,OAAO,OAAO,CAmC1B;AAED;;;;;GAKG;AACH,+BAJW,MAAM,kBAEJ,OAAO,KAAQ,CAkO3B;AAED;;;;GAIG;AACH,6BAHW,MAAM,GACJ,OAAO,CAAC,MAAO,IAAI,CAAC,CAiBhC;AAED;;;;;GAKG;AACH,+BAJW,MAAM,kBAEJ,OAAO,CAAC,OAAO,CAAC,CA6B5B;AAiID;;;;GAIG;AACH,+BAHW,MAAM,GACJ,OAAO,CAAC,OAAO,CAAC,CAmB5B;AAED;;;GAGG;AACH,sDA2CC;AAED;;;GAGG;AACH,oDAoCC;AAuKD;;;GAGG;AACH,yCAFa,OAAO,CAAC,MAAM,CAAC,CAqC3B;AAhzBD;;GAEG;AACH,wBAAkB,aAAa,CAAC;AAChC,6BAAuB,2BAA2B,CAAC"}

package/dist/commands/worktree.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Handle worktree subcommands
+ * @param {string} subcommand - Subcommand name
+ * @param {Object} options - Command options
+ */
+export function worktreeCommand(subcommand: string, options?: any): Promise<void>;
+//# sourceMappingURL=worktree.d.ts.map

package/dist/commands/worktree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktree.d.ts","sourceRoot":"","sources":["../../src/commands/worktree.js"],"names":[],"mappings":"AAcA;;;;GAIG;AACH,4CAHW,MAAM,gCAuBhB"}

package/dist/commands/worktree.js

@@ -0,0 +1,136 @@
+/**
+ * @fileoverview CAWS Worktree CLI Command
+ * Manages git worktrees for agent scope isolation
+ * @author @darianrosebrook
+ */
+
+const chalk = require('chalk');
+const {
+  createWorktree,
+  listWorktrees,
+  destroyWorktree,
+  pruneWorktrees,
+} = require('../worktree/worktree-manager');
+
+/**
+ * Handle worktree subcommands
+ * @param {string} subcommand - Subcommand name
+ * @param {Object} options - Command options
+ */
+async function worktreeCommand(subcommand, options = {}) {
+  try {
+    switch (subcommand) {
+      case 'create':
+        return handleCreate(options);
+      case 'list':
+        return handleList();
+      case 'destroy':
+        return handleDestroy(options);
+      case 'prune':
+        return handlePrune(options);
+      default:
+        console.error(chalk.red(`Unknown worktree subcommand: ${subcommand}`));
+        console.log(chalk.blue('Available: create, list, destroy, prune'));
+        process.exit(1);
+    }
+  } catch (error) {
+    console.error(chalk.red(`❌ ${error.message}`));
+    process.exit(1);
+  }
+}
+
+function handleCreate(options) {
+  const { name, scope, baseBranch, specId } = options;
+
+  if (!name) {
+    console.error(chalk.red('❌ Worktree name is required'));
+    console.log(chalk.blue('Usage: caws worktree create <name> [--scope "src/auth/**"]'));
+    process.exit(1);
+  }
+
+  console.log(chalk.cyan(`🌿 Creating worktree: ${name}`));
+
+  const entry = createWorktree(name, { scope, baseBranch, specId });
+
+  console.log(chalk.green(`✅ Worktree created`));
+  console.log(chalk.gray(`   Path:   ${entry.path}`));
+  console.log(chalk.gray(`   Branch: ${entry.branch}`));
+  if (entry.scope) console.log(chalk.gray(`   Scope:  ${entry.scope}`));
+  if (entry.specId) console.log(chalk.gray(`   Spec:   ${entry.specId}`));
+  console.log(chalk.blue(`\n💡 cd ${entry.path} to start working in the isolated worktree`));
+}
+
+function handleList() {
+  const entries = listWorktrees();
+
+  if (entries.length === 0) {
+    console.log(chalk.gray('No worktrees registered.'));
+    console.log(chalk.blue('Create one with: caws worktree create <name>'));
+    return;
+  }
+
+  console.log(chalk.bold.cyan('🌿 CAWS Worktrees'));
+  console.log(chalk.cyan('━'.repeat(70)));
+  console.log(
+    chalk.bold(
+      'Name'.padEnd(20) +
+        'Status'.padEnd(12) +
+        'Branch'.padEnd(20) +
+        'Scope'
+    )
+  );
+  console.log(chalk.gray('─'.repeat(70)));
+
+  for (const entry of entries) {
+    const statusColor =
+      entry.status === 'active'
+        ? chalk.green
+        : entry.status === 'destroyed'
+        ? chalk.gray
+        : chalk.yellow;
+
+    console.log(
+      entry.name.padEnd(20) +
+        statusColor(entry.status.padEnd(12)) +
+        (entry.branch || '').padEnd(20) +
+        (entry.scope || '-')
+    );
+  }
+
+  console.log('');
+}
+
+function handleDestroy(options) {
+  const { name, deleteBranch, force } = options;
+
+  if (!name) {
+    console.error(chalk.red('❌ Worktree name is required'));
+    console.log(chalk.blue('Usage: caws worktree destroy <name> [--delete-branch] [--force]'));
+    process.exit(1);
+  }
+
+  console.log(chalk.cyan(`🗑️  Destroying worktree: ${name}`));
+  destroyWorktree(name, { deleteBranch, force });
+  console.log(chalk.green(`✅ Worktree '${name}' destroyed`));
+  if (deleteBranch) {
+    console.log(chalk.gray('   Branch also deleted'));
+  }
+}
+
+function handlePrune(options) {
+  const maxAge = options.maxAge !== undefined ? parseInt(options.maxAge, 10) : 30;
+
+  console.log(chalk.cyan(`🧹 Pruning worktrees (max age: ${maxAge} days)`));
+  const pruned = pruneWorktrees({ maxAgeDays: maxAge });
+
+  if (pruned.length === 0) {
+    console.log(chalk.gray('Nothing to prune.'));
+  } else {
+    console.log(chalk.green(`✅ Pruned ${pruned.length} worktree(s):`));
+    for (const entry of pruned) {
+      console.log(chalk.gray(`   - ${entry.name} (created ${entry.createdAt})`));
+    }
+  }
+}
+
+module.exports = { worktreeCommand };

package/dist/config/lite-scope.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Load lite scope configuration from .caws/scope.json
+ * @param {string} [projectRoot] - Project root directory (defaults to cwd)
+ * @returns {Object} Scope configuration (defaults if file not found)
+ */
+export function loadLiteScope(projectRoot?: string): any;
+/**
+ * Check if a file path is allowed by the scope configuration
+ * @param {string} filePath - Relative file path to check
+ * @param {Object} [scope] - Scope configuration (loads from disk if not provided)
+ * @param {string} [projectRoot] - Project root directory
+ * @returns {boolean} Whether the path is allowed
+ */
+export function isPathAllowed(filePath: string, scope?: any, projectRoot?: string): boolean;
+/**
+ * Check if a filename or path matches any banned pattern
+ * @param {string} filePath - File path to check
+ * @param {Object} [scope] - Scope configuration (loads from disk if not provided)
+ * @param {string} [projectRoot] - Project root directory
+ * @returns {{ matched: boolean, pattern: string|null, category: string|null }} Match result
+ */
+export function matchesBannedPattern(filePath: string, scope?: any, projectRoot?: string): {
+    matched: boolean;
+    pattern: string | null;
+    category: string | null;
+};
+/**
+ * Default scope configuration for lite mode
+ * @returns {Object} Default scope.json contents
+ */
+export function getLiteScopeDefaults(): any;
+export const SCOPE_FILE: ".caws/scope.json";
+//# sourceMappingURL=lite-scope.d.ts.map

package/dist/config/lite-scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lite-scope.d.ts","sourceRoot":"","sources":["../../src/config/lite-scope.js"],"names":[],"mappings":"AA8BA;;;;GAIG;AACH,4CAHW,MAAM,OAgChB;AAED;;;;;;GAMG;AACH,wCALW,MAAM,6BAEN,MAAM,GACJ,OAAO,CAiCnB;AAED;;;;;;GAMG;AACH,+CALW,MAAM,6BAEN,MAAM,GACJ;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,GAAC,IAAI,CAAC;IAAC,QAAQ,EAAE,MAAM,GAAC,IAAI,CAAA;CAAE,CAsC7E;AAzID;;;GAGG;AACH,4CAYC;AAlBD,yBAAmB,kBAAkB,CAAC"}