@paths.design/caws-cli 9.1.1 → 9.3.0

package/dist/utils/spec-resolver.js

@@ -12,6 +12,7 @@ const chalk = require('chalk');
 
 // Import SPEC_TYPES from constants for consistent display
 const { SPEC_TYPES } = require('../constants/spec-types');
+const { findProjectRoot } = require('./detection');
 
 /**
  * Spec resolution priority:
@@ -22,6 +23,18 @@ const SPECS_DIR = '.caws/specs';
 const LEGACY_SPEC = '.caws/working-spec.yaml';
 const SPECS_REGISTRY = '.caws/specs/registry.json';
 
+/**
+ * Get the project root for spec resolution.
+ * Caches per process to avoid repeated filesystem walks.
+ */
+let _cachedProjectRoot = null;
+function getProjectRoot() {
+  if (!_cachedProjectRoot) {
+    _cachedProjectRoot = findProjectRoot();
+  }
+  return _cachedProjectRoot;
+}
+
 /**
  * Resolve spec file path based on priority
  * @param {Object} options - Resolution options
@@ -36,7 +49,7 @@ async function resolveSpec(options = {}) {
 
   // 1. Explicit file path takes highest priority
   if (specFile) {
-    const explicitPath = path.isAbsolute(specFile) ? specFile : path.join(process.cwd(), specFile);
+    const explicitPath = path.isAbsolute(specFile) ? specFile : path.join(getProjectRoot(), specFile);
 
     if (await fs.pathExists(explicitPath)) {
       const yaml = require('js-yaml');
@@ -55,7 +68,7 @@ async function resolveSpec(options = {}) {
 
   // 2. Feature-specific spec (preferred for multi-agent)
   if (specId) {
-    const featurePath = path.join(process.cwd(), SPECS_DIR, `${specId}.yaml`);
+    const featurePath = path.join(getProjectRoot(), SPECS_DIR, `${specId}.yaml`);
 
     if (await fs.pathExists(featurePath)) {
       const yaml = require('js-yaml');
@@ -83,7 +96,7 @@ async function resolveSpec(options = {}) {
   if (specIds.length === 1) {
     // Single spec - use it automatically
     const singleSpecId = specIds[0];
-    const singleSpecPath = path.join(process.cwd(), SPECS_DIR, registry.specs[singleSpecId].path);
+    const singleSpecPath = path.join(getProjectRoot(), SPECS_DIR, registry.specs[singleSpecId].path);
 
     if (await fs.pathExists(singleSpecPath)) {
       const yaml = require('js-yaml');
@@ -179,7 +192,7 @@ async function resolveSpec(options = {}) {
   }
 
   // 4. Fall back to legacy working-spec.yaml (with warning)
-  const legacyPath = path.join(process.cwd(), LEGACY_SPEC);
+  const legacyPath = path.join(getProjectRoot(), LEGACY_SPEC);
 
   if (await fs.pathExists(legacyPath)) {
     const yaml = require('js-yaml');
@@ -211,7 +224,7 @@ async function resolveSpec(options = {}) {
  * @returns {Promise<Object>} Registry data
  */
 async function loadSpecsRegistry() {
-  const registryPath = path.join(process.cwd(), SPECS_REGISTRY);
+  const registryPath = path.join(getProjectRoot(), SPECS_REGISTRY);
 
   if (!(await fs.pathExists(registryPath))) {
     return {
@@ -241,7 +254,7 @@ async function listAvailableSpecs() {
   const specs = [];
 
   // Check feature-specific specs
-  const specsDir = path.join(process.cwd(), SPECS_DIR);
+  const specsDir = path.join(getProjectRoot(), SPECS_DIR);
   if (await fs.pathExists(specsDir)) {
     const files = await fs.readdir(specsDir);
     const yamlFiles = files.filter((f) => f.endsWith('.yaml') || f.endsWith('.yml'));
@@ -257,7 +270,7 @@ async function listAvailableSpecs() {
 
         specs.push({
           id: spec.id || path.basename(file, path.extname(file)),
-          path: path.relative(process.cwd(), specPath),
+          path: path.relative(getProjectRoot(), specPath),
           type: 'feature',
           title: spec.title || 'Untitled',
         });
@@ -268,7 +281,7 @@ async function listAvailableSpecs() {
   }
 
   // Check legacy working-spec.yaml
-  const legacyPath = path.join(process.cwd(), LEGACY_SPEC);
+  const legacyPath = path.join(getProjectRoot(), LEGACY_SPEC);
   if (await fs.pathExists(legacyPath)) {
     try {
       const yaml = require('js-yaml');
@@ -342,7 +355,7 @@ async function interactiveSpecSelection(specIds) {
 async function checkMultiSpecStatus() {
   const registry = await loadSpecsRegistry();
   const hasFeatureSpecs = Object.keys(registry.specs ?? {}).length > 0;
-  const legacyPath = path.join(process.cwd(), LEGACY_SPEC);
+  const legacyPath = path.join(getProjectRoot(), LEGACY_SPEC);
   const hasLegacySpec = await fs.pathExists(legacyPath);
 
   return {
@@ -374,7 +387,7 @@ async function checkScopeConflicts(specIds) {
       try {
         spec = yaml.load(content);
       } catch (yamlError) {
-        const relativePath = path.relative(process.cwd(), specPath);
+        const relativePath = path.relative(getProjectRoot(), specPath);
         throw new Error(
           `Invalid YAML syntax in ${relativePath}: ${yamlError.message}\n` +
             (yamlError.mark

package/dist/validation/spec-validation.js

@@ -85,6 +85,14 @@ const validateWorkingSpec = (spec, _options = {}) => {
     // For new policy-based specs, change_budget is not required
     // It's derived from policy.yaml + waivers
 
+    // Normalize risk_tier: accept "T1"/"T2"/"T3" strings and convert to numeric
+    if (spec.risk_tier !== undefined && typeof spec.risk_tier === 'string') {
+      const match = spec.risk_tier.match(/^T?(\d)$/i);
+      if (match) {
+        spec.risk_tier = parseInt(match[1], 10);
+      }
+    }
+
     for (const field of requiredFields) {
       if (!spec[field]) {
         return {

package/dist/worktree/worktree-manager.js

@@ -13,6 +13,46 @@ const WORKTREES_DIR = '.caws/worktrees';
 const REGISTRY_FILE = '.caws/worktrees.json';
 const BRANCH_PREFIX = 'caws/';
 
+/**
+ * Get the last commit info for a branch
+ * @param {string} branch - Branch name
+ * @param {string} root - Repository root
+ * @returns {{ age: string, timestamp: Date, sha: string } | null}
+ */
+function getLastCommitInfo(branch, root) {
+  try {
+    const output = execFileSync(
+      'git',
+      ['log', branch, '-1', '--format=%H%n%aI%n%ar'],
+      { cwd: root, encoding: 'utf8', stdio: 'pipe' }
+    ).trim();
+    const [sha, iso, age] = output.split('\n');
+    return { sha, timestamp: new Date(iso), age };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check if a branch has been merged into another branch
+ * @param {string} branch - Branch to check
+ * @param {string} target - Target branch (e.g., "main")
+ * @param {string} root - Repository root
+ * @returns {boolean}
+ */
+function isBranchMerged(branch, target, root) {
+  try {
+    const merged = execFileSync(
+      'git',
+      ['branch', '--merged', target, '--list', branch],
+      { cwd: root, encoding: 'utf8', stdio: 'pipe' }
+    ).trim();
+    return merged.length > 0;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Get the git repository root
  * @returns {string} Absolute path to repo root
@@ -250,10 +290,21 @@ function listWorktrees() {
     const inGit = gitWorktrees.some(
       (wt) => path.resolve(wt) === path.resolve(entry.path)
     );
+    const status = exists && inGit ? 'active' : exists ? 'orphaned' : 'missing';
+
+    // Enrich with commit recency
+    const lastCommit = entry.branch ? getLastCommitInfo(entry.branch, root) : null;
+
+    // Check if branch is already merged to base
+    const merged = entry.branch && entry.baseBranch
+      ? isBranchMerged(entry.branch, entry.baseBranch, root)
+      : false;
 
     return {
       ...entry,
-      status: exists && inGit ? 'active' : exists ? 'orphaned' : 'missing',
+      status,
+      lastCommit,
+      merged,
     };
   });
 
@@ -277,16 +328,62 @@ function destroyWorktree(name, options = {}) {
     throw new Error(`Worktree '${name}' not found in registry`);
   }
 
+  // Ownership check: refuse to destroy another agent's active worktree without --force
+  const currentSession = process.env.CLAUDE_SESSION_ID || null;
+  if (
+    !force &&
+    entry.status === 'active' &&
+    entry.owner &&
+    currentSession &&
+    entry.owner !== currentSession
+  ) {
+    const lastCommit = entry.branch ? getLastCommitInfo(entry.branch, root) : null;
+    const recency = lastCommit ? ` (last commit: ${lastCommit.age})` : '';
+    throw new Error(
+      `Worktree '${name}' belongs to another session${recency}.\n` +
+        `   Owner: ${entry.owner}\n` +
+        `   You:   ${currentSession}\n` +
+        `Another agent may be actively working here.\n` +
+        `Do NOT destroy worktrees you did not create. Ask the user if cleanup is needed.`
+    );
+  }
+
+  // Even with --force, warn loudly when destroying another session's worktree
+  if (
+    force &&
+    entry.status === 'active' &&
+    entry.owner &&
+    currentSession &&
+    entry.owner !== currentSession
+  ) {
+    const lastCommit = entry.branch ? getLastCommitInfo(entry.branch, root) : null;
+    const recency = lastCommit ? ` (last commit: ${lastCommit.age})` : '';
+    console.log(chalk.red(`\n   ⚠ WARNING: Force-destroying worktree '${name}' owned by another session${recency}`));
+    console.log(chalk.red(`   Owner: ${entry.owner}`));
+    console.log(chalk.red(`   You:   ${currentSession}`));
+    console.log(chalk.red(`   If the other agent is still running, this WILL break their work.\n`));
+  }
+
+  // Auto-force when the branch is already merged to its base branch.
+  // Dirty files in a merged worktree are definitionally stale.
+  const merged = entry.branch && entry.baseBranch
+    ? isBranchMerged(entry.branch, entry.baseBranch, root)
+    : false;
+  const effectiveForce = force || merged;
+  if (merged && !force) {
+    console.log(chalk.gray(`   Branch ${entry.branch} already merged to ${entry.baseBranch}, auto-forcing cleanup`));
+  }
+
   // Remove git worktree — handle already-deleted directories gracefully
   const dirExists = fs.existsSync(entry.path);
   if (dirExists) {
     try {
       const args = ['worktree', 'remove'];
-      if (force) args.push('--force');
+      if (effectiveForce) args.push('--force');
       args.push(entry.path);
       execFileSync('git', args, { cwd: root, stdio: 'pipe' });
     } catch (error) {
-      if (force) {
+      if (effectiveForce) {
         // Force cleanup: remove directory manually
         fs.removeSync(entry.path);
       } else {
@@ -310,7 +407,7 @@ function destroyWorktree(name, options = {}) {
     try {
       execFileSync('git', ['branch', '-d', entry.branch], { cwd: root, stdio: 'pipe' });
     } catch {
-      if (force) {
+      if (effectiveForce) {
         try {
           execFileSync('git', ['branch', '-D', entry.branch], { cwd: root, stdio: 'pipe' });
         } catch {
@@ -326,19 +423,143 @@ function destroyWorktree(name, options = {}) {
   saveRegistry(root, registry);
 }
 
+/**
+ * Merge a worktree branch back to base in one operation.
+ * Sequence: dry-run conflict check → destroy worktree → merge → cleanup.
+ * @param {string} name - Worktree name
+ * @param {Object} options - Merge options
+ * @param {boolean} [options.dryRun] - Preview conflicts without merging
+ * @param {boolean} [options.deleteBranch] - Delete branch after merge
+ * @param {string} [options.message] - Custom merge commit message
+ * @returns {Object} Merge result
+ */
+function mergeWorktree(name, options = {}) {
+  const root = getRepoRoot();
+  const registry = loadRegistry(root);
+  const { dryRun = false, deleteBranch = true, message } = options;
+
+  const entry = registry.worktrees[name];
+  if (!entry) {
+    throw new Error(`Worktree '${name}' not found in registry`);
+  }
+
+  const baseBranch = entry.baseBranch || 'main';
+
+  // Check for uncommitted work in the worktree
+  if (fs.existsSync(entry.path)) {
+    try {
+      const status = execFileSync(
+        'git',
+        ['status', '--porcelain'],
+        { cwd: entry.path, encoding: 'utf8', stdio: 'pipe' }
+      ).trim();
+      if (status) {
+        throw new Error(
+          `Worktree '${name}' has uncommitted changes:\n${status}\n` +
+            `Commit or discard changes before merging.`
+        );
+      }
+    } catch (error) {
+      if (error.message.includes('uncommitted changes')) throw error;
+      // Non-fatal: status check failed, proceed cautiously
+    }
+  }
+
+  // Dry-run: check for conflicts using git merge-tree (new-style, git 2.38+)
+  let conflicts = [];
+  try {
+    // New-style merge-tree: takes two branches, computes merge-base automatically
+    const mergeTreeResult = execFileSync(
+      'git',
+      ['merge-tree', '--write-tree', baseBranch, entry.branch],
+      { cwd: root, encoding: 'utf8', stdio: 'pipe' }
+    );
+    // Exit 0 = clean merge, no conflicts
+  } catch (mergeTreeError) {
+    // Exit 1 = conflicts detected; parse them from output
+    const output = (mergeTreeError.stdout || '') + (mergeTreeError.stderr || '');
+    const conflictLines = output.split('\n').filter(
+      (l) => l.includes('CONFLICT') || l.includes('conflict')
+    );
+    if (mergeTreeError.status === 1 && conflictLines.length > 0) {
+      conflicts = conflictLines;
+    } else if (mergeTreeError.status === 1) {
+      conflicts = ['Merge conflicts detected (run merge manually to inspect)'];
+    }
+    // Other exit codes (e.g., merge-tree not supported) = can't detect, proceed
+  }
+
+  if (dryRun) {
+    return {
+      name,
+      branch: entry.branch,
+      baseBranch,
+      conflicts,
+      wouldMerge: conflicts.length === 0,
+    };
+  }
+
+  // Destroy the worktree (auto-forces since we're about to merge)
+  destroyWorktree(name, { deleteBranch: false, force: true });
+
+  // Switch to base branch
+  const currentBranch = getCurrentBranch();
+  if (currentBranch !== baseBranch) {
+    execFileSync('git', ['checkout', baseBranch], { cwd: root, stdio: 'pipe' });
+  }
+
+  // Merge
+  const mergeMessage = message || `merge(worktree): ${name}`;
+  try {
+    execFileSync(
+      'git',
+      ['merge', '--no-ff', entry.branch, '-m', mergeMessage],
+      { cwd: root, stdio: 'pipe' }
+    );
+  } catch (error) {
+    return {
+      name,
+      branch: entry.branch,
+      baseBranch,
+      merged: false,
+      conflicts: [`Merge failed: ${error.message}`],
+      message: 'Merge conflicts detected. Resolve with git and commit.',
+    };
+  }
+
+  // Delete branch after successful merge
+  if (deleteBranch) {
+    try {
+      execFileSync('git', ['branch', '-d', entry.branch], { cwd: root, stdio: 'pipe' });
+    } catch {
+      // Non-fatal
+    }
+  }
+
+  return {
+    name,
+    branch: entry.branch,
+    baseBranch,
+    merged: true,
+    conflicts: [],
+  };
+}
+
 /**
  * Prune stale worktree entries
  * @param {Object} options - Prune options
  * @param {number} [options.maxAgeDays] - Remove entries older than this many days
+ * @param {number} [options.recentCommitMinutes] - Protect branches with commits newer than this (default: 60)
  * @returns {Array} Pruned entries
  */
 function pruneWorktrees(options = {}) {
   const root = getRepoRoot();
   const registry = loadRegistry(root);
-  const { maxAgeDays = 30 } = options;
+  const { maxAgeDays = 30, recentCommitMinutes = 60 } = options;
 
   const now = new Date();
   const pruned = [];
+  const skipped = [];
 
   for (const [name, entry] of Object.entries(registry.worktrees)) {
     const created = new Date(entry.createdAt);
@@ -354,6 +575,18 @@ function pruneWorktrees(options = {}) {
       (!dirExists && ageDays > maxAgeDays);
 
     if (shouldPrune) {
+      // Before pruning a non-destroyed entry, check for recent commits
+      if (entry.status !== 'destroyed' && entry.branch) {
+        const lastCommit = getLastCommitInfo(entry.branch, root);
+        if (lastCommit) {
+          const commitAgeMinutes = (now - lastCommit.timestamp) / (1000 * 60);
+          if (commitAgeMinutes < recentCommitMinutes) {
+            skipped.push({ name, reason: `recent commit (${lastCommit.age})`, entry });
+            continue;
+          }
+        }
+      }
+
       // Clean up filesystem if still exists
       if (dirExists) {
         try {
@@ -378,16 +611,19 @@ function pruneWorktrees(options = {}) {
   }
 
   saveRegistry(root, registry);
-  return pruned;
+  return { pruned, skipped };
 }
 
 module.exports = {
   createWorktree,
   listWorktrees,
   destroyWorktree,
+  mergeWorktree,
   pruneWorktrees,
   loadRegistry,
   getRepoRoot,
+  getLastCommitInfo,
+  isBranchMerged,
   WORKTREES_DIR,
   REGISTRY_FILE,
   BRANCH_PREFIX,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paths.design/caws-cli",
-  "version": "9.1.1",
+  "version": "9.3.0",
   "description": "CAWS CLI - Coding Agent Workflow System command-line tools for spec management, quality gates, and AI-assisted development",
   "main": "dist/index.js",
   "bin": {

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

@@ -4,18 +4,15 @@ 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.
+Checks whether a file is within scope of active working-spec and feature specs. Used by Cursor hooks for scope validation on file attachments.
 
 ```bash
-# Validate experimental code containment
-node .caws/tools/scope-guard.js validate
+# Check if a file is in scope
+node .caws/tools/scope-guard.js check src/index.js
 
-# Check containment status
-node .caws/tools/scope-guard.js check .caws/working-spec.yaml
+# Exit code 0 = in scope, 1 = out of scope
 ```
 
 **Usage in Cursor Hooks:**
 
 The `.cursor/hooks/scope-guard.sh` hook automatically uses this tool to validate file attachments against working spec scope boundaries.
-
-