taskplane 0.3.0 → 0.4.0

package/extensions/taskplane/types.ts

@@ -36,6 +36,8 @@ export interface OrchestratorConfig {
 		tools: string;
 		verify: string[];
 		order: "fewest-files-first" | "sequential";
+		/** Merge agent timeout in minutes. Default: 10. Increase for large batches. */
+		timeout_minutes: number;
 	};
 	failure: {
 		on_task_failure: "skip-dependents" | "stop-wave" | "stop-all";
@@ -168,6 +170,7 @@ export const DEFAULT_ORCHESTRATOR_CONFIG: OrchestratorConfig = {
 		tools: "read,write,edit,bash,grep,find,ls",
 		verify: [],
 		order: "fewest-files-first",
+		timeout_minutes: 10,
 	},
 	failure: {
 		on_task_failure: "skip-dependents",
@@ -1049,7 +1052,8 @@ export class MergeError extends Error {
  * Merge agents typically complete in 10-60 seconds. A 5-minute timeout
  * is generous and covers verification (go build) on large codebases.
  */
-export const MERGE_TIMEOUT_MS = 5 * 60 * 1000;
+/** Default merge agent timeout. Use config.merge.timeout_minutes to override. */
+export const MERGE_TIMEOUT_MS = 10 * 60 * 1000;
 
 /**
  * Polling interval for merge result file (ms).
@@ -1796,6 +1800,14 @@ export interface ExecutionContext {
 	taskRunnerConfig: TaskRunnerConfig;
 	/** Loaded orchestrator configuration */
 	orchestratorConfig: OrchestratorConfig;
+	/**
+	 * Resolved pointer for config/agent paths (null in repo mode).
+	 *
+	 * When present, `pointer.configRoot` and `pointer.agentRoot` point to
+	 * the config repo's config directory. State/sidecar paths are NOT
+	 * affected — they always live at `<workspaceRoot>/.pi/`.
+	 */
+	pointer: PointerResolution | null;
 }
 
 
@@ -1861,6 +1873,73 @@ export class WorkspaceConfigError extends Error {
 }
 
 
+// ── Pointer Resolution Types ─────────────────────────────────────────
+
+/**
+ * Canonical filename for the workspace pointer file.
+ * Located at `<workspace-root>/.pi/taskplane-pointer.json`.
+ *
+ * Created by `taskplane init` in workspace mode. Points to the config
+ * repo and config path within it. Not committed to git — each user
+ * creates it during onboarding.
+ */
+export const POINTER_FILENAME = "taskplane-pointer.json";
+
+/**
+ * Resolve the absolute path to the pointer file.
+ * @param workspaceRoot - Absolute path to the workspace root
+ */
+export function pointerFilePath(workspaceRoot: string): string {
+	return join(workspaceRoot, ".pi", POINTER_FILENAME);
+}
+
+/**
+ * Result of resolving the workspace pointer file.
+ *
+ * This is the primary contract for downstream consumers (task-runner,
+ * orchestrator, merge agent, dashboard). All pointer failures are
+ * non-fatal: when the pointer cannot be resolved, `used` is false and
+ * `configRoot`/`agentRoot` fall back to workspace-root paths.
+ *
+ * State/sidecar paths are NOT affected by the pointer — they always
+ * live at `<workspace-root>/.pi/` regardless of pointer resolution.
+ *
+ * In repo mode, `resolvePointer()` returns null (pointer is ignored
+ * entirely, even if a file happens to exist).
+ */
+export interface PointerResolution {
+	/**
+	 * Whether the pointer was successfully resolved.
+	 * - true: pointer file was found, parsed, and config_repo resolved
+	 *   to a known repo in WorkspaceConfig.repos.
+	 * - false: pointer was missing, malformed, or referenced an unknown
+	 *   repo. Fallback paths are used instead.
+	 */
+	used: boolean;
+
+	/**
+	 * Resolved config root directory.
+	 * - When used=true: `<config-repo-path>/<config_path>/`
+	 * - When used=false: `<workspace-root>/.pi/` (existing fallback)
+	 */
+	configRoot: string;
+
+	/**
+	 * Resolved agent overrides directory.
+	 * - When used=true: `<config-repo-path>/<config_path>/agents/`
+	 * - When used=false: `<workspace-root>/.pi/agents/` (existing fallback)
+	 */
+	agentRoot: string;
+
+	/**
+	 * Warning message when pointer resolution fell back.
+	 * - undefined when used=true (no warning)
+	 * - Human-readable reason string when used=false
+	 */
+	warning?: string;
+}
+
+
 // ── Workspace Defaults ───────────────────────────────────────────────
 
 /**
@@ -1900,6 +1979,7 @@ export function createRepoModeContext(
 		workspaceConfig: null,
 		taskRunnerConfig,
 		orchestratorConfig,
+		pointer: null,
 	};
 }
 

package/extensions/taskplane/workspace.ts

@@ -37,16 +37,18 @@
  * @module orch/workspace
  */
 import { readFileSync, existsSync, realpathSync } from "fs";
-import { resolve } from "path";
+import { resolve, relative, isAbsolute } from "path";
 import { parse as yamlParse } from "yaml";
 
 import { runGit } from "./git.ts";
 import {
 	WorkspaceConfigError,
 	workspaceConfigPath,
+	pointerFilePath,
 	type WorkspaceConfig,
 	type WorkspaceRepoConfig,
 	type WorkspaceRoutingConfig,
+	type PointerResolution,
 } from "./types.ts";
 
 
@@ -94,6 +96,185 @@ function resolveAbsolutePath(p: string, base: string): string {
 }
 
 
+// ── Pointer Resolution ───────────────────────────────────────────────
+
+/**
+ * Resolve the workspace pointer file to find config and agent roots.
+ *
+ * The pointer file (`<workspace-root>/.pi/taskplane-pointer.json`) tells
+ * Taskplane where to find project config and agent overrides in workspace
+ * (polyrepo) mode. It's created by `taskplane init` and is local-only
+ * (not committed to git).
+ *
+ * **Repo mode:** Returns null. The pointer is workspace-only — in repo
+ * mode it is never read, even if a file happens to exist on disk.
+ *
+ * **Workspace mode:** Reads and validates the pointer, then resolves
+ * config and agent roots. All failures are non-fatal:
+ * - Missing pointer file → warn + fallback
+ * - Malformed JSON → warn + fallback
+ * - Missing required fields → warn + fallback
+ * - Unknown config_repo (not in WorkspaceConfig.repos) → warn + fallback
+ * - Path traversal in config_path → warn + fallback
+ *
+ * Fallback paths: `<workspace-root>/.pi/` for config,
+ * `<workspace-root>/.pi/agents/` for agents.
+ *
+ * State/sidecar paths are NOT affected by the pointer and are not
+ * included in the return value — they always live at
+ * `<workspace-root>/.pi/` regardless.
+ *
+ * @param workspaceRoot - Absolute path to the workspace root directory
+ * @param workspaceConfig - Loaded workspace config (null = repo mode → returns null)
+ * @returns PointerResolution with resolved paths, or null in repo mode
+ */
+export function resolvePointer(
+	workspaceRoot: string,
+	workspaceConfig: WorkspaceConfig | null,
+): PointerResolution | null {
+	// ── Repo mode: pointer is ignored entirely ───────────────────
+	if (workspaceConfig === null) {
+		return null;
+	}
+
+	const fallbackConfigRoot = resolve(workspaceRoot, ".pi");
+	const fallbackAgentRoot = resolve(workspaceRoot, ".pi", "agents");
+
+	const filePath = pointerFilePath(workspaceRoot);
+
+	// ── 1. File existence ────────────────────────────────────────
+	if (!existsSync(filePath)) {
+		return {
+			used: false,
+			configRoot: fallbackConfigRoot,
+			agentRoot: fallbackAgentRoot,
+			warning: `Pointer file not found: ${filePath}. Run 'taskplane init' to create it.`,
+		};
+	}
+
+	// ── 2. Read file ─────────────────────────────────────────────
+	let rawContent: string;
+	try {
+		rawContent = readFileSync(filePath, "utf-8");
+	} catch (err: unknown) {
+		const msg = err instanceof Error ? err.message : String(err);
+		return {
+			used: false,
+			configRoot: fallbackConfigRoot,
+			agentRoot: fallbackAgentRoot,
+			warning: `Cannot read pointer file ${filePath}: ${msg}`,
+		};
+	}
+
+	// ── 3. Parse JSON ────────────────────────────────────────────
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(rawContent);
+	} catch {
+		return {
+			used: false,
+			configRoot: fallbackConfigRoot,
+			agentRoot: fallbackAgentRoot,
+			warning: `Pointer file ${filePath} contains invalid JSON.`,
+		};
+	}
+
+	// ── 4. Validate shape ────────────────────────────────────────
+	if (parsed == null || typeof parsed !== "object" || Array.isArray(parsed)) {
+		return {
+			used: false,
+			configRoot: fallbackConfigRoot,
+			agentRoot: fallbackAgentRoot,
+			warning: `Pointer file ${filePath} must be a JSON object.`,
+		};
+	}
+
+	const doc = parsed as Record<string, unknown>;
+	const configRepo = doc.config_repo;
+	const configPath = doc.config_path;
+
+	if (!configRepo || typeof configRepo !== "string" || configRepo.trim() === "") {
+		return {
+			used: false,
+			configRoot: fallbackConfigRoot,
+			agentRoot: fallbackAgentRoot,
+			warning: `Pointer file ${filePath} is missing required field 'config_repo'.`,
+		};
+	}
+
+	if (!configPath || typeof configPath !== "string" || configPath.trim() === "") {
+		return {
+			used: false,
+			configRoot: fallbackConfigRoot,
+			agentRoot: fallbackAgentRoot,
+			warning: `Pointer file ${filePath} is missing required field 'config_path'.`,
+		};
+	}
+
+	// ── 5. Guard path traversal ──────────────────────────────────
+	const normalizedConfigPath = configPath.trim().replace(/\\/g, "/");
+
+	// Reject absolute paths (POSIX `/...` and Windows `C:/...`, `\\...`)
+	if (isAbsolute(normalizedConfigPath) || isAbsolute(configPath.trim())) {
+		return {
+			used: false,
+			configRoot: fallbackConfigRoot,
+			agentRoot: fallbackAgentRoot,
+			warning: `Pointer file ${filePath} has invalid config_path '${configPath}' (absolute paths not allowed).`,
+		};
+	}
+
+	// Reject traversal sequences
+	if (
+		normalizedConfigPath.startsWith("..") ||
+		normalizedConfigPath.includes("/../") ||
+		normalizedConfigPath.endsWith("/..")
+	) {
+		return {
+			used: false,
+			configRoot: fallbackConfigRoot,
+			agentRoot: fallbackAgentRoot,
+			warning: `Pointer file ${filePath} has invalid config_path '${configPath}' (path traversal not allowed).`,
+		};
+	}
+
+	// ── 6. Resolve config_repo against workspace repos map ──────
+	const repoId = configRepo.trim();
+	const repoConfig = workspaceConfig.repos.get(repoId);
+	if (!repoConfig) {
+		const available = Array.from(workspaceConfig.repos.keys()).join(", ");
+		return {
+			used: false,
+			configRoot: fallbackConfigRoot,
+			agentRoot: fallbackAgentRoot,
+			warning: `Pointer file ${filePath}: config_repo '${repoId}' not found in workspace repos. Available repos: ${available}`,
+		};
+	}
+
+	// ── 7. Build resolved paths + containment check ──────────────
+	const resolvedConfigRoot = resolve(repoConfig.path, normalizedConfigPath);
+
+	// Verify the resolved path is within the repo root (defense-in-depth)
+	const rel = relative(repoConfig.path, resolvedConfigRoot);
+	if (rel.startsWith("..") || isAbsolute(rel)) {
+		return {
+			used: false,
+			configRoot: fallbackConfigRoot,
+			agentRoot: fallbackAgentRoot,
+			warning: `Pointer file ${filePath} has invalid config_path '${configPath}' (resolved path escapes config repo root).`,
+		};
+	}
+
+	const resolvedAgentRoot = resolve(resolvedConfigRoot, "agents");
+
+	return {
+		used: true,
+		configRoot: resolvedConfigRoot,
+		agentRoot: resolvedAgentRoot,
+	};
+}
+
+
 // ── Workspace Config Loading ─────────────────────────────────────────
 
 /**
@@ -366,34 +547,47 @@ export function loadWorkspaceConfig(workspaceRoot: string): WorkspaceConfig | nu
  */
 export function buildExecutionContext(
 	cwd: string,
-	loadOrchConfig: (root: string) => import("./types.ts").OrchestratorConfig,
-	loadTaskConfig: (root: string) => import("./types.ts").TaskRunnerConfig,
+	loadOrchConfig: (root: string, pointerConfigRoot?: string) => import("./types.ts").OrchestratorConfig,
+	loadTaskConfig: (root: string, pointerConfigRoot?: string) => import("./types.ts").TaskRunnerConfig,
 ): import("./types.ts").ExecutionContext {
-	const orchestratorConfig = loadOrchConfig(cwd);
-	const taskRunnerConfig = loadTaskConfig(cwd);
-
 	const workspaceConfig = loadWorkspaceConfig(cwd);
 
 	if (workspaceConfig === null) {
-		// Repo mode: cwd is both workspace root and repo root
+		// Repo mode: pointer is ignored entirely. Config loads from cwd.
+		const orchestratorConfig = loadOrchConfig(cwd);
+		const taskRunnerConfig = loadTaskConfig(cwd);
+
 		return {
 			workspaceRoot: cwd,
 			repoRoot: cwd,
 			mode: "repo",
 			workspaceConfig: null,
-			taskRunnerConfig,
 			orchestratorConfig,
+			taskRunnerConfig,
+			pointer: null,
 		};
 	}
 
-	// Workspace mode: workspace root is cwd, repo root is the default repo
+	// Workspace mode: resolve pointer once, pass configRoot to config loaders.
+	const pointer = resolvePointer(cwd, workspaceConfig);
+
+	// Log pointer warning once at startup (non-fatal).
+	if (pointer && pointer.warning) {
+		console.error(`[taskplane] pointer warning: ${pointer.warning}`);
+	}
+
+	const pointerConfigRoot = pointer?.configRoot;
+	const orchestratorConfig = loadOrchConfig(cwd, pointerConfigRoot);
+	const taskRunnerConfig = loadTaskConfig(cwd, pointerConfigRoot);
+
 	const defaultRepo = workspaceConfig.repos.get(workspaceConfig.routing.defaultRepo)!;
 	return {
 		workspaceRoot: cwd,
 		repoRoot: defaultRepo.path,
 		mode: "workspace",
 		workspaceConfig,
-		taskRunnerConfig,
 		orchestratorConfig,
+		taskRunnerConfig,
+		pointer,
 	};
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taskplane",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "AI agent orchestration for pi — parallel task execution with checkpoint discipline",
   "keywords": [
     "pi-package",

package/skills/create-taskplane-task/SKILL.md

@@ -326,11 +326,13 @@ Verify every task against this before reporting the launch command:
 
 ## Git Commit Convention
 
-The prompt template includes a `## Git Commit Convention` section with the full
-format table (`feat(TASK-ID):`, `fix(TASK-ID):`, `checkpoint: TASK-ID`, etc.).
-Always include it — without task ID prefixes, there's no way to trace commits
-back to the task that produced them (`git log --grep="PM-004"` only works if
-the prefix is there).
+The prompt template includes a `## Git Commit Convention` section. Workers
+commit at **step boundaries** (not after every checkbox) to keep git history
+meaningful. Hydration commits are the exception — STATUS.md expansions are
+committed immediately to preserve the plan for crash recovery. Always include
+the task ID prefix — without it, there's no way to trace commits back to the
+task that produced them (`git log --grep="PM-004"` only works if the prefix
+is there).
 
 ---
 

package/skills/create-taskplane-task/references/prompt-template.md

@@ -118,12 +118,13 @@ Copy this template when creating a new task. Replace all `[bracketed]` fields.
 
 ## Git Commit Convention
 
-All commits for this task MUST include the task ID for traceability:
+Commits happen at **step boundaries** (not after every checkbox). All commits
+for this task MUST include the task ID for traceability:
 
-- **Implementation:** `feat([PREFIX-###]): description`
+- **Step completion:** `feat([PREFIX-###]): complete Step N — description`
 - **Bug fixes:** `fix([PREFIX-###]): description`
 - **Tests:** `test([PREFIX-###]): description`
-- **Checkpoints:** `checkpoint: [PREFIX-###] description`
+- **Hydration:** `hydrate: [PREFIX-###] expand Step N checkboxes`
 
 ## Do NOT
 

package/templates/agents/local/task-merger.md

@@ -0,0 +1,27 @@
+---
+name: task-merger
+# tools: read,write,edit,bash,grep,find,ls
+# model:
+# standalone: true
+---
+
+<!-- ═══════════════════════════════════════════════════════════════════
+  Project-Specific Merger Guidance
+
+  This file is COMPOSED with the base task-merger prompt shipped in the
+  taskplane package. Your content here is appended after the base prompt.
+
+  The base prompt (maintained by taskplane) handles:
+  - Branch merge workflow (fast-forward, 3-way, conflict resolution)
+  - Post-merge verification command execution
+  - Result file JSON format and writing conventions
+
+  Add project-specific merge rules below. Common examples:
+  - Post-merge verification commands (build, lint, test)
+  - Conflict resolution preferences
+  - Protected files that should never be auto-merged
+
+  To override frontmatter values (tools, model), uncomment and edit above.
+  To use this file as a FULLY STANDALONE prompt (ignoring the base),
+  uncomment `standalone: true` above and write the complete prompt below.
+═══════════════════════════════════════════════════════════════════ -->

package/templates/agents/local/task-reviewer.md

@@ -0,0 +1,29 @@
+---
+name: task-reviewer
+# tools: read,write,bash,grep,find,ls
+# model: openai/gpt-5.3-codex
+# standalone: true
+---
+
+<!-- ═══════════════════════════════════════════════════════════════════
+  Project-Specific Reviewer Guidance
+
+  This file is COMPOSED with the base task-reviewer prompt shipped in the
+  taskplane package. Your content here is appended after the base prompt.
+
+  The base prompt (maintained by taskplane) handles:
+  - Plan review and code review workflows
+  - Verdict format (APPROVE / REVISE)
+  - Review file output conventions
+  - Plan granularity guidance
+
+  Add project-specific review criteria below. Common examples:
+  - Required test coverage thresholds
+  - Security review checklist items
+  - Architecture constraints to enforce
+  - Performance requirements
+
+  To override frontmatter values (tools, model), uncomment and edit above.
+  To use this file as a FULLY STANDALONE prompt (ignoring the base),
+  uncomment `standalone: true` above and write the complete prompt below.
+═══════════════════════════════════════════════════════════════════ -->

package/templates/agents/local/task-worker.md

@@ -0,0 +1,30 @@
+---
+name: task-worker
+# tools: read,write,edit,bash,grep,find,ls
+# model: anthropic/claude-sonnet-4-20250514
+# standalone: true
+---
+
+<!-- ═══════════════════════════════════════════════════════════════════
+  Project-Specific Worker Guidance
+
+  This file is COMPOSED with the base task-worker prompt shipped in the
+  taskplane package. Your content here is appended after the base prompt.
+
+  The base prompt (maintained by taskplane) handles:
+  - STATUS.md-first workflow and checkpoint discipline
+  - Fresh-context loop behavior and iteration rules
+  - Git commit conventions and .DONE file creation
+  - Review response handling
+
+  Add project-specific rules below. Common examples:
+  - Preferred package manager (pnpm, yarn, bun)
+  - Test commands (make test, npm run test:unit)
+  - Coding standards (linting, formatting)
+  - Framework-specific patterns
+  - Environment or deployment constraints
+
+  To override frontmatter values (tools, model), uncomment and edit above.
+  To use this file as a FULLY STANDALONE prompt (ignoring the base),
+  uncomment `standalone: true` above and write the complete prompt below.
+═══════════════════════════════════════════════════════════════════ -->

package/templates/agents/task-worker.md

@@ -18,45 +18,59 @@ ONLY memory.
 
 ## Checkpoint Discipline (CRITICAL)
 
-After completing EACH checkbox item, you MUST:
+There are two distinct actions: **checking off items** and **git commits**.
+They happen at different cadences.
 
-1. **Edit STATUS.md** to check off the item. Use the `edit` tool:
-   - oldText: `- [ ] The item text`
-   - newText: `- [x] The item text`
+### Checking off items (after EACH checkbox)
 
-2. **Git commit** the checkpoint:
-   ```bash
-   git add -A && git commit -m "checkpoint: <what you did>"
-   ```
-
-3. **Check for wrap-up signal:**
-   ```bash
-   if test -f "<TASK_FOLDER>/.task-wrap-up" || test -f "<TASK_FOLDER>/.wiggum-wrap-up"; then
-     echo "WRAP_UP_SIGNAL"
-   fi
-   ```
-   Primary signal file is `.task-wrap-up`; `.wiggum-wrap-up` is legacy and still supported.
-   If either signal exists, STOP immediately after this checkpoint.
-
-### Example checkpoint sequence:
-
-After verifying that source files exist, immediately do:
+After completing each checkbox item, **immediately update STATUS.md**:
 
 ```
 edit STATUS.md
-  oldText: "- [ ] Verify all source files exist"
-  newText: "- [x] Verify all source files exist"
+  oldText: "- [ ] The item text"
+  newText: "- [x] The item text"
 ```
 
-Then:
+Then **check for wrap-up signal:**
 ```bash
-git add -A && git commit -m "checkpoint: verified source files exist"
+if test -f "<TASK_FOLDER>/.task-wrap-up" || test -f "<TASK_FOLDER>/.wiggum-wrap-up"; then
+  echo "WRAP_UP_SIGNAL"
+fi
 ```
+Primary signal file is `.task-wrap-up`; `.wiggum-wrap-up` is legacy and still supported.
+If either signal exists, STOP immediately after this checkpoint.
 
-**NEVER batch updates.** Check off ONE item, commit, then do the next.
 If you do work but don't edit STATUS.md, that work is INVISIBLE to the
 orchestrator and you will be re-spawned to do it again.
 
+### Git commits (after completing a STEP)
+
+Git commits happen at **step boundaries**, not after every checkbox. When all
+checkboxes in a step are checked off:
+
+```bash
+git add -A && git commit -m "feat(TASK-ID): complete Step N — description"
+```
+
+This keeps the git history meaningful — one coherent commit per step instead of
+dozens of micro-commits that nobody reads.
+
+**Exceptions** — commit immediately (before step completion) in these cases:
+- **Hydration:** After expanding STATUS.md with new checkboxes, commit before
+  implementing: `git add -A && git commit -m "hydrate: expand Step N checkboxes"`
+- **REVISE response:** After adding reviewer revision items to STATUS.md:
+  `git add -A && git commit -m "hydrate: add R00N revision items to Step N"`
+- **Wrap-up signal:** If stopping mid-step due to a wrap-up signal, commit
+  whatever is done so far.
+
+### Why this approach
+
+STATUS.md is the worker's memory, not git. Checking off items in STATUS.md
+ensures the next worker iteration knows where to resume. Git commits preserve
+file changes at meaningful milestones. Per-checkbox commits waste tool calls
+on git housekeeping without adding recovery value — the files are already on
+disk in the worktree.
+
 ## STATUS.md Hydration (MANDATORY)
 
 STATUS.md is your ONLY memory. It needs enough structure so progress survives
@@ -85,7 +99,7 @@ Before implementing anything, assess whether the step needs expansion:
 3. **If expansion is needed**, add checkboxes for **distinct outcomes** you've
    identified — not for every individual code change. Think: "what are the 2-5
    things that need to be true when this step is done?"
-4. **Commit the hydrated STATUS.md immediately** — this IS a checkpoint:
+4. **Commit the hydrated STATUS.md immediately** (see Checkpoint Discipline exceptions):
    ```bash
    git add -A && git commit -m "hydrate: expand Step N checkboxes"
    ```
@@ -104,7 +118,7 @@ When a reviewer returns REVISE with specific feedback items:
 1. **Read the review file** in `.reviews/`
 2. **Add revision items as new checkboxes** in the current step — group related
    fixes into single checkboxes rather than creating one per reviewer sentence
-3. **Commit the hydrated STATUS.md:**
+3. **Commit the hydrated STATUS.md** (see Checkpoint Discipline exceptions):
    ```bash
    git add -A && git commit -m "hydrate: add R00N revision items to Step N"
    ```
@@ -112,9 +126,9 @@ When a reviewer returns REVISE with specific feedback items:
 
 ### Rules
 
-- **Hydration is a checkpoint.** Always commit STATUS.md after hydrating, before
-  implementing. If the iteration ends between hydration and implementation, the
-  plan is preserved for the next worker.
+- **Hydration gets an immediate commit.** Always commit STATUS.md after hydrating,
+  before implementing. If the iteration ends between hydration and implementation,
+  the plan is preserved for the next worker.
 - **One checkbox per meaningful outcome.** "Implement the CRUD methods" is one
   checkbox if they're straightforward. "Implement create + implement delete" is
   two checkboxes if they involve genuinely different logic. Use judgment — the

package/templates/config/task-orchestrator.yaml

@@ -76,6 +76,9 @@ merge:
 
   order: "fewest-files-first"
 
+  # Merge agent timeout in minutes. Increase for large batches with many files.
+  timeout_minutes: 10
+
 # ── Failure Handling ──────────────────────────────────────────────────
 
 failure: