sqlew 3.1.2 → 3.2.3

package/dist/tools/tasks.js

@@ -317,6 +317,58 @@ export function updateTask(params) {
         throw new Error(`Failed to update task: ${message}`);
     }
 }
+/**
+ * Internal helper: Query task dependencies (used by getTask and getDependencies)
+ */
+function queryTaskDependencies(db, taskId, includeDetails = false) {
+    // Build query based on include_details flag
+    let 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
+    `;
+    }
+    // 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);
+    // 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);
+    return { blockers, blocking };
+}
 /**
  * Get full task details
  */
@@ -389,7 +441,8 @@ export function getTask(params) {
       WHERE tfl.task_id = ?
     `);
         const files = filesStmt.all(params.task_id).map((row) => row.path);
-        return {
+        // Build result
+        const result = {
             found: true,
             task: {
                 ...task,
@@ -399,6 +452,15 @@ export function getTask(params) {
                 linked_files: files
             }
         };
+        // Include dependencies if requested (token-efficient, metadata-only)
+        if (params.include_dependencies) {
+            const deps = queryTaskDependencies(db, params.task_id, false);
+            result.task.dependencies = {
+                blockers: deps.blockers,
+                blocking: deps.blocking
+            };
+        }
+        return result;
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
@@ -413,36 +475,61 @@ export function listTasks(params = {}) {
     try {
         // Run auto-stale detection before listing
         const transitionCount = detectAndTransitionStaleTasks(db);
-        // Build query
-        let query = 'SELECT * FROM v_task_board WHERE 1=1';
+        // 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
+      `;
+        }
+        else {
+            // Standard query without dependency counts
+            query = 'SELECT * FROM v_task_board WHERE 1=1';
+        }
         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 += ' AND status = ?';
+            query += params.include_dependency_counts ? ' AND vt.status = ?' : ' AND status = ?';
             queryParams.push(params.status);
         }
         // Filter by assigned agent
         if (params.assigned_agent) {
-            query += ' AND assigned_to = ?';
+            query += params.include_dependency_counts ? ' AND vt.assigned_to = ?' : ' AND assigned_to = ?';
             queryParams.push(params.assigned_agent);
         }
         // Filter by layer
         if (params.layer) {
-            query += ' AND layer = ?';
+            query += params.include_dependency_counts ? ' AND vt.layer = ?' : ' AND layer = ?';
             queryParams.push(params.layer);
         }
         // Filter by tags
         if (params.tags && params.tags.length > 0) {
             for (const tag of params.tags) {
-                query += ' AND tags LIKE ?';
+                query += params.include_dependency_counts ? ' AND vt.tags LIKE ?' : ' AND tags LIKE ?';
                 queryParams.push(`%${tag}%`);
             }
         }
         // Order by updated timestamp (most recent first)
-        query += ' ORDER BY updated_ts DESC';
+        query += params.include_dependency_counts ? ' ORDER BY vt.updated_ts DESC' : ' ORDER BY updated_ts DESC';
         // Pagination
         const limit = params.limit !== undefined ? params.limit : 50;
         const offset = params.offset || 0;
@@ -670,6 +757,167 @@ export function archiveTask(params) {
         throw new Error(`Failed to archive task: ${message}`);
     }
 }
+/**
+ * Add dependency (blocking relationship) between tasks
+ */
+export function addDependency(params) {
+    const db = getDatabase();
+    if (!params.blocker_task_id) {
+        throw new Error('Parameter "blocker_task_id" is required');
+    }
+    if (!params.blocked_task_id) {
+        throw new Error('Parameter "blocked_task_id" is required');
+    }
+    try {
+        return transaction(db, () => {
+            // 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);
+            if (!blockerTask) {
+                throw new Error(`Blocker task #${params.blocker_task_id} not found`);
+            }
+            if (!blockedTask) {
+                throw new Error(`Blocked task #${params.blocked_task_id} not found`);
+            }
+            // Validation 3: Neither task is archived
+            if (blockerTask.status_id === TASK_STATUS.ARCHIVED) {
+                throw new Error(`Cannot add dependency: Task #${params.blocker_task_id} is archived`);
+            }
+            if (blockedTask.status_id === TASK_STATUS.ARCHIVED) {
+                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);
+            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(`
+        WITH RECURSIVE dependency_chain AS (
+          -- Start from the task that would be blocked
+          SELECT blocked_task_id as task_id, 1 as depth
+          FROM t_task_dependencies
+          WHERE blocker_task_id = ?
+
+          UNION ALL
+
+          -- Follow the chain of dependencies
+          SELECT d.blocked_task_id, dc.depth + 1
+          FROM t_task_dependencies d
+          JOIN dependency_chain dc ON d.blocker_task_id = dc.task_id
+          WHERE dc.depth < 100
+        )
+        SELECT task_id FROM dependency_chain WHERE task_id = ?
+      `).get(params.blocked_task_id, params.blocker_task_id);
+            if (cycleCheck) {
+                // Build cycle path for error message
+                const cyclePathResult = db.prepare(`
+          WITH RECURSIVE dependency_chain AS (
+            SELECT blocked_task_id as task_id, 1 as depth,
+                   CAST(blocked_task_id AS TEXT) as path
+            FROM t_task_dependencies
+            WHERE blocker_task_id = ?
+
+            UNION ALL
+
+            SELECT d.blocked_task_id, dc.depth + 1,
+                   dc.path || ' → ' || d.blocked_task_id
+            FROM t_task_dependencies d
+            JOIN dependency_chain dc ON d.blocker_task_id = dc.task_id
+            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);
+                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);
+            return {
+                success: true,
+                message: `Dependency added: Task #${params.blocker_task_id} blocks Task #${params.blocked_task_id}`
+            };
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        // Don't wrap error messages that are already descriptive
+        if (message.includes('not found') || message.includes('not allowed') || message.includes('Circular dependency') || message.includes('Cannot add dependency')) {
+            throw new Error(message);
+        }
+        throw new Error(`Failed to add dependency: ${message}`);
+    }
+}
+/**
+ * Remove dependency between tasks
+ */
+export function removeDependency(params) {
+    const db = getDatabase();
+    if (!params.blocker_task_id) {
+        throw new Error('Parameter "blocker_task_id" is required');
+    }
+    if (!params.blocked_task_id) {
+        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);
+        return {
+            success: true,
+            message: `Dependency removed: Task #${params.blocker_task_id} no longer blocks Task #${params.blocked_task_id}`
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to remove dependency: ${message}`);
+    }
+}
+/**
+ * Get dependencies for a task (bidirectional: what blocks this task, what this task blocks)
+ */
+export function getDependencies(params) {
+    const 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);
+        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);
+        return {
+            task_id: params.task_id,
+            blockers: deps.blockers,
+            blocking: deps.blocking
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        // Don't wrap error messages that are already descriptive
+        if (message.includes('not found')) {
+            throw new Error(message);
+        }
+        throw new Error(`Failed to get dependencies: ${message}`);
+    }
+}
 /**
  * Create multiple tasks atomically
  */
@@ -708,6 +956,7 @@ export function taskHelp() {
         tool: 'task',
         description: 'Kanban Task Watcher for managing tasks with AI-optimized lifecycle states',
         note: '💡 TIP: Use action: "example" to see comprehensive usage scenarios and real-world examples for all task actions.',
+        important: '🚨 AUTOMATIC FILE WATCHING: Linking files to tasks activates automatic file change monitoring and acceptance criteria validation. You can save 300 tokens per file compared to registering watchers manually. See auto_file_tracking section below.',
         actions: {
             create: {
                 description: 'Create a new task',
@@ -776,6 +1025,7 @@ 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.',
                 example: {
                     action: 'link',
                     task_id: 5,
@@ -808,6 +1058,69 @@ export function taskHelp() {
                     atomic: true
                 }
             },
+            add_dependency: {
+                description: 'Add blocking relationship between tasks',
+                required_params: ['blocker_task_id', 'blocked_task_id'],
+                validations: [
+                    'No self-dependencies',
+                    'No circular dependencies (direct or transitive)',
+                    'Both tasks must exist',
+                    'Neither task can be archived'
+                ],
+                example: {
+                    action: 'add_dependency',
+                    blocker_task_id: 1,
+                    blocked_task_id: 2
+                },
+                note: 'Task #1 must be completed before Task #2 can start'
+            },
+            remove_dependency: {
+                description: 'Remove blocking relationship between tasks',
+                required_params: ['blocker_task_id', 'blocked_task_id'],
+                example: {
+                    action: 'remove_dependency',
+                    blocker_task_id: 1,
+                    blocked_task_id: 2
+                },
+                note: 'Silently succeeds even if dependency does not exist'
+            },
+            get_dependencies: {
+                description: 'Query task dependencies (bidirectional)',
+                required_params: ['task_id'],
+                optional_params: ['include_details'],
+                returns: {
+                    blockers: 'Array of tasks that block this task',
+                    blocking: 'Array of tasks this task blocks'
+                },
+                example: {
+                    action: 'get_dependencies',
+                    task_id: 2,
+                    include_details: true
+                },
+                note: 'Defaults to metadata-only (token-efficient). Set include_details=true for full task details.'
+            },
+            watcher: {
+                description: 'Query file watcher status and monitored files/tasks',
+                required_params: [],
+                optional_params: ['subaction'],
+                subactions: ['status', 'list_files', 'list_tasks', 'help'],
+                default_subaction: 'status',
+                examples: {
+                    status: {
+                        action: 'watcher',
+                        subaction: 'status'
+                    },
+                    list_files: {
+                        action: 'watcher',
+                        subaction: 'list_files'
+                    },
+                    list_tasks: {
+                        action: 'watcher',
+                        subaction: 'list_tasks'
+                    }
+                },
+                note: 'Use to monitor which files/tasks are being watched. File watching activates automatically when you link files to tasks.'
+            },
             help: {
                 description: 'Return this help documentation',
                 example: { action: 'help' }
@@ -831,6 +1144,24 @@ export function taskHelp() {
             3: 'high',
             4: 'critical'
         },
+        auto_file_tracking: {
+            description: 'Automatic file watching and acceptance criteria validation - save 300 tokens per file vs manual registration',
+            recommendation: '⭐ BEST PRACTICE: Except in exceptional cases, it is recommended to set up file watchers for all tasks that involve code changes. This provides automatic status tracking with zero token overhead.',
+            how_it_works: [
+                '1. Link files to tasks using the link action with link_type="file"',
+                '2. File watcher automatically activates and monitors linked files',
+                '3. When files are saved, watcher detects changes',
+                '4. If task has acceptance_criteria, watcher validates criteria against changes',
+                '5. Results appear in terminal output with pass/fail status'
+            ],
+            requirements: [
+                'Task must have files linked via link action',
+                'File paths must be relative to project root (e.g., "src/api/auth.ts")',
+                'Watcher only monitors files explicitly linked to tasks'
+            ],
+            token_efficiency: 'File watching happens in background. No MCP tokens consumed until you query status. Manual file tracking would cost ~500-1000 tokens per file check.',
+            documentation_reference: 'docs/AUTO_FILE_TRACKING.md - Complete guide with examples'
+        },
         documentation: {
             task_overview: 'docs/TASK_OVERVIEW.md - Lifecycle, status transitions, auto-stale detection (363 lines, ~10k tokens)',
             task_actions: 'docs/TASK_ACTIONS.md - All action references with examples (854 lines, ~21k tokens)',
@@ -842,4 +1173,316 @@ export function taskHelp() {
         }
     };
 }
+/**
+ * Query file watcher status and monitored files/tasks
+ */
+export function watcherStatus(args) {
+    const subaction = args.subaction || 'status';
+    const watcher = FileWatcher.getInstance();
+    if (subaction === 'help') {
+        return {
+            action: 'watcher',
+            description: 'Query file watcher status and monitored files/tasks',
+            subactions: {
+                status: {
+                    description: 'Get overall watcher status (running, files watched, tasks monitored)',
+                    example: { action: 'watcher', subaction: 'status' }
+                },
+                list_files: {
+                    description: 'List all files being watched with their associated tasks',
+                    example: { action: 'watcher', subaction: 'list_files' }
+                },
+                list_tasks: {
+                    description: 'List all tasks that have active file watchers',
+                    example: { action: 'watcher', subaction: 'list_tasks' }
+                },
+                help: {
+                    description: 'Show this help documentation',
+                    example: { action: 'watcher', subaction: 'help' }
+                }
+            },
+            note: 'File watching activates automatically when you link files to tasks using the link action with link_type="file". The watcher monitors linked files for changes and validates acceptance criteria.'
+        };
+    }
+    if (subaction === 'status') {
+        const status = watcher.getStatus();
+        return {
+            success: true,
+            watcher_status: {
+                running: status.running,
+                files_watched: status.filesWatched,
+                tasks_monitored: status.tasksWatched
+            },
+            message: status.running
+                ? `File watcher is running. Monitoring ${status.filesWatched} file(s) across ${status.tasksWatched} task(s).`
+                : 'File watcher is not running. Link files to tasks to activate automatic file watching.'
+        };
+    }
+    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();
+        // Group by file
+        const fileMap = new Map();
+        for (const link of fileLinks) {
+            if (!fileMap.has(link.file_path)) {
+                fileMap.set(link.file_path, []);
+            }
+            fileMap.get(link.file_path).push({
+                task_id: link.id,
+                task_title: link.title,
+                status: link.status_name
+            });
+        }
+        const files = Array.from(fileMap.entries()).map(([path, tasks]) => ({
+            file_path: path,
+            tasks: tasks
+        }));
+        return {
+            success: true,
+            files_watched: files.length,
+            files: files,
+            message: files.length > 0
+                ? `Watching ${files.length} file(s) linked to tasks.`
+                : 'No files currently linked to tasks. Use link action with link_type="file" to activate file watching.'
+        };
+    }
+    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 tasks = taskLinks.map(task => ({
+            task_id: task.id,
+            task_title: task.title,
+            status: task.status_name,
+            files_count: task.file_count,
+            files: task.files.split(', ')
+        }));
+        return {
+            success: true,
+            tasks_monitored: tasks.length,
+            tasks: tasks,
+            message: tasks.length > 0
+                ? `Monitoring ${tasks.length} task(s) with linked files.`
+                : 'No tasks currently have linked files. Use link action with link_type="file" to activate file watching.'
+        };
+    }
+    return {
+        error: `Invalid subaction: ${subaction}. Valid subactions: status, list_files, list_tasks, help`
+    };
+}
+/**
+ * Get comprehensive examples for task tool
+ * @returns Examples documentation object
+ */
+export function taskExample() {
+    return {
+        tool: 'task',
+        description: 'Comprehensive task management examples for Kanban-style workflow',
+        scenarios: {
+            basic_task_management: {
+                title: 'Creating and Managing Tasks',
+                examples: [
+                    {
+                        scenario: 'Create a new task',
+                        request: '{ action: "create", title: "Implement user authentication", description: "Add JWT-based auth to API", priority: 3, assigned_agent: "backend-agent", layer: "business", tags: ["authentication", "security"] }',
+                        explanation: 'Creates task in todo status with high priority'
+                    },
+                    {
+                        scenario: 'Get task details',
+                        request: '{ action: "get", task_id: 5 }',
+                        response: 'Full task details including metadata, links, and timestamps'
+                    },
+                    {
+                        scenario: 'List tasks by status',
+                        request: '{ action: "list", status: "in_progress", limit: 20 }',
+                        explanation: 'View all in-progress tasks'
+                    }
+                ]
+            },
+            status_workflow: {
+                title: 'Task Lifecycle (Status Transitions)',
+                workflow: [
+                    {
+                        step: 1,
+                        status: 'todo',
+                        action: '{ action: "create", title: "...", status: "todo" }',
+                        description: 'Task created and waiting to be started'
+                    },
+                    {
+                        step: 2,
+                        status: 'in_progress',
+                        action: '{ action: "move", task_id: 1, new_status: "in_progress" }',
+                        description: 'Agent starts working on task'
+                    },
+                    {
+                        step: 3,
+                        status: 'waiting_review',
+                        action: '{ action: "move", task_id: 1, new_status: "waiting_review" }',
+                        description: 'Work complete, awaiting review/approval'
+                    },
+                    {
+                        step: 4,
+                        status: 'done',
+                        action: '{ action: "move", task_id: 1, new_status: "done" }',
+                        description: 'Task reviewed and completed'
+                    },
+                    {
+                        step: 5,
+                        status: 'archived',
+                        action: '{ action: "archive", task_id: 1 }',
+                        description: 'Task archived for historical record'
+                    }
+                ],
+                blocked_status: {
+                    description: 'Use "blocked" when task cannot proceed due to dependencies',
+                    example: '{ action: "move", task_id: 1, new_status: "blocked" }'
+                }
+            },
+            auto_stale_detection: {
+                title: 'Automatic Stale Task Management',
+                behavior: [
+                    {
+                        rule: 'in_progress > 2 hours → waiting_review',
+                        explanation: 'Tasks stuck in progress auto-move to waiting_review',
+                        rationale: 'Prevents tasks from being forgotten while in progress'
+                    },
+                    {
+                        rule: 'waiting_review > 24 hours → todo',
+                        explanation: 'Unreviewed tasks return to todo queue',
+                        rationale: 'Ensures waiting tasks dont accumulate indefinitely'
+                    }
+                ],
+                configuration: {
+                    keys: ['task_stale_hours_in_progress', 'task_stale_hours_waiting_review', 'task_auto_stale_enabled'],
+                    note: 'Configure via config table in database'
+                }
+            },
+            task_linking: {
+                title: 'Linking Tasks to Context',
+                examples: [
+                    {
+                        scenario: 'Link task to decision',
+                        request: '{ action: "link", task_id: 5, link_type: "decision", target_id: "api_auth_method", link_relation: "implements" }',
+                        explanation: 'Track which tasks implement specific decisions'
+                    },
+                    {
+                        scenario: 'Link task to constraint',
+                        request: '{ action: "link", task_id: 5, link_type: "constraint", target_id: 3, link_relation: "addresses" }',
+                        explanation: 'Show task addresses a performance/architecture/security constraint'
+                    },
+                    {
+                        scenario: 'Link task to file',
+                        request: '{ action: "link", task_id: 5, link_type: "file", target_id: "src/api/auth.ts", link_relation: "modifies" }',
+                        explanation: 'Activates automatic file watching for the task - saves 300 tokens per file vs manual registration',
+                        behavior: 'File watcher monitors linked files and validates acceptance criteria when files change'
+                    }
+                ]
+            },
+            batch_operations: {
+                title: 'Batch Task Creation',
+                examples: [
+                    {
+                        scenario: 'Create multiple related tasks',
+                        request: '{ action: "batch_create", tasks: [{"title": "Design API", "priority": 3}, {"title": "Implement API", "priority": 3}, {"title": "Write tests", "priority": 2}], atomic: false }',
+                        explanation: 'Create task breakdown - use atomic:false for best-effort'
+                    }
+                ]
+            },
+            filtering_queries: {
+                title: 'Advanced Task Queries',
+                examples: [
+                    {
+                        scenario: 'Find high-priority tasks for agent',
+                        request: '{ action: "list", assigned_agent: "backend-agent", priority: 3, status: "todo" }',
+                        note: 'Priority is numeric: 1=low, 2=medium, 3=high, 4=critical'
+                    },
+                    {
+                        scenario: 'Get all security-related tasks',
+                        request: '{ action: "list", tags: ["security"], limit: 50 }',
+                        explanation: 'Filter by tags for topic-based views'
+                    },
+                    {
+                        scenario: 'View infrastructure layer tasks',
+                        request: '{ action: "list", layer: "infrastructure" }',
+                        explanation: 'See all DevOps/config related tasks'
+                    }
+                ]
+            },
+            file_watcher_status: {
+                title: 'File Watcher Status Queries',
+                examples: [
+                    {
+                        scenario: 'Check if file watcher is running',
+                        request: '{ action: "watcher", subaction: "status" }',
+                        explanation: 'Returns running status, files watched count, tasks monitored count',
+                        response: '{ running: true, files_watched: 5, tasks_monitored: 3 }'
+                    },
+                    {
+                        scenario: 'List all files being watched',
+                        request: '{ action: "watcher", subaction: "list_files" }',
+                        explanation: 'Shows file paths and which tasks are watching them',
+                        response: '{ files: [{ file_path: "src/api/auth.ts", tasks: [{ task_id: 5, title: "...", status: "in_progress" }] }] }'
+                    },
+                    {
+                        scenario: 'List tasks with active file watchers',
+                        request: '{ action: "watcher", subaction: "list_tasks" }',
+                        explanation: 'Shows tasks and which files they are watching',
+                        response: '{ tasks: [{ task_id: 5, title: "...", files: ["src/api/auth.ts", "src/api/middleware.ts"] }] }'
+                    }
+                ]
+            }
+        },
+        valid_transitions: {
+            from_todo: ['in_progress', 'blocked', 'done', 'archived'],
+            from_in_progress: ['waiting_review', 'blocked', 'todo'],
+            from_waiting_review: ['done', 'in_progress', 'todo'],
+            from_blocked: ['todo', 'in_progress'],
+            from_done: ['archived', 'todo'],
+            from_archived: []
+        },
+        best_practices: {
+            task_creation: [
+                'Use descriptive titles (200 char max)',
+                'Set appropriate priority: 1=low, 2=medium (default), 3=high, 4=critical',
+                'Assign to layer where work will be done',
+                'Tag comprehensively for easy filtering',
+                'Include acceptance_criteria for complex tasks'
+            ],
+            status_management: [
+                'Move to in_progress when starting work',
+                'Use waiting_review for completed but unverified work',
+                'Set to blocked with notes explaining dependency',
+                'Archive done tasks periodically for cleaner views'
+            ],
+            linking: [
+                '⭐ RECOMMENDED: Set up file watchers for all tasks involving code changes (except exceptional cases)',
+                'Link tasks to decisions they implement',
+                'Link to constraints they address',
+                'Link files to activate automatic file watching (save 300 tokens per file vs manual registration)',
+                'Use descriptive link_relation values'
+            ],
+            coordination: [
+                'Use assigned_agent for clear ownership',
+                'Filter by status for Kanban board views',
+                'Monitor auto-stale transitions for stuck work',
+                'Use tags for cross-cutting concerns (security, performance, etc.)'
+            ]
+        }
+    };
+}
 //# sourceMappingURL=tasks.js.map