@zeliper/zscode-mcp-server 1.0.1 → 1.0.3

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"));
@@ -166,14 +210,17 @@ export class StateManager {
                     priority: taskConfig.priority,
                     status: "pending",
                     execution_mode: taskConfig.execution_mode,
+                    model: taskConfig.model, // Model override for this task
                     depends_on: [], // Will be resolved after all tasks are created
+                    cross_staging_refs: [], // Will be populated if cross-staging refs are provided
+                    memory_tags: [], // Will be populated if memory tags are provided
                     order: taskIndex,
                     createdAt: now,
                     updatedAt: now,
                 };
                 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++) {
@@ -193,11 +240,16 @@ export class StateManager {
                 order: stagingIndex,
                 execution_type: config.execution_type,
                 status: "pending",
+                default_model: config.default_model, // Default model for tasks in this staging
+                session_budget: config.session_budget, // Session budget category
+                recommended_sessions: config.recommended_sessions, // Recommended session count
                 tasks: taskIds,
+                depends_on_stagings: [], // Will be populated if staging dependencies are provided
+                auto_include_artifacts: true, // Default to auto-include
                 artifacts_path: artifactsPath,
                 createdAt: now,
             };
-            this.state.stagings[stagingId] = staging;
+            state.stagings[stagingId] = staging;
             stagingIds.push(stagingId);
         }
         // Create plan
@@ -211,17 +263,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 +282,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 +301,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 +311,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 +328,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 +337,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 +364,7 @@ export class StateManager {
                     return t?.status === "done";
                 });
                 if (allTasksDone) {
-                    await this.completestaging(staging.id);
+                    await this.completeStaging(staging.id);
                 }
             }
         }
@@ -333,19 +374,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 +415,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 +446,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 +520,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 +540,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 +558,291 @@ 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);
+    }
+    /**
+     * Get memories for a specific event (staging-start, task-start, etc.)
+     * Returns general + event-specific memories, optionally filtered by additional tags
+     */
+    getMemoriesForEvent(event, additionalTags) {
+        if (!this.state)
+            return [];
+        const enabledMemories = this.state.context.memories.filter(m => m.enabled);
+        // Get general + event-specific memories
+        let result = enabledMemories.filter(m => m.category === "general" || m.category === event);
+        // If additional tags are provided, also include memories matching those tags
+        if (additionalTags && additionalTags.length > 0) {
+            const tagMatched = enabledMemories.filter(m => additionalTags.some(tag => m.tags.includes(tag)));
+            // Add tag-matched memories that aren't already in result
+            const resultIds = new Set(result.map(m => m.id));
+            for (const m of tagMatched) {
+                if (!resultIds.has(m.id)) {
+                    result.push(m);
+                }
+            }
+        }
+        // Sort by priority (descending)
+        return result.sort((a, b) => b.priority - a.priority);
+    }
+    /**
+     * Get artifacts from stagings that this staging depends on
+     */
+    getRelatedStagingArtifacts(stagingId) {
+        const staging = this.getStaging(stagingId);
+        if (!staging)
+            return [];
+        const results = [];
+        for (const ref of staging.depends_on_stagings) {
+            const depStaging = this.getStaging(ref.stagingId);
+            if (!depStaging)
+                continue;
+            const tasks = this.getTasksByStaging(ref.stagingId);
+            const taskOutputs = {};
+            // If taskIds is specified, only include those tasks; otherwise include all
+            const targetTaskIds = ref.taskIds ?? tasks.map(t => t.id);
+            for (const task of tasks) {
+                if (targetTaskIds.includes(task.id) && task.output) {
+                    taskOutputs[task.id] = task.output;
+                }
+            }
+            results.push({
+                stagingId: depStaging.id,
+                stagingName: depStaging.name,
+                taskOutputs,
+            });
+        }
+        return results;
+    }
+    /**
+     * Get task outputs for cross-staging references
+     */
+    getCrossReferencedTaskOutputs(taskId) {
+        const task = this.getTask(taskId);
+        if (!task)
+            return [];
+        const results = [];
+        for (const ref of task.cross_staging_refs) {
+            const refTask = this.getTask(ref.taskId);
+            if (!refTask)
+                continue;
+            results.push({
+                taskId: refTask.id,
+                taskTitle: refTask.title,
+                stagingId: ref.stagingId,
+                output: refTask.output ?? null,
+            });
+        }
+        return results;
+    }
+    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();
+    }
+    // ============ Project Summary Operations ============
+    /**
+     * Get the existing project summary memory (if any)
+     */
+    getProjectSummary() {
+        if (!this.state)
+            return undefined;
+        return this.state.context.memories.find(m => m.category === "project-summary");
+    }
+    /**
+     * Generate a project summary from current state
+     */
+    generateProjectSummaryContent() {
+        if (!this.state)
+            return "";
+        const project = this.state.project;
+        const plans = Object.values(this.state.plans);
+        const memories = this.state.context.memories.filter(m => m.category !== "project-summary");
+        // Calculate stats
+        const activePlans = plans.filter(p => p.status === "active");
+        const completedPlans = plans.filter(p => p.status === "completed");
+        const totalTasks = Object.keys(this.state.tasks).length;
+        const completedTasks = Object.values(this.state.tasks).filter(t => t.status === "done").length;
+        // Build summary content
+        const lines = [];
+        // Project info
+        lines.push(`# ${project.name}`);
+        if (project.description) {
+            lines.push(`\n${project.description}`);
+        }
+        // Goals
+        if (project.goals.length > 0) {
+            lines.push(`\n## Goals`);
+            project.goals.forEach(g => lines.push(`- ${g}`));
+        }
+        // Constraints
+        if (project.constraints.length > 0) {
+            lines.push(`\n## Constraints`);
+            project.constraints.forEach(c => lines.push(`- ${c}`));
+        }
+        // Current status
+        lines.push(`\n## Status`);
+        lines.push(`- Active Plans: ${activePlans.length}`);
+        lines.push(`- Completed Plans: ${completedPlans.length}`);
+        lines.push(`- Tasks: ${completedTasks}/${totalTasks} completed`);
+        // Active plan details
+        if (activePlans.length > 0) {
+            lines.push(`\n## Active Work`);
+            for (const plan of activePlans) {
+                const stagings = this.getStagingsByPlan(plan.id);
+                const currentStaging = stagings.find(s => s.status === "in_progress");
+                lines.push(`- **${plan.title}**`);
+                if (currentStaging) {
+                    const tasks = this.getTasksByStaging(currentStaging.id);
+                    const inProgress = tasks.filter(t => t.status === "in_progress");
+                    lines.push(`  - Current: ${currentStaging.name}`);
+                    if (inProgress.length > 0) {
+                        lines.push(`  - Tasks: ${inProgress.map(t => t.title).join(", ")}`);
+                    }
+                }
+            }
+        }
+        // Key memories (non project-summary)
+        const keyMemories = memories.filter(m => m.enabled && m.priority >= 70);
+        if (keyMemories.length > 0) {
+            lines.push(`\n## Key Rules`);
+            for (const m of keyMemories.slice(0, 5)) {
+                lines.push(`- **${m.title}** (${m.category})`);
+            }
+        }
+        // Recent decisions
+        const recentDecisions = this.state.context.decisions.slice(-3);
+        if (recentDecisions.length > 0) {
+            lines.push(`\n## Recent Decisions`);
+            for (const d of recentDecisions) {
+                lines.push(`- ${d.title}: ${d.decision}`);
+            }
+        }
+        return lines.join("\n");
+    }
+    /**
+     * Create or update the project summary memory
+     */
+    async saveProjectSummary(content) {
+        const state = this.ensureInitialized();
+        const summaryContent = content ?? this.generateProjectSummaryContent();
+        const existingSummary = this.getProjectSummary();
+        if (existingSummary) {
+            // Update existing summary
+            return this.updateMemory(existingSummary.id, {
+                content: summaryContent,
+                title: `${state.project.name} - Project Summary`,
+            });
+        }
+        else {
+            // Create new summary
+            return this.addMemory("project-summary", `${state.project.name} - Project Summary`, summaryContent, ["auto-generated", "summary"], 100 // Highest priority to appear first
+            );
+        }
+    }
+    /**
+     * Get memories that should always be applied (general + project-summary)
+     */
+    getAlwaysAppliedMemories() {
+        if (!this.state)
+            return [];
+        const enabledMemories = this.state.context.memories.filter(m => m.enabled);
+        // Return general + project-summary memories
+        const result = enabledMemories.filter(m => m.category === "general" || m.category === "project-summary");
+        // Sort by priority (descending)
+        return result.sort((a, b) => b.priority - a.priority);
+    }
     // ============ Session Operations ============
     async startSession() {
         await this.addHistory("session_started", {});
@@ -490,13 +859,9 @@ export class StateManager {
     }
     // ============ Modify Operations ============
     async updatePlan(planId, updates) {
-        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);
         if (plan.status === "archived" || plan.status === "cancelled") {
-            throw new Error(`Cannot modify ${plan.status} plan`);
+            throw new PlanInvalidStateError(planId, plan.status, ["draft", "active", "completed"]);
         }
         const now = new Date().toISOString();
         if (updates.title !== undefined)
@@ -509,13 +874,9 @@ export class StateManager {
         return plan;
     }
     async updateStaging(stagingId, updates) {
-        if (!this.state)
-            throw new Error("Project not initialized");
-        const staging = this.getStaging(stagingId);
-        if (!staging)
-            throw new Error(`Staging not found: ${stagingId}`);
+        const staging = this.requireStaging(stagingId);
         if (staging.status === "completed" || staging.status === "cancelled") {
-            throw new Error(`Cannot modify ${staging.status} staging`);
+            throw new StagingInvalidStateError(stagingId, staging.status, ["pending", "in_progress"]);
         }
         if (updates.name !== undefined)
             staging.name = updates.name;
@@ -523,18 +884,21 @@ export class StateManager {
             staging.description = updates.description;
         if (updates.execution_type !== undefined)
             staging.execution_type = updates.execution_type;
+        if (updates.default_model !== undefined)
+            staging.default_model = updates.default_model;
+        if (updates.session_budget !== undefined)
+            staging.session_budget = updates.session_budget;
+        if (updates.recommended_sessions !== undefined)
+            staging.recommended_sessions = updates.recommended_sessions;
         await this.addHistory("staging_updated", { stagingId, updates });
         await this.save();
         return staging;
     }
     async addStaging(planId, config) {
-        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" || plan.status === "completed") {
-            throw new Error(`Cannot add staging to ${plan.status} plan`);
+            throw new PlanInvalidStateError(planId, plan.status, ["draft", "active"]);
         }
         const now = new Date().toISOString();
         const stagingId = idGenerator.generateStagingId();
@@ -555,11 +919,16 @@ export class StateManager {
             order: insertAt,
             execution_type: config.execution_type,
             status: "pending",
+            default_model: config.default_model,
+            session_budget: config.session_budget,
+            recommended_sessions: config.recommended_sessions,
             tasks: [],
+            depends_on_stagings: [],
+            auto_include_artifacts: true,
             artifacts_path: artifactsPath,
             createdAt: now,
         };
-        this.state.stagings[stagingId] = staging;
+        state.stagings[stagingId] = staging;
         // Insert into plan's staging list
         plan.stagings.splice(insertAt, 0, stagingId);
         plan.updatedAt = now;
@@ -568,20 +937,15 @@ export class StateManager {
         return staging;
     }
     async removeStaging(stagingId) {
-        if (!this.state)
-            throw new Error("Project not initialized");
-        const staging = this.getStaging(stagingId);
-        if (!staging)
-            throw new Error(`Staging not found: ${stagingId}`);
+        const state = this.ensureInitialized();
+        const staging = this.requireStaging(stagingId);
         if (staging.status === "in_progress") {
-            throw new Error("Cannot remove in_progress staging");
+            throw new StagingInvalidStateError(stagingId, staging.status, ["pending", "completed", "cancelled"]);
         }
-        const plan = this.getPlan(staging.planId);
-        if (!plan)
-            throw new Error(`Plan not found: ${staging.planId}`);
+        const plan = this.requirePlan(staging.planId);
         // Remove all tasks in this staging
         for (const taskId of staging.tasks) {
-            delete this.state.tasks[taskId];
+            delete state.tasks[taskId];
         }
         // Remove staging from plan
         plan.stagings = plan.stagings.filter(id => id !== stagingId);
@@ -593,22 +957,52 @@ export class StateManager {
             s.order = i;
         });
         // Remove staging
-        delete this.state.stagings[stagingId];
+        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) {
-        if (!this.state)
-            throw new Error("Project not initialized");
-        const staging = this.getStaging(stagingId);
-        if (!staging)
-            throw new Error(`Staging not found: ${stagingId}`);
+        const state = this.ensureInitialized();
+        const staging = this.requireStaging(stagingId);
         if (staging.status === "completed" || staging.status === "cancelled") {
-            throw new Error(`Cannot add task to ${staging.status} staging`);
+            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,
@@ -618,33 +1012,31 @@ export class StateManager {
             priority: config.priority,
             status: "pending",
             execution_mode: config.execution_mode,
+            model: config.model,
             depends_on: config.depends_on ?? [],
+            cross_staging_refs: [],
+            memory_tags: [],
             order: existingTasks.length,
             createdAt: now,
             updatedAt: now,
         };
-        this.state.tasks[taskId] = task;
+        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) {
-        if (!this.state)
-            throw new Error("Project not initialized");
-        const task = this.getTask(taskId);
-        if (!task)
-            throw new Error(`Task not found: ${taskId}`);
+        const state = this.ensureInitialized();
+        const task = this.requireTask(taskId);
         if (task.status === "in_progress") {
-            throw new Error("Cannot remove in_progress task");
+            throw new TaskInvalidStateError(taskId, task.status, ["pending", "done", "blocked", "cancelled"]);
         }
-        const staging = this.getStaging(task.stagingId);
-        if (!staging)
-            throw new Error(`Staging not found: ${task.stagingId}`);
+        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(this.state.tasks)) {
+        for (const t of Object.values(state.tasks)) {
             t.depends_on = t.depends_on.filter(id => id !== taskId);
         }
         // Reorder remaining tasks
@@ -654,18 +1046,14 @@ export class StateManager {
             t.order = i;
         });
         // Remove task
-        delete this.state.tasks[taskId];
+        delete state.tasks[taskId];
         await this.addHistory("task_removed", { taskId, taskTitle: task.title });
         await this.save();
     }
     async updateTaskDetails(taskId, updates) {
-        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);
         if (task.status === "done" || task.status === "cancelled") {
-            throw new Error(`Cannot modify ${task.status} task`);
+            throw new TaskInvalidStateError(taskId, task.status, ["pending", "in_progress", "blocked"]);
         }
         const now = new Date().toISOString();
         if (updates.title !== undefined)
@@ -676,6 +1064,31 @@ export class StateManager {
             task.priority = updates.priority;
         if (updates.execution_mode !== undefined)
             task.execution_mode = updates.execution_mode;
+        if (updates.model !== undefined)
+            task.model = updates.model;
+        // 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();