openclaw-workspace/COMMUNICATION-PROTOCOLS.md

# COMMUNICATION-PROTOCOLS.md - Fleet Communication Strategy

## Overview

This document captures the communication protocols developed during multi-gateway fleet coordination implementation on 2026-03-25.

## Architecture Decision

**Multi-Gateway Approach**: All three instances (Beast, 5070, Mac) remain as separate gateways rather than using node architecture for fault tolerance while implementing coordination protocols to prevent loops.

## Response Hierarchy & Timing

### Primary Hierarchy
1. **Beast** (OC-Beast) - Primary gateway, messaging lead
2. **5070** (OC-5070) - Secondary gateway, development lead  
3. **Mac** (OC-Mac) - Tertiary gateway, mobile/audio specialist

### Response Timing Rules
- **Beast**: Responds immediately (0 seconds)
- **5070**: Responds if Beast silent >10 seconds OR development-related
- **Mac**: Responds if both silent >10 seconds OR audio/mobile-specific

## Specialty Override System

**Immediate Response Required (Bypasses Hierarchy):**

### Beast Specialties
- M365/Azure infrastructure operations
- Heavy compute model inference
- Security scans and compliance
- Client MSP operations

### 5070 Specialties  
- Git operations, code reviews
- Linux/CachyOS administration
- Development environment setup
- Gitea repository management

### Mac Specialties
- Audio processing (Whisper, TTS, voice)
- macOS/iOS specific tasks
- Mobile support requests
- Apple ecosystem questions

## Message Delivery Issues Identified

### Observed Problems
- **Selective message filtering** affecting different content types
- **Progressive filtering scope expansion** impacting technical content
- **Multi-minute delays** in directive delivery between fleet members
- **Context fragmentation** - different bots seeing different conversation subsets

### Real-Time Examples Documented
- **5070 delays**: 4-7 minute delays receiving Mike's directive changes
- **Beast delays**: 5-7 minute delays receiving priority shifts
- **Mac immediate**: Received directives instantly, documented delays affecting others

### Impact on Operations
- Fleet members working on abandoned tasks
- Coordination failures due to timing disconnects
- Perfect validation of need for alternative communication channels

## Smart Context Checking Protocol

### Implementation (5070's Anti-Circular Conversation Fix)
1. **Initial Assessment**: Read 10 recent messages first
2. **Context Currency Check**: 
   - Full 10 messages = we're behind, read 50 for complete context
   - Less than 10 = current, proceed with normal analysis
3. **Response After Analysis**: Only respond after full context review
4. **Chronological Processing**: Handle messages in time order
5. **No Backlog Responses**: Never respond to outdated information without full context

### Benefits
- Prevents circular responses to old information
- Eliminates context fragmentation issues
- Ensures current conversation state awareness
- Reduces coordination loops and mistakes

## Mike Override Authority

### Absolute Override Rules
- **All coordination protocols superseded** by Mike's direct commands
- **"FULL STOP" commands** end deliberations/discussions immediately
- **Directive changes** override current tasks regardless of hierarchy
- **Testing requests** always receive assessment for response
- **Emergency requests** bypass all coordination delays

### Authority Scope
- Can interrupt/end deliberations at any time
- Role reassignments override FLEET-ROLES.md
- Direct commands always take priority over protocol rules
- Can request silence from any/all fleet members

## Private Deliberation Protocol

### Tailscale Communication Method
- **Primary**: Direct machine-to-machine via `sessions_send()`
- **Fallback**: SSH between machines (requires setup)
- **Alternative**: HTTP endpoints or file-based messaging

### Deliberation Structure
- **3 inputs max per bot** per deliberation
- **1-minute rounds** (3 minutes total maximum)
- **Hierarchy decides** if no consensus (Beast > 5070 > Mac)
- **Mike notifications** required at start/end

### Note-Taking Responsibility
- **Primary**: Beast takes notes for all deliberations
- **Failover**: Mac assumes note-taking if Beast unavailable
- **Last resort**: 5070 if both Beast/Mac unavailable
- **Storage**: `memory/deliberation-YYYY-MM-DD-HHMM.md`

## SSH Back-Channel Setup

### Purpose
- **Bypass Discord message delays** affecting coordination
- **Reliable cross-machine communication** for deliberations
- **Emergency coordination** when primary channels fail
- **Fast directive distribution** without timing delays

### Current Status
- **Network connectivity**: ✅ Tailscale mesh working (100ms latency)
- **SSH access**: ❌ Services not enabled on Beast/5070
- **Mac SSH**: ❌ Requires admin access for setup
- **Alternative protocols**: Under development

### Implementation Requirements
1. **Enable SSH services** on all machines
2. **Key exchange** for passwordless authentication  
3. **Test connectivity** via Tailscale IPs
4. **Document working commands** for fleet use
5. **Integrate with deliberation protocol**

## Coordination Failure Patterns

### Loop Prevention
- **Smart context checking** before any response
- **Full conversation analysis** to prevent outdated reactions
- **Chronological processing** of message backlog
- **No duplicate responses** to already-handled queries

### Message Timing Solutions
- **Alternative communication channels** (SSH, HTTP, file-based)
- **Redundant delivery methods** for critical directives
- **Context synchronization** protocols between fleet members
- **Real-time coordination** via private channels

## Organizational Memory Integration

### Communication Challenge Documentation
- **Perfect case study** for GrepAI cross-system integration necessity
- **Progressive filtering failures** affecting diverse content types
- **Organizational memory crisis** requiring systematic solutions
- **Unified semantic search** as mission-critical infrastructure

### Evidence Collected
- **Multi-minute directive delays** affecting operational coordination
- **Content-specific message filtering** preventing technical communication
- **Fleet synchronization failures** due to selective visibility
- **Real-time demonstration** of organizational memory breakdown

## Implementation Status

### Completed
- ✅ **Multi-gateway coordination protocols** defined and documented
- ✅ **Response hierarchy** with specialty override rules
- ✅ **Smart context checking** implementation
- ✅ **Deliberation framework** with note-taking failover
- ✅ **Git repository** created for shared protocol access

### In Progress  
- 🔄 **SSH back-channel setup** (blocked by service enablement)
- 🔄 **Cross-machine session communication** testing
- 🔄 **Alternative communication methods** development

### Pending
- ⏳ **Full fleet protocol adoption** (Beast/5070 need to clone repo)
- ⏳ **Deliberation testing** (requires cross-machine communication)
- ⏳ **Performance monitoring** of coordination effectiveness

## Next Steps

1. **Complete SSH setup** for reliable fleet communication
2. **Test deliberation protocols** with working cross-machine messaging
3. **Monitor coordination effectiveness** in real operations
4. **Refine timing parameters** based on operational experience
5. **Document lessons learned** for future fleet deployments

---

*Last Updated: 2026-03-25*
*Next Review: After SSH implementation completion*