@adaptic/maestro 1.1.6 → 1.1.8

package/docs/guides/outbound-governance-setup.md

@@ -0,0 +1,438 @@
+# Outbound Governance Setup Guide
+
+How the agent's outbound communication safety system works: pre-send audit hooks, factual validation, outbound deduplication (atomic locks + LLM semantic checks), information barriers, disclosure assessment, and audit logging. This is the governance layer that ensures every outbound message is safe, accurate, and non-duplicated.
+
+**Prerequisites**: At least one communication channel configured ([Email](email-setup.md), [Slack](slack-setup.md), [WhatsApp](whatsapp-setup.md), or [SMS](voice-sms-setup.md)).
+
+---
+
+## Architecture Overview
+
+Every outbound message passes through multiple safety layers before being sent:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  Agent drafts a message                                          │
+│         │                                                        │
+│         ▼                                                        │
+│  ┌─── Layer 0: Factual Validation ──────────────────────────┐   │
+│  │  validate-outbound.py / validate_outbound.py              │   │
+│  │  Checks: relationship accuracy, AI disclosure, scheduling │   │
+│  │  Result: PASS / WARN / BLOCK                              │   │
+│  └──────────────────────────────────────────────────────────┘   │
+│         │                                                        │
+│         ▼                                                        │
+│  ┌─── Layer 1: LLM Semantic Dedup (email only) ─────────────┐  │
+│  │  llm_email_dedup.py                                        │  │
+│  │  Asks Claude Haiku: "Was this topic already addressed?"    │  │
+│  │  Result: PASS / DEDUP_SKIP                                 │  │
+│  └──────────────────────────────────────────────────────────┘   │
+│         │                                                        │
+│         ▼                                                        │
+│  ┌─── Layer 2: Information Barrier Check ────────────────────┐  │
+│  │  disclosure_assessment.py + disclosure_boundaries.py       │  │
+│  │  Checks: recipient access level, content provenance        │  │
+│  │  Result: PASS / WARN / STRIP / BLOCK                       │  │
+│  └──────────────────────────────────────────────────────────┘   │
+│         │                                                        │
+│         ▼                                                        │
+│  ┌─── Layer 3: Content-Hash Dedup ──────────────────────────┐  │
+│  │  outbound-dedup.sh / outbound_dedup.py                     │  │
+│  │  Atomic mkdir lock: sha256(to + subject + body[:100])      │  │
+│  │  Result: CLAIMED (send) / DEDUP_SKIP (another session)    │  │
+│  └──────────────────────────────────────────────────────────┘   │
+│         │                                                        │
+│         ▼                                                        │
+│  ┌─── Layer 4: Pre-Send Audit Hook ─────────────────────────┐  │
+│  │  hooks/pre-send-audit.sh                                    │  │
+│  │  Rate limits: 3,000/hour, 20,000/day                       │  │
+│  │  Result: ALLOWED / BLOCKED                                  │  │
+│  └──────────────────────────────────────────────────────────┘   │
+│         │                                                        │
+│         ▼                                                        │
+│      SEND ──▶ Post-action log (hooks/post-action-log.sh)       │
+│              Session end log (hooks/session-end-log.sh)          │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**Design principle**: Fail-open on infrastructure errors. If a dedup lock fails or a validation script crashes, the message sends anyway. It's better to send a duplicate than to silently drop a message.
+
+---
+
+## 1. Claude Code Hooks (`scripts/hooks/`)
+
+Hooks are shell scripts registered in `.claude/settings.json` that execute before or after tool calls.
+
+### 1.1 Pre-Send Audit (`pre-send-audit.sh`)
+
+**Trigger**: `PreToolUse` hook, fires before Slack/Gmail send tools.
+
+**What it does**:
+1. Reads the tool input from stdin
+2. Checks daily send counter against rate limits (3,000/hour, 20,000/day)
+3. Logs the send to `logs/audit/YYYY-MM-DD-sends.jsonl`
+4. Exit 0 = allowed (message shown to Claude)
+5. Exit 2 = blocked (rejection message shown to Claude)
+
+**Rate limit state**: `logs/audit/send-counter.yaml` — tracks hourly and daily totals, resets at midnight.
+
+### 1.2 Post-Action Log (`post-action-log.sh`)
+
+**Trigger**: `PostToolUse` hook, fires after every tool execution.
+
+**What it does**:
+- Logs tool name and completion timestamp to `logs/audit/YYYY-MM-DD-actions.jsonl`
+- Consumes stdin (tool result) without blocking
+
+### 1.3 MCP Slack Send Block (`block-mcp-slack-send.sh`)
+
+**Trigger**: `PreToolUse` hook, matches MCP Slack send tools.
+
+**What it does**:
+- Unconditionally blocks MCP Slack sends (exit 2)
+- Enforces CEO directive: all Slack sends must use `scripts/slack-send.sh` with User OAuth Token
+- MCP Slack adds "Sent using @Claude" label, breaking agent identity
+
+### 1.4 Session End Log (`session-end-log.sh`)
+
+**Trigger**: `Stop` hook, fires when a Claude session ends.
+
+**What it does**:
+1. Logs session completion to `logs/sessions/YYYY-MM-DD-sessions.jsonl`
+2. Spawns the post-interaction indexer in the background (`post-interaction-indexer.py --scan-today`)
+3. Fire-and-forget: indexer runs asynchronously, doesn't block session teardown
+
+### 1.5 Hook Registration
+
+Hooks are registered in `.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "mcp__claude_ai_Slack__slack_send_message",
+        "command": "bash scripts/hooks/block-mcp-slack-send.sh"
+      },
+      {
+        "matcher": "Bash",
+        "command": "bash scripts/hooks/pre-send-audit.sh slack"
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "*",
+        "command": "bash scripts/hooks/post-action-log.sh"
+      }
+    ],
+    "Stop": [
+      {
+        "command": "bash scripts/hooks/session-end-log.sh"
+      }
+    ]
+  }
+}
+```
+
+---
+
+## 2. Factual Validation (`validate-outbound.py`)
+
+Checks outbound messages for factual errors before sending.
+
+### 2.1 What It Checks
+
+| Check | Severity | Example |
+|---|---|---|
+| Relationship claims | Block | Claiming a meeting happened that didn't |
+| AI disclosure | Block | Revealing the agent is AI in external comms |
+| In-person scheduling | Block | Scheduling the agent for a physical meeting |
+| Title accuracy | Warn | Using wrong title for a contact |
+| Date accuracy | Warn | Referencing incorrect dates |
+
+### 2.2 Usage
+
+Called automatically by send scripts, or manually:
+
+```bash
+echo "Let's meet at the office tomorrow" | python3 scripts/validate-outbound.py --type slack --recipient "C1234567890"
+```
+
+**Exit codes**:
+- 0: passed (safe to send)
+- 1: issues found (check JSON output for blockers vs warnings)
+
+### 2.3 Integration
+
+Every send script calls `validate-outbound.py` in its pre-send pipeline. If the validator finds `block`-severity issues, the send is aborted with an error message explaining what to fix.
+
+---
+
+## 3. Outbound Deduplication
+
+### 3.1 Content-Hash Dedup (`outbound-dedup.sh`)
+
+Prevents concurrent Claude sessions from sending identical messages.
+
+**Mechanism**: Atomic `mkdir`-based locking (POSIX-guaranteed atomic).
+
+**Key generation**:
+
+| Channel | Hash Input |
+|---|---|
+| Email | `sha256(to + subject + body[:100])` |
+| SMS | `sha256(to + body[:100])` |
+| WhatsApp | `sha256(to + body[:100])` |
+| Slack | Channel + message_ts (passthrough) |
+
+**Commands**:
+
+```bash
+# Generate a dedup key
+./scripts/outbound-dedup.sh generate-key email "to@example.com" "Subject" "Body text"
+
+# Acquire a lock (returns CLAIMED or DEDUP_SKIP)
+./scripts/outbound-dedup.sh acquire email <key> <session_id>
+
+# Confirm send succeeded (audit trail)
+./scripts/outbound-dedup.sh confirm email <key> "preview text"
+
+# Check lock status
+./scripts/outbound-dedup.sh check email <key>
+
+# Clean up expired locks
+./scripts/outbound-dedup.sh cleanup [max_age_minutes]
+```
+
+**Lock TTL**: 720 minutes (12 hours) — long because email dedup needs to span multiple sessions.
+
+**Lock directory**: `state/locks/outbound/{channel}/{dedup-key}/`
+
+### 3.2 Slack Response Dedup (`slack-responded.sh`)
+
+Specialised dedup for Slack responses. Uses the same atomic mkdir pattern but keyed by `channel + message_ts`:
+
+```bash
+# Acquire response lock
+./scripts/slack-responded.sh acquire <channel> <message_ts> <session_id>
+
+# Confirm response sent
+./scripts/slack-responded.sh confirm <channel> <message_ts> "preview text"
+```
+
+### 3.3 LLM Semantic Dedup (`llm_email_dedup.py`)
+
+For email only. Uses Claude Haiku to check if a topic has already been addressed:
+
+1. Fetches recent sent emails to the same recipient via IMAP
+2. Sends both the draft and recent emails to Haiku with the question: "Has this specific topic already been addressed in a recent email?"
+3. Returns `DEDUP_SKIP` if the LLM says yes
+
+This catches cases where the content-hash doesn't match (different wording, same topic).
+
+### 3.4 Cleanup
+
+Stale locks are cleaned by:
+
+```bash
+# Clean locks older than 5 minutes (default)
+./scripts/outbound-dedup.sh cleanup
+
+# Clean locks older than 60 minutes
+./scripts/outbound-dedup.sh cleanup 60
+
+# Bulk cleanup script
+./scripts/outbound-dedup-cleanup.sh
+```
+
+---
+
+## 4. Information Barriers & Disclosure Assessment
+
+### 4.1 Disclosure Assessment (`disclosure_assessment.py`)
+
+The hard gate that prevents information leakage across recipient boundaries.
+
+**What it does**:
+1. Loads the recipient's user profile from `memory/profiles/users/`
+2. Loads the channel profile from `memory/profiles/channels/` (if Slack)
+3. Extracts keywords and entities from the draft message
+4. Checks message content against the recipient's information boundaries
+5. Checks content provenance (where the information originated)
+6. Assigns severity: low (warn), medium (strip), high (block), critical (block + escalate)
+
+**Exit codes**:
+- 0: passed or warn (safe to send)
+- 1: stripped (send but redact flagged content)
+- 2: blocked (do not send)
+
+**Usage**:
+
+```bash
+# Check a message before sending
+echo "The JVA negotiation is progressing well" | \
+    python3 scripts/disclosure_assessment.py --recipient shayan-kargarian
+
+# With channel context
+python3 scripts/disclosure_assessment.py \
+    --recipient shayan-kargarian --channel rollup-strategy \
+    --message "The acquisition target has confirmed AED 40K"
+```
+
+### 4.2 Disclosure Boundaries (`disclosure_boundaries.py`)
+
+Defines the information boundary rules:
+
+- What information each recipient can receive
+- What topics are restricted per relationship type
+- What sources/matters are confidential to specific deal teams
+
+Rules are derived from user profiles and the information barriers policy.
+
+### 4.3 Information Barriers Policy
+
+Defined in `policies/information-barriers.yaml` (if present). Specifies:
+
+- **Chinese walls** between deal teams
+- **Restricted topics** per recipient classification
+- **Provenance tracking** — which information came from which source/matter
+- **Escalation rules** — what happens when a barrier is breached
+
+### 4.4 Testing Information Barriers
+
+```bash
+python3 scripts/test-information-barriers.py
+```
+
+Runs test scenarios to verify barriers are correctly enforced.
+
+---
+
+## 5. Audit Trail
+
+### 5.1 Log Files
+
+| Log | Path | Contents |
+|---|---|---|
+| Actions | `logs/audit/YYYY-MM-DD-actions.jsonl` | All tool executions, sends, dedup events |
+| Sends | `logs/audit/YYYY-MM-DD-sends.jsonl` | Pre-send audit decisions (allowed/blocked) |
+| Validation | `logs/audit/YYYY-MM-DD-validation.jsonl` | Factual validation results |
+| Pre-draft | `logs/audit/YYYY-MM-DD-pre-draft-lookups.jsonl` | Context lookups before drafting |
+| Sessions | `logs/sessions/YYYY-MM-DD-sessions.jsonl` | Session start/end events |
+
+### 5.2 Rate Limit State
+
+`logs/audit/send-counter.yaml`:
+
+```yaml
+date: "2026-04-09"
+hourly: {}
+totals:
+  slack: 42
+  gmail: 8
+  whatsapp: 3
+  total: 53
+limits:
+  per_hour: 3000
+  per_day: 20000
+```
+
+Resets daily at midnight.
+
+---
+
+## 6. Self-Optimization Metrics
+
+`scripts/self-optimization/compute-metrics.py` calculates governance metrics:
+
+- Dedup hit rate (what percentage of sends were caught as duplicates)
+- Validation block rate (what percentage of messages had issues)
+- Average response latency per channel
+- Session concurrency utilisation
+
+---
+
+## 7. Testing
+
+| # | Test | How to Verify |
+|---|---|---|
+| 1 | Pre-send hook | Send a Slack message — check `logs/audit/YYYY-MM-DD-sends.jsonl` |
+| 2 | Rate limit | Manually set counter to 19999 in `send-counter.yaml` — next send should block |
+| 3 | MCP block | Attempt MCP Slack send — should be blocked |
+| 4 | Factual validation | Send message mentioning in-person meeting — should block |
+| 5 | Content-hash dedup | Send identical email twice — second should `DEDUP_SKIP` |
+| 6 | LLM dedup | Send two different emails about same topic — second should warn |
+| 7 | Slack response dedup | Reply to same message from two sessions — one should skip |
+| 8 | Disclosure assessment | Test with restricted content + external recipient |
+| 9 | Audit logging | Verify all sends appear in `logs/audit/` |
+| 10 | Lock cleanup | Run `./scripts/outbound-dedup.sh cleanup` — stale locks removed |
+
+---
+
+## 8. Troubleshooting
+
+### All sends blocked: "Daily send limit reached"
+
+1. Check `logs/audit/send-counter.yaml` — if total is at 20,000, wait for midnight reset
+2. For emergencies, manually reset the counter: delete the file (it recreates on next send)
+3. Consider if a runaway session is sending in a loop
+
+### Dedup false positives (legitimate messages being skipped)
+
+1. Check lock directory: `ls state/locks/outbound/email/`
+2. Clean stale locks: `./scripts/outbound-dedup.sh cleanup 5`
+3. For email: reduce lock TTL if 12 hours is too long for your use case
+4. Use `--force` flag on send scripts to bypass dedup for exceptional cases
+
+### Disclosure assessment blocking legitimate messages
+
+1. Check the recipient's user profile in `memory/profiles/users/`
+2. Review what information boundaries are set
+3. Run the assessment manually to see the exact output
+4. Update the user profile if boundaries are too restrictive
+
+### Hooks not firing
+
+1. Check `.claude/settings.json` has the hooks registered
+2. Verify hook scripts are executable: `chmod +x scripts/hooks/*.sh`
+3. Check hook script paths are correct (relative to repo root)
+4. Test hook manually: `echo '{}' | bash scripts/hooks/pre-send-audit.sh slack`
+
+---
+
+## Key Files
+
+| File | Purpose |
+|---|---|
+| **Hooks** | |
+| `scripts/hooks/pre-send-audit.sh` | Rate limiting and send logging |
+| `scripts/hooks/post-action-log.sh` | Tool completion logging |
+| `scripts/hooks/block-mcp-slack-send.sh` | MCP Slack send block |
+| `scripts/hooks/session-end-log.sh` | Session end logging + indexer trigger |
+| **Validation** | |
+| `scripts/validate-outbound.py` | Factual validation (relationship, dates, disclosure) |
+| `scripts/validate_outbound.py` | Alternate import path for Python scripts |
+| **Dedup** | |
+| `scripts/outbound-dedup.sh` | Atomic content-hash deduplication |
+| `scripts/outbound_dedup.py` | Python dedup module (imported by send scripts) |
+| `scripts/outbound-dedup-cleanup.sh` | Stale lock cleanup |
+| `scripts/slack-responded.sh` | Slack response deduplication |
+| `scripts/llm_email_dedup.py` | LLM semantic email deduplication |
+| **Information Barriers** | |
+| `scripts/disclosure_assessment.py` | Post-draft disclosure analysis |
+| `scripts/disclosure_boundaries.py` | Information boundary rule definitions |
+| `scripts/test-information-barriers.py` | Barrier test suite |
+| **Policy** | |
+| `policies/action-classification.yaml` | Action risk levels and approval rules |
+| `policies/information-barriers.yaml` | Information barrier definitions |
+| `.claude/settings.json` | Hook registration |
+
+---
+
+## Related Documents
+
+- [Email Setup](email-setup.md) — Email dedup pipeline integration
+- [Slack Setup](slack-setup.md) — Slack dedup and MCP block
+- [Communications Policy](../governance/communications-policy.md) — Voice modes and approval rules
+- [Action Approval Model](../governance/action-approval-model.md) — Approval workflows
+- [Information Barrier Design](../superpowers/specs/2026-04-05-information-barrier-design.md) — Technical specification