add matrix orchestrator rail and repo scaffolding

rails/orchestrator-matrix/README.md

@@ -0,0 +1,50 @@
+# 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
+- `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
+~/.mosaic/bin/mosaic-orchestrator-run --once
+```
+
+Continuous loop:
+
+```bash
+~/.mosaic/bin/mosaic-orchestrator-run --poll-sec 10
+```
+
+## Matrix Note
+
+This rail writes canonical events to `.mosaic/orchestrator/events.ndjson`.
+Matrix bridge services can consume and relay these events to Matrix rooms.

rails/orchestrator-matrix/adapters/README.md

@@ -0,0 +1,52 @@
+# Adapter Contract
+
+Runtime adapters translate task commands into concrete worker invocations.
+
+## Minimal Contract
+
+Each task should define either:
+
+1. `command` directly in `tasks.json`, or
+2. controller-level `worker.command_template` in `.mosaic/orchestrator/config.json`
+
+`command_template` may use:
+
+- `{task_id}`
+- `{task_title}`
+- `{task_file}`
+
+## Examples
+
+Codex:
+
+```json
+{
+  "worker": {
+    "command_template": "codex \"run task {task_id}: {task_title}\""
+  }
+}
+```
+
+Claude:
+
+```json
+{
+  "worker": {
+    "command_template": "claude -p \"Execute task {task_id}: {task_title}\""
+  }
+}
+```
+
+OpenCode:
+
+```json
+{
+  "worker": {
+    "command_template": "opencode \"execute task {task_id}: {task_title}\""
+  }
+}
+```
+
+## Recommendation
+
+Prefer explicit per-task `command` for deterministic execution and auditability.

rails/orchestrator-matrix/controller/mosaic_orchestrator.py

@@ -0,0 +1,259 @@
+#!/usr/bin/env python3
+"""Deterministic orchestrator controller for Mosaic task delegation."""
+
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import json
+import os
+import pathlib
+import subprocess
+import sys
+import time
+import uuid
+from typing import Any
+
+
+def now_iso() -> str:
+    return dt.datetime.now(dt.timezone.utc).isoformat()
+
+
+def load_json(path: pathlib.Path, default: Any) -> Any:
+    if not path.exists():
+        return default
+    with path.open("r", encoding="utf-8") as f:
+        return json.load(f)
+
+
+def save_json(path: pathlib.Path, data: Any) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(path.suffix + ".tmp")
+    with tmp.open("w", encoding="utf-8") as f:
+        json.dump(data, f, indent=2)
+        f.write("\n")
+    tmp.replace(path)
+
+
+def append_event(events_path: pathlib.Path, event: dict[str, Any]) -> None:
+    events_path.parent.mkdir(parents=True, exist_ok=True)
+    with events_path.open("a", encoding="utf-8") as f:
+        f.write(json.dumps(event, ensure_ascii=True) + "\n")
+
+
+def emit_event(
+    events_path: pathlib.Path,
+    event_type: str,
+    task_id: str,
+    status: str,
+    source: str,
+    message: str,
+    metadata: dict[str, Any] | None = None,
+) -> None:
+    append_event(
+        events_path,
+        {
+            "event_id": str(uuid.uuid4()),
+            "event_type": event_type,
+            "task_id": task_id,
+            "status": status,
+            "timestamp": now_iso(),
+            "source": source,
+            "message": message,
+            "metadata": metadata or {},
+        },
+    )
+
+
+def run_shell(command: str, cwd: pathlib.Path, log_path: pathlib.Path) -> tuple[int, str]:
+    log_path.parent.mkdir(parents=True, exist_ok=True)
+    with log_path.open("a", encoding="utf-8") as log:
+        log.write(f"\n[{now_iso()}] COMMAND: {command}\n")
+        log.flush()
+        proc = subprocess.Popen(
+            ["bash", "-lc", command],
+            cwd=str(cwd),
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            text=True,
+            encoding="utf-8",
+        )
+        output_chunks: list[str] = []
+        assert proc.stdout is not None
+        for line in proc.stdout:
+            output_chunks.append(line)
+            log.write(line)
+        code = proc.wait()
+        log.write(f"[{now_iso()}] EXIT: {code}\n")
+    return code, "".join(output_chunks)
+
+
+def render_command_template(template: str, task: dict[str, Any], task_file: pathlib.Path) -> str:
+    return (
+        template.replace("{task_id}", str(task.get("id", "")))
+        .replace("{task_title}", str(task.get("title", "")))
+        .replace("{task_file}", str(task_file))
+    )
+
+
+def pick_next_task(tasks: list[dict[str, Any]]) -> dict[str, Any] | None:
+    for task in tasks:
+        if task.get("status", "pending") == "pending":
+            return task
+    return None
+
+
+def run_single_task(repo_root: pathlib.Path, orch_dir: pathlib.Path, config: dict[str, Any]) -> bool:
+    tasks_path = orch_dir / "tasks.json"
+    state_path = orch_dir / "state.json"
+    events_path = orch_dir / "events.ndjson"
+    logs_dir = orch_dir / "logs"
+    results_dir = orch_dir / "results"
+
+    tasks = load_json(tasks_path, {"tasks": []})
+    task_items = tasks.get("tasks", [])
+    if not isinstance(task_items, list):
+        raise ValueError("tasks.json must contain {'tasks': [...]} structure")
+
+    task = pick_next_task(task_items)
+    if not task:
+        return False
+
+    task_id = str(task.get("id", "unknown-task"))
+    task["status"] = "running"
+    task["started_at"] = now_iso()
+    save_json(tasks_path, {"tasks": task_items})
+
+    state = load_json(state_path, {"running_task_id": None, "updated_at": None})
+    state["running_task_id"] = task_id
+    state["updated_at"] = now_iso()
+    save_json(state_path, state)
+
+    emit_event(events_path, "task.assigned", task_id, "running", "controller", "Task assigned")
+    emit_event(events_path, "task.started", task_id, "running", "worker", "Worker execution started")
+
+    log_path = logs_dir / f"{task_id}.log"
+    task_file = orch_dir / f"task-{task_id}.json"
+    save_json(task_file, task)
+
+    cmd = str(task.get("command", "")).strip()
+    if not cmd:
+        template = str(config.get("worker", {}).get("command_template", "")).strip()
+        if template:
+            cmd = render_command_template(template, task, task_file)
+
+    if not cmd:
+        task["status"] = "failed"
+        task["failed_at"] = now_iso()
+        task["error"] = "No task command or worker command_template configured."
+        save_json(tasks_path, {"tasks": task_items})
+        emit_event(events_path, "task.failed", task_id, "failed", "controller", task["error"])
+        state["running_task_id"] = None
+        state["updated_at"] = now_iso()
+        save_json(state_path, state)
+        return True
+
+    rc, _ = run_shell(cmd, repo_root, log_path)
+    if rc != 0:
+        task["status"] = "failed"
+        task["failed_at"] = now_iso()
+        task["error"] = f"Worker command failed with exit code {rc}"
+        save_json(tasks_path, {"tasks": task_items})
+        emit_event(events_path, "task.failed", task_id, "failed", "worker", task["error"])
+        state["running_task_id"] = None
+        state["updated_at"] = now_iso()
+        save_json(state_path, state)
+        save_json(results_dir / f"{task_id}.json", {"task_id": task_id, "status": "failed", "exit_code": rc})
+        return True
+
+    gates = task.get("quality_gates") or config.get("quality_gates") or []
+    all_passed = True
+    gate_results: list[dict[str, Any]] = []
+    for gate in gates:
+        gate_cmd = str(gate).strip()
+        if not gate_cmd:
+            continue
+        emit_event(events_path, "rail.check.started", task_id, "running", "quality-gate", f"Running gate: {gate_cmd}")
+        gate_rc, _ = run_shell(gate_cmd, repo_root, log_path)
+        if gate_rc == 0:
+            emit_event(events_path, "rail.check.passed", task_id, "running", "quality-gate", f"Gate passed: {gate_cmd}")
+        else:
+            all_passed = False
+            emit_event(
+                events_path,
+                "rail.check.failed",
+                task_id,
+                "failed",
+                "quality-gate",
+                f"Gate failed ({gate_rc}): {gate_cmd}",
+            )
+        gate_results.append({"command": gate_cmd, "exit_code": gate_rc})
+
+    if all_passed:
+        task["status"] = "completed"
+        task["completed_at"] = now_iso()
+        emit_event(events_path, "task.completed", task_id, "completed", "controller", "Task completed")
+    else:
+        task["status"] = "failed"
+        task["failed_at"] = now_iso()
+        task["error"] = "One or more quality gates failed"
+        emit_event(events_path, "task.failed", task_id, "failed", "controller", task["error"])
+
+    save_json(tasks_path, {"tasks": task_items})
+    state["running_task_id"] = None
+    state["updated_at"] = now_iso()
+    save_json(state_path, state)
+    save_json(
+        results_dir / f"{task_id}.json",
+        {
+            "task_id": task_id,
+            "status": task["status"],
+            "completed_at": task.get("completed_at"),
+            "failed_at": task.get("failed_at"),
+            "gate_results": gate_results,
+        },
+    )
+    return True
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Mosaic deterministic orchestrator controller")
+    parser.add_argument("--repo", default=os.getcwd(), help="Repository root (default: cwd)")
+    parser.add_argument("--once", action="store_true", help="Process at most one pending task and exit")
+    parser.add_argument("--poll-sec", type=int, default=10, help="Polling interval for continuous mode")
+    args = parser.parse_args()
+
+    repo_root = pathlib.Path(args.repo).resolve()
+    orch_dir = repo_root / ".mosaic" / "orchestrator"
+    config_path = orch_dir / "config.json"
+    if not config_path.exists():
+        print(f"[mosaic-orchestrator] missing config: {config_path}", file=sys.stderr)
+        return 1
+
+    config = load_json(config_path, {})
+    if not config.get("enabled", False):
+        print("[mosaic-orchestrator] disabled in .mosaic/orchestrator/config.json (enabled=false)")
+        return 0
+
+    if args.once:
+        processed = run_single_task(repo_root, orch_dir, config)
+        if not processed:
+            print("[mosaic-orchestrator] no pending tasks")
+        return 0
+
+    print(f"[mosaic-orchestrator] loop start repo={repo_root} poll={args.poll_sec}s")
+    while True:
+        try:
+            processed = run_single_task(repo_root, orch_dir, config)
+            if not processed:
+                time.sleep(max(1, args.poll_sec))
+        except KeyboardInterrupt:
+            print("\n[mosaic-orchestrator] stopping")
+            return 0
+        except Exception as exc:  # pragma: no cover
+            print(f"[mosaic-orchestrator] error: {exc}", file=sys.stderr)
+            time.sleep(max(1, args.poll_sec))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

rails/orchestrator-matrix/protocol/event.schema.json

@@ -0,0 +1,64 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mosaicstack.dev/schemas/orchestrator/event.schema.json",
+  "title": "Mosaic Orchestrator Event",
+  "type": "object",
+  "required": [
+    "event_id",
+    "event_type",
+    "task_id",
+    "status",
+    "timestamp",
+    "source"
+  ],
+  "properties": {
+    "event_id": {
+      "type": "string",
+      "description": "UUID string"
+    },
+    "event_type": {
+      "type": "string",
+      "enum": [
+        "task.assigned",
+        "task.started",
+        "task.progress",
+        "task.completed",
+        "task.failed",
+        "rail.check.started",
+        "rail.check.passed",
+        "rail.check.failed"
+      ]
+    },
+    "task_id": {
+      "type": "string"
+    },
+    "status": {
+      "type": "string",
+      "enum": [
+        "pending",
+        "running",
+        "completed",
+        "failed"
+      ]
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "source": {
+      "type": "string",
+      "enum": [
+        "controller",
+        "worker",
+        "quality-gate"
+      ]
+    },
+    "message": {
+      "type": "string"
+    },
+    "metadata": {
+      "type": "object"
+    }
+  },
+  "additionalProperties": true
+}

rails/orchestrator-matrix/protocol/task.schema.json

@@ -0,0 +1,49 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mosaicstack.dev/schemas/orchestrator/task.schema.json",
+  "title": "Mosaic Orchestrator Task",
+  "type": "object",
+  "required": [
+    "id",
+    "title",
+    "status"
+  ],
+  "properties": {
+    "id": {
+      "type": "string"
+    },
+    "title": {
+      "type": "string"
+    },
+    "description": {
+      "type": "string"
+    },
+    "status": {
+      "type": "string",
+      "enum": [
+        "pending",
+        "running",
+        "completed",
+        "failed"
+      ]
+    },
+    "runtime": {
+      "type": "string",
+      "description": "Preferred worker runtime, e.g. codex, claude, opencode"
+    },
+    "command": {
+      "type": "string",
+      "description": "Worker command to execute for this task"
+    },
+    "quality_gates": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "metadata": {
+      "type": "object"
+    }
+  },
+  "additionalProperties": true
+}