Done Retirement

Pipeline retirement processor for the Gastown chipset. When a polecat finishes its work, this pipeline validates, commits, pushes, submits an MR, notifies, cleans up, and terminates. In hardware terms, it is the instruction retirement unit — writing results to the register file (shared repository), updating the reorder buffer (merge queue), and freeing execution resources.

Activation Triggers

This skill activates when:

• A polecat has completed execution and is ready to retire its work
• An agent's hook status transitions to

  completed

• A work item's status transitions to

  done

• A convoy needs to track individual bead completion

The 7-Stage Retirement Pipeline

Every retirement flows through seven stages in strict order. The pipeline has an irreversibility boundary at Stage 3 (Push). Before push, the retirement can be aborted and the bead returned to

in_progress

done

Stages:

VALIDATE → COMMIT → PUSH → SUBMIT → NOTIFY → CLEANUP → TERMINATE

Full TypeScript implementations live in

references/retirement-implementation.md

"Done Means Gone" — Irreversibility Rules

The irreversibility contract is the core design principle of this pipeline and MUST remain active at all times:

1. Before push (Stages 1-2): The retirement can be aborted. The bead returns to

   in_progress

   and the polecat continues working. No permanent side effects.
2. At push (Stage 3): The point of no return. The branch reaches the shared repository. The work item status transitions to

   done

   .
3. After push (Stages 4-7): Consequences unfold. The merge request is created, notifications sent, workspace destroyed, agent terminated. Each of these stages can fail individually without compromising the work — the branch is already safe in the remote.

Stages 1-2:  REVERSIBLE    (abort returns to in_progress)
Stage 3:     COMMITMENT    (push to remote, status = done)
Stages 4-7:  CONSEQUENCES  (submit, notify, cleanup, terminate)

If any consequence stage fails (e.g., mail delivery failure in Stage 5), the work is still done. The failure is logged and the mayor can retry the notification manually. The push is the only stage that truly matters for durability.

Cleanup is destructive by design. The polecat's local state — worktree, context files, dispatch records — is deleted. There is no going back to inspect local state after cleanup. If the work needs revision, a new polecat is spawned with a fresh workspace.

Termination is the final lifecycle transition. The polecat goes from

active

terminated

Convoy Progress Tracking

When a bead belongs to a convoy (batch dispatch), its completion updates the convoy's aggregate progress. The mayor monitors convoy progress to determine when all beads in a batch are done. A convoy is complete when all beads reach

done

merged

Communication Protocol

Done retirement is invoked by the polecat itself when work is complete — there is no external trigger message. On the outbound side, it sends durable

mail

handoff

Boundary: What Done Retirement Does NOT Do

Done retirement does not merge code (the refinery does), decide when work is complete (the polecat does), re-assign work (the mayor handles reassignment), preserve local state ("done means gone"), or reverse after push (the irreversibility contract is absolute). It is the exit ramp — and there is no U-turn after the push.

Integration with Other Gastown Skills

Invoked by

polecat-worker

refinery-merge

hook-persistence

mail-async

beads-state

sling-dispatch

References

Implementation detail moved to:

• references/retirement-implementation.md

  — full TypeScript code for all 7 stages, convoy tracking, refinery integration, and error handling.

• references/gastown-origin.md

  — how this pattern derives from Gastown's

  done.go

  completion pipeline.