sqlew 3.2.5 → 3.6.0

package/dist/watcher/file-watcher.d.ts

@@ -2,11 +2,13 @@
  * File Watcher - Auto-tracking file changes linked to tasks
  * Monitors files and auto-transitions task status on file modification
  *
- * Features:
- * - chokidar-based file watching with debouncing
+ * Features (v3.5.1):
+ * - chokidar v4 file watching with automatic WSL support
+ * - Project root watching with .gitignore support
  * - Dynamic file registration (add/remove files at runtime)
  * - Auto-transition: todo → in_progress on file change
  * - Maps file paths → task IDs for efficient lookup
+ * - Respects .gitignore patterns and built-in ignore rules
  */
 /**
  * FileWatcher class - Singleton pattern
@@ -18,13 +20,22 @@ export declare class FileWatcher {
     private isRunning;
     private debounceTimers;
     private readonly DEBOUNCE_MS;
+    private gitignoreParser;
+    private projectRoot;
+    private lastModifiedTimes;
+    private filesModifiedSet;
+    private vcsDetectionInterval;
     private constructor();
     /**
      * Get singleton instance
      */
     static getInstance(): FileWatcher;
     /**
-     * Initialize and start the file watcher
+     * Detect if running on WSL (Windows Subsystem for Linux)
+     */
+    private isWSL;
+    /**
+     * Initialize and start the file watcher (v3.5.1 - Chokidar v4)
      */
     start(): Promise<void>;
     /**
@@ -43,10 +54,38 @@ export declare class FileWatcher {
      * Unregister all files for a specific task
      */
     unregisterTask(taskId: number): void;
+    /**
+     * Check if a path is a VCS index file
+     */
+    private isVCSIndexFile;
+    /**
+     * Get VCS index file path for given VCS type (v3.5.3)
+     * Centralized mapping for easier extension to Mercurial/SVN
+     * @param vcsType - VCS type string (Git, Mercurial, SVN)
+     * @returns Absolute path to VCS index file, or null if VCS has no local index
+     */
+    private getVCSIndexPath;
+    /**
+     * Re-detect VCS and start watching index files (v3.5.3)
+     * Called when VCS might be initialized after watcher starts
+     * Public method for external triggering (e.g., after git init)
+     */
+    refreshVCSWatching(): Promise<void>;
+    /**
+     * Watch VCS index files for commit detection
+     */
+    private watchVCSIndexFiles;
     /**
      * Handle file change event
      */
     private handleFileChange;
+    /**
+     * Handle VCS index file change - triggers two-step Git-aware workflow (v3.5.2)
+     * Step 1: Staging (git add) → waiting_review → done
+     * Step 2: Commit (git commit) → done → archived
+     * Fallback: If files already committed (not in staging), use v3.4.0 logic
+     */
+    private handleVCSIndexChange;
     /**
      * Check acceptance criteria and auto-complete task if all pass
      */
@@ -56,13 +95,24 @@ export declare class FileWatcher {
      */
     private loadTaskFileLinks;
     /**
-     * Normalize file path (resolve relative paths, remove trailing slashes)
+     * Normalize file path (convert to relative path from project root, remove trailing slashes)
      */
     private normalizePath;
     /**
      * Get total count of tasks being watched
      */
     private getTotalTaskCount;
+    /**
+     * Check if task is ready for review and transition if conditions met
+     * Quality gates:
+     * - All watched files modified at least once
+     * - TypeScript compiles without errors (if .ts files)
+     * - Tests pass (if test files exist)
+     * - Idle for configured time (default 15 minutes)
+     *
+     * @param taskId - Task ID to check
+     */
+    private checkAndTransitionToReview;
     /**
      * Get current watcher status
      */

package/dist/watcher/file-watcher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file-watcher.d.ts","sourceRoot":"","sources":["../../src/watcher/file-watcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAkBH;;GAEG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAA4B;IACnD,OAAO,CAAC,OAAO,CAA0B;IACzC,OAAO,CAAC,YAAY,CAA6C;IACjE,OAAO,CAAC,SAAS,CAAkB;IACnC,OAAO,CAAC,cAAc,CAA0C;IAChE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAQ;IAEpC,OAAO;IAIP;;OAEG;WACW,WAAW,IAAI,WAAW;IAOxC;;OAEG;IACU,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA2CnC;;OAEG;IACU,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAwBlC;;OAEG;IACI,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI;IAwCrG;;OAEG;IACI,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAuB7D;;OAEG;IACI,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAgB3C;;OAEG;YACW,gBAAgB;IAwE9B;;OAEG;YACW,uBAAuB;IA2FrC;;OAEG;YACW,iBAAiB;IAqC/B;;OAEG;IACH,OAAO,CAAC,aAAa;IAUrB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAQzB;;OAEG;IACI,SAAS,IAAI;QAClB,OAAO,EAAE,OAAO,CAAC;QACjB,YAAY,EAAE,MAAM,CAAC;QACrB,YAAY,EAAE,MAAM,CAAC;KACtB;CAOF"}
+{"version":3,"file":"file-watcher.d.ts","sourceRoot":"","sources":["../../src/watcher/file-watcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAqCH;;GAEG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAA4B;IACnD,OAAO,CAAC,OAAO,CAA0B;IACzC,OAAO,CAAC,YAAY,CAA6C;IACjE,OAAO,CAAC,SAAS,CAAkB;IACnC,OAAO,CAAC,cAAc,CAA0C;IAChE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAQ;IACpC,OAAO,CAAC,eAAe,CAAgC;IACvD,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,iBAAiB,CAAkC;IAC3D,OAAO,CAAC,gBAAgB,CAAuC;IAC/D,OAAO,CAAC,oBAAoB,CAA+B;IAE3D,OAAO;IAMP;;OAEG;WACW,WAAW,IAAI,WAAW;IAOxC;;OAEG;IACH,OAAO,CAAC,KAAK;IASb;;OAEG;IACU,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAsFnC;;OAEG;IACU,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAkClC;;OAEG;IACI,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI;IA4BrG;;OAEG;IACI,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAoB7D;;OAEG;IACI,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAgB3C;;OAEG;IACH,OAAO,CAAC,cAAc;IAatB;;;;;OAKG;IACH,OAAO,CAAC,eAAe;IAUvB;;;;OAIG;IACU,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC;IAUhD;;OAEG;YACW,kBAAkB;IAyBhC;;OAEG;YACW,gBAAgB;IAuF9B;;;;;OAKG;YACW,oBAAoB;IAsClC;;OAEG;YACW,uBAAuB;IA2FrC;;OAEG;YACW,iBAAiB;IAqC/B;;OAEG;IACH,OAAO,CAAC,aAAa;IAkBrB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAQzB;;;;;;;;;OASG;YACW,0BAA0B;IA6GxC;;OAEG;IACI,SAAS,IAAI;QAClB,OAAO,EAAE,OAAO,CAAC;QACjB,YAAY,EAAE,MAAM,CAAC;QACrB,YAAY,EAAE,MAAM,CAAC;KACtB;CAOF"}

package/dist/watcher/file-watcher.js

@@ -2,17 +2,37 @@
  * File Watcher - Auto-tracking file changes linked to tasks
  * Monitors files and auto-transitions task status on file modification
  *
- * Features:
- * - chokidar-based file watching with debouncing
+ * Features (v3.5.1):
+ * - chokidar v4 file watching with automatic WSL support
+ * - Project root watching with .gitignore support
  * - Dynamic file registration (add/remove files at runtime)
  * - Auto-transition: todo → in_progress on file change
  * - Maps file paths → task IDs for efficient lookup
+ * - Respects .gitignore patterns and built-in ignore rules
  */
 import chokidar from 'chokidar';
-import { getDatabase } from '../database.js';
-import { basename, dirname } from 'path';
+import { getAdapter, getConfigInt, getConfigBool } from '../database.js';
+import { SQLiteAdapter } from '../adapters/index.js';
+import { basename, join } from 'path';
 import { existsSync } from 'fs';
+import { execSync } from 'child_process';
 import { executeAcceptanceCriteria } from './test-executor.js';
+import { createGitIgnoreParser } from './gitignore-parser.js';
+import { checkReadyForReview } from '../utils/quality-checks.js';
+import { CONFIG_KEYS } from '../constants.js';
+import { detectAndCompleteReviewedTasks, detectAndCompleteOnStaging, detectAndArchiveOnCommit } from '../utils/task-stale-detection.js';
+import { detectVCS } from '../utils/vcs-adapter.js';
+/**
+ * Helper to get raw better-sqlite3 Database instance from adapter
+ * For legacy code that uses db.prepare() directly
+ */
+function getRawDb() {
+    const adapter = getAdapter();
+    if (adapter instanceof SQLiteAdapter) {
+        return adapter.getRawDatabase();
+    }
+    throw new Error('File watcher only supported for SQLite adapter');
+}
 /**
  * FileWatcher class - Singleton pattern
  */
@@ -23,8 +43,15 @@ export class FileWatcher {
     isRunning = false;
     debounceTimers = new Map();
     DEBOUNCE_MS = 2000; // Wait 2s after last write
+    gitignoreParser = null;
+    projectRoot;
+    lastModifiedTimes = new Map(); // taskId -> timestamp
+    filesModifiedSet = new Map(); // taskId -> modified files
+    vcsDetectionInterval = null; // Periodic VCS re-detection (v3.5.3)
     constructor() {
         // Private constructor for singleton
+        // Determine project root (current working directory)
+        this.projectRoot = process.cwd();
     }
     /**
      * Get singleton instance
@@ -36,7 +63,19 @@ export class FileWatcher {
         return FileWatcher.instance;
     }
     /**
-     * Initialize and start the file watcher
+     * Detect if running on WSL (Windows Subsystem for Linux)
+     */
+    isWSL() {
+        try {
+            const result = execSync('uname -r', { encoding: 'utf-8' });
+            return result.toLowerCase().includes('microsoft') || result.toLowerCase().includes('wsl');
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Initialize and start the file watcher (v3.5.1 - Chokidar v4)
      */
     async start() {
         if (this.isRunning) {
@@ -44,31 +83,71 @@ export class FileWatcher {
             return;
         }
         try {
-            // Initialize chokidar with debouncing
-            this.watcher = chokidar.watch([], {
+            // Initialize gitignore parser
+            this.gitignoreParser = createGitIgnoreParser(this.projectRoot);
+            // Detect WSL (informational only - chokidar v4 handles WSL automatically)
+            const isWSL = this.isWSL();
+            if (isWSL) {
+                console.error('✓ WSL detected - chokidar v4 handles WSL automatically');
+            }
+            // Initialize chokidar v4 with debouncing and gitignore support
+            // NOTE: Chokidar v4 automatically detects and handles WSL without manual polling configuration
+            this.watcher = chokidar.watch(this.projectRoot, {
                 persistent: true,
                 ignoreInitial: true, // Don't trigger on startup
                 awaitWriteFinish: {
                     stabilityThreshold: this.DEBOUNCE_MS,
                     pollInterval: 100
                 },
-                ignored: /(^|[\/\\])\../, // Ignore dotfiles
+                ignored: (path) => {
+                    // Use gitignore parser to filter files
+                    if (this.gitignoreParser) {
+                        return this.gitignoreParser.shouldIgnore(path);
+                    }
+                    // Fallback: ignore dotfiles
+                    return /(^|[\/\\])\./.test(path);
+                },
             });
             // Set up event handlers
             this.watcher.on('change', (path) => {
-                this.handleFileChange(path);
+                // Check if this is a VCS index file
+                if (this.isVCSIndexFile(path)) {
+                    this.handleVCSIndexChange(path);
+                }
+                else {
+                    this.handleFileChange(path);
+                }
             });
             this.watcher.on('add', (path) => {
-                this.handleFileChange(path);
+                // Check if this is a VCS index file
+                if (this.isVCSIndexFile(path)) {
+                    this.handleVCSIndexChange(path);
+                }
+                else {
+                    this.handleFileChange(path);
+                }
             });
             this.watcher.on('error', (error) => {
                 console.error('File watcher error:', error);
             });
             // Load existing task-file links from database
             await this.loadTaskFileLinks();
+            // Initialize tracking maps
+            this.lastModifiedTimes.clear();
+            this.filesModifiedSet.clear();
+            // Watch VCS index files for commit detection (v3.4.0 VCS-aware auto-complete)
+            await this.watchVCSIndexFiles();
+            // Periodic VCS re-detection (v3.5.3)
+            // Handles case where git is initialized after watcher starts
+            // Check every 5 minutes for new VCS initialization
+            this.vcsDetectionInterval = setInterval(async () => {
+                await this.refreshVCSWatching();
+            }, 5 * 60 * 1000); // 5 minutes
             this.isRunning = true;
             console.error('✓ File watcher started successfully');
+            console.error(`  Project root: ${this.projectRoot}`);
             console.error(`  Watching ${this.watchedFiles.size} files for ${this.getTotalTaskCount()} tasks`);
+            console.error(`  .gitignore patterns loaded: ${existsSync(this.projectRoot + '/.gitignore') ? 'Yes' : 'No'}`);
         }
         catch (error) {
             console.error('Failed to start file watcher:', error);
@@ -86,6 +165,14 @@ export class FileWatcher {
             // Clear all debounce timers
             this.debounceTimers.forEach(timer => clearTimeout(timer));
             this.debounceTimers.clear();
+            // Clear tracking maps
+            this.lastModifiedTimes.clear();
+            this.filesModifiedSet.clear();
+            // Clear VCS detection interval (v3.5.3)
+            if (this.vcsDetectionInterval) {
+                clearInterval(this.vcsDetectionInterval);
+                this.vcsDetectionInterval = null;
+            }
             // Close watcher
             if (this.watcher) {
                 await this.watcher.close();
@@ -112,18 +199,6 @@ export class FileWatcher {
         // Add to watched files map
         if (!this.watchedFiles.has(normalizedPath)) {
             this.watchedFiles.set(normalizedPath, []);
-            // Check if file exists
-            if (existsSync(normalizedPath)) {
-                // File exists - watch it directly
-                this.watcher.add(normalizedPath);
-                console.error(`  Watching file: ${basename(normalizedPath)} for task #${taskId}`);
-            }
-            else {
-                // File doesn't exist - watch parent directory
-                const parentDir = dirname(normalizedPath);
-                this.watcher.add(parentDir);
-                console.error(`  Watching directory: ${parentDir} for task #${taskId} (file doesn't exist yet)`);
-            }
         }
         const mappings = this.watchedFiles.get(normalizedPath);
         // Check if task already registered for this file
@@ -152,10 +227,7 @@ export class FileWatcher {
         if (filtered.length === 0) {
             // No more tasks watching this file
             this.watchedFiles.delete(normalizedPath);
-            if (this.watcher) {
-                this.watcher.unwatch(normalizedPath);
-            }
-            console.error(`  Stopped watching: ${basename(normalizedPath)}`);
+            console.error(`  Removed task mapping for: ${basename(normalizedPath)}`);
         }
         else {
             this.watchedFiles.set(normalizedPath, filtered);
@@ -177,6 +249,72 @@ export class FileWatcher {
             this.unregisterFile(filePath, taskId);
         });
     }
+    /**
+     * Check if a path is a VCS index file
+     */
+    isVCSIndexFile(path) {
+        // Git index file
+        if (path.endsWith('.git/index') || path.endsWith('.git\\index')) {
+            return true;
+        }
+        // Mercurial dirstate file
+        if (path.endsWith('.hg/dirstate') || path.endsWith('.hg\\dirstate')) {
+            return true;
+        }
+        // SVN doesn't have a local index file that changes on commit
+        return false;
+    }
+    /**
+     * Get VCS index file path for given VCS type (v3.5.3)
+     * Centralized mapping for easier extension to Mercurial/SVN
+     * @param vcsType - VCS type string (Git, Mercurial, SVN)
+     * @returns Absolute path to VCS index file, or null if VCS has no local index
+     */
+    getVCSIndexPath(vcsType) {
+        const vcsIndexPaths = {
+            'Git': join(this.projectRoot, '.git', 'index'),
+            'Mercurial': join(this.projectRoot, '.hg', 'dirstate'),
+            'SVN': null, // SVN has no local index file (commits are remote)
+        };
+        return vcsIndexPaths[vcsType] || null;
+    }
+    /**
+     * Re-detect VCS and start watching index files (v3.5.3)
+     * Called when VCS might be initialized after watcher starts
+     * Public method for external triggering (e.g., after git init)
+     */
+    async refreshVCSWatching() {
+        if (!this.watcher || !this.isRunning) {
+            console.error('⚠ Cannot refresh VCS watching: watcher not running');
+            return;
+        }
+        console.error('\n🔍 Re-detecting VCS...');
+        await this.watchVCSIndexFiles();
+    }
+    /**
+     * Watch VCS index files for commit detection
+     */
+    async watchVCSIndexFiles() {
+        // Detect VCS type
+        const vcsAdapter = await detectVCS(this.projectRoot);
+        if (!vcsAdapter) {
+            console.error('ℹ No VCS detected - skipping VCS index watching');
+            return;
+        }
+        const vcsType = vcsAdapter.getVCSType();
+        const indexPath = this.getVCSIndexPath(vcsType);
+        if (indexPath === null) {
+            console.error(`ℹ ${vcsType} detected - no local index file to watch (commits are remote)`);
+            return;
+        }
+        if (existsSync(indexPath) && this.watcher) {
+            this.watcher.add(indexPath);
+            console.error(`✓ Watching ${indexPath} for ${vcsType} commits (v3.5.3)`);
+        }
+        else if (!existsSync(indexPath)) {
+            console.error(`⚠ ${vcsType} index file not found: ${indexPath}`);
+        }
+    }
     /**
      * Handle file change event
      */
@@ -187,10 +325,17 @@ export class FileWatcher {
             return;
         }
         console.error(`\n📝 File changed: ${basename(normalizedPath)}`);
-        const db = getDatabase();
+        const adapter = getAdapter();
+        const db = getRawDb();
         // Process each task linked to this file
         for (const mapping of mappings) {
             const { taskId, taskTitle, currentStatus } = mapping;
+            // Track file modification
+            this.lastModifiedTimes.set(taskId, Date.now());
+            if (!this.filesModifiedSet.has(taskId)) {
+                this.filesModifiedSet.set(taskId, new Set());
+            }
+            this.filesModifiedSet.get(taskId).add(normalizedPath);
             // Auto-transition: todo → in_progress
             if (currentStatus === 'todo') {
                 try {
@@ -231,17 +376,62 @@ export class FileWatcher {
             // Check acceptance criteria for in_progress tasks
             if (currentStatus === 'in_progress' || mapping.currentStatus === 'in_progress') {
                 await this.checkAcceptanceCriteria(taskId, taskTitle, mapping);
+                // After debounce period, check if task is ready for review
+                // Use setTimeout to check after idle period
+                const idleMinutes = await getConfigInt(adapter, CONFIG_KEYS.REVIEW_IDLE_MINUTES, 15);
+                setTimeout(async () => {
+                    await this.checkAndTransitionToReview(taskId);
+                }, idleMinutes * 60 * 1000);
             }
             else {
                 console.error(`  • Task #${taskId} "${taskTitle}": status ${currentStatus}`);
             }
         }
     }
+    /**
+     * Handle VCS index file change - triggers two-step Git-aware workflow (v3.5.2)
+     * Step 1: Staging (git add) → waiting_review → done
+     * Step 2: Commit (git commit) → done → archived
+     * Fallback: If files already committed (not in staging), use v3.4.0 logic
+     */
+    async handleVCSIndexChange(filePath) {
+        console.error('\n🔄 VCS index changed - checking for tasks ready to auto-transition');
+        const db = getAdapter();
+        try {
+            // Step 1: Check for staged files → complete tasks (waiting_review → done)
+            const stagingCompleted = await detectAndCompleteOnStaging(db);
+            // Step 2: Check for committed files → archive tasks (done → archived)
+            const commitArchived = await detectAndArchiveOnCommit(db);
+            // Fallback: Check for committed files → complete tasks (waiting_review → done)
+            // This handles cases where files go straight to commit without visible staging
+            const commitCompleted = await detectAndCompleteReviewedTasks(db);
+            // Log results
+            const transitions = [];
+            if (stagingCompleted > 0) {
+                transitions.push(`${stagingCompleted} task(s) completed (git add detected)`);
+            }
+            if (commitCompleted > 0) {
+                transitions.push(`${commitCompleted} task(s) completed (git commit fallback)`);
+            }
+            if (commitArchived > 0) {
+                transitions.push(`${commitArchived} task(s) archived (git commit detected)`);
+            }
+            if (transitions.length > 0) {
+                console.error(`  ✓ ${transitions.join(', ')}`);
+            }
+            else {
+                console.error(`  ℹ No tasks ready for auto-transition`);
+            }
+        }
+        catch (error) {
+            console.error(`  ✗ Error during VCS-aware auto-transition:`, error);
+        }
+    }
     /**
      * Check acceptance criteria and auto-complete task if all pass
      */
     async checkAcceptanceCriteria(taskId, taskTitle, mapping) {
-        const db = getDatabase();
+        const db = getRawDb();
         try {
             // Get acceptance criteria JSON
             const taskDetails = db.prepare(`
@@ -313,7 +503,7 @@ export class FileWatcher {
      * Load existing task-file links from database
      */
     async loadTaskFileLinks() {
-        const db = getDatabase();
+        const db = getRawDb();
         try {
             // Query all active tasks with file links
             const query = `
@@ -341,13 +531,21 @@ export class FileWatcher {
         }
     }
     /**
-     * Normalize file path (resolve relative paths, remove trailing slashes)
+     * Normalize file path (convert to relative path from project root, remove trailing slashes)
      */
     normalizePath(filePath) {
-        // Remove trailing slashes
-        let normalized = filePath.replace(/[\/\\]+$/, '');
         // Convert backslashes to forward slashes (Windows compatibility)
-        normalized = normalized.replace(/\\/g, '/');
+        let normalized = filePath.replace(/\\/g, '/');
+        // Remove trailing slashes
+        normalized = normalized.replace(/[\/\\]+$/, '');
+        // Convert absolute paths to relative paths from project root
+        const projectRootNormalized = this.projectRoot.replace(/\\/g, '/');
+        if (normalized.startsWith(projectRootNormalized + '/')) {
+            normalized = normalized.substring(projectRootNormalized.length + 1);
+        }
+        else if (normalized.startsWith(projectRootNormalized)) {
+            normalized = normalized.substring(projectRootNormalized.length);
+        }
         return normalized;
     }
     /**
@@ -360,6 +558,104 @@ export class FileWatcher {
         });
         return taskIds.size;
     }
+    /**
+     * Check if task is ready for review and transition if conditions met
+     * Quality gates:
+     * - All watched files modified at least once
+     * - TypeScript compiles without errors (if .ts files)
+     * - Tests pass (if test files exist)
+     * - Idle for configured time (default 15 minutes)
+     *
+     * @param taskId - Task ID to check
+     */
+    async checkAndTransitionToReview(taskId) {
+        const adapter = getAdapter();
+        const db = getRawDb();
+        try {
+            // Get current task status
+            const task = db.prepare(`
+        SELECT t.status_id, s.name as status_name, td.acceptance_criteria_json
+        FROM t_tasks t
+        JOIN m_task_statuses s ON s.id = t.status_id
+        LEFT JOIN t_task_details td ON td.task_id = t.id
+        WHERE t.id = ?
+      `).get(taskId);
+            if (!task) {
+                return; // Task not found
+            }
+            // Only check for in_progress tasks
+            if (task.status_name !== 'in_progress') {
+                return;
+            }
+            // Read configuration
+            const idleMinutes = await getConfigInt(adapter, CONFIG_KEYS.REVIEW_IDLE_MINUTES, 15);
+            const requireAllFilesModified = await getConfigBool(adapter, CONFIG_KEYS.REVIEW_REQUIRE_ALL_FILES_MODIFIED, true);
+            const requireTestsPass = await getConfigBool(adapter, CONFIG_KEYS.REVIEW_REQUIRE_TESTS_PASS, true);
+            const requireCompile = await getConfigBool(adapter, CONFIG_KEYS.REVIEW_REQUIRE_COMPILE, true);
+            // Check idle time
+            const lastModified = this.lastModifiedTimes.get(taskId);
+            if (!lastModified) {
+                return; // No modifications tracked yet
+            }
+            const idleTimeMs = Date.now() - lastModified;
+            const requiredIdleMs = idleMinutes * 60 * 1000;
+            if (idleTimeMs < requiredIdleMs) {
+                return; // Not idle long enough
+            }
+            // Get all watched files for this task
+            const filePaths = [];
+            this.watchedFiles.forEach((mappings, path) => {
+                if (mappings.some(m => m.taskId === taskId)) {
+                    filePaths.push(path);
+                }
+            });
+            if (filePaths.length === 0) {
+                return; // No files being watched
+            }
+            // Get modified files set
+            const modifiedFiles = this.filesModifiedSet.get(taskId) || new Set();
+            // Run quality checks
+            const { ready, results } = await checkReadyForReview(db, taskId, filePaths, modifiedFiles, {
+                requireAllFilesModified,
+                requireTestsPass,
+                requireCompile,
+            });
+            if (ready) {
+                // All quality gates passed - transition to waiting_review
+                console.error(`  ✓ Quality checks passed for task #${taskId}`);
+                // Log individual results
+                results.forEach(({ check, result }) => {
+                    console.error(`    • ${check}: ${result.message}`);
+                });
+                // Update task status
+                db.prepare(`
+          UPDATE t_tasks
+          SET status_id = (SELECT id FROM m_task_statuses WHERE name = 'waiting_review'),
+              updated_ts = unixepoch()
+          WHERE id = ?
+        `).run(taskId);
+                console.error(`  → Task #${taskId} auto-transitioned to waiting_review`);
+                // Clear tracking for this task
+                this.lastModifiedTimes.delete(taskId);
+                this.filesModifiedSet.delete(taskId);
+            }
+            else {
+                // Some checks failed - log details
+                const failedChecks = results.filter(({ result }) => !result.passed);
+                console.error(`  ℹ Task #${taskId} not ready for review (${failedChecks.length} checks failed)`);
+                failedChecks.forEach(({ check, result }) => {
+                    console.error(`    • ${check}: ${result.message}`);
+                    if (result.details) {
+                        console.error(`      ${result.details}`);
+                    }
+                });
+            }
+        }
+        catch (error) {
+            // Log error but don't crash the watcher
+            console.error(`Error checking review readiness for task #${taskId}:`, error);
+        }
+    }
     /**
      * Get current watcher status
      */