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

src/ClaudeDo.Worker/CLAUDE.md

@@ -96,6 +96,19 @@ nothing to merge; a worktree task's branch just stays Active for the worktrees o
 `… → WaitingForChildren → WaitingForReview → Done` via the single `TryAdvanceParentAsync`.
 Planning/improvement **children** go straight to `Done`; only the parent is reviewed.
 
+**Unit branch.** The parent's own worktree is the unit branch (improvement parents have it from
+their run, planning parents get it in `QueuePlanAsync` via `UnitBranchService.EnsureUnitWorktreeAsync`).
+Children fork from its current head and `UnitBranchService.AbsorbChildAsync` fast-forwards it to
+the child (`merge --ff-only` in the parent worktree) — from `TaskRunner.HandleSuccess` right before
+`CompleteAsync`, and from `TaskMergeService.ApproveAndMergeAsync` for an interactive child in
+review. The child row goes `Merged` with `MergeCommit` null (so `revert_merge` only works on the
+whole unit), its worktree and branch are removed, the parent row's `HeadCommit`/`DiffStat` move
+along. A child that can't fast-forward (e.g. started in parallel via Run now) is `Failed` — no
+merge fallback; in the approve path it stays `WaitingForReview` with a `blocked` result.
+`UnitBranchService` never writes task status (it would close a DI cycle through
+`PlanningChainCoordinator`). ⚠️ `QueuePicker` counts `worktrees.state='merged'` as a satisfied
+dependency, so an absorbed child satisfies a `dependsOn` edge although nothing reached `main` yet.
+
 **Approve = merge the whole unit.** `ApproveReview` / `review_task` approve is the single
 review+merge action — there is no separate "Merge all". Details, plus the post-merge verify
 gate and the conflict resolver → [review-merge](../../docs/explore-notes/review-merge.md).
@@ -108,6 +121,11 @@ gate and the conflict resolver → [review-merge](../../docs/explore-notes/revie
 2. `PlanningChainCoordinator.SetupChainAsync(parent, enqueue: false)` establishes the blocked-by chain (child[i] → child[i-1]) but **leaves children `Idle`** — finalize never auto-queues. Queueing is a deliberate user action: `QueuePlanAsync` (hub `QueuePlanningSubtasksAsync`, the "Queue plan" button) calls `SetupChainAsync(parent, enqueue: true)`.
 3. Once queued, the first child is woken automatically; successors unblock as their predecessor reaches a terminal state via `OnChildFinishedAsync`.
 
+`QueuePlanAsync` first gives the parent its worktree (the unit branch, see Unified parent model);
+the integration branch in `PlanningAggregator` (`planning/{slug}-integration`, `checkout -b` in the
+main checkout) is only built for legacy units — a parent that owns the unit returns
+`unitBase..unitBranch` as its combined diff.
+
 A child that hits a roadblock (fails, or reports `CLAUDEDO_BLOCKED`) does **not** advance the
 parent — it stays in `WaitingForChildren` until every child is terminal, with blocked children
 surfaced on the parent's Session tab instead.
@@ -130,7 +148,7 @@ Full flow, invariants, and model/effort/max-turns resolution (including the low-
 - **ClaudeProcess** — spawns `claude -p --output-format stream-json --verbose --permission-mode auto` (or whatever app settings specify). Prompt via stdin, NDJSON from stdout. CancellationToken kills the process tree. Resolves `_cfg.ClaudeBin` via `ExecutableResolver` (`ClaudeDo.Data`, shared with `ClaudeCliPreflight` and the Installer's checks) before spawning — a `.cmd`/`.bat` shim (e.g. an npm-installed `claude`) is launched through `cmd.exe /c` since `UseShellExecute = false` can't exec a shim directly; a resolved `.exe` starts exactly as before. Throws if nothing resolves. *(Not yet on `main` — see `Environment Checks` in `ClaudeDo.Installer/CLAUDE.md`.)*
 - **ClaudeArgsBuilder** — `--model`, `--effort`, `--max-turns`, `--append-system-prompt`, `--agents`, `--json-schema`, `--resume`
 - **StreamAnalyzer** — parses NDJSON; extracts session_id, token counts, turn counts, result text, structured output. Replaced MessageParser.
-- **WorktreeManager** — worktrees on `<typ>/<nummer>-<slug>` branches, same leaf as the folder (`NameFor`, slug capped at 40 chars, umlauts transliterated). Typ from `BranchTypeFor` (`feat`→`feature`, `fix/refactor/docs/test/chore` as-is, anything else `chore`). Nummer = ticket id (own `TicketRef` or the parent's), else the task number — in a company repo (`CompanyRepo`, origin matches `company_remote_pattern`) without a ticket no number at all. A taken folder/branch name gets an 8-char task-id suffix, so the self-heal never force-deletes a foreign branch. Base = parent head for children, else `list_config.base_branch`, else the checked-out HEAD. Commits with semantic messages, updates DB with head commit + diff stats
+- **WorktreeManager** — worktrees on `<typ>/<nummer>-<slug>` branches, same leaf as the folder (`NameFor`, slug capped at 40 chars, umlauts transliterated). Typ from `BranchTypeFor` (`feat`→`feature`, `fix/refactor/docs/test/chore` as-is, anything else `chore`). Nummer = ticket id (own `TicketRef` or the parent's), else the task number — in a company repo (`CompanyRepo`, origin matches `company_remote_pattern`) without a ticket no number at all. A taken folder/branch name gets an 8-char task-id suffix, so the self-heal never force-deletes a foreign branch. Base = `rev-parse <unit branch>` for a child whose parent has an Active worktree, else `list_config.base_branch`, else the checked-out HEAD. Commits with semantic messages, updates DB with head commit + diff stats
 - **CommitMessageBuilder** — `{commitType}(slug): title\n\ndescription\n\nClaudeDo-Task: taskId`; `BuildMerge` is the merge-commit variant (`{commitType}(slug): merge title` + trailer). **Every merge caller passes a blank commit message on purpose** — `TaskMergeService` fills in `BuildMerge` from the task's commit type and its list's name, which is the only place that knows both. Don't reintroduce a caller-side literal.
 - **TaskResetService** — discards a failed task's worktree, resets the row to Idle, preserves run history
 - **AgentFileService** — manages `~/.claudeDo/agents/*.md`; list/refresh via SignalR