releases/ClaudeDo
2
0
Fork 0
Code Issues 1 Pull Requests 2 Actions Packages Projects Releases 39 Wiki Activity

docs(worker): document unit branch, child absorb and legacy approve routing

Browse Source
This commit is contained in:
mika kuns
2026-10-01 11:26:17 +02:00
parent 44d94caabc
commit 823368484e
2 changed files with 34 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/explore-notes/review-merge.md
+15 -8
View File
@@ -1,8 +1,8 @@
# Review, merge & conflict resolution
> **Explore-note — verify before trusting.** Distilled map of a subsystem, not authoritative.
> Last verified against `168ab1cd` (2026-08-26), which added the batch verify
> (`skipVerify` + `verify_merges`).
> Last verified against `44d94caa` (2026-10-01), which made the parent's worktree the unit
> branch (children fast-forwarded into it).
> Planning mode renders per file and `DiffLinesView` is retired.
> Drift check: `git log --oneline 20bce9b..HEAD -- src/ClaudeDo.Worker/Lifecycle src/ClaudeDo.Worker/State src/ClaudeDo.Worker/Planning src/ClaudeDo.Ui/ViewModels/Conflicts src/ClaudeDo.Worker/External`
> Stable structure only (no line numbers). See docs/explore-notes/README.md.
@@ -15,11 +15,17 @@ Covers the review→merge path: `TaskStateService` review transitions, `TaskMerg
`ApproveReview` (hub) and `review_task` approve (MCP) are the **single** review+merge action.
There is no separate "Merge all" entry.
- **Task with children** → drives `PlanningMergeOrchestrator`: merges the parent worktree if
`Active`, then each `Done` child in order, then sets the parent `Done`. A mid-merge conflict
pauses for `ContinuePlanningMerge` / `AbortPlanningMerge`.
- **Childless task** → `TaskMergeService.ApproveAndMergeAsync`. A conflict keeps the task in
`WaitingForReview`.
- **Legacy unit** (`UnitBranchService.HasUnabsorbedChildrenAsync`: a `Done` child whose worktree
is still `Active`, i.e. planned before the unit branch existed) → drives
`PlanningMergeOrchestrator`: merges the parent worktree if `Active` (planning parents too, for a
mixed unit), then each `Done` child in order, then sets the parent `Done`. A mid-merge conflict
pauses for `ContinuePlanningMerge` / `AbortPlanningMerge`. Children in `WaitingForReview` are
silently skipped there.
- **Everything else** — a childless task, or a parent whose children were absorbed into its unit
branch → `TaskMergeService.ApproveAndMergeAsync` on the task's own worktree. A conflict keeps
the task in `WaitingForReview`.
- **Child of a unit** (parent has an `Active` worktree) → `ApproveAndMergeAsync` absorbs it into
the unit branch (`UnitBranchService.AbsorbChildAsync`, ff-only) instead of merging to the target.
- **No active worktree** (sandbox run) → straight to `Done`.
Review transitions all live in `TaskStateService`: `SubmitForReviewAsync`,
@@ -203,7 +209,8 @@ succeeds, written **only** by `WorktreeRepository.SetMergedAsync` (which atomica
It is the only thing that makes `revert_merge` possible without heuristically searching
`git log` — see [external-mcp.md](external-mcp.md) → `RevertMerge`. Null for any worktree
merged before the field existed.
merged before the field existed, and for a child absorbed into its unit branch (a fast-forward
has no merge commit) — such a child is reverted with its whole unit, never alone.
## Review gate in the UI