Add design docs and gitignore
This commit is contained in:
@@ -0,0 +1,225 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user