sqlew 3.2.5 → 3.6.0

package/dist/tools/tasks.js

@@ -1,12 +1,14 @@
 /**
  * Task management tools for Kanban Task Watcher
  * Implements create, update, get, list, move, link, archive, batch_create actions
+ *
+ * CONVERTED: Using Knex.js with DatabaseAdapter (async/await)
  */
-import { getDatabase, getOrCreateAgent, getOrCreateTag, getOrCreateContextKey, getLayerId, getOrCreateFile, transaction } from '../database.js';
-import { detectAndTransitionStaleTasks } from '../utils/task-stale-detection.js';
-import { processBatch } from '../utils/batch.js';
+import { getAdapter, getOrCreateAgent, getOrCreateTag, getOrCreateContextKey, getLayerId, getOrCreateFile } from '../database.js';
+import { detectAndTransitionStaleTasks, autoArchiveOldDoneTasks, detectAndCompleteReviewedTasks, detectAndArchiveOnCommit } from '../utils/task-stale-detection.js';
 import { FileWatcher } from '../watcher/index.js';
 import { validatePriorityRange, validateLength, validateRange } from '../utils/validators.js';
+import { logTaskCreate, logTaskStatusChange } from '../utils/activity-logging.js';
 /**
  * Task status enum (matches m_task_statuses)
  */
@@ -53,10 +55,12 @@ const VALID_TRANSITIONS = {
  * Used by createTask (with transaction) and batchCreateTasks (manages its own transaction)
  *
  * @param params - Task parameters
- * @param db - Database instance
+ * @param adapter - Database adapter instance
+ * @param trx - Optional transaction
  * @returns Response with success status and task metadata
  */
-function createTaskInternal(params, db) {
+async function createTaskInternal(params, adapter, trx) {
+    const knex = trx || adapter.getKnex();
     // Validate priority
     const priority = params.priority !== undefined ? params.priority : 2;
     validatePriorityRange(priority);
@@ -69,7 +73,7 @@ function createTaskInternal(params, db) {
     // Validate layer if provided
     let layerId = null;
     if (params.layer) {
-        layerId = getLayerId(db, params.layer);
+        layerId = await getLayerId(adapter, params.layer, trx);
         if (layerId === null) {
             throw new Error(`Invalid layer: ${params.layer}. Must be one of: presentation, business, data, infrastructure, cross-cutting`);
         }
@@ -77,19 +81,24 @@ function createTaskInternal(params, db) {
     // Get or create agents
     let assignedAgentId = null;
     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);
+        assignedAgentId = await getOrCreateAgent(adapter, params.assigned_agent, trx);
     }
+    // Default to 'system' if no created_by_agent provided
+    // This ensures the activity log has a valid agent_id
+    const createdBy = params.created_by_agent || 'system';
+    const createdByAgentId = await getOrCreateAgent(adapter, createdBy, trx);
     // Insert task
-    const insertTaskStmt = db.prepare(`
-    INSERT INTO t_tasks (title, status_id, priority, assigned_agent_id, created_by_agent_id, layer_id)
-    VALUES (?, ?, ?, ?, ?, ?)
-  `);
-    const taskResult = insertTaskStmt.run(params.title, statusId, priority, assignedAgentId, createdByAgentId, layerId);
-    const taskId = taskResult.lastInsertRowid;
+    const now = Math.floor(Date.now() / 1000);
+    const [taskId] = await knex('t_tasks').insert({
+        title: params.title,
+        status_id: statusId,
+        priority: priority,
+        assigned_agent_id: assignedAgentId,
+        created_by_agent_id: createdByAgentId,
+        layer_id: layerId,
+        created_ts: now,
+        updated_ts: now
+    });
     // Process acceptance_criteria (can be string, JSON string, or array)
     let acceptanceCriteriaString = null;
     let acceptanceCriteriaJson = null;
@@ -127,26 +136,123 @@ function createTaskInternal(params, db) {
     }
     // Insert task details if provided
     if (params.description || acceptanceCriteriaString || acceptanceCriteriaJson || params.notes) {
-        const insertDetailsStmt = db.prepare(`
-      INSERT INTO t_task_details (task_id, description, acceptance_criteria, acceptance_criteria_json, notes)
-      VALUES (?, ?, ?, ?, ?)
-    `);
-        insertDetailsStmt.run(taskId, params.description || null, acceptanceCriteriaString, acceptanceCriteriaJson, params.notes || null);
+        await knex('t_task_details').insert({
+            task_id: Number(taskId),
+            description: params.description || null,
+            acceptance_criteria: acceptanceCriteriaString,
+            acceptance_criteria_json: acceptanceCriteriaJson,
+            notes: params.notes || null
+        });
     }
     // Insert tags if provided
     if (params.tags && params.tags.length > 0) {
-        const insertTagStmt = db.prepare(`
-      INSERT INTO t_task_tags (task_id, tag_id)
-      VALUES (?, ?)
-    `);
-        for (const tagName of params.tags) {
-            const tagId = getOrCreateTag(db, tagName);
-            insertTagStmt.run(taskId, tagId);
+        // Parse tags - handle MCP SDK converting JSON string to char array
+        let tagsParsed;
+        if (typeof params.tags === 'string') {
+            // String - try to parse as JSON
+            try {
+                tagsParsed = JSON.parse(params.tags);
+            }
+            catch {
+                // If not valid JSON, treat as single tag name
+                tagsParsed = [params.tags];
+            }
+        }
+        else if (Array.isArray(params.tags)) {
+            // Check if it's an array of single characters (MCP SDK bug)
+            // Example: ['[', '"', 't', 'e', 's', 't', 'i', 'n', 'g', '"', ']']
+            if (params.tags.every((item) => typeof item === 'string' && item.length === 1)) {
+                // Join characters back into string and parse JSON
+                const jsonString = params.tags.join('');
+                try {
+                    tagsParsed = JSON.parse(jsonString);
+                }
+                catch (e) {
+                    const errMsg = e instanceof Error ? e.message : String(e);
+                    throw new Error(`Invalid tags format: ${jsonString}. ${errMsg}`);
+                }
+            }
+            else {
+                // Normal array of tag names
+                tagsParsed = params.tags;
+            }
+        }
+        else {
+            throw new Error('Parameter "tags" must be a string or array');
+        }
+        for (const tagName of tagsParsed) {
+            const tagId = await getOrCreateTag(adapter, tagName, trx);
+            await knex('t_task_tags').insert({
+                task_id: Number(taskId),
+                tag_id: tagId
+            }).onConflict(['task_id', 'tag_id']).ignore();
+        }
+    }
+    // Activity logging (replaces triggers)
+    await logTaskCreate(knex, {
+        task_id: Number(taskId),
+        title: params.title,
+        agent_id: createdByAgentId,
+        layer_id: layerId || undefined
+    });
+    // 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');
+        }
+        for (const filePath of watchFilesParsed) {
+            const fileId = await getOrCreateFile(adapter, filePath, trx);
+            await knex('t_task_file_links').insert({
+                task_id: Number(taskId),
+                file_id: fileId
+            }).onConflict(['task_id', 'file_id']).ignore();
+        }
+        // Register files with watcher for auto-tracking
+        try {
+            const watcher = FileWatcher.getInstance();
+            for (const filePath of watchFilesParsed) {
+                watcher.registerFile(filePath, Number(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,
+        task_id: Number(taskId),
         title: params.title,
         status: status,
         message: `Task "${params.title}" created successfully`
@@ -155,16 +261,16 @@ function createTaskInternal(params, db) {
 /**
  * Create a new task
  */
-export function createTask(params) {
-    const db = getDatabase();
+export async function createTask(params, adapter) {
+    const actualAdapter = adapter ?? getAdapter();
     // 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 await actualAdapter.transaction(async (trx) => {
+            return await createTaskInternal(params, actualAdapter, trx);
         });
     }
     catch (error) {
@@ -175,56 +281,50 @@ export function createTask(params) {
 /**
  * Update task metadata
  */
-export function updateTask(params) {
-    const db = getDatabase();
+export async function updateTask(params, adapter) {
+    const actualAdapter = adapter ?? getAdapter();
     // Validate required parameters
     if (!params.task_id) {
         throw new Error('Parameter "task_id" is required');
     }
     try {
-        return transaction(db, () => {
+        return await actualAdapter.transaction(async (trx) => {
+            const knex = actualAdapter.getKnex();
             // Check if task exists
-            const taskExists = db.prepare('SELECT id FROM t_tasks WHERE id = ?').get(params.task_id);
+            const taskExists = await trx('t_tasks').where({ id: params.task_id }).first();
             if (!taskExists) {
                 throw new Error(`Task with id ${params.task_id} not found`);
             }
-            // Build update query dynamically
-            const updates = [];
-            const updateParams = [];
+            // Build update data dynamically
+            const updateData = {};
             if (params.title !== undefined) {
                 if (params.title.trim() === '') {
                     throw new Error('Parameter "title" cannot be empty');
                 }
                 validateLength(params.title, 'Parameter "title"', 200);
-                updates.push('title = ?');
-                updateParams.push(params.title);
+                updateData.title = params.title;
             }
             if (params.priority !== undefined) {
                 validatePriorityRange(params.priority);
-                updates.push('priority = ?');
-                updateParams.push(params.priority);
+                updateData.priority = params.priority;
             }
             if (params.assigned_agent !== undefined) {
-                const agentId = getOrCreateAgent(db, params.assigned_agent);
-                updates.push('assigned_agent_id = ?');
-                updateParams.push(agentId);
+                const agentId = await getOrCreateAgent(actualAdapter, params.assigned_agent, trx);
+                updateData.assigned_agent_id = agentId;
             }
             if (params.layer !== undefined) {
-                const layerId = getLayerId(db, params.layer);
+                const layerId = await getLayerId(actualAdapter, params.layer, trx);
                 if (layerId === null) {
                     throw new Error(`Invalid layer: ${params.layer}. Must be one of: presentation, business, data, infrastructure, cross-cutting`);
                 }
-                updates.push('layer_id = ?');
-                updateParams.push(layerId);
+                updateData.layer_id = layerId;
             }
             // Update t_tasks if any updates
-            if (updates.length > 0) {
-                const updateStmt = db.prepare(`
-          UPDATE t_tasks
-          SET ${updates.join(', ')}
-          WHERE id = ?
-        `);
-                updateStmt.run(...updateParams, params.task_id);
+            if (Object.keys(updateData).length > 0) {
+                await trx('t_tasks')
+                    .where({ id: params.task_id })
+                    .update(updateData);
+                // TODO: Add activity logging for updates if needed
             }
             // Update t_task_details if any detail fields provided
             if (params.description !== undefined || params.acceptance_criteria !== undefined || params.notes !== undefined) {
@@ -266,43 +366,95 @@ 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);
-                if (detailsExist) {
+                const detailsExist = await trx('t_task_details').where({ task_id: params.task_id }).first();
+                const detailsUpdate = {};
+                if (params.description !== undefined) {
+                    detailsUpdate.description = params.description || null;
+                }
+                if (acceptanceCriteriaString !== undefined) {
+                    detailsUpdate.acceptance_criteria = acceptanceCriteriaString;
+                }
+                if (acceptanceCriteriaJson !== undefined) {
+                    detailsUpdate.acceptance_criteria_json = acceptanceCriteriaJson;
+                }
+                if (params.notes !== undefined) {
+                    detailsUpdate.notes = params.notes || null;
+                }
+                if (detailsExist && Object.keys(detailsUpdate).length > 0) {
                     // Update existing details
-                    const detailUpdates = [];
-                    const detailParams = [];
-                    if (params.description !== undefined) {
-                        detailUpdates.push('description = ?');
-                        detailParams.push(params.description || null);
-                    }
-                    if (acceptanceCriteriaString !== undefined) {
-                        detailUpdates.push('acceptance_criteria = ?');
-                        detailParams.push(acceptanceCriteriaString);
+                    await trx('t_task_details')
+                        .where({ task_id: params.task_id })
+                        .update(detailsUpdate);
+                }
+                else if (!detailsExist) {
+                    // Insert new details
+                    await trx('t_task_details').insert({
+                        task_id: params.task_id,
+                        description: params.description || null,
+                        acceptance_criteria: acceptanceCriteriaString !== undefined ? acceptanceCriteriaString : null,
+                        acceptance_criteria_json: acceptanceCriteriaJson !== undefined ? acceptanceCriteriaJson : null,
+                        notes: 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);
                     }
-                    if (acceptanceCriteriaJson !== undefined) {
-                        detailUpdates.push('acceptance_criteria_json = ?');
-                        detailParams.push(acceptanceCriteriaJson);
+                    catch {
+                        // If not valid JSON, treat as single file path
+                        watchFilesParsed = [params.watch_files];
                     }
-                    if (params.notes !== undefined) {
-                        detailUpdates.push('notes = ?');
-                        detailParams.push(params.notes || null);
+                }
+                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}`);
+                        }
                     }
-                    if (detailUpdates.length > 0) {
-                        const updateDetailsStmt = db.prepare(`
-              UPDATE t_task_details
-              SET ${detailUpdates.join(', ')}
-              WHERE task_id = ?
-            `);
-                        updateDetailsStmt.run(...detailParams, params.task_id);
+                    else {
+                        // Normal array of file paths
+                        watchFilesParsed = params.watch_files;
                     }
                 }
                 else {
-                    // Insert new details
-                    const insertDetailsStmt = db.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);
+                    throw new Error('Parameter "watch_files" must be a string or array');
+                }
+                for (const filePath of watchFilesParsed) {
+                    const fileId = await getOrCreateFile(actualAdapter, filePath, trx);
+                    await trx('t_task_file_links').insert({
+                        task_id: params.task_id,
+                        file_id: fileId
+                    }).onConflict(['task_id', 'file_id']).ignore();
+                }
+                // Register files with watcher for auto-tracking
+                try {
+                    const taskData = await trx('t_tasks as t')
+                        .join('m_task_statuses as s', 't.status_id', 's.id')
+                        .where('t.id', params.task_id)
+                        .select('t.title', 's.name as status')
+                        .first();
+                    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 {
@@ -320,89 +472,70 @@ export function updateTask(params) {
 /**
  * Internal helper: Query task dependencies (used by getTask and getDependencies)
  */
-function queryTaskDependencies(db, taskId, includeDetails = false) {
+async function queryTaskDependencies(adapter, taskId, includeDetails = false) {
+    const knex = adapter.getKnex();
     // Build query based on include_details flag
-    let selectFields;
+    const selectFields = includeDetails
+        ? [
+            't.id',
+            't.title',
+            's.name as status',
+            't.priority',
+            'aa.name as assigned_to',
+            't.created_ts',
+            't.updated_ts',
+            'td.description'
+        ]
+        : [
+            't.id',
+            't.title',
+            's.name as status',
+            't.priority'
+        ];
+    // Get blockers (tasks that block this task)
+    let blockersQuery = knex('t_tasks as t')
+        .join('t_task_dependencies as d', 't.id', 'd.blocker_task_id')
+        .leftJoin('m_task_statuses as s', 't.status_id', 's.id')
+        .leftJoin('m_agents as aa', 't.assigned_agent_id', 'aa.id')
+        .where('d.blocked_task_id', taskId)
+        .select(selectFields);
     if (includeDetails) {
-        // Include description from t_task_details
-        selectFields = `
-      t.id,
-      t.title,
-      s.name as status,
-      t.priority,
-      aa.name as assigned_to,
-      t.created_ts,
-      t.updated_ts,
-      td.description
-    `;
-    }
-    else {
-        // Metadata only (token-efficient)
-        selectFields = `
-      t.id,
-      t.title,
-      s.name as status,
-      t.priority
-    `;
+        blockersQuery = blockersQuery.leftJoin('t_task_details as td', 't.id', 'td.task_id');
     }
-    // Get blockers (tasks that block this task)
-    const blockersQuery = `
-    SELECT ${selectFields}
-    FROM t_tasks t
-    JOIN t_task_dependencies d ON t.id = d.blocker_task_id
-    LEFT JOIN m_task_statuses s ON t.status_id = s.id
-    LEFT JOIN m_agents aa ON t.assigned_agent_id = aa.id
-    ${includeDetails ? 'LEFT JOIN t_task_details td ON t.id = td.task_id' : ''}
-    WHERE d.blocked_task_id = ?
-  `;
-    const blockers = db.prepare(blockersQuery).all(taskId);
+    const blockers = await blockersQuery;
     // Get blocking (tasks this task blocks)
-    const blockingQuery = `
-    SELECT ${selectFields}
-    FROM t_tasks t
-    JOIN t_task_dependencies d ON t.id = d.blocked_task_id
-    LEFT JOIN m_task_statuses s ON t.status_id = s.id
-    LEFT JOIN m_agents aa ON t.assigned_agent_id = aa.id
-    ${includeDetails ? 'LEFT JOIN t_task_details td ON t.id = td.task_id' : ''}
-    WHERE d.blocker_task_id = ?
-  `;
-    const blocking = db.prepare(blockingQuery).all(taskId);
+    let blockingQuery = knex('t_tasks as t')
+        .join('t_task_dependencies as d', 't.id', 'd.blocked_task_id')
+        .leftJoin('m_task_statuses as s', 't.status_id', 's.id')
+        .leftJoin('m_agents as aa', 't.assigned_agent_id', 'aa.id')
+        .where('d.blocker_task_id', taskId)
+        .select(selectFields);
+    if (includeDetails) {
+        blockingQuery = blockingQuery.leftJoin('t_task_details as td', 't.id', 'td.task_id');
+    }
+    const blocking = await blockingQuery;
     return { blockers, blocking };
 }
 /**
  * Get full task details
  */
-export function getTask(params) {
-    const db = getDatabase();
+export async function getTask(params, adapter) {
+    const actualAdapter = adapter ?? getAdapter();
+    const knex = actualAdapter.getKnex();
     if (!params.task_id) {
         throw new Error('Parameter "task_id" is required');
     }
     try {
         // Get task with details
-        const stmt = db.prepare(`
-      SELECT
-        t.id,
-        t.title,
-        s.name as status,
-        t.priority,
-        aa.name as assigned_to,
-        ca.name as created_by,
-        l.name as layer,
-        t.created_ts,
-        t.updated_ts,
-        t.completed_ts,
-        td.description,
-        td.acceptance_criteria,
-        td.notes
-      FROM t_tasks t
-      LEFT JOIN m_task_statuses s ON t.status_id = s.id
-      LEFT JOIN m_agents aa ON t.assigned_agent_id = aa.id
-      LEFT JOIN m_agents ca ON t.created_by_agent_id = ca.id
-      LEFT JOIN m_layers l ON t.layer_id = l.id
-      LEFT JOIN t_task_details td ON t.id = td.task_id
-      WHERE t.id = ?
-    `);
-        const task = stmt.get(params.task_id);
+        const task = await knex('t_tasks as t')
+            .leftJoin('m_task_statuses as s', 't.status_id', 's.id')
+            .leftJoin('m_agents as aa', 't.assigned_agent_id', 'aa.id')
+            .leftJoin('m_agents as ca', 't.created_by_agent_id', 'ca.id')
+            .leftJoin('m_layers as l', 't.layer_id', 'l.id')
+            .leftJoin('t_task_details as td', 't.id', 'td.task_id')
+            .where('t.id', params.task_id)
+            .select('t.id', 't.title', 's.name as status', 't.priority', 'aa.name as assigned_to', 'ca.name as created_by', 'l.name as layer', 't.created_ts', 't.updated_ts', 't.completed_ts', 'td.description', 'td.acceptance_criteria', 'td.notes')
+            .first();
         if (!task) {
             return {
                 found: false,
@@ -410,37 +543,27 @@ export function getTask(params) {
             };
         }
         // Get tags
-        const tagsStmt = db.prepare(`
-      SELECT tg.name
-      FROM t_task_tags tt
-      JOIN m_tags tg ON tt.tag_id = tg.id
-      WHERE tt.task_id = ?
-    `);
-        const tags = tagsStmt.all(params.task_id).map((row) => row.name);
+        const tags = await knex('t_task_tags as tt')
+            .join('m_tags as tg', 'tt.tag_id', 'tg.id')
+            .where('tt.task_id', params.task_id)
+            .select('tg.name')
+            .then(rows => rows.map((row) => row.name));
         // Get decision links
-        const decisionsStmt = db.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
-      WHERE tdl.task_id = ?
-    `);
-        const decisions = decisionsStmt.all(params.task_id);
+        const decisions = await knex('t_task_decision_links as tdl')
+            .join('m_context_keys as ck', 'tdl.decision_key_id', 'ck.id')
+            .where('tdl.task_id', params.task_id)
+            .select('ck.key', 'tdl.link_type');
         // Get constraint links
-        const constraintsStmt = db.prepare(`
-      SELECT c.id, c.constraint_text
-      FROM t_task_constraint_links tcl
-      JOIN t_constraints c ON tcl.constraint_id = c.id
-      WHERE tcl.task_id = ?
-    `);
-        const constraints = constraintsStmt.all(params.task_id);
+        const constraints = await knex('t_task_constraint_links as tcl')
+            .join('t_constraints as c', 'tcl.constraint_id', 'c.id')
+            .where('tcl.task_id', params.task_id)
+            .select('c.id', 'c.constraint_text');
         // Get file links
-        const filesStmt = db.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);
+        const files = await knex('t_task_file_links as tfl')
+            .join('m_files as f', 'tfl.file_id', 'f.id')
+            .where('tfl.task_id', params.task_id)
+            .select('f.path')
+            .then(rows => rows.map((row) => row.path));
         // Build result
         const result = {
             found: true,
@@ -454,7 +577,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 = await queryTaskDependencies(actualAdapter, params.task_id, false);
             result.task.dependencies = {
                 blockers: deps.blockers,
                 blocking: deps.blocking
@@ -470,80 +593,76 @@ export function getTask(params) {
 /**
  * List tasks (token-efficient, no descriptions)
  */
-export function listTasks(params = {}) {
-    const db = getDatabase();
+export async function listTasks(params = {}, adapter) {
+    const actualAdapter = adapter ?? getAdapter();
+    const knex = actualAdapter.getKnex();
     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 = await detectAndTransitionStaleTasks(actualAdapter);
+        const gitCompletedCount = await detectAndCompleteReviewedTasks(actualAdapter);
+        const gitArchivedCount = await detectAndArchiveOnCommit(actualAdapter);
+        const archiveCount = await autoArchiveOldDoneTasks(actualAdapter);
         // Build query with optional dependency counts
         let query;
         if (params.include_dependency_counts) {
             // Include dependency counts with LEFT JOINs
-            query = `
-        SELECT
-          vt.*,
-          COALESCE(blockers.blocked_by_count, 0) as blocked_by_count,
-          COALESCE(blocking.blocking_count, 0) as blocking_count
-        FROM v_task_board vt
-        LEFT JOIN (
-          SELECT blocked_task_id, COUNT(*) as blocked_by_count
-          FROM t_task_dependencies
-          GROUP BY blocked_task_id
-        ) blockers ON vt.id = blockers.blocked_task_id
-        LEFT JOIN (
-          SELECT blocker_task_id, COUNT(*) as blocking_count
-          FROM t_task_dependencies
-          GROUP BY blocker_task_id
-        ) blocking ON vt.id = blocking.blocker_task_id
-        WHERE 1=1
-      `;
+            const blockersCTE = knex('t_task_dependencies')
+                .select('blocked_task_id')
+                .count('* as blocked_by_count')
+                .groupBy('blocked_task_id')
+                .as('blockers');
+            const blockingCTE = knex('t_task_dependencies')
+                .select('blocker_task_id')
+                .count('* as blocking_count')
+                .groupBy('blocker_task_id')
+                .as('blocking');
+            query = knex('v_task_board as vt')
+                .leftJoin(blockersCTE, 'vt.id', 'blockers.blocked_task_id')
+                .leftJoin(blockingCTE, 'vt.id', 'blocking.blocker_task_id')
+                .select('vt.*', knex.raw('COALESCE(blockers.blocked_by_count, 0) as blocked_by_count'), knex.raw('COALESCE(blocking.blocking_count, 0) as blocking_count'));
         }
         else {
             // Standard query without dependency counts
-            query = 'SELECT * FROM v_task_board WHERE 1=1';
+            query = knex('v_task_board');
         }
-        const queryParams = [];
         // Filter by status
         if (params.status) {
             if (!STATUS_TO_ID[params.status]) {
                 throw new Error(`Invalid status: ${params.status}. Must be one of: todo, in_progress, waiting_review, blocked, done, archived`);
             }
-            query += params.include_dependency_counts ? ' AND vt.status = ?' : ' AND status = ?';
-            queryParams.push(params.status);
+            query = query.where(params.include_dependency_counts ? 'vt.status' : 'status', params.status);
         }
         // Filter by assigned agent
         if (params.assigned_agent) {
-            query += params.include_dependency_counts ? ' AND vt.assigned_to = ?' : ' AND assigned_to = ?';
-            queryParams.push(params.assigned_agent);
+            query = query.where(params.include_dependency_counts ? 'vt.assigned_to' : 'assigned_to', params.assigned_agent);
         }
         // Filter by layer
         if (params.layer) {
-            query += params.include_dependency_counts ? ' AND vt.layer = ?' : ' AND layer = ?';
-            queryParams.push(params.layer);
+            query = query.where(params.include_dependency_counts ? 'vt.layer' : 'layer', params.layer);
         }
         // Filter by tags
         if (params.tags && params.tags.length > 0) {
             for (const tag of params.tags) {
-                query += params.include_dependency_counts ? ' AND vt.tags LIKE ?' : ' AND tags LIKE ?';
-                queryParams.push(`%${tag}%`);
+                query = query.where(params.include_dependency_counts ? 'vt.tags' : 'tags', 'like', `%${tag}%`);
             }
         }
         // Order by updated timestamp (most recent first)
-        query += params.include_dependency_counts ? ' ORDER BY vt.updated_ts DESC' : ' ORDER BY updated_ts DESC';
+        query = query.orderBy(params.include_dependency_counts ? 'vt.updated_ts' : 'updated_ts', 'desc');
         // Pagination
         const limit = params.limit !== undefined ? params.limit : 50;
         const offset = params.offset || 0;
         validateRange(limit, 'Parameter "limit"', 0, 100);
         validateRange(offset, 'Parameter "offset"', 0, Number.MAX_SAFE_INTEGER);
-        query += ' LIMIT ? OFFSET ?';
-        queryParams.push(limit, offset);
+        query = query.limit(limit).offset(offset);
         // Execute query
-        const stmt = db.prepare(query);
-        const rows = stmt.all(...queryParams);
+        const rows = await query;
         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 +673,9 @@ export function listTasks(params = {}) {
 /**
  * Move task to different status
  */
-export function moveTask(params) {
-    const db = getDatabase();
+export async function moveTask(params, adapter) {
+    const actualAdapter = adapter ?? getAdapter();
+    const knex = actualAdapter.getKnex();
     if (!params.task_id) {
         throw new Error('Parameter "task_id" is required');
     }
@@ -563,11 +683,15 @@ 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
+        await detectAndTransitionStaleTasks(actualAdapter);
+        await autoArchiveOldDoneTasks(actualAdapter);
+        return await actualAdapter.transaction(async (trx) => {
             // Get current status
-            const taskRow = db.prepare('SELECT status_id FROM t_tasks WHERE id = ?').get(params.task_id);
+            const taskRow = await trx('t_tasks')
+                .where({ id: params.task_id })
+                .select('status_id')
+                .first();
             if (!taskRow) {
                 throw new Error(`Task with id ${params.task_id} not found`);
             }
@@ -583,13 +707,26 @@ export function moveTask(params) {
                     `Valid transitions: ${validNextStatuses.map(id => ID_TO_STATUS[id]).join(', ')}`);
             }
             // Update status
-            const updateStmt = db.prepare(`
-        UPDATE t_tasks
-        SET status_id = ?,
-            completed_ts = CASE WHEN ? = 5 THEN unixepoch() ELSE completed_ts END
-        WHERE id = ?
-      `);
-            updateStmt.run(newStatusId, newStatusId, params.task_id);
+            const updateData = {
+                status_id: newStatusId
+            };
+            // Set completed_ts when moving to done
+            if (newStatusId === TASK_STATUS.DONE) {
+                updateData.completed_ts = Math.floor(Date.now() / 1000);
+            }
+            await trx('t_tasks')
+                .where({ id: params.task_id })
+                .update(updateData);
+            // Activity logging (replaces trigger)
+            // Note: Using system agent (id=1) for status changes
+            // In a real implementation, you'd pass the actual agent_id who made the change
+            const systemAgentId = 1;
+            await logTaskStatusChange(knex, {
+                task_id: params.task_id,
+                old_status: currentStatusId,
+                new_status: newStatusId,
+                agent_id: systemAgentId
+            });
             // Update watcher if moving to done or archived (stop watching)
             if (params.new_status === 'done' || params.new_status === 'archived') {
                 try {
@@ -617,8 +754,9 @@ export function moveTask(params) {
 /**
  * Link task to decision/constraint/file
  */
-export function linkTask(params) {
-    const db = getDatabase();
+export async function linkTask(params, adapter) {
+    const actualAdapter = adapter ?? getAdapter();
+    const knex = actualAdapter.getKnex();
     if (!params.task_id) {
         throw new Error('Parameter "task_id" is required');
     }
@@ -629,21 +767,21 @@ export function linkTask(params) {
         throw new Error('Parameter "target_id" is required');
     }
     try {
-        return transaction(db, () => {
+        return await actualAdapter.transaction(async (trx) => {
             // Check if task exists
-            const taskExists = db.prepare('SELECT id FROM t_tasks WHERE id = ?').get(params.task_id);
+            const taskExists = await trx('t_tasks').where({ id: params.task_id }).first();
             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 = await getOrCreateContextKey(actualAdapter, decisionKey, trx);
                 const linkRelation = params.link_relation || 'implements';
-                const stmt = db.prepare(`
-          INSERT OR REPLACE INTO t_task_decision_links (task_id, decision_key_id, link_type)
-          VALUES (?, ?, ?)
-        `);
-                stmt.run(params.task_id, keyId, linkRelation);
+                await knex('t_task_decision_links').insert({
+                    task_id: params.task_id,
+                    decision_key_id: keyId,
+                    link_type: linkRelation
+                }).onConflict(['task_id', 'decision_key_id']).merge();
                 return {
                     success: true,
                     task_id: params.task_id,
@@ -656,15 +794,14 @@ 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 = await trx('t_constraints').where({ id: constraintId }).first();
                 if (!constraintExists) {
                     throw new Error(`Constraint with id ${constraintId} not found`);
                 }
-                const stmt = db.prepare(`
-          INSERT OR IGNORE INTO t_task_constraint_links (task_id, constraint_id)
-          VALUES (?, ?)
-        `);
-                stmt.run(params.task_id, constraintId);
+                await trx('t_task_constraint_links').insert({
+                    task_id: params.task_id,
+                    constraint_id: constraintId
+                }).onConflict(['task_id', 'constraint_id']).ignore();
                 return {
                     success: true,
                     task_id: params.task_id,
@@ -674,21 +811,23 @@ 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(`
-          INSERT OR IGNORE INTO t_task_file_links (task_id, file_id)
-          VALUES (?, ?)
-        `);
-                stmt.run(params.task_id, fileId);
+                const fileId = await getOrCreateFile(actualAdapter, filePath, trx);
+                await trx('t_task_file_links').insert({
+                    task_id: params.task_id,
+                    file_id: fileId
+                }).onConflict(['task_id', 'file_id']).ignore();
                 // Register file with watcher for auto-tracking
                 try {
-                    const taskData = db.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);
+                    const taskData = await trx('t_tasks as t')
+                        .join('m_task_statuses as s', 't.status_id', 's.id')
+                        .where('t.id', params.task_id)
+                        .select('t.title', 's.name as status')
+                        .first();
                     if (taskData) {
                         const watcher = FileWatcher.getInstance();
                         watcher.registerFile(filePath, params.task_id, taskData.title, taskData.status);
@@ -703,7 +842,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 +859,19 @@ export function linkTask(params) {
 /**
  * Archive completed task
  */
-export function archiveTask(params) {
-    const db = getDatabase();
+export async function archiveTask(params, adapter) {
+    const actualAdapter = adapter ?? getAdapter();
+    const knex = actualAdapter.getKnex();
     if (!params.task_id) {
         throw new Error('Parameter "task_id" is required');
     }
     try {
-        return transaction(db, () => {
+        return await actualAdapter.transaction(async (trx) => {
             // 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 = await trx('t_tasks')
+                .where({ id: params.task_id })
+                .select('status_id')
+                .first();
             if (!taskRow) {
                 throw new Error(`Task with id ${params.task_id} not found`);
             }
@@ -735,8 +879,18 @@ 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 = ?');
-            updateStmt.run(TASK_STATUS.ARCHIVED, params.task_id);
+            await trx('t_tasks')
+                .where({ id: params.task_id })
+                .update({ status_id: TASK_STATUS.ARCHIVED });
+            // Activity logging
+            // Note: Using system agent (id=1) for status changes
+            const systemAgentId = 1;
+            await logTaskStatusChange(knex, {
+                task_id: params.task_id,
+                old_status: TASK_STATUS.DONE,
+                new_status: TASK_STATUS.ARCHIVED,
+                agent_id: systemAgentId
+            });
             // Unregister from file watcher (archived tasks don't need tracking)
             try {
                 const watcher = FileWatcher.getInstance();
@@ -760,8 +914,9 @@ export function archiveTask(params) {
 /**
  * Add dependency (blocking relationship) between tasks
  */
-export function addDependency(params) {
-    const db = getDatabase();
+export async function addDependency(params, adapter) {
+    const actualAdapter = adapter ?? getAdapter();
+    const knex = actualAdapter.getKnex();
     if (!params.blocker_task_id) {
         throw new Error('Parameter "blocker_task_id" is required');
     }
@@ -769,14 +924,20 @@ export function addDependency(params) {
         throw new Error('Parameter "blocked_task_id" is required');
     }
     try {
-        return transaction(db, () => {
+        return await actualAdapter.transaction(async (trx) => {
             // 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 = await trx('t_tasks')
+                .where({ id: params.blocker_task_id })
+                .select('id', 'status_id')
+                .first();
+            const blockedTask = await trx('t_tasks')
+                .where({ id: params.blocked_task_id })
+                .select('id', 'status_id')
+                .first();
             if (!blockerTask) {
                 throw new Error(`Blocker task #${params.blocker_task_id} not found`);
             }
@@ -791,15 +952,17 @@ 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(`
-        SELECT 1 FROM t_task_dependencies
-        WHERE blocker_task_id = ? AND blocked_task_id = ?
-      `).get(params.blocked_task_id, params.blocker_task_id);
+            const reverseExists = await trx('t_task_dependencies')
+                .where({
+                blocker_task_id: params.blocked_task_id,
+                blocked_task_id: params.blocker_task_id
+            })
+                .first();
             if (reverseExists) {
                 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 = await trx.raw(`
         WITH RECURSIVE dependency_chain AS (
           -- Start from the task that would be blocked
           SELECT blocked_task_id as task_id, 1 as depth
@@ -815,10 +978,11 @@ export function addDependency(params) {
           WHERE dc.depth < 100
         )
         SELECT task_id FROM dependency_chain WHERE task_id = ?
-      `).get(params.blocked_task_id, params.blocker_task_id);
+      `, [params.blocked_task_id, params.blocker_task_id])
+                .then((result) => result[0]);
             if (cycleCheck) {
                 // Build cycle path for error message
-                const cyclePathResult = db.prepare(`
+                const cyclePathResult = await trx.raw(`
           WITH RECURSIVE dependency_chain AS (
             SELECT blocked_task_id as task_id, 1 as depth,
                    CAST(blocked_task_id AS TEXT) as path
@@ -834,16 +998,17 @@ export function addDependency(params) {
             WHERE dc.depth < 100
           )
           SELECT path FROM dependency_chain WHERE task_id = ? ORDER BY depth DESC LIMIT 1
-        `).get(params.blocked_task_id, params.blocker_task_id);
+        `, [params.blocked_task_id, params.blocker_task_id])
+                    .then((result) => result[0]);
                 const cyclePath = cyclePathResult?.path || `#${params.blocked_task_id} → ... → #${params.blocker_task_id}`;
                 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(`
-        INSERT INTO t_task_dependencies (blocker_task_id, blocked_task_id)
-        VALUES (?, ?)
-      `);
-            insertStmt.run(params.blocker_task_id, params.blocked_task_id);
+            await trx('t_task_dependencies').insert({
+                blocker_task_id: params.blocker_task_id,
+                blocked_task_id: params.blocked_task_id,
+                created_ts: Math.floor(Date.now() / 1000)
+            });
             return {
                 success: true,
                 message: `Dependency added: Task #${params.blocker_task_id} blocks Task #${params.blocked_task_id}`
@@ -862,8 +1027,9 @@ export function addDependency(params) {
 /**
  * Remove dependency between tasks
  */
-export function removeDependency(params) {
-    const db = getDatabase();
+export async function removeDependency(params, adapter) {
+    const actualAdapter = adapter ?? getAdapter();
+    const knex = actualAdapter.getKnex();
     if (!params.blocker_task_id) {
         throw new Error('Parameter "blocker_task_id" is required');
     }
@@ -871,11 +1037,12 @@ export function removeDependency(params) {
         throw new Error('Parameter "blocked_task_id" is required');
     }
     try {
-        const deleteStmt = db.prepare(`
-      DELETE FROM t_task_dependencies
-      WHERE blocker_task_id = ? AND blocked_task_id = ?
-    `);
-        deleteStmt.run(params.blocker_task_id, params.blocked_task_id);
+        await knex('t_task_dependencies')
+            .where({
+            blocker_task_id: params.blocker_task_id,
+            blocked_task_id: params.blocked_task_id
+        })
+            .delete();
         return {
             success: true,
             message: `Dependency removed: Task #${params.blocker_task_id} no longer blocks Task #${params.blocked_task_id}`
@@ -889,20 +1056,21 @@ 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 async function getDependencies(params, adapter) {
+    const actualAdapter = adapter ?? getAdapter();
+    const knex = actualAdapter.getKnex();
     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 = await knex('t_tasks').where({ id: params.task_id }).first();
         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 = await queryTaskDependencies(actualAdapter, params.task_id, includeDetails);
         return {
             task_id: params.task_id,
             blockers: deps.blockers,
@@ -921,32 +1089,296 @@ export function getDependencies(params) {
 /**
  * Create multiple tasks atomically
  */
-export function batchCreateTasks(params) {
-    const db = getDatabase();
+export async function batchCreateTasks(params, adapter) {
+    const actualAdapter = adapter ?? getAdapter();
     if (!params.tasks || !Array.isArray(params.tasks)) {
         throw new Error('Parameter "tasks" is required and must be an array');
     }
+    if (params.tasks.length > 50) {
+        throw new Error('Parameter "tasks" must contain at most 50 items');
+    }
     const atomic = params.atomic !== undefined ? params.atomic : true;
-    // Use processBatch utility
-    const batchResult = processBatch(db, params.tasks, (task, db) => {
-        const result = createTaskInternal(task, db);
+    try {
+        if (atomic) {
+            // Atomic mode: All or nothing
+            const results = await actualAdapter.transaction(async (trx) => {
+                const processedResults = [];
+                for (const task of params.tasks) {
+                    try {
+                        const result = await createTaskInternal(task, actualAdapter, trx);
+                        processedResults.push({
+                            title: task.title,
+                            task_id: result.task_id,
+                            success: true,
+                            error: undefined
+                        });
+                    }
+                    catch (error) {
+                        const errorMessage = error instanceof Error ? error.message : String(error);
+                        throw new Error(`Batch failed at task "${task.title}": ${errorMessage}`);
+                    }
+                }
+                return processedResults;
+            });
+            return {
+                success: true,
+                created: results.length,
+                failed: 0,
+                results: results
+            };
+        }
+        else {
+            // Non-atomic mode: Process each independently
+            const results = [];
+            let created = 0;
+            let failed = 0;
+            for (const task of params.tasks) {
+                try {
+                    const result = await actualAdapter.transaction(async (trx) => {
+                        return await createTaskInternal(task, actualAdapter, trx);
+                    });
+                    results.push({
+                        title: task.title,
+                        task_id: result.task_id,
+                        success: true,
+                        error: undefined
+                    });
+                    created++;
+                }
+                catch (error) {
+                    const errorMessage = error instanceof Error ? error.message : String(error);
+                    results.push({
+                        title: task.title,
+                        task_id: undefined,
+                        success: false,
+                        error: errorMessage
+                    });
+                    failed++;
+                }
+            }
+            return {
+                success: failed === 0,
+                created: created,
+                failed: failed,
+                results: results
+            };
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to execute batch operation: ${message}`);
+    }
+}
+/**
+ * Watch/unwatch files for a task (v3.4.1)
+ * Replaces the need to use task.link(file) for file watching
+ */
+export async function watchFiles(params, adapter) {
+    const actualAdapter = adapter ?? getAdapter();
+    const knex = actualAdapter.getKnex();
+    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 await actualAdapter.transaction(async (trx) => {
+            // Check if task exists
+            const taskData = await trx('t_tasks as t')
+                .join('m_task_statuses as s', 't.status_id', 's.id')
+                .where('t.id', params.task_id)
+                .select('t.id', 't.title', 's.name as status')
+                .first();
+            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 addedFiles = [];
+                for (const filePath of params.file_paths) {
+                    const fileId = await getOrCreateFile(actualAdapter, filePath, trx);
+                    // Check if already exists
+                    const existing = await trx('t_task_file_links')
+                        .where({ task_id: params.task_id, file_id: fileId })
+                        .first();
+                    if (!existing) {
+                        await trx('t_task_file_links').insert({
+                            task_id: params.task_id,
+                            file_id: fileId
+                        });
+                        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 removedFiles = [];
+                for (const filePath of params.file_paths) {
+                    const deleted = await trx('t_task_file_links')
+                        .where('task_id', params.task_id)
+                        .whereIn('file_id', function () {
+                        this.select('id').from('m_files').where({ path: filePath });
+                    })
+                        .delete();
+                    if (deleted > 0) {
+                        removedFiles.push(filePath);
+                    }
+                }
+                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 files = await trx('t_task_file_links as tfl')
+                    .join('m_files as f', 'tfl.file_id', 'f.id')
+                    .where('tfl.task_id', params.task_id)
+                    .select('f.path')
+                    .then(rows => rows.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 async function getPrunedFiles(params, adapter) {
+    const actualAdapter = adapter ?? getAdapter();
+    const knex = actualAdapter.getKnex();
+    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 = await knex('t_tasks').where({ id: params.task_id }).first();
+        if (!task) {
+            throw new Error(`Task not found: ${params.task_id}`);
+        }
+        // Get pruned files
+        const limit = params.limit || 100;
+        const rows = await knex('t_task_pruned_files as tpf')
+            .leftJoin('m_context_keys as k', 'tpf.linked_decision_key_id', 'k.id')
+            .where('tpf.task_id', params.task_id)
+            .select('tpf.id', 'tpf.file_path', knex.raw(`datetime(tpf.pruned_ts, 'unixepoch') as pruned_at`), 'k.key as linked_decision')
+            .orderBy('tpf.pruned_ts', 'desc')
+            .limit(limit);
         return {
-            title: task.title,
-            task_id: result.task_id
+            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}`
         };
-    }, atomic, 50);
-    // Map batch results to task batch response format
-    return {
-        success: batchResult.success,
-        created: batchResult.processed,
-        failed: batchResult.failed,
-        results: batchResult.results.map(r => ({
-            title: r.data?.title || '',
-            task_id: r.data?.task_id,
-            success: r.success,
-            error: r.error
-        }))
-    };
+    }
+    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 async function linkPrunedFile(params, adapter) {
+    const actualAdapter = adapter ?? getAdapter();
+    const knex = actualAdapter.getKnex();
+    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 = await knex('m_context_keys as k')
+            .whereExists(function () {
+            this.select('*')
+                .from('t_decisions as d')
+                .whereRaw('d.key_id = k.id');
+        })
+            .where('k.key', params.decision_key)
+            .select('k.id as key_id')
+            .first();
+        if (!decision) {
+            throw new Error(`Decision not found: ${params.decision_key}`);
+        }
+        // Check if pruned file exists
+        const prunedFile = await knex('t_task_pruned_files')
+            .where({ id: params.pruned_file_id })
+            .select('id', 'task_id', 'file_path')
+            .first();
+        if (!prunedFile) {
+            throw new Error(`Pruned file record not found: ${params.pruned_file_id}`);
+        }
+        // Update the link
+        const updated = await knex('t_task_pruned_files')
+            .where({ id: params.pruned_file_id })
+            .update({ linked_decision_key_id: decision.key_id });
+        if (updated === 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 +1393,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 +1402,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 +1461,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 +1471,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 +1641,9 @@ export function taskHelp() {
 /**
  * Query file watcher status and monitored files/tasks
  */
-export function watcherStatus(args) {
+export async function watcherStatus(args, adapter) {
+    const actualAdapter = adapter ?? getAdapter();
+    const knex = actualAdapter.getKnex();
     const subaction = args.subaction || 'status';
     const watcher = FileWatcher.getInstance();
     if (subaction === 'help') {
@@ -1219,15 +1686,13 @@ export function watcherStatus(args) {
         };
     }
     if (subaction === 'list_files') {
-        const db = getDatabase();
-        const fileLinks = db.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
-      JOIN m_task_statuses ts ON t.status_id = ts.id
-      WHERE t.status_id != 6  -- Exclude archived tasks
-      ORDER BY tfl.file_path, t.id
-    `).all();
+        const fileLinks = await knex('t_task_file_links as tfl')
+            .join('t_tasks as t', 'tfl.task_id', 't.id')
+            .join('m_task_statuses as ts', 't.status_id', 'ts.id')
+            .join('m_files as f', 'tfl.file_id', 'f.id')
+            .where('t.status_id', '!=', 6) // Exclude archived tasks
+            .select('f.path as file_path', 't.id', 't.title', 'ts.name as status_name')
+            .orderBy(['f.path', 't.id']);
         // Group by file
         const fileMap = new Map();
         for (const link of fileLinks) {
@@ -1254,17 +1719,14 @@ export function watcherStatus(args) {
         };
     }
     if (subaction === 'list_tasks') {
-        const db = getDatabase();
-        const taskLinks = db.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
-      JOIN m_task_statuses ts ON t.status_id = ts.id
-      JOIN t_task_file_links tfl ON t.id = tfl.task_id
-      WHERE t.status_id != 6  -- Exclude archived tasks
-      GROUP BY t.id, t.title, ts.status_name
-      ORDER BY t.id
-    `).all();
+        const taskLinks = await knex('t_tasks as t')
+            .join('m_task_statuses as ts', 't.status_id', 'ts.id')
+            .join('t_task_file_links as tfl', 't.id', 'tfl.task_id')
+            .join('m_files as f', 'tfl.file_id', 'f.id')
+            .where('t.status_id', '!=', 6) // Exclude archived tasks
+            .groupBy('t.id', 't.title', 'ts.name')
+            .select('t.id', 't.title', 'ts.name as status_name', knex.raw('COUNT(DISTINCT tfl.file_id) as file_count'), knex.raw('GROUP_CONCAT(DISTINCT f.path, \', \') as files'))
+            .orderBy('t.id');
         const tasks = taskLinks.map(task => ({
             task_id: task.id,
             task_title: task.title,