ClaudeDo/docs/superpowers/specs/2026-10-01-unit-branch-draft-pr-design.md

# Unit-Branch + Draft-PR — Design

**Datum:** 2026-10-01 · **Status:** abgenommen (mit Basis-Branch pro Liste + Fetch)
**Diagramme:** Obsidian `07 - Plattform & Technik/ClaudeDo/ClaudeDo - Branch und PR Ablauf.md`
**Ersetzt:** die offene Entscheidung aus `2026-08-06-planning-chain-fork-base-design.md`

## Ziel

Aufgaben starten und später zu fertigen PRs zurückkommen. In Firmen-Repos (Azure DevOps Server)
heißen Branches nach dem work-conventions-Schema, und das Review endet in einem **Draft-PR** statt
in einem lokalen Merge auf `main`. Nebenbei sehen Planning-Children endlich die Arbeit ihres
Vorgängers.

## Begriffe

- **Unit:** ein einzelner Task, oder ein Parent (Planning oder Improvement) samt Children.
- **Unit-Branch:** der eine Branch, auf dem die ganze Arbeit einer Unit landet. Er gehört dem
  Worktree des Unit-Roots (Einzeltask bzw. Parent).
- **Firmen-Repo:** Die `origin`-URL enthält `company_remote_pattern` (`worker.config.json`,
  Default `/_git/`, nur per Hand editierbar). Geprüft wird live über `git remote get-url origin`
  und ohne Cache.

## Entscheidungen

| Frage | Entscheidung |
|---|---|
| Branchname | Einheitlich `<typ>/<nummer>-<slug>`. Die Nummer ist die Ticket-Id aus `TicketRef` (beim Child die des Unit-Roots), sonst privat die Task-Nummer. Im Firmen-Repo ohne Ticket entfällt sie (`<typ>/<slug>`). `claudedo/{nr}-…` fällt weg. Planning-Session-Worktrees bleiben `claudedo/planning/{guid}`. |
| Typ | `feat`→`feature`. `fix`, `refactor`, `docs`, `test`, `chore` bleiben, wie sie sind. Alles andere (`ci`, `perf`, `style`, `build`) wird `chore`. |
| Slug | `CommitMessageBuilder.ToSlug` plus Umlaut-Auflösung (`ä→ae`, `ö→oe`, `ü→ue`, `ß→ss`), ≤40 Zeichen wie heute. |
| Children | Starten vom aktuellen Head des Unit-Branches. Ist ein Child fertig, wird der Unit-Branch sofort per **fast-forward** auf den Head des Childs gezogen. Das gilt privat und in Firmen-Repos. |
| Review-Ende privat | Unverändert: Approve merged den Unit-Branch auf `main`, dann läuft Verify auf `main`. |
| Review-Ende Firma | Approve führt Verify im Worktree des Unit-Roots aus, dann Push und Draft-PR. Der Task bleibt `WaitingForReview` mit PR-Link. `Done` setzt Mika per Toggle nach dem ADO-Merge. |
| PR-Automatik | Kein Auto-PR bei einem Statuswechsel. Automatisiert wird über den Merge-Helper, dessen `approve` dann den PR erzeugt. |
| ADO-Zugang | Eigener PAT (Scope Code Read & Write). Er wird per `DpapiTokenStore` in `~/.claudeDo/azdo.pat` gespeichert, ohne Abhängigkeit auf das work-conventions-Plugin. |
| dependsOn über Units | Wartet bewusst auf den echten Merge. Abhängige Arbeit gehört in eine Unit mit einem PR. |
| Basis-Branch | Pro Liste einstellbar (`list_config.base_branch`, z.B. `dev` für die LagerApp). Leer heißt: privat der gerade ausgecheckte Branch des Main-Checkouts (wie heute), Firma der Default-Branch des ADO-Repos. Gilt als Basis des Unit-Branches, als PR-Ziel und als Vorauswahl des privaten Merge-Ziels. |
| Basis aktualisieren | Firmen-Repo: `git fetch origin <basis>`, bevor der Unit-Branch angelegt wird. Der Unit-Branch startet von `origin/<basis>`, der lokale Basis-Branch wird best-effort per fast-forward nachgezogen. |

## 1. Branch-Naming (`WorktreeManager`)

- `NameFor(task, ticketId, isCompany)` liefert den Leaf `<nummer>-<slug>` bzw. `<slug>`, und
  `BranchFor` liefert `<typ>/<leaf>`. Der Ordnername des Worktrees bleibt der Leaf.
- **Kollisionsprüfung** (heute `Contains($"claudedo/{name}")`, Zeile 83) prüft den neuen vollen
  Branchnamen. Bei einem Treffer kommt das Id-Suffix dran, wie heute.
- **Self-Heal** (`git branch -D` nach „already exists“) läuft nur noch, wenn der Branch in einer
  `worktrees`-Zeile steht, deren Task der aktuelle Task ist. Sonst gibt es keinen Delete, sondern
  das Id-Suffix, und der Branch des Nutzers bleibt unangetastet. Ohne das Präfix `claudedo/` ist
  das Pflicht, sonst löscht ClaudeDo einen fremden `feature/…`-Branch.
- **`UntrackedWorktreeRecovery`** filtert statt nach dem Präfix nach „Worktree-Pfad liegt unter
  einer ClaudeDo-Worktree-Root (`.claudedo-worktrees` bzw. Central-Root), aber nicht unter
  `planning/`“.
- `PlanningAggregator.CleanupIntegrationBranchAsync:137` (Präfix-Check beim Checkout-Fallback)
  wird mit Abschnitt 3 ohnehin hinfällig.
- Bestehende Worktrees behalten ihren Namen. Der Branchname steht in der DB und wird nie neu
  abgeleitet, eine Migration ist also nicht nötig.
- **Bugfix nebenbei:** `DetailsIslandViewModel.cs:1223/1385` baut für Dialogtexte
  `claudedo/{Task.Id}`, das ist schon heute falsch. Künftig steht dort `worktree.BranchName`. Das
  literale `"← main"` (`:670/:933`) zeigt das echte Ziel an.

## 2. Unit-Branch und Children

**Wer besitzt den Unit-Branch?**
- **Einzeltask:** sein eigener Worktree. Am Ablauf ändert sich nichts.
- **Improvement-Parent:** sein eigener Worktree, den er schon heute hat. Seine Children starten
  schon heute von `parent.HeadCommit`.
- **Planning-Parent:** hat heute **keinen** Worktree. Neu: `QueuePlanAsync` legt per
  `WorktreeManager.CreateAsync` einen Worktree für den Parent an, auf dem Unit-Branch und mit
  `main` HEAD als Basis. Damit hat jeder Parent eine `worktrees`-Zeile, die den Unit-Branch und
  später die PR-URL trägt.

**Basis eines Childs** (`ResolveBaseCommitAsync`): Das ist immer der aktuelle Head des
Unit-Branches (`rev-parse <unitBranch>`). Der Sonderfall „nur bei `PlanningPhase.None`“ fällt weg.

**Basis eines Unit-Roots** (Einzeltask, Parent):
- **Privat:** `list_config.base_branch`, sonst der ausgecheckte Branch des Main-Checkouts. Heute
  ist es `RevParseHeadAsync`. Ist `base_branch` gesetzt, wird es `rev-parse <base_branch>`, auch
  wenn gerade ein anderer Branch ausgecheckt ist.
- **Firma:**
  - Zuerst `git fetch origin <basis>`. `<basis>` ist `base_branch`, sonst der Default-Branch des
    Repos per ADO-API, ersatzweise `git symbolic-ref refs/remotes/origin/HEAD`.
  - Der Unit-Branch startet von `origin/<basis>`.
  - Dann wird der lokale `<basis>` best-effort nachgezogen:
    - nicht ausgecheckt: `git fetch origin <basis>:<basis>` (lehnt einen nicht-fast-forward
      selbst ab)
    - ausgecheckt und sauber: `git -C <workingDir> merge --ff-only origin/<basis>`
    - schmutzig oder divergiert: Warnung ins Log, kein Eingriff in den Checkout
  - Schlägt der Fetch fehl (offline, keine Credentials), wird gewarnt und es geht mit dem
    lokalen `<basis>` weiter. Der Task scheitert daran nicht.
  - Der Fetch nutzt dieselbe PAT-Übergabe wie der Push (Abschnitt 3).
- Der Fetch läuft einmal pro Unit-Root, nicht pro Child. Children starten vom Unit-Branch.

**Spalte `list_config.base_branch`** (nullable string, Migration):
- Sie wird im Listeneinstellungs-Modal gepflegt, als Freitext mit Vorschlägen aus
  `ListLocalBranchesAsync`, und in `get_list_config` mitgeliefert.
- ⚠️ `ListRepository.SetConfigAsync` kopiert verbatim (siehe `TicketProjectId`). Jeder Schreiber
  muss den Wert durchreichen, sonst setzt ihn z.B. `set_list_config` still zurück:
  `WorkerHub.UpdateListConfig`, `ConfigMcpTools`, alle Stellen, die eine frische
  `ListConfigEntity` bauen.
- `UpdateListConfigDto` braucht ihn tri-state wie `TicketProjectId`, damit ein Aufrufer, der das
  Feld nicht kennt, es nicht löscht.
- **Merge-Ziel privat:** `TaskMergeService.GetTargetsAsync` setzt `DefaultBranch` auf
  `base_branch`, falls gesetzt. Das leere Ziel (`ApproveAndMergeAsync:1077`, `PreviewAsync:910`)
  löst ebenfalls auf `base_branch` auf, sonst wie heute.

**Absorbieren eines Childs:** Neu ist `UnitBranchService.AbsorbChildAsync(childId)`, das in
`git -C <parentWorktree> merge --ff-only <childBranch>` mündet.
- Die Kette ist seriell (`BlockedByTaskId`), und das Child startet vom Head des Unit-Branches.
  Deshalb ist es **immer** ein fast-forward, Konflikte sind ausgeschlossen. Lässt es sich nicht
  fast-forwarden, z.B. weil jemand ein Child manuell parallel per „Run now“ gestartet hat, wird
  das Child `Failed` mit einer klaren Meldung, ohne Merge-Versuch.
  `ponytail: kein Merge-Fallback; einbauen, falls parallele Children ein echter Fall werden.`
- Danach wird der Worktree des Childs entfernt, der Branch gelöscht und die Zeile auf `Merged`
  gesetzt (`MergeCommit` = null, denn es gibt keinen Merge-Commit). `revert_merge` greift auf
  Child-Ebene deshalb nicht, revertiert wird die ganze Unit.
- Aufgerufen wird es aus `TaskRunner.HandleSuccess` direkt vor `_state.CompleteAsync`. Ein
  ff-Fehler wird so zu `FailAsync` statt zu einem Unblock des Nachfolgers.
- Interaktive Children landen in `WaitingForReview`, und ihr Approve geht durch
  `TaskMergeService.ApproveAndMergeAsync`. Dort gilt neu: Hat der Task einen Parent mit eigenem
  Worktree, wird `AbsorbChildAsync` aufgerufen statt auf das Ziel gemergt.
- Kein Git-Code in `TaskStateService` oder `PlanningChainCoordinator`, die bleiben git-frei.

**Was dabei wegfällt:** Den Unit-Merge Child für Child am Ende gibt es für neue Units nicht mehr.
Ein Parent wird beim Approve wie ein Einzeltask behandelt, über seinen eigenen Worktree in
`TaskMergeService.ApproveAndMergeAsync`. Auch der Integration-Branch
(`PlanningAggregator`, `planning/{slug}-integration`, dafür `checkout -b` im Main-Checkout) ist
für neue Units unnötig, denn der kombinierte Diff ist `unitBase..unitHead`.

**Routing beim Approve** (`WorkerHub.ApproveReview`, `ExternalMcpService.ReviewTask`): Heute
geht jeder Task mit Children an den Orchestrator. Neu gilt: Gibt es ein `Done`-Child mit einem
`Active`-Worktree, also eins, das nicht absorbiert wurde, läuft der Legacy-Orchestrator. Sonst
geht es über `ApproveAndMergeAsync` auf den Worktree des Parents.

**Altbestand:** Parents ohne eigenen Worktree (vor dem Rollout geplant) laufen weiter über
`PlanningMergeOrchestrator` und den bestehenden Aggregator. Diesen Legacy-Pfad entfernen wir in
einem Folge-Task, sobald keine solchen Units mehr offen sind.

## 3. Approve im Firmen-Repo

`TaskMergeService.ApproveAndMergeAsync` verzweigt nach `IsCompanyRepo(list)`:

1. **Verify** im Worktree des Unit-Roots (`IVerifyCommandRunner.RunAsync(worktreePath, …)`), nicht
   im Main-Checkout. Ohne Verify-Command entfällt der Schritt. Rot heißt: Ergebnis
   `verify_failed`, der Task bleibt `WaitingForReview`, kein Push. `skipVerify` wird im
   Firmen-Modus ignoriert, weil kein Merge landet, auf den man das Verify verschieben könnte.
2. **Push** mit `git -C <worktree> push -u origin <unitBranch>`. Der PAT geht als
   `http.extraHeader` über `GIT_CONFIG_COUNT`/`GIT_CONFIG_KEY_0`/`GIT_CONFIG_VALUE_0` in der
   Prozess-Umgebung mit. Er steht also nicht in der Kommandozeile, und es gibt keinen
   Credential-Manager-Prompt im Hintergrundprozess.
3. **PR**, neuer `AzureDevOpsClient`, portiert aus `pr-create.ps1`:
   - Der Remote wird an `/_git/` zerlegt: API-Basis = alles davor, Repo = Segment danach.
     Eingebettete Zugangsdaten fliegen raus.
   - `GET …/pullrequests?searchCriteria.sourceRefName=refs/heads/<branch>&searchCriteria.status=active`.
     Gibt es schon einen PR, wird er wiederverwendet (idempotent, auch wenn der Skill in der
     Session schon einen angelegt hat).
   - Sonst `POST …/pullrequests` mit `isDraft: true` und `targetRefName = <basis>`. Das ist
     `list_config.base_branch`, sonst `defaultBranch` aus `GET …/repositories/<repo>`.
   - Die API-Version fällt auf die zurück, die der Server in seiner Fehlermeldung nennt, wie im
     Skript.
4. Die **PR-URL** wird gespeichert, in der neuen nullable Spalte `worktrees.pull_request_url`
   (Migration). Danach folgen `WorktreeUpdated` und der Rückgabestatus `pr_created` bzw.
   `pr_updated`.
5. Der Task bleibt `WaitingForReview`, der Worktree bleibt `Active`, und das Ticket bleibt auf
   `InBearbeitung`.

**PR-Inhalt:**
- **Titel:** `<commitType>(<list-slug>): <titel>, Resolves #<ticket>`. Ohne Ticket entfällt
  `Resolves`.
- **Beschreibung:**
  - `Resolves [#412](<ticket-url>)`. Die Projekt-Id kommt über `BandelTicketClient.GetTicketAsync`
    → `ParentTicketID` (bei Tasks eine Ebene höher). Ohne Id gibt es keinen Link.
  - Leerzeile, dann die Task-Beschreibung.
  - Leerzeile, dann `Geprüft: <verify command> grün` bzw. `Geprüft: nichts automatisch`.

**Commits im Firmen-Repo:** `CommitMessageBuilder` lässt den Trailer `ClaudeDo-Task:` weg. Er
wird nirgends gelesen, und die Konvention verbietet Signatur-Trailer.

**Rerun nach Änderungswunsch:** Ein normaler Reject mit Feedback, der auf demselben Worktree
weiterläuft. Der nächste Approve pusht nach, und der vorhandene PR aktualisiert sich.

**Fehler:** Fehlt der PAT, wird der Push abgelehnt oder scheitert ein REST-Aufruf, dann landen
Statusmeldung und Footer-Strip (`FlashFooterError`) beim Nutzer, und der Task bleibt
`WaitingForReview`. Scheitert der PR nach einem erfolgreichen Push, sagt die Meldung das genau
so: „gepusht, PR fehlgeschlagen: …“.

**Laufzeit:** Verify plus Push können länger als 5 s dauern. Der MCP-Pfad meldet deshalb Progress
über `ProgressReporter`, sonst bricht der MCP-Client nach 300 s Leerlauf ab.

## 4. Merge-Helper

Die Prompts in `PromptFiles` (merge und merge_final) bekommen einen Firmen-Repo-Absatz:
- `review_task approve` liefert `pr_created`/`pr_updated` mit URL.
- `verify_merges` entfällt, weil das Verify bereits im Approve läuft.
- Die Abschluss-Zusammenfassung listet die PR-Links auf.
- Die Regel „erst mergen, dann neu starten“ bleibt harmlos, da `main` sich nicht bewegt.

## 5. UI

- Der Settings-Reiter „Ticketsystem“ heißt künftig **„Externe Dienste“**. Er bekommt einen
  zweiten Abschnitt **Azure DevOps** mit PAT-Feld, Test-Button und Löschen-Button, gespiegelt vom
  Ticket-PAT.
- Neue Hub-Methoden: `GetAzureDevOpsSettings`, `SetAzureDevOpsToken`, `ClearAzureDevOpsToken`,
  `TestAzureDevOpsConnection`. Neuer DI-Marker `AzureDevOpsPatStore`.
- Der Test braucht ein Firmen-Repo als Kontext: Er nimmt die erste Liste, deren `origin` passt,
  und ruft `GET …/repositories/<repo>` auf.
- Im Detail-Pane heißt der Approve-Button im Firmen-Repo **„Draft-PR erstellen“**. Er ist weiter
  hinter „Diff öffnen“ gegated, und das Ziel-Dropdown ist ausgeblendet. Ist eine PR-URL gesetzt,
  erscheint ein Link und der Button heißt „PR aktualisieren“.
- Locale-Keys kommen in `en.json` und `de.json` gleichzeitig hinzu.

## 6. Bewusst draußen

- PR-Status-Polling bzw. automatisches `Done` nach dem ADO-Merge.
- Andere PR-Provider als Azure DevOps. `company_remote_pattern` schaltet nur das Schema um, die
  PR-API ist ADO-spezifisch.
- Aufräumen von Worktree und lokalem Branch, wenn ein Firmen-Task auf `Done` gesetzt wird. Das
  geht über die bestehende Worktree-Übersicht.
- `git fetch` in privaten Repos. Die Basis bleibt dort lokal.
- Eine UI für `company_remote_pattern`.

## 7. Tests

Keine Tests mit der echten Claude-CLI und keine gegen das echte ADO.

- **Naming:** Typ-Mapping, Nummernregel (Ticket, privat, Firma ohne Ticket), Umlaute,
  Kollision mit einem fremden Branch (der Branch überlebt, das Suffix greift), Self-Heal löscht
  nur DB-eigene Branches. Die betroffenen Asserts in `WorktreeManagerTests` (`:69`, `:131/138`,
  `:160`, `:314`) passe ich an.
- **Unit-Branch** (echtes git, Worker.Tests):
  - Ein Child startet vom Head des Unit-Branches.
  - Zwei serielle Children werden per fast-forward absorbiert, und Child 2 sieht die Dateien von
    Child 1.
  - Ein nicht fast-forwardbares Child wird `Failed`.
  - Ein Planning-Parent bekommt seinen Worktree bei `QueuePlanAsync`.
- **Approve Firma:**
  - Ein lokales Bare-Repo dient als `origin`, und das Muster wird auf dessen Pfad gesetzt.
  - `AzureDevOpsClient` wird gefakt: PR anlegen, vorhandenen PR wiederverwenden, Verify rot
    heißt kein Push, PR-Fehler nach dem Push.
- **Remote-Parsing:** die Fälle aus dem `-SelfTest` des Skripts.
- **Basis:**
  - `base_branch` gesetzt: Der Unit-Root startet davon, auch wenn ein anderer Branch ausgecheckt
    ist.
  - Firma: Nach dem Fetch startet der Unit-Root von `origin/<basis>`. Das testet ein Bare-Repo,
    das einen Commit voraus ist.
  - Der lokale Basis-Branch wird nachgezogen, ein schmutziger Checkout bleibt unangetastet.
  - Ein Fetch-Fehler bricht den Task nicht.
  - `SetConfigAsync`, `set_list_config` und `UpdateListConfig` erhalten `base_branch`.
- **Manueller Smoke-Test (Mika):** PAT eintragen, Test-Button. Ein Ticket-Task in einem echten
  Firmen-Repo bis zum Draft-PR durchspielen, danach eine Planning-Unit mit 2 Children.