# COMMS-PROTOCOL.md — Fleet Communication Standard

*Updated 2026-03-10 after Task 1 routing/reporting failure.*

---

## Purpose
The fleet must stop mixing delivery paths. A message is not "sent" just because one channel accepted it. It only counts when it reaches the **right channel for that job**, is **acknowledged**, and changes the next action.

This protocol defines the canonical channel for each job.

---

## Canonical Channel Rules

### 1. Action / Urgent Coordination = **Live Gateway Session**
Use:
- `scripts/agent-bridge.js <agent> wake "message"`
- `scripts/builder-bridge.js send <sessionKey> "TASK"`

Use this for:
- live task assignment
- urgent follow-up
- real-time coordination
- anything where delay or backlog is unacceptable

**This is the primary control path.**

### 2. Proof / Structured Handoff = **JSONL Inbox**
Use:
```bash
node /home/ccuser/shared/scripts/inbox.js send --from <agent> --to <agent> --subject "..." --body "..."
```

Use this for:
- completion proof
- structured summaries
- blockers / dependencies
- decision handoffs
- anything that needs durable acknowledgment tracking

**This is the source of truth for proof, not for urgency.**

### 3. Long-Form Artifact / History = **Markdown Inbox or File**
Use:
- `/home/ccuser/the-50-dollar-app/RIVET-INBOX.md`
- `BUILDER-INBOX.md`
- report/spec files

Use this for:
- changelogs
- long reports
- specs
- history / archive

**Markdown files are artifacts, not primary action routing.**

### 4. Status = **fleet-state / status.json**
Use status files and fleet-state for:
- current declared state
- heartbeat freshness
- degraded reason

**Status is not proof of task delivery.**

---

## Builder ↔ Rivet Rules

### Builder task assignment
- **Primary:** `builder-bridge.js send` into Builder's live session
- **Secondary proof:** JSONL inbox message summarizing the task if needed
- **Artifact/history:** `RIVET-INBOX.md`

### Builder completion reporting
Builder must report in this order:
1. **JSONL inbox** → short proof summary
2. **RIVET-INBOX.md** → detailed artifact/changelog if needed
3. **status.json / fleet-state** → reflected current state

If Builder updates markdown/status without JSONL proof, completion is **not considered cleanly delivered**.

### Rivet response rule
If Builder sends:
- **bridge action** → Rivet must expect immediate execution movement
- **JSONL proof** → Rivet must ACK it
- **markdown artifact only** → Rivet must not treat that alone as delivery proof

---

## Fleet-Wide Rules

### Rule 1 — One message, one job, one channel
Do not send the same task through 3 ambiguous paths unless one is explicitly marked backup.

### Rule 2 — Tail is not triage
Reading the tail of a large unread inbox is not valid triage. Agents must:
- read unread properly
- acknowledge handled messages
- archive stale acked noise

### Rule 3 — Sent != received
A message is only real when all 3 are true:
1. delivered to the right channel
2. acknowledged or reflected in action
3. visible in the next step/proof

### Rule 4 — Backlog is a reliability issue
If unread backlog grows large enough to bury high-priority messages, that is an operational incident.

### Rule 5 — Live session beats stale file state for control
If live gateway session and stale markdown/status disagree:
- use live session for urgent action
- use JSONL inbox for proof
- fix the stale file/status path

---

## ACK Discipline

### JSONL inbox
- ACK every handled message
- archive resolved messages
- do not leave high-priority items unread after action is taken

### Builder markdown inboxes
- markdown is for artifacts/history, not the only ACK path
- if a markdown update matters, send a JSONL proof message pointing to it

---

## Failure Handling

### If bridge path works but status is stale
- treat as routing/reporting split
- continue using bridge for action
- log proof via JSONL inbox
- repair status path separately

### If JSONL inbox is backlogged
- stop relying on tail output
- triage unread by priority/age
- ACK/archive aggressively

### If markdown artifact update fails
- do not assume completion delivered
- resend proof via JSONL inbox
- then rewrite artifact if needed

---

## Definition of Clean Delivery
A task handoff is clean only when:
- the task was sent on the right control path
- the receiver acknowledged or acted
- proof came back through the proof path
- status reflects the same reality

If any of those are missing, comms is still broken.