done-retirement

Done Retirement

Pipeline retirement processor for the Gastown chipset. When a polecat finishes its work, the done retirement pipeline takes over -- it validates the work, commits and pushes the branch, creates a merge request, notifies the convoy and mayor, cleans up the workspace, and terminates the agent. In hardware terms, done retirement is the instruction retirement unit -- it takes completed instructions from the execution unit (polecat), writes results to the register file (shared repository), updates the reorder buffer (merge queue), and frees execution resources (workspace and agent slot).

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

Core Capabilities

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. After push, the process is irreversible -- the branch is in the shared repository and the workspace will be destroyed.

VALIDATE      COMMIT        PUSH          SUBMIT        NOTIFY        CLEANUP      TERMINATE
   |             |            |              |             |             |             |
   v             v            v              v             v             v             v
verify work   ensure all   push branch   create merge  send mail to  remove work   mark agent
is actually   changes are  to shared     request       convoy/mayor  directory     as idle or
complete      committed    repository    record in     and witness   and context   terminated,
(criteria     to working   (IRREVERSIBLE state                                    release
met)          branch       AFTER THIS)                                            resources

Stage 1 -- Validate:

Verify that the work is actually complete. The bead's acceptance criteria must be met before the retirement pipeline begins. Validation checks the work item's done criteria against the actual state of the working branch.

const state = new StateManager({ stateDir: '.chipset/state/' });

async function validateCompletion(
  agentId: string,
  beadId: string
): Promise<ValidationResult> {
  const workItem = await state.getWorkItem(beadId);
  const hook = await state.getHook(agentId);

  // Work item must exist and be in progress
  if (!workItem || workItem.status !== 'in_progress') {
    return { valid: false, reason: `Work item ${beadId} is not in_progress` };
  }

  // Hook must be active for this agent
  if (!hook || hook.status !== 'active') {
    return { valid: false, reason: `No active hook for agent ${agentId}` };
  }

  // Check that the agent is the assigned worker
  if (workItem.assignee !== agentId) {
    return { valid: false, reason: `Agent ${agentId} is not assigned to ${beadId}` };
  }

  return { valid: true };
}

Validation failures are non-destructive. The bead stays in_progress and the polecat continues working. The polecat should not call done until its acceptance criteria are met.

Stage 2 -- Commit:

Ensure all changes are committed to the working branch. If there are uncommitted changes, commit them with a summary message. If the working tree is clean, this stage is a no-op.

async function ensureCommitted(
  context: WorkspaceContext
): Promise<void> {
  // Check for uncommitted changes
  // git status --porcelain
  // If output is non-empty, commit with a summary message

  // Verify the branch has at least one commit
  // git log --oneline -1 polecat/{beadId}
  // If no commits, validation should have caught this (Stage 1)
}

The commit stage ensures no work is lost. Even partial work gets committed before the branch is pushed. The commit message follows the project's conventional commit format.

Stage 3 -- Push:

Push the working branch to the shared repository. This is the point of no return.

async function pushBranch(context: WorkspaceContext): Promise<void> {
  // Push the polecat's branch to remote
  // git push origin polecat/{beadId}

  // Update work item status to 'done'
  await state.updateWorkStatus(context.beadId, 'done');
}

IRREVERSIBILITY BOUNDARY: After the push completes, the retirement process cannot be undone. The branch exists in the shared repository and serves as the durable artifact of the polecat's work. All subsequent stages (submit, notify, cleanup, terminate) are consequences of this push. Even if they fail, the work is preserved in the remote branch.

The push uses the write-then-rename pattern for the state update: the work item status file is written to a temporary location, fsynced, and renamed atomically. A crash during push leaves either the old status (in_progress) or the new status (done), never a partial state.

Stage 4 -- Submit:

Create a merge request record in the state for the refinery to process. The merge request links the polecat's branch to the target branch and queues it for sequential merge processing.

async function submitMergeRequest(
  context: WorkspaceContext
): Promise<MergeRequest> {
  const mr: MergeRequest = {
    id: `mr-${context.beadId}`,
    sourceBranch: `polecat/${context.beadId}`,
    targetBranch: 'main',
    status: 'pending',
    beadId: context.beadId,
  };

  // Write MR record atomically
  const mrPath = join(stateDir, 'merge-queue', `${mr.id}.json`);
  await atomicWrite(mrPath, serializeSorted(mr));

  return mr;
}

The merge request is a state record, not a Git platform PR. The refinery reads these records from the state/merge-queue/ directory and processes them in FIFO order. The refinery skill handles the actual rebase-test-merge pipeline.

Stage 5 -- Notify:

Send completion notifications to the convoy, mayor, and witness. These messages provide the audit trail for the work item's completion.

async function notifyCompletion(
  context: WorkspaceContext,
  mr: MergeRequest,
  convoyId?: string
): Promise<void> {
  // Notify mayor of completion
  const mayorMail: AgentMessage = {
    from: context.agentId,
    to: 'mayor',
    channel: 'mail',
    payload: `DONE: ${context.beadId} - branch ${mr.sourceBranch} pushed, MR ${mr.id} submitted`,
    timestamp: new Date().toISOString(),
    durable: true,
  };
  await sendMail(mayorMail);

  // Notify witness for monitoring records
  const witnessMail: AgentMessage = {
    from: context.agentId,
    to: 'witness',
    channel: 'mail',
    payload: `RETIRED: ${context.beadId} - agent ${context.agentId} completing retirement`,
    timestamp: new Date().toISOString(),
    durable: true,
  };
  await sendMail(witnessMail);

  // Update convoy progress if part of a batch
  if (convoyId) {
    await state.updateConvoyProgress(convoyId);
  }
}

Notifications use the mail-async durable messaging channel. Messages persist on disk and survive agent termination -- the mayor and witness can read them even after the polecat is gone.

Stage 6 -- Cleanup:

Remove the working directory and execution context. After cleanup, the polecat's local workspace no longer exists. The branch in the shared repository is the only artifact.

async function cleanupWorkspace(
  context: WorkspaceContext
): Promise<void> {
  // Clear the agent's hook (work is done)
  await state.clearHook(context.agentId);

  // Remove the dispatch record (dispatch lifecycle complete)
  const dispatchPath = join(stateDir, 'dispatch', `${context.beadId}.json`);
  await removeFile(dispatchPath);

  // Remove worktree or working directory
  // git worktree remove polecat/{beadId} --force
  // (or equivalent workspace teardown)
}

Cleanup is destructive by design. The polecat's local state -- worktree, context files, di