@critical-path/core 0.16.0 → 0.17.0

package/src/domain/metrics.ts

@@ -0,0 +1,484 @@
+import type {
+  Task,
+  Activity,
+  TimeEntry,
+  TaskProgressInference,
+  ProgressInferenceSource,
+  ProgressCurveProfile,
+  TaskProgressHistoryPoint,
+  TaskProgressHistory,
+  TaskEVM,
+  TaskInferredActuals,
+  TaskMetrics,
+  RealityDelta
+} from '../types/index.js';
+import { resolveStatusDefinition } from '../utils/status.js';
+
+export interface MetricOptions {
+  referenceDate?: Date;
+  customStatusDefinitions?: Array<{ key: string; category: any; label: string }>;
+}
+
+/**
+ * Infer task progress percentage from explicit user input, todos/checklists,
+ * logged effort vs estimate, and elapsed schedule duration.
+ */
+export function inferTaskProgress(
+  task: Task,
+  options?: MetricOptions
+): TaskProgressInference {
+  const referenceDate = options?.referenceDate ?? new Date();
+  const statusDef = resolveStatusDefinition(task.status, options?.customStatusDefinitions);
+  const semanticStatus = task.semanticStatus || statusDef.category;
+
+  // Completed tasks are 100% complete
+  if (semanticStatus === 'completed') {
+    return {
+      progressPercentage: 100,
+      source: task.progress === 100 ? 'explicit' : 'blended',
+      isExplicit: task.progress !== undefined && task.progress !== null,
+      breakdown: {
+        explicitProgress: task.progress,
+        todoProgress: task.todos && task.todos.length > 0 ? 100 : undefined,
+        effortProgress: 100,
+        scheduleProgress: 100
+      }
+    };
+  }
+
+  // 1. Explicit Progress
+  let explicitProgress: number | undefined;
+  if (task.progress !== undefined && task.progress !== null) {
+    explicitProgress = Math.min(100, Math.max(0, Math.round(task.progress * 10) / 10));
+  }
+
+  // 2. Checklist / Todo Progress
+  let todoProgress: number | undefined;
+  if (task.todos && task.todos.length > 0) {
+    const completed = task.todos.filter((t) => t.completed).length;
+    todoProgress = Math.round((completed / task.todos.length) * 1000) / 10;
+  }
+
+  // 3. Effort / Hours Progress (Logged vs Estimated)
+  let effortProgress: number | undefined;
+  const estimatedH = task.estimatedHours || (task.estimatedDurationMinutes ? task.estimatedDurationMinutes / 60 : 0);
+  const loggedH = task.loggedHours || task.actualHours || 0;
+  if (estimatedH > 0) {
+    effortProgress = Math.min(100, Math.round((loggedH / estimatedH) * 1000) / 10);
+  }
+
+  // 4. Schedule Elapsed Progress
+  let scheduleProgress: number | undefined;
+  const startDateStr = task.actualStartDate || task.plannedStartDate;
+  if (startDateStr && task.dueDate && semanticStatus === 'in_progress') {
+    const startTime = new Date(startDateStr).getTime();
+    const dueTime = new Date(task.dueDate).getTime();
+    const nowTime = referenceDate.getTime();
+
+    if (!isNaN(startTime) && !isNaN(dueTime) && dueTime > startTime) {
+      const elapsed = nowTime - startTime;
+      const total = dueTime - startTime;
+      const ratio = Math.min(1, Math.max(0, elapsed / total));
+      scheduleProgress = Math.round(ratio * 1000) / 10;
+    }
+  }
+
+  // Select canonical progress percentage and primary inference source
+  let progressPercentage = 0;
+  let source: ProgressInferenceSource = 'explicit';
+
+  if (explicitProgress !== undefined && explicitProgress > 0) {
+    progressPercentage = explicitProgress;
+    source = 'explicit';
+  } else if (todoProgress !== undefined && todoProgress > 0) {
+    progressPercentage = todoProgress;
+    source = 'todos';
+  } else if (effortProgress !== undefined && effortProgress > 0 && semanticStatus === 'in_progress') {
+    progressPercentage = effortProgress;
+    source = 'time_effort';
+  } else if (scheduleProgress !== undefined && scheduleProgress > 0 && semanticStatus === 'in_progress') {
+    progressPercentage = scheduleProgress;
+    source = 'schedule_elapsed';
+  } else if (explicitProgress !== undefined) {
+    progressPercentage = explicitProgress;
+    source = 'explicit';
+  } else {
+    progressPercentage = 0;
+    source = 'explicit';
+  }
+
+  return {
+    progressPercentage,
+    source,
+    isExplicit: explicitProgress !== undefined,
+    breakdown: {
+      explicitProgress,
+      todoProgress,
+      effortProgress,
+      scheduleProgress
+    }
+  };
+}
+
+/**
+ * Calculate Earned Value Management (EVM) metrics for a task.
+ */
+export function calculateTaskEVM(
+  task: Task,
+  options?: MetricOptions & { progressInference?: TaskProgressInference }
+): TaskEVM {
+  const referenceDate = options?.referenceDate ?? new Date();
+  const statusDef = resolveStatusDefinition(task.status, options?.customStatusDefinitions);
+  const semanticStatus = task.semanticStatus || statusDef.category;
+
+  const estimatedHours = task.estimatedHours || (task.estimatedDurationMinutes ? task.estimatedDurationMinutes / 60 : 0);
+  const actualCost = Math.round(((task.loggedHours ?? task.actualHours) || 0) * 100) / 100;
+
+  if (estimatedHours <= 0) {
+    return {
+      plannedValue: actualCost,
+      earnedValue: actualCost,
+      actualCost,
+      costVariance: 0,
+      scheduleVariance: 0,
+      costPerformanceIndex: 1.0,
+      schedulePerformanceIndex: 1.0
+    };
+  }
+
+  const progress = options?.progressInference ?? inferTaskProgress(task, options);
+  const actualProgressRatio = Math.min(1, Math.max(0, progress.progressPercentage / 100));
+  const earnedValue = Math.round(actualProgressRatio * estimatedHours * 100) / 100;
+
+  // Compute Planned Value (PV) based on expected progress at reference date
+  let plannedRatio = 0;
+  if (semanticStatus === 'completed') {
+    plannedRatio = 1.0;
+  } else {
+    const startStr = task.plannedStartDate || task.actualStartDate;
+    if (startStr && task.dueDate) {
+      const startTime = new Date(startStr).getTime();
+      const dueTime = new Date(task.dueDate).getTime();
+      const nowTime = referenceDate.getTime();
+
+      if (!isNaN(startTime) && !isNaN(dueTime)) {
+        if (nowTime <= startTime) {
+          plannedRatio = 0;
+        } else if (nowTime >= dueTime) {
+          plannedRatio = 1.0;
+        } else {
+          plannedRatio = (nowTime - startTime) / (dueTime - startTime);
+        }
+      }
+    } else if (task.dueDate) {
+      const dueTime = new Date(task.dueDate).getTime();
+      if (!isNaN(dueTime) && referenceDate.getTime() >= dueTime) {
+        plannedRatio = 1.0;
+      } else if (semanticStatus === 'in_progress') {
+        plannedRatio = 0.5;
+      }
+    } else if (semanticStatus === 'in_progress') {
+      plannedRatio = 0.5;
+    }
+  }
+
+  const plannedValue = Math.round(plannedRatio * estimatedHours * 100) / 100;
+  const costVariance = Math.round((earnedValue - actualCost) * 100) / 100;
+  const scheduleVariance = Math.round((earnedValue - plannedValue) * 100) / 100;
+
+  const costPerformanceIndex = actualCost > 0
+    ? Math.round((earnedValue / actualCost) * 100) / 100
+    : earnedValue > 0 ? 1.0 : 1.0;
+
+  const schedulePerformanceIndex = plannedValue > 0
+    ? Math.round((earnedValue / plannedValue) * 100) / 100
+    : earnedValue > 0 ? 1.0 : 1.0;
+
+  return {
+    plannedValue,
+    earnedValue,
+    actualCost,
+    costVariance,
+    scheduleVariance,
+    costPerformanceIndex,
+    schedulePerformanceIndex
+  };
+}
+
+/**
+ * Reconstruct task progress history and curve shape from activity logs.
+ */
+export function reconstructTaskProgressHistory(
+  task: Task,
+  activities: Activity[] = [],
+  options?: MetricOptions
+): TaskProgressHistory {
+  const referenceDate = options?.referenceDate ?? new Date();
+  const taskActivities = activities
+    .filter((a) => a.taskId === task.id)
+    .sort((a, b) => new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime());
+
+  const points: TaskProgressHistoryPoint[] = [];
+
+  // Point 0: Task creation
+  points.push({
+    timestamp: task.createdAt,
+    progress: 0,
+    inferredProgress: 0,
+    status: 'todo',
+    semanticStatus: 'not_started',
+    action: 'task.created'
+  });
+
+  let runningProgress = 0;
+  let runningStatus = task.status;
+
+  for (const act of taskActivities) {
+    let pointProgress = runningProgress;
+    let pointInferred: number | undefined;
+
+    const details = (act.details || {}) as Record<string, unknown>;
+
+    if (act.action === 'task.status_changed') {
+      const newStatus = (details.toStatus as string) || (details.newStatus as string) || runningStatus;
+      runningStatus = newStatus;
+      const def = resolveStatusDefinition(newStatus, options?.customStatusDefinitions);
+      if (def.category === 'completed') {
+        pointProgress = 100;
+        pointInferred = 100;
+      }
+    } else if (act.action === 'task.updated') {
+      if (typeof details.progress === 'number') {
+        pointProgress = Math.min(100, Math.max(0, details.progress));
+      } else if (details.updates && typeof (details.updates as Record<string, unknown>).progress === 'number') {
+        pointProgress = Math.min(100, Math.max(0, (details.updates as Record<string, unknown>).progress as number));
+      }
+    }
+
+    runningProgress = pointProgress;
+    const def = resolveStatusDefinition(runningStatus, options?.customStatusDefinitions);
+
+    points.push({
+      timestamp: act.createdAt,
+      progress: pointProgress,
+      inferredProgress: pointInferred,
+      status: runningStatus,
+      semanticStatus: def.category,
+      action: act.action
+    });
+  }
+
+  // Ensure latest current state is reflected at the end if different from last point
+  const currentInferred = inferTaskProgress(task, options);
+  const currentProgress = task.progress ?? currentInferred.progressPercentage;
+  const lastPoint = points[points.length - 1];
+
+  if (!lastPoint || lastPoint.progress !== currentProgress || lastPoint.status !== task.status) {
+    points.push({
+      timestamp: task.updatedAt || referenceDate.toISOString(),
+      progress: currentProgress,
+      inferredProgress: currentInferred.progressPercentage,
+      status: task.status,
+      semanticStatus: task.semanticStatus || resolveStatusDefinition(task.status, options?.customStatusDefinitions).category,
+      action: 'snapshot.current'
+    });
+  }
+
+  // Deduplicate any points with exact same timestamp
+  const uniquePoints: TaskProgressHistoryPoint[] = [];
+  const seenTimestamps = new Set<string>();
+  for (const pt of points) {
+    if (!seenTimestamps.has(pt.timestamp + pt.action)) {
+      seenTimestamps.add(pt.timestamp + pt.action);
+      uniquePoints.push(pt);
+    }
+  }
+
+  // Classify curve profile
+  const curveProfile = classifyCurveProfile(uniquePoints, task, referenceDate);
+
+  return {
+    taskId: task.id,
+    points: uniquePoints,
+    curveProfile
+  };
+}
+
+function classifyCurveProfile(
+  points: TaskProgressHistoryPoint[],
+  task: Task,
+  referenceDate: Date
+): ProgressCurveProfile {
+  if (points.length < 3) {
+    return 'insufficient_data';
+  }
+
+  const startPt = points[0];
+  const endPt = points[points.length - 1];
+  const startTime = new Date(startPt.timestamp).getTime();
+  const endTime = new Date(endPt.timestamp).getTime();
+  const totalDuration = endTime - startTime;
+
+  if (totalDuration <= 0) {
+    return 'insufficient_data';
+  }
+
+  // Check if stalled: last 2 or more points have same progress for an extended span while in progress
+  const statusDef = resolveStatusDefinition(task.status);
+  if (statusDef.category === 'in_progress') {
+    const lastActivity = new Date(endPt.timestamp).getTime();
+    const stallThresholdMs = 5 * 24 * 60 * 60 * 1000;
+    if (referenceDate.getTime() - lastActivity > stallThresholdMs) {
+      return 'stalled';
+    }
+  }
+
+  // Sample progress at 25%, 50%, and 75% marks of timeline
+  const p25Time = startTime + totalDuration * 0.25;
+  const p50Time = startTime + totalDuration * 0.50;
+  const p75Time = startTime + totalDuration * 0.75;
+
+  const getInterpolatedProgress = (t: number): number => {
+    if (t <= startTime) return points[0].progress;
+    if (t >= endTime) return endPt.progress;
+
+    for (let i = 0; i < points.length - 1; i++) {
+      const pA = points[i];
+      const pB = points[i + 1];
+      const tA = new Date(pA.timestamp).getTime();
+      const tB = new Date(pB.timestamp).getTime();
+      if (t >= tA && t <= tB) {
+        if (tB === tA) return pA.progress;
+        const fraction = (t - tA) / (tB - tA);
+        return pA.progress + fraction * (pB.progress - pA.progress);
+      }
+    }
+    return endPt.progress;
+  };
+
+  const p25 = getInterpolatedProgress(p25Time);
+  const p50 = getInterpolatedProgress(p50Time);
+  const p75 = getInterpolatedProgress(p75Time);
+  const finalP = endPt.progress;
+
+  const totalGain = finalP - startPt.progress;
+  if (totalGain <= 5) {
+    return 'stalled';
+  }
+
+  // Early Surge: Reached > 60% early on (by 25% or 50% time) and flattened
+  if (p25 >= 60 || (p50 >= 65 && finalP - p50 <= 15)) {
+    return 'early_surge';
+  }
+
+  // Late Rush: Little progress (< 25%) until late in the timeline (75%), then steep jump
+  if (p50 <= 20 && p75 <= 35 && finalP >= 70) {
+    return 'late_rush';
+  }
+
+  // S-Curve: Slow start (p25 <= 25), steep middle acceleration (p75 - p25 >= 55), slow finish (finalP - p75 <= 20)
+  if (p25 <= 25 && (p75 - p25) >= 55 && (finalP - p75) <= 20) {
+    return 's_curve';
+  }
+
+  // Default steady progression
+  return 'linear';
+}
+
+/**
+ * Calculate comprehensive multi-dimensional metrics for a task.
+ */
+export function calculateTaskMetrics(
+  task: Task,
+  activities: Activity[] = [],
+  timeEntries: TimeEntry[] = [],
+  options?: MetricOptions
+): TaskMetrics {
+  const referenceDate = options?.referenceDate ?? new Date();
+  const taskTimeEntries = timeEntries.filter((te) => te.taskId === task.id);
+  const taskActivities = activities.filter((a) => a.taskId === task.id);
+
+  const loggedHoursFromEntries = taskTimeEntries.reduce((sum, e) => sum + e.hours, 0);
+  const effectiveLoggedHours = Math.max(loggedHoursFromEntries, task.loggedHours || 0, task.actualHours || 0);
+  const estimatedHours = task.estimatedHours || (task.estimatedDurationMinutes ? task.estimatedDurationMinutes / 60 : 0);
+  const varianceHours = Math.round((effectiveLoggedHours - estimatedHours) * 100) / 100;
+
+  // Multi-dimensional variance
+  let scheduleVarianceDays: number | undefined;
+  if (task.dueDate && task.actualEndDate) {
+    const dueTime = new Date(task.dueDate).getTime();
+    const actualTime = new Date(task.actualEndDate).getTime();
+    if (!isNaN(dueTime) && !isNaN(actualTime)) {
+      scheduleVarianceDays = Math.round((actualTime - dueTime) / (1000 * 60 * 60 * 24));
+    }
+  }
+
+  let durationVarianceHours: number | undefined;
+  if (task.actualStartDate && task.actualEndDate && task.plannedStartDate && task.dueDate) {
+    const actualDuration = (new Date(task.actualEndDate).getTime() - new Date(task.actualStartDate).getTime()) / (1000 * 60 * 60);
+    const plannedDuration = (new Date(task.dueDate).getTime() - new Date(task.plannedStartDate).getTime()) / (1000 * 60 * 60);
+    if (!isNaN(actualDuration) && !isNaN(plannedDuration)) {
+      durationVarianceHours = Math.round((actualDuration - plannedDuration) * 100) / 100;
+    }
+  }
+
+  const accuracyRatio = estimatedHours > 0
+    ? Math.round((effectiveLoggedHours / estimatedHours) * 100) / 100
+    : undefined;
+
+  const nowIso = referenceDate.toISOString();
+  const isOverdue = Boolean(
+    task.dueDate &&
+    task.dueDate < nowIso &&
+    task.semanticStatus !== 'completed' &&
+    task.semanticStatus !== 'canceled'
+  );
+  const isOverEstimate = Boolean(estimatedHours > 0 && effectiveLoggedHours > estimatedHours);
+
+  const realityDelta: RealityDelta = {
+    plannedStartDate: task.plannedStartDate,
+    actualStartDate: task.actualStartDate,
+    dueDate: task.dueDate,
+    actualEndDate: task.actualEndDate,
+    estimatedHours: Math.round(estimatedHours * 100) / 100,
+    loggedHours: Math.round(effectiveLoggedHours * 100) / 100,
+    varianceHours,
+    effortVarianceHours: varianceHours,
+    durationVarianceHours,
+    scheduleVarianceDays,
+    accuracyRatio,
+    isOverdue,
+    isOverEstimate
+  };
+
+  // Compute Inferred Actuals
+  let activeWorkingHours: number | undefined;
+  if (task.actualStartDate && task.actualEndDate) {
+    const startMs = new Date(task.actualStartDate).getTime();
+    const endMs = new Date(task.actualEndDate).getTime();
+    if (!isNaN(startMs) && !isNaN(endMs) && endMs >= startMs) {
+      activeWorkingHours = Math.round(((endMs - startMs) / (1000 * 60 * 60)) * 100) / 100;
+    }
+  }
+
+  const inferredActuals: TaskInferredActuals = {
+    actualStartDate: task.actualStartDate,
+    actualEndDate: task.actualEndDate,
+    isStartDateInferred: Boolean(task.actualStartDate && !task.plannedStartDate),
+    isEndDateInferred: Boolean(task.actualEndDate && task.semanticStatus === 'completed'),
+    activeWorkingHours
+  };
+
+  const progress = inferTaskProgress(task, options);
+  const evm = calculateTaskEVM(task, { ...options, progressInference: progress });
+  const progressHistory = reconstructTaskProgressHistory(task, taskActivities, options);
+
+  return {
+    taskId: task.id,
+    inferredActuals,
+    realityDelta,
+    progress,
+    evm,
+    progressHistory
+  };
+}

package/src/engine/index.ts

@@ -28,7 +28,9 @@ import type {
   TaskLadderView,
   MacroPhaseRollup,
   StandardTaskTimelineItem,
-  ConcreteTaskEvidence
+  ConcreteTaskEvidence,
+  TaskMetrics,
+  TaskProgressHistory
 } from '../types/index.js';
 import { StorageAdapter, InMemoryStore } from '../store/index.js';
 import { PluginRegistry } from '../plugins/index.js';
@@ -77,6 +79,11 @@ 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';
 
 export class CriticalPathEngine {
   public readonly store: StorageAdapter;
@@ -451,6 +458,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 +1375,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 +1461,54 @@ 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
+    });
+  }
+
   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

@@ -426,7 +426,7 @@ export interface CriticalPathConfig {
 }
 
 // ==========================================
-// Bret Victor's Ladder of Abstraction Types
+// Ladder of Abstraction Types
 // ==========================================
 
 export type AbstractionLevel = 'macro' | 'standard' | 'concrete' | 'all';
@@ -518,11 +518,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 +627,6 @@ export interface TaskLadderView {
   macroPhase?: MacroPhaseRollup;
   standard: StandardTaskTimelineItem;
   concrete: ConcreteTaskEvidence;
+  metrics?: TaskMetrics;
 }
 

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/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"}