Co-authored-by: ayattara <alassane.yattara@savoirfairelinux.com> Co-authored-by: Carlos Florencio <carlosmflorencio@gmail.com>
3.9 KiB
status, system, requirements, created, updated, owners
| status | system | requirements | created | updated | owners | ||
|---|---|---|---|---|---|---|---|
| draft | tasks |
|
2026-08-30 | 2026-09-14 |
|
Managed Branch Compaction System Design
Purpose and boundaries
This design extends Task Runtime Cleanup for the disposition of managed local branches at terminal task boundaries. It defines capture of ownership and integration metadata on canonical task-environment repository rows, the fail-closed eligibility checks under the repository lock, the exact-head recovery protocol, bounded archived-branch maintenance, and the bounded cleanup receipt.
It does not change task deletion semantics, remote refs, branch-policy configuration, or archive and unarchive state ownership.
Requirement mapping
| Requirement | Design source |
|---|---|
| REQ-TASKS-MANAGED-BRANCH-COMPACTION-001 | Sections below |
Decision source
ADR-2026-08-30-compact-integrated-managed-branches
Metadata capture
Every task-environment repository row that materializes a worktree branch persists three conservative fields, each defaulting to unknown or empty for legacy rows without inference:
worktree_branch_owner:kandev,external, orunknown;worktree_integration_ref: the intended base or integration branch, resolved from the task branch policy pull-request target first, then the contribution destination target, then the task repository base branch;worktree_recovery_head_shaplusworktree_branch_compacted_at: the exact compaction recovery state, empty until a deletion is prepared.
Missing or ambiguous metadata always retains the branch.
Terminal compaction boundary
Immediately after a terminal cleanup successfully removes the worktree
registration, while still holding the existing repository lock, cleanup
considers exactly one explicit candidate local branch. The candidate is
eligible only when the persisted owner is kandev, exactly one durable
environment-repository row owns the repository and branch identity, no live Git
worktree uses the branch, the branch is neither protected nor the repository
default, base, or integration ref, and the branch's exact tip is an ancestor of
the exact persisted integration ref. Cleanup never fetches, globs, enumerates
unrelated refs, or infers eligibility from names, age, or convention.
Before deletion, cleanup persists the exact candidate head SHA with
compare-and-set semantics, then removes the branch with
git update-ref -d refs/heads/<branch> <expected-head-sha>. An expected-head
mismatch or any check failure retains the branch and leaves the state retryable.
Exact-head recovery
Recreation after archive or unarchive restores a missing managed branch from the recorded exact head before any refreshed-origin or contribution materialization can select a different head. A local branch of the same name must resolve to the recorded head or recovery fails closed. The hidden identity-derived recovery ref is deleted before the durable recovery fields are CAS-cleared, so every interruption point remains retryable. Branches that were never compacted keep the existing preserved-local-ref behavior and restore without rewriting their tip.
Bounded archived maintenance
Storage maintenance selects at most 100 archived, inactive, deleted-worktree rows per run without scanning names, revalidates archived state and session inactivity immediately before mutation, and reuses the same manager-owned policy. Interrupted rows retry; a durable completion marker prevents reselection. A branch that becomes live during deletion is restored at the exact recorded head and retained.
Observability
Each cleanup operation returns a bounded receipt with attempted, deleted, and retained counts plus fixed retained-reason counts. Logs and metrics expose the same bounded labels without branch lists, secrets, commit contents, or unbounded cardinality.