Domain: Tasks — Function Reference

⚠ HERITAGE EXTRACTION — donor AMS tasks domain (Wave 8 quarantine)

This file extracts the donor AMS src/domains/tasks/index.js (deleted R53). The 13-tool donor task family (task_create_batch, task_eisenhower, task_productivity_report, task_sync_to_gsd, task_link_roadmap, etc.) is donor genealogy. Phase 0 Colibri ships exactly 8 β Task Pipeline tools per ADR-004 R74.5 — no task_eisenhower, no task_sync_to_gsd, no task_create_batch. The canonical Phase 0 task surface is in ../mcp-tools-phase-0.md and ../../concepts/β-task-pipeline.md. The AMS_ACL_ENABLED flag is donor-only — Phase 0 has no ACL middleware.

Read this file as donor genealogy only.

The Tasks domain provides Eisenhower Matrix task management backed by SQLite. It implements smart project-context detection (4-level priority fallback), task dependency management with cycle detection, GSD sync, and roadmap linking. ACL enforcement is toggled via AMS_ACL_ENABLED.

MCP Tools Exposed

Tasks are exposed through the unified controller, not a tool definition file in this domain. Key tool names (from router): task_create, task_get, task_update, task_delete, task_list, task_create_batch, task_eisenhower, task_next_actions, task_productivity_report, task_sync_to_gsd, task_link_roadmap, task_get_by_roadmap, task_deps.

Tool Name (approximate) Description Key Inputs Returns
task_create Create a task title, description?, status?, priority?, projectId?, roadmapId?, nodeId?, phase?, progress? { success, task, message }
task_get Get a task by ID id: string { success, task }
task_update Update a task id: string, updates: object, projectId? { success, task, message }
task_delete Delete a task id: string, projectId? { success, message }
task_list List tasks with filters status?, priority?, projectId?, roadmapId?, limit?, offset? { success, count, items[], total, limit, offset, hasMore, projectFiltered }
task_create_batch Create multiple tasks tasks[]: array, projectId? { success, created, failed, taskIds[], errors[] }
task_eisenhower Get Eisenhower Matrix projectId?, detailMode?, quadrantLimit? Matrix object by priority quadrant
task_next_actions Get highest-priority todo tasks limit?, projectId? { success, count, projectFiltered, actions[] }
task_productivity_report Full productivity report projectId?, detailMode?, quadrantLimit? Comprehensive report with matrix, stats, next actions
task_sync_to_gsd Sync tasks → GSD markdown projectName: string { success, changes, changeDetails[], stats }
task_link_roadmap Link task to roadmap node taskId, roadmapId, nodeId?, phase?, projectId? { success, task, message }
task_get_by_roadmap Get tasks by roadmap roadmapId: string { success, roadmapId, count, items[] }
task_deps Manage task dependencies action: add\|remove\|get_chain\|get_blocked, taskId, dependsOn?, projectId? Dependency info

Core Functions

detectProjectContext(explicitProjectRef, options)

Purpose: Resolve the active project ID using a 4-level priority fallback. Parameters: explicitProjectRef?: string, options: { requireExplicitMatch?: boolean } Returns: Promise<string|null> — project ID or null (all tasks mode). Priority order:

  1. Explicit explicitProjectRef (name or ID lookup via dbResolveProjectByIdOrName)
  2. AMS_CURRENT_PROJECT environment variable
  3. Auto-detect single project (only if exactly one project exists)
  4. null (backward-compatible all-tasks mode) Notes for rewrite: This fallback logic is critical for backward compatibility. The requireExplicitMatch option causes an error if explicit ref not found.

assertTaskScope(taskId, projectId, actionLabel)

Purpose: Load a task and verify it belongs to the resolved project scope. Parameters: taskId: string, projectId: string|null, actionLabel: string Returns: Promise<{ task, scopedProjectId }> Side effects: Throws if task not found or project mismatch.

createTask(params)

Purpose: Validate and create a task in the database. Parameters: params: { title, description?, status?, priority?, projectId?, roadmapId?, nodeId?, phase?, progress? } Returns: Promise<{ success, task, message }> Side effects: Writes to tasks table. Project ID resolved via detectProjectContext.

getTask(id)

Purpose: Fetch a task by ID. Parameters: id: string Returns: Promise<{ success, task }> Side effects: Throws if not found.

updateTask(id, updates, projectId)

Purpose: Validate and update a task; auto-cancels dependent tasks when cancelling. Parameters: id: string, updates: object, projectId?: string Returns: Promise<{ success, task, message }> Side effects: If updates.status === 'cancelled' and was not cancelled before, triggers cancelDependentTasks(id) recursively.

createTaskBatch(params)

Purpose: Create multiple tasks in a loop; collects per-item errors. Parameters: params: { tasks: [], projectId? } Returns: Promise<{ success, created, failed, taskIds[], errors[] }>

deleteTask(id, projectId)

Purpose: Delete a task after verifying scope. Parameters: id: string, projectId?: string Returns: Promise<{ success, message }>

listTasks(filters)

Purpose: List tasks with optional filters; auto-detects project context. Parameters: filters: { status?, priority?, projectId?, roadmapId?, limit?, offset? } Returns: Promise<{ success, count, projectFiltered, items[], total, limit, offset, hasMore }>

getEisenhowerMatrix(projectId, options)

Purpose: Fetch all 4 Eisenhower quadrants in parallel; returns full or compact view. Parameters: projectId?: string, options: { detailMode?: 'full'|'compact'|'summary', quadrantLimit?: number } Returns: Promise<{ success, projectId, projectFiltered, detailMode, quadrantLimit, quadrants, matrix, matrixMeta }> Notes for rewrite: 4 parallel DB queries, one per priority value. Quadrant limits only apply in compact mode.

getNextActions(limit, projectId)

Purpose: Return top-N todo tasks sorted by Eisenhower priority score. Parameters: limit: number (default 5), projectId?: string Returns: Promise<{ success, count, projectFiltered, actions[] }> Algorithm: Priority score: urgent_important=4, not_urgent_important=3, urgent_not_important=2, not_urgent_not_important=1.

generateProductivityReport(projectId, options)

Purpose: Comprehensive productivity report combining matrix, next actions, and summary stats. Parameters: projectId?: string, options: { detailMode?, quadrantLimit? } Returns: Promise<{ success, projectFiltered, projectId, detailMode, summary, nextActions, eisenhower, matrix, matrixMeta, quadrantDistribution }>

syncTasksToGSD(projectName)

Purpose: Proxy to syncTasksToGSDAtomic — write task statuses to GSD TODOS.md. Parameters: projectName: string Returns: Promise<sync result>

linkTaskToRoadmap(taskId, roadmapId, nodeId, phase, projectId)

Purpose: Update a task’s roadmap link fields. Parameters: taskId, roadmapId, nodeId?, phase?, projectId? Returns: Promise<{ success, task, message }>

getTasksByRoadmap(roadmapId)

Purpose: List all tasks linked to a specific roadmap. Parameters: roadmapId: string Returns: Promise<{ success, roadmapId, count, items[], total, ... }>

handleTaskDeps(action, taskId, dependsOn, projectId)

Purpose: Add, remove, or query task dependency relationships. Parameters: action: 'add'|'remove'|'get_chain'|'get_blocked', taskId: string, dependsOn?: string, projectId?: string Returns: Promise<object> varies by action. Notes for rewrite:

  • add: validates both tasks exist and are in same project scope; prevents cross-project deps with ACL
  • get_chain: returns direct deps + full chain with cycle detection
  • get_blocked: returns tasks that depend on this task (reverse lookup)

initTaskDomain()

Purpose: No-op initialization stub for compatibility.

Database Operations

Operation Query Pattern Tables Used
Create task INSERT with UUID tasks
Get task SELECT by id tasks
Update task UPDATE by id tasks
Delete task DELETE by id tasks
List tasks SELECT with WHERE filters + LIMIT/OFFSET tasks
Resolve project SELECT by id or name gsd_projects
List GSD projects SELECT all gsd_projects
Add dependency INSERT task_dependencies
Remove dependency DELETE task_dependencies
Get dependencies SELECT task_dependencies
Get blocked by SELECT reverse task_dependencies
Dependency chain Recursive walk via multiple SELECTs task_dependencies, tasks

Key Algorithms

Eisenhower Priority Sort 

priority_score = { urgent_important: 4, not_urgent_important: 3,
                   urgent_not_important: 2, not_urgent_not_important: 1 }
sorted = tasks.sort((a, b) => priority_score[b.priority] - priority_score[a.priority])
return sorted.slice(0, limit)

Cascade Cancellation (cancelDependentTasks) 

queue = [taskId], visited = Set()
while queue not empty:
  current = queue.shift()
  if current in visited: continue
  visited.add(current)
  blocked = dbGetTasksBlockedBy(current)  // tasks that depend on current
  for each blocked task:
    if status not done/cancelled: dbUpdateTask(id, { status: 'cancelled' })
    queue.push(blockedId)

Recursive Dependency Count 

countDependencies(chain):
  count = 0
  for item in chain:
    count += 1
    if item.subDependencies: count += countDependencies(item.subDependencies)
  return count

Compact Task Shape (toCompactTask)

Fields returned: id, title, status, priority, progress, phase, roadmapId, nodeId, projectId

buildStatusBreakdown 

reduce tasks into { [status]: count } map

Back to top

Colibri — documentation-first MCP runtime. Apache 2.0 + Commons Clause.

This site uses Just the Docs, a documentation theme for Jekyll.