@allpepper/task-orchestrator 1.1.3 → 1.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@allpepper/task-orchestrator",
-  "version": "1.1.3",
+  "version": "1.2.1",
   "description": "MCP server for hierarchical task orchestration with SQLite persistence",
   "type": "module",
   "main": "src/index.ts",

package/src/db/migrate.ts

@@ -19,7 +19,7 @@ interface Migration {
 
 function loadMigrations(): Migration[] {
   const migrationsDir = join(dirname(import.meta.path), 'migrations');
-  const files = ['001_initial_schema.sql'];
+  const files = ['001_initial_schema.sql', '002_generalize_dependencies.sql'];
 
   return files.map((file, i) => ({
     version: i + 1,

package/src/db/migrations/002_generalize_dependencies.sql

@@ -0,0 +1,27 @@
+-- Migration 002: Generalize dependencies table for polymorphic entity references
+-- Renames task-specific columns to entity-generic ones and adds entity_type discriminator
+
+-- Step 1: Create new table with generalized schema
+CREATE TABLE IF NOT EXISTS dependencies_new (
+    id TEXT PRIMARY KEY,
+    from_entity_id TEXT NOT NULL,
+    to_entity_id TEXT NOT NULL,
+    entity_type TEXT NOT NULL DEFAULT 'task' CHECK (entity_type IN ('task', 'feature')),
+    type VARCHAR(20) NOT NULL CHECK (type IN ('BLOCKS', 'IS_BLOCKED_BY', 'RELATES_TO')),
+    created_at TEXT NOT NULL
+);
+
+-- Step 2: Copy existing data, mapping old columns to new and defaulting entity_type to 'task'
+INSERT INTO dependencies_new (id, from_entity_id, to_entity_id, entity_type, type, created_at)
+SELECT id, from_task_id, to_task_id, 'task', type, created_at
+FROM dependencies;
+
+-- Step 3: Drop old table and rename new one
+DROP TABLE IF EXISTS dependencies;
+ALTER TABLE dependencies_new RENAME TO dependencies;
+
+-- Step 4: Recreate indexes with new column names
+CREATE UNIQUE INDEX IF NOT EXISTS idx_dependencies_unique ON dependencies(from_entity_id, to_entity_id, type, entity_type);
+CREATE INDEX IF NOT EXISTS idx_dependencies_from_entity_id ON dependencies(from_entity_id);
+CREATE INDEX IF NOT EXISTS idx_dependencies_to_entity_id ON dependencies(to_entity_id);
+CREATE INDEX IF NOT EXISTS idx_dependencies_entity_type ON dependencies(entity_type);

package/src/domain/types.ts

@@ -76,6 +76,11 @@ export enum DependencyType {
   RELATES_TO = 'RELATES_TO'
 }
 
+export enum DependencyEntityType {
+  TASK = 'task',
+  FEATURE = 'feature'
+}
+
 export enum LockStatus {
   UNLOCKED = 'UNLOCKED',
   LOCKED_EXCLUSIVE = 'LOCKED_EXCLUSIVE',
@@ -177,8 +182,9 @@ export interface TemplateSection {
 
 export interface Dependency {
   id: string;
-  fromTaskId: string;
-  toTaskId: string;
+  fromEntityId: string;
+  toEntityId: string;
+  entityType: DependencyEntityType;
   type: DependencyType;
   createdAt: Date;
 }

package/src/repos/dependencies.ts

@@ -9,7 +9,7 @@ import {
   err,
   toDate
 } from './base';
-import type { Result, Dependency, DependencyType, Task } from '../domain/types';
+import type { Result, Dependency, DependencyType, DependencyEntityType, Task, Feature } from '../domain/types';
 import { ValidationError, NotFoundError, ConflictError } from '../domain/types';
 
 // ============================================================================
@@ -18,17 +18,17 @@ import { ValidationError, NotFoundError, ConflictError } from '../domain/types';
 
 /**
  * Check if adding a dependency would create a circular dependency.
- * Uses BFS to traverse the dependency graph from toTaskId following BLOCKS dependencies.
- * If we reach fromTaskId, it means adding fromTaskId -> toTaskId would create a cycle.
+ * Uses BFS to traverse the dependency graph from toEntityId following BLOCKS dependencies.
+ * If we reach fromEntityId, it means adding fromEntityId -> toEntityId would create a cycle.
  */
-function hasCircularDependency(fromTaskId: string, toTaskId: string): boolean {
+function hasCircularDependency(fromEntityId: string, toEntityId: string, entityType: DependencyEntityType): boolean {
   const visited = new Set<string>();
-  const queue = [toTaskId];
+  const queue = [toEntityId];
 
   while (queue.length > 0) {
     const current = queue.shift()!;
 
-    if (current === fromTaskId) {
+    if (current === fromEntityId) {
       return true;
     }
 
@@ -38,14 +38,13 @@ function hasCircularDependency(fromTaskId: string, toTaskId: string): boolean {
 
     visited.add(current);
 
-    // Follow BLOCKS dependencies from current task
-    const deps = queryAll<{ to_task_id: string }>(
-      "SELECT to_task_id FROM dependencies WHERE from_task_id = ? AND type = 'BLOCKS'",
-      [current]
+    const deps = queryAll<{ to_entity_id: string }>(
+      "SELECT to_entity_id FROM dependencies WHERE from_entity_id = ? AND type = 'BLOCKS' AND entity_type = ?",
+      [current, entityType]
     );
 
     for (const dep of deps) {
-      queue.push(dep.to_task_id);
+      queue.push(dep.to_entity_id);
     }
   }
 
@@ -60,8 +59,9 @@ function hasCircularDependency(fromTaskId: string, toTaskId: string): boolean {
 function mapRowToDependency(row: any): Dependency {
   return {
     id: row.id,
-    fromTaskId: row.from_task_id,
-    toTaskId: row.to_task_id,
+    fromEntityId: row.from_entity_id,
+    toEntityId: row.to_entity_id,
+    entityType: row.entity_type as DependencyEntityType,
     type: row.type as DependencyType,
     createdAt: toDate(row.created_at)
   };
@@ -87,52 +87,83 @@ function mapRowToTask(row: any): Task {
   };
 }
 
+/** Map database row to Feature domain object */
+function mapRowToFeature(row: any): Feature {
+  return {
+    id: row.id,
+    projectId: row.project_id ?? undefined,
+    name: row.name,
+    summary: row.summary,
+    description: row.description ?? undefined,
+    status: row.status,
+    priority: row.priority,
+    version: row.version,
+    createdAt: toDate(row.created_at),
+    modifiedAt: toDate(row.modified_at)
+  };
+}
+
 // ============================================================================
 // Repository Functions
 // ============================================================================
 
 /**
- * Create a new dependency between two tasks.
+ * Create a new dependency between two entities of the same type.
  *
  * Validates:
- * - fromTaskId != toTaskId (no self-dependency)
- * - Both tasks exist
+ * - fromEntityId != toEntityId (no self-dependency)
+ * - Both entities exist
  * - No circular dependencies (if A blocks B, B cannot block A)
  * - No duplicate dependencies
  */
 export function createDependency(params: {
-  fromTaskId: string;
-  toTaskId: string;
+  fromEntityId: string;
+  toEntityId: string;
   type: DependencyType;
+  entityType: DependencyEntityType;
 }): Result<Dependency> {
-  const { fromTaskId, toTaskId, type } = params;
+  let { fromEntityId, toEntityId, type, entityType } = params;
+
+  // Normalize IS_BLOCKED_BY → BLOCKS by swapping from/to.
+  // This keeps a single canonical form in the DB so all downstream
+  // queries only need to handle BLOCKS direction.
+  if (type === 'IS_BLOCKED_BY') {
+    [fromEntityId, toEntityId] = [toEntityId, fromEntityId];
+    type = 'BLOCKS' as DependencyType;
+  }
 
   // Validate: no self-dependency
-  if (fromTaskId === toTaskId) {
-    return err('Cannot create a dependency from a task to itself', 'SELF_DEPENDENCY');
+  if (fromEntityId === toEntityId) {
+    return err('Cannot create a dependency from an entity to itself', 'SELF_DEPENDENCY');
   }
 
-  // Validate: both tasks exist
-  const fromTask = queryOne<{ id: string }>(
-    'SELECT id FROM tasks WHERE id = ?',
-    [fromTaskId]
+  // Validate: both entities exist
+  const table = entityType === 'task' ? 'tasks' : 'features';
+  const fromEntity = queryOne<{ id: string }>(
+    `SELECT id FROM ${table} WHERE id = ?`,
+    [fromEntityId]
   );
 
-  if (!fromTask) {
-    return err(`Task not found: ${fromTaskId}`, 'NOT_FOUND');
+  if (!fromEntity) {
+    return err(`${entityType} not found: ${fromEntityId}`, 'NOT_FOUND');
   }
 
-  const toTask = queryOne<{ id: string }>(
-    'SELECT id FROM tasks WHERE id = ?',
-    [toTaskId]
+  const toEntity = queryOne<{ id: string }>(
+    `SELECT id FROM ${table} WHERE id = ?`,
+    [toEntityId]
   );
 
-  if (!toTask) {
-    return err(`Task not found: ${toTaskId}`, 'NOT_FOUND');
+  if (!toEntity) {
+    return err(`${entityType} not found: ${toEntityId}`, 'NOT_FOUND');
   }
 
   // Validate: no circular dependencies for BLOCKS type
-  if (type === 'BLOCKS' && hasCircularDependency(fromTaskId, toTaskId)) {
+  // (IS_BLOCKED_BY is already normalized to BLOCKS above, RELATES_TO has no direction)
+  const isCircular = type === 'BLOCKS'
+    ? hasCircularDependency(fromEntityId, toEntityId, entityType)
+    : false;
+
+  if (isCircular) {
     return err(
       'Cannot create dependency: would create a circular dependency',
       'CIRCULAR_DEPENDENCY'
@@ -141,13 +172,13 @@ export function createDependency(params: {
 
   // Check for duplicate
   const existing = queryOne<{ id: string }>(
-    'SELECT id FROM dependencies WHERE from_task_id = ? AND to_task_id = ? AND type = ?',
-    [fromTaskId, toTaskId, type]
+    'SELECT id FROM dependencies WHERE from_entity_id = ? AND to_entity_id = ? AND type = ? AND entity_type = ?',
+    [fromEntityId, toEntityId, type, entityType]
   );
 
   if (existing) {
     return err(
-      'Dependency already exists between these tasks with this type',
+      'Dependency already exists between these entities with this type',
       'DUPLICATE_DEPENDENCY'
     );
   }
@@ -158,14 +189,15 @@ export function createDependency(params: {
 
   try {
     execute(
-      'INSERT INTO dependencies (id, from_task_id, to_task_id, type, created_at) VALUES (?, ?, ?, ?, ?)',
-      [id, fromTaskId, toTaskId, type, createdAt]
+      'INSERT INTO dependencies (id, from_entity_id, to_entity_id, entity_type, type, created_at) VALUES (?, ?, ?, ?, ?, ?)',
+      [id, fromEntityId, toEntityId, entityType, type, createdAt]
     );
 
     const dependency: Dependency = {
       id,
-      fromTaskId,
-      toTaskId,
+      fromEntityId,
+      toEntityId,
+      entityType,
       type,
       createdAt: toDate(createdAt)
     };
@@ -177,33 +209,37 @@ export function createDependency(params: {
 }
 
 /**
- * Get dependencies for a task.
+ * Get dependencies for an entity.
  *
- * @param taskId - The task ID to query
+ * @param entityId - The entity ID to query
  * @param direction - Filter by direction:
- *   - 'dependencies': tasks that this task depends on (from_task_id = taskId)
- *   - 'dependents': tasks that depend on this task (to_task_id = taskId)
+ *   - 'dependencies': entities that this entity depends on (from_entity_id = entityId)
+ *   - 'dependents': entities that depend on this entity (to_entity_id = entityId)
  *   - 'both': union of above (default)
+ * @param entityType - Optional filter by entity type
  */
 export function getDependencies(
-  taskId: string,
-  direction: 'dependencies' | 'dependents' | 'both' = 'both'
+  entityId: string,
+  direction: 'dependencies' | 'dependents' | 'both' = 'both',
+  entityType?: DependencyEntityType
 ): Result<Dependency[]> {
   try {
     let dependencies: Dependency[] = [];
+    const typeFilter = entityType ? ' AND entity_type = ?' : '';
+    const typeParam = entityType ? [entityType] : [];
 
     if (direction === 'dependencies' || direction === 'both') {
       const rows = queryAll<any>(
-        'SELECT * FROM dependencies WHERE from_task_id = ? ORDER BY created_at',
-        [taskId]
+        `SELECT * FROM dependencies WHERE from_entity_id = ?${typeFilter} ORDER BY created_at`,
+        [entityId, ...typeParam]
       );
       dependencies.push(...rows.map(mapRowToDependency));
     }
 
     if (direction === 'dependents' || direction === 'both') {
       const rows = queryAll<any>(
-        'SELECT * FROM dependencies WHERE to_task_id = ? ORDER BY created_at',
-        [taskId]
+        `SELECT * FROM dependencies WHERE to_entity_id = ?${typeFilter} ORDER BY created_at`,
+        [entityId, ...typeParam]
       );
       dependencies.push(...rows.map(mapRowToDependency));
     }
@@ -232,125 +268,217 @@ export function deleteDependency(id: string): Result<boolean> {
 }
 
 /**
- * Get all blocked tasks.
+ * Get all blocked entities of a given type.
  *
- * Returns tasks that either:
+ * Returns entities that either:
  * - Have status = 'BLOCKED', OR
- * - Have incomplete blocking dependencies (tasks that block them but are not completed)
+ * - Have incomplete blocking dependencies (blockers that are not completed/resolved)
  *
- * @param params - Optional filters for projectId and/or featureId
+ * @param params - Entity type and optional filters
  */
-export function getBlockedTasks(params?: {
+export function getBlocked(params: {
+  entityType: DependencyEntityType;
   projectId?: string;
   featureId?: string;
-}): Result<Task[]> {
+}): Result<(Task | Feature)[]> {
   try {
-    let sql = `
-      SELECT DISTINCT t.*
-      FROM tasks t
-      WHERE (
-        t.status = 'BLOCKED'
-        OR EXISTS (
-          SELECT 1
-          FROM dependencies d
-          JOIN tasks blocker ON blocker.id = d.from_task_id
-          WHERE d.to_task_id = t.id
-            AND d.type = 'BLOCKS'
-            AND blocker.status NOT IN ('COMPLETED', 'CANCELLED')
+    const { entityType } = params;
+
+    if (entityType === 'task') {
+      let sql = `
+        SELECT DISTINCT t.*
+        FROM tasks t
+        WHERE (
+          t.status = 'BLOCKED'
+          OR EXISTS (
+            SELECT 1
+            FROM dependencies d
+            JOIN tasks blocker ON blocker.id = d.from_entity_id
+            WHERE d.to_entity_id = t.id
+              AND d.type = 'BLOCKS'
+              AND d.entity_type = 'task'
+              AND blocker.status NOT IN ('COMPLETED', 'CANCELLED')
+          )
         )
-      )
-    `;
-
-    const sqlParams: string[] = [];
-
-    if (params?.projectId) {
-      sql += ' AND t.project_id = ?';
-      sqlParams.push(params.projectId);
-    }
-
-    if (params?.featureId) {
-      sql += ' AND t.feature_id = ?';
-      sqlParams.push(params.featureId);
+      `;
+
+      const sqlParams: string[] = [];
+
+      if (params.projectId) {
+        sql += ' AND t.project_id = ?';
+        sqlParams.push(params.projectId);
+      }
+
+      if (params.featureId) {
+        sql += ' AND t.feature_id = ?';
+        sqlParams.push(params.featureId);
+      }
+
+      sql += `
+        ORDER BY
+          CASE t.priority
+            WHEN 'HIGH' THEN 1
+            WHEN 'MEDIUM' THEN 2
+            WHEN 'LOW' THEN 3
+          END,
+          t.created_at ASC
+      `;
+
+      const rows = queryAll<any>(sql, sqlParams);
+      return ok(rows.map(mapRowToTask));
+    } else {
+      let sql = `
+        SELECT DISTINCT f.*
+        FROM features f
+        WHERE (
+          f.status = 'BLOCKED'
+          OR EXISTS (
+            SELECT 1
+            FROM dependencies d
+            JOIN features blocker ON blocker.id = d.from_entity_id
+            WHERE d.to_entity_id = f.id
+              AND d.type = 'BLOCKS'
+              AND d.entity_type = 'feature'
+              AND blocker.status NOT IN ('COMPLETED', 'ARCHIVED')
+          )
+        )
+      `;
+
+      const sqlParams: string[] = [];
+
+      if (params.projectId) {
+        sql += ' AND f.project_id = ?';
+        sqlParams.push(params.projectId);
+      }
+
+      sql += `
+        ORDER BY
+          CASE f.priority
+            WHEN 'HIGH' THEN 1
+            WHEN 'MEDIUM' THEN 2
+            WHEN 'LOW' THEN 3
+          END,
+          f.created_at ASC
+      `;
+
+      const rows = queryAll<any>(sql, sqlParams);
+      return ok(rows.map(mapRowToFeature));
     }
-
-    sql += ' ORDER BY t.priority DESC, t.created_at ASC';
-
-    const rows = queryAll<any>(sql, sqlParams);
-    const tasks = rows.map(mapRowToTask);
-
-    return ok(tasks);
   } catch (error: any) {
-    return err(`Failed to get blocked tasks: ${error.message}`, 'QUERY_FAILED');
+    return err(`Failed to get blocked entities: ${error.message}`, 'QUERY_FAILED');
   }
 }
 
 /**
- * Get the next task to work on.
+ * Get the next entity to work on.
+ *
+ * For tasks: returns the highest priority PENDING task with no incomplete blockers.
+ * Ordered by priority, complexity (simpler first), then creation time.
  *
- * Returns the highest priority PENDING task that has no incomplete blocking dependencies.
- * Considers priority and complexity.
+ * For features: returns the highest priority DRAFT/PLANNING feature with no incomplete blockers.
+ * Ordered by priority, then creation time.
  *
- * @param params - Optional filters and priority preference
+ * @param params - Entity type, optional filters, and priority preference
  */
-export function getNextTask(params?: {
+export function getNext(params: {
+  entityType: DependencyEntityType;
   projectId?: string;
   featureId?: string;
   priority?: string;
-}): Result<Task | null> {
+}): Result<Task | Feature | null> {
   try {
-    let sql = `
-      SELECT t.*
-      FROM tasks t
-      WHERE t.status = 'PENDING'
-        AND NOT EXISTS (
-          SELECT 1
-          FROM dependencies d
-          JOIN tasks blocker ON blocker.id = d.from_task_id
-          WHERE d.to_task_id = t.id
-            AND d.type = 'BLOCKS'
-            AND blocker.status NOT IN ('COMPLETED', 'CANCELLED')
-        )
-    `;
-
-    const sqlParams: string[] = [];
-
-    if (params?.projectId) {
-      sql += ' AND t.project_id = ?';
-      sqlParams.push(params.projectId);
-    }
-
-    if (params?.featureId) {
-      sql += ' AND t.feature_id = ?';
-      sqlParams.push(params.featureId);
-    }
-
-    if (params?.priority) {
-      sql += ' AND t.priority = ?';
-      sqlParams.push(params.priority);
-    }
-
-    // Order by priority (HIGH > MEDIUM > LOW), then by complexity (simpler first), then by creation time
-    sql += `
-      ORDER BY
-        CASE t.priority
-          WHEN 'HIGH' THEN 1
-          WHEN 'MEDIUM' THEN 2
-          WHEN 'LOW' THEN 3
-        END,
-        t.complexity ASC,
-        t.created_at ASC
-      LIMIT 1
-    `;
-
-    const row = queryOne<any>(sql, sqlParams);
-
-    if (!row) {
-      return ok(null);
+    const { entityType } = params;
+
+    if (entityType === 'task') {
+      let sql = `
+        SELECT t.*
+        FROM tasks t
+        WHERE t.status = 'PENDING'
+          AND NOT EXISTS (
+            SELECT 1
+            FROM dependencies d
+            JOIN tasks blocker ON blocker.id = d.from_entity_id
+            WHERE d.to_entity_id = t.id
+              AND d.type = 'BLOCKS'
+              AND d.entity_type = 'task'
+              AND blocker.status NOT IN ('COMPLETED', 'CANCELLED')
+          )
+      `;
+
+      const sqlParams: string[] = [];
+
+      if (params.projectId) {
+        sql += ' AND t.project_id = ?';
+        sqlParams.push(params.projectId);
+      }
+
+      if (params.featureId) {
+        sql += ' AND t.feature_id = ?';
+        sqlParams.push(params.featureId);
+      }
+
+      if (params.priority) {
+        sql += ' AND t.priority = ?';
+        sqlParams.push(params.priority);
+      }
+
+      sql += `
+        ORDER BY
+          CASE t.priority
+            WHEN 'HIGH' THEN 1
+            WHEN 'MEDIUM' THEN 2
+            WHEN 'LOW' THEN 3
+          END,
+          t.complexity ASC,
+          t.created_at ASC
+        LIMIT 1
+      `;
+
+      const row = queryOne<any>(sql, sqlParams);
+      return ok(row ? mapRowToTask(row) : null);
+    } else {
+      let sql = `
+        SELECT f.*
+        FROM features f
+        WHERE f.status IN ('DRAFT', 'PLANNING')
+          AND NOT EXISTS (
+            SELECT 1
+            FROM dependencies d
+            JOIN features blocker ON blocker.id = d.from_entity_id
+            WHERE d.to_entity_id = f.id
+              AND d.type = 'BLOCKS'
+              AND d.entity_type = 'feature'
+              AND blocker.status NOT IN ('COMPLETED', 'ARCHIVED')
+          )
+      `;
+
+      const sqlParams: string[] = [];
+
+      if (params.projectId) {
+        sql += ' AND f.project_id = ?';
+        sqlParams.push(params.projectId);
+      }
+
+      if (params.priority) {
+        sql += ' AND f.priority = ?';
+        sqlParams.push(params.priority);
+      }
+
+      sql += `
+        ORDER BY
+          CASE f.priority
+            WHEN 'HIGH' THEN 1
+            WHEN 'MEDIUM' THEN 2
+            WHEN 'LOW' THEN 3
+          END,
+          f.created_at ASC
+        LIMIT 1
+      `;
+
+      const row = queryOne<any>(sql, sqlParams);
+      return ok(row ? mapRowToFeature(row) : null);
     }
-
-    const task = mapRowToTask(row);
-    return ok(task);
   } catch (error: any) {
-    return err(`Failed to get next task: ${error.message}`, 'QUERY_FAILED');
+    return err(`Failed to get next entity: ${error.message}`, 'QUERY_FAILED');
   }
 }

package/src/repos/features.ts

@@ -376,7 +376,7 @@ export function deleteFeature(id: string, options?: { cascade?: boolean }): Resu
 
         // Delete each task's dependencies, sections, and tags
         for (const task of taskIds) {
-          execute('DELETE FROM dependencies WHERE from_task_id = ? OR to_task_id = ?', [task.id, task.id]);
+          execute('DELETE FROM dependencies WHERE (from_entity_id = ? OR to_entity_id = ?) AND entity_type = ?', [task.id, task.id, 'task']);
           execute('DELETE FROM sections WHERE entity_type = ? AND entity_id = ?', [EntityType.TASK, task.id]);
           deleteTags(task.id, EntityType.TASK);
         }
@@ -385,6 +385,9 @@ export function deleteFeature(id: string, options?: { cascade?: boolean }): Resu
         execute('DELETE FROM tasks WHERE feature_id = ?', [id]);
       }
 
+      // Delete feature-level dependencies
+      execute('DELETE FROM dependencies WHERE (from_entity_id = ? OR to_entity_id = ?) AND entity_type = ?', [id, id, 'feature']);
+
       // Delete feature sections
       execute('DELETE FROM sections WHERE entity_type = ? AND entity_id = ?', [EntityType.FEATURE, id]);