@critical-path/core 0.18.0 → 0.19.0

package/src/domain/ladder.ts

@@ -17,9 +17,11 @@ import type {
   ConcreteTaskEvidence,
   ConcreteEvidenceSummary,
   RealityDelta,
-  TaskLadderView
+  TaskLadderView,
+  WorkSchedule
 } from '../types/index.js';
 import { calculateCPM, getTaskDurationHours } from './cpm.js';
+import { DEFAULT_WORK_SCHEDULE, getWorkingDaysBetween } from './calendar.js';
 
 export interface LadderContext {
   project: Project;
@@ -31,6 +33,7 @@ export interface LadderContext {
   attachments?: Attachment[];
   timeEntries?: TimeEntry[];
   activities?: Activity[];
+  schedule?: WorkSchedule;
 }
 
 export function aggregateConcreteEvidenceForTask(
@@ -38,7 +41,8 @@ export function aggregateConcreteEvidenceForTask(
   attachments: Attachment[] = [],
   deliverables: Deliverable[] = [],
   timeEntries: TimeEntry[] = [],
-  activities: Activity[] = []
+  activities: Activity[] = [],
+  schedule?: WorkSchedule
 ): ConcreteTaskEvidence {
   const taskAttachments = attachments.filter((a) => a.taskId === task.id);
   const taskDeliverables = deliverables.filter(
@@ -70,10 +74,19 @@ export function aggregateConcreteEvidenceForTask(
   const isOverEstimate = Boolean(estimatedHours > 0 && effectiveLoggedHours > estimatedHours);
 
   let scheduleVarianceDays: number | undefined;
+  let scheduleVarianceWorkingDays: number | undefined;
   if (task.dueDate && task.actualEndDate) {
     const dueTime = new Date(task.dueDate).getTime();
     const actualTime = new Date(task.actualEndDate).getTime();
     scheduleVarianceDays = Math.round((actualTime - dueTime) / (1000 * 60 * 60 * 24));
+    const effectiveSched = schedule || DEFAULT_WORK_SCHEDULE;
+    if (actualTime > dueTime) {
+      scheduleVarianceWorkingDays = Math.max(0, getWorkingDaysBetween(task.dueDate, task.actualEndDate, effectiveSched) - 1);
+    } else if (actualTime < dueTime) {
+      scheduleVarianceWorkingDays = -Math.max(0, getWorkingDaysBetween(task.actualEndDate, task.dueDate, effectiveSched) - 1);
+    } else {
+      scheduleVarianceWorkingDays = 0;
+    }
   }
 
   let durationVarianceHours: number | undefined;
@@ -100,6 +113,7 @@ export function aggregateConcreteEvidenceForTask(
     effortVarianceHours: varianceHours,
     durationVarianceHours,
     scheduleVarianceDays,
+    scheduleVarianceWorkingDays,
     accuracyRatio,
     isOverdue,
     isOverEstimate
@@ -309,8 +323,14 @@ export function buildTimelineLadder(
   const targetLevel = options.level || 'all';
   const generatedAt = new Date().toISOString();
 
+  const effectiveSchedule = context.schedule || project.schedule || DEFAULT_WORK_SCHEDULE;
+  const projectStartDate = project.startDate || (tasks.length > 0 ? tasks.find((t) => t.plannedStartDate)?.plannedStartDate : undefined);
+
   // Run Critical Path Method (CPM)
-  const cpm = calculateCPM(project.id, tasks, dependencies);
+  const cpm = calculateCPM(project.id, tasks, dependencies, {
+    schedule: effectiveSchedule,
+    projectStartDate
+  });
   const criticalSet = new Set(cpm.criticalTaskIds);
   const scheduleMap = new Map(cpm.tasks.map((s) => [s.taskId, s]));
 
@@ -352,7 +372,8 @@ export function buildTimelineLadder(
       attachments,
       deliverables,
       timeEntries,
-      activities
+      activities,
+      effectiveSchedule
     );
   }
 

package/src/domain/metrics.test.ts

@@ -148,6 +148,8 @@ describe('Task Metrics Domain', () => {
   });
 
   describe('reconstructTaskProgressHistory & Curve Profile', () => {
+    const referenceDate = new Date('2026-09-09T12:00:00Z');
+
     it('detects linear progress', () => {
       const activities: Activity[] = [
         { id: 'a1', taskId: 'task-1', actorId: 'u1', action: 'task.updated', details: { progress: 25 }, createdAt: '2026-09-02T10:00:00Z' },
@@ -156,7 +158,7 @@ describe('Task Metrics Domain', () => {
         { id: 'a4', taskId: 'task-1', actorId: 'u1', action: 'task.updated', details: { progress: 100 }, createdAt: '2026-09-08T10:00:00Z' }
       ];
       const task: Task = { ...baseTask, progress: 100, updatedAt: '2026-09-08T10:00:00Z' };
-      const history = reconstructTaskProgressHistory(task, activities);
+      const history = reconstructTaskProgressHistory(task, activities, { referenceDate });
 
       expect(history.points.length).toBeGreaterThanOrEqual(4);
       expect(history.curveProfile).toBe('linear');
@@ -170,7 +172,7 @@ describe('Task Metrics Domain', () => {
         { id: 'a4', taskId: 'task-1', actorId: 'u1', action: 'task.updated', details: { progress: 95 }, createdAt: '2026-09-09T10:00:00Z' }
       ];
       const task: Task = { ...baseTask, progress: 95, updatedAt: '2026-09-09T10:00:00Z' };
-      const history = reconstructTaskProgressHistory(task, activities);
+      const history = reconstructTaskProgressHistory(task, activities, { referenceDate });
 
       expect(history.curveProfile).toBe('s_curve');
     });
@@ -182,7 +184,7 @@ describe('Task Metrics Domain', () => {
         { id: 'a3', taskId: 'task-1', actorId: 'u1', action: 'task.updated', details: { progress: 78 }, createdAt: '2026-09-08T10:00:00Z' }
       ];
       const task: Task = { ...baseTask, progress: 78, updatedAt: '2026-09-08T10:00:00Z' };
-      const history = reconstructTaskProgressHistory(task, activities);
+      const history = reconstructTaskProgressHistory(task, activities, { referenceDate });
 
       expect(history.curveProfile).toBe('early_surge');
     });
@@ -194,7 +196,7 @@ describe('Task Metrics Domain', () => {
         { id: 'a3', taskId: 'task-1', actorId: 'u1', action: 'task.updated', details: { progress: 90 }, createdAt: '2026-09-08T10:00:00Z' }
       ];
       const task: Task = { ...baseTask, progress: 90, updatedAt: '2026-09-08T10:00:00Z' };
-      const history = reconstructTaskProgressHistory(task, activities);
+      const history = reconstructTaskProgressHistory(task, activities, { referenceDate });
 
       expect(history.curveProfile).toBe('late_rush');
     });

package/src/domain/workload.test.ts

@@ -235,4 +235,77 @@ describe('calculateWorkloadDistribution', () => {
     expect(distribution.buckets.length).toBeGreaterThan(0);
     expect(distribution.seriesKeys).toContain('u1');
   });
+
+  it('distributes task effort only on working days and reduces capacity on holidays', () => {
+    // Friday 2026-09-18 to Tuesday 2026-09-22 (5 calendar days: Fri, Sat, Sun, Mon, Tue)
+    // Monday 2026-09-21 is a Holiday!
+    // Active working days: Friday 2026-09-18 and Tuesday 2026-09-22 (2 days total)
+    // 16 estimated hours should be divided into 8h on Fri, 0h on Sat, 0h on Sun, 0h on Mon, 8h on Tue!
+    const customSchedule = {
+      name: 'Holiday Calendar',
+      defaultHoursPerDay: 8,
+      days: [
+        { dayOfWeek: 0, isWorkingDay: false },
+        { dayOfWeek: 1, isWorkingDay: true, hours: [{ start: '09:00', end: '17:00' }] },
+        { dayOfWeek: 2, isWorkingDay: true, hours: [{ start: '09:00', end: '17:00' }] },
+        { dayOfWeek: 3, isWorkingDay: true, hours: [{ start: '09:00', end: '17:00' }] },
+        { dayOfWeek: 4, isWorkingDay: true, hours: [{ start: '09:00', end: '17:00' }] },
+        { dayOfWeek: 5, isWorkingDay: true, hours: [{ start: '09:00', end: '17:00' }] },
+        { dayOfWeek: 6, isWorkingDay: false }
+      ],
+      holidays: [{ date: '2026-09-21', name: 'Monday Holiday' }]
+    };
+
+    const tasks: Task[] = [
+      {
+        id: 't_holiday',
+        projectId: 'p1',
+        title: 'Holiday Spanning Task',
+        status: 'todo',
+        priority: 'high',
+        assigneeId: 'u2',
+        estimatedHours: 16,
+        plannedStartDate: '2026-09-18', // Friday
+        dueDate: '2026-09-22',          // Tuesday
+        createdAt: '2026-09-01',
+        updatedAt: '2026-09-01'
+      }
+    ];
+
+    const result = calculateWorkloadDistribution(
+      { tasks, users },
+      {
+        startDate: '2026-09-18',
+        endDate: '2026-09-22',
+        interval: 'day',
+        groupBy: 'assignee',
+        metric: 'scheduled',
+        schedule: customSchedule
+      }
+    );
+
+    const fri = result.buckets.find((b) => b.date === '2026-09-18');
+    const sat = result.buckets.find((b) => b.date === '2026-09-19');
+    const sun = result.buckets.find((b) => b.date === '2026-09-20');
+    const mon = result.buckets.find((b) => b.date === '2026-09-21');
+    const tue = result.buckets.find((b) => b.date === '2026-09-22');
+
+    expect(fri?.values.u2).toBe(8);
+    expect(fri?.capacity?.u2).toBe(8);
+
+    expect(sat?.values.u2).toBe(0);
+    expect(sat?.capacity?.u2).toBe(0);
+
+    expect(sun?.values.u2).toBe(0);
+    expect(sun?.capacity?.u2).toBe(0);
+
+    // Monday is holiday: 0 scheduled effort, 0 capacity
+    expect(mon?.values.u2).toBe(0);
+    expect(mon?.capacity?.u2).toBe(0);
+
+    expect(tue?.values.u2).toBe(8);
+    expect(tue?.capacity?.u2).toBe(8);
+
+    expect(result.totalHours).toBe(16);
+  });
 });

package/src/domain/workload.ts

@@ -10,6 +10,12 @@ import type {
   WorkloadDistribution,
   WorkloadDistributionOptions
 } from '../types/index.js';
+import {
+  DEFAULT_WORK_SCHEDULE,
+  getWorkingDaysList,
+  getNetAvailableCapacity,
+  getWorkingHoursInDay
+} from './calendar.js';
 
 export interface WorkloadContext {
   tasks: Task[];
@@ -260,21 +266,53 @@ export function calculateWorkloadDistribution(
         taskEnd = taskStart;
       }
 
-      // Calculate days in task window
+      // Resolve schedule for task assignee / team / project
+      const taskSchedule =
+        (task.assigneeId && options.userSchedules?.[task.assigneeId]) ||
+        (task.assigneeId && userMap.get(task.assigneeId)?.schedule) ||
+        (task.teamId && options.teamSchedules?.[task.teamId]) ||
+        (task.teamId && teamMap.get(task.teamId)?.schedule) ||
+        options.schedule ||
+        DEFAULT_WORK_SCHEDULE;
+
+      const workingDays = getWorkingDaysList(taskStart, taskEnd, taskSchedule);
       const msPerDay = 1000 * 60 * 60 * 24;
-      const totalDays = Math.max(1, Math.round((taskEnd.getTime() - taskStart.getTime()) / msPerDay) + 1);
-      const hoursPerDay = hoursToDistribute / totalDays;
-
-      // Distribute across overlapping buckets
-      for (const bucket of bucketList) {
-        const bucketLastDay = addDays(bucket.endDate, -1);
-        const overlapStart = new Date(Math.max(taskStart.getTime(), bucket.startDate.getTime()));
-        const overlapEnd = new Date(Math.min(taskEnd.getTime(), bucketLastDay.getTime()));
-
-        if (overlapStart <= overlapEnd) {
-          const overlapDays = Math.round((overlapEnd.getTime() - overlapStart.getTime()) / msPerDay) + 1;
-          const bucketEffort = overlapDays * hoursPerDay;
-          addValue(bucket, dimKey, bucketEffort);
+
+      if (workingDays.length > 0) {
+        const hoursPerWorkingDay = hoursToDistribute / workingDays.length;
+
+        for (const bucket of bucketList) {
+          const bucketStart = bucket.startDate.getTime();
+          const bucketEnd = bucket.endDate.getTime();
+
+          let workingDaysInBucket = 0;
+          for (const wdStr of workingDays) {
+            const wdTime = parseDateOnly(wdStr).getTime();
+            if (wdTime >= bucketStart && wdTime < bucketEnd) {
+              workingDaysInBucket++;
+            }
+          }
+
+          if (workingDaysInBucket > 0) {
+            const bucketEffort = workingDaysInBucket * hoursPerWorkingDay;
+            addValue(bucket, dimKey, bucketEffort);
+          }
+        }
+      } else {
+        // Fallback if no working days in range (e.g. task scheduled on an all-holiday window)
+        const totalDays = Math.max(1, Math.round((taskEnd.getTime() - taskStart.getTime()) / msPerDay) + 1);
+        const hoursPerDay = hoursToDistribute / totalDays;
+
+        for (const bucket of bucketList) {
+          const bucketLastDay = addDays(bucket.endDate, -1);
+          const overlapStart = new Date(Math.max(taskStart.getTime(), bucket.startDate.getTime()));
+          const overlapEnd = new Date(Math.min(taskEnd.getTime(), bucketLastDay.getTime()));
+
+          if (overlapStart <= overlapEnd) {
+            const overlapDays = Math.round((overlapEnd.getTime() - overlapStart.getTime()) / msPerDay) + 1;
+            const bucketEffort = overlapDays * hoursPerDay;
+            addValue(bucket, dimKey, bucketEffort);
+          }
         }
       }
     }
@@ -325,6 +363,12 @@ export function calculateWorkloadDistribution(
       bucketTotalHours += roundedHours;
 
       // Capacity calculation
+      const entitySchedule =
+        (groupBy === 'assignee' && (options.userSchedules?.[key] || userMap.get(key)?.schedule)) ||
+        (groupBy === 'team' && (options.teamSchedules?.[key] || teamMap.get(key)?.schedule)) ||
+        options.schedule ||
+        DEFAULT_WORK_SCHEDULE;
+
       let weeklyCap = defaultWeeklyCapacity;
       if (options.capacityOverrides && typeof options.capacityOverrides[key] === 'number') {
         weeklyCap = options.capacityOverrides[key];
@@ -344,13 +388,23 @@ export function calculateWorkloadDistribution(
       }
 
       let bucketCap = 0;
-      if (interval === 'week') {
-        bucketCap = weeklyCap;
+      if (key === 'unassigned') {
+        bucketCap = 0;
+      } else if (interval === 'week') {
+        const netWeekCap = getNetAvailableCapacity(ib.startDate, addDays(ib.endDate, -1), entitySchedule);
+        const baseline = (entitySchedule.defaultHoursPerDay ?? 8) * 5;
+        const scale = baseline > 0 ? weeklyCap / baseline : 1;
+        bucketCap = Math.round(netWeekCap * scale * 100) / 100;
       } else if (interval === 'day') {
-        bucketCap = Math.round((weeklyCap / 5) * 100) / 100;
+        const dayHours = getWorkingHoursInDay(ib.startDate, entitySchedule);
+        const baseline = (entitySchedule.defaultHoursPerDay ?? 8) * 5;
+        const scale = baseline > 0 ? weeklyCap / baseline : 1;
+        bucketCap = Math.round(dayHours * scale * 100) / 100;
       } else if (interval === 'month') {
-        const daysInMonth = new Date(Date.UTC(ib.startDate.getUTCFullYear(), ib.startDate.getUTCMonth() + 1, 0)).getUTCDate();
-        bucketCap = Math.round((weeklyCap * (daysInMonth / 7)) * 100) / 100;
+        const netMonthCap = getNetAvailableCapacity(ib.startDate, addDays(ib.endDate, -1), entitySchedule);
+        const baseline = (entitySchedule.defaultHoursPerDay ?? 8) * 5;
+        const scale = baseline > 0 ? weeklyCap / baseline : 1;
+        bucketCap = Math.round(netMonthCap * scale * 100) / 100;
       }
 
       capacity[key] = bucketCap;

package/src/engine/index.ts

@@ -51,6 +51,7 @@ import {
   TaskCreatedEvent,
   TaskUpdatedEvent,
   TaskStatusChangedEvent,
+  TaskBlockedEvent,
   TaskUnblockedEvent,
   TaskDeletedEvent,
   ProjectCreatedEvent,
@@ -79,7 +80,7 @@ import {
 import { validateAttachmentUrl, AttachmentValidationError } from '../domain/entities.js';
 import { validateCustomFieldValues } from '../domain/custom-fields.js';
 import { detectDependencyCycle, CircularDependencyError } from '../domain/graph.js';
-import { calculateCPM } from '../domain/cpm.js';
+import { calculateCPM, type CPMOptions } from '../domain/cpm.js';
 import { buildTimelineLadder, aggregateConcreteEvidenceForTask } from '../domain/ladder.js';
 import {
   calculateTaskMetrics,
@@ -89,6 +90,7 @@ import {
 import { calculateWorkloadDistribution } from '../domain/workload.js';
 
 export class CriticalPathEngine {
+  public readonly config: CriticalPathConfig;
   public readonly store: StorageAdapter;
   public readonly fileStorage?: FileStorageAdapter;
   public readonly plugins: PluginRegistry;
@@ -96,6 +98,7 @@ export class CriticalPathEngine {
   public readonly ready: Promise<void> = Promise.resolve();
 
   constructor(config: CriticalPathConfig = {}) {
+    this.config = config;
     this.store = typeof config.store === 'object' && config.store !== null
       ? (config.store as StorageAdapter)
       : new InMemoryStore();
@@ -531,6 +534,58 @@ export class CriticalPathEngine {
       await this.events.publish(updateEvent);
     }
 
+    const wasBlocked = Boolean(existing.isBlocked || existing.customFields?.isBlocked || existing.status === 'blocked');
+    const isNowBlocked = Boolean(updated.isBlocked || updated.customFields?.isBlocked || updated.status === 'blocked');
+
+    if (!wasBlocked && isNowBlocked) {
+      const blockedReason = updated.blockedReason ?? (updated.customFields?.blockedReason as string | undefined) ?? null;
+      const blockedEvent: TaskBlockedEvent = {
+        id: `evt_${Math.random().toString(36).substring(2, 9)}`,
+        name: 'task.blocked',
+        aggregateId: updated.id,
+        aggregateType: 'Task',
+        occurredAt: now,
+        payload: {
+          task: updated,
+          reason: blockedReason
+        }
+      };
+      await this.events.publish(blockedEvent);
+      await this.store.logActivity({
+        projectId: updated.projectId,
+        taskId: updated.id,
+        actorId: updated.assigneeId || 'system',
+        action: 'task.blocked',
+        details: { reason: blockedReason }
+      });
+      this.dispatchWebhook('task.blocked', {
+        task: updated,
+        reason: blockedReason
+      });
+    } else if (wasBlocked && !isNowBlocked) {
+      const unblockedEvent: TaskUnblockedEvent = {
+        id: `evt_${Math.random().toString(36).substring(2, 9)}`,
+        name: 'task.unblocked',
+        aggregateId: updated.id,
+        aggregateType: 'Task',
+        occurredAt: now,
+        payload: {
+          task: updated
+        }
+      };
+      await this.events.publish(unblockedEvent);
+      await this.store.logActivity({
+        projectId: updated.projectId,
+        taskId: updated.id,
+        actorId: updated.assigneeId || 'system',
+        action: 'task.unblocked',
+        details: {}
+      });
+      this.dispatchWebhook('task.unblocked', {
+        task: updated
+      });
+    }
+
     await this.store.logActivity({
       projectId: updated.projectId,
       taskId: updated.id,
@@ -577,6 +632,11 @@ export class CriticalPathEngine {
             updates.status = defaultStatus;
           }
 
+          if (downstream.isBlocked || downstream.blockedReason) {
+            updates.isBlocked = false;
+            updates.blockedReason = null;
+          }
+
           if (downstream.customFields?.isBlocked || downstream.customFields?.blockedReason) {
             updates.customFields = {
               ...downstream.customFields,
@@ -1379,7 +1439,11 @@ export class CriticalPathEngine {
   }
 
   // --- Ladder of Abstraction & Critical Path Method ---
-  async calculateCriticalPath(projectId: string): Promise<CriticalPathAnalysis> {
+  async calculateCriticalPath(
+    projectId: string,
+    options: CPMOptions = {}
+  ): Promise<CriticalPathAnalysis> {
+    const project = await this.store.getProject(projectId);
     const tasks = await this.store.getTasks(projectId);
     const allDepArrays = await Promise.all(tasks.map((t) => this.store.getDependencies(t.id)));
     const seenDepIds = new Set<string>();
@@ -1392,7 +1456,9 @@ export class CriticalPathEngine {
         }
       }
     }
-    return calculateCPM(projectId, tasks, dependencies);
+    const schedule = options.schedule || project?.schedule || this.config.defaultSchedule;
+    const projectStartDate = options.projectStartDate || project?.startDate;
+    return calculateCPM(projectId, tasks, dependencies, { schedule, projectStartDate });
   }
 
   async getTimelineLadder(
@@ -1435,6 +1501,8 @@ export class CriticalPathEngine {
     const timeEntriesNested = await Promise.all(tasks.map((t) => this.store.getTimeEntries(t.id)));
     const timeEntries: TimeEntry[] = timeEntriesNested.flat();
 
+    const schedule = project.schedule || this.config.defaultSchedule;
+
     return buildTimelineLadder(
       {
         project,
@@ -1445,7 +1513,8 @@ export class CriticalPathEngine {
         deliverables,
         attachments,
         timeEntries,
-        activities
+        activities,
+        schedule
       },
       options
     );
@@ -1518,6 +1587,8 @@ export class CriticalPathEngine {
   ): Promise<WorkloadDistribution> {
     const tasks = await this.store.getTasks(projectId);
     const teams = await this.store.getTeams();
+    const project = projectId ? await this.store.getProject(projectId) : undefined;
+    const schedule = options.schedule || project?.schedule || this.config.defaultSchedule;
 
     const timeEntriesNested = await Promise.all(tasks.map((t) => this.store.getTimeEntries(t.id)));
     const timeEntries: TimeEntry[] = timeEntriesNested.flat();
@@ -1529,7 +1600,10 @@ export class CriticalPathEngine {
         teams,
         projectId
       },
-      options
+      {
+        ...options,
+        schedule
+      }
     );
   }
 

package/src/store/sqlite.test.ts

@@ -40,8 +40,24 @@ describe('SQLiteStore', () => {
     expect(task.priority).toBe('high');
     expect(task.tags).toContain('sqlite');
 
-    const updated = await store.updateTask(task.id, { status: 'in_progress' });
+    const updated = await store.updateTask(task.id, {
+      status: 'in_progress',
+      isBlocked: true,
+      blockedReason: 'Waiting for SQLite lock'
+    });
     expect(updated?.status).toBe('in_progress');
+    expect(updated?.isBlocked).toBe(true);
+    expect(updated?.blockedReason).toBe('Waiting for SQLite lock');
+
+    const fetchedTask = await store.getTask(task.id);
+    expect(fetchedTask?.isBlocked).toBe(true);
+    expect(fetchedTask?.blockedReason).toBe('Waiting for SQLite lock');
+
+    const unblocked = await store.updateTask(task.id, {
+      isBlocked: false,
+      blockedReason: null
+    });
+    expect(unblocked?.isBlocked).toBe(false);
 
     const projectTasks = await store.getTasks(project.id);
     expect(projectTasks).toHaveLength(1);

package/src/store/sqlite.ts

@@ -132,6 +132,8 @@ export class SQLiteStore implements StorageAdapter {
         actualDurationMinutes REAL,
         billableDurationMinutes REAL,
         progress REAL,
+        isBlocked INTEGER,
+        blockedReason TEXT,
         tags TEXT,
         customFields TEXT,
         parentId TEXT,
@@ -659,8 +661,9 @@ export class SQLiteStore implements StorageAdapter {
         reviewerId, iterationId, teamId, containerId, deliverableId, plannedStartDate, actualStartDate, actualEndDate,
         dueDate, estimatedHours, loggedHours, actualHours, billableHours,
         estimatedDurationMinutes, actualDurationMinutes, billableDurationMinutes, progress,
+        isBlocked, blockedReason,
         tags, customFields, parentId, createdAt, updatedAt
-      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `);
     stmt.run(
       newTask.id,
@@ -690,6 +693,8 @@ export class SQLiteStore implements StorageAdapter {
       newTask.actualDurationMinutes ?? null,
       newTask.billableDurationMinutes ?? null,
       newTask.progress ?? null,
+      newTask.isBlocked !== undefined ? (newTask.isBlocked ? 1 : 0) : null,
+      newTask.blockedReason ?? null,
       JSON.stringify(newTask.tags || []),
       JSON.stringify(newTask.customFields || {}),
       newTask.parentId || null,
@@ -716,6 +721,7 @@ export class SQLiteStore implements StorageAdapter {
         plannedStartDate = ?, actualStartDate = ?, actualEndDate = ?, dueDate = ?,
         estimatedHours = ?, loggedHours = ?, actualHours = ?, billableHours = ?,
         estimatedDurationMinutes = ?, actualDurationMinutes = ?, billableDurationMinutes = ?, progress = ?,
+        isBlocked = ?, blockedReason = ?,
         tags = ?, customFields = ?, parentId = ?, updatedAt = ?
       WHERE id = ?
     `);
@@ -746,6 +752,8 @@ export class SQLiteStore implements StorageAdapter {
       updated.actualDurationMinutes ?? null,
       updated.billableDurationMinutes ?? null,
       updated.progress ?? null,
+      updated.isBlocked !== undefined ? (updated.isBlocked ? 1 : 0) : null,
+      updated.blockedReason ?? null,
       JSON.stringify(updated.tags || []),
       JSON.stringify(updated.customFields || {}),
       updated.parentId || null,
@@ -1188,6 +1196,8 @@ export class SQLiteStore implements StorageAdapter {
   private mapTask(row: any): Task {
     return {
       ...row,
+      isBlocked: row.isBlocked !== null && row.isBlocked !== undefined ? Boolean(row.isBlocked) : undefined,
+      blockedReason: row.blockedReason || undefined,
       taskType: row.taskType || undefined,
       deliverableId: row.deliverableId || undefined,
       tags: row.tags ? JSON.parse(row.tags) : [],

package/src/task-state.test.ts

@@ -1,7 +1,7 @@
 import { describe, it, expect, vi } from 'vitest';
 import { CriticalPathEngine } from './engine/index.js';
 import { deriveTaskLifecycleState } from './utils/status.js';
-import type { Task, StatusDefinition, TaskUnblockedEvent } from './index.js';
+import type { Task, StatusDefinition, TaskBlockedEvent, TaskUnblockedEvent } from './index.js';
 
 describe('Task State Behaviour & Dependency Validation', () => {
   const baseTask: Task = {
@@ -443,5 +443,64 @@ describe('Task State Behaviour & Dependency Validation', () => {
       expect(lifecycle?.isBlocked).toBe(false);
       expect(lifecycle?.isReady).toBe(true);
     });
+
+    it('manages first-class isBlocked and blockedReason independently of workflow status', async () => {
+      const engine = new CriticalPathEngine();
+      const project = await engine.createProject({ key: 'BLOCK', name: 'First Class Blocking' });
+
+      const blockedEvents: TaskBlockedEvent[] = [];
+      const unblockedEvents: TaskUnblockedEvent[] = [];
+      engine.events.subscribe<TaskBlockedEvent>('task.blocked', (evt) => {
+        blockedEvents.push(evt);
+      });
+      engine.events.subscribe<TaskUnblockedEvent>('task.unblocked', (evt) => {
+        unblockedEvents.push(evt);
+      });
+
+      // 1. Create a task in 'in_progress' status
+      const task = await engine.createTask({
+        projectId: project.id,
+        title: 'Work on feature',
+        status: 'in_progress'
+      });
+
+      let lifecycle = await engine.getTaskLifecycleState(task.id);
+      expect(lifecycle?.isBlocked).toBe(false);
+
+      // 2. Explicitly block the task while keeping status in_progress
+      const blockedTask = await engine.updateTask(task.id, {
+        isBlocked: true,
+        blockedReason: 'Awaiting third-party API key'
+      });
+      expect(blockedTask?.isBlocked).toBe(true);
+      expect(blockedTask?.blockedReason).toBe('Awaiting third-party API key');
+      expect(blockedTask?.status).toBe('in_progress');
+
+      // Verify domain event
+      expect(blockedEvents).toHaveLength(1);
+      expect(blockedEvents[0].aggregateId).toBe(task.id);
+      expect(blockedEvents[0].payload.reason).toBe('Awaiting third-party API key');
+
+      // Verify lifecycle state
+      lifecycle = await engine.getTaskLifecycleState(task.id);
+      expect(lifecycle?.isBlocked).toBe(true);
+      expect(lifecycle?.isReady).toBe(false);
+
+      // 3. Unblock the task
+      const unblockedTask = await engine.updateTask(task.id, {
+        isBlocked: false,
+        blockedReason: null
+      });
+      expect(unblockedTask?.isBlocked).toBe(false);
+      expect(unblockedTask?.blockedReason).toBeNull();
+      expect(unblockedTask?.status).toBe('in_progress');
+
+      // Verify domain event
+      expect(unblockedEvents).toHaveLength(1);
+      expect(unblockedEvents[0].aggregateId).toBe(task.id);
+
+      lifecycle = await engine.getTaskLifecycleState(task.id);
+      expect(lifecycle?.isBlocked).toBe(false);
+    });
   });
 });