226 lines
6.2 KiB
Markdown
226 lines
6.2 KiB
Markdown
# 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:
|
|
|
|
- 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
|