@nijaru/tk 0.0.1 → 0.0.3

package/src/db/storage.ts

@@ -7,9 +7,11 @@ import {
   writeFileSync,
   realpathSync,
   lstatSync,
+  renameSync,
 } from "fs";
 import { join, resolve, basename } from "path";
 import { getTasksDir, getWorkingDir } from "../lib/root";
+import { isTaskOverdue } from "../lib/time";
 import type { Task, Config, Status, Priority, TaskWithMeta, LogEntry } from "../types";
 import { DEFAULT_CONFIG, taskId, parseId, generateRef } from "../types";
 
@@ -31,6 +33,22 @@ function getConfigPath(tasksDir: string): string {
   return join(tasksDir, "config.json");
 }
 
+/**
+ * Write a file atomically by writing to a temporary file and renaming it.
+ */
+function atomicWrite(path: string, content: string): void {
+  const tempPath = `${path}.tmp.${generateRef()}`;
+  try {
+    writeFileSync(tempPath, content);
+    renameSync(tempPath, path);
+  } catch (e) {
+    if (existsSync(tempPath)) {
+      unlinkSync(tempPath);
+    }
+    throw e;
+  }
+}
+
 function validatePathSafety(path: string, tasksDir: string): boolean {
   try {
     if (existsSync(path)) {
@@ -45,8 +63,50 @@ function validatePathSafety(path: string, tasksDir: string): boolean {
     }
     return true;
   } catch {
-    return true;
+    // Fail closed: deny access on any error
+    return false;
+  }
+}
+
+const STATUS_ORDER: Record<Status, number> = { active: 0, open: 1, done: 2 };
+
+/**
+ * Compare two tasks for sorting:
+ * 1. Status (active > open > done)
+ * 2. If active/open: overdue > priority (1-4, 0) > due date > created_at
+ * 3. If done: completed_at (newest first)
+ */
+export function compareTasks(a: Task, b: Task): number {
+  const sA = STATUS_ORDER[a.status] ?? 99;
+  const sB = STATUS_ORDER[b.status] ?? 99;
+  if (sA !== sB) return sA - sB;
+
+  if (a.status !== "done") {
+    // Overdue hoist
+    const overdueA = isTaskOverdue(a.due_date, a.status) ? 0 : 1;
+    const overdueB = isTaskOverdue(b.due_date, b.status) ? 0 : 1;
+    if (overdueA !== overdueB) return overdueA - overdueB;
+
+    // Priority (1-4, then 0/none)
+    const pA = a.priority === 0 ? 5 : a.priority;
+    const pB = b.priority === 0 ? 5 : b.priority;
+    if (pA !== pB) return pA - pB;
+
+    // Due date (soonest first, nulls last)
+    if (a.due_date !== b.due_date) {
+      if (!a.due_date) return 1;
+      if (!b.due_date) return -1;
+      return a.due_date.localeCompare(b.due_date);
+    }
+
+    // Created at (newest first)
+    return new Date(b.created_at).getTime() - new Date(a.created_at).getTime();
   }
+
+  // Done tasks: newest completion first
+  const timeA = a.completed_at ? new Date(a.completed_at).getTime() : 0;
+  const timeB = b.completed_at ? new Date(b.completed_at).getTime() : 0;
+  return timeB - timeA;
 }
 
 // --- Config Operations ---
@@ -68,7 +128,7 @@ export function getConfig(): Config {
 export function saveConfig(config: Config): void {
   const tasksDir = ensureTasksDir();
   const configPath = getConfigPath(tasksDir);
-  writeFileSync(configPath, JSON.stringify(config, null, 2));
+  atomicWrite(configPath, JSON.stringify(config, null, 2));
 }
 
 export function updateConfig(updates: Partial<Config>): Config {
@@ -153,12 +213,12 @@ export function renameProject(oldProject: string, newProject: string): RenameRes
       const newPath = getTaskPath(tasksDir, taskId(task));
 
       // Write to new path, delete old
-      writeFileSync(newPath, JSON.stringify(task, null, 2));
+      atomicWrite(newPath, JSON.stringify(task, null, 2));
       unlinkSync(oldPath);
     } else if (modified) {
       // Just update references in non-renamed task
       const path = getTaskPath(tasksDir, taskId(task));
-      writeFileSync(path, JSON.stringify(task, null, 2));
+      atomicWrite(path, JSON.stringify(task, null, 2));
     }
   }
 
@@ -197,14 +257,145 @@ function readTaskFile(path: string, tasksDir?: string): Task | null {
   }
   try {
     const text = readFileSync(path, "utf-8");
-    return JSON.parse(text);
+    const parsed = JSON.parse(text);
+    // Validate structure to avoid crashes on malformed data
+    if (!isValidTaskStructure(parsed)) return null;
+    return parsed;
   } catch {
     return null;
   }
 }
 
 function writeTaskFile(path: string, task: Task): void {
-  writeFileSync(path, JSON.stringify(task, null, 2));
+  atomicWrite(path, JSON.stringify(task, null, 2));
+}
+
+/**
+ * Validate that a parsed object has the minimum required Task structure.
+ * Returns true if valid, false otherwise.
+ */
+function isValidTaskStructure(obj: unknown): obj is Task {
+  if (!obj || typeof obj !== "object") return false;
+  const t = obj as Record<string, unknown>;
+  return (
+    typeof t.project === "string" &&
+    typeof t.ref === "string" &&
+    typeof t.title === "string" &&
+    typeof t.status === "string" &&
+    Array.isArray(t.blocked_by)
+  );
+}
+
+/**
+ * Remove references to specific IDs from a task's blocked_by and parent fields.
+ * Returns true if the task was modified.
+ */
+function removeRefsFromTask(task: Task, shouldRemove: (id: string) => boolean): boolean {
+  let modified = false;
+
+  const originalLen = task.blocked_by.length;
+  task.blocked_by = task.blocked_by.filter((id) => !shouldRemove(id));
+  if (task.blocked_by.length !== originalLen) {
+    modified = true;
+  }
+
+  if (task.parent && shouldRemove(task.parent)) {
+    task.parent = null;
+    modified = true;
+  }
+
+  return modified;
+}
+
+// --- Auto-cleanup ---
+
+export interface CleanupInfo {
+  orphanedBlockers: string[];
+  orphanedParent: string | null;
+  idMismatch: { was: string; fixed: string } | null;
+}
+
+/**
+ * Clean orphaned references from a task. Returns info about what was cleaned.
+ * Writes to disk if any changes were made.
+ */
+function cleanTaskOrphans(
+  task: Task,
+  path: string,
+  expectedId: string,
+  tasksDir: string,
+): CleanupInfo {
+  const cleanup: CleanupInfo = {
+    orphanedBlockers: [],
+    orphanedParent: null,
+    idMismatch: null,
+  };
+
+  let modified = false;
+
+  // Check ID mismatch (filename vs content)
+  const actualId = taskId(task);
+  if (actualId !== expectedId) {
+    const parsed = parseId(expectedId);
+    if (parsed) {
+      cleanup.idMismatch = { was: actualId, fixed: expectedId };
+      task.project = parsed.project;
+      task.ref = parsed.ref;
+      modified = true;
+    }
+  }
+
+  // Check orphaned blocked_by references
+  const validBlockers: string[] = [];
+  for (const blockerId of task.blocked_by) {
+    if (existsSync(getTaskPath(tasksDir, blockerId))) {
+      validBlockers.push(blockerId);
+    } else {
+      cleanup.orphanedBlockers.push(blockerId);
+      modified = true;
+    }
+  }
+  if (cleanup.orphanedBlockers.length > 0) {
+    task.blocked_by = validBlockers;
+  }
+
+  // Check orphaned parent reference
+  if (task.parent && !existsSync(getTaskPath(tasksDir, task.parent))) {
+    cleanup.orphanedParent = task.parent;
+    task.parent = null;
+    modified = true;
+  }
+
+  // Write back if modified
+  if (modified) {
+    task.updated_at = new Date().toISOString();
+    atomicWrite(path, JSON.stringify(task, null, 2));
+  }
+
+  return cleanup;
+}
+
+function hasCleanup(info: CleanupInfo): boolean {
+  return (
+    info.orphanedBlockers.length > 0 || info.orphanedParent !== null || info.idMismatch !== null
+  );
+}
+
+export function formatCleanupMessage(taskId: string, info: CleanupInfo): string {
+  const parts: string[] = [];
+
+  if (info.orphanedBlockers.length > 0) {
+    const s = info.orphanedBlockers.length === 1 ? "reference" : "references";
+    parts.push(`${info.orphanedBlockers.length} orphaned ${s}`);
+  }
+  if (info.orphanedParent) {
+    parts.push("orphaned parent");
+  }
+  if (info.idMismatch) {
+    parts.push(`ID mismatch (was ${info.idMismatch.was})`);
+  }
+
+  return `(cleaned ${parts.join(", ")} from ${taskId})`;
 }
 
 function writeTaskFileExclusive(path: string, task: Task): boolean {
@@ -295,6 +486,36 @@ export function validateParent(
   return { ok: true };
 }
 
+// --- Task Enrichment ---
+
+/**
+ * Enriches a Task with computed metadata.
+ * Can optionally take a status map for efficient bulk processing of blockers.
+ */
+export function enrichTask(task: Task, statusMap?: Map<string, Status>): TaskWithMeta {
+  const tasksDir = getTasksDir();
+  let blockedByIncomplete = false;
+
+  for (const blockerId of task.blocked_by) {
+    let status = statusMap?.get(blockerId);
+    if (status === undefined) {
+      status = readTaskFile(getTaskPath(tasksDir, blockerId), tasksDir)?.status;
+    }
+
+    if (status && status !== "done") {
+      blockedByIncomplete = true;
+      break;
+    }
+  }
+
+  return {
+    ...task,
+    id: taskId(task),
+    is_overdue: isTaskOverdue(task.due_date, task.status),
+    blocked_by_incomplete: blockedByIncomplete,
+  };
+}
+
 // --- Task CRUD ---
 
 export interface CreateTaskOptions {
@@ -343,7 +564,7 @@ export function createTask(options: CreateTaskOptions): Task & { id: string } {
 
     const path = getTaskPath(tasksDir, id);
     if (writeTaskFileExclusive(path, task)) {
-      return { ...task, id };
+      return enrichTask(task);
     }
     // Collision (extremely rare with 4 chars) - retry with new ref
   }
@@ -351,18 +572,12 @@ export function createTask(options: CreateTaskOptions): Task & { id: string } {
   throw new Error(`Failed to create task after ${maxRetries} attempts`);
 }
 
-export function getTask(id: string): (Task & { id: string }) | null {
-  const tasksDir = getTasksDir();
-  if (!existsSync(tasksDir)) return null;
-
-  const path = getTaskPath(tasksDir, id);
-  const task = readTaskFile(path, tasksDir);
-  if (!task) return null;
-
-  return { ...task, id: taskId(task) };
+export interface TaskResult {
+  task: TaskWithMeta;
+  cleanup: CleanupInfo | null;
 }
 
-export function getTaskWithMeta(id: string): TaskWithMeta | null {
+export function getTask(id: string): TaskResult | null {
   const tasksDir = getTasksDir();
   if (!existsSync(tasksDir)) return null;
 
@@ -370,40 +585,18 @@ export function getTaskWithMeta(id: string): TaskWithMeta | null {
   const task = readTaskFile(path, tasksDir);
   if (!task) return null;
 
-  // Check if any blockers are incomplete
-  let blockedByIncomplete = false;
-  for (const blockerId of task.blocked_by) {
-    const blockerTask = readTaskFile(getTaskPath(tasksDir, blockerId), tasksDir);
-    if (!blockerTask) continue;
-    if (blockerTask.status !== "done") {
-      blockedByIncomplete = true;
-      break;
-    }
-  }
-
-  // Check if overdue (due date is before today, not including today)
-  let isOverdue = false;
-  if (task.due_date && task.status !== "done") {
-    const today = new Date();
-    today.setHours(0, 0, 0, 0);
-    const parts = task.due_date.split("-").map(Number);
-    const year = parts[0];
-    const month = parts[1];
-    const day = parts[2];
-    if (year && month && day) {
-      const dueDate = new Date(year, month - 1, day);
-      isOverdue = dueDate < today;
-    }
-  }
+  // Auto-clean orphaned references
+  const cleanup = cleanTaskOrphans(task, path, id, tasksDir);
 
   return {
-    ...task,
-    id: taskId(task),
-    blocked_by_incomplete: blockedByIncomplete,
-    is_overdue: isOverdue,
+    task: enrichTask(task),
+    cleanup: hasCleanup(cleanup) ? cleanup : null,
   };
 }
 
+// Deprecated alias for getTask
+export const getTaskWithMeta = getTask;
+
 export interface ListOptions {
   status?: Status;
   priority?: Priority;
@@ -416,80 +609,63 @@ export interface ListOptions {
   limit?: number;
 }
 
-export function listTasks(options?: ListOptions): (Task & { id: string })[] {
+export function listTasks(options?: ListOptions): TaskWithMeta[] {
   const tasksDir = getTasksDir();
   if (!existsSync(tasksDir)) return [];
 
-  let tasks = getAllTasks(tasksDir);
-
-  // Apply filters
-  if (options?.status) {
-    tasks = tasks.filter((t) => t.status === options.status);
-  }
-  if (options?.priority !== undefined) {
-    tasks = tasks.filter((t) => t.priority === options.priority);
-  }
-  if (options?.project) {
-    tasks = tasks.filter((t) => t.project === options.project);
-  }
-  if (options?.label) {
-    tasks = tasks.filter((t) => t.labels.includes(options.label!));
-  }
-  if (options?.assignee) {
-    tasks = tasks.filter((t) => t.assignees.includes(options.assignee!));
-  }
-  if (options?.parent) {
-    tasks = tasks.filter((t) => t.parent === options.parent);
-  }
-  if (options?.roots) {
-    tasks = tasks.filter((t) => t.parent === null);
-  }
-  if (options?.overdue) {
-    const today = new Date();
-    today.setHours(0, 0, 0, 0);
-    tasks = tasks.filter((t) => {
-      if (!t.due_date || t.status === "done") return false;
-      const parts = t.due_date.split("-").map(Number);
-      const year = parts[0];
-      const month = parts[1];
-      const day = parts[2];
-      if (!year || !month || !day) return false;
-      const dueDate = new Date(year, month - 1, day);
-      return dueDate < today;
-    });
+  const allTasks = getAllTasks(tasksDir);
+  // Build status map from all tasks once for efficient blocker lookups during enrichment
+  const statusMap = new Map<string, Status>(allTasks.map((t) => [taskId(t), t.status]));
+
+  let tasks = allTasks;
+
+  // Apply filters declaratively
+  if (options) {
+    const filters: ((t: Task) => boolean)[] = [];
+
+    if (options.status) filters.push((t) => t.status === options.status);
+    if (options.priority !== undefined) filters.push((t) => t.priority === options.priority);
+    if (options.project) filters.push((t) => t.project === options.project);
+    if (options.label) filters.push((t) => t.labels.includes(options.label!));
+    if (options.assignee) filters.push((t) => t.assignees.includes(options.assignee!));
+    if (options.parent) filters.push((t) => t.parent === options.parent);
+    if (options.roots) filters.push((t) => t.parent === null);
+    if (options.overdue) filters.push((t) => isTaskOverdue(t.due_date, t.status));
+
+    if (filters.length > 0) {
+      tasks = tasks.filter((t) => filters.every((f) => f(t)));
+    }
   }
 
-  // Sort by priority (lower = more urgent), then created_at (newer first)
-  tasks.sort((a, b) => {
-    if (a.priority !== b.priority) return a.priority - b.priority;
-    return new Date(b.created_at).getTime() - new Date(a.created_at).getTime();
-  });
+  tasks.sort(compareTasks);
 
   if (options?.limit) {
     tasks = tasks.slice(0, options.limit);
   }
 
-  return tasks.map((t) => ({ ...t, id: taskId(t) }));
+  return tasks.map((t) => enrichTask(t, statusMap));
 }
 
-export function listReadyTasks(): (Task & { id: string })[] {
+export function listReadyTasks(): TaskWithMeta[] {
   const tasksDir = getTasksDir();
   if (!existsSync(tasksDir)) return [];
 
-  const openTasks = listTasks({ status: "open" });
-
-  const readyTasks = openTasks.filter((task) => {
-    for (const blockerId of task.blocked_by) {
-      const blockerTask = readTaskFile(getTaskPath(tasksDir, blockerId), tasksDir);
-      if (!blockerTask) continue;
-      if (blockerTask.status !== "done") {
-        return false;
+  const allTasks = getAllTasks(tasksDir);
+  const statusMap = new Map<string, Status>(allTasks.map((t) => [taskId(t), t.status]));
+
+  const readyTasks = allTasks
+    .filter((task) => task.status === "active" || task.status === "open")
+    .filter((task) => {
+      for (const blockerId of task.blocked_by) {
+        const blockerStatus = statusMap.get(blockerId);
+        if (blockerStatus && blockerStatus !== "done") return false;
       }
-    }
-    return true;
-  });
+      return true;
+    });
+
+  readyTasks.sort(compareTasks);
 
-  return readyTasks;
+  return readyTasks.map((t) => enrichTask(t, statusMap));
 }
 
 export function updateTaskStatus(id: string, status: Status): (Task & { id: string }) | null {
@@ -504,7 +680,7 @@ export function updateTaskStatus(id: string, status: Status): (Task & { id: stri
   task.completed_at = status === "done" ? now : null;
 
   writeTaskFile(path, task);
-  return { ...task, id: taskId(task) };
+  return enrichTask(task);
 }
 
 export interface UpdateTaskOptions {
@@ -536,7 +712,7 @@ export function updateTask(id: string, updates: UpdateTaskOptions): (Task & { id
   task.updated_at = now;
 
   writeTaskFile(path, task);
-  return { ...task, id: taskId(task) };
+  return enrichTask(task);
 }
 
 export function deleteTask(id: string): boolean {
@@ -546,12 +722,12 @@ export function deleteTask(id: string): boolean {
 
   unlinkSync(path);
 
-  // Remove this task from all blocked_by arrays
+  // Remove this task from all blocked_by arrays and parent references
   const allTasks = getAllTasks(tasksDir);
   for (const task of allTasks) {
-    if (task.blocked_by.includes(id)) {
-      task.blocked_by = task.blocked_by.filter((b) => b !== id);
-      writeTaskFile(getTaskPath(tasksDir, taskId(task)), task);
+    const modified = removeRefsFromTask(task, (ref) => ref === id);
+    if (modified) {
+      atomicWrite(getTaskPath(tasksDir, taskId(task)), JSON.stringify(task, null, 2));
     }
   }
 
@@ -560,8 +736,7 @@ export function deleteTask(id: string): boolean {
 
 export interface CleanOptions {
   olderThanMs?: number;
-  status?: Status;
-  all?: boolean;
+  force?: boolean; // ignore age threshold
 }
 
 export function cleanTasks(options: CleanOptions): number {
@@ -569,16 +744,15 @@ export function cleanTasks(options: CleanOptions): number {
   if (!existsSync(tasksDir)) return 0;
 
   const tasks = getAllTasks(tasksDir);
-  const cutoff = options.olderThanMs ? Date.now() - options.olderThanMs : 0;
+  // Clamp cutoff to prevent negative values from very large olderThanMs
+  const cutoff = options.olderThanMs ? Math.max(0, Date.now() - options.olderThanMs) : 0;
 
   const toDelete: string[] = [];
 
   for (const task of tasks) {
-    const validStatus = options.status ? task.status === options.status : task.status === "done";
+    if (task.status !== "done") continue;
 
-    if (!validStatus) continue;
-
-    if (!options.all && cutoff > 0) {
+    if (!options.force && cutoff > 0) {
       if (!task.completed_at) continue;
       if (new Date(task.completed_at).getTime() >= cutoff) continue;
     }
@@ -590,14 +764,14 @@ export function cleanTasks(options: CleanOptions): number {
     unlinkSync(getTaskPath(tasksDir, id));
   }
 
-  // Clean up dangling blocked_by references
+  // Clean up dangling blocked_by and parent references
   if (toDelete.length > 0) {
+    const toDeleteSet = new Set(toDelete);
     const remaining = getAllTasks(tasksDir);
     for (const task of remaining) {
-      const original = task.blocked_by.length;
-      task.blocked_by = task.blocked_by.filter((b) => !toDelete.includes(b));
-      if (task.blocked_by.length !== original) {
-        writeTaskFile(getTaskPath(tasksDir, taskId(task)), task);
+      const modified = removeRefsFromTask(task, (id) => toDeleteSet.has(id));
+      if (modified) {
+        atomicWrite(getTaskPath(tasksDir, taskId(task)), JSON.stringify(task, null, 2));
       }
     }
   }
@@ -623,18 +797,11 @@ export function addLogEntry(taskIdStr: string, message: string): LogEntry {
 
   task.logs.push(entry);
   task.updated_at = now;
-  writeTaskFile(path, task);
+  atomicWrite(path, JSON.stringify(task, null, 2));
 
   return entry;
 }
 
-export function getLogEntries(taskIdStr: string): LogEntry[] {
-  const tasksDir = getTasksDir();
-  const path = getTaskPath(tasksDir, taskIdStr);
-  const task = readTaskFile(path, tasksDir);
-  return task?.logs ?? [];
-}
-
 // --- Block Operations ---
 
 export function addBlock(taskIdStr: string, blockedBy: string): { ok: boolean; error?: string } {
@@ -661,7 +828,7 @@ export function addBlock(taskIdStr: string, blockedBy: string): { ok: boolean; e
 
   task.blocked_by.push(blockedBy);
   task.updated_at = new Date().toISOString();
-  writeTaskFile(taskPath, task);
+  atomicWrite(taskPath, JSON.stringify(task, null, 2));
 
   return { ok: true };
 }
@@ -677,30 +844,13 @@ export function removeBlock(taskIdStr: string, blockedBy: string): boolean {
 
   task.blocked_by.splice(idx, 1);
   task.updated_at = new Date().toISOString();
-  writeTaskFile(taskPath, task);
+  atomicWrite(taskPath, JSON.stringify(task, null, 2));
 
   return true;
 }
 
-export function getBlockers(taskIdStr: string): string[] {
-  const tasksDir = getTasksDir();
-  const task = readTaskFile(getTaskPath(tasksDir, taskIdStr), tasksDir);
-  return task?.blocked_by ?? [];
-}
-
-export function getBlocking(taskIdStr: string): string[] {
-  const tasksDir = getTasksDir();
-  const allTasks = getAllTasks(tasksDir);
-  return allTasks.filter((t) => t.blocked_by.includes(taskIdStr)).map((t) => taskId(t));
-}
-
 // --- Utility ---
 
-export function tasksExist(): boolean {
-  const tasksDir = getTasksDir();
-  return existsSync(tasksDir);
-}
-
 export function initTasks(project?: string): string {
   const tasksDir = ensureTasksDir();
   const config = getConfig();
@@ -765,13 +915,100 @@ export function resolveId(input: string): string | null {
     return matches[0];
   }
 
-  // No match or ambiguous
   return null;
 }
 
+export function findMatchingIds(input: string): string[] {
+  const tasksDir = getTasksDir();
+  if (!existsSync(tasksDir)) return [];
+
+  const inputLower = input.toLowerCase();
+  const files = readdirSync(tasksDir);
+  const matches: string[] = [];
+
+  for (const file of files) {
+    if (!file.endsWith(".json") || file === "config.json") continue;
+    const id = file.slice(0, -5);
+    if (!parseId(id)) continue;
+    const ref = id.split("-")[1] ?? "";
+    if (id.startsWith(inputLower) || ref.startsWith(inputLower)) {
+      matches.push(id);
+    }
+  }
+
+  return matches;
+}
+
+// --- Health Check ---
+
+export interface CheckResult {
+  totalTasks: number;
+  cleaned: { task: string; info: CleanupInfo }[];
+  unfixable: { file: string; error: string }[];
+}
+
 /**
- * Validate that an ID is in the correct format.
+ * Run health check on all tasks.
+ * Auto-fixes orphaned refs/ID mismatches and reports unfixable issues.
  */
-export function isValidId(id: string): boolean {
-  return parseId(id) !== null;
+export function checkTasks(): CheckResult {
+  const tasksDir = getTasksDir();
+  const result: CheckResult = {
+    totalTasks: 0,
+    cleaned: [],
+    unfixable: [],
+  };
+
+  if (!existsSync(tasksDir)) return result;
+
+  const files = readdirSync(tasksDir).filter((f) => f.endsWith(".json") && f !== "config.json");
+
+  for (const file of files) {
+    const expectedId = file.slice(0, -5);
+
+    // Warn about unexpected files (non-task JSON)
+    if (!parseId(expectedId)) {
+      result.unfixable.push({
+        file,
+        error: "Invalid task ID format in filename",
+      });
+      continue;
+    }
+
+    const path = join(tasksDir, file);
+
+    // Try to read and parse
+    let parsed: unknown;
+    try {
+      const text = readFileSync(path, "utf-8");
+      parsed = JSON.parse(text);
+    } catch (e) {
+      // Corrupted JSON - unfixable
+      result.unfixable.push({
+        file,
+        error: e instanceof Error ? e.message : "Invalid JSON",
+      });
+      continue;
+    }
+
+    // Validate task structure
+    if (!isValidTaskStructure(parsed)) {
+      result.unfixable.push({
+        file,
+        error: "Invalid task structure (missing required fields)",
+      });
+      continue;
+    }
+
+    const task = parsed;
+    result.totalTasks++;
+
+    // Auto-clean (same as getTask does)
+    const cleanup = cleanTaskOrphans(task, path, expectedId, tasksDir);
+    if (hasCleanup(cleanup)) {
+      result.cleaned.push({ task: expectedId, info: cleanup });
+    }
+  }
+
+  return result;
 }