Gas City Convoys Catalog¶

Purpose: Define the canonical Convoy primitive in Bluefly orchestration, lifecycle mechanics, tracking edges, auto-close semantics, and stranded work detection within the Gas City 1.4.x runtime.

Upstream Authority: How Gas City Works, Tutorial 06 — Beads & Convoys, Coming from Gas City.

1. Architectural Definition¶

A Convoy is a bead of type convoy. It is the native Gas City primitive that answers batch questions ("are all five of these tasks done yet?") without introducing artificial dependency locks:

CONVOY = Grouped work objective / execution lineage
BEAD   = Atomic work unit tracked via non-blocking `tracks` edges

Convoys replace all synthetic abstractions (e.g. "lanes", "swimlanes", "buckets"). Convoys are bead-backed, stored directly in the canonical Dolt ledger (hq), and visible through both bd list --type convoy and gc convoy commands.

stateDiagram-v2
    [*] --> Open: gc convoy create / gc sling
    Open --> Tracking: gc convoy add <convoy> <bead>
    Tracking --> AutoClosed: on_close hook (all member beads closed)
    Tracking --> Landed: gc convoy land (--owned flag skips auto-close)
    AutoClosed --> [*]
    Landed --> [*]

2. Convoy Mechanics & Lifecycle¶

Membership via `tracks` Edges¶

Membership in a convoy is established via non-blocking tracks edges.
In bd show <bead>, membership displays as: ← ○ convoy-id [P2] (tracks).
Tracking is pure grouping: it changes no parent and blocks no execution.

Provisioning & Dispatch¶

Ad-hoc Grouping: gc convoy create "Objective Name" bead-1 bead-2 ...
Single Task Dispatch: gc sling <target> <bead> automatically wraps the bead in an input convoy.
Dynamic Addition: gc convoy add <convoy-id> <bead-id>

Completion Semantics¶

Default (Auto-Close):
When all member beads are closed, the background on_close hook automatically closes the convoy bead.
Requires zero operator or agent polling loops.
Governed / Manual (--owned):
For release gates, deployment milestones, or human review boundaries created with --owned.
Bypasses auto-close and requires explicit closure:
```
gc convoy land <convoy-id>
```
Reconciliation:
If an auto-close hook misfires or store connectivity is interrupted during closure:
```
gc convoy check
```

Stranded Work Detection¶

gc convoy stranded detects open beads inside convoys that lack an assignee or routing target (gc.routed_to).
This command is the mechanical Canary for the factory health rule:
```
READY_BEADS > 0 AND IDLE_AGENTS > 0 = DISPATCH_FAILURE
```

3. Convoy Metadata Schema¶

Every convoy bead carries structured metadata governing its execution and release path:

Field	Purpose	Example
`convoy.owner`	Managing coordinator agent	`BLU`, `MAYOR`, `REFINERY`
`convoy.notify`	Recipient notified upon completion	`@channel-factory`, agent mail
`convoy.merge`	Merge protocol for PRs	`direct`, `mr`, `local`
`target`	Target branch inherited by member beads	`release/v0.1.x`, `main`

Set at creation:

gc convoy create "Release v0.1.x Convergence" --owner refinery --merge mr --target release/v0.1.x

Update during execution:

gc convoy target <convoy-id> <branch>

4. Operational Commands (CLI Reference)¶

Command	Action	Output / Behavior
`gc convoy create "<title>" <beads...>`	Creates a convoy tracking specified beads	Emits new convoy bead ID
`gc convoy list`	Lists all active convoys	Table of open convoys with progress
`gc convoy status <id>`	Detailed progress of a specific convoy	Closed / Active / Blocked / Ready breakdown
`gc convoy add <id> <bead>`	Appends a bead to an existing convoy	Adds `tracks` edge
`gc convoy check`	Evaluates member states and auto-closes	Closes eligible convoys
`gc convoy stranded`	Reports unassigned/unrouted open beads	Canary check for factory dispatch
`gc convoy land <id>`	Lands/closes an `--owned` convoy	Explicit gate closure

5. Factory Board Integration¶

The Factory Board (Engineering-Standard/operating-model/gas-city-factory-board.md) is a pure derived projection of active Convoys. It polls no synthetic state files; it reads directly from:

gc convoy list --json
gc convoy status <id> --json
bd ready --flat --json
gc events --json

Refer to the Factory Board Operating Model for visual drilldown, pull queue specifications, and BLU portfolio coordination contracts.