Branches, integration and Stable releases
Follow Git refs from an isolated task worktree through delivery, integration and promotion to a versioned Stable release.
The platform owns worktrees, commits, delivery refs, integration, promotion and cleanup. Coding agents edit files; the platform performs Git mutations.
1. The platform owns Git mutations
A coding agent does not branch, stage, commit, push or merge. The platform captures its file changes and manages the task and protected branches.
task/<key>developmain2. Every coding run is isolated
Managed coding runs use isolated Git worktrees, including single-slot execution, resume and reissue. Reducing parallelism to one does not move coding work into the shared checkout.
- The task/<key> branch keeps task work separate from the integration branch.
- The platform preserves and publishes the task result before integration.
- Normal cleanup requires the task branch to be contained in the integration target.
3. Remote delivery carries an identity
Delivery refs identify the attempt, fencing generation and commit. A fencing token is an increasing lease generation; a stale runner cannot publish an accepted result over a newer attempt.
- Result refs preserve the delivered commit; salvage refs preserve recoverable work before teardown.
- Quarantine refs keep rejected delivery evidence separate from the integration branch.
runner/<host>/<key>agent-studio/results/<attempt>/fence-<n>/<sha>agent-studio/salvage/...agent-studio/quarantine/...4. Integrate after automatic gates, before human review
After successful delivery and automatic gates, the platform integrates into the configured target, typically develop. It checks delivery proof, fencing, history and conflicts. Integrated means the effective delivered commits are reachable from that branch.
Human review follows against the integrated revision. Integration does not mean acceptance, release or Stable status; those are separate recorded decisions.
5. Promote the reviewed release candidate
A release/<utc> marker pins the develop candidate. The promotion gate recalculates the range, verifies the manifest and required checks, then advances main to that exact candidate with a non-force atomic push.
The candidate can include integrated tasks still awaiting acceptance. Inspect the manifest’s open reviews and escalations before promotion.
6. Freeze a qualified version
A Stable deployment starts from an immutable v<semver> tag on a qualified main commit. Its build manifest records source SHA, version, checks, artifacts and release evidence. A repair receives a new version and tag.
7. Check reachability before cleanup
Normal finalization removes a task worktree and branch only after containment in the integration target. A stale-ref sweep presents a deletion plan for operator confirmation. It retains live, checked-out and protected refs, and any ref whose ownership or recovery state is unclear.
Ref flow
From task card to Stable
Platform-owned refs preserve delivery, integration and release evidence.- 01 · Scope Task card declared outcome
- 02 · Isolate Isolated worktree
task/<key>remove after integration - 03 · Deliver Runner refs
runner · results · salvage · quarantinesweep by policy - 04 · Integrate
developmerge gate - 05 · Promote
mainrelease/<utc>protected marker - 06 · Freeze Immutable release
v<semver> + manifest
| Class | Created by | Deleted when |
|---|---|---|
task/<key> | Task preparation | It is contained in the integration branch and no active worktree needs it. |
runner/<host>/<key> | Remote runner | It is merged into both develop and main and is at least 7 days old. |
agent-studio/results/<attempt>/fence-<n>/<sha> | Run finalization | The proof commit is on main; the audit records its ref, SHA, proof branch and task key. |
agent-studio/salvage/… | Pre-teardown recovery | The task is terminal and the commit is on main, or the ref is at least 14 days old. |
agent-studio/quarantine/… | Integration gate | It is at least 30 days old and no open escalation references it. |
release/<utc> | Promotion workflow | Never through the stale-branch sweep; release refs are protected. |
v<semver> | Stable release workflow | Never; Stable tags are immutable. |
8. Review through the task record
This workflow coordinates delivery through the task and its recorded scope, commit, checks, findings and human decision. Integration and promotion gates use those records without requiring a separate pull request.