@critical-path/core 0.20.1 → 0.21.0

package/src/domain/metrics.ts

@@ -478,7 +478,8 @@ export function calculateTaskMetrics(
     isEndDateInferred: Boolean(task.actualEndDate && task.semanticStatus === 'completed'),
     activeWorkingHours,
     calendarDurationHours,
-    actualDurationSeconds: task.actualDurationSeconds
+    actualDurationSeconds: task.actualDurationSeconds,
+    blockedDurationSeconds: task.blockedDurationSeconds
   };
 
   const progress = inferTaskProgress(task, options);

package/src/domain/task-duration.test.ts

@@ -2,6 +2,7 @@ import { describe, it, expect, vi } from 'vitest';
 import { TaskEntity } from './entities.js';
 import { CriticalPathEngine } from '../engine/index.js';
 import { InMemoryStore } from '../store/index.js';
+import { SQLiteStore } from '../store/sqlite.js';
 import { DEFAULT_SOFTWARE_WORKFLOW } from '../utils/workflow.js';
 
 describe('Task Execution Timestamps & Cumulative In-Progress Duration', () => {
@@ -167,4 +168,187 @@ describe('Task Execution Timestamps & Cumulative In-Progress Duration', () => {
       vi.useRealTimers();
     }
   });
+
+  it('tracks blocked duration while task is in_progress', async () => {
+    vi.useFakeTimers();
+    try {
+      const store = new InMemoryStore();
+      const engine = new CriticalPathEngine({ store });
+
+      const project = await engine.createProject({
+        name: 'Blocked Project'
+      });
+
+      vi.setSystemTime(new Date('2026-09-24T10:00:00Z'));
+      const task = await engine.createTask({
+        projectId: project.id,
+        title: 'Blocked Tracking Feature'
+      });
+
+      // 1. Being blocked in 'todo' does NOT accumulate blocked duration or stamp blockedSince
+      await engine.updateTask(task.id, { isBlocked: true, blockedReason: 'Waiting for spec' });
+      const todoBlocked = await engine.getTask(task.id);
+      expect(todoBlocked?.isBlocked).toBe(true);
+      expect(todoBlocked?.blockedSince).toBeUndefined();
+      expect(todoBlocked?.blockedDurationSeconds).toBeUndefined();
+
+      // 2. Unblock while still in todo
+      await engine.updateTask(task.id, { isBlocked: false, blockedReason: null });
+
+      // 3. Start task at 10:00:00 (in_progress)
+      const started = await engine.updateTask(task.id, { status: 'in_progress' });
+      expect(started?.inProgressSince).toBe('2026-09-24T10:00:00.000Z');
+      expect(started?.blockedSince).toBeUndefined();
+
+      // 4. Block task at 10:00:30 (30 seconds in)
+      vi.setSystemTime(new Date('2026-09-24T10:00:30Z'));
+      const blocked = await engine.updateTask(task.id, { isBlocked: true, blockedReason: 'API down' });
+      expect(blocked?.isBlocked).toBe(true);
+      expect(blocked?.blockedSince).toBe('2026-09-24T10:00:30.000Z');
+
+      // 5. Unblock task at 10:01:00 (30 seconds blocked)
+      vi.setSystemTime(new Date('2026-09-24T10:01:00Z'));
+      const unblocked = await engine.updateTask(task.id, { isBlocked: false, blockedReason: null });
+      expect(unblocked?.isBlocked).toBe(false);
+      expect(unblocked?.blockedSince).toBeNull();
+      expect(unblocked?.blockedDurationSeconds).toBe(30);
+
+      // 6. Block again at 10:01:10
+      vi.setSystemTime(new Date('2026-09-24T10:01:10Z'));
+      const blockedAgain = await engine.updateTask(task.id, { isBlocked: true, blockedReason: 'Review pending' });
+      expect(blockedAgain?.blockedSince).toBe('2026-09-24T10:01:10.000Z');
+
+      // 7. Complete task at 10:01:24 while still blocked (14 seconds blocked)
+      // Total gross in-progress: 84s (1m 24s)
+      // Total blocked duration: 30s + 14s = 44s
+      vi.setSystemTime(new Date('2026-09-24T10:01:24Z'));
+      const completed = await engine.updateTask(task.id, { status: 'done' });
+      expect(completed?.status).toBe('done');
+      expect(completed?.actualDurationSeconds).toBe(84);
+      expect(completed?.blockedDurationSeconds).toBe(44);
+      expect(completed?.blockedSince).toBeNull();
+
+      // 8. Verify metrics
+      const metrics = await engine.getTaskMetrics(task.id);
+      expect(metrics?.inferredActuals.actualDurationSeconds).toBe(84);
+      expect(metrics?.inferredActuals.blockedDurationSeconds).toBe(44);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('persists and retrieves blocked duration fields in SQLiteStore', async () => {
+    const store = new SQLiteStore({ filename: ':memory:' });
+    const project = await store.createProject({ key: 'SQL', name: 'SQLite Project' });
+
+    const task = await store.createTask({
+      projectId: project.id,
+      title: 'SQLite Blocked Task',
+      status: 'in_progress',
+      priority: 'medium',
+      isBlocked: true,
+      blockedReason: 'Third party dependency',
+      blockedSince: '2026-09-24T12:00:00.000Z',
+      blockedDurationSeconds: 120
+    });
+
+    const retrieved = await store.getTask(task.id);
+    expect(retrieved?.isBlocked).toBe(true);
+    expect(retrieved?.blockedReason).toBe('Third party dependency');
+    expect(retrieved?.blockedSince).toBe('2026-09-24T12:00:00.000Z');
+    expect(retrieved?.blockedDurationSeconds).toBe(120);
+
+    const updated = await store.updateTask(task.id, {
+      isBlocked: false,
+      blockedReason: null,
+      blockedSince: null,
+      blockedDurationSeconds: 180
+    });
+    expect(updated?.isBlocked).toBe(false);
+    expect(updated?.blockedReason).toBeFalsy();
+    expect(updated?.blockedSince).toBeFalsy();
+    expect(updated?.blockedDurationSeconds).toBe(180);
+
+    const reloaded = await store.getTask(task.id);
+    expect(reloaded?.isBlocked).toBe(false);
+    expect(reloaded?.blockedReason).toBeUndefined();
+    expect(reloaded?.blockedSince).toBeUndefined();
+    expect(reloaded?.blockedDurationSeconds).toBe(180);
+  });
+
+  it('manages blocked state directly on TaskEntity transitions and updates', () => {
+    vi.useFakeTimers();
+    try {
+      vi.setSystemTime(new Date('2026-09-24T12:00:00Z'));
+      const task = TaskEntity.create({
+        projectId: 'proj_blk',
+        title: 'Entity Blocked Test',
+        status: 'in_progress'
+      });
+
+      // Block while in progress
+      vi.setSystemTime(new Date('2026-09-24T12:00:30Z'));
+      task.update({ isBlocked: true, blockedReason: 'Database migration' });
+      expect(task.isBlocked).toBe(true);
+      expect(task.blockedSince).toBe('2026-09-24T12:00:30.000Z');
+
+      // Unblock while in progress
+      vi.setSystemTime(new Date('2026-09-24T12:01:00Z'));
+      task.update({ isBlocked: false, blockedReason: null });
+      expect(task.isBlocked).toBe(false);
+      expect(task.blockedSince).toBeNull();
+      expect(task.blockedDurationSeconds).toBe(30);
+
+      // Block again
+      vi.setSystemTime(new Date('2026-09-24T12:01:10Z'));
+      task.update({ isBlocked: true, blockedReason: 'Code review' });
+      expect(task.blockedSince).toBe('2026-09-24T12:01:10.000Z');
+
+      // Transition to completed (done) while blocked
+      vi.setSystemTime(new Date('2026-09-24T12:01:30Z'));
+      task.transitionTo('done', DEFAULT_SOFTWARE_WORKFLOW);
+      expect(task.status).toBe('done');
+      expect(task.actualDurationSeconds).toBe(90);
+      expect(task.blockedDurationSeconds).toBe(50); // 30s + 20s
+      expect(task.blockedSince).toBeNull();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('sets completedAt and actualEndDate on completion and resets progress when reopening', async () => {
+    vi.useFakeTimers();
+    try {
+      const store = new InMemoryStore();
+      const engine = new CriticalPathEngine({ store });
+
+      const project = await engine.createProject({ name: 'Progress Transition Proj' });
+      vi.setSystemTime(new Date('2026-10-01T10:00:00Z'));
+      const task = await engine.createTask({
+        projectId: project.id,
+        title: 'Task for completion test',
+        status: 'in_progress',
+        progress: 50
+      });
+
+      // Complete the task
+      vi.setSystemTime(new Date('2026-10-01T12:00:00Z'));
+      const completed = await engine.updateTask(task.id, { status: 'done' });
+      expect(completed?.status).toBe('done');
+      expect(completed?.actualEndDate).toBe('2026-10-01T12:00:00.000Z');
+      expect(completed?.completedAt).toBe('2026-10-01T12:00:00.000Z');
+      expect(completed?.progress).toBe(100);
+
+      // Reopen to todo -> actualEndDate & completedAt cleared, progress reset from 100 to 0
+      vi.setSystemTime(new Date('2026-10-01T13:00:00Z'));
+      const reopened = await engine.updateTask(task.id, { status: 'todo' });
+      expect(reopened?.status).toBe('todo');
+      expect(reopened?.actualEndDate).toBeUndefined();
+      expect(reopened?.completedAt).toBeUndefined();
+      expect(reopened?.progress).toBe(0);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
 });
+

package/src/engine/index.ts

@@ -373,6 +373,11 @@ export class CriticalPathEngine {
     const actualStartDate = processedInput.actualStartDate ?? taskInput.actualStartDate ?? (statusDef.category === 'in_progress' ? now : undefined);
     const inProgressSince = processedInput.inProgressSince ?? taskInput.inProgressSince ?? (statusDef.category === 'in_progress' ? now : undefined);
     const actualEndDate = processedInput.actualEndDate ?? taskInput.actualEndDate ?? ((statusDef.category === 'completed' || statusDef.category === 'canceled') ? now : undefined);
+    const completedAt = processedInput.completedAt ?? taskInput.completedAt ?? (statusDef.category === 'completed' ? now : undefined);
+
+    const isInitialBlocked = processedInput.isBlocked ?? taskInput.isBlocked ?? false;
+    const blockedSince = processedInput.blockedSince ?? taskInput.blockedSince ?? (isInitialBlocked && statusDef.category === 'in_progress' ? now : undefined);
+    const blockedDurationSeconds = processedInput.blockedDurationSeconds ?? taskInput.blockedDurationSeconds;
 
     const created = await this.store.createTask({
       projectId,
@@ -393,6 +398,7 @@ export class CriticalPathEngine {
       plannedStartDate: processedInput.plannedStartDate ?? taskInput.plannedStartDate,
       actualStartDate,
       actualEndDate,
+      completedAt,
       dueDate: processedInput.dueDate ?? taskInput.dueDate,
       estimatedHours: processedInput.estimatedHours ?? taskInput.estimatedHours,
       loggedHours: processedInput.loggedHours ?? taskInput.loggedHours ?? 0,
@@ -403,8 +409,10 @@ export class CriticalPathEngine {
       billableDurationMinutes: processedInput.billableDurationMinutes ?? taskInput.billableDurationMinutes,
       actualDurationSeconds: processedInput.actualDurationSeconds ?? taskInput.actualDurationSeconds,
       inProgressSince,
+      blockedDurationSeconds,
+      blockedSince,
       progress: processedInput.progress ?? taskInput.progress ?? (statusDef.category === 'completed' ? 100 : 0),
-      isBlocked: processedInput.isBlocked ?? taskInput.isBlocked ?? false,
+      isBlocked: isInitialBlocked,
       blockedReason: processedInput.blockedReason ?? taskInput.blockedReason ?? null,
       tags: processedInput.tags ?? taskInput.tags ?? [],
       customFields: processedInput.customFields ?? taskInput.customFields ?? {},
@@ -507,22 +515,25 @@ export class CriticalPathEngine {
 
     const processedUpdates = await this.plugins.runBeforeTaskUpdate(id, taskUpdates);
 
-    // Auto-update execution/completion timestamps if status changes
-    if (processedUpdates.status && processedUpdates.status !== existing.status) {
-      const statusDef = resolveStatusDefinition(
-        processedUpdates.status,
-        project?.statusDefinitions || workflow?.statuses
-      );
-      processedUpdates.semanticStatus = processedUpdates.semanticStatus ?? statusDef.category;
-      const now = new Date().toISOString();
+    const now = new Date().toISOString();
+    const existingStatusDef = resolveStatusDefinition(
+      existing.status,
+      project?.statusDefinitions || workflow?.statuses
+    );
+    const newStatusDef = processedUpdates.status
+      ? resolveStatusDefinition(
+          processedUpdates.status,
+          project?.statusDefinitions || workflow?.statuses
+        )
+      : undefined;
+    const effectiveCategory = newStatusDef?.category ?? existingStatusDef.category;
 
-      const existingStatusDef = resolveStatusDefinition(
-        existing.status,
-        project?.statusDefinitions || workflow?.statuses
-      );
+    // Auto-update execution/completion timestamps if status changes
+    if (processedUpdates.status && processedUpdates.status !== existing.status && newStatusDef) {
+      processedUpdates.semanticStatus = processedUpdates.semanticStatus ?? newStatusDef.category;
 
-      // 1. Leaving in_progress: finalize active session duration
-      if (existingStatusDef.category === 'in_progress' && statusDef.category !== 'in_progress') {
+      // 1. Leaving in_progress: finalize active session duration and blocked duration
+      if (existingStatusDef.category === 'in_progress' && newStatusDef.category !== 'in_progress') {
         const inProgressSince = existing.inProgressSince;
         if (inProgressSince) {
           const startMs = new Date(inProgressSince).getTime();
@@ -540,39 +551,113 @@ export class CriticalPathEngine {
           }
           processedUpdates.inProgressSince = null;
         }
+
+        const blockedSince = processedUpdates.blockedSince ?? existing.blockedSince;
+        if (blockedSince) {
+          const startMs = new Date(blockedSince).getTime();
+          const endMs = new Date(now).getTime();
+          if (!isNaN(startMs) && !isNaN(endMs) && endMs >= startMs) {
+            const sessionSeconds = Math.max(0, (endMs - startMs) / 1000);
+            processedUpdates.blockedDurationSeconds =
+              (processedUpdates.blockedDurationSeconds ?? existing.blockedDurationSeconds ?? 0) + sessionSeconds;
+          }
+          processedUpdates.blockedSince = null;
+        }
       }
 
-      // 2. Entering in_progress: retain earliest start date & start session timer
-      if (statusDef.category === 'in_progress') {
+      // 2. Entering in_progress: retain earliest start date & start session timer (and blocked timer if blocked)
+      if (newStatusDef.category === 'in_progress') {
         if (!existing.actualStartDate && !processedUpdates.actualStartDate) {
           processedUpdates.actualStartDate = now;
         }
         if (!processedUpdates.inProgressSince) {
           processedUpdates.inProgressSince = now;
         }
+        const isTaskBlocked = processedUpdates.isBlocked !== undefined
+          ? Boolean(processedUpdates.isBlocked)
+          : Boolean(existing.isBlocked);
+        if (isTaskBlocked && !processedUpdates.blockedSince) {
+          processedUpdates.blockedSince = now;
+        }
+        // Moving from completed/canceled to in_progress resets completion timestamp and progress
         if (
-          (existingStatusDef.category === 'completed' || existingStatusDef.category === 'canceled') &&
-          processedUpdates.actualEndDate === undefined
+          existingStatusDef.category === 'completed' || existingStatusDef.category === 'canceled'
         ) {
-          processedUpdates.actualEndDate = undefined;
+          if (processedUpdates.actualEndDate === undefined) {
+            processedUpdates.actualEndDate = undefined;
+          }
+          if (processedUpdates.completedAt === undefined) {
+            processedUpdates.completedAt = undefined;
+          }
+          if (existing.progress === 100 && processedUpdates.progress === undefined) {
+            processedUpdates.progress = 0;
+          }
         }
       } else if (
         (existingStatusDef.category === 'completed' || existingStatusDef.category === 'canceled') &&
-        statusDef.category === 'not_started' &&
-        processedUpdates.actualEndDate === undefined
+        newStatusDef.category === 'not_started'
       ) {
-        processedUpdates.actualEndDate = undefined;
+        // Moving from completed/canceled to not_started resets completion timestamp and progress
+        if (processedUpdates.actualEndDate === undefined) {
+          processedUpdates.actualEndDate = undefined;
+        }
+        if (processedUpdates.completedAt === undefined) {
+          processedUpdates.completedAt = undefined;
+        }
+        if (existing.progress === 100 && processedUpdates.progress === undefined) {
+          processedUpdates.progress = 0;
+        }
       }
 
       // 3. Entering completed or canceled
-      if ((statusDef.category === 'completed' || statusDef.category === 'canceled') && !processedUpdates.actualEndDate) {
-        processedUpdates.actualEndDate = now;
-        if (statusDef.category === 'completed' && processedUpdates.progress === undefined && (existing.progress || 0) < 100) {
+      if (newStatusDef.category === 'completed') {
+        if (!processedUpdates.actualEndDate) {
+          processedUpdates.actualEndDate = now;
+        }
+        if (!processedUpdates.completedAt) {
+          processedUpdates.completedAt = now;
+        }
+        if (processedUpdates.progress === undefined && (existing.progress || 0) < 100) {
           processedUpdates.progress = 100;
         }
+      } else if (newStatusDef.category === 'canceled') {
+        if (!processedUpdates.actualEndDate) {
+          processedUpdates.actualEndDate = now;
+        }
+        if (processedUpdates.completedAt === undefined) {
+          processedUpdates.completedAt = undefined;
+        }
       }
     }
 
+    // Handle isBlocked transitions while in_progress (when in_progress, whether status changed or not)
+    if (effectiveCategory === 'in_progress') {
+      const wasBlocked = Boolean(existing.isBlocked);
+      const isNowBlocked = processedUpdates.isBlocked !== undefined
+        ? Boolean(processedUpdates.isBlocked)
+        : wasBlocked;
+
+      if (!wasBlocked && isNowBlocked) {
+        if (!processedUpdates.blockedSince) {
+          processedUpdates.blockedSince = now;
+        }
+      } else if (wasBlocked && !isNowBlocked) {
+        const blockedSince = existing.blockedSince ?? processedUpdates.blockedSince;
+        if (blockedSince) {
+          const startMs = new Date(blockedSince).getTime();
+          const endMs = new Date(now).getTime();
+          if (!isNaN(startMs) && !isNaN(endMs) && endMs >= startMs) {
+            const sessionSeconds = Math.max(0, (endMs - startMs) / 1000);
+            processedUpdates.blockedDurationSeconds =
+              (processedUpdates.blockedDurationSeconds ?? existing.blockedDurationSeconds ?? 0) + sessionSeconds;
+          }
+          processedUpdates.blockedSince = null;
+        }
+      }
+    } else if (processedUpdates.isBlocked === false && (existing.blockedSince || processedUpdates.blockedSince)) {
+      processedUpdates.blockedSince = null;
+    }
+
     // Mutual sync for manual duration/effort edits
     if (processedUpdates.actualDurationSeconds !== undefined && processedUpdates.actualHours === undefined) {
       processedUpdates.actualHours = Math.round((processedUpdates.actualDurationSeconds / 3600) * 100) / 100;
@@ -591,7 +676,6 @@ export class CriticalPathEngine {
 
     await this.plugins.runAfterTaskUpdate(updated, existing);
 
-    const now = new Date().toISOString();
     const isStatusChange = existing.status !== updated.status;
 
     // Publish typed Domain Events
@@ -741,9 +825,18 @@ export class CriticalPathEngine {
           let updatedDownstream = downstream;
           const updates: Partial<Task> = {};
 
-          if (downstream.isBlocked || downstream.blockedReason) {
+          if (downstream.isBlocked || downstream.blockedReason || downstream.blockedSince) {
             updates.isBlocked = false;
             updates.blockedReason = null;
+            if (downstream.blockedSince) {
+              const startMs = new Date(downstream.blockedSince).getTime();
+              const endMs = new Date().getTime();
+              if (!isNaN(startMs) && !isNaN(endMs) && endMs >= startMs) {
+                const blockedSeconds = Math.max(0, (endMs - startMs) / 1000);
+                updates.blockedDurationSeconds = (downstream.blockedDurationSeconds ?? 0) + blockedSeconds;
+              }
+              updates.blockedSince = null;
+            }
           }
 
           if (Object.keys(updates).length > 0) {

package/src/status.test.ts

@@ -1,7 +1,22 @@
 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';
+import {
+  resolveStatusDefinition,
+  deriveTaskLifecycleState,
+  isDraftTask,
+  isArchivedTask,
+  isTrashedTask,
+  isTrashedOrArchivedTask,
+  isWorkflowTask,
+  getTaskSemanticStatus,
+  isTaskCompleted,
+  isTaskInProgress,
+  isTaskNotStarted,
+  isTaskCanceled,
+  isTaskActive,
+  isTaskUnassigned
+} from './utils/status.js';
+import type { Task, StatusDefinition, Workflow } from './types/index.js';
 
 describe('Universal Semantic Statuses & Implied Statuses', () => {
   describe('resolveStatusDefinition', () => {
@@ -223,4 +238,117 @@ describe('Universal Semantic Statuses & Implied Statuses', () => {
       expect(stateB?.blockingTaskIds).toEqual([]);
     });
   });
+
+  describe('Canonical Task Lifecycle & Semantic Status Predicates', () => {
+    it('identifies draft, archived, and trashed tasks properly', () => {
+      expect(isDraftTask(null)).toBe(false);
+      expect(isDraftTask({ isDraft: true })).toBe(true);
+      expect(isDraftTask({ isDraft: false })).toBe(false);
+
+      expect(isArchivedTask(null)).toBe(false);
+      expect(isArchivedTask({ archived: true })).toBe(true);
+      expect(isArchivedTask({ archivedAt: '2026-09-01T00:00:00Z' })).toBe(true);
+      expect(isArchivedTask({ status: 'archived' })).toBe(true);
+      expect(isArchivedTask({ customFields: { isArchived: true } })).toBe(true);
+      expect(isArchivedTask({ status: 'todo' })).toBe(false);
+
+      expect(isTrashedTask(null)).toBe(false);
+      expect(isTrashedTask({ trashed: true })).toBe(true);
+      expect(isTrashedTask({ trashedAt: '2026-09-01T00:00:00Z' })).toBe(true);
+      expect(isTrashedTask({ status: 'trashed' })).toBe(true);
+      expect(isTrashedTask({ customFields: { isTrashed: true } })).toBe(true);
+      expect(isTrashedTask({ status: 'todo' })).toBe(false);
+
+      expect(isTrashedOrArchivedTask({ trashed: true })).toBe(true);
+      expect(isTrashedOrArchivedTask({ archived: true })).toBe(true);
+      expect(isTrashedOrArchivedTask({ status: 'todo' })).toBe(false);
+    });
+
+    it('identifies workflow tasks excluding draft, trashed, and archived tasks (UCH-137)', () => {
+      expect(isWorkflowTask(null)).toBe(false);
+      expect(isWorkflowTask({ status: 'todo' })).toBe(true);
+      expect(isWorkflowTask({ status: 'in_progress' })).toBe(true);
+      expect(isWorkflowTask({ status: 'done' })).toBe(true);
+
+      // Draft tasks are excluded
+      expect(isWorkflowTask({ status: 'todo', isDraft: true })).toBe(false);
+      // Trashed tasks are excluded
+      expect(isWorkflowTask({ status: 'todo', trashed: true })).toBe(false);
+      // Archived tasks are excluded
+      expect(isWorkflowTask({ status: 'done', archived: true })).toBe(false);
+    });
+
+    it('resolves semantic status using workflow, defaults, and custom definitions', () => {
+      const mockWorkflow: Workflow = {
+        id: 'wf_custom',
+        name: 'Custom Flow',
+        isDefault: true,
+        statuses: [
+          { key: 'discovery', label: 'Discovery', category: 'not_started' },
+          { key: 'developing', label: 'Developing', category: 'in_progress' },
+          { key: 'delivered', label: 'Delivered', category: 'completed' },
+          { key: 'dropped', label: 'Dropped', category: 'canceled' }
+        ],
+        transitions: [],
+        createdAt: '2026-09-01T00:00:00Z',
+        updatedAt: '2026-09-01T00:00:00Z'
+      };
+
+      expect(getTaskSemanticStatus({ status: 'developing' }, mockWorkflow)).toBe('in_progress');
+      expect(getTaskSemanticStatus({ status: 'delivered' }, mockWorkflow)).toBe('completed');
+      expect(getTaskSemanticStatus({ status: 'dropped' }, mockWorkflow)).toBe('canceled');
+      expect(getTaskSemanticStatus({ status: 'discovery' }, mockWorkflow)).toBe('not_started');
+
+      // Falls back to standard defaults when not in custom workflow
+      expect(getTaskSemanticStatus({ status: 'in_progress' }, mockWorkflow)).toBe('in_progress');
+      expect(getTaskSemanticStatus({ status: 'done' })).toBe('completed');
+      expect(getTaskSemanticStatus({ status: 'todo' })).toBe('not_started');
+      expect(getTaskSemanticStatus({ status: 'canceled' })).toBe('canceled');
+    });
+
+    it('verifies lifecycle predicates (completed, in_progress, not_started, canceled, active)', () => {
+      const taskDone = { status: 'done' };
+      const taskActive = { status: 'in_progress' };
+      const taskTodo = { status: 'todo' };
+      const taskCanceled = { status: 'canceled' };
+
+      expect(isTaskCompleted(taskDone)).toBe(true);
+      expect(isTaskCompleted(taskActive)).toBe(false);
+
+      expect(isTaskInProgress(taskActive)).toBe(true);
+      expect(isTaskInProgress(taskDone)).toBe(false);
+
+      expect(isTaskNotStarted(taskTodo)).toBe(true);
+      expect(isTaskNotStarted(taskActive)).toBe(false);
+
+      expect(isTaskCanceled(taskCanceled)).toBe(true);
+      expect(isTaskCanceled(taskDone)).toBe(false);
+
+      // Active tasks
+      expect(isTaskActive(taskTodo)).toBe(true);
+      expect(isTaskActive(taskActive)).toBe(true);
+      expect(isTaskActive(taskDone)).toBe(false);
+      expect(isTaskActive(taskCanceled)).toBe(false);
+      expect(isTaskActive({ ...taskActive, isDraft: true })).toBe(false);
+      expect(isTaskActive({ ...taskActive, archived: true })).toBe(false);
+      expect(isTaskActive({ ...taskActive, trashed: true })).toBe(false);
+    });
+
+    it('identifies unassigned tasks properly', () => {
+      expect(isTaskUnassigned(null)).toBe(true);
+      expect(isTaskUnassigned({})).toBe(true);
+      expect(isTaskUnassigned({ assigneeId: undefined })).toBe(true);
+      expect(isTaskUnassigned({ assigneeId: '' })).toBe(true);
+      expect(isTaskUnassigned({ assigneeId: 'unassigned' })).toBe(true);
+      expect(isTaskUnassigned({ assigneeId: '  UNASSIGNED  ' })).toBe(true);
+      expect(isTaskUnassigned({ assigneeId: 'user_123' })).toBe(false);
+
+      // Assignees array checks
+      expect(isTaskUnassigned({ assignees: [] })).toBe(true);
+      expect(isTaskUnassigned({ assignees: ['unassigned'] })).toBe(true);
+      expect(isTaskUnassigned({ assignees: [{ id: 'unassigned', name: 'unassigned' }] })).toBe(true);
+      expect(isTaskUnassigned({ assignees: ['user_456'] })).toBe(false);
+      expect(isTaskUnassigned({ assignees: [{ id: 'user_456', name: 'Alice' }] })).toBe(false);
+    });
+  });
 });