@critical-path/core 0.20.1 → 0.21.0

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,
@@ -133,6 +134,8 @@ export class SQLiteStore implements StorageAdapter {
         billableDurationMinutes REAL,
         actualDurationSeconds REAL,
         inProgressSince TEXT,
+        blockedDurationSeconds REAL,
+        blockedSince TEXT,
         progress REAL,
         isBlocked INTEGER,
         blockedReason TEXT,
@@ -264,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 ---
@@ -660,21 +669,21 @@ 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, progress,
+        actualDurationSeconds, inProgressSince, blockedDurationSeconds, blockedSince, progress,
         isBlocked, blockedReason,
         tags, customFields, parentId, createdAt, updatedAt
-      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `);
     stmt.run(
       newTask.id,
       newTask.projectId,
       newTask.title,
       newTask.description || null,
-      newTask.status,
-      newTask.priority,
+      newTask.status || 'todo',
+      newTask.priority || 'medium',
       newTask.taskType || null,
       newTask.assigneeId || null,
       newTask.assignees ? JSON.stringify(newTask.assignees) : null,
@@ -687,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,
@@ -697,6 +707,8 @@ export class SQLiteStore implements StorageAdapter {
       newTask.billableDurationMinutes ?? null,
       newTask.actualDurationSeconds ?? null,
       newTask.inProgressSince ?? null,
+      newTask.blockedDurationSeconds ?? null,
+      newTask.blockedSince ?? null,
       newTask.progress ?? null,
       newTask.isBlocked !== undefined ? (newTask.isBlocked ? 1 : 0) : null,
       newTask.blockedReason ?? null,
@@ -723,10 +735,10 @@ 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 = ?, progress = ?,
+        actualDurationSeconds = ?, inProgressSince = ?, blockedDurationSeconds = ?, blockedSince = ?, progress = ?,
         isBlocked = ?, blockedReason = ?,
         tags = ?, customFields = ?, parentId = ?, updatedAt = ?
       WHERE id = ?
@@ -749,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,
@@ -759,6 +772,8 @@ export class SQLiteStore implements StorageAdapter {
       updated.billableDurationMinutes ?? null,
       updated.actualDurationSeconds ?? null,
       updated.inProgressSince ?? null,
+      updated.blockedDurationSeconds ?? null,
+      updated.blockedSince ?? null,
       updated.progress ?? null,
       updated.isBlocked !== undefined ? (updated.isBlocked ? 1 : 0) : null,
       updated.blockedReason ?? null,
@@ -1204,6 +1219,12 @@ export class SQLiteStore implements StorageAdapter {
   private mapTask(row: any): Task {
     return {
       ...row,
+      actualDurationSeconds: row.actualDurationSeconds ?? undefined,
+      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;
@@ -218,6 +219,10 @@ export interface Task {
   actualDurationSeconds?: number;
   /** Transient ISO timestamp marking the start of current 'in_progress' session (null when not in_progress) */
   inProgressSince?: string | null;
+  /** Cumulative duration spent in blocked state while in progress (in seconds) */
+  blockedDurationSeconds?: number;
+  /** Transient ISO timestamp marking when the task became blocked while in progress (null when not blocked or not in_progress) */
+  blockedSince?: string | null;
   // Progress (0 to 100 percentage)
   progress?: number;
   isBlocked?: boolean;
@@ -634,6 +639,8 @@ export interface TaskInferredActuals {
   calendarDurationHours?: number;
   /** Cumulative active execution duration in seconds */
   actualDurationSeconds?: number;
+  /** Cumulative duration spent in blocked state while in progress (in seconds) */
+  blockedDurationSeconds?: number;
 }
 
 export interface TaskMetrics {

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

package/src/utils/fractional-index.ts

@@ -0,0 +1,260 @@
+/**
+ * Fractional Lexical Indexing Utility
+ *
+ * Deterministic Base-62 fractional indexing for ordered lists and swimlane task sequences.
+ * Produces lexicographically sortable strings (`orderIndex`) that allow infinite insertion
+ * between any two items without floating-point precision loss.
+ */
+
+export const BASE_62 = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz';
+
+/**
+ * Encodes a non-negative integer into Base-62.
+ */
+function toBase62(n: number): string {
+  if (n === 0) return '0';
+  let s = '';
+  let curr = n;
+  while (curr > 0) {
+    s = BASE_62[curr % 62] + s;
+    curr = Math.floor(curr / 62);
+  }
+  return s;
+}
+
+/**
+ * Decodes a Base-62 string into a non-negative integer.
+ */
+function fromBase62(s: string): number {
+  let n = 0;
+  for (let i = 0; i < s.length; i++) {
+    const idx = BASE_62.indexOf(s[i]);
+    if (idx === -1) return 0;
+    n = n * 62 + idx;
+  }
+  return n;
+}
+
+/**
+ * Encodes an integer into a prefix-encoded string such that standard
+ * string comparison strictly matches integer comparison.
+ *
+ * Non-negative integers (0, 1, 2, ...):
+ *   Prefix 'a'-'z' specifies the digit count (1 to 26 digits).
+ *   0 -> "a0", 1 -> "a1", 61 -> "az", 62 -> "b10", ...
+ *
+ * Negative integers (-1, -2, ...):
+ *   Prefix 'Z'-'A' specifies inverted digit count with inverted digits.
+ *   -1 -> "Zz", -2 -> "Zy", ...
+ */
+export function encodeInteger(n: number): string {
+  if (n >= 0) {
+    const digits = toBase62(n);
+    const prefixCode = 97 + digits.length - 1; // 97 is 'a'
+    const prefix = String.fromCharCode(Math.min(prefixCode, 122)); // clamp to 'z'
+    return prefix + digits;
+  } else {
+    const pos = -n - 1;
+    const digits = toBase62(pos);
+    let inverted = '';
+    for (let i = 0; i < digits.length; i++) {
+      const idx = BASE_62.indexOf(digits[i]);
+      inverted += BASE_62[61 - idx];
+    }
+    const prefixCode = 90 - (digits.length - 1); // 90 is 'Z'
+    const prefix = String.fromCharCode(Math.max(prefixCode, 65)); // clamp to 'A'
+    return prefix + inverted;
+  }
+}
+
+/**
+ * Decodes a prefix-encoded integer string back into a number.
+ */
+export function decodeInteger(s: string): number {
+  if (!s || s.length < 2) return 0;
+  const prefix = s[0];
+  if (prefix >= 'a' && prefix <= 'z') {
+    const len = prefix.charCodeAt(0) - 97 + 1;
+    const digits = s.slice(1, 1 + len);
+    return fromBase62(digits);
+  } else if (prefix >= 'A' && prefix <= 'Z') {
+    const len = 90 - prefix.charCodeAt(0) + 1;
+    const inverted = s.slice(1, 1 + len);
+    let digits = '';
+    for (let i = 0; i < inverted.length; i++) {
+      const idx = BASE_62.indexOf(inverted[i]);
+      digits += idx !== -1 ? BASE_62[61 - idx] : '0';
+    }
+    const pos = fromBase62(digits);
+    return -pos - 1;
+  }
+  return 0;
+}
+
+/**
+ * Extracts the integer component from an order key.
+ */
+export function getIntegerPart(key: string): string {
+  if (!key || key.length < 2) return 'a0';
+  const prefix = key[0];
+  if (prefix >= 'a' && prefix <= 'z') {
+    const len = prefix.charCodeAt(0) - 97 + 1;
+    return key.slice(0, Math.min(key.length, 1 + len));
+  } else if (prefix >= 'A' && prefix <= 'Z') {
+    const len = 90 - prefix.charCodeAt(0) + 1;
+    return key.slice(0, Math.min(key.length, 1 + len));
+  }
+  return 'a0';
+}
+
+/**
+ * Computes a fractional midpoint suffix between suffixA and suffixB.
+ */
+function midpointSuffix(a: string, b: string | null): string {
+  let i = 0;
+  while (i < a.length && b !== null && i < b.length && a[i] === b[i]) {
+    i++;
+  }
+
+  const common = a.slice(0, i);
+  const charA = i < a.length ? a[i] : null;
+  const charB = b !== null && i < b.length ? b[i] : null;
+
+  const digitA = charA !== null ? BASE_62.indexOf(charA) : 0;
+  const digitB = charB !== null ? BASE_62.indexOf(charB) : BASE_62.length;
+
+  if (digitB - digitA > 1) {
+    const mid = Math.floor((digitA + digitB) / 2);
+    return common + BASE_62[mid];
+  }
+
+  if (charA !== null) {
+    const restA = a.slice(i + 1);
+    const restB = b !== null && i < b.length && charA === charB ? b.slice(i + 1) : null;
+    return common + charA + midpointSuffix(restA, restB);
+  }
+
+  if (b !== null && i < b.length) {
+    if (digitB === 0) {
+      const restB = b.slice(i + 1);
+      return common + '0' + midpointSuffix('', restB);
+    }
+  }
+
+  return common + 'V';
+}
+
+/**
+ * Generates a default initial order key for an index with optional spacing.
+ * E.g. index 0 -> "a0", index 1 (spacing 2) -> "a2", index 2 -> "a4"
+ */
+export function getInitialKey(index: number, spacing: number = 2): string {
+  return encodeInteger(Math.max(0, index) * Math.max(1, spacing));
+}
+
+/**
+ * Generates a single key strictly between keys `a` and `b` (a < key < b).
+ * Handles null/undefined for lower and upper bounds.
+ */
+export function generateKeyBetween(
+  a: string | null | undefined,
+  b: string | null | undefined
+): string {
+  const hasA = a !== null && a !== undefined && a !== '';
+  const hasB = b !== null && b !== undefined && b !== '';
+
+  if (!hasA && !hasB) {
+    return 'a0';
+  }
+
+  if (!hasA && hasB) {
+    const intB = getIntegerPart(b!);
+    if (intB === b) {
+      const valB = decodeInteger(intB);
+      return encodeInteger(valB - 1);
+    }
+    // If b has fractional suffix (e.g. "a0V"), integer part is already strictly smaller than b
+    return intB;
+  }
+
+  if (hasA && !hasB) {
+    const intA = getIntegerPart(a!);
+    const valA = decodeInteger(intA);
+    return encodeInteger(valA + 1);
+  }
+
+  // Both a and b are present
+  if (a! >= b!) {
+    // Graceful fallback for inverted or equal keys
+    return a! + 'V';
+  }
+
+  const intA = getIntegerPart(a!);
+  const intB = getIntegerPart(b!);
+
+  if (intA !== intB) {
+    const valA = decodeInteger(intA);
+    const valB = decodeInteger(intB);
+
+    if (valB - valA > 1) {
+      const midVal = Math.floor((valA + valB) / 2);
+      return encodeInteger(midVal);
+    }
+
+    if (valB - valA === 1) {
+      const suffixA = a!.slice(intA.length);
+      return intA + midpointSuffix(suffixA, null);
+    }
+  }
+
+  // Same integer part or fractional subdivision
+  const suffixA = a!.slice(intA.length);
+  const suffixB = b!.slice(intB.length);
+  return intA + midpointSuffix(suffixA, suffixB);
+}
+
+/**
+ * Generates `count` keys in strictly ascending order between keys `a` and `b`.
+ * Uses a balanced divide-and-conquer partition to guarantee even spacing.
+ */
+export function generateNKeysBetween(
+  a: string | null | undefined,
+  b: string | null | undefined,
+  count: number
+): string[] {
+  if (count <= 0) return [];
+  if (count === 1) return [generateKeyBetween(a, b)];
+
+  const result: string[] = new Array(count);
+
+  function fill(
+    leftKey: string | null | undefined,
+    rightKey: string | null | undefined,
+    startIdx: number,
+    endIdx: number
+  ) {
+    if (startIdx > endIdx) return;
+    const midIdx = Math.floor((startIdx + endIdx) / 2);
+    const midKey = generateKeyBetween(leftKey, rightKey);
+    result[midIdx] = midKey;
+    fill(leftKey, midKey, startIdx, midIdx - 1);
+    fill(midKey, rightKey, midIdx + 1, endIdx);
+  }
+
+  fill(a, b, 0, count - 1);
+  return result;
+}
+
+/**
+ * Standard comparator for fractional order indices.
+ * Uses strict code-point comparison matching Firestore, SQLite, and JavaScript array.sort().
+ */
+export function compareOrderIndices(
+  a: string | null | undefined,
+  b: string | null | undefined
+): number {
+  if (!a && !b) return 0;
+  if (!a) return 1;
+  if (!b) return -1;
+  return a < b ? -1 : a > b ? 1 : 0;
+}

package/src/utils/index.ts

@@ -2,4 +2,6 @@ export * from './status.js';
 export * from './key.js';
 export * from './workflow.js';
 export * from './mentions.js';
+export * from './fractional-index.js';
+
 

package/src/utils/key.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { generateProjectKey, validateProjectKey, formatTaskKey } from './key.js';
+import { generateProjectKey, validateProjectKey, formatTaskKey, isTempTaskId } from './key.js';
 
 describe('Project Key Utilities', () => {
   describe('generateProjectKey', () => {
@@ -52,4 +52,25 @@ describe('Project Key Utilities', () => {
       expect(formatTaskKey('', 10)).toBe('TASK-10');
     });
   });
+
+  describe('isTempTaskId', () => {
+    it('detects temp_ prefixed IDs', () => {
+      expect(isTempTaskId('temp_123456_abc')).toBe(true);
+      expect(isTempTaskId('#temp_123456_abc')).toBe(true);
+    });
+
+    it('detects temp- prefixed IDs', () => {
+      expect(isTempTaskId('temp-task-1')).toBe(true);
+      expect(isTempTaskId('#temp-task-1')).toBe(true);
+    });
+
+    it('returns false for permanent or invalid IDs', () => {
+      expect(isTempTaskId('task_123')).toBe(false);
+      expect(isTempTaskId('PROJ-1')).toBe(false);
+      expect(isTempTaskId(null)).toBe(false);
+      expect(isTempTaskId(undefined)).toBe(false);
+      expect(isTempTaskId('')).toBe(false);
+    });
+  });
 });
+

package/src/utils/key.ts

@@ -49,3 +49,14 @@ export function formatTaskKey(projectKey: string, taskNumber: number): string {
   const prefix = projectKey ? projectKey.toUpperCase() : 'TASK';
   return `${prefix}-${taskNumber}`;
 }
+
+/**
+ * Checks whether a given task ID represents a temporary/optimistic task
+ * (e.g. temp_1790... or temp-task-...) while it is actively being created.
+ */
+export function isTempTaskId(id?: string | null): boolean {
+  if (!id || typeof id !== 'string') return false;
+  const clean = id.trim().replace(/^#/, '');
+  return clean.startsWith('temp_') || clean.startsWith('temp-');
+}
+