STD-COMM-001: Fleet Communication & Coordination Law¶

Status: Canonical & Binding
Standard ID: STD-COMM-001
Owner: Blu (kingstown-core.blu) — Director
Scope: All autonomous agents, human operators, and rigs across the Bluefly estate.

1. Prime Directive & Plane Separation¶

Beads are durable state. gc mail is agent communication. Gas City Events are observation proof. ContextControl is governed human projection.

BEADS != EVENTS
EVENTS != COMMANDS
MAIL != WORK AUTHORITY
CONTEXTCONTROL != ORCHESTRATOR
RAW BD = scope-local authority
GC = Factory-wide operational view
MAIL_SENT != WORK_ACCEPTED

2. The Four Communication Planes¶

(See detailed specification in STD-ARCH-002)

Plane	Authority	Purpose
Work Plane	Beads (`bd`)	What work exists, ownership, dependencies, readiness, status
Execution Plane	Agents + Formulas + Sessions	Perform bounded execution (Formula V2 materializes work steps)
Observation Plane	Gas City Events	Immutable, typed, cursor-based state transition proof (SSE streams)
Human / Control Plane	ContextControl (Drupal)	Who can request, approve, inspect, govern, and understand work

Medium	Role	Durability
Beads (`bd`)	Work authority, state, findings, blockers, evidence	Durable — survives session
`gc mail`	Inter-agent notifications, context sharing	Durable — stored in Bead substrate
`gc sling`	Governed ownership transfer between lanes	Durable — recorded on Bead
Gas City Events	Immutable, append-only activity proof	Durable — replay from sequence number
GitLab	Source commits, MR state, CI pipeline evidence	Durable — canonical source truth
Chat window / tmux pane	Human interaction surface only	Disposable — destroyed with session
tmux `send-keys` broadcast	Bootstrap / session recovery only	Ephemeral — not a communications bus
Local artifacts / scratch files	Ephemeral working notes	Ephemeral — not authoritative

Prohibited coordination patterns: - Assuming another agent has read your chat window. - Using transcript.jsonl or session memory as handoff state. - Writing cross-lane status into scratch files and expecting other lanes to read them. - Routing work through the human when gc mail or gc sling are available. - Using tmux send-keys as a routine inter-agent communication path. - Assuming MAIL_SENT equals WORK_ACCEPTED. Work handoffs require Bead dependency + sling/route.

2a. Bootstrap Exception — tmux `send-keys`¶

TMUX_BROADCAST = BOOTSTRAP_ONLY
TMUX_BROADCAST ≠ DURABLE_COMMUNICATION

Direct tmux window injection (tmux send-keys) MAY be used only to: 1. Bootstrap a new fleet-wide law or directive into live sessions before gc mail reaches all lanes. 2. Recover an unreachable agent session that cannot yet receive gc mail.

It MUST NOT be used as normal agent-to-agent communication.

Any instruction delivered through tmux MUST subsequently be represented in canonical Beads, gc mail, or an Engineering Standard. A tmux paste that is not followed by durable representation is an incomplete delivery.

3. Mandatory Startup Protocol¶

Every agent that begins or resumes a session MUST execute the following before claiming any work:

gc mail inbox                           # Read pending mail
gc bd list --status in_progress         # See what your lane already owns
gc bd list --status blocked             # Identify blockers requiring action
gc bd list --status open --limit 10     # Identify available work

If gc mail inbox fails due to the version-skew defect (bl-hevf49), fall back to:

gc bd list --type=wisp --limit 20       # List recent mail beads directly
bd show <message-id>                    # Read individual mail items

4. Required State Transitions¶

Every agent MUST send gc mail to kingstown-core.blu at the following transitions:

Transition	Subject Pattern	Body Must Include
START	`[START] <bead-id> <bead-title>`	Lane identity, bead claimed, dependencies checked
BLOCKED	`[BLOCKED] <bead-id> <blocker>`	Bead ID, exact blocker, owner of blocker, handoff route
HANDOFF	`[HANDOFF] <bead-id> → <target>`	Source bead, target lane, evidence, what remains
READY_FOR_ACCEPTANCE	`[ACCEPT] <bead-id>`	MR URL, pipeline URL, evidence, verification performed
CLOSED	`[CLOSED] <bead-id>`	Final evidence, what was shipped, dependent beads unblocked

Every material state change must also be recorded on the Bead itself (via bd update) before the mail is sent.

5. Cross-Lane Routing¶

When work belongs to another lane, route it durably — do not implement it:

gc sling <target-lane> <bead-id>          # Transfer bead ownership
gc mail send kingstown-core.blu \         # Notify Blu of the transfer
  -s "[HANDOFF] <bead-id> → <target>" \
  -m "<evidence and rationale>"

Do not: - Fix another lane's implementation silently. - Ask the human to route it. - Block your own lane waiting for another lane to notice.

After routing, continue with the highest-priority ready work inside your own lane.

6. `gc mail` Operational Contract¶

Sending¶

# Default sender resolves to human — this works:
gc mail send <target> -s "<subject>" -m "<body>"

# --from with agent identity fails unless a valid Gas City session exists:
# DO NOT USE: gc mail send ... --from antigravity   # "invalid sender: session not found"

Known Defect (`bl-hevf49`)¶

gc mail read <id> fails with JSON/revision decoding error due to gc 1.4.1 / bd 1.3.0 schema mismatch.

Workaround:

gc bd show <message-id>   # Read mail body via Bead show
bd show <message-id>      # Alternative path

Ownership routing: Blu owns routing and acceptance for bl-hevf49. Implementation is split by component:

Component	Owner lane
gc / bd version compatibility	BluCityPacks (Gas City behavior)
Oracle binary / package version deployment	Oracle IaC Convergence
Sender identity / provenance contract	Agent ID
Expected communication behavior definition	Durable Work Gov
Routing, acceptance, and closeout	Blu (Director)

Blu coordinates — Blu does not implement. A defect that affects fleet coordination does not make Blu the implementation owner.

`gc mail send --all`¶

The --all flag triggers a bd query "ephemeral=true AND label=gc:session" scan which takes 40+ seconds under Dolt contention (current Oracle load: ~21 avg). Use --all only when necessary; prefer targeted sends to specific session names.

Failure Handling¶

If gc mail send fails: 1. Retry once with a 30-second wait. 2. If still failing, record on the Bead: GC_MAIL_DELIVERY=FAILED reason=<error>. 3. If the bead is critical, notify Blu via an alternate available path (nudge, direct bd update). 4. Do NOT route through the human.

7. Blu Dashboard Protocol¶

Blu operates as the fleet director using the following dashboard (not by waiting for agents to report in chat windows):

gc mail inbox                              # Pending inter-lane mail
gc bd list --status in_progress            # All lanes' active work
gc bd list --status blocked                # All lanes' blockers
gc bd list --status open --priority p0     # P0 queue
gc events --follow                         # Live activity stream

Blu MUST NOT: - Wait for agents to "check in" through chat. - Ask the human to relay state between lanes. - Use gc session nudge as the primary status mechanism.

8. Runtime State Invariant¶

Engineering Standards MUST NOT embed transient operational state.

Do not record in a standard: - Current active Bead IDs or their status - Current disk utilization or storage runway figures - Named gates that reference specific open incidents - Version numbers of running binaries

Current fleet posture is resolved from canonical Beads and runtime evidence, not from this document.

# Resolve active constraints — run this, do not read a standard for it:
gc bd list --status open --priority p0          # Active P0 work
gc bd list --status blocked                     # Active blockers / gates
gc bd list --label gate --status open           # Named gates
gcstatus                                        # Oracle runtime posture

Historical example (not current state): bl-xgrcpf (Oracle storage runway) was a P0 gate that blocked Keycloak/SSO work. It was resolved when Oracle root was expanded (~193 GB filesystem, ~50% used) and IaC MR !247 was merged. It is recorded here only to illustrate how gates are resolved — not to assert current status.

Any enforcement constraint that should actually block execution must be represented as an open, unresolved Bead in the canonical Bead store, not as a line in a document.

9. Evidence Requirements¶

All mail messages sent for BLOCKED, HANDOFF, and CLOSED transitions must include:

BEAD=
TRANSITION=
EVIDENCE=        (link, commit, pipeline, test output — not assertion)
BLOCKER_OWNER=   (if BLOCKED)
MR=              (if ACCEPT or CLOSED)
PIPELINE=        (if ACCEPT or CLOSED)
NEXT_WORK=

Narrative assertions from the agent are not sufficient evidence. Proof requires: test output, CI pipeline status, GitLab MR state, Gas City Events, or Bead state.

10. Violations¶

A communication law violation is: - Recording work state only in a chat window. - Failing to send gc mail at a required transition. - Routing cross-lane work through the human. - Using local scratch files as handoff state to another agent. - Sending a CLOSED transition without MR_MERGED and RUNTIME_VERIFIED evidence. - Dumping raw findings, investigation transcripts, or command output to the operator instead of routing to Beads or BluCity-Docs.

On detection: Record the violation in the Bead. Route the correction once. Continue authorized work. Do not audit the audit.

9. Information Routing — Write Before You Talk¶

Thomas is not the factory's memory, message bus, notebook, or log collector.

Every finding must be routed to its durable home before it is communicated to the operator.

9.1 Routing Table¶

Finding type	Durable home	Then report?
Active work state, blockers, decisions	Bead	Exception/milestone only
Reusable knowledge (architecture, standard, procedure, pattern)	BluCity-Docs	DOCS field in completion
Agent-to-agent coordination	Gas City Mail	No — use the bus
Raw command output / evidence	Bead comment or Evidence file	Summarize only
Human decision required	Escalate with minimal context	Yes — one escalation

9.2 Information Lifecycle¶

DISCOVERY
  ↓
BEAD COMMENT / EVIDENCE
  ↓
VERIFICATION
  ↓
ACCEPTED KNOWLEDGE
  ↓
BLUCITY-DOCS (curated canonical layer)

Not:

DISCOVERY → 500 lines sent to Thomas → forgotten

A finding is not organizational knowledge because an agent generated it. Verify it first.

9.3 Beads vs BluCity-Docs Boundary¶

Beads = high-volume operational memory. Every material event, finding, decision, and evidence reference goes here.
BluCity-Docs = curated canonical knowledge. Promote from Beads only when a finding becomes:
an architectural rule · an accepted engineering standard · a reusable operating procedure · a proven troubleshooting procedure · a stable infrastructure fact · a repeatable deployment pattern · a security rule · a naming convention · an ownership boundary · a system-of-record decision

Do not flood BluCity-Docs with session logs. That moves the dump from chat into Markdown.

9.4 Search Before Research¶

Before starting any investigation: 1. Search relevant Beads. 2. Search BluCity-Docs. 3. Inspect current source/runtime. 4. Only then perform new research.

If the answer exists in Beads or BluCity-Docs, retrieve it. Do not make the operator re-explain prior decisions.

9.5 Operator Response Budget¶

Normal completion messages to Thomas: ≤ 10 lines.

Required format:

STATUS: DONE | BLOCKED | NEEDS_OPERATOR

BEAD: <id>

RESULT:
<1–3 sentence summary>

CHANGED:
<very short list of material changes>

EVIDENCE:
<where evidence is recorded>

DOCS:
<canonical documents updated, or NONE>

NEXT:
<next action, or NONE>

Permitted exceptions (still bounded): - Explicit operator request for detail. - Escalation of a genuine human-only decision (threshold, legal, destructive authorization, unavailable credential). - Milestone completion summary (still ≤ 20 lines).

Prohibited regardless of context: - Investigation diaries. - Giant tables. - Command transcripts. - File inventories. - Speculative architecture essays. - Repeated context from prior turns.

9.6 WITNESS Rejects Information-Routing Failures¶

WITNESS must refuse acceptance (CERTIFICATION=FAIL) when: - Important decisions exist only in chat, not in the Bead. - Evidence was sent to the operator rather than recorded durably. - A Bead was not updated with material findings. - Reusable knowledge was discovered but canonical documentation was not updated. - A duplicate document was created instead of updating authority. - An agent asked Thomas for information already available in Beads, BluCity-Docs, source, runtime, or Gas City Mail. - Completion cannot be reconstructed from the durable record alone.

9.7 Agent Handoff Completeness¶

A handoff is incomplete unless the receiving agent can proceed without asking Thomas. Required:

BEAD ID
CURRENT STATE
ACCEPTANCE CRITERIA
BLOCKERS
RELEVANT CANONICAL DOCS
EVIDENCE LOCATION
NEXT EXECUTABLE ACTION

Use Gas City Mail for the handoff. The Bead must contain the full record.

Appendix: Quick Reference¶

# Read mail
gc mail inbox
gc bd show <message-id>          # If gc mail read is broken (bl-hevf49)

# Send mail
gc mail send kingstown-core.blu -s "[START] bl-xxxxx My Bead" -m "body"
gc mail send <target-session> -s "subject" -m "body"

# Update bead
bd update <bead-id> --notes "Material finding, decision, or state change"
bd update <bead-id> --status blocked

# Route cross-lane
gc sling <target> <bead-id>

# Nudge (emergency only, not primary coordination)
gc session nudge <session-name> "message"

# Fleet dashboard (Blu only)
gc bd list --status in_progress
gc bd list --status blocked
gc events --follow