# Worktree Execution Model

## Purpose

This document defines how code-writing workers should execute in isolated Git worktrees instead of modifying the user's primary working tree.

The default recommendation is strict mode:

- every task attempt gets its own Git worktree
- the worktree is created by `orch` during dispatch
- the worker writes code only inside that assigned worktree
- the leader reviews and integrates the result later

This model is intended for code tasks. Non-code tasks may not need a worktree.

## Why Worktrees

Using a worktree per task attempt gives:

- isolation between concurrent workers
- protection for the user's main working tree
- deterministic base revisions for review and retry
- easier cleanup of abandoned or failed attempts
- a clean mapping from task attempt to diff, branch, and workspace path

## Strict Mode

Strict mode means workers only start from an explicit committed Git base.

Rules:

- `orch dispatch` must resolve a concrete `base_ref` to a commit
- worker execution must happen in a separate worktree
- the worker must not modify the user's primary checkout
- each retry gets a fresh attempt and a fresh worktree
- the leader integrates results explicitly after review

## Base Revision Policy

The safest default is:

- use an explicit committed `base_ref`
- fail dispatch if the leader is implicitly relying on uncommitted local changes

Recommended strict policy:

1. if `--base-ref` is provided, resolve it to a commit and use that exact commit
2. if `--base-ref` is omitted and the repository is clean, default to `HEAD`
3. if `--base-ref` is omitted and the repository has uncommitted changes, fail dispatch

This keeps worker execution reproducible and avoids hidden divergence from the leader's uncommitted state.

## Lifecycle

### 1. Leader Decides a Task Is Ready

`orch` determines that a task may be dispatched.

### 2. `orch dispatch` Creates an Attempt Workspace

For one task attempt, `orch` should:

- resolve the source repository from the caller context or an explicit repo-path override
- pick a `base_ref`
- create an attempt record
- choose a branch name
- create a worktree path
- create the worktree from the chosen base commit
- write workspace metadata into the attempt record
- include the workspace metadata in the inbox task payload

### 3. Worker Runs Inside the Assigned Worktree

The worker runtime should launch `codex exec` with the assigned worktree as its working directory.

Example shape:

```bash
codex exec -C /path/to/worktrees/blog_mvp_001/T4/attempt-1 "Implement the assigned task using the provided repository context."
```

The worker must treat the assigned worktree as its only writable repository root.

### 4. Worker Reports Through `inbox`

The worker reports progress, blocked questions, results, and failure through `inbox`.

### 5. Leader Reviews and Integrates

After completion, the leader may:

- inspect the worktree directly
- inspect the branch diff
- request fixes through a new attempt
- merge or cherry-pick the result into the integration branch

### 6. `orch cleanup` Removes Unneeded Worktrees

After review and integration, `orch cleanup` should remove completed or abandoned worktrees that are no longer needed.

## Attempt-To-Workspace Mapping

The mapping should be one-to-one:

- one task attempt
- one branch
- one worktree path

Do not reuse a worktree for multiple attempts. Reuse creates hidden state and makes retries harder to reason about.

## Naming Conventions

Recommended branch naming:

```text
orch/<run_id>/<task_id>/attempt-<n>
```

Recommended worktree path:

```text
.orch/worktrees/<run_id>/<task_id>/attempt-<n>
```

Example:

```text
branch: orch/blog_mvp_001/T4/attempt-1
path:   .orch/worktrees/blog_mvp_001/T4/attempt-1
```

Identifiers should be sanitized for filesystem and Git branch compatibility.

## Workspace Metadata

Each task attempt should record:

- `base_ref`
- `base_commit`
- `branch_name`
- `worktree_path`
- `workspace_status`
- `result_commit` if the worker produces one

Suggested `workspace_status` values:

- `created`
- `active`
- `completed`
- `abandoned`
- `cleaned`

## Dispatch-Time Behavior

`orch dispatch` should treat worktree creation as part of dispatch, not as a later best-effort step.

Recommended behavior:

1. validate the Git repository and base commit
2. enforce strict mode policy
3. create the attempt row
4. create the branch and worktree
5. create the inbox thread and initial task message
6. write worktree metadata into the task payload
7. mark the task as `dispatched`

If worktree creation fails, dispatch should fail atomically and the task should remain undispatched.

## Worker Runtime Contract

The worker runtime may be a small launcher around `codex exec`.

Recommended responsibilities:

- read the assigned thread or attempt metadata
- claim the inbox thread
- launch `codex exec -C <worktree_path>`
- forward result status into `inbox`
- never rewrite the worktree assignment itself

This keeps workspace ownership in `orch` and execution ownership in the worker runtime.

## Review and Integration

Strict mode works best when integration is explicit.

The leader should decide whether to:

- merge the attempt branch
- cherry-pick one or more commits
- open a follow-up attempt for fixes
- discard the attempt and remove the worktree

Workers should not self-merge into the user's main branch.

## Retry Policy

A retry should create:

- a new attempt number
- a new branch
- a new worktree

Do not reopen the previous worktree for a retry unless you are intentionally debugging that attempt by hand.

## Failure and Cleanup

Recommended `orch cleanup` behavior:

- remove worktrees for completed attempts after integration
- remove worktrees for abandoned or superseded attempts
- preserve worktrees that are still running or under active review unless forced

Suggested flags:

- `--run RUN_ID`
- `--task TASK_ID`
- `--attempt N`
- `--all-completed`
- `--force`

## Relationship To Existing Docs

- [architecture.md](/home/kurihada/project/ai-workflow-skill/docs/architecture.md): high-level separation of inbox and orch
- [orch-cli.md](/home/kurihada/project/ai-workflow-skill/docs/orch-cli.md): scheduling commands that create and manage attempts
- [blog-project-example.md](/home/kurihada/project/ai-workflow-skill/docs/blog-project-example.md): example of dispatch creating a worktree-backed attempt
