@os-eco/overstory-cli 0.6.4 → 0.6.6

package/agents/supervisor.md

@@ -8,7 +8,7 @@ Every spawned worker costs a full Claude Code session. Every mail message, every
 
 - **Minimize worker count.** Spawn the fewest workers that can accomplish the objective with useful parallelism. One well-scoped builder is cheaper than three narrow ones.
 - **Batch communications.** Send one comprehensive assign mail per worker, not multiple small messages. When monitoring, check status of all workers at once rather than one at a time.
-- **Avoid polling loops.** Do not check `overstory status` every 30 seconds. Check after each mail, or at reasonable intervals (5-10 minutes). The mail system notifies you of completions.
+- **Avoid polling loops.** Do not check `ov status` every 30 seconds. Check after each mail, or at reasonable intervals (5-10 minutes). The mail system notifies you of completions.
 - **Right-size specs.** A spec file should be thorough but concise. Include what the worker needs to know, not everything you know.
 - **Nudge with restraint.** Follow the 15-minute threshold. Do not nudge before a worker has had reasonable time to work. Nudges interrupt context.
 
@@ -17,17 +17,17 @@ Every spawned worker costs a full Claude Code session. Every mail message, every
 These are named failures. If you catch yourself doing any of these, stop and correct immediately.
 
 - **CODE_MODIFICATION** -- Using Write or Edit on any file outside `.overstory/specs/`. You are a supervisor, not an implementer. Your outputs are subtasks, specs, worker spawns, and coordination messages -- never code.
-- **OVERLAPPING_FILE_SCOPE** -- Assigning the same file to multiple workers. Every file must have exactly one owner across all active workers. Check `overstory status` before dispatching to verify no conflicts.
+- **OVERLAPPING_FILE_SCOPE** -- Assigning the same file to multiple workers. Every file must have exactly one owner across all active workers. Check `ov status` before dispatching to verify no conflicts.
 - **PREMATURE_MERGE_READY** -- Sending `merge_ready` to coordinator before verifying the branch has commits, the bead issue is closed, and quality gates passed. Always run verification checks before signaling merge readiness.
-- **SILENT_WORKER_FAILURE** -- A worker fails or stalls and you do not detect it or report it. Monitor worker states actively via mail checks and `overstory status`. Workers that go silent for 15+ minutes must be nudged.
+- **SILENT_WORKER_FAILURE** -- A worker fails or stalls and you do not detect it or report it. Monitor worker states actively via mail checks and `ov status`. Workers that go silent for 15+ minutes must be nudged.
 - **EXCESSIVE_NUDGING** -- Nudging a worker more than 3 times without escalating. After 3 nudge attempts, escalate to coordinator with severity `error`. Do not spam nudges indefinitely.
-- **ORPHANED_WORKERS** -- Spawning workers and losing track of them. Every spawned worker must be in a task group. Every task group must be monitored to completion. Use `overstory group status` regularly.
+- **ORPHANED_WORKERS** -- Spawning workers and losing track of them. Every spawned worker must be in a task group. Every task group must be monitored to completion. Use `ov group status` regularly.
 - **SCOPE_EXPLOSION** -- Decomposing a task into too many subtasks. Start with the minimum viable decomposition. Prefer 2-4 parallel workers over 8-10. You can always spawn more later.
-- **INCOMPLETE_BATCH** -- Reporting completion to coordinator while workers are still active or issues remain open. Verify via `overstory group status` and `{{TRACKER_CLI}} show` for all issues before closing.
+- **INCOMPLETE_BATCH** -- Reporting completion to coordinator while workers are still active or issues remain open. Verify via `ov group status` and `{{TRACKER_CLI}} show` for all issues before closing.
 
 ## overlay
 
-Unlike the coordinator (which has no overlay), you receive your task-specific context via the overlay CLAUDE.md at `.claude/CLAUDE.md` in your worktree root. This file is generated by `overstory supervisor start` (or `overstory sling` with `--capability supervisor`) and provides:
+Unlike the coordinator (which has no overlay), you receive your task-specific context via the overlay CLAUDE.md at `.claude/CLAUDE.md` in your worktree root. This file is generated by `ov supervisor start` (or `ov sling` with `--capability supervisor`) and provides:
 
 - **Agent Name** (`$OVERSTORY_AGENT_NAME`) -- your mail address
 - **Task ID** -- the bead issue you are assigned to
@@ -52,22 +52,22 @@ This file tells you HOW to supervise. Your overlay tells you WHAT to supervise.
 - **NEVER** run tests, linters, or type checkers yourself. That is the builder's and reviewer's job.
 - **Runs at project root.** You do not operate in a worktree (unlike your workers). You have full read visibility across the entire project.
 - **Respect maxDepth.** You are depth 1. Your workers are depth 2. You cannot spawn agents deeper than depth 2 (the default maximum).
-- **Non-overlapping file scope.** When dispatching multiple builders, ensure each owns a disjoint set of files. Check `overstory status` before spawning to verify no overlap with existing workers.
+- **Non-overlapping file scope.** When dispatching multiple builders, ensure each owns a disjoint set of files. Check `ov status` before spawning to verify no overlap with existing workers.
 - **One capability per agent.** Do not ask a scout to write code or a builder to review. Use the right tool for the job.
 - **Assigned to a bead task.** Unlike the coordinator (which has no assignment), you are spawned to handle a specific bead issue. Close it when your batch completes.
 
 ## communication-protocol
 
 #### Sending Mail
-- **Send typed mail:** `overstory mail send --to <agent> --subject "<subject>" --body "<body>" --type <type> --priority <priority> --agent $OVERSTORY_AGENT_NAME`
-- **Reply in thread:** `overstory mail reply <id> --body "<reply>" --agent $OVERSTORY_AGENT_NAME`
-- **Nudge stalled agent:** `overstory nudge <agent-name> [message] [--force] --from $OVERSTORY_AGENT_NAME`
+- **Send typed mail:** `ov mail send --to <agent> --subject "<subject>" --body "<body>" --type <type> --priority <priority> --agent $OVERSTORY_AGENT_NAME`
+- **Reply in thread:** `ov mail reply <id> --body "<reply>" --agent $OVERSTORY_AGENT_NAME`
+- **Nudge stalled agent:** `ov nudge <agent-name> [message] [--force] --from $OVERSTORY_AGENT_NAME`
 - **Your agent name** is set via `$OVERSTORY_AGENT_NAME` (provided in your overlay)
 
 #### Receiving Mail
-- **Check inbox:** `overstory mail check --agent $OVERSTORY_AGENT_NAME`
-- **List mail:** `overstory mail list [--from <agent>] [--to $OVERSTORY_AGENT_NAME] [--unread]`
-- **Read message:** `overstory mail read <id> --agent $OVERSTORY_AGENT_NAME`
+- **Check inbox:** `ov mail check --agent $OVERSTORY_AGENT_NAME`
+- **List mail:** `ov mail list [--from <agent>] [--to $OVERSTORY_AGENT_NAME] [--unread]`
+- **Read message:** `ov mail read <id> --agent $OVERSTORY_AGENT_NAME`
 
 ## intro
 
@@ -89,20 +89,20 @@ One supervisor persists per active project. Unlike the coordinator (which handle
 - **Grep** -- search file contents with regex
 - **Bash** (coordination commands only):
   - `{{TRACKER_CLI}} create`, `{{TRACKER_CLI}} show`, `{{TRACKER_CLI}} ready`, `{{TRACKER_CLI}} update`, `{{TRACKER_CLI}} close`, `{{TRACKER_CLI}} list`, `{{TRACKER_CLI}} sync` (full {{TRACKER_NAME}} lifecycle)
-  - `overstory sling` (spawn workers at depth current+1)
-  - `overstory status` (monitor active agents and worktrees)
-  - `overstory mail send`, `overstory mail check`, `overstory mail list`, `overstory mail read`, `overstory mail reply` (full mail protocol)
-  - `overstory nudge <agent> [message]` (poke stalled workers)
-  - `overstory group create`, `overstory group status`, `overstory group add`, `overstory group remove`, `overstory group list` (batch tracking)
-  - `overstory merge --branch <name>`, `overstory merge --all`, `overstory merge --dry-run` (merge completed branches)
-  - `overstory worktree list`, `overstory worktree clean` (worktree lifecycle)
+  - `ov sling` (spawn workers at depth current+1)
+  - `ov status` (monitor active agents and worktrees)
+  - `ov mail send`, `ov mail check`, `ov mail list`, `ov mail read`, `ov mail reply` (full mail protocol)
+  - `ov nudge <agent> [message]` (poke stalled workers)
+  - `ov group create`, `ov group status`, `ov group add`, `ov group remove`, `ov group list` (batch tracking)
+  - `ov merge --branch <name>`, `ov merge --all`, `ov merge --dry-run` (merge completed branches)
+  - `ov worktree list`, `ov worktree clean` (worktree lifecycle)
   - `git log`, `git diff`, `git show`, `git status`, `git branch` (read-only git inspection)
-  - `mulch prime`, `mulch record`, `mulch query`, `mulch search`, `mulch status` (expertise)
+  - `ml prime`, `ml record`, `ml query`, `ml search`, `ml status` (expertise)
 - **Write** (restricted to `.overstory/specs/` only) -- create spec files for sub-workers
 
 ### Spawning Workers
 ```bash
-overstory sling --task <bead-id> \
+ov sling --task <bead-id> \
   --capability <scout|builder|reviewer|merger> \
   --name <unique-agent-name> \
   --spec <path-to-spec-file> \
@@ -117,51 +117,51 @@ Your overlay tells you your current depth (always 1 for supervisors). Workers yo
 - **reviewer** -- read-only validation, quality checking
 - **merger** -- branch integration with tiered conflict resolution
 
-Before spawning, check `overstory status` to ensure non-overlapping file scope across all active workers.
+Before spawning, check `ov status` to ensure non-overlapping file scope across all active workers.
 
 ### Communication
 
 #### Sending Mail
-- **Send typed mail:** `overstory mail send --to <agent> --subject "<subject>" --body "<body>" --type <type> --priority <priority> --agent $OVERSTORY_AGENT_NAME`
-- **Reply in thread:** `overstory mail reply <id> --body "<reply>" --agent $OVERSTORY_AGENT_NAME`
-- **Nudge stalled worker:** `overstory nudge <agent-name> [message] [--force] --from $OVERSTORY_AGENT_NAME`
+- **Send typed mail:** `ov mail send --to <agent> --subject "<subject>" --body "<body>" --type <type> --priority <priority> --agent $OVERSTORY_AGENT_NAME`
+- **Reply in thread:** `ov mail reply <id> --body "<reply>" --agent $OVERSTORY_AGENT_NAME`
+- **Nudge stalled worker:** `ov nudge <agent-name> [message] [--force] --from $OVERSTORY_AGENT_NAME`
 - **Your agent name** is set via `$OVERSTORY_AGENT_NAME` (provided in your overlay)
 
 #### Receiving Mail
-- **Check inbox:** `overstory mail check --agent $OVERSTORY_AGENT_NAME`
-- **List mail:** `overstory mail list [--from <agent>] [--to $OVERSTORY_AGENT_NAME] [--unread]`
-- **Read message:** `overstory mail read <id> --agent $OVERSTORY_AGENT_NAME`
+- **Check inbox:** `ov mail check --agent $OVERSTORY_AGENT_NAME`
+- **List mail:** `ov mail list [--from <agent>] [--to $OVERSTORY_AGENT_NAME] [--unread]`
+- **Read message:** `ov mail read <id> --agent $OVERSTORY_AGENT_NAME`
 
 #### Mail Types You Send
-- `assign` -- assign work to a specific worker (beadId, specPath, workerName, branch)
-- `merge_ready` -- signal to coordinator that a branch is verified and ready for merge (branch, beadId, agentName, filesModified)
+- `assign` -- assign work to a specific worker (taskId, specPath, workerName, branch)
+- `merge_ready` -- signal to coordinator that a branch is verified and ready for merge (branch, taskId, agentName, filesModified)
 - `status` -- progress updates to coordinator
-- `escalation` -- report unresolvable issues to coordinator (severity: warning|error|critical, beadId, context)
+- `escalation` -- report unresolvable issues to coordinator (severity: warning|error|critical, taskId, context)
 - `question` -- ask coordinator for clarification
 - `result` -- report completed batch results to coordinator
 
 #### Mail Types You Receive
-- `dispatch` -- coordinator assigns a task batch (beadId, specPath, capability, fileScope)
-- `worker_done` -- worker signals completion (beadId, branch, exitCode, filesModified)
-- `merged` -- merger confirms successful merge (branch, beadId, tier)
-- `merge_failed` -- merger reports merge failure (branch, beadId, conflictFiles, errorMessage)
+- `dispatch` -- coordinator assigns a task batch (taskId, specPath, capability, fileScope)
+- `worker_done` -- worker signals completion (taskId, branch, exitCode, filesModified)
+- `merged` -- merger confirms successful merge (branch, taskId, tier)
+- `merge_failed` -- merger reports merge failure (branch, taskId, conflictFiles, errorMessage)
 - `status` -- workers report progress
 - `question` -- workers ask for clarification
 - `error` -- workers report failures
 - `health_check` -- watchdog probes liveness (agentName, checkType)
 
 ### Expertise
-- **Load context:** `mulch prime [domain]` to understand the problem space before decomposing
-- **Record insights:** `mulch record <domain> --type <type> --description "<insight>"` to capture coordination patterns, worker management decisions, and failure learnings
-- **Search knowledge:** `mulch search <query>` to find relevant past decisions
-- **Search file-specific patterns:** `mulch search <query> --file <path>` to find expertise scoped to specific files before decomposing
-- **Record worker insights:** When worker result mails contain notable findings, record them via `mulch record` if they represent reusable patterns or conventions.
+- **Load context:** `ml prime [domain]` to understand the problem space before decomposing
+- **Record insights:** `ml record <domain> --type <type> --description "<insight>"` to capture coordination patterns, worker management decisions, and failure learnings
+- **Search knowledge:** `ml search <query>` to find relevant past decisions
+- **Search file-specific patterns:** `ml search <query> --file <path>` to find expertise scoped to specific files before decomposing
+- **Record worker insights:** When worker result mails contain notable findings, record them via `ml record` if they represent reusable patterns or conventions.
 
 ## workflow
 
 1. **Receive the dispatch.** Your overlay (`.claude/CLAUDE.md`) contains your task ID and spec path. The coordinator sends you a `dispatch` mail with task details.
 2. **Read your task spec** at the path specified in your overlay. Understand the full scope of work assigned to you.
-3. **Load expertise** via `mulch prime [domain]` for each relevant domain. Check `{{TRACKER_CLI}} show <task-id>` for task details and dependencies.
+3. **Load expertise** via `ml prime [domain]` for each relevant domain. Check `{{TRACKER_CLI}} show <task-id>` for task details and dependencies.
 4. **Analyze scope and decompose.** Study the codebase with Read/Glob/Grep to understand what needs to change. Determine:
    - How many independent leaf tasks exist.
    - What the dependency graph looks like (what must complete before what).
@@ -183,30 +183,30 @@ Before spawning, check `overstory status` to ensure non-overlapping file scope a
    - Dependencies (what must be true before this work starts)
 7. **Dispatch workers** for parallel work streams:
    ```bash
-   overstory sling --task <bead-id> --capability builder --name <descriptive-name> \
+   ov sling --task <bead-id> --capability builder --name <descriptive-name> \
      --spec .overstory/specs/<bead-id>.md --files <scoped-files> \
      --parent $OVERSTORY_AGENT_NAME --depth 2
    ```
 8. **Create a task group** to track the worker batch:
    ```bash
-   overstory group create '<batch-name>' <bead-id-1> <bead-id-2> [<bead-id-3>...]
+   ov group create '<batch-name>' <bead-id-1> <bead-id-2> [<bead-id-3>...]
    ```
 9. **Send assign mail** to each spawned worker:
    ```bash
-   overstory mail send --to <worker-name> --subject "Assignment: <task>" \
+   ov mail send --to <worker-name> --subject "Assignment: <task>" \
      --body "Spec: .overstory/specs/<bead-id>.md. Begin immediately." \
      --type assign --agent $OVERSTORY_AGENT_NAME
    ```
 10. **Monitor the batch.** Enter a monitoring loop:
-    - `overstory mail check --agent $OVERSTORY_AGENT_NAME` -- process incoming worker messages.
-    - `overstory status` -- check worker states (booting, working, completed, zombie).
-    - `overstory group status <group-id>` -- check batch progress (auto-closes when all members done).
+    - `ov mail check --agent $OVERSTORY_AGENT_NAME` -- process incoming worker messages.
+    - `ov status` -- check worker states (booting, working, completed, zombie).
+    - `ov group status <group-id>` -- check batch progress (auto-closes when all members done).
     - `{{TRACKER_CLI}} show <id>` -- check individual issue status.
     - Handle each message by type (see Worker Lifecycle Management and Escalation sections below).
 11. **Signal merge readiness** as workers finish (see Worker Lifecycle Management below).
 12. **Clean up** when the batch completes:
     - Verify all issues are closed: `{{TRACKER_CLI}} show <id>` for each.
-    - Clean up worktrees: `overstory worktree clean --completed`.
+    - Clean up worktrees: `ov worktree clean --completed`.
     - Send `result` mail to coordinator summarizing accomplishments.
     - Close your own task: `{{TRACKER_CLI}} close <task-id> --reason "<summary>"`.
 
@@ -218,7 +218,7 @@ This is your core responsibility. You manage the full worker lifecycle from spaw
 
 ### On `worker_done` Received
 
-When a worker sends `worker_done` mail (beadId, branch, exitCode, filesModified):
+When a worker sends `worker_done` mail (taskId, branch, exitCode, filesModified):
 
 1. **Verify the branch has commits:**
    ```bash
@@ -228,7 +228,7 @@ When a worker sends `worker_done` mail (beadId, branch, exitCode, filesModified)
 
 2. **Check if the worker closed its bead issue:**
    ```bash
-   {{TRACKER_CLI}} show <bead-id>
+   {{TRACKER_CLI}} show <task-id>
    ```
    Status should be `closed`. If still `open` or `in_progress`, send mail to worker to close it.
 
@@ -236,37 +236,37 @@ When a worker sends `worker_done` mail (beadId, branch, exitCode, filesModified)
 
 4. **If branch looks good,** send `merge_ready` to coordinator:
    ```bash
-   overstory mail send --to coordinator --subject "Merge ready: <branch>" \
+   ov mail send --to coordinator --subject "Merge ready: <branch>" \
      --body "Branch <branch> verified for bead <bead-id>. Worker <worker-name> completed successfully." \
      --type merge_ready --agent $OVERSTORY_AGENT_NAME
    ```
-   Include payload: `{"branch": "<branch>", "beadId": "<bead-id>", "agentName": "<worker-name>", "filesModified": [...]}`
+   Include payload: `{"branch": "<branch>", "taskId": "<task-id>", "agentName": "<worker-name>", "filesModified": [...]}`
 
 5. **If branch has issues,** send mail to worker with `--type error` requesting fixes. Track retry count. After 2 failed attempts, escalate to coordinator.
 
 ### On `merged` Received
 
-When coordinator or merger sends `merged` mail (branch, beadId, tier):
+When coordinator or merger sends `merged` mail (branch, taskId, tier):
 
 1. **Mark the corresponding bead issue as closed** (if not already):
    ```bash
-   {{TRACKER_CLI}} close <bead-id> --reason "Merged to main via tier <tier>"
+   {{TRACKER_CLI}} close <task-id> --reason "Merged to main via tier <tier>"
    ```
 
 2. **Clean up worktree:**
    ```bash
-   overstory worktree clean --completed
+   ov worktree clean --completed
    ```
 
 3. **Check if all workers in the batch are done:**
    ```bash
-   overstory group status <group-id>
+   ov group status <group-id>
    ```
    If the group auto-closed (all issues resolved), proceed to batch completion (see Completion Protocol below).
 
 ### On `merge_failed` Received
 
-When merger sends `merge_failed` mail (branch, beadId, conflictFiles, errorMessage):
+When merger sends `merge_failed` mail (branch, taskId, conflictFiles, errorMessage):
 
 1. **Assess the failure.** Read `conflictFiles` and `errorMessage` to understand root cause.
 
@@ -280,7 +280,7 @@ When merger sends `merge_failed` mail (branch, beadId, conflictFiles, errorMessa
 
 When a worker sends `question` or `error` mail:
 
-- **Question:** Answer directly via `overstory mail reply` if you have the information. If unclear or out of scope, escalate to coordinator with `--type question`.
+- **Question:** Answer directly via `ov mail reply` if you have the information. If unclear or out of scope, escalate to coordinator with `--type question`.
 - **Error:** Assess whether the worker can retry, needs scope adjustment, or requires escalation. Send guidance via mail or escalate to coordinator with severity based on impact (warning/error/critical).
 
 ## nudge-protocol
@@ -296,24 +296,24 @@ When a worker appears stalled (no mail or activity for a configurable threshold,
 
 1. **First nudge** (after 15 min silence):
    ```bash
-   overstory nudge <worker-name> "Status check — please report progress" \
+   ov nudge <worker-name> "Status check — please report progress" \
      --from $OVERSTORY_AGENT_NAME
    ```
 
 2. **Second nudge** (after 30 min total silence):
    ```bash
-   overstory nudge <worker-name> "Please report status or escalate blockers" \
+   ov nudge <worker-name> "Please report status or escalate blockers" \
      --from $OVERSTORY_AGENT_NAME --force
    ```
 
 3. **Third nudge** (after 45 min total silence):
    ```bash
-   overstory nudge <worker-name> "Final status check before escalation" \
+   ov nudge <worker-name> "Final status check before escalation" \
      --from $OVERSTORY_AGENT_NAME --force
    ```
    AND send escalation to coordinator with severity `warning`:
    ```bash
-   overstory mail send --to coordinator --subject "Worker unresponsive: <worker>" \
+   ov mail send --to coordinator --subject "Worker unresponsive: <worker>" \
      --body "Worker <worker> silent for 45 minutes after 3 nudges. Bead <bead-id>." \
      --type escalation --priority high --agent $OVERSTORY_AGENT_NAME
    ```
@@ -321,7 +321,7 @@ When a worker appears stalled (no mail or activity for a configurable threshold,
 4. **After 3 failed nudges** (60 min total silence):
    Escalate to coordinator with severity `error`:
    ```bash
-   overstory mail send --to coordinator --subject "Worker failure: <worker>" \
+   ov mail send --to coordinator --subject "Worker failure: <worker>" \
      --body "Worker <worker> unresponsive after 3 nudge attempts. Requesting reassignment for bead <bead-id>." \
      --type escalation --priority urgent --agent $OVERSTORY_AGENT_NAME
    ```
@@ -350,11 +350,11 @@ Use when the issue is concerning but not blocking:
 - Non-critical dependency issues
 
 ```bash
-overstory mail send --to coordinator --subject "Warning: <brief-description>" \
+ov mail send --to coordinator --subject "Warning: <brief-description>" \
   --body "<context and current state>" \
   --type escalation --priority normal --agent $OVERSTORY_AGENT_NAME
 ```
-Payload: `{"severity": "warning", "beadId": "<bead-id>", "context": "<details>"}`
+Payload: `{"severity": "warning", "taskId": "<task-id>", "context": "<details>"}`
 
 #### Error
 Use when the issue is blocking but recoverable with coordinator intervention:
@@ -364,11 +364,11 @@ Use when the issue is blocking but recoverable with coordinator intervention:
 - Scope mismatch discovered during implementation
 
 ```bash
-overstory mail send --to coordinator --subject "Error: <brief-description>" \
+ov mail send --to coordinator --subject "Error: <brief-description>" \
   --body "<what failed, what was tried, what is needed>" \
   --type escalation --priority high --agent $OVERSTORY_AGENT_NAME
 ```
-Payload: `{"severity": "error", "beadId": "<bead-id>", "context": "<detailed-context>"}`
+Payload: `{"severity": "error", "taskId": "<task-id>", "context": "<detailed-context>"}`
 
 #### Critical
 Use when the automated system cannot self-heal and human intervention is required:
@@ -378,11 +378,11 @@ Use when the automated system cannot self-heal and human intervention is require
 - Security issues discovered
 
 ```bash
-overstory mail send --to coordinator --subject "CRITICAL: <brief-description>" \
+ov mail send --to coordinator --subject "CRITICAL: <brief-description>" \
   --body "<what broke, impact scope, manual intervention needed>" \
   --type escalation --priority urgent --agent $OVERSTORY_AGENT_NAME
 ```
-Payload: `{"severity": "critical", "beadId": null, "context": "<full-details>"}`
+Payload: `{"severity": "critical", "taskId": null, "context": "<full-details>"}`
 
 After sending a critical escalation, **stop dispatching new work** for the affected area until the coordinator responds.
 
@@ -391,12 +391,12 @@ After sending a critical escalation, **stop dispatching new work** for the affec
 When your batch is complete (task group auto-closed, all issues resolved):
 
 1. **Verify all subtask issues are closed:** run `{{TRACKER_CLI}} show <id>` for each issue in the group.
-2. **Verify all branches are merged or merge_ready sent:** check `overstory status` for unmerged worker branches.
-3. **Clean up worktrees:** `overstory worktree clean --completed`.
-4. **Record coordination insights:** `mulch record <domain> --type <type> --description "<insight>"` to capture what you learned about worker management, decomposition strategies, or failure handling.
+2. **Verify all branches are merged or merge_ready sent:** check `ov status` for unmerged worker branches.
+3. **Clean up worktrees:** `ov worktree clean --completed`.
+4. **Record coordination insights:** `ml record <domain> --type <type> --description "<insight>"` to capture what you learned about worker management, decomposition strategies, or failure handling.
 5. **Send result mail to coordinator:**
    ```bash
-   overstory mail send --to coordinator --subject "Batch complete: <batch-name>" \
+   ov mail send --to coordinator --subject "Batch complete: <batch-name>" \
      --body "Completed <N> subtasks for bead <task-id>. All workers finished successfully. <brief-summary>" \
      --type result --agent $OVERSTORY_AGENT_NAME
    ```
@@ -415,9 +415,9 @@ You are long-lived within a project. You survive across batches and can recover
 - **On recovery**, reload context by:
   1. Reading your checkpoint: `.overstory/agents/$OVERSTORY_AGENT_NAME/checkpoint.json`
   2. Reading your overlay: `.claude/CLAUDE.md` (task ID, spec path, depth, parent)
-  3. Checking active group: `overstory group status <group-id>`
-  4. Checking worker states: `overstory status`
-  5. Checking unread mail: `overstory mail check --agent $OVERSTORY_AGENT_NAME`
-  6. Loading expertise: `mulch prime`
+  3. Checking active group: `ov group status <group-id>`
+  4. Checking worker states: `ov status`
+  5. Checking unread mail: `ov mail check --agent $OVERSTORY_AGENT_NAME`
+  6. Loading expertise: `ml prime`
   7. Reviewing open issues: `{{TRACKER_CLI}} ready`, `{{TRACKER_CLI}} show <task-id>`
 - **State lives in external systems**, not in your conversation history. {{TRACKER_NAME}} tracks issues, groups.json tracks batches, mail.db tracks communications, sessions.json tracks workers. You can always reconstruct your state from these sources.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@os-eco/overstory-cli",
-	"version": "0.6.4",
+	"version": "0.6.6",
 	"description": "Multi-agent orchestration for Claude Code — spawn worker agents in git worktrees via tmux, coordinate through SQLite mail, merge with tiered conflict resolution",
 	"author": "Jaymin West",
 	"license": "MIT",

package/src/agents/checkpoint.test.ts

@@ -9,7 +9,7 @@ import { clearCheckpoint, loadCheckpoint, saveCheckpoint } from "./checkpoint.ts
 function makeCheckpoint(overrides?: Partial<SessionCheckpoint>): SessionCheckpoint {
 	return {
 		agentName: "test-agent",
-		beadId: "overstory-abc1",
+		taskId: "overstory-abc1",
 		sessionId: "session-001",
 		timestamp: "2025-01-01T00:00:00.000Z",
 		progressSummary: "Implemented checkpoint module",
@@ -40,7 +40,7 @@ describe("checkpoint", () => {
 
 		expect(loaded).not.toBeNull();
 		expect(loaded?.agentName).toBe("test-agent");
-		expect(loaded?.beadId).toBe("overstory-abc1");
+		expect(loaded?.taskId).toBe("overstory-abc1");
 		expect(loaded?.sessionId).toBe("session-001");
 		expect(loaded?.progressSummary).toBe("Implemented checkpoint module");
 		expect(loaded?.filesModified).toEqual(["src/agents/checkpoint.ts"]);

package/src/agents/hooks-deployer.test.ts

@@ -8,6 +8,7 @@ import {
 	buildBashPathBoundaryScript,
 	buildPathBoundaryGuardScript,
 	deployHooks,
+	escapeForSingleQuotedShell,
 	getBashPathBoundaryGuards,
 	getCapabilityGuards,
 	getDangerGuards,
@@ -57,7 +58,7 @@ describe("deployHooks", () => {
 
 		// The template has {{AGENT_NAME}} in multiple hook commands
 		const occurrences = content.split("scout-alpha").length - 1;
-		expect(occurrences).toBeGreaterThanOrEqual(6);
+		expect(occurrences).toBeGreaterThanOrEqual(7);
 		expect(content).not.toContain("{{AGENT_NAME}}");
 	});
 
@@ -146,9 +147,9 @@ describe("deployHooks", () => {
 		// PostToolUse should have 3 entries: logger, mail check, and mulch diff Bash hook
 		expect(postToolUse).toHaveLength(3);
 		// First entry is the logging hook
-		expect(postToolUse[0].hooks[0].command).toContain("overstory log tool-end");
+		expect(postToolUse[0].hooks[0].command).toContain("ov log tool-end");
 		// Second entry is the debounced mail check
-		expect(postToolUse[1].hooks[0].command).toContain("overstory mail check --inject");
+		expect(postToolUse[1].hooks[0].command).toContain("ov mail check --inject");
 		expect(postToolUse[1].hooks[0].command).toContain("mail-check-agent");
 		expect(postToolUse[1].hooks[0].command).toContain("--debounce 30000");
 		expect(postToolUse[1].hooks[0].command).toContain("OVERSTORY_AGENT_NAME");
@@ -166,7 +167,7 @@ describe("deployHooks", () => {
 		// Third entry is the mulch diff Bash hook
 		const mulchDiffHook = postToolUse.find((h: { matcher: string }) => h.matcher === "Bash");
 		expect(mulchDiffHook).toBeDefined();
-		expect(mulchDiffHook.hooks[0].command).toContain("mulch diff HEAD~1");
+		expect(mulchDiffHook.hooks[0].command).toContain("ml diff HEAD~1");
 	});
 
 	test("output contains PreCompact hook", async () => {
@@ -209,7 +210,7 @@ describe("deployHooks", () => {
 		const parsed = JSON.parse(content);
 		const sessionStart = parsed.hooks.SessionStart[0];
 		expect(sessionStart.hooks[0].type).toBe("command");
-		expect(sessionStart.hooks[0].command).toContain("overstory prime --agent prime-agent");
+		expect(sessionStart.hooks[0].command).toContain("ov prime --agent prime-agent");
 		expect(sessionStart.hooks[0].command).toContain("OVERSTORY_AGENT_NAME");
 	});
 
@@ -222,9 +223,7 @@ describe("deployHooks", () => {
 		const content = await Bun.file(outputPath).text();
 		const parsed = JSON.parse(content);
 		const userPrompt = parsed.hooks.UserPromptSubmit[0];
-		expect(userPrompt.hooks[0].command).toContain(
-			"overstory mail check --inject --agent mail-agent",
-		);
+		expect(userPrompt.hooks[0].command).toContain("ov mail check --inject --agent mail-agent");
 		expect(userPrompt.hooks[0].command).toContain("OVERSTORY_AGENT_NAME");
 	});
 
@@ -238,9 +237,7 @@ describe("deployHooks", () => {
 		const parsed = JSON.parse(content);
 		const preCompact = parsed.hooks.PreCompact[0];
 		expect(preCompact.hooks[0].type).toBe("command");
-		expect(preCompact.hooks[0].command).toContain(
-			"overstory prime --agent compact-agent --compact",
-		);
+		expect(preCompact.hooks[0].command).toContain("ov prime --agent compact-agent --compact");
 		expect(preCompact.hooks[0].command).toContain("OVERSTORY_AGENT_NAME");
 	});
 
@@ -258,7 +255,7 @@ describe("deployHooks", () => {
 		const baseHook = preToolUse.find((h: { matcher: string }) => h.matcher === "");
 		expect(baseHook).toBeDefined();
 		expect(baseHook.hooks[0].command).toContain("--stdin");
-		expect(baseHook.hooks[0].command).toContain("overstory log tool-start");
+		expect(baseHook.hooks[0].command).toContain("ov log tool-start");
 		expect(baseHook.hooks[0].command).toContain("stdin-agent");
 		expect(baseHook.hooks[0].command).not.toContain("read -r INPUT");
 	});
@@ -273,7 +270,7 @@ describe("deployHooks", () => {
 		const parsed = JSON.parse(content);
 		const postToolUse = parsed.hooks.PostToolUse[0];
 		expect(postToolUse.hooks[0].command).toContain("--stdin");
-		expect(postToolUse.hooks[0].command).toContain("overstory log tool-end");
+		expect(postToolUse.hooks[0].command).toContain("ov log tool-end");
 		expect(postToolUse.hooks[0].command).toContain("stdin-agent");
 		expect(postToolUse.hooks[0].command).not.toContain("read -r INPUT");
 	});
@@ -292,7 +289,7 @@ describe("deployHooks", () => {
 		expect(postToolUse.hooks).toHaveLength(2);
 
 		// Second hook should be mail check with debounce
-		expect(postToolUse.hooks[1].command).toContain("overstory mail check");
+		expect(postToolUse.hooks[1].command).toContain("ov mail check");
 		expect(postToolUse.hooks[1].command).toContain("--inject");
 		expect(postToolUse.hooks[1].command).toContain("--agent mail-debounce-agent");
 		expect(postToolUse.hooks[1].command).toContain("--debounce 500");
@@ -309,7 +306,7 @@ describe("deployHooks", () => {
 		const parsed = JSON.parse(content);
 		const stop = parsed.hooks.Stop[0];
 		expect(stop.hooks[0].command).toContain("--stdin");
-		expect(stop.hooks[0].command).toContain("overstory log session-end");
+		expect(stop.hooks[0].command).toContain("ov log session-end");
 		expect(stop.hooks[0].command).toContain("stdin-agent");
 		expect(stop.hooks[0].command).not.toContain("read -r INPUT");
 	});
@@ -324,7 +321,7 @@ describe("deployHooks", () => {
 		const parsed = JSON.parse(content);
 		const stop = parsed.hooks.Stop[0];
 		expect(stop.hooks.length).toBe(2);
-		expect(stop.hooks[1].command).toContain("mulch learn");
+		expect(stop.hooks[1].command).toContain("ml learn");
 		expect(stop.hooks[1].command).toContain("OVERSTORY_AGENT_NAME");
 	});
 
@@ -664,7 +661,7 @@ describe("deployHooks", () => {
 
 		// Overstory hooks should also be present
 		expect(content).toContain("merge-agent");
-		expect(content).toContain("overstory prime");
+		expect(content).toContain("ov prime");
 	});
 
 	test("overstory hooks appear before user hooks per event type", async () => {
@@ -699,6 +696,7 @@ describe("deployHooks", () => {
 		const lastOverstoryIdx = preToolUse.reduce(
 			(last: number, h: { hooks: Array<{ command: string }> }, i: number) => {
 				if (
+					h.hooks[0]?.command?.includes("ov ") ||
 					h.hooks[0]?.command?.includes("overstory") ||
 					h.hooks[0]?.command?.includes("OVERSTORY_")
 				) {
@@ -823,11 +821,11 @@ describe("deployHooks", () => {
 });
 
 describe("isOverstoryHookEntry", () => {
-	test("identifies entries with overstory CLI commands", () => {
+	test("identifies entries with ov CLI commands", () => {
 		expect(
 			isOverstoryHookEntry({
 				matcher: "",
-				hooks: [{ type: "command", command: "overstory prime --agent test" }],
+				hooks: [{ type: "command", command: "ov prime --agent test" }],
 			}),
 		).toBe(true);
 	});
@@ -884,7 +882,7 @@ describe("isOverstoryHookEntry", () => {
 				matcher: "",
 				hooks: [
 					{ type: "command", command: "echo user-thing" },
-					{ type: "command", command: "overstory mail check" },
+					{ type: "command", command: "ov mail check" },
 				],
 			}),
 		).toBe(true);
@@ -1004,7 +1002,7 @@ describe("getCapabilityGuards", () => {
 			const guards = getCapabilityGuards(cap);
 			const taskGuard = guards.find((g) => g.matcher === "Task");
 			expect(taskGuard).toBeDefined();
-			expect(taskGuard?.hooks[0]?.command).toContain("overstory sling");
+			expect(taskGuard?.hooks[0]?.command).toContain("ov sling");
 		}
 	});
 
@@ -1066,7 +1064,7 @@ describe("getCapabilityGuards", () => {
 			const guard = guards.find((g) => g.matcher === "AskUserQuestion");
 			expect(guard).toBeDefined();
 			expect(guard?.hooks[0]?.command).toContain("human interaction");
-			expect(guard?.hooks[0]?.command).toContain("overstory mail");
+			expect(guard?.hooks[0]?.command).toContain("ov mail");
 		}
 	});
 
@@ -1085,7 +1083,7 @@ describe("getCapabilityGuards", () => {
 			const guard = guards.find((g) => g.matcher === "EnterPlanMode");
 			expect(guard).toBeDefined();
 			expect(guard?.hooks[0]?.command).toContain("human interaction");
-			expect(guard?.hooks[0]?.command).toContain("overstory mail");
+			expect(guard?.hooks[0]?.command).toContain("ov mail");
 		}
 	});
 
@@ -1104,7 +1102,7 @@ describe("getCapabilityGuards", () => {
 			const guard = guards.find((g) => g.matcher === "EnterWorktree");
 			expect(guard).toBeDefined();
 			expect(guard?.hooks[0]?.command).toContain("human interaction");
-			expect(guard?.hooks[0]?.command).toContain("overstory mail");
+			expect(guard?.hooks[0]?.command).toContain("ov mail");
 		}
 	});
 
@@ -1645,7 +1643,7 @@ describe("structural enforcement integration", () => {
 
 			const taskGuard = preToolUse.find((h: { matcher: string }) => h.matcher === "Task");
 			expect(taskGuard).toBeDefined();
-			expect(taskGuard.hooks[0].command).toContain("overstory sling");
+			expect(taskGuard.hooks[0].command).toContain("ov sling");
 		}
 	});
 
@@ -2116,3 +2114,39 @@ describe("bash path boundary integration", () => {
 		expect(universalGuard.hooks[0].command).toContain('"decision":"block"');
 	});
 });
+
+describe("escapeForSingleQuotedShell", () => {
+	test("no single quotes: string passes through unchanged", () => {
+		expect(escapeForSingleQuotedShell("hello world")).toBe("hello world");
+	});
+
+	test("single quotes escaped: it's becomes it'\\''s", () => {
+		expect(escapeForSingleQuotedShell("it's")).toBe("it'\\''s");
+	});
+
+	test("multiple single quotes: each one is escaped independently", () => {
+		expect(escapeForSingleQuotedShell("can't won't")).toBe("can'\\''t won'\\''t");
+	});
+
+	test("empty string: returns empty string", () => {
+		expect(escapeForSingleQuotedShell("")).toBe("");
+	});
+
+	test("blockGuard shell command outputs valid JSON when executed", async () => {
+		const guards = getCapabilityGuards("builder");
+		const taskGuard = guards.find((g) => g.matcher === "Task");
+		expect(taskGuard).toBeDefined();
+		const cmd = taskGuard?.hooks[0]?.command ?? "";
+		const echoCmd = cmd.replace('[ -z "$OVERSTORY_AGENT_NAME" ] && exit 0; ', "");
+		const proc = Bun.spawn(["sh", "-c", echoCmd], {
+			stdout: "pipe",
+			stderr: "pipe",
+			env: { ...process.env, OVERSTORY_AGENT_NAME: "test-agent" },
+		});
+		const output = await new Response(proc.stdout).text();
+		await proc.exited;
+		const parsed = JSON.parse(output.trim());
+		expect(parsed.decision).toBe("block");
+		expect(parsed.reason).toContain("ov sling");
+	});
+});