@adaptic/maestro 1.0.0

package/docs/architecture/continuous-monitoring.md

@@ -0,0 +1,221 @@
+# Continuous Inbound Monitoring & Autonomous Response Architecture
+
+> How Sophie watches Slack, WhatsApp, and Gmail continuously and responds autonomously.
+
+---
+
+## Overview
+
+The CEO Brain operates a **continuous monitoring loop** across all communication channels. Unlike the scheduled workflows (morning brief, comms triage) which run at fixed times, the continuous monitor runs **perpetually** — polling channels every 30-120 seconds and dispatching responses based on urgency, classification, and approval rules.
+
+### Two Response Modes
+
+1. **Direct Response** — Sophie's main orchestrating Claude Code session handles simple/routine inbound items directly (acknowledgements, status updates, scheduling, routine follow-ups)
+2. **Spawned Session** — For complex inbound tasks that require deep work (research, analysis, document preparation, multi-step coordination), Sophie spawns a dedicated Claude Code sub-session that works independently and reports back
+
+```
+┌─────────────────────────────────────────────────────────┐
+│              CONTINUOUS MONITORING LOOP                   │
+│                                                          │
+│  ┌──────────┐  ┌──────────┐  ┌──────────────┐          │
+│  │  Slack    │  │ WhatsApp │  │    Gmail      │          │
+│  │ Monitor  │  │ Monitor  │  │   Monitor     │          │
+│  └────┬─────┘  └────┬─────┘  └──────┬───────┘          │
+│       │              │               │                   │
+│       └──────────────┼───────────────┘                   │
+│                      ▼                                   │
+│           ┌──────────────────┐                           │
+│           │ Inbound          │                           │
+│           │ Dispatcher       │                           │
+│           └────────┬─────────┘                           │
+│                    │                                     │
+│         ┌──────────┼──────────┐                          │
+│         ▼          ▼          ▼                          │
+│    ┌─────────┐ ┌────────┐ ┌─────────┐                   │
+│    │ Simple  │ │ Queue  │ │ Complex │                    │
+│    │ Direct  │ │ for    │ │ Spawn   │                    │
+│    │ Reply   │ │ Review │ │ Session │                    │
+│    └─────────┘ └────────┘ └─────────┘                   │
+│                                                          │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Monitoring Loop Intervals
+
+| Channel  | Poll Interval | Method                  | Scope                              |
+| -------- | ------------- | ----------------------- | ---------------------------------- |
+| Slack    | 60 seconds    | Desktop app observation | Priority channels + DMs + mentions |
+| Gmail    | 120 seconds   | Browser observation     | Unread inbox, priority senders     |
+| WhatsApp | 120 seconds   | Desktop app observation | Business-tagged contacts only      |
+
+These run as **persistent background processes** via launchd, independent of the main Claude Code session.
+
+---
+
+## Inbound Classification
+
+Every inbound message is classified along three dimensions:
+
+### 1. Urgency
+
+| Level        | Criteria                                                     | Response SLA                  |
+| ------------ | ------------------------------------------------------------ | ----------------------------- |
+| **Critical** | From Mehran, regulator, or flagged-urgent contact            | < 5 minutes (immediate alert) |
+| **High**     | From investor, board member, acquisition target, senior team | < 30 minutes                  |
+| **Normal**   | From team member, known contact, routine business            | < 2 hours                     |
+| **Low**      | Newsletter, notification, non-actionable                     | Next scheduled triage         |
+
+### 2. Complexity
+
+| Level        | Criteria                                                      | Response Mode                       |
+| ------------ | ------------------------------------------------------------- | ----------------------------------- |
+| **Simple**   | Acknowledgement, yes/no, scheduling, status update            | Direct reply from main session      |
+| **Moderate** | Requires context lookup, short analysis, or coordination      | Direct reply with research          |
+| **Complex**  | Requires deep analysis, document preparation, multi-step work | Spawn dedicated Claude Code session |
+
+### 3. Risk
+
+| Level      | Criteria                                                 | Approval                  |
+| ---------- | -------------------------------------------------------- | ------------------------- |
+| **Low**    | Internal team, routine content                           | Auto-send (pre-approved)  |
+| **Medium** | External known contact, substantive content              | Draft + queue for review  |
+| **High**   | Investor, regulator, board, M&A, financial/legal content | Draft + explicit approval |
+
+---
+
+## Autonomous Response Rules
+
+Sophie can respond autonomously (without Mehran's approval) to:
+
+### Auto-Respond (Send Immediately, Log All)
+
+- Internal team messages requesting status updates
+- Acknowledgements to known contacts ("Thanks, received — reviewing now")
+- Calendar confirmations and scheduling responses
+- Follow-up chasers for items already approved
+- Internal Slack thread replies continuing approved conversation threads
+
+### Draft-and-Hold (Send After Review)
+
+- First-contact replies to external parties
+- Substantive responses containing analysis or recommendations
+- Any reply that creates a commitment or deadline
+- Messages to contacts classified as investor/board/regulator
+
+### Escalate Immediately (Alert Mehran)
+
+- Messages from regulators (DFSA, MAS, FCA, SEC, etc.)
+- Messages flagged as urgent from any channel
+- Messages containing legal threats or compliance issues
+- Messages from acquisition targets or their advisors
+
+---
+
+## Session Spawning
+
+When an inbound item requires complex work, Sophie spawns a dedicated Claude Code session:
+
+### When to Spawn
+
+- Research request requiring web searches and analysis (> 5 minutes of work)
+- Document preparation (memo, brief, analysis, board material)
+- Multi-repo investigation (checking code, regulatory docs, strategy docs)
+- Due diligence task on a rollup target
+- Complex email requiring context assembly from multiple sources
+- Any task that would block the main monitoring loop for > 3 minutes
+
+### Spawn Mechanism
+
+```bash
+# Sophie spawns a sub-session with a specific task
+claude --dangerously-skip-permissions \
+  -p "You are working for Sophie Nguyen, Chief of Staff at Adaptic.ai.
+      Task: {task_description}
+      Context: {assembled_context}
+      Deliver output to: {output_path}
+      When complete, write a summary to: {completion_signal_path}" \
+  --output-format text \
+  > logs/sessions/{session_id}.log 2>&1 &
+```
+
+### Session Contract
+
+Each spawned session receives:
+
+- **Task description** — What needs to be done
+- **Context** — Relevant knowledge, conversation history, source material
+- **Output path** — Where to write the deliverable
+- **Completion signal** — File path to write when done (monitored by main session)
+- **Time budget** — Maximum runtime before auto-termination
+- **Scope boundary** — What repos/files the session may access
+
+### Session Types
+
+| Type            | Use Case                        | Time Budget | Example                                                          |
+| --------------- | ------------------------------- | ----------- | ---------------------------------------------------------------- |
+| Quick Research  | Look something up, summarise    | 5 min       | "What's the latest on DFSA AI governance guidelines?"            |
+| Draft Response  | Prepare a reply needing context | 10 min      | Complex email reply needing rollup strategy context              |
+| Analysis        | Deep dive on a topic            | 30 min      | Competitive intelligence report on a new entrant                 |
+| Document Prep   | Create a deliverable            | 60 min      | Board readiness assessment, target briefing                      |
+| Multi-Repo Task | Cross-codebase investigation    | 30 min      | Check DFSA gap status across dfsa-submission and adapticai repos |
+
+### Session Lifecycle
+
+```
+Spawn → Execute → Write Output → Signal Completion → Main Session Reviews → Route Output
+```
+
+1. **Spawn**: Main session creates the task with full context
+2. **Execute**: Sub-session works independently
+3. **Output**: Sub-session writes deliverable to `outputs/sessions/{id}/`
+4. **Signal**: Sub-session writes completion marker
+5. **Review**: Main session reads output, verifies quality
+6. **Route**: Main session delivers output (send reply, file memo, update memory, etc.)
+
+---
+
+## Monitoring Process Architecture
+
+### launchd Services
+
+Three persistent monitoring services, each as a launchd daemon:
+
+1. **com.adaptic.ceobrain.monitor.slack** — Slack observation loop
+2. **com.adaptic.ceobrain.monitor.gmail** — Gmail observation loop
+3. **com.adaptic.ceobrain.monitor.whatsapp** — WhatsApp observation loop
+
+Plus one dispatcher:
+
+4. **com.adaptic.ceobrain.dispatcher** — Classifies and routes inbound items
+
+### Main Session Role
+
+The main Claude Code session (Sophie) runs continuously and:
+
+- Reads the inbound queue populated by monitors
+- Classifies items by urgency/complexity/risk
+- Handles simple items directly
+- Spawns sessions for complex items
+- Reviews outputs from spawned sessions
+- Manages the response queue
+- Maintains executive memory and state
+
+### Failure Handling
+
+- If a monitor crashes, launchd restarts it automatically
+- If the main session crashes, monitors continue queueing — items are processed on restart
+- Spawned sessions have time budgets — they are killed if they exceed them
+- All inbound items are persisted to disk before processing (no data loss on crash)
+
+---
+
+## Security Considerations
+
+- Monitors are **observe-only** — they cannot send messages
+- Only the main session (or approved spawned sessions) can send
+- All autonomous sends are logged with full content and recipient
+- Rate limits apply even to autonomous responses
+- The emergency stop halts all monitoring and response
+- Session spawning is logged with task description and scope