Parallelism with worktrees
How woostack isolates bounded implementation work independently from artifact storage.
Worktrees isolate tracked writes. They do not own scope, approval, status, or acceptance. The canonical worktree contract defines collision checks, ancestry, recovery, and teardown.
One worktree per bounded task
Each active task has one controller/run identity, one branch, one worktree, one allowed surface, and at most one implementation PR. Local run manifests and task IDs remain separate from optional provider identities and mirror records.
.woostack/worktrees/tasks/<stable-task-id>Before create, resume, review reopen, commit, or teardown, woostack reconciles the deterministic
path and active task/run contract directly with filesystem state, git worktree list --porcelain,
local/remote branches and commits, dirty/index/diff state, Graphite ancestry, and canonical GitHub
PR facts. The branch may have only one checkout and every observed head/base/path must form one
consistent state.
For new work, git worktree add -b creates the branch and deterministic checkout together and lets
Git reject an existing branch, path, or checkout. A retained task resumes only when every direct
fact agrees with the same approved contract or completely verified handoff. Partial, foreign, or
competing state blocks without reset, stash, deletion, adoption, or create-around.
The parent branch intent and last admitted tip come from approved content and verified Git ancestry. A same-branch descendant tip is compatible only when fresh delivery-checkpoint and current-head review/check evidence match that exact tip. Fresh work then starts at the latest re-admitted tip, while retained work preserves its recorded start/head and revalidates ancestry, diff, and PR base without silent rebase, reset, or recreate.
| Task kind | Fresh branch start | Graphite parent |
|---|---|---|
| Standalone task | latest compatible tip of the integration branch | integration branch |
| Independent feature root | latest compatible tip of the approved parent branch | approved parent branch |
| Dependency child | latest compatible tip/head of its declared Git parent | declared parent branch |
Branch identity changes, rewrites, conflicts, duplicate ancestry, delivery-evidence mismatch, and incomplete evidence block. Titles, nearby branches, artifact relations alone, and task order do not substitute for the approved dependency graph and Git ancestry.
The primary tree stays clean
Tracked implementation writes land in the task worktree. The primary checkout remains a clean, stable coordination point.
Execute processes tasks strictly sequentially within each local run. Distinct local run IDs may run concurrently only when their responsibility surfaces, branches, worktrees, and PRs are disjoint. Dependent tasks always follow their declared Git parent. Subagents receive the exact path and verify that their physical working directory matches the Git top level before writing.
Teardown and recovery
- Success: after the finalized commit and canonical PR identity read back and the task worktree is clean, remove only the exact deterministic worktree. Branch, commits, PR, and remote evidence remain.
- Failure, handoff, or unknown: preserve the worktree. Report task/run contract, deterministic path, worktree inventory, branch/ancestry, dirty state, observed boundary, and safe next action; a timeout proves neither success nor absence.
- Review reopen: reattach only the existing verified branch/head when its deterministic path is free and the branch is checked out nowhere; never invent or adopt an unrelated checkout.
Artifact synchronization and delivery evidence remain separate. Optional provider failure never weakens local collision or ancestry checks and is nonblocking for verified local authority.