sqlew 3.2.5 → 3.5.3

package/dist/tools/tasks.js

@@ -3,7 +3,7 @@
  * Implements create, update, get, list, move, link, archive, batch_create actions
  */
 import { getDatabase, getOrCreateAgent, getOrCreateTag, getOrCreateContextKey, getLayerId, getOrCreateFile, transaction } from '../database.js';
-import { detectAndTransitionStaleTasks } from '../utils/task-stale-detection.js';
+import { detectAndTransitionStaleTasks, autoArchiveOldDoneTasks, detectAndCompleteReviewedTasks, detectAndArchiveOnCommit } from '../utils/task-stale-detection.js';
 import { processBatch } from '../utils/batch.js';
 import { FileWatcher } from '../watcher/index.js';
 import { validatePriorityRange, validateLength, validateRange } from '../utils/validators.js';
@@ -79,10 +79,10 @@ function createTaskInternal(params, db) {
     if (params.assigned_agent) {
         assignedAgentId = getOrCreateAgent(db, params.assigned_agent);
     }
-    let createdByAgentId = null;
-    if (params.created_by_agent) {
-        createdByAgentId = getOrCreateAgent(db, params.created_by_agent);
-    }
+    // Default to 'system' if no created_by_agent provided
+    // This ensures the activity log trigger has a valid agent_id
+    const createdBy = params.created_by_agent || 'system';
+    const createdByAgentId = getOrCreateAgent(db, createdBy);
     // Insert task
     const insertTaskStmt = db.prepare(`
     INSERT INTO t_tasks (title, status_id, priority, assigned_agent_id, created_by_agent_id, layer_id)
@@ -144,6 +144,62 @@ function createTaskInternal(params, db) {
             insertTagStmt.run(taskId, tagId);
         }
     }
+    // Link files and register with watcher if watch_files provided (v3.4.1)
+    if (params.watch_files && params.watch_files.length > 0) {
+        // Parse watch_files - handle MCP SDK converting JSON string to char array
+        let watchFilesParsed;
+        if (typeof params.watch_files === 'string') {
+            // String - try to parse as JSON
+            try {
+                watchFilesParsed = JSON.parse(params.watch_files);
+            }
+            catch {
+                // If not valid JSON, treat as single file path
+                watchFilesParsed = [params.watch_files];
+            }
+        }
+        else if (Array.isArray(params.watch_files)) {
+            // Check if it's an array of single characters (MCP SDK bug)
+            // Example: ['[', '"', 'f', 'i', 'l', 'e', '.', 't', 'x', 't', '"', ']']
+            if (params.watch_files.every((item) => typeof item === 'string' && item.length === 1)) {
+                // Join characters back into string and parse JSON
+                const jsonString = params.watch_files.join('');
+                try {
+                    watchFilesParsed = JSON.parse(jsonString);
+                }
+                catch (e) {
+                    const errMsg = e instanceof Error ? e.message : String(e);
+                    throw new Error(`Invalid watch_files format: ${jsonString}. ${errMsg}`);
+                }
+            }
+            else {
+                // Normal array of file paths
+                watchFilesParsed = params.watch_files;
+            }
+        }
+        else {
+            throw new Error('Parameter "watch_files" must be a string or array');
+        }
+        const insertFileLinkStmt = db.prepare(`
+      INSERT OR IGNORE INTO t_task_file_links (task_id, file_id)
+      VALUES (?, ?)
+    `);
+        for (const filePath of watchFilesParsed) {
+            const fileId = getOrCreateFile(db, filePath);
+            insertFileLinkStmt.run(taskId, fileId);
+        }
+        // Register files with watcher for auto-tracking
+        try {
+            const watcher = FileWatcher.getInstance();
+            for (const filePath of watchFilesParsed) {
+                watcher.registerFile(filePath, taskId, params.title, status);
+            }
+        }
+        catch (error) {
+            // Watcher may not be initialized yet, ignore
+            console.error('Warning: Could not register files with watcher:', error);
+        }
+    }
     return {
         success: true,
         task_id: taskId,
@@ -155,16 +211,16 @@ function createTaskInternal(params, db) {
 /**
  * Create a new task
  */
-export function createTask(params) {
-    const db = getDatabase();
+export function createTask(params, db) {
+    const actualDb = db ?? getDatabase();
     // Validate required parameters
     if (!params.title || params.title.trim() === '') {
         throw new Error('Parameter "title" is required and cannot be empty');
     }
     validateLength(params.title, 'Parameter "title"', 200);
     try {
-        return transaction(db, () => {
-            return createTaskInternal(params, db);
+        return transaction(actualDb, () => {
+            return createTaskInternal(params, actualDb);
         });
     }
     catch (error) {
@@ -175,16 +231,16 @@ export function createTask(params) {
 /**
  * Update task metadata
  */
-export function updateTask(params) {
-    const db = getDatabase();
+export function updateTask(params, db) {
+    const actualDb = db ?? getDatabase();
     // Validate required parameters
     if (!params.task_id) {
         throw new Error('Parameter "task_id" is required');
     }
     try {
-        return transaction(db, () => {
+        return transaction(actualDb, () => {
             // Check if task exists
-            const taskExists = db.prepare('SELECT id FROM t_tasks WHERE id = ?').get(params.task_id);
+            const taskExists = actualDb.prepare('SELECT id FROM t_tasks WHERE id = ?').get(params.task_id);
             if (!taskExists) {
                 throw new Error(`Task with id ${params.task_id} not found`);
             }
@@ -205,12 +261,12 @@ export function updateTask(params) {
                 updateParams.push(params.priority);
             }
             if (params.assigned_agent !== undefined) {
-                const agentId = getOrCreateAgent(db, params.assigned_agent);
+                const agentId = getOrCreateAgent(actualDb, params.assigned_agent);
                 updates.push('assigned_agent_id = ?');
                 updateParams.push(agentId);
             }
             if (params.layer !== undefined) {
-                const layerId = getLayerId(db, params.layer);
+                const layerId = getLayerId(actualDb, params.layer);
                 if (layerId === null) {
                     throw new Error(`Invalid layer: ${params.layer}. Must be one of: presentation, business, data, infrastructure, cross-cutting`);
                 }
@@ -219,7 +275,7 @@ export function updateTask(params) {
             }
             // Update t_tasks if any updates
             if (updates.length > 0) {
-                const updateStmt = db.prepare(`
+                const updateStmt = actualDb.prepare(`
           UPDATE t_tasks
           SET ${updates.join(', ')}
           WHERE id = ?
@@ -266,7 +322,7 @@ export function updateTask(params) {
                     }
                 }
                 // Check if details exist
-                const detailsExist = db.prepare('SELECT task_id FROM t_task_details WHERE task_id = ?').get(params.task_id);
+                const detailsExist = actualDb.prepare('SELECT task_id FROM t_task_details WHERE task_id = ?').get(params.task_id);
                 if (detailsExist) {
                     // Update existing details
                     const detailUpdates = [];
@@ -288,7 +344,7 @@ export function updateTask(params) {
                         detailParams.push(params.notes || null);
                     }
                     if (detailUpdates.length > 0) {
-                        const updateDetailsStmt = db.prepare(`
+                        const updateDetailsStmt = actualDb.prepare(`
               UPDATE t_task_details
               SET ${detailUpdates.join(', ')}
               WHERE task_id = ?
@@ -298,13 +354,75 @@ export function updateTask(params) {
                 }
                 else {
                     // Insert new details
-                    const insertDetailsStmt = db.prepare(`
+                    const insertDetailsStmt = actualDb.prepare(`
             INSERT INTO t_task_details (task_id, description, acceptance_criteria, acceptance_criteria_json, notes)
             VALUES (?, ?, ?, ?, ?)
           `);
                     insertDetailsStmt.run(params.task_id, params.description || null, acceptanceCriteriaString !== undefined ? acceptanceCriteriaString : null, acceptanceCriteriaJson !== undefined ? acceptanceCriteriaJson : null, params.notes || null);
                 }
             }
+            // Handle watch_files if provided (v3.4.1)
+            if (params.watch_files && params.watch_files.length > 0) {
+                // Parse watch_files - handle MCP SDK converting JSON string to char array
+                let watchFilesParsed;
+                if (typeof params.watch_files === 'string') {
+                    // String - try to parse as JSON
+                    try {
+                        watchFilesParsed = JSON.parse(params.watch_files);
+                    }
+                    catch {
+                        // If not valid JSON, treat as single file path
+                        watchFilesParsed = [params.watch_files];
+                    }
+                }
+                else if (Array.isArray(params.watch_files)) {
+                    // Check if it's an array of single characters (MCP SDK bug)
+                    if (params.watch_files.every((item) => typeof item === 'string' && item.length === 1)) {
+                        // Join characters back into string and parse JSON
+                        const jsonString = params.watch_files.join('');
+                        try {
+                            watchFilesParsed = JSON.parse(jsonString);
+                        }
+                        catch {
+                            throw new Error(`Invalid watch_files format: ${jsonString}`);
+                        }
+                    }
+                    else {
+                        // Normal array of file paths
+                        watchFilesParsed = params.watch_files;
+                    }
+                }
+                else {
+                    throw new Error('Parameter "watch_files" must be a string or array');
+                }
+                const insertFileLinkStmt = actualDb.prepare(`
+          INSERT OR IGNORE INTO t_task_file_links (task_id, file_id)
+          VALUES (?, ?)
+        `);
+                for (const filePath of watchFilesParsed) {
+                    const fileId = getOrCreateFile(actualDb, filePath);
+                    insertFileLinkStmt.run(params.task_id, fileId);
+                }
+                // Register files with watcher for auto-tracking
+                try {
+                    const taskData = actualDb.prepare(`
+            SELECT t.title, s.name as status
+            FROM t_tasks t
+            JOIN m_task_statuses s ON t.status_id = s.id
+            WHERE t.id = ?
+          `).get(params.task_id);
+                    if (taskData) {
+                        const watcher = FileWatcher.getInstance();
+                        for (const filePath of watchFilesParsed) {
+                            watcher.registerFile(filePath, params.task_id, taskData.title, taskData.status);
+                        }
+                    }
+                }
+                catch (error) {
+                    // Watcher may not be initialized yet, ignore
+                    console.error('Warning: Could not register files with watcher:', error);
+                }
+            }
             return {
                 success: true,
                 task_id: params.task_id,
@@ -372,14 +490,14 @@ function queryTaskDependencies(db, taskId, includeDetails = false) {
 /**
  * Get full task details
  */
-export function getTask(params) {
-    const db = getDatabase();
+export function getTask(params, db) {
+    const actualDb = db ?? getDatabase();
     if (!params.task_id) {
         throw new Error('Parameter "task_id" is required');
     }
     try {
         // Get task with details
-        const stmt = db.prepare(`
+        const stmt = actualDb.prepare(`
       SELECT
         t.id,
         t.title,
@@ -410,7 +528,7 @@ export function getTask(params) {
             };
         }
         // Get tags
-        const tagsStmt = db.prepare(`
+        const tagsStmt = actualDb.prepare(`
       SELECT tg.name
       FROM t_task_tags tt
       JOIN m_tags tg ON tt.tag_id = tg.id
@@ -418,7 +536,7 @@ export function getTask(params) {
     `);
         const tags = tagsStmt.all(params.task_id).map((row) => row.name);
         // Get decision links
-        const decisionsStmt = db.prepare(`
+        const decisionsStmt = actualDb.prepare(`
       SELECT ck.key, tdl.link_type
       FROM t_task_decision_links tdl
       JOIN m_context_keys ck ON tdl.decision_key_id = ck.id
@@ -426,7 +544,7 @@ export function getTask(params) {
     `);
         const decisions = decisionsStmt.all(params.task_id);
         // Get constraint links
-        const constraintsStmt = db.prepare(`
+        const constraintsStmt = actualDb.prepare(`
       SELECT c.id, c.constraint_text
       FROM t_task_constraint_links tcl
       JOIN t_constraints c ON tcl.constraint_id = c.id
@@ -434,7 +552,7 @@ export function getTask(params) {
     `);
         const constraints = constraintsStmt.all(params.task_id);
         // Get file links
-        const filesStmt = db.prepare(`
+        const filesStmt = actualDb.prepare(`
       SELECT f.path
       FROM t_task_file_links tfl
       JOIN m_files f ON tfl.file_id = f.id
@@ -454,7 +572,7 @@ export function getTask(params) {
         };
         // Include dependencies if requested (token-efficient, metadata-only)
         if (params.include_dependencies) {
-            const deps = queryTaskDependencies(db, params.task_id, false);
+            const deps = queryTaskDependencies(actualDb, params.task_id, false);
             result.task.dependencies = {
                 blockers: deps.blockers,
                 blocking: deps.blocking
@@ -470,11 +588,14 @@ export function getTask(params) {
 /**
  * List tasks (token-efficient, no descriptions)
  */
-export function listTasks(params = {}) {
-    const db = getDatabase();
+export async function listTasks(params = {}, db) {
+    const actualDb = db ?? getDatabase();
     try {
-        // Run auto-stale detection before listing
-        const transitionCount = detectAndTransitionStaleTasks(db);
+        // Run auto-stale detection, git-aware completion, and auto-archive before listing
+        const transitionCount = detectAndTransitionStaleTasks(actualDb);
+        const gitCompletedCount = await detectAndCompleteReviewedTasks(actualDb);
+        const gitArchivedCount = await detectAndArchiveOnCommit(actualDb);
+        const archiveCount = autoArchiveOldDoneTasks(actualDb);
         // Build query with optional dependency counts
         let query;
         if (params.include_dependency_counts) {
@@ -538,12 +659,15 @@ export function listTasks(params = {}) {
         query += ' LIMIT ? OFFSET ?';
         queryParams.push(limit, offset);
         // Execute query
-        const stmt = db.prepare(query);
+        const stmt = actualDb.prepare(query);
         const rows = stmt.all(...queryParams);
         return {
             tasks: rows,
             count: rows.length,
-            stale_tasks_transitioned: transitionCount
+            stale_tasks_transitioned: transitionCount,
+            git_auto_completed: gitCompletedCount,
+            git_archived: gitArchivedCount,
+            archived_tasks: archiveCount
         };
     }
     catch (error) {
@@ -554,8 +678,8 @@ export function listTasks(params = {}) {
 /**
  * Move task to different status
  */
-export function moveTask(params) {
-    const db = getDatabase();
+export function moveTask(params, db) {
+    const actualDb = db ?? getDatabase();
     if (!params.task_id) {
         throw new Error('Parameter "task_id" is required');
     }
@@ -563,11 +687,12 @@ export function moveTask(params) {
         throw new Error('Parameter "new_status" is required');
     }
     try {
-        // Run auto-stale detection before move
-        detectAndTransitionStaleTasks(db);
-        return transaction(db, () => {
+        // Run auto-stale detection and auto-archive before move
+        detectAndTransitionStaleTasks(actualDb);
+        autoArchiveOldDoneTasks(actualDb);
+        return transaction(actualDb, () => {
             // Get current status
-            const taskRow = db.prepare('SELECT status_id FROM t_tasks WHERE id = ?').get(params.task_id);
+            const taskRow = actualDb.prepare('SELECT status_id FROM t_tasks WHERE id = ?').get(params.task_id);
             if (!taskRow) {
                 throw new Error(`Task with id ${params.task_id} not found`);
             }
@@ -583,7 +708,7 @@ export function moveTask(params) {
                     `Valid transitions: ${validNextStatuses.map(id => ID_TO_STATUS[id]).join(', ')}`);
             }
             // Update status
-            const updateStmt = db.prepare(`
+            const updateStmt = actualDb.prepare(`
         UPDATE t_tasks
         SET status_id = ?,
             completed_ts = CASE WHEN ? = 5 THEN unixepoch() ELSE completed_ts END
@@ -617,8 +742,8 @@ export function moveTask(params) {
 /**
  * Link task to decision/constraint/file
  */
-export function linkTask(params) {
-    const db = getDatabase();
+export function linkTask(params, db) {
+    const actualDb = db ?? getDatabase();
     if (!params.task_id) {
         throw new Error('Parameter "task_id" is required');
     }
@@ -629,17 +754,17 @@ export function linkTask(params) {
         throw new Error('Parameter "target_id" is required');
     }
     try {
-        return transaction(db, () => {
+        return transaction(actualDb, () => {
             // Check if task exists
-            const taskExists = db.prepare('SELECT id FROM t_tasks WHERE id = ?').get(params.task_id);
+            const taskExists = actualDb.prepare('SELECT id FROM t_tasks WHERE id = ?').get(params.task_id);
             if (!taskExists) {
                 throw new Error(`Task with id ${params.task_id} not found`);
             }
             if (params.link_type === 'decision') {
                 const decisionKey = String(params.target_id);
-                const keyId = getOrCreateContextKey(db, decisionKey);
+                const keyId = getOrCreateContextKey(actualDb, decisionKey);
                 const linkRelation = params.link_relation || 'implements';
-                const stmt = db.prepare(`
+                const stmt = actualDb.prepare(`
           INSERT OR REPLACE INTO t_task_decision_links (task_id, decision_key_id, link_type)
           VALUES (?, ?, ?)
         `);
@@ -656,11 +781,11 @@ export function linkTask(params) {
             else if (params.link_type === 'constraint') {
                 const constraintId = Number(params.target_id);
                 // Check if constraint exists
-                const constraintExists = db.prepare('SELECT id FROM t_constraints WHERE id = ?').get(constraintId);
+                const constraintExists = actualDb.prepare('SELECT id FROM t_constraints WHERE id = ?').get(constraintId);
                 if (!constraintExists) {
                     throw new Error(`Constraint with id ${constraintId} not found`);
                 }
-                const stmt = db.prepare(`
+                const stmt = actualDb.prepare(`
           INSERT OR IGNORE INTO t_task_constraint_links (task_id, constraint_id)
           VALUES (?, ?)
         `);
@@ -674,16 +799,20 @@ export function linkTask(params) {
                 };
             }
             else if (params.link_type === 'file') {
+                // Deprecation warning (v3.4.1)
+                console.warn(`⚠️  DEPRECATION WARNING: task.link(link_type="file") is deprecated as of v3.4.1.`);
+                console.warn(`   Use task.create(watch_files=[...]) or task.update(watch_files=[...]) instead.`);
+                console.warn(`   Or use the new watch_files action: { action: "watch_files", task_id: ${params.task_id}, file_paths: ["..."] }`);
                 const filePath = String(params.target_id);
-                const fileId = getOrCreateFile(db, filePath);
-                const stmt = db.prepare(`
+                const fileId = getOrCreateFile(actualDb, filePath);
+                const stmt = actualDb.prepare(`
           INSERT OR IGNORE INTO t_task_file_links (task_id, file_id)
           VALUES (?, ?)
         `);
                 stmt.run(params.task_id, fileId);
                 // Register file with watcher for auto-tracking
                 try {
-                    const taskData = db.prepare(`
+                    const taskData = actualDb.prepare(`
             SELECT t.title, s.name as status
             FROM t_tasks t
             JOIN m_task_statuses s ON t.status_id = s.id
@@ -703,7 +832,8 @@ export function linkTask(params) {
                     task_id: params.task_id,
                     linked_to: 'file',
                     target: filePath,
-                    message: `Task ${params.task_id} linked to file "${filePath}"`
+                    deprecation_warning: 'task.link(link_type="file") is deprecated. Use task.create/update(watch_files) or watch_files action instead.',
+                    message: `Task ${params.task_id} linked to file "${filePath}" (DEPRECATED API - use watch_files instead)`
                 };
             }
             else {
@@ -719,15 +849,15 @@ export function linkTask(params) {
 /**
  * Archive completed task
  */
-export function archiveTask(params) {
-    const db = getDatabase();
+export function archiveTask(params, db) {
+    const actualDb = db ?? getDatabase();
     if (!params.task_id) {
         throw new Error('Parameter "task_id" is required');
     }
     try {
-        return transaction(db, () => {
+        return transaction(actualDb, () => {
             // Check if task is in 'done' status
-            const taskRow = db.prepare('SELECT status_id FROM t_tasks WHERE id = ?').get(params.task_id);
+            const taskRow = actualDb.prepare('SELECT status_id FROM t_tasks WHERE id = ?').get(params.task_id);
             if (!taskRow) {
                 throw new Error(`Task with id ${params.task_id} not found`);
             }
@@ -735,7 +865,7 @@ export function archiveTask(params) {
                 throw new Error(`Task ${params.task_id} must be in 'done' status to archive (current: ${ID_TO_STATUS[taskRow.status_id]})`);
             }
             // Update to archived
-            const updateStmt = db.prepare('UPDATE t_tasks SET status_id = ? WHERE id = ?');
+            const updateStmt = actualDb.prepare('UPDATE t_tasks SET status_id = ? WHERE id = ?');
             updateStmt.run(TASK_STATUS.ARCHIVED, params.task_id);
             // Unregister from file watcher (archived tasks don't need tracking)
             try {
@@ -760,8 +890,8 @@ export function archiveTask(params) {
 /**
  * Add dependency (blocking relationship) between tasks
  */
-export function addDependency(params) {
-    const db = getDatabase();
+export function addDependency(params, db) {
+    const actualDb = db ?? getDatabase();
     if (!params.blocker_task_id) {
         throw new Error('Parameter "blocker_task_id" is required');
     }
@@ -769,14 +899,14 @@ export function addDependency(params) {
         throw new Error('Parameter "blocked_task_id" is required');
     }
     try {
-        return transaction(db, () => {
+        return transaction(actualDb, () => {
             // Validation 1: No self-dependencies
             if (params.blocker_task_id === params.blocked_task_id) {
                 throw new Error('Self-dependency not allowed');
             }
             // Validation 2: Both tasks must exist and check if archived
-            const blockerTask = db.prepare('SELECT id, status_id FROM t_tasks WHERE id = ?').get(params.blocker_task_id);
-            const blockedTask = db.prepare('SELECT id, status_id FROM t_tasks WHERE id = ?').get(params.blocked_task_id);
+            const blockerTask = actualDb.prepare('SELECT id, status_id FROM t_tasks WHERE id = ?').get(params.blocker_task_id);
+            const blockedTask = actualDb.prepare('SELECT id, status_id FROM t_tasks WHERE id = ?').get(params.blocked_task_id);
             if (!blockerTask) {
                 throw new Error(`Blocker task #${params.blocker_task_id} not found`);
             }
@@ -791,7 +921,7 @@ export function addDependency(params) {
                 throw new Error(`Cannot add dependency: Task #${params.blocked_task_id} is archived`);
             }
             // Validation 4: No direct circular (reverse relationship)
-            const reverseExists = db.prepare(`
+            const reverseExists = actualDb.prepare(`
         SELECT 1 FROM t_task_dependencies
         WHERE blocker_task_id = ? AND blocked_task_id = ?
       `).get(params.blocked_task_id, params.blocker_task_id);
@@ -799,7 +929,7 @@ export function addDependency(params) {
                 throw new Error(`Circular dependency detected: Task #${params.blocked_task_id} already blocks Task #${params.blocker_task_id}`);
             }
             // Validation 5: No transitive circular (check if adding this would create a cycle)
-            const cycleCheck = db.prepare(`
+            const cycleCheck = actualDb.prepare(`
         WITH RECURSIVE dependency_chain AS (
           -- Start from the task that would be blocked
           SELECT blocked_task_id as task_id, 1 as depth
@@ -818,7 +948,7 @@ export function addDependency(params) {
       `).get(params.blocked_task_id, params.blocker_task_id);
             if (cycleCheck) {
                 // Build cycle path for error message
-                const cyclePathResult = db.prepare(`
+                const cyclePathResult = actualDb.prepare(`
           WITH RECURSIVE dependency_chain AS (
             SELECT blocked_task_id as task_id, 1 as depth,
                    CAST(blocked_task_id AS TEXT) as path
@@ -839,7 +969,7 @@ export function addDependency(params) {
                 throw new Error(`Circular dependency detected: Task #${params.blocker_task_id} → #${cyclePath} → #${params.blocker_task_id}`);
             }
             // All validations passed - insert dependency
-            const insertStmt = db.prepare(`
+            const insertStmt = actualDb.prepare(`
         INSERT INTO t_task_dependencies (blocker_task_id, blocked_task_id)
         VALUES (?, ?)
       `);
@@ -862,8 +992,8 @@ export function addDependency(params) {
 /**
  * Remove dependency between tasks
  */
-export function removeDependency(params) {
-    const db = getDatabase();
+export function removeDependency(params, db) {
+    const actualDb = db ?? getDatabase();
     if (!params.blocker_task_id) {
         throw new Error('Parameter "blocker_task_id" is required');
     }
@@ -871,7 +1001,7 @@ export function removeDependency(params) {
         throw new Error('Parameter "blocked_task_id" is required');
     }
     try {
-        const deleteStmt = db.prepare(`
+        const deleteStmt = actualDb.prepare(`
       DELETE FROM t_task_dependencies
       WHERE blocker_task_id = ? AND blocked_task_id = ?
     `);
@@ -889,20 +1019,20 @@ export function removeDependency(params) {
 /**
  * Get dependencies for a task (bidirectional: what blocks this task, what this task blocks)
  */
-export function getDependencies(params) {
-    const db = getDatabase();
+export function getDependencies(params, db) {
+    const actualDb = db ?? getDatabase();
     if (!params.task_id) {
         throw new Error('Parameter "task_id" is required');
     }
     const includeDetails = params.include_details || false;
     try {
         // Check if task exists
-        const taskExists = db.prepare('SELECT id FROM t_tasks WHERE id = ?').get(params.task_id);
+        const taskExists = actualDb.prepare('SELECT id FROM t_tasks WHERE id = ?').get(params.task_id);
         if (!taskExists) {
             throw new Error(`Task with id ${params.task_id} not found`);
         }
         // Use the shared helper function
-        const deps = queryTaskDependencies(db, params.task_id, includeDetails);
+        const deps = queryTaskDependencies(actualDb, params.task_id, includeDetails);
         return {
             task_id: params.task_id,
             blockers: deps.blockers,
@@ -921,15 +1051,15 @@ export function getDependencies(params) {
 /**
  * Create multiple tasks atomically
  */
-export function batchCreateTasks(params) {
-    const db = getDatabase();
+export function batchCreateTasks(params, db) {
+    const actualDb = db ?? getDatabase();
     if (!params.tasks || !Array.isArray(params.tasks)) {
         throw new Error('Parameter "tasks" is required and must be an array');
     }
     const atomic = params.atomic !== undefined ? params.atomic : true;
     // Use processBatch utility
-    const batchResult = processBatch(db, params.tasks, (task, db) => {
-        const result = createTaskInternal(task, db);
+    const batchResult = processBatch(actualDb, params.tasks, (task, actualDb) => {
+        const result = createTaskInternal(task, actualDb);
         return {
             title: task.title,
             task_id: result.task_id
@@ -948,6 +1078,232 @@ export function batchCreateTasks(params) {
         }))
     };
 }
+/**
+ * Watch/unwatch files for a task (v3.4.1)
+ * Replaces the need to use task.link(file) for file watching
+ */
+export function watchFiles(params, db) {
+    const actualDb = db ?? getDatabase();
+    if (!params.task_id) {
+        throw new Error('Parameter "task_id" is required');
+    }
+    if (!params.action) {
+        throw new Error('Parameter "action" is required (watch, unwatch, or list)');
+    }
+    try {
+        return transaction(actualDb, () => {
+            // Check if task exists
+            const taskData = actualDb.prepare(`
+        SELECT t.id, t.title, s.name as status
+        FROM t_tasks t
+        JOIN m_task_statuses s ON t.status_id = s.id
+        WHERE t.id = ?
+      `).get(params.task_id);
+            if (!taskData) {
+                throw new Error(`Task with id ${params.task_id} not found`);
+            }
+            if (params.action === 'watch') {
+                if (!params.file_paths || params.file_paths.length === 0) {
+                    throw new Error('Parameter "file_paths" is required for watch action');
+                }
+                const insertFileLinkStmt = actualDb.prepare(`
+          INSERT OR IGNORE INTO t_task_file_links (task_id, file_id)
+          VALUES (?, ?)
+        `);
+                const addedFiles = [];
+                for (const filePath of params.file_paths) {
+                    const fileId = getOrCreateFile(actualDb, filePath);
+                    const result = insertFileLinkStmt.run(params.task_id, fileId);
+                    // Check if row was actually inserted (changes > 0)
+                    if (result.changes > 0) {
+                        addedFiles.push(filePath);
+                    }
+                }
+                // Register files with watcher
+                try {
+                    const watcher = FileWatcher.getInstance();
+                    for (const filePath of addedFiles) {
+                        watcher.registerFile(filePath, params.task_id, taskData.title, taskData.status);
+                    }
+                }
+                catch (error) {
+                    // Watcher may not be initialized yet, ignore
+                    console.error('Warning: Could not register files with watcher:', error);
+                }
+                return {
+                    success: true,
+                    task_id: params.task_id,
+                    action: 'watch',
+                    files_added: addedFiles.length,
+                    files: addedFiles,
+                    message: `Watching ${addedFiles.length} file(s) for task ${params.task_id}`
+                };
+            }
+            else if (params.action === 'unwatch') {
+                if (!params.file_paths || params.file_paths.length === 0) {
+                    throw new Error('Parameter "file_paths" is required for unwatch action');
+                }
+                const deleteFileLinkStmt = actualDb.prepare(`
+          DELETE FROM t_task_file_links
+          WHERE task_id = ? AND file_id = (SELECT id FROM m_files WHERE path = ?)
+        `);
+                const removedFiles = [];
+                for (const filePath of params.file_paths) {
+                    const result = deleteFileLinkStmt.run(params.task_id, filePath);
+                    // Check if row was actually deleted (changes > 0)
+                    if (result.changes > 0) {
+                        removedFiles.push(filePath);
+                    }
+                }
+                // Unregister files from watcher
+                try {
+                    const watcher = FileWatcher.getInstance();
+                    for (const filePath of removedFiles) {
+                        // Note: FileWatcher.unregisterFile doesn't exist in current API
+                        // The watcher will handle cleanup when task moves to done/archived
+                        // For now, we just remove the DB link
+                    }
+                }
+                catch (error) {
+                    // Watcher may not be initialized, ignore
+                }
+                return {
+                    success: true,
+                    task_id: params.task_id,
+                    action: 'unwatch',
+                    files_removed: removedFiles.length,
+                    files: removedFiles,
+                    message: `Stopped watching ${removedFiles.length} file(s) for task ${params.task_id}`
+                };
+            }
+            else if (params.action === 'list') {
+                const filesStmt = actualDb.prepare(`
+          SELECT f.path
+          FROM t_task_file_links tfl
+          JOIN m_files f ON tfl.file_id = f.id
+          WHERE tfl.task_id = ?
+        `);
+                const files = filesStmt.all(params.task_id).map((row) => row.path);
+                return {
+                    success: true,
+                    task_id: params.task_id,
+                    action: 'list',
+                    files_count: files.length,
+                    files: files,
+                    message: `Task ${params.task_id} is watching ${files.length} file(s)`
+                };
+            }
+            else {
+                throw new Error(`Invalid action: ${params.action}. Must be one of: watch, unwatch, list`);
+            }
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to ${params.action} files: ${message}`);
+    }
+}
+/**
+ * Get pruned files for a task (v3.5.0 Auto-Pruning)
+ * Returns audit trail of files that were auto-pruned as non-existent
+ */
+export function getPrunedFiles(params, db) {
+    const actualDb = db ?? getDatabase();
+    try {
+        // Validate task_id
+        if (!params.task_id || typeof params.task_id !== 'number') {
+            throw new Error('task_id is required and must be a number');
+        }
+        // Validate task exists
+        const task = actualDb.prepare('SELECT id FROM t_tasks WHERE id = ?').get(params.task_id);
+        if (!task) {
+            throw new Error(`Task not found: ${params.task_id}`);
+        }
+        // Get pruned files
+        const limit = params.limit || 100;
+        const rows = actualDb.prepare(`
+      SELECT
+        tpf.id,
+        tpf.file_path,
+        datetime(tpf.pruned_ts, 'unixepoch') as pruned_at,
+        k.key as linked_decision
+      FROM t_task_pruned_files tpf
+      LEFT JOIN m_context_keys k ON tpf.linked_decision_key_id = k.id
+      WHERE tpf.task_id = ?
+      ORDER BY tpf.pruned_ts DESC
+      LIMIT ?
+    `).all(params.task_id, limit);
+        return {
+            success: true,
+            task_id: params.task_id,
+            pruned_files: rows,
+            count: rows.length,
+            message: rows.length > 0
+                ? `Found ${rows.length} pruned file(s) for task ${params.task_id}`
+                : `No pruned files for task ${params.task_id}`
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to get pruned files: ${message}`);
+    }
+}
+/**
+ * Link a pruned file to a decision (v3.5.0 Auto-Pruning)
+ * Attaches WHY reasoning to pruned files for project archaeology
+ */
+export function linkPrunedFile(params, db) {
+    const actualDb = db ?? getDatabase();
+    try {
+        // Validate pruned_file_id
+        if (!params.pruned_file_id || typeof params.pruned_file_id !== 'number') {
+            throw new Error('pruned_file_id is required and must be a number');
+        }
+        // Validate decision_key
+        if (!params.decision_key || typeof params.decision_key !== 'string') {
+            throw new Error('decision_key is required and must be a string');
+        }
+        // Get decision key_id
+        const decision = actualDb.prepare(`
+      SELECT k.id as key_id
+      FROM m_context_keys k
+      WHERE k.key = ? AND EXISTS (
+        SELECT 1 FROM t_decisions d WHERE d.key_id = k.id
+      )
+    `).get(params.decision_key);
+        if (!decision) {
+            throw new Error(`Decision not found: ${params.decision_key}`);
+        }
+        // Check if pruned file exists
+        const prunedFile = actualDb.prepare(`
+      SELECT id, task_id, file_path FROM t_task_pruned_files WHERE id = ?
+    `).get(params.pruned_file_id);
+        if (!prunedFile) {
+            throw new Error(`Pruned file record not found: ${params.pruned_file_id}`);
+        }
+        // Update the link
+        const result = actualDb.prepare(`
+      UPDATE t_task_pruned_files
+      SET linked_decision_key_id = ?
+      WHERE id = ?
+    `).run(decision.key_id, params.pruned_file_id);
+        if (result.changes === 0) {
+            throw new Error(`Failed to link pruned file #${params.pruned_file_id} to decision ${params.decision_key}`);
+        }
+        return {
+            success: true,
+            pruned_file_id: params.pruned_file_id,
+            decision_key: params.decision_key,
+            task_id: prunedFile.task_id,
+            file_path: prunedFile.file_path,
+            message: `Linked pruned file "${prunedFile.file_path}" to decision "${params.decision_key}"`
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to link pruned file: ${message}`);
+    }
+}
 /**
  * Return comprehensive help documentation
  */
@@ -961,7 +1317,8 @@ export function taskHelp() {
             create: {
                 description: 'Create a new task',
                 required_params: ['title'],
-                optional_params: ['description', 'acceptance_criteria', 'notes', 'priority', 'assigned_agent', 'created_by_agent', 'layer', 'tags', 'status'],
+                optional_params: ['description', 'acceptance_criteria', 'notes', 'priority', 'assigned_agent', 'created_by_agent', 'layer', 'tags', 'status', 'watch_files'],
+                watch_files_param: '⭐ NEW in v3.4.1: Pass watch_files array to automatically link and watch files (replaces task.link(file))',
                 example: {
                     action: 'create',
                     title: 'Implement authentication endpoint',
@@ -969,18 +1326,21 @@ export function taskHelp() {
                     priority: 3,
                     assigned_agent: 'backend-agent',
                     layer: 'presentation',
-                    tags: ['api', 'authentication']
+                    tags: ['api', 'authentication'],
+                    watch_files: ['src/api/auth.ts', 'src/middleware/jwt.ts']
                 }
             },
             update: {
                 description: 'Update task metadata',
                 required_params: ['task_id'],
-                optional_params: ['title', 'priority', 'assigned_agent', 'layer', 'description', 'acceptance_criteria', 'notes'],
+                optional_params: ['title', 'priority', 'assigned_agent', 'layer', 'description', 'acceptance_criteria', 'notes', 'watch_files'],
+                watch_files_param: '⭐ NEW in v3.4.1: Pass watch_files array to add files to watch list',
                 example: {
                     action: 'update',
                     task_id: 5,
                     priority: 4,
-                    assigned_agent: 'senior-backend-agent'
+                    assigned_agent: 'senior-backend-agent',
+                    watch_files: ['src/api/users.ts']
                 }
             },
             get: {
@@ -1025,7 +1385,8 @@ export function taskHelp() {
                 required_params: ['task_id', 'link_type', 'target_id'],
                 optional_params: ['link_relation'],
                 link_types: ['decision', 'constraint', 'file'],
-                file_linking_behavior: '⚠️  IMPORTANT: When link_type="file", this action ACTIVATES AUTOMATIC FILE WATCHING. The file watcher monitors linked files for changes and validates acceptance criteria when files are saved. You can save 300 tokens per file compared to registering watchers manually.',
+                file_linking_behavior: '⚠️  DEPRECATED in v3.4.1: link_type="file" is deprecated. Use watch_files action or watch_files parameter instead.',
+                deprecation_note: 'For file watching, use: (1) watch_files parameter in create/update, or (2) watch_files action with watch/unwatch/list',
                 example: {
                     action: 'link',
                     task_id: 5,
@@ -1034,6 +1395,34 @@ export function taskHelp() {
                     link_relation: 'implements'
                 }
             },
+            watch_files: {
+                description: '⭐ NEW in v3.4.1: Watch/unwatch files for a task (replaces task.link(file))',
+                required_params: ['task_id', 'action'],
+                optional_params: ['file_paths'],
+                actions: ['watch', 'unwatch', 'list'],
+                behavior: {
+                    watch: 'Add files to watch list and activate file monitoring',
+                    unwatch: 'Remove files from watch list',
+                    list: 'List all files currently watched by this task'
+                },
+                examples: {
+                    watch: {
+                        task_id: 5,
+                        action: 'watch',
+                        file_paths: ['src/api/auth.ts', 'src/middleware/jwt.ts']
+                    },
+                    unwatch: {
+                        task_id: 5,
+                        action: 'unwatch',
+                        file_paths: ['src/middleware/jwt.ts']
+                    },
+                    list: {
+                        task_id: 5,
+                        action: 'list'
+                    }
+                },
+                note: 'Preferred over task.link(file) for better clarity and batch operations'
+            },
             archive: {
                 description: 'Archive completed task (must be in done status)',
                 required_params: ['task_id'],
@@ -1176,7 +1565,8 @@ export function taskHelp() {
 /**
  * Query file watcher status and monitored files/tasks
  */
-export function watcherStatus(args) {
+export function watcherStatus(args, db) {
+    const actualDb = db ?? getDatabase();
     const subaction = args.subaction || 'status';
     const watcher = FileWatcher.getInstance();
     if (subaction === 'help') {
@@ -1219,8 +1609,7 @@ export function watcherStatus(args) {
         };
     }
     if (subaction === 'list_files') {
-        const db = getDatabase();
-        const fileLinks = db.prepare(`
+        const fileLinks = actualDb.prepare(`
       SELECT DISTINCT tfl.file_path, t.id, t.title, ts.status_name
       FROM t_task_file_links tfl
       JOIN t_tasks t ON tfl.task_id = t.id
@@ -1254,8 +1643,7 @@ export function watcherStatus(args) {
         };
     }
     if (subaction === 'list_tasks') {
-        const db = getDatabase();
-        const taskLinks = db.prepare(`
+        const taskLinks = actualDb.prepare(`
       SELECT t.id, t.title, ts.status_name, COUNT(DISTINCT tfl.file_path) as file_count,
              GROUP_CONCAT(DISTINCT tfl.file_path, ', ') as files
       FROM t_tasks t