ai-workflow-skill/docs/roadmaps/archive/orch-strict-worktree-support.md

Orch Strict Worktree Support

Status

• completed

Owner

• codex

Started At

• 2026-03-19

Goal

• implement dispatch-time strict worktree support so orch can resolve a committed base, create a branch and worktree per attempt, and persist workspace metadata into attempt storage and inbox payload

Scope

• extend orch dispatch to support Git-backed worktree creation
• enforce strict-mode base resolution and dirty-repo checks
• persist base_ref, base_commit, branch_name, worktree_path, and workspace_status
• add integration tests for successful worktree dispatch and strict-mode rejection on dirty repositories
• update project-level implementation roadmap after the work is validated

Checklist

• inspect current worktree design docs and dispatch constraints
• implement git helpers for repo discovery, base resolution, branch naming, and worktree creation
• wire worktree metadata into orch dispatch attempt storage and inbox payload
• add integration coverage for strict worktree success and dirty-repo failure
• run go test ./...
• update docs/implementation-roadmap.md
• archive this roadmap with completion summary

Files

• docs/roadmaps/archive/orch-strict-worktree-support.md
• docs/implementation-roadmap.md
• internal/cli/orch/dispatch.go
• internal/cli/orch/integration_test.go
• internal/cli/orch/worktree.go
• internal/store/orch.go

Decisions

• use the current working directory as the default source repo for orch dispatch, with an explicit override flag only if implementation needs it
• keep worktree creation tied to dispatch so failed workspace creation cannot silently leave a task marked as dispatched

Blockers

• none

Next Step

• implement orch wait, then continue with retry/reassign/cancel/cleanup on top of the now worktree-aware dispatch model

Completion Summary

• orch dispatch now supports strict Git-backed worktree provisioning with repo discovery, committed base resolution, branch naming, and per-attempt worktree paths
• dispatch persists workspace metadata on attempts and includes the same metadata in inbox task payloads for worker runtimes
• integration tests now cover successful strict worktree creation, dirty-repo rejection without --base-ref, and explicit-base dispatch on dirty repositories