@critical-path/core 0.16.0 → 0.18.0

package/src/engine/index.ts

@@ -28,7 +28,11 @@ import type {
   TaskLadderView,
   MacroPhaseRollup,
   StandardTaskTimelineItem,
-  ConcreteTaskEvidence
+  ConcreteTaskEvidence,
+  TaskMetrics,
+  TaskProgressHistory,
+  WorkloadDistribution,
+  WorkloadDistributionOptions
 } from '../types/index.js';
 import { StorageAdapter, InMemoryStore } from '../store/index.js';
 import { PluginRegistry } from '../plugins/index.js';
@@ -77,6 +81,12 @@ import { validateCustomFieldValues } from '../domain/custom-fields.js';
 import { detectDependencyCycle, CircularDependencyError } from '../domain/graph.js';
 import { calculateCPM } from '../domain/cpm.js';
 import { buildTimelineLadder, aggregateConcreteEvidenceForTask } from '../domain/ladder.js';
+import {
+  calculateTaskMetrics,
+  reconstructTaskProgressHistory,
+  type MetricOptions
+} from '../domain/metrics.js';
+import { calculateWorkloadDistribution } from '../domain/workload.js';
 
 export class CriticalPathEngine {
   public readonly store: StorageAdapter;
@@ -451,6 +461,19 @@ export class CriticalPathEngine {
       );
       processedUpdates.semanticStatus = processedUpdates.semanticStatus ?? statusDef.category;
       const now = new Date().toISOString();
+
+      const existingStatusDef = resolveStatusDefinition(
+        existing.status,
+        project?.statusDefinitions || workflow?.statuses
+      );
+      if (
+        (existingStatusDef.category === 'completed' || existingStatusDef.category === 'canceled') &&
+        (statusDef.category === 'in_progress' || statusDef.category === 'not_started') &&
+        processedUpdates.actualEndDate === undefined
+      ) {
+        processedUpdates.actualEndDate = undefined;
+      }
+
       if (statusDef.category === 'in_progress' && !existing.actualStartDate && !processedUpdates.actualStartDate) {
         processedUpdates.actualStartDate = now;
       }
@@ -1355,7 +1378,7 @@ export class CriticalPathEngine {
     return this.store.deleteIteration(id);
   }
 
-  // --- Bret Victor's Ladder of Abstraction & Critical Path Method ---
+  // --- Ladder of Abstraction & Critical Path Method ---
   async calculateCriticalPath(projectId: string): Promise<CriticalPathAnalysis> {
     const tasks = await this.store.getTasks(projectId);
     const allDepArrays = await Promise.all(tasks.map((t) => this.store.getDependencies(t.id)));
@@ -1441,15 +1464,75 @@ export class CriticalPathEngine {
 
     const concrete = ladder.concrete?.[taskId] || aggregateConcreteEvidenceForTask(task);
     const macroPhase = ladder.macro?.phases.find((p) => p.taskIds.includes(taskId));
+    const metrics = await this.getTaskMetrics(taskId);
 
     return {
       taskId,
       macroPhase,
       standard,
-      concrete
+      concrete,
+      metrics: metrics || undefined
     };
   }
 
+  async getTaskMetrics(taskId: string, options?: MetricOptions): Promise<TaskMetrics | null> {
+    const task = await this.store.getTask(taskId);
+    if (!task) return null;
+
+    const [activities, timeEntries, project, workflow] = await Promise.all([
+      this.store.getActivities({ taskId }),
+      this.store.getTimeEntries(taskId),
+      this.store.getProject(task.projectId),
+      this.resolveProjectWorkflow(task.projectId)
+    ]);
+
+    const customStatusDefinitions = project?.statusDefinitions || workflow?.statuses;
+
+    return calculateTaskMetrics(task, activities, timeEntries, {
+      customStatusDefinitions,
+      ...options
+    });
+  }
+
+  async getTaskProgressHistory(taskId: string, options?: MetricOptions): Promise<TaskProgressHistory | null> {
+    const task = await this.store.getTask(taskId);
+    if (!task) return null;
+
+    const [activities, project, workflow] = await Promise.all([
+      this.store.getActivities({ taskId }),
+      this.store.getProject(task.projectId),
+      this.resolveProjectWorkflow(task.projectId)
+    ]);
+
+    const customStatusDefinitions = project?.statusDefinitions || workflow?.statuses;
+
+    return reconstructTaskProgressHistory(task, activities, {
+      customStatusDefinitions,
+      ...options
+    });
+  }
+
+  async getWorkloadDistribution(
+    projectId?: string,
+    options: WorkloadDistributionOptions = {}
+  ): Promise<WorkloadDistribution> {
+    const tasks = await this.store.getTasks(projectId);
+    const teams = await this.store.getTeams();
+
+    const timeEntriesNested = await Promise.all(tasks.map((t) => this.store.getTimeEntries(t.id)));
+    const timeEntries: TimeEntry[] = timeEntriesNested.flat();
+
+    return calculateWorkloadDistribution(
+      {
+        tasks,
+        timeEntries,
+        teams,
+        projectId
+      },
+      options
+    );
+  }
+
   private async dispatchWebhook(event: WebhookEvent, payload: Record<string, unknown>): Promise<void> {
     const webhooks = await this.store.getWebhooks();
     const active = webhooks.filter((w) => w.active && w.events.includes(event));

package/src/types/index.ts

@@ -39,6 +39,7 @@ export interface User {
   email: string;
   avatarUrl?: string;
   role: Role;
+  weeklyCapacityHours?: number;
   createdAt: string;
 }
 
@@ -48,6 +49,7 @@ export interface Team {
   description?: string;
   leaderId?: string;
   memberIds: string[];
+  weeklyCapacityHours?: number;
   createdAt: string;
   updatedAt: string;
 }
@@ -426,7 +428,7 @@ export interface CriticalPathConfig {
 }
 
 // ==========================================
-// Bret Victor's Ladder of Abstraction Types
+// Ladder of Abstraction Types
 // ==========================================
 
 export type AbstractionLevel = 'macro' | 'standard' | 'concrete' | 'all';
@@ -518,11 +520,78 @@ export interface RealityDelta {
   estimatedHours: number;
   loggedHours: number;
   varianceHours: number; // loggedHours - estimatedHours
+  effortVarianceHours?: number; // loggedHours - estimatedHours (effort variance)
+  durationVarianceHours?: number; // actual duration hours - planned duration hours
   scheduleVarianceDays?: number; // days difference between planned/due vs actual
+  accuracyRatio?: number; // loggedHours / estimatedHours (estimation accuracy ratio)
   isOverdue: boolean;
   isOverEstimate: boolean;
 }
 
+export type ProgressInferenceSource = 'explicit' | 'todos' | 'time_effort' | 'schedule_elapsed' | 'blended';
+
+export interface TaskProgressInference {
+  progressPercentage: number;
+  source: ProgressInferenceSource;
+  isExplicit: boolean;
+  breakdown: {
+    explicitProgress?: number;
+    todoProgress?: number;
+    effortProgress?: number;
+    scheduleProgress?: number;
+  };
+}
+
+export type ProgressCurveProfile =
+  | 'linear'
+  | 's_curve'
+  | 'early_surge'
+  | 'late_rush'
+  | 'stalled'
+  | 'insufficient_data';
+
+export interface TaskProgressHistoryPoint {
+  timestamp: string;
+  progress: number;
+  inferredProgress?: number;
+  status: TaskStatus;
+  semanticStatus?: SemanticStatus;
+  action: string;
+}
+
+export interface TaskProgressHistory {
+  taskId: string;
+  points: TaskProgressHistoryPoint[];
+  curveProfile: ProgressCurveProfile;
+}
+
+export interface TaskEVM {
+  plannedValue: number; // PV (expected hours)
+  earnedValue: number; // EV (earned hours)
+  actualCost: number; // AC (logged hours)
+  costVariance: number; // CV = EV - AC
+  scheduleVariance: number; // SV = EV - PV
+  costPerformanceIndex: number; // CPI = EV / AC
+  schedulePerformanceIndex: number; // SPI = EV / PV
+}
+
+export interface TaskInferredActuals {
+  actualStartDate?: string;
+  actualEndDate?: string;
+  isStartDateInferred: boolean;
+  isEndDateInferred: boolean;
+  activeWorkingHours?: number;
+}
+
+export interface TaskMetrics {
+  taskId: string;
+  inferredActuals: TaskInferredActuals;
+  realityDelta: RealityDelta;
+  progress: TaskProgressInference;
+  evm: TaskEVM;
+  progressHistory: TaskProgressHistory;
+}
+
 export interface ConcreteTaskEvidence {
   taskId: string;
   attachments: Attachment[];
@@ -560,5 +629,45 @@ export interface TaskLadderView {
   macroPhase?: MacroPhaseRollup;
   standard: StandardTaskTimelineItem;
   concrete: ConcreteTaskEvidence;
+  metrics?: TaskMetrics;
+}
+
+export type WorkloadInterval = 'day' | 'week' | 'month';
+export type WorkloadGroupBy = 'assignee' | 'team' | 'taskType' | 'priority' | 'status';
+export type WorkloadMetric = 'scheduled' | 'logged' | 'remaining' | 'blended';
+
+export interface WorkloadBucket {
+  date: string; // ISO date string e.g. "2026-09-14" (start of bucket)
+  timestamp: number; // Unix timestamp in ms
+  totalHours: number;
+  values: Record<string, number>; // Dimension key to hours: { [dimensionKey]: hours }
+  capacity?: Record<string, number>; // Dimension key to available capacity hours: { [dimensionKey]: capacityHours }
+  totalCapacity?: number;
+  utilizationRatio?: number; // totalHours / totalCapacity
+}
+
+export interface WorkloadDistribution {
+  projectId?: string;
+  startDate: string;
+  endDate: string;
+  interval: WorkloadInterval;
+  groupBy: WorkloadGroupBy;
+  metric: WorkloadMetric;
+  seriesKeys: string[]; // Unique series keys sorted across all buckets
+  seriesLabels: Record<string, string>; // Human-readable labels e.g. { [key]: "Alice" }
+  buckets: WorkloadBucket[];
+  totalHours: number;
+  totalCapacity?: number;
+  averageUtilization?: number;
+}
+
+export interface WorkloadDistributionOptions {
+  startDate?: string;
+  endDate?: string;
+  interval?: WorkloadInterval; // default: 'week'
+  groupBy?: WorkloadGroupBy; // default: 'assignee'
+  metric?: WorkloadMetric; // default: 'blended'
+  defaultWeeklyCapacityHours?: number; // default: 40
+  capacityOverrides?: Record<string, number>; // e.g. { [assigneeOrTeamId]: weeklyCapacityHours }
 }
 

package/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["./src/deliverables.test.ts","./src/index.test.ts","./src/index.ts","./src/status.test.ts","./src/task-state.test.ts","./src/use-case-validation.test.ts","./src/domain/cpm.test.ts","./src/domain/cpm.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/domain/ladder.test.ts","./src/domain/ladder.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/task-state.test.ts","./src/use-case-validation.test.ts","./src/domain/cpm.test.ts","./src/domain/cpm.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/domain/ladder.test.ts","./src/domain/ladder.ts","./src/domain/metrics.test.ts","./src/domain/metrics.ts","./src/domain/workload.test.ts","./src/domain/workload.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"}