docs(workflow): make parallel worktree lanes mergeable across Codex tasks #184

Problem

Parallel OpenCodex rounds now have several independent PRs targeting dev at the same time. The repository has the pieces for this workflow, but the lane manifest, collision check, hosted-CI handoff, and merge ownership are spread across separate rules. That makes it easy to create duplicate work for one issue, let a lower layer drift while an upper layer is being reviewed, or recover the wrong worktree after a timeout or context compaction.

The current round is a concrete example: #4741, #4737, #4729, #4736, and #4743 are separate new PRs with different authors and overlapping integration pressure. The links below are evidence for the workflow design; they are not a request to merge those PRs automatically.

Existing evidence

• CodexClaw docs(plan): diff-level roadmap for the Windows issue sweep stack (L0) #146 documents a manual L0-L6 stack, a bottom-up merge order, and the rule that stacked children must keep their parent base. docs(plan): diff-level roadmap for the Windows issue sweep stack (L0) #146
• CodexClaw Separate thread dispatch from subagent dispatch, and add DEV-STACK-08 #163 separates thread worktrees from in-lane subagents and records DEV-STACK-08 for the child-chain merge exception. Separate thread dispatch from subagent dispatch, and add DEV-STACK-08 #163
• CodexClaw feat(recall): key project scope by normalized git origin so managed worktrees join their main checkout #127 scopes recall by normalized git origin so managed worktrees join the main checkout. feat(recall): key project scope by normalized git origin so managed worktrees join their main checkout #127
• CodexClaw fix(provider-bridge): reuse win-exec for PATHEXT resolution and ComSpec routing (L1, #131) #147 was closed unmerged while the same L1 work landed through fix(provider-bridge): reuse win-exec for PATHEXT resolution and ComSpec routing (L1, #131) #153, showing how duplicate lane ownership creates avoidable rework. fix(provider-bridge): reuse win-exec for PATHEXT resolution and ComSpec routing (L1, #131) #147 fix(provider-bridge): reuse win-exec for PATHEXT resolution and ComSpec routing (L1, #131) #153
• CodexClaw delegation: 분석 중인 서브에이전트를 조기 회수하지 않도록 판단 기준 개선 #178 records early recovery of a still-reading subagent as a coordination failure. delegation: 분석 중인 서브에이전트를 조기 회수하지 않도록 판단 기준 개선 #178
• CodexClaw ci: dev is deleted after every release promotion (delete_branch_on_merge plus the cleanup workflow), breaking the target-branch rule #175 records the danger of branch cleanup deleting an integration branch. ci: dev is deleted after every release promotion (delete_branch_on_merge plus the cleanup workflow), breaking the target-branch rule #175
• CodexClaw ci: shard Windows test legs, aggregate ci check, WSL lane on integration-line pushes only #121 records CI sharding and aggregate checks for parallel platform work. ci: shard Windows test legs, aggregate ci check, WSL lane on integration-line pushes only #121
• OpenCodex currently requires dev as the integration target and treats stacked child bases as an explicit CI case. https://github.com/lidge-jun/opencodex/blob/dev/.github/workflows/enforce-pr-target.yml
• The current OpenCodex candidate lanes are #4741, #4737, #4729, #4736, and #4743. fix(retry): stop ambiguous reset replay across recovery boundaries opencodex#4741 fix(codex): handle nested error object in token refresh and classify refresh_token_invalidated as revoked opencodex#4737 [Bug] Accept unambiguous bare tool-name echoes for namespaced tools (Command Code muse family) opencodex#4729 fix(catalog): write every slug exactly once from retained sync (#4730) opencodex#4736 fix(web-search): bound withheld tool events and close cells on read failure opencodex#4743

These pages and the current authenticated GitHub state were researched through the Aside signed-in browser session on 2026-09-16.

Proposed workflow contract

1. Create one isolated worktree task per implementation lane. Record lane id, task id, worktree path, branch, base SHA, source PR or issue, owner, touched-path summary, and current head SHA.
2. Before writing, fetch origin/dev and check open PRs and existing worktrees for the same issue, branch, and dominant files. A collision must be resolved by choosing one owner or making the lanes explicitly disjoint.
3. The thread owns its worktree. In-lane subagents may inspect or edit only the assigned scope and must not merge, retarget, rebase, or push another lane. The host owns rebase decisions and the final merge.
4. Verify hosted CI at the exact head SHA. Record workflow event, ref, check-run IDs, and whether path filters omitted a required shard. A heartbeat or timeout is a wakeup mechanism, not evidence that work is complete.
5. Merge an ordinary stack bottom-up. For a cumulative child chain, follow the DEV-STACK-08 top-down cascade into its parent before the parent lands in dev. After absorbing a newer dev head, rerun exact-head tip evidence before merging.
6. Treat branch cleanup as a separate lifecycle decision. Never delete or recreate a long-lived integration branch as part of routine closed-PR cleanup.

Acceptance criteria

• Add a concise lane-manifest and collision-preflight recipe to the relevant CodexClaw workflow documentation.
• Define the ownership boundary between host, worktree thread, and in-lane subagent, including the rule that the host makes rebase and merge decisions.
• Define exact-head hosted-CI evidence and the recovery procedure after timeout or context compaction.
• Document ordinary bottom-up stacks, the DEV-STACK-08 cumulative-child exception, and the [WRONG BRANCH] expectation for stacked children.
• Add a lightweight regression or fixture that detects duplicate issue ownership or a missing lane base/head record without running repository-wide tests.
• Keep the workflow compatible with repositories that prohibit local suites and use hosted CI as the verification source.

Scope

This issue is for CodexClaw workflow guidance and its smallest supporting checks. It does not merge or rewrite the OpenCodex candidate PRs listed above, and it does not introduce a replacement runtime or a new GitHub-native stack dependency.