Skip to content

Gas city factory board

1. Architectural Alignment: Gas City Primitives

The Factory Board maps 1:1 to canonical Gas City primitives:

| Concept | Gas City Primitive | Ground Truth | | :---

Gas City Doctrine Enforcement (v2.0) - Sessions perform work. (Sessions are disposable). - Beads remember work. (Durable universal substrate). - Convoys group work. - Mail coordinates work. - Formulas remember how. (Reusable methods). - Agents execute. - Packs configure. - Rigs scope. - Orders trigger. - Events prove what happened. - Work is not complete until verified and promoted (Capability, Skill, Formula, Pack, Order, Policy). (No parallel "learning lifecycles" or "agent memory" outside this machinery).

| :--- | :--- | | Work Objective / Grouping | CONVOY | Bead of type convoy; membership via non-blocking tracks edges | | Atomic Work Unit | BEAD | Persistent work record in Dolt hq (tasks, features, bugs, epics) | | Execution Surface | RIG | Project registered with city (BluCity/rigs/*) | | Worker Identity | AGENT | Autonomous principal running in a managed session | | Execution Method | FORMULA | Reusable task workflow that materializes as child beads | | Observation | EVENT | Immutable, append-only log of lifecycle transitions | | Delivery State | GITLAB MR / CI | Operational truth for merged code and container artifacts |

2. Convoy Lifecycle & Mechanics

Convoys answer batch questions — "are all five of these tasks done yet?" — without blocking dependencies.

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 --> [*]

Core Commands & Rules

Creation & Grouping: - Ad-hoc sprint / objective: gc convoy create "Objective Name" bead-1 bead-2 ... - Single task dispatch: gc sling <target> <bead> automatically wraps in convoy - Membership via tracks edges (grouping, NOT blocking)

Completion Semantics: - Auto-Close (default): on_close hook fires when all tracked beads close — no polling - Manual / Governed (--owned): For release gates or deployment convoys. Requires explicit: gc convoy land <convoy-id> - Reconciliation: gc convoy check resolves misfired auto-close hooks

Stranded Work Detection: - gc convoy stranded → open beads in convoys with no assignee or routing target - This IS the READY_BEADS>0 AND IDLE_AGENTS>0 = FAILURE detection mechanism

Convoy Metadata:

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

Set at creation: gc convoy create "Deploy v2" --owner mayor --merge mr --target main Update later: gc convoy target <id> <branch>

3. Pull-Based Agent Discovery Protocol

Agents do NOT have work pushed. They query ready beads via the canonical claim protocol:

flowchart LR
    A["Work Created<br/>(bd create / gc sling / formula cook)"] --> B["Routed to Agent<br/>(assignee / gc.routed_to)"]
    B --> C["Session Startup<br/>(gc hook --claim)"]
    C --> D["Atomic Claim<br/>(one ready bead + continuation siblings)"]
    D --> E["Agent Executes"]
    E --> F["bd close → convoy auto-closes"]

Readiness rules: - Blocked beads (is_blocked = true) are invisible to bd ready - Pool query: bd ready --metadata-field gc.routed_to=drupal/worker --unassigned --limit=1 - When a blocker closes, downstream bead becomes ready automatically via EVENT

WIP Constraints: - Per-convoy: convoy ready beads > 0 AND idle agents > 0 ⇒ dispatch - Per-agent: max_active_sessions in Gas City config (mechanical, not prose) - No agent claims multiple beads concurrently unless explicitly linked as continuation siblings

4. Factory Board Visual Model

[ Overview ]  [ Convoys ]  [ Beads ]  [ Agents ]  [ Rigs ]  [ Formulas ]  [ Orders ]  [ Events ]  [ GitLab ]  [ Releases ]

Executive Metric Strip

┌─────────────────┬─────────────┬─────────────┬──────────────┬───────────────┬────────────┐
│ ACTIVE CONVOYS  │ READY BEADS │ ACTIVE BEAD │ BLOCKED BEAD │ ACTIVE AGENTS │  OPEN MRS  │
│        6        │     17      │      6      │      4       │       8       │     6      │
└─────────────────┴─────────────┴─────────────┴──────────────┴───────────────┴────────────┘

[!IMPORTANT] READY BEADS > 0 with ACTIVE AGENTS having capacity = dispatch failure. This is the primary factory health signal.

Active Convoys Table

Convoy ID Title / Objective Owner Target Progress Ready Active Blocked Stranded Assigned Agents Delivery
hq-cv-243 Drupal Recipe Factory BLU release/v0.1.x 6/11 3 1 1 0 agent-drupal !243 ✅
hq-cv-221 Agent Identity Chain BLU release/v0.1.x 4/7 1 1 1 0 agent-drupal, agent-contract !221 🔄
hq-cv-104 City Authority Recovery MAYOR main 8/12 2 1 1 0 agent-mayor —
hq-cv-247 Release v0.1.x Convergence REFINERY main 14/18 2 1 1 0 agent-refinery !126, !247
hq-cv-099 OpenClaw Runtime Adapter RUNTIME develop 9/10 0 1 0 0 agent-openclaw !10 ✅

Data sources: - Convoy list: gc convoy list --json - Progress: gc convoy status <id> --json - Stranded: gc convoy stranded --json - Delivery: glab mr list --json cross-referenced with bead metadata branch

Convoy Drilldown (Bead Graph)

Clicking a convoy row expands to the full bead graph with dependency edges:

CONVOY: hq-cv-221 (Agent Identity Chain)
OWNER: BLU │ TARGET: release/v0.1.x │ MERGE: mr │ NOTIFY: @channel-factory
PROGRESS: 4 / 7 closed ████████░░░░░ 57%

┌────────────────────────────────────────────────────────────────────────┐
│ ✅ CLOSED (4)                                                          │
│ ✓ bl-711: Define OSSA identity specification                           │
│ ✓ bl-712: Register DUADP identity token provider                       │
│ ✓ bl-715: Provision GitLab machine principal (@bluefly)                │
│ ✓ bl-719: Verify DRUPAL commit provenance signing                      │
├────────────────────────────────────────────────────────────────────────┤
│ 🔵 ACTIVE (1)                                                          │
│ ● bl-722: ContractPlane authorization gate integration                 │
│   Assignee: agent-contract · Rig: contractplane-ai · MR: !221          │
├────────────────────────────────────────────────────────────────────────┤
│ 🔴 BLOCKED (1)                                                         │
│ ! bl-725: ContextControl production provenance audit                   │
│   Blocked by: bl-1402 (root: hq-cv-104 City Authority Recovery)        │
├────────────────────────────────────────────────────────────────────────┤
│ ⚪ READY (1)                                                            │
│ ○ bl-728: Propagate verified machine identity to secondary roles       │
│   Eligible: unassigned · Pool: drupal/worker                           │
└────────────────────────────────────────────────────────────────────────┘

Global Work Feeds

Ready Across All Convoys (Pull Queue)

[!TIP] This is the view an idle agent's gc hook --claim queries. If this table has rows and agents are idle, the factory has a dispatch failure.

Bead ID Convoy Rig Routed To Priority Title
bl-1234 hq-cv-243 recipe_amcs drupal/worker P1 Hook recipe validation runner
bl-728 hq-cv-221 duadp drupal/worker P2 Propagate verified machine identity
bl-1402 hq-cv-104 blucity mayor/worker P0 Reconcile Dolt manifest sync locks

Data source: bd ready --flat --json across all scopes

Blocked Work Analysis

Bead ID Convoy Direct Blocker Root Cause Remediation Owner
bl-725 hq-cv-221 bl-1402 City authority Dolt lock prevents schema write MAYOR
bl-1109 hq-cv-243 bl-1234 Recipe test fixtures depend on validator runner BLU

Data source: bd list --status open --blocked --json + dependency graph traversal

Stranded Work Warning

⚠ gc convoy stranded
CONVOY      ISSUE     TITLE
hq-cv-247   bl-1501   Update release notes template

[!WARNING] Stranded work = open bead inside a convoy with no assignee AND no gc.routed_to. It will never be claimed. Route it: gc sling <target> bl-1501

5. Agent Status Panel

Agent Provider Rig Session Status Current Bead Convoy WIP
gascity.mayor claude — (city) gc-mayor-1 active bl-1402 hq-cv-104 1/1
backend/gascity.polecat codex blucity gc-pol-3 active bl-722 hq-cv-221 1/3
backend/gascity.polecat codex blucity gc-pol-4 idle — — 0/3
gascity.refinery claude — (city) gc-ref-1 active bl-247 hq-cv-247 1/1
gascity.witness claude blucity-docs gc-wit-1 idle — — 0/1

Data source: gc session list --json + gc status --json

[!IMPORTANT] max_active_sessions is the native Gas City WIP limit. This replaces prose instructions about "don't over-parallelize."

6. BLU Operating Contract for Convoys

Portfolio Governance

  1. BLU monitors convoy distribution, detects stalled objectives, ensures WIP limits are respected
  2. BLU creates and manipulates convoys strictly through gc convoy create, gc convoy add, gc sling
  3. BLU does NOT invent synthetic groupings outside Gas City primitives

Dispatch Rules

  1. When dependencies clear, the resulting EVENT automatically makes child beads ready
  2. Autonomous agents claim via gc hook --claim — pull model, not push
  3. gc convoy stranded is the canary — if it returns rows, route them immediately

Completion Verification

  1. Convoy auto-closes when all tracked beads close (unless --owned)
  2. BLU verifies convoy completion means effect is proven, not just bead status
  3. For --owned convoys (release gates): BLU or designated owner must explicitly land

Cross-Convoy Dependencies

  1. A bead in convoy A can be blocked_by a bead in convoy B
  2. The blocked bead remains invisible to bd ready until the blocker closes
  3. The board shows cross-convoy blockers in the Blocked Work Analysis feed
  4. BLU routes the blocker resolution, not the blocked bead

7. Data Collection Contract

Every board view is populated from Gas City JSON output — no scraped prose, no cached state files:

Board Section Data Source Command
Executive Metrics City status gc status --json
Active Convoys Convoy list gc convoy list --json (when available) or bd list --type convoy --status open --json
Convoy Progress Convoy status gc convoy status <id> --json
Ready Queue Ready beads bd ready --flat --json
Blocked Analysis Blocked beads bd list --status open --blocked --json
Stranded Warning Stranded beads gc convoy stranded --json
Agent Status Session list gc session list --json
GitLab Delivery MR state glab mr list --json
Events Feed Event stream gc events --json --follow

[!NOTE] gc --json is the automation contract. Use gc --json-schema=result to discover the exact schema for each command. Validate at command boundaries, not inline.

8. Implementation Notes

What This Replaces

Old New
"Execution Lanes" (invented) Convoys (native Gas City primitive)
Manual dispatch lists gc convoy stranded + bd ready
Prose WIP limits max_active_sessions in agent config
Push-based task assignment Pull via gc hook --claim
Status polling EVENT-driven readiness

What This Does NOT Implement

  • No new Bluefly abstractions
  • No dashboard service (board is a data model, not a running process)
  • No replacement for Beads/Gas City (this IS Beads/Gas City)
  • No convoy creation until authority recovery (Phase 6) completes

Prerequisites

  1. Oracle City authority recovery must complete (single authoritative Dolt)
  2. Gas City gc must be operational on the target host
  3. gc convoy commands must be available (verify gc --version)
  4. Board data scripts use gc --json which requires sufficiently recent gc