@critical-path/core 0.14.0 → 0.15.1

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;
@@ -352,6 +369,7 @@ export type WebhookEvent =
   | 'task.updated'
   | 'task.deleted'
   | 'task.status_changed'
+  | 'task.unblocked'
   | 'comment.created'
   | 'comment.updated'
   | 'comment.deleted'

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

package/src/utils/workflow.ts

@@ -90,25 +90,38 @@ export const DEFAULT_VFX_WORKFLOW: Workflow = {
   name: 'VFX Production Workflow',
   description: 'Visual effects production pipeline from bidding and drafting to internal lead review and client supervisor approval.',
   statuses: [
-    { key: 'bidding', label: 'Bidding & Draft', completionState: 'not_done', executionState: 'inactive' },
-    { key: 'awarded', label: 'Awarded / Ready', completionState: 'not_done', executionState: 'inactive' },
-    { key: 'in_production', label: 'In Production', completionState: 'not_done', executionState: 'active' },
-    { key: 'internal_review', label: 'Internal Review', completionState: 'not_done', executionState: 'active' },
-    { key: 'client_review', label: 'Client Review', completionState: 'not_done', executionState: 'active' },
-    { key: 'revision_requested', label: 'Revision Requested', completionState: 'not_done', executionState: 'active' },
-    { key: 'approved', label: 'Approved (Final)', completionState: 'done', executionState: 'inactive' },
+    { key: 'bidding', label: 'Bidding & Draft', category: 'not_started' },
+    { key: 'awarded', label: 'Awarded / Ready', category: 'not_started' },
+    { key: 'in_production', label: 'In Production', category: 'in_progress' },
+    { key: 'internal_review', label: 'Internal Review', category: 'in_progress' },
+    { key: 'client_review', label: 'Client Review', category: 'in_progress' },
+    { key: 'revision_requested', label: 'Revision Requested', category: 'in_progress' },
+    { key: 'approved', label: 'Approved (Final)', category: 'completed' },
     DEFAULT_STATUS_DEFINITIONS.canceled
   ],
   transitions: [
     { name: 'Award Bid', fromStatusKey: 'bidding', toStatusKey: 'awarded' },
+    { name: 'Start Directly from Bid', fromStatusKey: 'bidding', toStatusKey: 'in_production' },
     { name: 'Start Work', fromStatusKey: 'awarded', toStatusKey: 'in_production' },
+    { name: 'Reopen Bid', fromStatusKey: 'awarded', toStatusKey: 'bidding' },
     { name: 'Submit to Lead Review', fromStatusKey: 'in_production', toStatusKey: 'internal_review' },
+    { name: 'Fast-Track Client Review', fromStatusKey: 'in_production', toStatusKey: 'client_review' },
+    { name: 'Direct Approval', fromStatusKey: 'in_production', toStatusKey: 'approved' },
     { name: 'Submit to Client Review', fromStatusKey: 'internal_review', toStatusKey: 'client_review' },
     { name: 'Request Internal Revisions', fromStatusKey: 'internal_review', toStatusKey: 'revision_requested' },
+    { name: 'Return to Production', fromStatusKey: 'internal_review', toStatusKey: 'in_production' },
+    { name: 'Approve from Lead Review', fromStatusKey: 'internal_review', toStatusKey: 'approved' },
     { name: 'Request Client Revisions', fromStatusKey: 'client_review', toStatusKey: 'revision_requested' },
-    { name: 'Address Revisions', fromStatusKey: 'revision_requested', toStatusKey: 'in_production' },
+    { name: 'Return to Lead Review', fromStatusKey: 'client_review', toStatusKey: 'internal_review' },
     { name: 'Approve Final Shot', fromStatusKey: 'client_review', toStatusKey: 'approved' },
-    { name: 'Cancel', fromStatusKey: '*', toStatusKey: 'canceled' }
+    { name: 'Address Revisions in Production', fromStatusKey: 'revision_requested', toStatusKey: 'in_production' },
+    { name: 'Resubmit to Lead Review', fromStatusKey: 'revision_requested', toStatusKey: 'internal_review' },
+    { name: 'Resubmit to Client Review', fromStatusKey: 'revision_requested', toStatusKey: 'client_review' },
+    { name: 'Reopen Shot', fromStatusKey: 'approved', toStatusKey: 'in_production' },
+    { name: 'Reopen Lead Review', fromStatusKey: 'approved', toStatusKey: 'internal_review' },
+    { name: 'Cancel', fromStatusKey: '*', toStatusKey: 'canceled' },
+    { name: 'Restore to Bidding', fromStatusKey: 'canceled', toStatusKey: 'bidding' },
+    { name: 'Restore to Production', fromStatusKey: 'canceled', toStatusKey: 'in_production' }
   ],
   taskTypes: [
     { key: 'vfx_task', label: 'VFX Task', description: 'Department task (e.g. Matchmove, Animation, FX, Comp)', icon: 'film' },
@@ -126,27 +139,36 @@ export const DEFAULT_CREATIVE_WORKFLOW: Workflow = {
   name: 'Creative Production Workflow',
   description: 'Production pipeline for creative deliverables from briefing and concepts to internal review, client feedback, and final delivery.',
   statuses: [
-    { key: 'briefing', label: 'Briefing & Scoping', completionState: 'not_done', executionState: 'inactive' },
-    { key: 'concept', label: 'Concept & Storyboarding', completionState: 'not_done', executionState: 'active' },
-    { key: 'in_production', label: 'In Production', completionState: 'not_done', executionState: 'active' },
-    { key: 'internal_review', label: 'Internal Review', completionState: 'not_done', executionState: 'active' },
-    { key: 'client_review', label: 'Client Review', completionState: 'not_done', executionState: 'active' },
-    { key: 'revision_requested', label: 'Revision Requested', completionState: 'not_done', executionState: 'active' },
-    { key: 'approved', label: 'Approved', completionState: 'done', executionState: 'inactive' },
-    { key: 'delivered', label: 'Delivered', completionState: 'done', executionState: 'inactive' },
+    { key: 'briefing', label: 'Briefing & Scoping', category: 'not_started' },
+    { key: 'concept', label: 'Concept & Storyboarding', category: 'in_progress' },
+    { key: 'in_production', label: 'In Production', category: 'in_progress' },
+    { key: 'internal_review', label: 'Internal Review', category: 'in_progress' },
+    { key: 'client_review', label: 'Client Review', category: 'in_progress' },
+    { key: 'revision_requested', label: 'Revision Requested', category: 'in_progress' },
+    { key: 'approved', label: 'Approved', category: 'completed' },
+    { key: 'delivered', label: 'Delivered', category: 'completed' },
     DEFAULT_STATUS_DEFINITIONS.canceled
   ],
   transitions: [
     { name: 'Start Concepts', fromStatusKey: 'briefing', toStatusKey: 'concept' },
     { name: 'Approve Concept for Production', fromStatusKey: 'concept', toStatusKey: 'in_production' },
+    { name: 'Return to Briefing', fromStatusKey: 'concept', toStatusKey: 'briefing' },
     { name: 'Submit for Internal Review', fromStatusKey: 'in_production', toStatusKey: 'internal_review' },
+    { name: 'Submit for Client Review', fromStatusKey: 'in_production', toStatusKey: 'client_review' },
     { name: 'Submit for Client Review', fromStatusKey: 'internal_review', toStatusKey: 'client_review' },
     { name: 'Request Revisions (Internal)', fromStatusKey: 'internal_review', toStatusKey: 'revision_requested' },
+    { name: 'Return to Production', fromStatusKey: 'internal_review', toStatusKey: 'in_production' },
+    { name: 'Approve from Lead Review', fromStatusKey: 'internal_review', toStatusKey: 'approved' },
     { name: 'Request Revisions (Client)', fromStatusKey: 'client_review', toStatusKey: 'revision_requested' },
+    { name: 'Return to Internal Review', fromStatusKey: 'client_review', toStatusKey: 'internal_review' },
     { name: 'Address Revisions', fromStatusKey: 'revision_requested', toStatusKey: 'in_production' },
+    { name: 'Resubmit to Lead Review', fromStatusKey: 'revision_requested', toStatusKey: 'internal_review' },
+    { name: 'Resubmit to Client Review', fromStatusKey: 'revision_requested', toStatusKey: 'client_review' },
     { name: 'Approve Work', fromStatusKey: 'client_review', toStatusKey: 'approved' },
     { name: 'Deliver Final Assets', fromStatusKey: 'approved', toStatusKey: 'delivered' },
-    { name: 'Cancel', fromStatusKey: '*', toStatusKey: 'canceled' }
+    { name: 'Reopen Deliverable', fromStatusKey: 'delivered', toStatusKey: 'in_production' },
+    { name: 'Cancel', fromStatusKey: '*', toStatusKey: 'canceled' },
+    { name: 'Restore', fromStatusKey: 'canceled', toStatusKey: 'briefing' }
   ],
   taskTypes: [
     { key: 'deliverable', label: 'Deliverable', description: 'Finished asset, cutdown, or packaged export', icon: 'package' },
@@ -211,6 +233,41 @@ export function getAllowedNextStatuses(
   return [allStatusKeys[currentIndex + 1]];
 }
 
+export function getAllowedTransitions(
+  workflow: Workflow | undefined,
+  currentStatus: string
+): string[] {
+  if (!workflow || !workflow.statuses || workflow.statuses.length === 0) {
+    return Object.keys(DEFAULT_STATUS_DEFINITIONS);
+  }
+
+  const allStatusKeys = workflow.statuses.map((s) => s.key);
+  if (!allStatusKeys.includes(currentStatus)) {
+    return [];
+  }
+
+  if (workflow.transitions && workflow.transitions.length > 0) {
+    const matches = workflow.transitions.filter(
+      (t) => t.fromStatusKey === '*' || t.fromStatusKey === currentStatus
+    );
+
+    const allowed = new Set<string>();
+    for (const t of matches) {
+      if (t.toStatusKey === '*') {
+        allStatusKeys.filter((k) => k !== currentStatus).forEach((k) => allowed.add(k));
+      } else if (t.toStatusKey !== currentStatus && allStatusKeys.includes(t.toStatusKey)) {
+        allowed.add(t.toStatusKey);
+      }
+    }
+
+    return Array.from(allowed);
+  }
+
+  const next = getAllowedNextStatuses(workflow, currentStatus);
+  const prev = getAllowedPreviousStatuses(workflow, currentStatus);
+  return Array.from(new Set([...next, ...prev]));
+}
+
 export function getAllowedPreviousStatuses(
   workflow: Workflow | undefined,
   currentStatus: string

package/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["./src/deliverables.test.ts","./src/index.test.ts","./src/index.ts","./src/use-case-validation.test.ts","./src/domain/custom-fields.ts","./src/domain/ddd.test.ts","./src/domain/entities.ts","./src/domain/events.ts","./src/domain/graph.ts","./src/domain/index.ts","./src/engine/index.ts","./src/plugins/index.ts","./src/storage/file-storage.ts","./src/storage/firebase-storage.ts","./src/storage/index.ts","./src/storage/s3.ts","./src/storage/storage.test.ts","./src/store/firebase.test.ts","./src/store/firebase.ts","./src/store/index.ts","./src/store/sqlite.test.ts","./src/store/sqlite.ts","./src/types/index.ts","./src/utils/index.ts","./src/utils/key.test.ts","./src/utils/key.ts","./src/utils/mentions.test.ts","./src/utils/mentions.ts","./src/utils/status.ts","./src/utils/workflow.ts"],"version":"5.9.3"}
+{"root":["./src/deliverables.test.ts","./src/index.test.ts","./src/index.ts","./src/status.test.ts","./src/use-case-validation.test.ts","./src/domain/custom-fields.ts","./src/domain/ddd.test.ts","./src/domain/entities.ts","./src/domain/events.ts","./src/domain/graph.ts","./src/domain/index.ts","./src/engine/index.ts","./src/plugins/index.ts","./src/storage/file-storage.ts","./src/storage/firebase-storage.ts","./src/storage/index.ts","./src/storage/s3.ts","./src/storage/storage.test.ts","./src/store/firebase.test.ts","./src/store/firebase.ts","./src/store/index.ts","./src/store/sqlite.test.ts","./src/store/sqlite.ts","./src/types/index.ts","./src/utils/index.ts","./src/utils/key.test.ts","./src/utils/key.ts","./src/utils/mentions.test.ts","./src/utils/mentions.ts","./src/utils/status.ts","./src/utils/workflow.ts"],"version":"5.9.3"}