# Mosaic Matrix Orchestrator Rail

Runtime-agnostic orchestration rail for delegating work to worker agents and enforcing
mechanical quality gates.

## Purpose

- Decouple orchestration from any single agent runtime feature set
- Persist state in repo-local `.mosaic/orchestrator/` files
- Emit structured events for Matrix transport and audit trails
- Enforce rails before marking tasks complete

## Components

- `protocol/` - JSON schemas for task/event payloads
- `dispatcher/` - MACP dispatch helpers for worktrees, command generation, results, and cleanup
- `controller/mosaic_orchestrator.py` - deterministic controller loop
- `adapters/` - runtime adapter guidance

## Repo Contract

The controller expects this layout in each bootstrapped repo:

```text
.mosaic/orchestrator/
  config.json
  tasks.json
  state.json
  events.ndjson
  logs/
  results/
```

## Quick Start

From a bootstrapped repo:

```bash
~/.config/mosaic/bin/mosaic-orchestrator-matrix-cycle
~/.config/mosaic/bin/mosaic-orchestrator-run --once
~/.config/mosaic/bin/mosaic-orchestrator-drain
```

Continuous loop:

```bash
~/.config/mosaic/bin/mosaic-orchestrator-run --poll-sec 10
```

Sync from `docs/TASKS.md` to queue:

```bash
~/.config/mosaic/bin/mosaic-orchestrator-sync-tasks --apply
```

Set worker command when needed:

```bash
export MOSAIC_WORKER_EXEC="codex -p"
# or
export MOSAIC_WORKER_EXEC="opencode -p"
```

Publish new orchestrator events to Matrix:

```bash
~/.config/mosaic/bin/mosaic-orchestrator-matrix-publish
```

Consume Matrix task messages into `tasks.json`:

```bash
~/.config/mosaic/bin/mosaic-orchestrator-matrix-consume
```

## Matrix Note

This rail writes canonical events to `.mosaic/orchestrator/events.ndjson`.
The Matrix transport bridge publishes those events into the configured control room
and can consume task commands from that room.

Task injection message format (room text):

```text
!mosaic-task {"id":"TASK-123","title":"Fix bug","command":"echo run","quality_gates":["pnpm lint"]}
```

## MACP Notes

MACP-aware tasks add dispatch metadata on top of the existing queue model:

- `dispatch`: `exec`, `yolo`, or `acp`
- `type`: task category used for orchestration intent
- `worktree` / `branch`: task-specific git execution context
- `brief_path`: markdown brief consumed by runtime-backed dispatchers
- `result_path`: structured result JSON written under `.mosaic/orchestrator/`

Controller behavior remains backward compatible:

- Tasks without `dispatch` continue through the legacy shell execution path.
- Tasks with `dispatch` use the MACP dispatcher and can emit `task.gated` and `task.escalated`.
- `acp` dispatch is fail-safe in Phase 1: it escalates with `ACP dispatch requires OpenClaw integration (Phase 2)` instead of reporting success.
- `yolo` dispatch stages the brief in a temporary file so the brief body does not appear in process arguments.

Manual queue operations are exposed through:

```bash
mosaic macp submit ...
mosaic macp status
mosaic macp drain
mosaic macp history --task-id TASK-001
mosaic macp watch --once
mosaic macp watch --webhook
```

The Phase 2A event bridge consumes `.mosaic/orchestrator/events.ndjson` through a polling watcher,
persists cursor state in `.mosaic/orchestrator/event_cursor.json`, and can fan out events to
Discord-formatted stdout lines or webhook callbacks.