@critical-path/core 0.20.2 → 0.21.0

package/src/engine/index.ts

@@ -373,6 +373,7 @@ 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);
@@ -397,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,
@@ -577,26 +579,54 @@ export class CriticalPathEngine {
         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') &&
-        newStatusDef.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 ((newStatusDef.category === 'completed' || newStatusDef.category === 'canceled') && !processedUpdates.actualEndDate) {
-        processedUpdates.actualEndDate = now;
-        if (newStatusDef.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;
+        }
       }
     }
 

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);
+    });
+  });
 });

package/src/store/sqlite.ts

@@ -123,6 +123,7 @@ export class SQLiteStore implements StorageAdapter {
         plannedStartDate TEXT,
         actualStartDate TEXT,
         actualEndDate TEXT,
+        completedAt TEXT,
         dueDate TEXT,
         estimatedHours REAL,
         loggedHours REAL,
@@ -266,6 +267,12 @@ export class SQLiteStore implements StorageAdapter {
     } catch {
       // Column may already exist
     }
+
+    try {
+      this.db.exec('ALTER TABLE tasks ADD COLUMN completedAt TEXT');
+    } catch {
+      // Column may already exist
+    }
   }
 
   // --- Projects ---
@@ -662,13 +669,13 @@ export class SQLiteStore implements StorageAdapter {
     const stmt = this.db.prepare(`
       INSERT INTO tasks (
         id, projectId, title, description, status, priority, taskType, assigneeId, assignees, reporterId,
-        reviewerId, iterationId, teamId, containerId, deliverableId, plannedStartDate, actualStartDate, actualEndDate,
+        reviewerId, iterationId, teamId, containerId, deliverableId, plannedStartDate, actualStartDate, actualEndDate, completedAt,
         dueDate, estimatedHours, loggedHours, actualHours, billableHours,
         estimatedDurationMinutes, actualDurationMinutes, billableDurationMinutes,
         actualDurationSeconds, inProgressSince, blockedDurationSeconds, blockedSince, progress,
         isBlocked, blockedReason,
         tags, customFields, parentId, createdAt, updatedAt
-      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `);
     stmt.run(
       newTask.id,
@@ -689,6 +696,7 @@ export class SQLiteStore implements StorageAdapter {
       newTask.plannedStartDate || null,
       newTask.actualStartDate || null,
       newTask.actualEndDate || null,
+      newTask.completedAt || null,
       newTask.dueDate || null,
       newTask.estimatedHours ?? null,
       newTask.loggedHours ?? null,
@@ -727,7 +735,7 @@ export class SQLiteStore implements StorageAdapter {
       UPDATE tasks SET
         projectId = ?, title = ?, description = ?, status = ?, priority = ?, taskType = ?,
         assigneeId = ?, assignees = ?, reporterId = ?, reviewerId = ?, iterationId = ?, teamId = ?, containerId = ?, deliverableId = ?,
-        plannedStartDate = ?, actualStartDate = ?, actualEndDate = ?, dueDate = ?,
+        plannedStartDate = ?, actualStartDate = ?, actualEndDate = ?, completedAt = ?, dueDate = ?,
         estimatedHours = ?, loggedHours = ?, actualHours = ?, billableHours = ?,
         estimatedDurationMinutes = ?, actualDurationMinutes = ?, billableDurationMinutes = ?,
         actualDurationSeconds = ?, inProgressSince = ?, blockedDurationSeconds = ?, blockedSince = ?, progress = ?,
@@ -753,6 +761,7 @@ export class SQLiteStore implements StorageAdapter {
       updated.plannedStartDate || null,
       updated.actualStartDate || null,
       updated.actualEndDate || null,
+      updated.completedAt || null,
       updated.dueDate || null,
       updated.estimatedHours ?? null,
       updated.loggedHours ?? null,
@@ -1214,6 +1223,8 @@ export class SQLiteStore implements StorageAdapter {
       inProgressSince: row.inProgressSince || undefined,
       blockedDurationSeconds: row.blockedDurationSeconds ?? undefined,
       blockedSince: row.blockedSince || undefined,
+      actualEndDate: row.actualEndDate || undefined,
+      completedAt: row.completedAt || undefined,
       isBlocked: row.isBlocked !== null && row.isBlocked !== undefined ? Boolean(row.isBlocked) : undefined,
       blockedReason: row.blockedReason || undefined,
       taskType: row.taskType || undefined,

package/src/types/index.ts

@@ -205,6 +205,7 @@ export interface Task {
   plannedStartDate?: string;
   actualStartDate?: string;
   actualEndDate?: string;
+  completedAt?: string;
   dueDate?: string;
   // Duration & Effort (in hours and/or minutes)
   estimatedHours?: number;

package/src/utils/fractional-index.test.ts

@@ -0,0 +1,191 @@
+import { describe, it, expect } from 'vitest';
+import {
+  encodeInteger,
+  decodeInteger,
+  getIntegerPart,
+  getInitialKey,
+  generateKeyBetween,
+  generateNKeysBetween,
+  compareOrderIndices
+} from './fractional-index.js';
+
+describe('fractional-index', () => {
+  describe('encodeInteger and decodeInteger', () => {
+    it('encodes and decodes non-negative integers', () => {
+      const cases = [0, 1, 2, 9, 10, 61, 62, 100, 1000, 3843, 3844];
+      for (const n of cases) {
+        const encoded = encodeInteger(n);
+        expect(decodeInteger(encoded)).toBe(n);
+      }
+    });
+
+    it('encodes and decodes negative integers', () => {
+      const cases = [-1, -2, -10, -62, -100, -1000];
+      for (const n of cases) {
+        const encoded = encodeInteger(n);
+        expect(decodeInteger(encoded)).toBe(n);
+      }
+    });
+
+    it('strictly maintains lexicographical sorting across integers', () => {
+      const sequence = [-100, -62, -10, -2, -1, 0, 1, 2, 9, 10, 61, 62, 100, 3843, 3844];
+      const encoded = sequence.map((n) => encodeInteger(n));
+
+      for (let i = 0; i < encoded.length - 1; i++) {
+        expect(encoded[i] < encoded[i + 1]).toBe(true);
+        expect(compareOrderIndices(encoded[i], encoded[i + 1])).toBeLessThan(0);
+      }
+
+      // Reversing and sorting with compareOrderIndices or standard sort() restores exact order
+      const reversed = [...encoded].reverse();
+      expect(reversed.sort(compareOrderIndices)).toEqual(encoded);
+      expect([...encoded].reverse().sort()).toEqual(encoded);
+    });
+  });
+
+  describe('getInitialKey', () => {
+    it('generates spaced initial keys', () => {
+      const k0 = getInitialKey(0);
+      const k1 = getInitialKey(1);
+      const k2 = getInitialKey(2);
+
+      expect(k0).toBe('a0');
+      expect(k1).toBe('a2');
+      expect(k2).toBe('a4');
+
+      expect(k0 < k1).toBe(true);
+      expect(k1 < k2).toBe(true);
+    });
+  });
+
+  describe('generateKeyBetween', () => {
+    it('returns default initial key when both bounds are null/undefined', () => {
+      expect(generateKeyBetween(null, null)).toBe('a0');
+      expect(generateKeyBetween(undefined, undefined)).toBe('a0');
+      expect(generateKeyBetween('', '')).toBe('a0');
+    });
+
+    it('generates a key before an upper bound', () => {
+      const b0 = 'a0';
+      const beforeB0 = generateKeyBetween(null, b0);
+      expect(beforeB0 < b0).toBe(true);
+
+      const b1 = 'a1';
+      const beforeB1 = generateKeyBetween(null, b1);
+      expect(beforeB1 < b1).toBe(true);
+
+      const bFractional = 'a0V';
+      const beforeFractional = generateKeyBetween(null, bFractional);
+      expect(beforeFractional < bFractional).toBe(true);
+    });
+
+    it('generates a key after a lower bound', () => {
+      const a0 = 'a0';
+      const afterA0 = generateKeyBetween(a0, null);
+      expect(a0 < afterA0).toBe(true);
+
+      const aFractional = 'a0V';
+      const afterFractional = generateKeyBetween(aFractional, null);
+      expect(aFractional < afterFractional).toBe(true);
+    });
+
+    it('generates key between spaced integers', () => {
+      const a = 'a0';
+      const b = 'a2';
+      const mid = generateKeyBetween(a, b);
+
+      expect(mid).toBe('a1');
+      expect(a < mid).toBe(true);
+      expect(mid < b).toBe(true);
+    });
+
+    it('generates fractional key between adjacent integers', () => {
+      const a = 'a0';
+      const b = 'a1';
+      const mid = generateKeyBetween(a, b);
+
+      expect(a < mid).toBe(true);
+      expect(mid < b).toBe(true);
+    });
+
+    it('handles nested fractional insertions without degradation', () => {
+      let current = 'a0';
+      const target = 'a1';
+
+      // Perform 50 sequential midpoint insertions
+      for (let i = 0; i < 50; i++) {
+        const next = generateKeyBetween(current, target);
+        expect(current < next).toBe(true);
+        expect(next < target).toBe(true);
+        current = next;
+      }
+    });
+  });
+
+  describe('generateNKeysBetween', () => {
+    it('returns empty array for count <= 0', () => {
+      expect(generateNKeysBetween('a0', 'a2', 0)).toEqual([]);
+      expect(generateNKeysBetween('a0', 'a2', -1)).toEqual([]);
+    });
+
+    it('generates 1 key matching generateKeyBetween', () => {
+      const keys = generateNKeysBetween('a0', 'a2', 1);
+      expect(keys.length).toBe(1);
+      expect(keys[0]).toBe('a1');
+    });
+
+    it('generates N keys in strictly ascending order between a and b', () => {
+      const count = 5;
+      const a = 'a0';
+      const b = 'a1';
+      const keys = generateNKeysBetween(a, b, count);
+
+      expect(keys.length).toBe(count);
+
+      // Check strictly greater than a
+      expect(a < keys[0]).toBe(true);
+
+      // Check strictly increasing
+      for (let i = 0; i < keys.length - 1; i++) {
+        expect(keys[i] < keys[i + 1]).toBe(true);
+      }
+
+      // Check strictly less than b
+      expect(keys[count - 1] < b).toBe(true);
+    });
+
+    it('generates N keys at swimlane start (a is null)', () => {
+      const count = 3;
+      const b = 'a0';
+      const keys = generateNKeysBetween(null, b, count);
+
+      expect(keys.length).toBe(count);
+      for (let i = 0; i < keys.length - 1; i++) {
+        expect(keys[i] < keys[i + 1]).toBe(true);
+      }
+      expect(keys[count - 1] < b).toBe(true);
+    });
+
+    it('generates N keys at swimlane end (b is null)', () => {
+      const count = 4;
+      const a = 'a5';
+      const keys = generateNKeysBetween(a, null, count);
+
+      expect(keys.length).toBe(count);
+      expect(a < keys[0]).toBe(true);
+      for (let i = 0; i < keys.length - 1; i++) {
+        expect(keys[i] < keys[i + 1]).toBe(true);
+      }
+    });
+
+    it('generates N keys in empty swimlane (both null)', () => {
+      const count = 6;
+      const keys = generateNKeysBetween(null, null, count);
+
+      expect(keys.length).toBe(count);
+      for (let i = 0; i < keys.length - 1; i++) {
+        expect(keys[i] < keys[i + 1]).toBe(true);
+      }
+    });
+  });
+});