Bluefly Worktree Lifecycle & Execution Surface Contract¶

Standard ID: STD-RUNTIME-004
Status: Approved / Enforced
Authority: Gas City Operating Doctrine, hq-wmsd.6, bl-dkbuyu
Applies to: All autonomous agents, operators, rigs, formulas, and worktrees

1. Executive Summary & Problem Statement¶

Work completion previously ended at bd close. Because work completion and execution surface cleanup were decoupled, the estate accumulated 160+ unmanaged directories, standalone clones, detached sessions, and broken gitdir pointers across worktrees and BluCity/.gc/worktrees.

This standard establishes the binding lifecycle governing the creation, execution, verification, and retirement of all worktrees and execution surfaces across the Bluefly platform.

2. The Twin Invariants of Factory Lifecycle¶

All autonomous agents and tooling must operate strictly under the Twin Invariants:

Rule 1: A Bead is not complete while its execution surface still exists.
Closing a work bead while its worktree or linked working directory remains active or registered on disk leaves behind execution debris and violates the factory contract.
Rule 2: An execution surface must never be deleted merely because a Bead claims to be complete.
Retirement requires independent, authoritative verification of remote push, release branch containment, MR status, and clean git working tree state before any directory may be deregistered or removed.

3. Canonical Definition of Work Completion (`WORK_COMPLETE`)¶

Work is not complete because code was written or a pull request was filed.
WORK_COMPLETE=YES strictly requires:

MR_MERGED=YES
DEPLOYED=YES              (when runtime deployment is governed)
RUNTIME_VERIFIED=YES      (proven against runtime target)
WORKTREE_CLEAN=YES        (zero uncommitted or untracked changes)
WORKTREE_DEREGISTERED=YES (pruned from git worktree list)
WORKTREE_REMOVED=YES      (directory safely trashed from filesystem)
BEAD_CLOSED=YES           (closed with authoritative terminal receipt)

Execution Sequence¶

The closeout lifecycle must follow this strict DAG ordering: 1. gather-receipt — inspect local commit SHA, diffstat, branch, and status. 2. verify-remote-push — prove local HEAD equals origin tracking branch. 3. verify-merge-containment — prove commit is merged into upstream target branch (origin/release/v0.1.x or origin/main). 4. verify-external-acceptance — verify GitLab MR status and CI pipeline success. 5. verify-worktree-clean — confirm working directory is 100% clean (git status --porcelain is empty). 6. retire-worktree — deregister and remove worktree from the parent repository root. 7. verify-retirement — confirm worktree is no longer registered and directory does not exist. 8. close-bead — execute bd close with terminal receipt metadata. 9. emit-terminal-receipt — emit standard factory completion receipt.

4. Physical Estate Separation¶

The Bluefly estate root strictly separates engineering checkouts from Gas City internal runtime states:

CANONICAL_ENGINEERING_WORKTREE_ROOT: [ESTATE_ROOT]/worktrees/ Exclusively reserved for active, bead-scoped engineering worktrees.
RUNTIME_ROOT: [ESTATE_ROOT]/BluCity/.gc/worktrees/ Exclusively reserved for Gas City internal session state (polecats/, refinery/).

Invariants:¶

Never Symlink Roots: The canonical engineering root must be a physical directory and must NEVER be symlinked to .gc/worktrees.
Never Create Clones in Worktree Roots: All engineering surfaces must be registered git worktrees (git worktree add). Standalone git clone directories inside worktree roots are strictly prohibited.
Bead-Scoped Naming: Every worktree must be named according to the formula:
```
[BEAD_ID]-[PROJECT_NAME]-[AGENT_NAME]
```
Example: hq-wmsd.6-blucity_packs-antigravity

5. Execution Surface Taxonomy (12-State Matrix)¶

The reconciliation patrol classifies all execution surfaces into 12 deterministic states:

State ID	Classification	State Description	Action Class
1	`REGISTERED_WORKTREE_CLEAN_MERGED`	Registered worktree, 0 uncommitted changes, commit merged into target	`AUTO_REMOVE`
2	`REGISTERED_WORKTREE_ACTIVE_SESSION`	Registered worktree attached to an active, running Gas City session	`PROTECTED`
3	`REGISTERED_WORKTREE_OPEN_MR`	Registered worktree associated with an open GitLab MR in progress	`PROTECTED`
4	`REGISTERED_WORKTREE_DIRTY`	Registered worktree containing modified or untracked files	`FINDING -> BEAD`
5	`REGISTERED_WORKTREE_UNMERGED_COMMITS`	Registered worktree with clean status but commits not merged into target	`FINDING -> BEAD`
6	`STANDALONE_CLONE_MERGED`	Standalone git clone directory, clean status, all commits merged to target	`AUTO_REMOVE` (trash)
7	`STANDALONE_CLONE_DIRTY_OR_UNMERGED`	Standalone git clone containing uncommitted or unmerged work	`FINDING -> BEAD`
8	`BROKEN_GITDIR_POINTER`	Worktree registration pointing to a missing or corrupted .git administrative dir	`AUTO_REMOVE` (`git worktree prune`)
9	`BROKEN_NAS_POINTER`	Checkout pointing to unreachable or stale NAS storage mount	`FINDING -> BEAD`
10	`RUNTIME_SESSION_ORPHAN`	Abandoned .gc runtime directory with no active process	`FINDING -> BEAD`
11	`EMPTY_OR_UNTRACKED_DIR`	Empty directory or folder without git metadata	`AUTO_REMOVE` (if empty) / `FINDING -> BEAD`
12	`UNCLASSIFIED_ANOMALY`	Any unrecognized or ambiguous directory structure	`FINDING -> BEAD`

6. Two-Action Operational Model¶

Automated lifecycle handlers operate under two mutually exclusive actions:

AUTO_REMOVE:
Strictly reserved for SAFE_TO_DISPOSE surfaces (clean + verified merged + no active session + no open MR).
Never uses destructive tools directly; uses trash for safe local removal.
Deletes branches only with safe ancestor checks (git branch -d, never -D).
FINDING -> BEAD:
Applied to any anomaly, dirty state, unmerged work, or broken mount.
Automatically logs an observable finding and emits a Beads work item for investigation.
Automated cleanup must NEVER silently destroy unmerged or dirty work.

7. External Worktree Retirement Algorithm¶

An execution surface must never attempt to remove itself from inside its own working directory. Doing so produces corrupt shell process state, cwd locking, and incomplete file deletion.

The closeout formula must resolve the common repository root first, change directory outside the worktree, and then perform the removal:

WT="$(git rev-parse --show-toplevel)"
COMMON="$(git rev-parse --git-common-dir)"
BRANCH="$(git branch --show-current)"
REPO_ROOT="$(cd "$COMMON/.." && pwd -P)"

# 1. Step outside the target worktree
cd "$REPO_ROOT"

# 2. Deregister and prune from git
git worktree remove "$WT"
git worktree prune --verbose

# 3. Safely delete the local branch (safe ancestor check only)
if [ -n "$BRANCH" ] && [ "$BRANCH" != "main" ] && [ "$BRANCH" != "release/v0.1.x" ]; then
  git branch -d "$BRANCH" || true
fi

# 4. Remove leftover physical directory if needed
if [ -e "$WT" ]; then
  if command -v trash >/dev/null 2>&1; then
    trash "$WT"
  fi
fi

8. Platform Automation & Governance Integration¶

Worktree lifecycle governance is executed autonomously via Gas City:

bead-lifecycle-claim: Formula that enforces WIP=1 and asserts agent identity before work begins.
bead-lifecycle-closeout: Mutating formula executing the 9-step DAG retirement sequence before closing the bead.
worktree-lifecycle-on-close: Order listening to bead.closed events that immediately cleans up associated execution surfaces.
worktree-lifecycle-patrol: Hourly order that scans estate surfaces against the 12-state matrix, removing safe surfaces and materializing remediation beads for anomalies.