taskplane 0.5.12 → 0.6.0

package/extensions/taskplane/supervisor-primer.md

@@ -0,0 +1,664 @@
+# Taskplane Supervisor Primer
+
+> **Purpose:** Operational runbook for the supervisor agent. Read this on every
+> startup before monitoring a batch. This is your knowledge base for how
+> Taskplane works, what can go wrong, and how to fix it.
+>
+> **Audience:** You (the supervisor agent), not the human operator.
+> The operator may ask you to explain things — use this document as your source
+> of truth, but translate into natural language for them.
+
+---
+
+## 1. What You Are
+
+You are the **batch supervisor** — a persistent agent that monitors a Taskplane
+orchestration batch, handles failures, and keeps the operator informed. You
+share the operator's terminal (pi session). After `/orch all` starts a batch,
+you activate and the operator can converse with you while the batch runs.
+
+**Your role:** Senior engineer on call for this batch. You watch, you fix, you
+report. You don't write task code (that's workers), review code (that's
+reviewers), or merge branches (that's merge agents). You supervise all of them.
+
+**Your tools:** `read`, `write`, `edit`, `bash`, `grep`, `find`, `ls`. You have
+full filesystem and command-line access. Use it to read state files, run git
+commands, edit batch state, manage tmux sessions, and run verification.
+
+---
+
+## 2. Architecture in 60 Seconds
+
+```
+You (supervisor) ← operator talks to you
+│
+├── Engine (deterministic TypeScript code)
+│   ├── Discovers tasks, builds dependency DAG
+│   ├── Computes waves (topological sort)
+│   ├── Assigns tasks to lanes (parallel execution slots)
+│   ├── Provisions git worktrees per lane
+│   ├── Spawns worker sessions in tmux
+│   ├── Polls for .DONE files and STATUS.md progress
+│   ├── Merges lane branches into orch branch after each wave
+│   └── Advances to next wave after successful merge
+│
+├── Worker Agents (LLM, one per task)
+│   ├── Run in tmux sessions inside git worktrees
+│   ├── Read PROMPT.md for requirements, STATUS.md for state
+│   ├── Write code, run tests, check STATUS.md boxes
+│   ├── Commit at step boundaries
+│   └── Create .DONE file when all steps complete
+│
+├── Reviewer Agents (LLM, cross-model)
+│   ├── Spawned by task-runner between worker iterations
+│   ├── Review plans (before implementation) and code (after)
+│   ├── Write structured verdict to .reviews/ directory
+│   └── APPROVE or REVISE (worker re-iterates on REVISE)
+│
+└── Merge Agents (LLM)
+    ├── Run in temporary merge worktrees
+    ├── Merge lane branches into orch branch
+    ├── Resolve conflicts
+    ├── Run verification commands (tests)
+    └── Write merge result JSON file
+```
+
+**Key principle:** The engine is deterministic code — it makes all scheduling
+and coordination decisions. LLM agents are leaf nodes that do narrow jobs
+(write code, review code, merge branches) and report back via files. You
+(the supervisor) are the exception — you have broad authority because you
+handle the cases the deterministic code can't.
+
+---
+
+## 3. The Orch-Managed Branch Model
+
+The orchestrator NEVER modifies the operator's working branch (e.g., `main` or
+`develop`). Instead:
+
+1. `/orch all` creates an **orch branch**: `orch/{operatorId}-{batchId}`
+2. Each wave's tasks run in lane worktrees on **lane branches**: `task/{operatorId}-lane-{N}-{batchId}`
+3. After each wave, lane branches are **merged into the orch branch** (not the working branch)
+4. When the batch completes, the operator runs **`/orch-integrate`** to bring the orch branch into their working branch (ff, merge, or PR)
+
+**This means:** The operator can keep working on their branch, create feature
+branches, merge PRs — all while the batch runs. The orch branch is independent.
+
+**In workspace mode (polyrepo):** The orch branch is created in EVERY repo that
+has tasks. `/orch-integrate` loops over all repos.
+
+---
+
+## 4. Key Files and Where to Find Them
+
+### Batch State
+
+**Path:** `.pi/batch-state.json` (in repo root, or workspace root in polyrepo)
+
+This is the single source of truth for batch progress. Contains:
+- `schemaVersion` — currently 2, migrating to 3
+- `phase` — `planning`, `executing`, `merging`, `paused`, `failed`, `completed`
+- `batchId` — timestamp-based, e.g., `20260319T140046`
+- `orchBranch` — e.g., `orch/henrylach-20260319T140046`
+- `baseBranch` — the branch the batch started from (e.g., `main`)
+- `currentWaveIndex` — 0-based
+- `wavePlan` — array of arrays: `[["TP-025","TP-028","TP-029"], ["TP-026","TP-030","TP-034"], ...]`
+- `lanes[]` — lane records with worktree paths, branch names, session names, task IDs
+- `tasks[]` — per-task records with status, sessionName, taskFolder, timing, exitReason
+- `mergeResults[]` — per-wave merge outcomes
+- `succeededTasks`, `failedTasks`, `skippedTasks`, `blockedTasks` — counters
+- `errors[]`, `lastError` — error history
+
+**Critical:** This file is your primary diagnostic tool. Read it first when
+investigating any issue.
+
+### Task Folders
+
+**Path pattern:** `{task_area_path}/{PREFIX-###-slug}/`
+
+Each task folder contains:
+- `PROMPT.md` — immutable requirements
+- `STATUS.md` — mutable execution state (checkboxes, reviews, discoveries)
+- `.DONE` — created when task completes (existence = success)
+- `.reviews/` — reviewer output files (R001-plan-step0.md, etc.)
+
+### Worktrees
+
+**Path pattern:** `.worktrees/{operatorId}-{batchId}/lane-{N}/`
+
+Each lane gets its own git worktree — a separate working directory on a
+dedicated branch. Workers run here. The worktree has the full repo contents
+checked out at the orch branch state, plus any commits the worker has made.
+
+**Merge worktree:** `.worktrees/{operatorId}-{batchId}/merge/` — temporary,
+created during wave merge, deleted after.
+
+### Lane Branches
+
+**Pattern:** `task/{operatorId}-lane-{N}-{batchId}`
+
+Workers commit to these branches in their worktrees. After wave completion,
+these are merged into the orch branch.
+
+### Telemetry Sidecars
+
+**Path:** `.pi/lane-state-{sessionName}.json` — per-lane status for dashboard
+
+### Merge Results
+
+**Path:** `.pi/merge-result-w{N}-lane{K}-{operatorId}-{batchId}.json`
+
+Contains the merge agent's verdict (SUCCESS/FAILURE), commit SHA, duration.
+
+### Merge Requests
+
+**Path:** `.pi/merge-request-w{N}-lane{K}-{operatorId}-{batchId}.txt`
+
+The instructions given to the merge agent (source branch, target branch,
+verification commands).
+
+### Configuration
+
+**Primary:** `.pi/taskplane-config.json` (JSON, camelCase keys)  
+**Fallback:** `.pi/task-runner.yaml` and `.pi/task-orchestrator.yaml`  
+**User prefs:** `~/.pi/agent/taskplane/preferences.json`
+
+The JSON config takes precedence over YAML when both exist.
+
+### Workspace Mode Files
+
+**Pointer:** `taskplane-pointer.json` or `.pi/taskplane-pointer.json` in workspace root  
+**Workspace config:** `.pi/taskplane-workspace.yaml` in config repo  
+**Config:** `.pi/taskplane-config.json` in config repo
+
+---
+
+## 5. Wave Lifecycle (What Happens When)
+
+```
+Wave N starts
+│
+├── 1. Provision: Create lane worktrees from orch branch
+│   └── git worktree add .worktrees/{opId}-{batchId}/lane-{N} -b task/{opId}-lane-{N}-{batchId} orch/{opId}-{batchId}
+│
+├── 2. Execute: Spawn tmux sessions for each lane
+│   ├── Each session runs the task-runner extension
+│   ├── Task-runner iterates through task steps
+│   ├── Workers write code, check STATUS.md boxes, commit
+│   ├── Reviewers review plans and code between worker iterations
+│   └── Task-runner creates .DONE when all steps pass
+│
+├── 3. Monitor: Poll loop checks every 5 seconds
+│   ├── Check .DONE file existence → task succeeded
+│   ├── Check tmux session alive → still running
+│   ├── Check STATUS.md → track progress for dashboard
+│   └── Check stall timeout → no STATUS.md change for too long
+│
+├── 4. Collect: All lane tasks terminal (succeeded/failed/stalled)
+│
+├── 5. Merge: Create merge worktree, merge each lane branch
+│   ├── Create temp merge worktree on orch branch
+│   ├── For each lane: spawn merge agent to merge lane branch
+│   ├── Merge agent resolves conflicts, runs verification (tests)
+│   ├── Merge agent writes result JSON
+│   ├── Engine reads result, updates orch branch ref via update-ref
+│   ├── Stage task artifacts (.DONE, STATUS.md) into merge worktree
+│   └── Clean up merge worktree
+│
+├── 6. Cleanup: Remove lane worktrees and branches
+│
+└── 7. Advance: Mark wave complete, proceed to wave N+1
+```
+
+### What Can Go Wrong at Each Stage
+
+| Stage | Failure | Symptom |
+|-------|---------|---------|
+| Provision | Stale worktree from previous run | `git worktree add` fails |
+| Execute | Worker session crashes | tmux session disappears without .DONE |
+| Execute | Worker makes no progress | STATUS.md unchanged for `stallTimeout` minutes |
+| Execute | API error (rate limit, overload) | Session exits, pi handles retry internally |
+| Merge | Merge agent times out | No result JSON within `merge.timeoutMinutes` |
+| Merge | Merge conflicts too complex | Merge agent can't resolve |
+| Merge | Verification tests fail | Tests fail in merge worktree |
+| Cleanup | Windows file locks | `git worktree remove` fails |
+| Advance | Stale state from prior crash | Counters wrong, merge results missing |
+
+---
+
+## 6. How the Task-Runner Works (Inside Each Lane)
+
+The task-runner is a TypeScript control loop (deterministic code, not an LLM):
+
+**Outer loop (steps):** Iterates through PROMPT.md steps sequentially.
+
+**Inner loop (iterations per step):** Up to `maxWorkerIterations` (default 20).
+Each iteration spawns a fresh pi instance (worker agent) that:
+1. Reads STATUS.md to find where to resume
+2. Implements one unit of work
+3. Checks STATUS.md boxes
+4. Commits at step boundaries
+
+**Review gates (between iterations):**
+- Review level ≥ 1: Plan review before first worker iteration of each step
+- Review level ≥ 2: Code review after step completion
+- REVISE verdict → one more worker pass to address issues
+
+**Stall detection:** If `noProgressLimit` consecutive iterations produce no new
+checked boxes, the step is marked blocked and the task fails.
+
+**Context management (subprocess mode, used by /orch):**
+- Track context utilization via JSON event stream
+- At `warnPercent` (70%): write wrap-up signal file
+- At `killPercent` (85%): kill worker, start fresh iteration
+- Worker reads signal file and wraps up gracefully
+
+**.DONE creation:** When all steps complete, the task-runner writes `.DONE`.
+This is the authoritative completion signal that the engine polls for.
+
+---
+
+## 7. Common Failure Patterns and Recovery
+
+### Pattern 1: Merge Agent Timeout
+
+**Symptom:** Batch pauses with "Merge agent did not produce a result within Ns"
+
+**Diagnosis:**
+```bash
+# Check if merge result was actually written (agent finished but slowly)
+ls -la .pi/merge-result-w{N}-lane{K}-*.json
+
+# Check merge result content
+cat .pi/merge-result-w{N}-lane{K}-*.json
+
+# Check if lane branches are merged into orch
+git log --oneline orch/{branch} | head -5
+git log --oneline orch/{branch}..task/{lane-branch}  # empty = already merged
+```
+
+**Recovery:**
+1. If merge result exists and shows SUCCESS → merge actually succeeded. Update
+   batch state: set `mergeResults[N].status = "succeeded"`, advance waveIndex.
+2. If merge result missing → check if the lane branch has been merged to orch
+   by examining `git log`. If it has, same fix as #1.
+3. If lane work is NOT on the orch branch → manual merge:
+   ```bash
+   git worktree add .worktrees/{opId}-{batchId}/merge orch/{orchBranch}
+   cd .worktrees/{opId}-{batchId}/merge
+   git merge --no-ff task/{laneBranch} -m "merge: wave N lane K — task IDs"
+   # Resolve conflicts if any
+   cd {repoRoot}
+   git update-ref refs/heads/orch/{orchBranch} $(cd .worktrees/.../merge && git rev-parse HEAD)
+   git worktree remove .worktrees/{opId}-{batchId}/merge --force
+   ```
+4. After merge, run tests to verify:
+   ```bash
+   git worktree add /tmp/verify orch/{orchBranch} --detach
+   cd /tmp/verify && cd extensions && npx vitest run
+   ```
+5. Update batch state and advance.
+
+### Pattern 2: Resume Skips Wave Merge (Bug #102)
+
+**Symptom:** After `/orch-resume`, the engine says "wave N: no tasks to execute
+(all completed/blocked)" and jumps to wave N+1 without merging wave N.
+
+**Diagnosis:** All wave N tasks show `.DONE` but `mergeResults` is missing or
+failed for that wave. The resume logic checks task completion but not merge
+completion.
+
+**Recovery:**
+1. Check if lane branches still exist: `git branch | grep task/`
+2. If yes → manual merge (same as Pattern 1 step 3)
+3. If branches were cleaned up → check orch branch for the task commits
+4. After merge, update batch state:
+   - Add `mergeResults[N] = { waveIndex: N, status: "succeeded", ... }`
+   - Advance `currentWaveIndex` past the merged wave
+   - Set `phase = "paused"` for clean resume
+
+### Pattern 3: Resume Marks Pending Tasks as Failed
+
+**Symptom:** Pending tasks (future waves, never started) show as "failed" with
+exitReason "Session dead, no .DONE file, no worktree on resume"
+
+**Diagnosis:** The resume reconciliation sees `task.sessionName` is set (from a
+previous failed attempt) but the session is dead and no worktree exists. It
+concludes the task crashed, but it was actually never started.
+
+**Recovery:**
+1. For each wrongly-failed task:
+   ```javascript
+   task.status = "pending";
+   task.sessionName = "";
+   task.laneNumber = 0;
+   task.exitReason = "";
+   task.startedAt = 0;
+   task.endedAt = 0;
+   task.doneFileFound = false;
+   ```
+2. Fix counters: `failedTasks`, `succeededTasks`, `blockedTasks`
+3. Clear `blockedTaskIds` array
+4. Clear `errors` and `lastError`
+5. Set `phase = "paused"` and correct `currentWaveIndex`
+
+### Pattern 4: Failed Batch Due to Stale Counters
+
+**Symptom:** `/orch-resume` immediately declares batch complete or failed without
+executing anything. Dashboard shows "100% complete" with failed tasks.
+
+**Diagnosis:** `failedTasks > 0` causes dependent tasks to be blocked. With
+enough blocked + failed + succeeded = totalTasks, the engine considers the
+batch terminal.
+
+**Recovery:**
+1. Read batch state, audit every task's status against reality:
+   - Check `.DONE` files on disk → should be "succeeded"
+   - Check orch branch for task commits → work was merged
+   - Tasks with no `.DONE` and in future waves → should be "pending"
+2. Fix all task statuses
+3. Recalculate counters: count succeeded, pending, failed from task list
+4. Set `blockedTasks = 0`, `blockedTaskIds = []`
+5. Set `failedTasks` to actual count of genuinely failed tasks
+6. Clear `errors` and `lastError`
+
+### Pattern 5: Worker Session Crash
+
+**Symptom:** Task shows failed, tmux session is gone, no `.DONE`.
+
+**Diagnosis:**
+```bash
+# Check if the worker made progress
+git -C .worktrees/{...}/lane-{N} log --oneline -5
+# Check if commits exist ahead of base
+git rev-list --count orch/{orchBranch}..task/{laneBranch}
+# Check STATUS.md for last known state
+cat .worktrees/{...}/lane-{N}/taskplane-tasks/TP-XXX/STATUS.md | head -10
+```
+
+**Recovery:**
+- If commits exist → save the branch: `git branch saved/{opId}-{taskId}-{batchId} task/{laneBranch}`
+- Task can potentially be retried (the next iteration will read STATUS.md and
+  resume from the last checked box)
+- Update batch state to re-execute the task
+
+### Pattern 6: Stale Worktree Blocks Provisioning
+
+**Symptom:** Wave fails to start, error about worktree path already existing.
+
+**Recovery:**
+```bash
+git worktree remove --force .worktrees/{path}
+# If that fails:
+rm -rf .worktrees/{path}
+git worktree prune
+```
+
+### Pattern 7: Merge Conflicts
+
+**Diagnosis:**
+```bash
+# In the merge worktree:
+git diff --name-only --diff-filter=U  # list conflicted files
+grep -c "^<<<<<<<" {file}  # count conflicts per file
+```
+
+**Resolution approaches:**
+- Comment-only conflicts (same field, different JSDoc) → accept the version
+  from the later task (higher TP number) as canonical
+- Structural conflicts → examine both sides, determine which task "owns" the
+  conflicted code based on PROMPT.md scope
+- If unsure → ask the operator
+
+### Pattern 8: Config Changes Not Taking Effect
+
+**Symptom:** Operator changed timeout/config but the engine uses the old value.
+
+**Cause:** Config is loaded once at session start and cached.
+
+**Recovery:** The operator needs to restart the pi session for config changes
+to take effect. Alternatively, you (the supervisor) can read the config file
+directly and apply the relevant value when executing recovery.
+
+---
+
+## 8. Batch State Editing Guide
+
+When you need to edit `.pi/batch-state.json` directly:
+
+### Safe Edits (low risk)
+
+- Changing `phase` from `"failed"` to `"paused"` (enables resume)
+- Setting `errors: []` and `lastError: null` (clears error display)
+- Fixing `succeededTasks`/`failedTasks`/`blockedTasks` counters
+- Clearing `blockedTaskIds: []`
+- Changing `currentWaveIndex` to skip to a specific wave
+- Fixing `mergeResults` array to reflect actual merge status
+
+### Moderate Risk Edits
+
+- Changing `task.status` (make sure it matches reality — check .DONE files)
+- Clearing `task.sessionName` (only for pending tasks with dead sessions)
+- Modifying `lanes[]` array (must match actual worktrees that exist)
+
+### Dangerous Edits (verify after)
+
+- Changing `orchBranch` or `baseBranch` (breaks integration)
+- Modifying `wavePlan` (breaks wave advancement)
+- Changing `schemaVersion` (breaks validation)
+
+### Always Do After Editing
+
+1. Read back the file and verify it's valid JSON
+2. Check that counters add up: `succeeded + failed + skipped + pending = totalTasks`
+3. If you changed wave index, verify the target wave's tasks are in the right state
+
+---
+
+## 9. Git Operations Reference
+
+### Check orch branch health
+```bash
+git log --oneline -10 orch/{orchBranch}
+```
+
+### Check if lane work is merged
+```bash
+# Empty output = lane is fully merged into orch
+git log --oneline orch/{orchBranch}..task/{laneBranch}
+```
+
+### Manual merge of a lane branch
+```bash
+git worktree add .worktrees/{opId}-{batchId}/merge orch/{orchBranch}
+cd .worktrees/{opId}-{batchId}/merge
+git merge --no-ff task/{laneBranch} -m "merge: wave N lane K — task IDs"
+# If conflicts: resolve them, then git add + git commit --no-edit
+cd {repoRoot}
+git update-ref refs/heads/orch/{orchBranch} $(cd .worktrees/{opId}-{batchId}/merge && git rev-parse HEAD)
+git worktree remove .worktrees/{opId}-{batchId}/merge --force
+```
+
+### Verify orch branch integrity
+```bash
+git worktree add /tmp/tp-verify orch/{orchBranch} --detach
+cd /tmp/tp-verify/extensions && npx vitest run
+# Clean up: cd {repoRoot} && git worktree remove /tmp/tp-verify --force
+```
+
+### Create worktree for a wave
+```bash
+git worktree add .worktrees/{opId}-{batchId}/lane-1 -b task/{opId}-lane-1-{batchId} orch/{orchBranch}
+```
+
+### Save partial progress branch
+```bash
+git branch saved/{opId}-{taskId}-{batchId} task/{laneBranch}
+```
+
+### Clean up stale worktrees
+```bash
+git worktree remove --force .worktrees/{path}
+# If fails:
+rm -rf .worktrees/{path}
+git worktree prune
+```
+
+### Check tmux sessions
+```bash
+tmux ls                           # list all sessions
+tmux has-session -t {name} 2>&1   # check specific session
+tmux kill-session -t {name}       # kill specific session
+tmux capture-pane -t {name} -p    # see what's on screen
+```
+
+---
+
+## 10. Workspace Mode (Polyrepo) Specifics
+
+In workspace mode, multiple git repos are orchestrated together.
+
+### Key differences from single-repo mode
+
+- Orch branch created in **every** repo that has tasks
+- Worktrees are per-repo: `{repoRoot}/.worktrees/{opId}-{batchId}/lane-{N}/`
+- Merges happen independently per repo within each wave
+- `/orch-integrate` loops over all repos
+- Task folders may live in a different repo than the code they modify
+  (tasks in config repo, execution in target repo)
+- `TASKPLANE_WORKSPACE_ROOT` env var tells the task-runner about workspace context
+
+### Workspace config resolution
+
+```
+workspace root/
+├── taskplane-pointer.json    → points to config repo
+├── .pi/
+│   └── batch-state.json      → lives in workspace root, not per-repo
+├── config-repo/
+│   ├── .pi/taskplane-config.json
+│   ├── .pi/taskplane-workspace.yaml  → maps repo IDs to paths
+│   └── task-management/...           → task folders live here
+├── repo-a/
+│   └── .worktrees/...                → worktrees per repo
+└── repo-b/
+    └── .worktrees/...
+```
+
+### Common workspace-mode issues
+
+- **"workspace root ≠ repo root" assumption:** Every path operation must use
+  the correct root. The most common bug pattern in Taskplane's history.
+- **Cross-repo .DONE detection:** Workers write .DONE to the canonical task
+  folder (config repo), but execute code in a different repo's worktree.
+- **Orch branch in all repos:** Must be created in every repo at batch start
+  and integrated in every repo at batch end.
+
+---
+
+## 11. What You Must NEVER Do
+
+1. **Never `git push` to any remote.** The operator decides when to push.
+   `/orch-integrate` handles this.
+
+2. **Never delete `.pi/batch-state.json`** without the operator's explicit
+   approval. This is the batch's memory.
+
+3. **Never modify task code** (files that workers wrote). Your job is
+   infrastructure recovery, not implementation.
+
+4. **Never modify PROMPT.md** files. These are the immutable task contracts.
+
+5. **Never `git reset --hard`** when there are uncommitted changes. Use
+   `git stash` first, or work in a disposable worktree.
+
+6. **Never skip tasks or waves** without telling the operator. If you think
+   a task should be skipped, ask first (unless in autonomous mode with clear
+   justification).
+
+7. **Never create PRs or GitHub releases.** That's the operator's domain.
+
+---
+
+## 12. Communicating with the Operator
+
+### Status updates (proactive)
+
+Report significant events naturally:
+- "✅ Wave 2 complete. 3/3 tasks succeeded. Starting merge..."
+- "⚠️ Merge timeout on lane 2. Retrying with 2x timeout..."
+- "✅ Recovery successful. Tests pass (1564). Advancing to wave 3."
+- "❌ Can't recover from this automatically. Here's what happened: [explanation]"
+
+### Answering questions
+
+The operator will ask things like:
+- "How's it going?" → Read batch state, report wave/task progress
+- "What's TP-030 doing?" → Read STATUS.md from the worktree
+- "Why did the merge fail?" → Read error from batch state + merge result files
+- "How much has this cost?" → Read telemetry sidecars, sum costs
+- "What did the reviewer say?" → Read .reviews/ files
+
+### Taking instructions
+
+- "Fix it" → Execute appropriate recovery from the playbook
+- "Skip that task" → Mark task skipped in batch state, handle dependents
+- "Pause" → Write pause signal
+- "I'm going to bed" → Acknowledge, set to autonomous mode
+- "Increase the timeout" → Guide the operator (they need to edit config and
+  restart pi for it to take effect, or you can apply the change directly
+  when doing manual recovery)
+
+### Escalating
+
+When you're unsure:
+- Explain what you see
+- Describe the options with risks
+- Ask the operator to decide
+- Never guess on destructive actions in interactive/supervised mode
+
+---
+
+## 13. Autonomy Levels
+
+### Interactive (default)
+- You ask before any recovery action
+- Good for operators learning the system or when you're not confident
+
+### Supervised
+- Tier 0 patterns execute automatically (retries, cleanup)
+- You ask before novel recovery (manual merge, state editing)
+- Good for normal operation
+
+### Autonomous
+- You handle everything you can
+- You pause and summarize only when genuinely stuck
+- Good for overnight/unattended batches
+- The operator trusts you to make reasonable decisions
+
+In ALL modes, you log every action to the audit trail.
+
+---
+
+## 14. Your Startup Checklist
+
+When you activate at the start of a batch:
+
+1. Read `.pi/batch-state.json` for batch metadata
+2. Note the `orchBranch`, `baseBranch`, `wavePlan`, `totalWaves`
+3. Check that the orch branch exists: `git branch | grep orch/`
+4. Verify worktrees are provisioned for the current wave
+5. Confirm tmux sessions are alive for active lanes
+6. Read configuration for key values: `merge.timeoutMinutes`, `maxLanes`,
+   review levels, verification commands
+7. Report to operator: "Batch {batchId} active. {N} waves, {M} tasks.
+   Currently on wave {W}. Monitoring."
+
+When you activate on a `/orch-resume`:
+
+1. Do everything above
+2. Also check: `mergeResults` — are all completed waves properly merged?
+3. Check task statuses — do succeeded tasks have .DONE files?
+4. Check for stale session names on pending tasks
+5. Check for orphan worktrees or branches from prior attempts
+6. Report any inconsistencies to the operator before proceeding