@zeliper/zscode-mcp-server 1.0.0 → 1.0.2

package/dist/state/manager.js

@@ -1,23 +1,29 @@
-import { readFile, writeFile, access, rm, cp } from "fs/promises";
+import { readFile, access, rm, cp } from "fs/promises";
 import { join, dirname } from "path";
 import { constants } from "fs";
 import { StateSchema } from "./schema.js";
-import { normalizePath, toPosixPath, ensureDir } from "../utils/paths.js";
+import { STATE_VERSION, } from "./types.js";
+import { normalizePath, toPosixPath, ensureDir, isPathSafe, isValidId, atomicWriteFile, generateSecureId, } from "../utils/paths.js";
+import { ProjectNotInitializedError, PlanNotFoundError, PlanInvalidStateError, StagingNotFoundError, StagingOrderError, StagingPlanMismatchError, StagingInvalidStateError, TaskNotFoundError, TaskInvalidStateError, TaskStateTransitionError, CircularDependencyError, MemoryNotFoundError, PathTraversalError, InvalidIdError, } from "../errors/index.js";
+// ============ Constants ============
+const MAX_HISTORY_ENTRIES = 1000;
+// Valid task state transitions
+const VALID_TASK_TRANSITIONS = {
+    pending: ["in_progress", "blocked", "cancelled"],
+    in_progress: ["done", "blocked", "cancelled"],
+    blocked: ["in_progress", "cancelled"],
+    done: [], // Terminal state - no transitions allowed
+    cancelled: [], // Terminal state - no transitions allowed
+};
 // ============ ID Generator ============
-function generateRandomId(length) {
-    const chars = "abcdefghijklmnopqrstuvwxyz0123456789";
-    let result = "";
-    for (let i = 0; i < length; i++) {
-        result += chars.charAt(Math.floor(Math.random() * chars.length));
-    }
-    return result;
-}
+// Uses cryptographically secure random generation
 const idGenerator = {
-    generatePlanId: () => `plan-${generateRandomId(8)}`,
-    generateStagingId: () => `staging-${generateRandomId(4)}`,
-    generateTaskId: () => `task-${generateRandomId(8)}`,
-    generateHistoryId: () => `hist-${Date.now()}-${generateRandomId(4)}`,
-    generateDecisionId: () => `dec-${Date.now()}-${generateRandomId(4)}`,
+    generatePlanId: () => `plan-${generateSecureId(8)}`,
+    generateStagingId: () => `staging-${generateSecureId(4)}`,
+    generateTaskId: () => `task-${generateSecureId(8)}`,
+    generateHistoryId: () => `hist-${Date.now()}-${generateSecureId(4)}`,
+    generateDecisionId: () => `dec-${Date.now()}-${generateSecureId(4)}`,
+    generateMemoryId: () => `mem-${generateSecureId(8)}`,
 };
 // ============ StateManager Class ============
 export class StateManager {
@@ -64,8 +70,47 @@ export class StateManager {
         if (!this.state) {
             throw new Error("No state to save");
         }
-        await ensureDir(dirname(this.stateFilePath));
-        await writeFile(this.stateFilePath, JSON.stringify(this.state, null, 2), "utf-8");
+        // Use atomic write to prevent data corruption
+        await atomicWriteFile(this.stateFilePath, JSON.stringify(this.state, null, 2));
+    }
+    // ============ Validation Helpers ============
+    ensureInitialized() {
+        if (!this.state) {
+            throw new ProjectNotInitializedError();
+        }
+        return this.state;
+    }
+    requirePlan(planId) {
+        const state = this.ensureInitialized();
+        const plan = state.plans[planId];
+        if (!plan) {
+            throw new PlanNotFoundError(planId);
+        }
+        return plan;
+    }
+    requireStaging(stagingId) {
+        const state = this.ensureInitialized();
+        const staging = state.stagings[stagingId];
+        if (!staging) {
+            throw new StagingNotFoundError(stagingId);
+        }
+        return staging;
+    }
+    requireTask(taskId) {
+        const state = this.ensureInitialized();
+        const task = state.tasks[taskId];
+        if (!task) {
+            throw new TaskNotFoundError(taskId);
+        }
+        return task;
+    }
+    requireMemory(memoryId) {
+        const state = this.ensureInitialized();
+        const memory = state.context.memories.find(m => m.id === memoryId);
+        if (!memory) {
+            throw new MemoryNotFoundError(memoryId);
+        }
+        return memory;
     }
     // ============ Getters ============
     getState() {
@@ -120,7 +165,7 @@ export class StateManager {
             updatedAt: now,
         };
         this.state = {
-            version: "2.0.0",
+            version: STATE_VERSION,
             project,
             plans: {},
             stagings: {},
@@ -130,6 +175,7 @@ export class StateManager {
                 lastUpdated: now,
                 activeFiles: [],
                 decisions: [],
+                memories: [],
             },
         };
         await this.addHistory("project_initialized", { projectName: name });
@@ -138,9 +184,7 @@ export class StateManager {
     }
     // ============ Plan Operations ============
     async createPlan(title, description, stagingConfigs) {
-        if (!this.state) {
-            throw new Error("Project not initialized");
-        }
+        const state = this.ensureInitialized();
         const now = new Date().toISOString();
         const planId = idGenerator.generatePlanId();
         const artifactsRoot = toPosixPath(join(".claude", "plans", planId, "artifacts"));
@@ -173,7 +217,7 @@ export class StateManager {
                 };
                 tasks.push(task);
                 taskIds.push(taskId);
-                this.state.tasks[taskId] = task;
+                state.tasks[taskId] = task;
             }
             // Resolve task dependencies within the same staging
             for (let i = 0; i < tasks.length; i++) {
@@ -197,7 +241,7 @@ export class StateManager {
                 artifacts_path: artifactsPath,
                 createdAt: now,
             };
-            this.state.stagings[stagingId] = staging;
+            state.stagings[stagingId] = staging;
             stagingIds.push(stagingId);
         }
         // Create plan
@@ -211,17 +255,13 @@ export class StateManager {
             createdAt: now,
             updatedAt: now,
         };
-        this.state.plans[planId] = plan;
+        state.plans[planId] = plan;
         await this.addHistory("plan_created", { planId, title, stagingCount: stagingIds.length });
         await this.save();
         return plan;
     }
     async updatePlanStatus(planId, status) {
-        if (!this.state)
-            throw new Error("Project not initialized");
-        const plan = this.getPlan(planId);
-        if (!plan)
-            throw new Error(`Plan not found: ${planId}`);
+        const plan = this.requirePlan(planId);
         plan.status = status;
         plan.updatedAt = new Date().toISOString();
         if (status === "completed") {
@@ -234,22 +274,17 @@ export class StateManager {
     }
     // ============ Staging Operations ============
     async startStaging(planId, stagingId) {
-        if (!this.state)
-            throw new Error("Project not initialized");
-        const plan = this.getPlan(planId);
-        if (!plan)
-            throw new Error(`Plan not found: ${planId}`);
-        const staging = this.getStaging(stagingId);
-        if (!staging)
-            throw new Error(`Staging not found: ${stagingId}`);
+        const state = this.ensureInitialized();
+        const plan = this.requirePlan(planId);
+        const staging = this.requireStaging(stagingId);
         if (staging.planId !== planId) {
-            throw new Error(`Staging ${stagingId} does not belong to plan ${planId}`);
+            throw new StagingPlanMismatchError(stagingId, planId, staging.planId);
         }
         // Check if previous staging is completed
         if (staging.order > 0) {
             const prevStaging = this.getStagingByOrder(planId, staging.order - 1);
             if (prevStaging && prevStaging.status !== "completed") {
-                throw new Error(`Cannot start staging: previous staging ${prevStaging.id} is not completed`);
+                throw new StagingOrderError(stagingId, prevStaging.id);
             }
         }
         const now = new Date().toISOString();
@@ -258,9 +293,9 @@ export class StateManager {
         plan.currentStagingId = stagingId;
         plan.status = "active";
         plan.updatedAt = now;
-        this.state.context.currentPlanId = planId;
-        this.state.context.currentStagingId = stagingId;
-        this.state.context.lastUpdated = now;
+        state.context.currentPlanId = planId;
+        state.context.currentStagingId = stagingId;
+        state.context.lastUpdated = now;
         // Create artifacts directory
         const artifactsDir = normalizePath(join(this.projectRoot, staging.artifacts_path));
         await ensureDir(artifactsDir);
@@ -268,12 +303,9 @@ export class StateManager {
         await this.save();
         return staging;
     }
-    async completestaging(stagingId) {
-        if (!this.state)
-            throw new Error("Project not initialized");
-        const staging = this.getStaging(stagingId);
-        if (!staging)
-            throw new Error(`Staging not found: ${stagingId}`);
+    async completeStaging(stagingId) {
+        const state = this.ensureInitialized();
+        const staging = this.requireStaging(stagingId);
         const now = new Date().toISOString();
         staging.status = "completed";
         staging.completedAt = now;
@@ -288,8 +320,8 @@ export class StateManager {
             if (allCompleted) {
                 plan.status = "completed";
                 plan.completedAt = now;
-                this.state.context.currentPlanId = undefined;
-                this.state.context.currentStagingId = undefined;
+                state.context.currentPlanId = undefined;
+                state.context.currentStagingId = undefined;
             }
         }
         await this.addHistory("staging_completed", { stagingId, stagingName: staging.name });
@@ -297,11 +329,12 @@ export class StateManager {
     }
     // ============ Task Operations ============
     async updateTaskStatus(taskId, status, notes) {
-        if (!this.state)
-            throw new Error("Project not initialized");
-        const task = this.getTask(taskId);
-        if (!task)
-            throw new Error(`Task not found: ${taskId}`);
+        const task = this.requireTask(taskId);
+        // Validate state transition
+        const allowedTransitions = VALID_TASK_TRANSITIONS[task.status];
+        if (!allowedTransitions.includes(status)) {
+            throw new TaskStateTransitionError(taskId, task.status, status, allowedTransitions);
+        }
         const now = new Date().toISOString();
         task.status = status;
         task.updatedAt = now;
@@ -323,7 +356,7 @@ export class StateManager {
                     return t?.status === "done";
                 });
                 if (allTasksDone) {
-                    await this.completestaging(staging.id);
+                    await this.completeStaging(staging.id);
                 }
             }
         }
@@ -333,19 +366,24 @@ export class StateManager {
         await this.save();
     }
     async saveTaskOutput(taskId, output) {
-        if (!this.state)
-            throw new Error("Project not initialized");
-        const task = this.getTask(taskId);
-        if (!task)
-            throw new Error(`Task not found: ${taskId}`);
+        // Validate taskId to prevent path traversal
+        if (!isValidId(taskId)) {
+            throw new InvalidIdError(taskId, "task");
+        }
+        const task = this.requireTask(taskId);
         task.output = output;
         task.updatedAt = new Date().toISOString();
         // Save output to artifacts file
         const staging = this.getStaging(task.stagingId);
         if (staging) {
+            const claudeDir = normalizePath(join(this.projectRoot, ".claude"));
             const outputPath = normalizePath(join(this.projectRoot, staging.artifacts_path, `${taskId}-output.json`));
-            await ensureDir(dirname(outputPath));
-            await writeFile(outputPath, JSON.stringify(output, null, 2), "utf-8");
+            // Verify path is within the .claude directory (path traversal protection)
+            if (!isPathSafe(claudeDir, outputPath)) {
+                throw new PathTraversalError(outputPath);
+            }
+            // Use atomic write to prevent data corruption
+            await atomicWriteFile(outputPath, JSON.stringify(output, null, 2));
         }
         await this.save();
     }
@@ -369,17 +407,23 @@ export class StateManager {
     }
     // ============ Archive Operations ============
     async archivePlan(planId, reason) {
-        if (!this.state)
-            throw new Error("Project not initialized");
-        const plan = this.getPlan(planId);
-        if (!plan)
-            throw new Error(`Plan not found: ${planId}`);
+        const state = this.ensureInitialized();
+        // Validate planId to prevent path traversal
+        if (!isValidId(planId)) {
+            throw new InvalidIdError(planId, "plan");
+        }
+        const plan = this.requirePlan(planId);
         if (plan.status !== "completed" && plan.status !== "cancelled") {
-            throw new Error(`Cannot archive plan in ${plan.status} status. Only completed or cancelled plans can be archived.`);
+            throw new PlanInvalidStateError(planId, plan.status, ["completed", "cancelled"]);
         }
         const now = new Date().toISOString();
+        const claudeDir = normalizePath(join(this.projectRoot, ".claude"));
         const sourcePath = normalizePath(join(this.projectRoot, ".claude", "plans", planId));
         const archivePath = normalizePath(join(this.projectRoot, ".claude", "archive", planId));
+        // Verify paths are within the .claude directory (path traversal protection)
+        if (!isPathSafe(claudeDir, sourcePath) || !isPathSafe(claudeDir, archivePath)) {
+            throw new PathTraversalError(planId);
+        }
         // Move plan directory to archive
         try {
             await ensureDir(dirname(archivePath));
@@ -394,23 +438,56 @@ export class StateManager {
         plan.archivedAt = now;
         plan.updatedAt = now;
         // Clear current context if this was the active plan
-        if (this.state.context.currentPlanId === planId) {
-            this.state.context.currentPlanId = undefined;
-            this.state.context.currentStagingId = undefined;
+        if (state.context.currentPlanId === planId) {
+            state.context.currentPlanId = undefined;
+            state.context.currentStagingId = undefined;
         }
         await this.addHistory("plan_archived", { planId, title: plan.title, reason });
         await this.save();
         return toPosixPath(join(".claude", "archive", planId));
     }
+    async unarchivePlan(planId) {
+        this.ensureInitialized();
+        // Validate planId to prevent path traversal
+        if (!isValidId(planId)) {
+            throw new InvalidIdError(planId, "plan");
+        }
+        const plan = this.requirePlan(planId);
+        if (plan.status !== "archived") {
+            throw new PlanInvalidStateError(planId, plan.status, ["archived"]);
+        }
+        const now = new Date().toISOString();
+        const claudeDir = normalizePath(join(this.projectRoot, ".claude"));
+        const archivePath = normalizePath(join(this.projectRoot, ".claude", "archive", planId));
+        const restorePath = normalizePath(join(this.projectRoot, ".claude", "plans", planId));
+        // Verify paths are within the .claude directory (path traversal protection)
+        if (!isPathSafe(claudeDir, archivePath) || !isPathSafe(claudeDir, restorePath)) {
+            throw new PathTraversalError(planId);
+        }
+        // Move plan directory back from archive
+        try {
+            await ensureDir(dirname(restorePath));
+            await cp(archivePath, restorePath, { recursive: true });
+            await rm(archivePath, { recursive: true, force: true });
+        }
+        catch (error) {
+            // Directory might not exist if no artifacts were created
+            console.error(`Unarchive directory operation failed: ${error}`);
+        }
+        // Restore plan to completed status (since it was completed before archiving)
+        plan.status = "completed";
+        plan.archivedAt = undefined;
+        plan.updatedAt = now;
+        await this.addHistory("plan_unarchived", { planId, title: plan.title });
+        await this.save();
+        return { plan, restoredPath: toPosixPath(join(".claude", "plans", planId)) };
+    }
     // ============ Cancel Operations ============
     async cancelPlan(planId, reason) {
-        if (!this.state)
-            throw new Error("Project not initialized");
-        const plan = this.getPlan(planId);
-        if (!plan)
-            throw new Error(`Plan not found: ${planId}`);
+        const state = this.ensureInitialized();
+        const plan = this.requirePlan(planId);
         if (plan.status === "archived" || plan.status === "cancelled") {
-            throw new Error(`Plan is already ${plan.status}`);
+            throw new PlanInvalidStateError(planId, plan.status, ["draft", "active", "completed"]);
         }
         const now = new Date().toISOString();
         let affectedStagings = 0;
@@ -435,9 +512,9 @@ export class StateManager {
         plan.status = "cancelled";
         plan.updatedAt = now;
         // Clear current context if this was the active plan
-        if (this.state.context.currentPlanId === planId) {
-            this.state.context.currentPlanId = undefined;
-            this.state.context.currentStagingId = undefined;
+        if (state.context.currentPlanId === planId) {
+            state.context.currentPlanId = undefined;
+            state.context.currentStagingId = undefined;
         }
         await this.addHistory("plan_cancelled", { planId, title: plan.title, reason, affectedStagings, affectedTasks });
         await this.save();
@@ -455,10 +532,14 @@ export class StateManager {
         };
         this.state.history.push(entry);
         this.state.context.lastUpdated = entry.timestamp;
+        // Enforce history size limit - remove oldest entries if exceeded
+        if (this.state.history.length > MAX_HISTORY_ENTRIES) {
+            const excess = this.state.history.length - MAX_HISTORY_ENTRIES;
+            this.state.history.splice(0, excess);
+        }
     }
     async addDecision(title, decision, rationale, relatedPlanId, relatedStagingId) {
-        if (!this.state)
-            throw new Error("Project not initialized");
+        const state = this.ensureInitialized();
         const now = new Date().toISOString();
         const decisionEntry = {
             id: idGenerator.generateDecisionId(),
@@ -469,11 +550,105 @@ export class StateManager {
             relatedStagingId,
             timestamp: now,
         };
-        this.state.context.decisions.push(decisionEntry);
+        state.context.decisions.push(decisionEntry);
         await this.addHistory("decision_added", { decisionId: decisionEntry.id, title });
         await this.save();
         return decisionEntry;
     }
+    // ============ Memory Operations ============
+    async addMemory(category, title, content, tags, priority) {
+        const state = this.ensureInitialized();
+        const now = new Date().toISOString();
+        const memory = {
+            id: idGenerator.generateMemoryId(),
+            category,
+            title,
+            content,
+            tags: tags ?? [],
+            priority: priority ?? 50,
+            enabled: true,
+            createdAt: now,
+            updatedAt: now,
+        };
+        state.context.memories.push(memory);
+        await this.addHistory("memory_added", { memoryId: memory.id, title, category });
+        await this.save();
+        return memory;
+    }
+    listMemories(category, tags, enabledOnly = true) {
+        if (!this.state)
+            return [];
+        let memories = this.state.context.memories;
+        if (enabledOnly) {
+            memories = memories.filter(m => m.enabled);
+        }
+        if (category) {
+            memories = memories.filter(m => m.category === category);
+        }
+        if (tags && tags.length > 0) {
+            memories = memories.filter(m => tags.some(tag => m.tags.includes(tag)));
+        }
+        // Sort by priority (descending)
+        return memories.sort((a, b) => b.priority - a.priority);
+    }
+    getMemoriesForContext(context) {
+        if (!this.state)
+            return [];
+        const enabledMemories = this.state.context.memories.filter(m => m.enabled);
+        let result;
+        if (context === "all") {
+            result = enabledMemories;
+        }
+        else if (context === "general") {
+            result = enabledMemories.filter(m => m.category === "general");
+        }
+        else {
+            // Return general + context-specific memories
+            result = enabledMemories.filter(m => m.category === "general" || m.category === context);
+        }
+        // Sort by priority (descending)
+        return result.sort((a, b) => b.priority - a.priority);
+    }
+    async updateMemory(memoryId, updates) {
+        const memory = this.requireMemory(memoryId);
+        const now = new Date().toISOString();
+        if (updates.title !== undefined)
+            memory.title = updates.title;
+        if (updates.content !== undefined)
+            memory.content = updates.content;
+        if (updates.category !== undefined)
+            memory.category = updates.category;
+        if (updates.tags !== undefined)
+            memory.tags = updates.tags;
+        if (updates.priority !== undefined)
+            memory.priority = updates.priority;
+        if (updates.enabled !== undefined)
+            memory.enabled = updates.enabled;
+        memory.updatedAt = now;
+        await this.addHistory("memory_updated", { memoryId, updates });
+        await this.save();
+        return memory;
+    }
+    async removeMemory(memoryId) {
+        const state = this.ensureInitialized();
+        const memory = this.requireMemory(memoryId);
+        const index = state.context.memories.findIndex(m => m.id === memoryId);
+        state.context.memories.splice(index, 1);
+        await this.addHistory("memory_removed", { memoryId, title: memory.title });
+        await this.save();
+    }
+    getMemory(memoryId) {
+        return this.state?.context.memories.find(m => m.id === memoryId);
+    }
+    getCategories() {
+        if (!this.state)
+            return [];
+        const categories = new Set();
+        for (const memory of this.state.context.memories) {
+            categories.add(memory.category);
+        }
+        return Array.from(categories).sort();
+    }
     // ============ Session Operations ============
     async startSession() {
         await this.addHistory("session_started", {});
@@ -488,6 +663,227 @@ export class StateManager {
         await this.addHistory("session_ended", { summary });
         await this.save();
     }
+    // ============ Modify Operations ============
+    async updatePlan(planId, updates) {
+        const plan = this.requirePlan(planId);
+        if (plan.status === "archived" || plan.status === "cancelled") {
+            throw new PlanInvalidStateError(planId, plan.status, ["draft", "active", "completed"]);
+        }
+        const now = new Date().toISOString();
+        if (updates.title !== undefined)
+            plan.title = updates.title;
+        if (updates.description !== undefined)
+            plan.description = updates.description;
+        plan.updatedAt = now;
+        await this.addHistory("plan_updated", { planId, updates });
+        await this.save();
+        return plan;
+    }
+    async updateStaging(stagingId, updates) {
+        const staging = this.requireStaging(stagingId);
+        if (staging.status === "completed" || staging.status === "cancelled") {
+            throw new StagingInvalidStateError(stagingId, staging.status, ["pending", "in_progress"]);
+        }
+        if (updates.name !== undefined)
+            staging.name = updates.name;
+        if (updates.description !== undefined)
+            staging.description = updates.description;
+        if (updates.execution_type !== undefined)
+            staging.execution_type = updates.execution_type;
+        await this.addHistory("staging_updated", { stagingId, updates });
+        await this.save();
+        return staging;
+    }
+    async addStaging(planId, config) {
+        const state = this.ensureInitialized();
+        const plan = this.requirePlan(planId);
+        if (plan.status === "archived" || plan.status === "cancelled" || plan.status === "completed") {
+            throw new PlanInvalidStateError(planId, plan.status, ["draft", "active"]);
+        }
+        const now = new Date().toISOString();
+        const stagingId = idGenerator.generateStagingId();
+        const insertAt = config.insertAt ?? plan.stagings.length;
+        // Reorder existing stagings
+        const stagings = this.getStagingsByPlan(planId);
+        for (const s of stagings) {
+            if (s.order >= insertAt) {
+                s.order++;
+            }
+        }
+        const artifactsPath = toPosixPath(join(plan.artifacts_root, stagingId));
+        const staging = {
+            id: stagingId,
+            planId,
+            name: config.name,
+            description: config.description,
+            order: insertAt,
+            execution_type: config.execution_type,
+            status: "pending",
+            tasks: [],
+            artifacts_path: artifactsPath,
+            createdAt: now,
+        };
+        state.stagings[stagingId] = staging;
+        // Insert into plan's staging list
+        plan.stagings.splice(insertAt, 0, stagingId);
+        plan.updatedAt = now;
+        await this.addHistory("staging_added", { planId, stagingId, name: config.name });
+        await this.save();
+        return staging;
+    }
+    async removeStaging(stagingId) {
+        const state = this.ensureInitialized();
+        const staging = this.requireStaging(stagingId);
+        if (staging.status === "in_progress") {
+            throw new StagingInvalidStateError(stagingId, staging.status, ["pending", "completed", "cancelled"]);
+        }
+        const plan = this.requirePlan(staging.planId);
+        // Remove all tasks in this staging
+        for (const taskId of staging.tasks) {
+            delete state.tasks[taskId];
+        }
+        // Remove staging from plan
+        plan.stagings = plan.stagings.filter(id => id !== stagingId);
+        plan.updatedAt = new Date().toISOString();
+        // Reorder remaining stagings
+        const remainingStagings = this.getStagingsByPlan(staging.planId);
+        remainingStagings.sort((a, b) => a.order - b.order);
+        remainingStagings.forEach((s, i) => {
+            s.order = i;
+        });
+        // Remove staging
+        delete state.stagings[stagingId];
+        await this.addHistory("staging_removed", { stagingId, stagingName: staging.name });
+        await this.save();
+    }
+    // ============ Circular Dependency Detection ============
+    /**
+     * Check for circular dependencies in task dependencies
+     * @param taskId - The task being checked
+     * @param depends_on - Dependencies to validate
+     * @returns dependency chain if circular, null otherwise
+     */
+    detectCircularDependency(taskId, depends_on, visited = new Set()) {
+        if (visited.has(taskId)) {
+            return Array.from(visited);
+        }
+        visited.add(taskId);
+        for (const depId of depends_on) {
+            const depTask = this.getTask(depId);
+            if (!depTask)
+                continue;
+            if (depTask.depends_on.includes(taskId)) {
+                return [...Array.from(visited), depId, taskId];
+            }
+            const chain = this.detectCircularDependency(depId, depTask.depends_on, new Set(visited));
+            if (chain) {
+                return chain;
+            }
+        }
+        return null;
+    }
+    async addTask(stagingId, config) {
+        const state = this.ensureInitialized();
+        const staging = this.requireStaging(stagingId);
+        if (staging.status === "completed" || staging.status === "cancelled") {
+            throw new StagingInvalidStateError(stagingId, staging.status, ["pending", "in_progress"]);
+        }
+        const now = new Date().toISOString();
+        const taskId = idGenerator.generateTaskId();
+        const existingTasks = this.getTasksByStaging(stagingId);
+        // Check for circular dependencies
+        if (config.depends_on && config.depends_on.length > 0) {
+            const circularChain = this.detectCircularDependency(taskId, config.depends_on);
+            if (circularChain) {
+                throw new CircularDependencyError(taskId, circularChain);
+            }
+        }
+        const task = {
+            id: taskId,
+            planId: staging.planId,
+            stagingId,
+            title: config.title,
+            description: config.description,
+            priority: config.priority,
+            status: "pending",
+            execution_mode: config.execution_mode,
+            depends_on: config.depends_on ?? [],
+            order: existingTasks.length,
+            createdAt: now,
+            updatedAt: now,
+        };
+        state.tasks[taskId] = task;
+        staging.tasks.push(taskId);
+        await this.addHistory("task_added", { stagingId, taskId, title: config.title });
+        await this.save();
+        return task;
+    }
+    async removeTask(taskId) {
+        const state = this.ensureInitialized();
+        const task = this.requireTask(taskId);
+        if (task.status === "in_progress") {
+            throw new TaskInvalidStateError(taskId, task.status, ["pending", "done", "blocked", "cancelled"]);
+        }
+        const staging = this.requireStaging(task.stagingId);
+        // Remove task from staging
+        staging.tasks = staging.tasks.filter(id => id !== taskId);
+        // Remove this task from other tasks' dependencies
+        for (const t of Object.values(state.tasks)) {
+            t.depends_on = t.depends_on.filter(id => id !== taskId);
+        }
+        // Reorder remaining tasks
+        const remainingTasks = this.getTasksByStaging(task.stagingId);
+        remainingTasks.sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
+        remainingTasks.forEach((t, i) => {
+            t.order = i;
+        });
+        // Remove task
+        delete state.tasks[taskId];
+        await this.addHistory("task_removed", { taskId, taskTitle: task.title });
+        await this.save();
+    }
+    async updateTaskDetails(taskId, updates) {
+        const task = this.requireTask(taskId);
+        if (task.status === "done" || task.status === "cancelled") {
+            throw new TaskInvalidStateError(taskId, task.status, ["pending", "in_progress", "blocked"]);
+        }
+        const now = new Date().toISOString();
+        if (updates.title !== undefined)
+            task.title = updates.title;
+        if (updates.description !== undefined)
+            task.description = updates.description;
+        if (updates.priority !== undefined)
+            task.priority = updates.priority;
+        if (updates.execution_mode !== undefined)
+            task.execution_mode = updates.execution_mode;
+        // Handle depends_on updates with circular dependency check
+        if (updates.depends_on !== undefined) {
+            // Validate all dependency IDs exist and are in the same staging
+            for (const depId of updates.depends_on) {
+                const depTask = this.getTask(depId);
+                if (!depTask) {
+                    throw new TaskNotFoundError(depId);
+                }
+                if (depTask.stagingId !== task.stagingId) {
+                    throw new TaskInvalidStateError(depId, "different staging", ["same staging as dependent task"]);
+                }
+                // Cannot depend on itself
+                if (depId === taskId) {
+                    throw new CircularDependencyError(taskId, [taskId]);
+                }
+            }
+            // Check for circular dependencies
+            const circularChain = this.detectCircularDependency(taskId, updates.depends_on);
+            if (circularChain) {
+                throw new CircularDependencyError(taskId, circularChain);
+            }
+            task.depends_on = updates.depends_on;
+        }
+        task.updatedAt = now;
+        await this.addHistory("task_updated", { taskId, updates });
+        await this.save();
+        return task;
+    }
     // ============ Utility Methods ============
     getProjectRoot() {
         return this.projectRoot;