@critical-path/core 0.14.0 → 0.15.0

package/src/engine/index.ts

@@ -20,11 +20,12 @@ import type {
   CreateProjectInput,
   Deliverable,
   DeliverableSummary,
-  CreateDeliverableInput
+  CreateDeliverableInput,
+  TaskLifecycleState
 } from '../types/index.js';
 import { StorageAdapter, InMemoryStore } from '../store/index.js';
 import { PluginRegistry } from '../plugins/index.js';
-import { deriveTaskLifecycleState, type TaskLifecycleState, resolveStatusDefinition } from '../utils/status.js';
+import { deriveTaskLifecycleState, resolveStatusDefinition } from '../utils/status.js';
 import {
   validateTransition,
   getAllowedNextStatuses,
@@ -335,16 +336,18 @@ export class CriticalPathEngine {
     const initialStatus = processedInput.status || taskInput.status || defaultStatus;
     const now = new Date().toISOString();
 
-    // Derive initial lifecycle timestamps
+    // Derive initial lifecycle timestamps and semantic status
     const statusDef = resolveStatusDefinition(initialStatus, project?.statusDefinitions || workflow?.statuses);
-    const actualStartDate = processedInput.actualStartDate ?? taskInput.actualStartDate ?? (statusDef.executionState === 'active' ? now : undefined);
-    const actualEndDate = processedInput.actualEndDate ?? taskInput.actualEndDate ?? (statusDef.completionState === 'done' ? now : undefined);
+    const semanticStatus = processedInput.semanticStatus ?? taskInput.semanticStatus ?? statusDef.category;
+    const actualStartDate = processedInput.actualStartDate ?? taskInput.actualStartDate ?? (statusDef.category === 'in_progress' ? now : undefined);
+    const actualEndDate = processedInput.actualEndDate ?? taskInput.actualEndDate ?? ((statusDef.category === 'completed' || statusDef.category === 'canceled') ? now : undefined);
 
     const created = await this.store.createTask({
       projectId,
       title: processedInput.title || taskInput.title,
       description: processedInput.description ?? taskInput.description,
       status: initialStatus,
+      semanticStatus,
       priority: processedInput.priority || taskInput.priority || 'medium',
       taskType: processedInput.taskType || taskInput.taskType || 'task',
       assigneeId: processedInput.assigneeId ?? taskInput.assigneeId,
@@ -366,7 +369,7 @@ export class CriticalPathEngine {
       estimatedDurationMinutes: processedInput.estimatedDurationMinutes ?? taskInput.estimatedDurationMinutes,
       actualDurationMinutes: processedInput.actualDurationMinutes ?? taskInput.actualDurationMinutes,
       billableDurationMinutes: processedInput.billableDurationMinutes ?? taskInput.billableDurationMinutes,
-      progress: processedInput.progress ?? taskInput.progress ?? (statusDef.completionState === 'done' ? 100 : 0),
+      progress: processedInput.progress ?? taskInput.progress ?? (statusDef.category === 'completed' ? 100 : 0),
       tags: processedInput.tags ?? taskInput.tags ?? [],
       customFields: processedInput.customFields ?? taskInput.customFields ?? {},
       parentId: processedInput.parentId ?? taskInput.parentId
@@ -428,13 +431,14 @@ export class CriticalPathEngine {
         processedUpdates.status,
         project?.statusDefinitions || workflow?.statuses
       );
+      processedUpdates.semanticStatus = processedUpdates.semanticStatus ?? statusDef.category;
       const now = new Date().toISOString();
-      if (statusDef.executionState === 'active' && !existing.actualStartDate && !processedUpdates.actualStartDate) {
+      if (statusDef.category === 'in_progress' && !existing.actualStartDate && !processedUpdates.actualStartDate) {
         processedUpdates.actualStartDate = now;
       }
-      if (statusDef.completionState === 'done' && !processedUpdates.actualEndDate) {
+      if ((statusDef.category === 'completed' || statusDef.category === 'canceled') && !processedUpdates.actualEndDate) {
         processedUpdates.actualEndDate = now;
-        if (processedUpdates.progress === undefined && (existing.progress || 0) < 100) {
+        if (statusDef.category === 'completed' && processedUpdates.progress === undefined && (existing.progress || 0) < 100) {
           processedUpdates.progress = 100;
         }
       }
@@ -590,13 +594,25 @@ export class CriticalPathEngine {
     };
   }
 
-  async getTaskLifecycleState(taskId: string): Promise<TaskLifecycleState | null> {
+  async getTaskLifecycleState(
+    taskId: string,
+    options?: { referenceDate?: Date; stalledThresholdDays?: number }
+  ): Promise<TaskLifecycleState | null> {
     const task = await this.getTask(taskId);
     if (!task) return null;
     const project = await this.getProject(task.projectId);
     const workflow = await this.resolveProjectWorkflow(task.projectId);
     const statusDefs = project?.statusDefinitions || workflow?.statuses;
-    return deriveTaskLifecycleState(task, statusDefs);
+
+    const graph = await this.getTaskDependencyGraph(taskId);
+    const upstreamTasks = graph.upstreamTasks;
+
+    return deriveTaskLifecycleState(task, {
+      customDefinitions: statusDefs,
+      referenceDate: options?.referenceDate,
+      stalledThresholdDays: options?.stalledThresholdDays,
+      upstreamTasks
+    });
   }
 
   // --- Time Tracking ---
@@ -1142,9 +1158,9 @@ export class CriticalPathEngine {
 
     for (const task of tasks) {
       const statusDef = resolveStatusDefinition(task.status, project?.statusDefinitions || workflow?.statuses);
-      if (statusDef.completionState === 'done') {
+      if (statusDef.category === 'completed') {
         completedTasks++;
-      } else if (statusDef.executionState === 'active') {
+      } else if (statusDef.category === 'in_progress') {
         activeTasks++;
       }
 
@@ -1154,7 +1170,7 @@ export class CriticalPathEngine {
       if (typeof task.progress === 'number') {
         totalProgress += task.progress;
       } else {
-        totalProgress += statusDef.completionState === 'done' ? 100 : 0;
+        totalProgress += statusDef.category === 'completed' ? 100 : 0;
       }
     }
 

package/src/index.test.ts

@@ -128,9 +128,9 @@ describe('CriticalPathEngine Core Tests', () => {
       key: 'CUST',
       name: 'Custom Workflow Project',
       statusDefinitions: [
-        { key: 'draft', label: 'Draft', completionState: 'not_done', executionState: 'inactive' },
-        { key: 'active_work', label: 'Active Work', completionState: 'not_done', executionState: 'active' },
-        { key: 'finished', label: 'Finished', completionState: 'done', executionState: 'inactive' }
+        { key: 'draft', label: 'Draft', category: 'not_started' },
+        { key: 'active_work', label: 'Active Work', category: 'in_progress' },
+        { key: 'finished', label: 'Finished', category: 'completed' }
       ]
     });
 
@@ -145,10 +145,10 @@ describe('CriticalPathEngine Core Tests', () => {
 
     const state = await engine.getTaskLifecycleState(task.id);
     expect(state).not.toBeNull();
-    expect(state?.completionState).toBe('not_done');
-    expect(state?.executionState).toBe('active');
+    expect(state?.semanticStatus).toBe('in_progress');
     expect(state?.isActive).toBe(true);
     expect(state?.isDone).toBe(false);
+    expect(state?.isBlocked).toBe(false);
   });
 
   it('builds task dependency graph with upstream and downstream tasks', async () => {
@@ -181,9 +181,9 @@ describe('CriticalPathEngine Core Tests', () => {
       name: 'Strict Software Workflow',
       defaultStatusKey: 'backlog',
       statuses: [
-        { key: 'backlog', label: 'Backlog', completionState: 'not_done', executionState: 'inactive' },
-        { key: 'in_progress', label: 'In Progress', completionState: 'not_done', executionState: 'active' },
-        { key: 'done', label: 'Done', completionState: 'done', executionState: 'inactive' }
+        { key: 'backlog', label: 'Backlog', category: 'not_started' },
+        { key: 'in_progress', label: 'In Progress', category: 'in_progress' },
+        { key: 'done', label: 'Done', category: 'completed' }
       ],
       transitions: [
         { id: 't1', fromStatusKey: 'backlog', toStatusKey: 'in_progress', name: 'Start Work' },

package/src/status.test.ts

@@ -0,0 +1,226 @@
+import { describe, it, expect } from 'vitest';
+import { CriticalPathEngine } from './engine/index.js';
+import { resolveStatusDefinition, deriveTaskLifecycleState } from './utils/status.js';
+import type { Task, StatusDefinition } from './types/index.js';
+
+describe('Universal Semantic Statuses & Implied Statuses', () => {
+  describe('resolveStatusDefinition', () => {
+    it('resolves core standard statuses to their semantic category', () => {
+      expect(resolveStatusDefinition('todo').category).toBe('not_started');
+      expect(resolveStatusDefinition('backlog').category).toBe('not_started');
+      expect(resolveStatusDefinition('in_progress').category).toBe('in_progress');
+      expect(resolveStatusDefinition('in_review').category).toBe('in_progress');
+      expect(resolveStatusDefinition('done').category).toBe('completed');
+      expect(resolveStatusDefinition('canceled').category).toBe('canceled');
+    });
+
+    it('resolves custom status definitions when provided', () => {
+      const customDefs: StatusDefinition[] = [
+        { key: 'concept', label: 'Concept & Brainstorming', category: 'not_started' },
+        { key: 'client_review', label: 'Client Feedback Session', category: 'in_progress' },
+        { key: 'shipped', label: 'Shipped to Customer', category: 'completed' },
+        { key: 'abandoned', label: 'Abandoned Initiative', category: 'canceled' }
+      ];
+
+      expect(resolveStatusDefinition('concept', customDefs).category).toBe('not_started');
+      expect(resolveStatusDefinition('client_review', customDefs).category).toBe('in_progress');
+      expect(resolveStatusDefinition('shipped', customDefs).category).toBe('completed');
+      expect(resolveStatusDefinition('abandoned', customDefs).category).toBe('canceled');
+    });
+
+    it('infers category heuristically when unknown status key is provided', () => {
+      expect(resolveStatusDefinition('draft_v2').category).toBe('not_started');
+      expect(resolveStatusDefinition('final_approved').category).toBe('completed');
+      expect(resolveStatusDefinition('active_development').category).toBe('in_progress');
+      expect(resolveStatusDefinition('rejected_proposal').category).toBe('canceled');
+      expect(resolveStatusDefinition('custom_arbitrary_key').category).toBe('not_started');
+    });
+  });
+
+  describe('deriveTaskLifecycleState', () => {
+    const baseTask: Task = {
+      id: 'task_1',
+      projectId: 'proj_1',
+      title: 'Design Wireframes',
+      status: 'todo',
+      priority: 'high',
+      createdAt: '2026-09-01T00:00:00.000Z',
+      updatedAt: '2026-09-01T00:00:00.000Z'
+    };
+
+    it('derives basic state for not_started task', () => {
+      const derived = deriveTaskLifecycleState(baseTask);
+      expect(derived.semanticStatus).toBe('not_started');
+      expect(derived.isActive).toBe(false);
+      expect(derived.isDone).toBe(false);
+      expect(derived.isCancelled).toBe(false);
+      expect(derived.isReady).toBe(true);
+      expect(derived.isBlocked).toBe(false);
+      expect(derived.isUnassigned).toBe(true);
+      expect(derived.isUnplanned).toBe(true);
+    });
+
+    it('derives blocked and ready states based on upstream tasks', () => {
+      const upstream1: Task = {
+        ...baseTask,
+        id: 'task_up1',
+        status: 'in_progress',
+        semanticStatus: 'in_progress'
+      };
+      const upstream2: Task = {
+        ...baseTask,
+        id: 'task_up2',
+        status: 'done',
+        semanticStatus: 'completed'
+      };
+
+      // When upstream1 is in progress, task_1 is blocked
+      const blockedState = deriveTaskLifecycleState(baseTask, {
+        upstreamTasks: [upstream1, upstream2]
+      });
+      expect(blockedState.isBlocked).toBe(true);
+      expect(blockedState.isReady).toBe(false);
+      expect(blockedState.blockingTaskIds).toEqual(['task_up1']);
+
+      // When all upstream tasks are completed, task_1 becomes ready
+      const allDoneState = deriveTaskLifecycleState(baseTask, {
+        upstreamTasks: [
+          { ...upstream1, status: 'done', semanticStatus: 'completed' },
+          upstream2
+        ]
+      });
+      expect(allDoneState.isBlocked).toBe(false);
+      expect(allDoneState.isReady).toBe(true);
+      expect(allDoneState.blockingTaskIds).toHaveLength(0);
+    });
+
+    it('derives schedule indicators: overdue, upcoming, unplanned', () => {
+      const refDate = new Date('2026-09-10T12:00:00.000Z');
+
+      // Overdue task
+      const overdueTask: Task = {
+        ...baseTask,
+        dueDate: '2026-09-08T00:00:00.000Z'
+      };
+      const overdueDerived = deriveTaskLifecycleState(overdueTask, { referenceDate: refDate });
+      expect(overdueDerived.isOverdue).toBe(true);
+      expect(overdueDerived.isUnplanned).toBe(false);
+
+      // Completed task is not overdue even if dueDate is past
+      const completedTask: Task = {
+        ...overdueTask,
+        status: 'done'
+      };
+      const completedDerived = deriveTaskLifecycleState(completedTask, { referenceDate: refDate });
+      expect(completedDerived.isOverdue).toBe(false);
+      expect(completedDerived.isDone).toBe(true);
+
+      // Upcoming task
+      const upcomingTask: Task = {
+        ...baseTask,
+        plannedStartDate: '2026-09-12T00:00:00.000Z' // within 3 days of Sept 10
+      };
+      const upcomingDerived = deriveTaskLifecycleState(upcomingTask, { referenceDate: refDate });
+      expect(upcomingDerived.isUpcoming).toBe(true);
+    });
+
+    it('derives resource indicators: unassigned and stalled', () => {
+      const refDate = new Date('2026-09-15T12:00:00.000Z');
+
+      // Assigned via assigneeId
+      const assignedTask1: Task = {
+        ...baseTask,
+        assigneeId: 'user_alice'
+      };
+      expect(deriveTaskLifecycleState(assignedTask1).isUnassigned).toBe(false);
+
+      // Assigned via assignees array
+      const assignedTask2: Task = {
+        ...baseTask,
+        assignees: [{ id: 'user_bob' }]
+      };
+      expect(deriveTaskLifecycleState(assignedTask2).isUnassigned).toBe(false);
+
+      // Stalled task: in_progress with no update in > 7 days
+      const stalledTask: Task = {
+        ...baseTask,
+        status: 'in_progress',
+        updatedAt: '2026-09-01T00:00:00.000Z'
+      };
+      const stalledDerived = deriveTaskLifecycleState(stalledTask, { referenceDate: refDate, stalledThresholdDays: 7 });
+      expect(stalledDerived.isStalled).toBe(true);
+
+      // Not stalled if updated recently
+      const activeTask: Task = {
+        ...stalledTask,
+        updatedAt: '2026-09-14T00:00:00.000Z'
+      };
+      expect(deriveTaskLifecycleState(activeTask, { referenceDate: refDate, stalledThresholdDays: 7 }).isStalled).toBe(false);
+    });
+
+    it('derives estimate indicators: isOverEstimate and isPaceWarning', () => {
+      // Over estimate by logged hours
+      const overEstimateTask: Task = {
+        ...baseTask,
+        status: 'in_progress',
+        estimatedHours: 10,
+        loggedHours: 12
+      };
+      const overEstDerived = deriveTaskLifecycleState(overEstimateTask);
+      expect(overEstDerived.isOverEstimate).toBe(true);
+
+      // Pace warning: in_progress task that has been active longer than estimated duration
+      const refDate = new Date('2026-09-10T00:00:00.000Z');
+      const paceWarningTask: Task = {
+        ...baseTask,
+        status: 'in_progress',
+        actualStartDate: '2026-09-01T00:00:00.000Z', // 9 days = 216 hours elapsed
+        estimatedHours: 40 // only 40 hours estimated
+      };
+      const paceDerived = deriveTaskLifecycleState(paceWarningTask, { referenceDate: refDate });
+      expect(paceDerived.isPaceWarning).toBe(true);
+    });
+  });
+
+  describe('Engine Integration', () => {
+    it('computes full lifecycle state with dependency graph integration', async () => {
+      const engine = new CriticalPathEngine();
+      const proj = await engine.createProject({ key: 'LIFECYCLE', name: 'Lifecycle Test' });
+
+      const taskA = await engine.createTask({
+        projectId: proj.id,
+        title: 'Task A (Dependency)',
+        status: 'todo',
+        priority: 'high'
+      });
+
+      const taskB = await engine.createTask({
+        projectId: proj.id,
+        title: 'Task B (Dependent)',
+        status: 'todo',
+        priority: 'medium'
+      });
+
+      await engine.store.addDependency({
+        taskId: taskB.id,
+        dependsOnTaskId: taskA.id,
+        type: 'blocking'
+      });
+
+      // Task B should be blocked by Task A
+      let stateB = await engine.getTaskLifecycleState(taskB.id);
+      expect(stateB?.isBlocked).toBe(true);
+      expect(stateB?.isReady).toBe(false);
+      expect(stateB?.blockingTaskIds).toEqual([taskA.id]);
+
+      // Complete Task A
+      await engine.updateTask(taskA.id, { status: 'done' });
+
+      // Task B should now be ready
+      stateB = await engine.getTaskLifecycleState(taskB.id);
+      expect(stateB?.isBlocked).toBe(false);
+      expect(stateB?.isReady).toBe(true);
+      expect(stateB?.blockingTaskIds).toEqual([]);
+    });
+  });
+});

package/src/store/firebase.test.ts

@@ -62,7 +62,7 @@ describe('FirebaseStore', () => {
       name: 'Firebase Workflow',
       isDefault: false,
       defaultStatusKey: 'backlog',
-      statuses: [{ key: 'backlog', label: 'Backlog', completionState: 'not_done', executionState: 'inactive' }],
+      statuses: [{ key: 'backlog', label: 'Backlog', category: 'not_started' }],
       transitions: []
     });
 

package/src/store/sqlite.test.ts

@@ -155,7 +155,7 @@ describe('SQLiteStore', () => {
       name: 'SQLite Workflow',
       isDefault: true,
       defaultStatusKey: 'todo',
-      statuses: [{ key: 'todo', label: 'To Do', completionState: 'not_done', executionState: 'inactive' }],
+      statuses: [{ key: 'todo', label: 'To Do', category: 'not_started' }],
       transitions: []
     });
 

package/src/types/index.ts

@@ -4,17 +4,33 @@ export type Priority = DefaultPriority | (string & {});
 export type DefaultTaskStatus = 'backlog' | 'todo' | 'in_progress' | 'in_review' | 'done' | 'canceled';
 export type TaskStatus = DefaultTaskStatus | (string & {});
 
-export type CompletionState = 'done' | 'not_done';
-export type ExecutionState = 'active' | 'inactive';
+export type SemanticStatus = 'not_started' | 'in_progress' | 'completed' | 'canceled';
 
 export interface StatusDefinition {
   key: string;
   label: string;
-  completionState: CompletionState;
-  executionState: ExecutionState;
-  isCancelled?: boolean;
+  category: SemanticStatus;
 }
 
+export interface TaskDerivedStatus {
+  semanticStatus: SemanticStatus;
+  isReady: boolean;
+  isBlocked: boolean;
+  blockingTaskIds: string[];
+  isOverdue: boolean;
+  isUpcoming: boolean;
+  isUnplanned: boolean;
+  isUnassigned: boolean;
+  isStalled: boolean;
+  isOverEstimate: boolean;
+  isPaceWarning: boolean;
+  isDone: boolean;
+  isActive: boolean;
+  isCancelled: boolean;
+}
+
+export type TaskLifecycleState = TaskDerivedStatus;
+
 export type Role = 'admin' | 'project_manager' | 'contributor' | 'viewer';
 
 export interface User {
@@ -142,6 +158,7 @@ export interface Task {
   title: string;
   description?: string;
   status: TaskStatus;
+  semanticStatus?: SemanticStatus;
   priority: Priority;
   taskType?: string; // e.g. "bug", "feature", "task", "epic"
   assigneeId?: string;

package/src/use-case-validation.test.ts

@@ -138,7 +138,7 @@ describe('Critical Path Use Case Validation Suite', () => {
       // Check Lifecycle State
       const lifecycle = await engine.getTaskLifecycleState(featureTask.id);
       expect(lifecycle?.isDone).toBe(true);
-      expect(lifecycle?.completionState).toBe('done');
+      expect(lifecycle?.semanticStatus).toBe('completed');
     });
   });
 

package/src/utils/status.ts

@@ -1,27 +1,24 @@
 import type {
   Task,
   StatusDefinition,
-  CompletionState,
-  ExecutionState
+  SemanticStatus,
+  TaskDerivedStatus,
 } from '../types/index.js';
 
 export const DEFAULT_STATUS_DEFINITIONS: Record<string, StatusDefinition> = {
-  backlog: { key: 'backlog', label: 'Backlog', completionState: 'not_done', executionState: 'inactive' },
-  todo: { key: 'todo', label: 'To Do', completionState: 'not_done', executionState: 'inactive' },
-  in_progress: { key: 'in_progress', label: 'In Progress', completionState: 'not_done', executionState: 'active' },
-  in_review: { key: 'in_review', label: 'In Review', completionState: 'not_done', executionState: 'active' },
-  done: { key: 'done', label: 'Done', completionState: 'done', executionState: 'inactive' },
-  canceled: { key: 'canceled', label: 'Canceled', completionState: 'done', executionState: 'inactive', isCancelled: true }
+  backlog: { key: 'backlog', label: 'Backlog', category: 'not_started' },
+  todo: { key: 'todo', label: 'To Do', category: 'not_started' },
+  in_progress: { key: 'in_progress', label: 'In Progress', category: 'in_progress' },
+  in_review: { key: 'in_review', label: 'In Review', category: 'in_progress' },
+  done: { key: 'done', label: 'Done', category: 'completed' },
+  canceled: { key: 'canceled', label: 'Canceled', category: 'canceled' }
 };
 
-export interface TaskLifecycleState {
-  completionState: CompletionState;
-  executionState: ExecutionState;
-  isDone: boolean;
-  isActive: boolean;
-  isCancelled: boolean;
-  isOverdue: boolean;
-  isUpcoming: boolean;
+export interface DeriveTaskLifecycleOptions {
+  customDefinitions?: StatusDefinition[];
+  referenceDate?: Date;
+  upstreamTasks?: Task[];
+  stalledThresholdDays?: number;
 }
 
 export function resolveStatusDefinition(
@@ -35,28 +32,66 @@ export function resolveStatusDefinition(
   if (DEFAULT_STATUS_DEFINITIONS[statusKey]) {
     return DEFAULT_STATUS_DEFINITIONS[statusKey];
   }
+
   // Fallback heuristic for unknown custom statuses:
-  const isDoneKey = ['done', 'completed', 'finished', 'closed', 'canceled', 'cancelled', 'approved', 'final'].includes(statusKey.toLowerCase());
-  const isActiveKey = ['in_progress', 'active', 'working', 'in_review', 'review'].includes(statusKey.toLowerCase());
+  const lower = statusKey.toLowerCase();
+  let category: SemanticStatus = 'not_started';
+  if (['canceled', 'cancelled', 'rejected', 'abandoned', 'void', 'dropped'].some((k) => lower.includes(k))) {
+    category = 'canceled';
+  } else if (['done', 'completed', 'finished', 'closed', 'approved', 'final', 'delivered', 'shipped'].some((k) => lower.includes(k))) {
+    category = 'completed';
+  } else if (['in_progress', 'active', 'working', 'in_review', 'review', 'testing', 'qa', 'building', 'editing'].some((k) => lower.includes(k))) {
+    category = 'in_progress';
+  }
+
   return {
     key: statusKey,
     label: statusKey,
-    completionState: isDoneKey ? 'done' : 'not_done',
-    executionState: isActiveKey ? 'active' : 'inactive',
-    isCancelled: statusKey.toLowerCase().includes('cancel')
+    category
   };
 }
 
 export function deriveTaskLifecycleState(
   task: Task,
-  customDefinitions?: StatusDefinition[],
-  referenceDate: Date = new Date()
-): TaskLifecycleState {
+  customDefinitionsOrOptions?: StatusDefinition[] | DeriveTaskLifecycleOptions,
+  legacyReferenceDate?: Date
+): TaskDerivedStatus {
+  let customDefinitions: StatusDefinition[] | undefined;
+  let referenceDate = legacyReferenceDate ?? new Date();
+  let upstreamTasks: Task[] = [];
+  let stalledThresholdDays = 5;
+
+  if (Array.isArray(customDefinitionsOrOptions)) {
+    customDefinitions = customDefinitionsOrOptions;
+  } else if (customDefinitionsOrOptions) {
+    customDefinitions = customDefinitionsOrOptions.customDefinitions;
+    if (customDefinitionsOrOptions.referenceDate) {
+      referenceDate = customDefinitionsOrOptions.referenceDate;
+    }
+    if (customDefinitionsOrOptions.upstreamTasks) {
+      upstreamTasks = customDefinitionsOrOptions.upstreamTasks;
+    }
+    if (customDefinitionsOrOptions.stalledThresholdDays !== undefined) {
+      stalledThresholdDays = customDefinitionsOrOptions.stalledThresholdDays;
+    }
+  }
+
   const def = resolveStatusDefinition(task.status, customDefinitions);
-  const isDone = def.completionState === 'done';
-  const isActive = def.executionState === 'active';
-  const isCancelled = Boolean(def.isCancelled);
+  const semanticStatus: SemanticStatus = def.category;
+  const isDone = semanticStatus === 'completed' || semanticStatus === 'canceled';
+  const isActive = semanticStatus === 'in_progress';
+  const isCancelled = semanticStatus === 'canceled';
 
+  // Dependency & Flow Indicators
+  const blockingTasks = upstreamTasks.filter((t) => {
+    const upstreamDef = resolveStatusDefinition(t.status, customDefinitions);
+    return upstreamDef.category !== 'completed';
+  });
+  const blockingTaskIds = blockingTasks.map((t) => t.id);
+  const isBlocked = !isDone && blockingTaskIds.length > 0;
+  const isReady = semanticStatus === 'not_started' && blockingTaskIds.length === 0;
+
+  // Time & Schedule Indicators
   let isOverdue = false;
   if (!isDone && task.dueDate) {
     const due = new Date(task.dueDate);
@@ -66,20 +101,71 @@ export function deriveTaskLifecycleState(
   }
 
   let isUpcoming = false;
-  if (!isDone && !isActive && task.plannedStartDate) {
+  if (semanticStatus === 'not_started' && task.plannedStartDate) {
     const plannedStart = new Date(task.plannedStartDate);
     if (!isNaN(plannedStart.getTime()) && plannedStart > referenceDate) {
       isUpcoming = true;
     }
   }
 
+  const isUnplanned = semanticStatus === 'not_started' && !task.iterationId && !task.plannedStartDate && !task.dueDate;
+
+  // Resource & Activity Indicators
+  const hasAssignee = Boolean(task.assigneeId || (task.assignees && task.assignees.length > 0));
+  const isUnassigned = !isDone && !hasAssignee;
+
+  let isStalled = false;
+  if (semanticStatus === 'in_progress') {
+    const lastActivity = task.updatedAt ? new Date(task.updatedAt) : (task.createdAt ? new Date(task.createdAt) : null);
+    if (lastActivity && !isNaN(lastActivity.getTime())) {
+      const thresholdMs = stalledThresholdDays * 24 * 60 * 60 * 1000;
+      if (referenceDate.getTime() - lastActivity.getTime() > thresholdMs) {
+        isStalled = true;
+      }
+    }
+  }
+
+  // Effort & Estimate Indicators
+  let isOverEstimate = false;
+  const loggedH = task.loggedHours ?? task.actualHours;
+  const estimatedH = task.estimatedHours;
+  if (estimatedH !== undefined && estimatedH > 0 && loggedH !== undefined && loggedH > estimatedH) {
+    isOverEstimate = true;
+  }
+  const actualM = task.actualDurationMinutes;
+  const estimatedM = task.estimatedDurationMinutes;
+  if (estimatedM !== undefined && estimatedM > 0 && actualM !== undefined && actualM > estimatedM) {
+    isOverEstimate = true;
+  }
+
+  let isPaceWarning = false;
+  if (semanticStatus === 'in_progress' && task.actualStartDate) {
+    const start = new Date(task.actualStartDate);
+    if (!isNaN(start.getTime())) {
+      const elapsedMs = referenceDate.getTime() - start.getTime();
+      const elapsedHours = elapsedMs / (1000 * 60 * 60);
+      if (estimatedH !== undefined && estimatedH > 0 && elapsedHours > estimatedH) {
+        isPaceWarning = true;
+      } else if (estimatedM !== undefined && estimatedM > 0 && (elapsedMs / (1000 * 60)) > estimatedM) {
+        isPaceWarning = true;
+      }
+    }
+  }
+
   return {
-    completionState: def.completionState,
-    executionState: def.executionState,
+    semanticStatus,
+    isReady,
+    isBlocked,
+    blockingTaskIds,
+    isOverdue,
+    isUpcoming,
+    isUnplanned,
+    isUnassigned,
+    isStalled,
+    isOverEstimate,
+    isPaceWarning,
     isDone,
     isActive,
-    isCancelled,
-    isOverdue,
-    isUpcoming
+    isCancelled
   };
 }