@locusai/sdk 0.10.2 → 0.10.5

package/dist/index-node.js

@@ -768,10 +768,12 @@ class ClaudeRunner {
   currentToolName;
   activeTools = new Map;
   activeProcess = null;
-  constructor(projectPath, model = DEFAULT_MODEL[PROVIDER.CLAUDE], log) {
+  timeoutMs;
+  constructor(projectPath, model = DEFAULT_MODEL[PROVIDER.CLAUDE], log, timeoutMs) {
     this.model = model;
     this.log = log;
     this.projectPath = import_node_path3.resolve(projectPath);
+    this.timeoutMs = timeoutMs ?? DEFAULT_TIMEOUT_MS;
   }
   setEventEmitter(emitter) {
     this.eventEmitter = emitter;
@@ -787,11 +789,14 @@ class ClaudeRunner {
     let lastError = null;
     for (let attempt = 1;attempt <= maxRetries; attempt++) {
       try {
-        return await this.executeRun(prompt);
+        return await this.withTimeout(this.executeRun(prompt));
       } catch (error) {
         const err = error;
         lastError = err;
         const isLastAttempt = attempt === maxRetries;
+        if (err.message.includes("timed out")) {
+          throw err;
+        }
         if (!isLastAttempt) {
           const delay = Math.pow(2, attempt) * 1000;
           console.warn(`Claude CLI attempt ${attempt} failed: ${err.message}. Retrying in ${delay}ms...`);
@@ -801,6 +806,23 @@ class ClaudeRunner {
     }
     throw lastError || new Error("Claude CLI failed after multiple attempts");
   }
+  withTimeout(promise) {
+    if (this.timeoutMs <= 0)
+      return promise;
+    return new Promise((resolve2, reject) => {
+      const timer = setTimeout(() => {
+        this.abort();
+        reject(new Error(`Claude CLI execution timed out after ${Math.round(this.timeoutMs / 60000)} minutes`));
+      }, this.timeoutMs);
+      promise.then((value) => {
+        clearTimeout(timer);
+        resolve2(value);
+      }, (err) => {
+        clearTimeout(timer);
+        reject(err);
+      });
+    });
+  }
   async* runStream(prompt) {
     const args = [
       "--dangerously-skip-permissions",
@@ -1165,7 +1187,7 @@ ${c.primary("[Claude]")} ${c.bold(`Running ${content_block.name}...`)}
     return new Error(message);
   }
 }
-var import_node_child_process, import_node_path3, SANDBOX_SETTINGS;
+var import_node_child_process, import_node_path3, SANDBOX_SETTINGS, DEFAULT_TIMEOUT_MS;
 var init_claude_runner = __esm(() => {
   init_config();
   init_colors();
@@ -1173,12 +1195,16 @@ var init_claude_runner = __esm(() => {
   import_node_child_process = require("node:child_process");
   import_node_path3 = require("node:path");
   SANDBOX_SETTINGS = JSON.stringify({
+    permissions: {
+      deny: ["Read(../**)", "Edit(../**)"]
+    },
     sandbox: {
       enabled: true,
       autoAllow: true,
       allowUnsandboxedCommands: false
     }
   });
+  DEFAULT_TIMEOUT_MS = 60 * 60 * 1000;
 });
 
 // src/ai/codex-runner.ts
@@ -1187,10 +1213,17 @@ class CodexRunner {
   model;
   log;
   activeProcess = null;
-  constructor(projectPath, model = DEFAULT_MODEL[PROVIDER.CODEX], log) {
+  eventEmitter;
+  currentToolName;
+  timeoutMs;
+  constructor(projectPath, model = DEFAULT_MODEL[PROVIDER.CODEX], log, timeoutMs) {
     this.projectPath = projectPath;
     this.model = model;
     this.log = log;
+    this.timeoutMs = timeoutMs ?? DEFAULT_TIMEOUT_MS2;
+  }
+  setEventEmitter(emitter) {
+    this.eventEmitter = emitter;
   }
   abort() {
     if (this.activeProcess && !this.activeProcess.killed) {
@@ -1203,9 +1236,12 @@ class CodexRunner {
     let lastError = null;
     for (let attempt = 1;attempt <= maxRetries; attempt++) {
       try {
-        return await this.executeRun(prompt);
+        return await this.withTimeout(this.executeRun(prompt));
       } catch (error) {
         lastError = error;
+        if (lastError.message.includes("timed out")) {
+          throw lastError;
+        }
         if (attempt < maxRetries) {
           const delay = Math.pow(2, attempt) * 1000;
           console.warn(`Codex CLI attempt ${attempt} failed: ${lastError.message}. Retrying in ${delay}ms...`);
@@ -1215,9 +1251,31 @@ class CodexRunner {
     }
     throw lastError || new Error("Codex CLI failed after multiple attempts");
   }
+  withTimeout(promise) {
+    if (this.timeoutMs <= 0)
+      return promise;
+    return new Promise((resolve2, reject) => {
+      const timer = setTimeout(() => {
+        this.abort();
+        reject(new Error(`Codex CLI execution timed out after ${Math.round(this.timeoutMs / 60000)} minutes`));
+      }, this.timeoutMs);
+      promise.then((value) => {
+        clearTimeout(timer);
+        resolve2(value);
+      }, (err) => {
+        clearTimeout(timer);
+        reject(err);
+      });
+    });
+  }
   async* runStream(prompt) {
     const outputPath = import_node_path4.join(import_node_os2.tmpdir(), `locus-codex-${import_node_crypto.randomUUID()}.txt`);
     const args = this.buildArgs(outputPath);
+    this.eventEmitter?.emitSessionStarted({
+      model: this.model,
+      provider: "codex"
+    });
+    this.eventEmitter?.emitPromptSubmitted(prompt, prompt.length > 500);
     const codex = import_node_child_process2.spawn("codex", args, {
       cwd: this.projectPath,
       stdio: ["pipe", "pipe", "pipe"],
@@ -1230,7 +1288,21 @@ class CodexRunner {
     let processEnded = false;
     let errorMessage = "";
     let finalOutput = "";
+    let finalContent = "";
+    let isThinking = false;
     const enqueueChunk = (chunk) => {
+      this.emitEventForChunk(chunk, isThinking);
+      if (chunk.type === "thinking") {
+        isThinking = true;
+      } else if (chunk.type === "text_delta" || chunk.type === "tool_use") {
+        if (isThinking) {
+          this.eventEmitter?.emitThinkingStoped();
+          isThinking = false;
+        }
+      }
+      if (chunk.type === "text_delta") {
+        finalContent += chunk.content;
+      }
       if (resolveChunk) {
         const resolve2 = resolveChunk;
         resolveChunk = null;
@@ -1271,16 +1343,21 @@ class CodexRunner {
     codex.stderr.on("data", processOutput);
     codex.on("error", (err) => {
       errorMessage = `Failed to start Codex CLI: ${err.message}. Ensure 'codex' is installed and available in PATH.`;
+      this.eventEmitter?.emitErrorOccurred(errorMessage, "SPAWN_ERROR");
       signalEnd();
     });
     codex.on("close", (code) => {
       this.activeProcess = null;
-      this.cleanupTempFile(outputPath);
       if (code === 0) {
         const result = this.readOutput(outputPath, finalOutput);
+        this.cleanupTempFile(outputPath);
         enqueueChunk({ type: "result", content: result });
-      } else if (!errorMessage) {
-        errorMessage = this.createErrorFromOutput(code, finalOutput).message;
+      } else {
+        this.cleanupTempFile(outputPath);
+        if (!errorMessage) {
+          errorMessage = this.createErrorFromOutput(code, finalOutput).message;
+          this.eventEmitter?.emitErrorOccurred(errorMessage, `EXIT_${code}`);
+        }
       }
       signalEnd();
     });
@@ -1294,6 +1371,12 @@ class CodexRunner {
       } else if (processEnded) {
         if (errorMessage) {
           yield { type: "error", error: errorMessage };
+          this.eventEmitter?.emitSessionEnded(false);
+        } else {
+          if (finalContent) {
+            this.eventEmitter?.emitResponseCompleted(finalContent);
+          }
+          this.eventEmitter?.emitSessionEnded(true);
         }
         break;
       } else {
@@ -1303,6 +1386,12 @@ class CodexRunner {
         if (chunk === null) {
           if (errorMessage) {
             yield { type: "error", error: errorMessage };
+            this.eventEmitter?.emitSessionEnded(false);
+          } else {
+            if (finalContent) {
+              this.eventEmitter?.emitResponseCompleted(finalContent);
+            }
+            this.eventEmitter?.emitSessionEnded(true);
           }
           break;
         }
@@ -1310,6 +1399,36 @@ class CodexRunner {
       }
     }
   }
+  emitEventForChunk(chunk, isThinking) {
+    if (!this.eventEmitter)
+      return;
+    switch (chunk.type) {
+      case "text_delta":
+        this.eventEmitter.emitTextDelta(chunk.content);
+        break;
+      case "tool_use":
+        if (this.currentToolName) {
+          this.eventEmitter.emitToolCompleted(this.currentToolName);
+        }
+        this.currentToolName = chunk.tool;
+        this.eventEmitter.emitToolStarted(chunk.tool);
+        break;
+      case "thinking":
+        if (!isThinking) {
+          this.eventEmitter.emitThinkingStarted(chunk.content);
+        }
+        break;
+      case "result":
+        if (this.currentToolName) {
+          this.eventEmitter.emitToolCompleted(this.currentToolName);
+          this.currentToolName = undefined;
+        }
+        break;
+      case "error":
+        this.eventEmitter.emitErrorOccurred(chunk.error);
+        break;
+    }
+  }
   executeRun(prompt) {
     return new Promise((resolve2, reject) => {
       const outputPath = import_node_path4.join(import_node_os2.tmpdir(), `locus-codex-${import_node_crypto.randomUUID()}.txt`);
@@ -1339,10 +1458,12 @@ class CodexRunner {
       });
       codex.on("close", (code) => {
         this.activeProcess = null;
-        this.cleanupTempFile(outputPath);
         if (code === 0) {
-          resolve2(this.readOutput(outputPath, output));
+          const result = this.readOutput(outputPath, output);
+          this.cleanupTempFile(outputPath);
+          resolve2(result);
         } else {
+          this.cleanupTempFile(outputPath);
           reject(this.createErrorFromOutput(code, errorOutput));
         }
       });
@@ -1352,12 +1473,18 @@ class CodexRunner {
   }
   buildArgs(outputPath) {
     const args = [
+      "--ask-for-approval",
+      "never",
       "exec",
       "--sandbox",
       "workspace-write",
       "--skip-git-repo-check",
       "--output-last-message",
-      outputPath
+      outputPath,
+      "-c",
+      "sandbox_workspace_write.network_access=true",
+      "-c",
+      'sandbox.excludedCommands=["git", "gh"]'
     ];
     if (this.model) {
       args.push("--model", this.model);
@@ -1408,7 +1535,7 @@ class CodexRunner {
     return new Promise((resolve2) => setTimeout(resolve2, ms));
   }
 }
-var import_node_child_process2, import_node_crypto, import_node_fs2, import_node_os2, import_node_path4;
+var import_node_child_process2, import_node_crypto, import_node_fs2, import_node_os2, import_node_path4, DEFAULT_TIMEOUT_MS2;
 var init_codex_runner = __esm(() => {
   init_config();
   init_resolve_bin();
@@ -1417,6 +1544,7 @@ var init_codex_runner = __esm(() => {
   import_node_fs2 = require("node:fs");
   import_node_os2 = require("node:os");
   import_node_path4 = require("node:path");
+  DEFAULT_TIMEOUT_MS2 = 60 * 60 * 1000;
 });
 
 // src/ai/factory.ts
@@ -1425,9 +1553,9 @@ function createAiRunner(provider, config) {
   const model = config.model ?? DEFAULT_MODEL[resolvedProvider];
   switch (resolvedProvider) {
     case PROVIDER.CODEX:
-      return new CodexRunner(config.projectPath, model, config.log);
+      return new CodexRunner(config.projectPath, model, config.log, config.timeoutMs);
     default:
-      return new ClaudeRunner(config.projectPath, model, config.log);
+      return new ClaudeRunner(config.projectPath, model, config.log, config.timeoutMs);
   }
 }
 var init_factory = __esm(() => {
@@ -1952,8 +2080,9 @@ class WorktreeManager {
       this.ensureDirectory(this.rootPath, "Worktree root");
       addWorktree();
     }
-    this.log(`Worktree created at ${worktreePath}`, "success");
-    return { worktreePath, branch, baseBranch };
+    const baseCommitHash = this.git("rev-parse HEAD", worktreePath).trim();
+    this.log(`Worktree created at ${worktreePath} (base: ${baseCommitHash.slice(0, 8)})`, "success");
+    return { worktreePath, branch, baseBranch, baseCommitHash };
   }
   list() {
     const output = this.git("worktree list --porcelain", this.projectPath);
@@ -2058,27 +2187,54 @@ class WorktreeManager {
     try {
       const count = this.git(`rev-list --count "${baseBranch}..HEAD"`, worktreePath).trim();
       return Number.parseInt(count, 10) > 0;
+    } catch (err) {
+      this.log(`Could not compare HEAD against base branch "${baseBranch}": ${err instanceof Error ? err.message : String(err)}`, "warn");
+      return false;
+    }
+  }
+  hasCommitsAheadOfHash(worktreePath, baseHash) {
+    try {
+      const headHash = this.git("rev-parse HEAD", worktreePath).trim();
+      return headHash !== baseHash;
     } catch {
       return false;
     }
   }
-  commitChanges(worktreePath, message, baseBranch) {
+  commitChanges(worktreePath, message, baseBranch, baseCommitHash) {
     const hasUncommittedChanges = this.hasChanges(worktreePath);
+    if (hasUncommittedChanges) {
+      const statusOutput = this.git("status --porcelain", worktreePath).trim();
+      this.log(`Detected uncommitted changes:
+${statusOutput.split(`
+`).slice(0, 10).join(`
+`)}${statusOutput.split(`
+`).length > 10 ? `
+... and ${statusOutput.split(`
+`).length - 10} more` : ""}`, "info");
+    }
     if (!hasUncommittedChanges) {
       if (baseBranch && this.hasCommitsAhead(worktreePath, baseBranch)) {
         const hash2 = this.git("rev-parse HEAD", worktreePath).trim();
         this.log(`Agent already committed changes (${hash2.slice(0, 8)}); skipping additional commit`, "info");
         return hash2;
       }
-      this.log("No changes to commit", "info");
+      if (baseCommitHash && this.hasCommitsAheadOfHash(worktreePath, baseCommitHash)) {
+        const hash2 = this.git("rev-parse HEAD", worktreePath).trim();
+        this.log(`Agent already committed changes (${hash2.slice(0, 8)}, detected via base commit hash); skipping additional commit`, "info");
+        return hash2;
+      }
+      const branch = this.getBranch(worktreePath);
+      this.log(`No changes detected in worktree (branch: ${branch}, baseBranch: ${baseBranch ?? "none"}, baseCommitHash: ${baseCommitHash?.slice(0, 8) ?? "none"})`, "warn");
       return null;
     }
     this.git("add -A", worktreePath);
     const staged = this.git("diff --cached --name-only", worktreePath).trim();
     if (!staged) {
-      this.log("No changes to commit", "info");
+      this.log("All changes were ignored by .gitignore — nothing to commit", "warn");
       return null;
     }
+    this.log(`Staging ${staged.split(`
+`).length} file(s) for commit`, "info");
     this.gitExec(["commit", "-m", message], worktreePath);
     const hash = this.git("rev-parse HEAD", worktreePath).trim();
     this.log(`Committed: ${hash.slice(0, 8)}`, "success");
@@ -2500,15 +2656,27 @@ class TaskExecutor {
     const basePrompt = await this.promptBuilder.build(task);
     try {
       this.deps.log("Starting Execution...", "info");
-      await this.deps.aiRunner.run(basePrompt);
-      return {
-        success: true,
-        summary: "Task completed by the agent"
-      };
+      const output = await this.deps.aiRunner.run(basePrompt);
+      const summary = this.extractSummary(output);
+      return { success: true, summary };
     } catch (error) {
       return { success: false, summary: `Error: ${error}` };
     }
   }
+  extractSummary(output) {
+    if (!output || !output.trim()) {
+      return "Task completed by the agent";
+    }
+    const paragraphs = output.split(/\n\n+/).map((p) => p.trim()).filter((p) => p.length > 0);
+    if (paragraphs.length === 0) {
+      return "Task completed by the agent";
+    }
+    const last = paragraphs[paragraphs.length - 1];
+    if (last.length > 500) {
+      return `${last.slice(0, 497)}...`;
+    }
+    return last;
+  }
 }
 var init_task_executor = __esm(() => {
   init_prompt_builder();
@@ -2526,7 +2694,7 @@ class GitWorkflow {
     this.log = log;
     this.ghUsername = ghUsername;
     const projectPath = config.projectPath || process.cwd();
-    this.worktreeManager = config.useWorktrees ? new WorktreeManager(projectPath, { cleanupPolicy: "auto" }) : null;
+    this.worktreeManager = config.useWorktrees ? new WorktreeManager(projectPath, { cleanupPolicy: "auto" }, log) : null;
     this.prService = config.autoPush ? new PrService(projectPath, log) : null;
   }
   createTaskWorktree(task, defaultExecutor) {
@@ -2534,6 +2702,7 @@ class GitWorkflow {
       return {
         worktreePath: null,
         baseBranch: null,
+        baseCommitHash: null,
         executor: defaultExecutor
       };
     }
@@ -2559,10 +2728,11 @@ class GitWorkflow {
     return {
       worktreePath: result.worktreePath,
       baseBranch: result.baseBranch,
+      baseCommitHash: result.baseCommitHash,
       executor: taskExecutor
     };
   }
-  commitAndPush(worktreePath, task, baseBranch) {
+  commitAndPush(worktreePath, task, baseBranch, baseCommitHash) {
     if (!this.worktreeManager) {
       return { branch: null, pushed: false, pushFailed: false };
     }
@@ -2579,7 +2749,7 @@ class GitWorkflow {
 
 ${trailers.join(`
 `)}`;
-      const hash = this.worktreeManager.commitChanges(worktreePath, commitMessage, baseBranch);
+      const hash = this.worktreeManager.commitChanges(worktreePath, commitMessage, baseBranch, baseCommitHash);
       if (!hash) {
         this.log("No changes to commit for this task", "info");
         return {
@@ -2619,7 +2789,12 @@ ${trailers.join(`
     } catch (err) {
       const errorMessage = err instanceof Error ? err.message : String(err);
       this.log(`Git commit failed: ${errorMessage}`, "error");
-      return { branch: null, pushed: false, pushFailed: false };
+      return {
+        branch: null,
+        pushed: false,
+        pushFailed: true,
+        pushError: `Git commit/push failed: ${errorMessage}`
+      };
     }
   }
   createPullRequest(task, branch, summary, baseBranch) {
@@ -2851,7 +3026,7 @@ class AgentWorker {
   }
   async executeTask(task) {
     const fullTask = await this.client.tasks.getById(task.id, this.config.workspaceId);
-    const { worktreePath, baseBranch, executor } = this.gitWorkflow.createTaskWorktree(fullTask, this.taskExecutor);
+    const { worktreePath, baseBranch, baseCommitHash, executor } = this.gitWorkflow.createTaskWorktree(fullTask, this.taskExecutor);
     this.currentWorktreePath = worktreePath;
     let branchPushed = false;
     let keepBranch = false;
@@ -2863,7 +3038,7 @@ class AgentWorker {
       let prError = null;
       let noChanges = false;
       if (result.success && worktreePath) {
-        const commitResult = this.gitWorkflow.commitAndPush(worktreePath, fullTask, baseBranch ?? undefined);
+        const commitResult = this.gitWorkflow.commitAndPush(worktreePath, fullTask, baseBranch ?? undefined, baseCommitHash ?? undefined);
         taskBranch = commitResult.branch;
         branchPushed = commitResult.pushed;
         keepBranch = taskBranch !== null;
@@ -4986,6 +5161,9 @@ class TierMergeService {
     }
   }
   findTierTaskBranches(tier) {
+    const tierTaskIds = this.tierTaskIds.get(tier);
+    if (!tierTaskIds || tierTaskIds.length === 0)
+      return [];
     try {
       const output = import_node_child_process8.execSync('git branch -r --list "origin/agent/*" --format="%(refname:short)"', { cwd: this.projectPath, encoding: "utf-8" }).trim();
       if (!output)
@@ -4993,13 +5171,13 @@ class TierMergeService {
       const remoteBranches = output.split(`
 `).map((b) => b.replace("origin/", ""));
       return remoteBranches.filter((branch) => {
-        const match = branch.match(/^agent\/([^-]+)/);
-        if (!match)
+        const branchSuffix = branch.replace(/^agent\//, "");
+        if (!branchSuffix)
           return false;
-        const taskIdPrefix = match[1];
-        return this.tierTaskIds.get(tier)?.some((id) => id.startsWith(taskIdPrefix) || taskIdPrefix.startsWith(id.slice(0, 8))) ?? false;
+        return tierTaskIds.some((id) => branchSuffix.startsWith(`${id}-`) || branchSuffix === id || branchSuffix.startsWith(id));
       });
-    } catch {
+    } catch (err) {
+      console.log(c.dim(`   Could not list remote branches for tier ${tier}: ${err instanceof Error ? err.message : String(err)}`));
       return [];
     }
   }
@@ -5550,6 +5728,7 @@ Review and refine the Tech Lead's breakdown:
 3. **Task Merging** — If two tasks are trivially small and related, merge them.
 4. **Complexity Scoring** — Rate each task 1-5 (1=trivial, 5=very complex).
 5. **Missing Tasks** — Add any tasks the Tech Lead missed (database migrations, configuration, testing, etc.).
+6. **Description Quality** — Review and improve each task description to be a clear, actionable implementation guide. Each description must tell the executing agent exactly what to do, where to do it (specific files/modules), how to do it (patterns, utilities, data flow), and what is NOT in scope. Vague descriptions like "Add authentication" must be rewritten with specific file paths, implementation approach, and boundaries.
 
 ## CRITICAL: Task Isolation & Overlap Detection
 
@@ -5575,7 +5754,7 @@ Your entire response must be a single JSON object — no text before it, no text
   "tasks": [
     {
       "title": "string",
-      "description": "string (2-4 sentences)",
+      "description": "string (detailed implementation guide: what to do, where to do it, how to do it, and boundaries)",
       "assigneeRole": "BACKEND | FRONTEND | QA | PM | DESIGN",
       "priority": "HIGH | MEDIUM | LOW | CRITICAL",
       "labels": ["string"],
@@ -5668,6 +5847,15 @@ Verify tier assignments are correct:
 ### 5. Merge Conflict Risk Zones
 Identify the highest-risk files (files that multiple same-tier tasks might touch) and ensure only ONE task per tier modifies each.
 
+### 6. Description Quality Validation
+For each task, verify the description is a clear, actionable implementation guide. Each description must specify:
+- **What to do** — the specific goal and expected behavior/outcome
+- **Where to do it** — specific files, modules, or directories to modify or create
+- **How to do it** — implementation approach, patterns to follow, existing utilities to use
+- **Boundaries** — what is NOT in scope for this task
+
+If any description is vague (e.g., "Add authentication", "Update the API", "Fix the frontend"), rewrite it with concrete implementation details. The executing agent receives ONLY the task title, description, and acceptance criteria as its instructions.
+
 ## Output Format
 
 Your entire response must be a single JSON object — no text before it, no text after it, no markdown code blocks, no explanation. Start your response with the "{" character:
@@ -5676,7 +5864,7 @@ Your entire response must be a single JSON object — no text before it, no text
   "hasIssues": true | false,
   "issues": [
     {
-      "type": "file_overlap" | "duplicated_work" | "not_self_contained" | "merge_conflict_risk" | "wrong_tier",
+      "type": "file_overlap" | "duplicated_work" | "not_self_contained" | "merge_conflict_risk" | "wrong_tier" | "vague_description",
       "description": "string describing the specific issue",
       "affectedTasks": ["Task Title 1", "Task Title 2"],
       "resolution": "string describing how to fix it (merge, move to different tier, consolidate)"
@@ -5689,7 +5877,7 @@ Your entire response must be a single JSON object — no text before it, no text
     "tasks": [
       {
         "title": "string",
-        "description": "string",
+        "description": "string (detailed implementation guide: what to do, where to do it, how to do it, and boundaries)",
         "assigneeRole": "BACKEND | FRONTEND | QA | PM | DESIGN",
         "priority": "CRITICAL | HIGH | MEDIUM | LOW",
         "labels": ["string"],
@@ -5713,6 +5901,7 @@ IMPORTANT:
 - If hasIssues is false, the revisedPlan should be identical to the input plan (no changes needed)
 - The revisedPlan is ALWAYS required — it becomes the final plan
 - When merging tasks, combine their acceptance criteria and update descriptions to cover all consolidated work
+- Ensure every task description is a detailed implementation guide (what, where, how, boundaries) — rewrite vague descriptions
 - Prefer fewer, larger, self-contained tasks over many small conflicting ones
 - Every task MUST have a "tier" field (integer >= 0)
 - tier 0 = foundational (runs first), tier 1 = depends on tier 0, tier 2 = depends on tier 1, etc.
@@ -5751,6 +5940,7 @@ Produce the final sprint plan:
 4. **Tier Assignment** — Assign each task an execution tier (integer, starting at 0). Tasks within the same tier run IN PARALLEL on separate git branches. Tasks in tier N+1 only start AFTER all tier N tasks are complete and merged. Tier 0 = foundational tasks (config, schemas, shared code). Higher tiers build on lower tier outputs.
 5. **Duration Estimate** — How many days this sprint will take with 2-3 agents working in parallel
 6. **Final Task List** — Each task with all fields filled in, ordered by execution priority
+7. **Description Quality Check** — Ensure every task description is a clear, actionable implementation guide. Each description must specify: what to do, where to do it (specific files/modules/directories), how to do it (implementation approach, patterns to follow, existing utilities to use), and what is NOT in scope. If any description is vague or generic, rewrite it with specifics. Remember: an independent agent will receive ONLY the task title, description, and acceptance criteria — the description is its primary instruction.
 
 Guidelines:
 - The order of tasks in the array determines execution order. Tasks are dispatched sequentially from first to last.
@@ -5760,6 +5950,7 @@ Guidelines:
 - Group related independent tasks in the same tier for maximum parallelism
 - Ensure acceptance criteria are specific and testable
 - Keep the sprint focused — if it's too large (>12 tasks), consider reducing scope
+- Ensure every task description reads as a standalone implementation brief — not a summary
 
 ## CRITICAL: Task Isolation Validation
 
@@ -5781,7 +5972,7 @@ Your entire response must be a single JSON object — no text before it, no text
   "tasks": [
     {
       "title": "string",
-      "description": "string",
+      "description": "string (detailed implementation guide: what to do, where to do it, how to do it, and boundaries)",
       "assigneeRole": "BACKEND | FRONTEND | QA | PM | DESIGN",
       "priority": "CRITICAL | HIGH | MEDIUM | LOW",
       "labels": ["string"],
@@ -5837,7 +6028,7 @@ ${input.codebaseIndex || "No codebase index available."}
 Analyze the CEO's directive and produce a detailed task breakdown. For each task:
 
 1. **Title** — Clear, action-oriented (e.g., "Implement user registration API endpoint")
-2. **Description** — What needs to be done technically, which files/modules are involved
+2. **Description** — A detailed, actionable implementation guide (see description requirements below)
 3. **Assignee Role** — Who should work on this: BACKEND, FRONTEND, QA, PM, or DESIGN
 4. **Priority** — HIGH, MEDIUM, or LOW based on business impact
 5. **Labels** — Relevant tags (e.g., "api", "database", "ui", "auth")
@@ -5849,6 +6040,19 @@ Think about:
 - What the right granularity is (not too big, not too small)
 - What risks or unknowns exist
 
+## CRITICAL: Task Description Requirements
+
+Each task description will be handed to an INDEPENDENT agent as its primary instruction. The agent will have access to the codebase but NO context about the planning meeting. Descriptions must be clear enough for the agent to execute the task without ambiguity.
+
+Each description MUST include:
+1. **What to do** — Clearly state the goal and what needs to be implemented, changed, or created. Be specific about the expected behavior or outcome.
+2. **Where to do it** — List the specific files, modules, or directories that need to be modified or created. Reference existing code paths when extending functionality.
+3. **How to do it** — Provide key implementation details: which patterns to follow, which existing utilities or services to use, what the data flow looks like.
+4. **Boundaries** — Clarify what is NOT in scope for this task to prevent overlap with other tasks.
+
+Bad example: "Add authentication to the API."
+Good example: "Implement JWT-based authentication middleware in src/middleware/auth.ts. Create a verifyToken middleware that extracts the Bearer token from the Authorization header, validates it using the existing JWT_SECRET from env config, and attaches the decoded user payload to req.user. Apply this middleware to all routes in src/routes/protected/. Add a POST /auth/login endpoint in src/routes/auth.ts that accepts {email, password}, validates credentials against the users table, and returns a signed JWT. This task does NOT include user registration or password reset — those are handled separately."
+
 ## CRITICAL: Task Isolation Rules
 
 Tasks will be executed by INDEPENDENT agents on SEPARATE git branches that get merged together. Each agent has NO knowledge of what other agents are doing. Therefore:
@@ -5867,7 +6071,7 @@ Your entire response must be a single JSON object — no text before it, no text
   "tasks": [
     {
       "title": "string",
-      "description": "string (2-4 sentences)",
+      "description": "string (detailed implementation guide: what to do, where to do it, how to do it, and boundaries — see description requirements above)",
       "assigneeRole": "BACKEND | FRONTEND | QA | PM | DESIGN",
       "priority": "HIGH | MEDIUM | LOW",
       "labels": ["string"],

package/dist/orchestrator/tier-merge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tier-merge.d.ts","sourceRoot":"","sources":["../../src/orchestrator/tier-merge.ts"],"names":[],"mappings":"AAMA;;;;;;;;;GASG;AACH,qBAAa,gBAAgB;IAKzB,OAAO,CAAC,WAAW;IACnB,OAAO,CAAC,QAAQ;IALlB,yDAAyD;IACzD,OAAO,CAAC,WAAW,CAAoC;gBAG7C,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,GAAG,IAAI;IAGjC;;OAEG;IACH,iBAAiB,CAAC,KAAK,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC,GAAG,IAAI;IAY3E;;;OAGG;IACH,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAKpC;;OAEG;IACH,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAiB3C;;;;;;;;OAQG;IACH,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IA0ElE;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IAkC5B,OAAO,CAAC,OAAO;CAOhB"}
+{"version":3,"file":"tier-merge.d.ts","sourceRoot":"","sources":["../../src/orchestrator/tier-merge.ts"],"names":[],"mappings":"AAMA;;;;;;;;;GASG;AACH,qBAAa,gBAAgB;IAKzB,OAAO,CAAC,WAAW;IACnB,OAAO,CAAC,QAAQ;IALlB,yDAAyD;IACzD,OAAO,CAAC,WAAW,CAAoC;gBAG7C,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,GAAG,IAAI;IAGjC;;OAEG;IACH,iBAAiB,CAAC,KAAK,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC,GAAG,IAAI;IAY3E;;;OAGG;IACH,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAKpC;;OAEG;IACH,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAiB3C;;;;;;;;OAQG;IACH,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IA0ElE;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IA0C5B,OAAO,CAAC,OAAO;CAOhB"}

package/dist/planning/agents/architect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"architect.d.ts","sourceRoot":"","sources":["../../../src/planning/agents/architect.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CA8ElE"}
+{"version":3,"file":"architect.d.ts","sourceRoot":"","sources":["../../../src/planning/agents/architect.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CA+ElE"}

package/dist/planning/agents/cross-task-reviewer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cross-task-reviewer.d.ts","sourceRoot":"","sources":["../../../src/planning/agents/cross-task-reviewer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,sBAAsB,GAC5B,MAAM,CA6HR"}
+{"version":3,"file":"cross-task-reviewer.d.ts","sourceRoot":"","sources":["../../../src/planning/agents/cross-task-reviewer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,sBAAsB,GAC5B,MAAM,CAuIR"}

package/dist/planning/agents/sprint-organizer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sprint-organizer.d.ts","sourceRoot":"","sources":["../../../src/planning/agents/sprint-organizer.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,oBAAoB,GAC1B,MAAM,CAwFR"}
+{"version":3,"file":"sprint-organizer.d.ts","sourceRoot":"","sources":["../../../src/planning/agents/sprint-organizer.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,oBAAoB,GAC1B,MAAM,CA0FR"}

package/dist/planning/agents/tech-lead.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tech-lead.d.ts","sourceRoot":"","sources":["../../../src/planning/agents/tech-lead.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAuEhE"}
+{"version":3,"file":"tech-lead.d.ts","sourceRoot":"","sources":["../../../src/planning/agents/tech-lead.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAoFhE"}

package/dist/worktree/worktree-config.d.ts

@@ -52,6 +52,8 @@ export interface CreateWorktreeResult {
     branch: string;
     /** Base branch used to create the task branch */
     baseBranch: string;
+    /** Commit hash of the base branch at worktree creation time */
+    baseCommitHash: string;
 }
 /** Default worktree configuration */
 export declare const DEFAULT_WORKTREE_CONFIG: WorktreeConfig;