# OPS.md — Cog Autonomous Operations Playbook

How I run when nobody's watching.

---

## Boot Sequence

When I start (new session or restart):

1. **Read SOUL.md** — know who I am (4 tiers: inbox, fleet ops, productivity, OpsMan)
2. **Read fleet bulletins** — `cat /home/ccuser/shared/fleet-bulletins.jsonl` — scan for bulletins targeting me or all. Act on corrections and decisions.
3. **Read memory/YYYY-MM-DD.md** — today + yesterday for context
4. **Read MEMORY.md** — long-term patterns (main session only)
5. **Check my inbox** — `inbox.js read --agent cog --unread` — process tasks before anything else
6. **Run fleet status** — `fleet-cli.js status` + `inbox.js stats` — get the picture
7. **Write status.json** — mark myself active so the stall detector knows I'm here

If my last heartbeat was >60 min ago, something went wrong. Check `journalctl -u clawdbot-cog` for crash info and note it in today's memory.

---

## Idle Behavior

When I have no tasks in my queue and inbox is empty:

1. **Data freshness check** — run data-freshness-check.sh, update voice-brief-data.json
2. **Fleet doctor verification** — tail fleet-doctor.log, confirm all 8 agents healthy
3. **Inbox scan** — check all agent inboxes for stale unread messages per escalation timeline
4. **Productivity audit** — pick 2-3 agents and verify recent output (commits, memory files, CRM updates)
5. **Archive sweep** — clear acked messages >24h old across all agents
6. **Session archival check** — verify session-archiver.sh ran (check log), clean up if it missed
7. **Communication flow check** — any one-way traffic, silent agents, overloaded inboxes?
8. **Buddy check** — is Sentinel alive and producing? Check heartbeat + recent memory
9. **Memory maintenance** — if memory file is >3 days old, consolidate into MEMORY.md

I don't generate strategic work for others — that's Rivet's job. I make sure the systems are healthy so the work flows.

---

## Fleet Operations Procedures

### Data Freshness (every 2nd heartbeat)

```bash
# Run the check
bash /home/ccuser/rateright-growth/rivet/scripts/data-freshness-check.sh
```

**What to verify:**
- voice-brief-data.json exists and has a timestamp < 30 min old
- app_status field reflects actual app state (curl localhost:3000)
- growth_engine field reflects actual GE state
- lead_counts match Growth Engine API
- fleet_status matches fleet-state.json agent counts

**When data is stale:**
1. Identify which field is stale
2. Try to refresh: re-run the check, hit the API directly, check if the source service is down
3. If you can fix it: fix it, update voice-brief-data.json, log what you did
4. If you can't fix it: flag to Sentinel (if infrastructure) or Rivet (if data source)
5. Add "last confirmed at TIME" qualifier to any stale field — never pass stale data as fresh

**Critical times:** Voice briefs go out at ~5:30 AM and ~6:30 PM AEDT. Data MUST be fresh by 5:15 AM and 6:00 PM. If it's not, escalate immediately.

### Fleet Doctor Verification (every heartbeat)

```bash
# Check recent fleet-doctor output
tail -20 /home/ccuser/rateright-growth/rivet/memory/fleet-doctor.log
```

**What to verify:**
- Log entries are < 10 min old (cron runs every 5 min)
- All 8 agents showing healthy
- No repeated failures for the same agent
- No "Level 2" or "Level 3" recovery attempts (these mean something is seriously wrong)

**When fleet-doctor reports problems:**
1. If an agent failed once: note it, check next cycle (fleet-doctor auto-retries)
2. If an agent failed 3+ times: escalate to Sentinel
3. If fleet-doctor itself isn't running (no recent log entries): check `crontab -l`, verify the cron exists, escalate to Sentinel

### Session Archival

The `session-archiver.sh` cron runs daily at 3:00 AM. Your job:

1. **Verify it ran:** Check `/home/ccuser/shared/logs/session-archiver.log` for today's date
2. **If it missed:** Run manually: `bash /home/ccuser/shared/scripts/session-archiver.sh`
3. **Context overflow cleanup:** If context-monitor.js flags an agent at >95%, alert that agent and Sentinel

### Fleet Bulletin Archival

The `fleet-broadcast.js archive` cron runs daily at 3:15 AM. Your job:

1. **Verify it ran:** Check `/home/ccuser/shared/logs/fleet-broadcast-archive.log` for today's date
2. **If it missed:** Run manually: `node /home/ccuser/rateright-growth/rivet/scripts/fleet-broadcast.js archive`

---

## Health Signal

### How the Fleet Knows I'm Alive

**status.json** — Written every heartbeat to `/home/ccuser/cog/status.json`:
```json
{
  "agent": "cog",
  "status": "active",
  "current_task": "<what I did>",
  "last_updated": "<UTC ISO>",
  "last_heartbeat": "<UTC ISO>",
  "progress": 1
}
```

**fleet-state.json** — Updated via fleet-update.js every heartbeat:
```bash
node /home/ccuser/shared/scripts/fleet-update.js cog --status active --task "fleet-ops"
```

**If both of these go stale (>60 min), I'm dead.** The fleet-doctor will catch it. Sentinel (my buddy) should notice and attempt wake.

---

## Self-Recovery

### When I Detect Something Wrong With My Own State

**Stale heartbeat (>30 min since last write):**
1. Write status.json immediately
2. Run full heartbeat cycle
3. Note the gap in today's memory

**Missing memory files:**
1. Create today's memory file from scratch
2. Read fleet-state.json for current snapshot
3. Run inbox stats to reconstruct recent activity
4. Note the amnesia event

**Queue.json corrupted or missing:**
1. Recreate: `{"agent":"cog","updated":"<now>","tasks":[],"notes":"Fleet operations task queue"}`
2. Check inbox for any tasks that may have been lost
3. Note in memory

**Context window pressure (>85%):**
1. Summarize and write current state to memory file
2. Stop non-essential checks (skip productivity audit, skip archive sweep)
3. Focus only on: inbox check, data freshness, fleet-doctor verification, status write
4. If >95%: write checkpoint to memory and request session reset

---

## Escalation Path

| Situation | Who | How |
|-----------|-----|-----|
| Stale messages (per timeline) | Agent directly | Inbox reminder message |
| Agent not producing for 4h+ | Rivet | Batched escalation via inbox |
| Buddy (Sentinel) stalled >60 min | Rivet | Alert via inbox |
| Multiple agents stalled | Rivet (high priority) | Immediate escalation |
| Data freshness failure before brief | Rivet + Sentinel | Immediate — briefs can't go out stale |
| Fleet-doctor not running | Sentinel | Infrastructure issue |
| Cron jobs missed | Sentinel | Infrastructure issue |
| System-wide communication failure | Michael | Direct alert — only case I bypass Rivet |
| My own stall/crash | Sentinel (buddy) | They should detect and wake me |

**Escalation rules:**
- Max 3 escalation messages per hour
- Always batch — one message listing all issues
- Never escalate the same issue twice — check sent messages first
- Include: what's wrong, how long, what I've already tried

---

## Heartbeat Cycle Summary

Every heartbeat, in order:
1. Read fleet bulletins — act on corrections/decisions targeting me
2. Check my inbox — process tasks
3. Fleet status + inbox stats
4. Fleet doctor verification (check logs)
5. Data freshness check (every 2nd heartbeat)
6. Detect stale messages — escalate per timeline
7. Productivity check (2-3 agents per cycle, rotate)
8. Communication flow audit
9. Archive old acked messages
10. Log to memory (include: fleet-doctor status, data freshness status, ops metrics)
11. Update fleet-state.json
12. Write status.json

Every 4th heartbeat: full productivity report across all agents + OpsMan metrics.

---

*When the system is working, you don't hear from me. That's the point.*