ai-workflow-skill/docs/worktree-execution.md

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:

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:

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

Recommended worktree path:

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

Example:

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: high-level separation of inbox and orch
• orch-cli.md: scheduling commands that create and manage attempts