From 014654972cfb740deb1c9980f1f89d9e97c46eb4 Mon Sep 17 00:00:00 2001
From: Jason Woltje <jason.woltje@uscllc.com>
Date: Tue, 17 Feb 2026 13:56:59 -0600
Subject: [PATCH] add single-command orchestrator matrix cycle

---
 README.md                            |  1 +
 bin/mosaic-bootstrap-repo            |  2 +-
 bin/mosaic-doctor                    |  1 +
 bin/mosaic-orchestrator-matrix-cycle | 19 +++++++++++++++++++
 rails/orchestrator-matrix/README.md  |  1 +
 templates/repo/.mosaic/README.md     |  1 +
 6 files changed, 24 insertions(+), 1 deletion(-)
 create mode 100755 bin/mosaic-orchestrator-matrix-cycle

diff --git a/README.md b/README.md
index e1c7cec..f1e1972 100644
--- a/README.md
+++ b/README.md
@@ -136,6 +136,7 @@ Mosaic includes a runtime-agnostic orchestrator rail at:
 Run from a bootstrapped repo:
 
 ```bash
+~/.mosaic/bin/mosaic-orchestrator-matrix-cycle
 ~/.mosaic/bin/mosaic-orchestrator-run --once
 ~/.mosaic/bin/mosaic-orchestrator-run --poll-sec 10
 ~/.mosaic/bin/mosaic-orchestrator-matrix-publish
diff --git a/bin/mosaic-bootstrap-repo b/bin/mosaic-bootstrap-repo
index 82ff1c7..429ffd1 100755
--- a/bin/mosaic-bootstrap-repo
+++ b/bin/mosaic-bootstrap-repo
@@ -104,7 +104,7 @@ fi
 echo "[mosaic] Repo bootstrap complete: $TARGET_DIR"
 echo "[mosaic] Next: edit $TARGET_DIR/.mosaic/repo-hooks.sh with project workflows"
 echo "[mosaic] Optional: apply quality rails via ~/.mosaic/bin/mosaic-quality-apply --template <template> --target $TARGET_DIR"
-echo "[mosaic] Optional: run orchestrator rail via ~/.mosaic/bin/mosaic-orchestrator-run --once"
+echo "[mosaic] Optional: run orchestrator rail via ~/.mosaic/bin/mosaic-orchestrator-matrix-cycle"
 
 if [[ -n "$QUALITY_TEMPLATE" ]]; then
   if [[ -x "$MOSAIC_HOME/bin/mosaic-quality-apply" ]]; then
diff --git a/bin/mosaic-doctor b/bin/mosaic-doctor
index e640f6f..06018c4 100755
--- a/bin/mosaic-doctor
+++ b/bin/mosaic-doctor
@@ -128,6 +128,7 @@ expect_file "$MOSAIC_HOME/bin/mosaic-quality-verify"
 expect_file "$MOSAIC_HOME/bin/mosaic-orchestrator-run"
 expect_file "$MOSAIC_HOME/bin/mosaic-orchestrator-matrix-publish"
 expect_file "$MOSAIC_HOME/bin/mosaic-orchestrator-matrix-consume"
+expect_file "$MOSAIC_HOME/bin/mosaic-orchestrator-matrix-cycle"
 expect_file "$MOSAIC_HOME/rails/orchestrator-matrix/transport/matrix_transport.py"
 
 # Claude runtime file checks (copied, non-symlink).
diff --git a/bin/mosaic-orchestrator-matrix-cycle b/bin/mosaic-orchestrator-matrix-cycle
new file mode 100755
index 0000000..164d5cf
--- /dev/null
+++ b/bin/mosaic-orchestrator-matrix-cycle
@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.mosaic}"
+
+consume="$MOSAIC_HOME/bin/mosaic-orchestrator-matrix-consume"
+run="$MOSAIC_HOME/bin/mosaic-orchestrator-run"
+publish="$MOSAIC_HOME/bin/mosaic-orchestrator-matrix-publish"
+
+for cmd in "$consume" "$run" "$publish"; do
+  if [[ ! -x "$cmd" ]]; then
+    echo "[mosaic-orch-cycle] missing executable: $cmd" >&2
+    exit 1
+  fi
+done
+
+"$consume"
+"$run" --once "$@"
+"$publish"
diff --git a/rails/orchestrator-matrix/README.md b/rails/orchestrator-matrix/README.md
index 9f594a2..f498456 100644
--- a/rails/orchestrator-matrix/README.md
+++ b/rails/orchestrator-matrix/README.md
@@ -35,6 +35,7 @@ The controller expects this layout in each bootstrapped repo:
 From a bootstrapped repo:
 
 ```bash
+~/.mosaic/bin/mosaic-orchestrator-matrix-cycle
 ~/.mosaic/bin/mosaic-orchestrator-run --once
 ```
 
diff --git a/templates/repo/.mosaic/README.md b/templates/repo/.mosaic/README.md
index 49f48d6..ec26cf7 100644
--- a/templates/repo/.mosaic/README.md
+++ b/templates/repo/.mosaic/README.md
@@ -37,6 +37,7 @@ Repo-local orchestrator state lives in `.mosaic/orchestrator/`.
 Run one cycle:
 
 ```bash
+~/.mosaic/bin/mosaic-orchestrator-matrix-cycle
 ~/.mosaic/bin/mosaic-orchestrator-run --once
 ```