feat: MACP Phase 2A — Event Bridge + Notification System (#11)

docs/DEVELOPER-GUIDE/orchestrator-matrix/macp-phase2a.md

@@ -0,0 +1,45 @@
+# MACP Phase 2A
+
+MACP Phase 2A adds the repo-local event bridge that makes orchestrator lifecycle events consumable by external systems.
+
+## What Changed
+
+1. `tools/orchestrator-matrix/events/event_watcher.py` polls `.mosaic/orchestrator/events.ndjson`, parses appended NDJSON events, dispatches callbacks, and persists a byte-offset cursor in `.mosaic/orchestrator/event_cursor.json`.
+2. `tools/orchestrator-matrix/events/webhook_adapter.py` forwards selected MACP events to a configured webhook endpoint with bounded retries and optional bearer auth.
+3. `tools/orchestrator-matrix/events/discord_formatter.py` renders task lifecycle events into concise Discord-friendly status lines.
+4. `bin/mosaic-macp` adds `watch` mode for one-shot or continuous event processing.
+
+## Watcher Behavior
+
+1. File watching is polling-based and stdlib-only for portability.
+2. The watcher resets its cursor if the events file is truncated.
+3. Corrupt JSON lines are logged to stderr and skipped.
+4. A trailing partial line is left unread until the newline arrives, preventing half-written events from being consumed.
+
+## Webhook Configuration
+
+Configure `.mosaic/orchestrator/config.json` under `macp.webhook`:
+
+```json
+{
+  "macp": {
+    "webhook": {
+      "enabled": false,
+      "url": "http://localhost:8080/macp/events",
+      "auth_token": "",
+      "timeout_seconds": 10,
+      "retry_count": 2,
+      "event_filter": ["task.completed", "task.failed", "task.escalated"]
+    }
+  }
+}
+```
+
+## CLI
+
+```bash
+mosaic macp watch --once
+mosaic macp watch --webhook
+```
+
+`--once` performs a single poll and exits. `--webhook` enables delivery via the configured `macp.webhook` block while still printing Discord-formatted event lines to stdout.