From caaa0e6a466eefe6c55ade83cfffcdad001a2d12 Mon Sep 17 00:00:00 2001
From: Jason Woltje <jason.woltje@uscllc.com>
Date: Tue, 17 Feb 2026 13:31:29 -0600
Subject: [PATCH] add matrix orchestrator rail and repo scaffolding

---
 README.md                                     |  16 ++
 STANDARDS.md                                  |   1 +
 bin/mosaic-bootstrap-repo                     |   7 +
 bin/mosaic-doctor                             |   2 +
 bin/mosaic-orchestrator-run                   |  12 +
 rails/orchestrator-matrix/README.md           |  50 ++++
 rails/orchestrator-matrix/adapters/README.md  |  52 ++++
 .../mosaic_orchestrator.cpython-311.pyc       | Bin 0 -> 14282 bytes
 .../controller/mosaic_orchestrator.py         | 259 ++++++++++++++++++
 .../protocol/event.schema.json                |  64 +++++
 .../protocol/task.schema.json                 |  49 ++++
 templates/repo/.mosaic/README.md              |  16 ++
 .../repo/.mosaic/orchestrator/config.json     |  19 ++
 .../repo/.mosaic/orchestrator/logs/.gitkeep   |   1 +
 .../.mosaic/orchestrator/results/.gitkeep     |   1 +
 .../repo/.mosaic/orchestrator/state.json      |   4 +
 .../repo/.mosaic/orchestrator/tasks.json      |  16 ++
 17 files changed, 569 insertions(+)
 create mode 100755 bin/mosaic-orchestrator-run
 create mode 100644 rails/orchestrator-matrix/README.md
 create mode 100644 rails/orchestrator-matrix/adapters/README.md
 create mode 100644 rails/orchestrator-matrix/controller/__pycache__/mosaic_orchestrator.cpython-311.pyc
 create mode 100755 rails/orchestrator-matrix/controller/mosaic_orchestrator.py
 create mode 100644 rails/orchestrator-matrix/protocol/event.schema.json
 create mode 100644 rails/orchestrator-matrix/protocol/task.schema.json
 create mode 100644 templates/repo/.mosaic/orchestrator/config.json
 create mode 100644 templates/repo/.mosaic/orchestrator/logs/.gitkeep
 create mode 100644 templates/repo/.mosaic/orchestrator/results/.gitkeep
 create mode 100644 templates/repo/.mosaic/orchestrator/state.json
 create mode 100644 templates/repo/.mosaic/orchestrator/tasks.json

diff --git a/README.md b/README.md
index 6880c66..d8de5ca 100644
--- a/README.md
+++ b/README.md
@@ -127,6 +127,22 @@ Templates currently supported:
 - `typescript-nextjs`
 - `monorepo`
 
+## Matrix Orchestrator Rail
+
+Mosaic includes a runtime-agnostic orchestrator rail at:
+
+- `~/.mosaic/rails/orchestrator-matrix/`
+
+Run from a bootstrapped repo:
+
+```bash
+~/.mosaic/bin/mosaic-orchestrator-run --once
+~/.mosaic/bin/mosaic-orchestrator-run --poll-sec 10
+```
+
+The controller reads/writes repo-local state in `.mosaic/orchestrator/` and emits
+structured events to `.mosaic/orchestrator/events.ndjson` for Matrix bridge consumption.
+
 ## Bootstrap Any Repo (Slave Linkage)
 
 Attach any repository/workspace to the master layer:
diff --git a/STANDARDS.md b/STANDARDS.md
index d7a98c2..d0dfd79 100644
--- a/STANDARDS.md
+++ b/STANDARDS.md
@@ -21,6 +21,7 @@ Master/slave model:
 - Run validation checks before claiming completion.
 - Apply quality rails from `~/.mosaic/rails/` when relevant (review, QA, git workflow).
 - For project-level mechanical enforcement templates, use `~/.mosaic/rails/quality/` via `~/.mosaic/bin/mosaic-quality-apply`.
+- For runtime-agnostic delegation/orchestration, use `~/.mosaic/rails/orchestrator-matrix/` with repo-local `.mosaic/orchestrator/` state.
 - Avoid hardcoded secrets and token leakage in remotes/commits.
 - Do not perform destructive git/file actions without explicit instruction.
 
diff --git a/bin/mosaic-bootstrap-repo b/bin/mosaic-bootstrap-repo
index 71d09d5..1a4210d 100755
--- a/bin/mosaic-bootstrap-repo
+++ b/bin/mosaic-bootstrap-repo
@@ -37,6 +37,7 @@ if [[ ! -d "$TEMPLATE_ROOT" ]]; then
 fi
 
 mkdir -p "$TARGET_DIR/.mosaic" "$TARGET_DIR/scripts/agent"
+mkdir -p "$TARGET_DIR/.mosaic/orchestrator" "$TARGET_DIR/.mosaic/orchestrator/logs" "$TARGET_DIR/.mosaic/orchestrator/results"
 
 copy_file() {
   local src="$1"
@@ -54,6 +55,11 @@ copy_file() {
 copy_file "$TEMPLATE_ROOT/.mosaic/README.md" "$TARGET_DIR/.mosaic/README.md"
 copy_file "$TEMPLATE_ROOT/.mosaic/repo-hooks.sh" "$TARGET_DIR/.mosaic/repo-hooks.sh"
 copy_file "$TEMPLATE_ROOT/.mosaic/quality-rails.yml" "$TARGET_DIR/.mosaic/quality-rails.yml"
+copy_file "$TEMPLATE_ROOT/.mosaic/orchestrator/config.json" "$TARGET_DIR/.mosaic/orchestrator/config.json"
+copy_file "$TEMPLATE_ROOT/.mosaic/orchestrator/tasks.json" "$TARGET_DIR/.mosaic/orchestrator/tasks.json"
+copy_file "$TEMPLATE_ROOT/.mosaic/orchestrator/state.json" "$TARGET_DIR/.mosaic/orchestrator/state.json"
+copy_file "$TEMPLATE_ROOT/.mosaic/orchestrator/logs/.gitkeep" "$TARGET_DIR/.mosaic/orchestrator/logs/.gitkeep"
+copy_file "$TEMPLATE_ROOT/.mosaic/orchestrator/results/.gitkeep" "$TARGET_DIR/.mosaic/orchestrator/results/.gitkeep"
 
 for file in "$TEMPLATE_ROOT"/scripts/agent/*.sh; do
   base="$(basename "$file")"
@@ -97,6 +103,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"
 
 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 dea20c2..ffab18a 100755
--- a/bin/mosaic-doctor
+++ b/bin/mosaic-doctor
@@ -116,6 +116,7 @@ expect_file "$MOSAIC_HOME/STANDARDS.md"
 expect_dir "$MOSAIC_HOME/guides"
 expect_dir "$MOSAIC_HOME/rails"
 expect_dir "$MOSAIC_HOME/rails/quality"
+expect_dir "$MOSAIC_HOME/rails/orchestrator-matrix"
 expect_dir "$MOSAIC_HOME/profiles"
 expect_dir "$MOSAIC_HOME/templates/agent"
 expect_dir "$MOSAIC_HOME/skills"
@@ -124,6 +125,7 @@ expect_file "$MOSAIC_HOME/bin/mosaic-link-runtime-assets"
 expect_file "$MOSAIC_HOME/bin/mosaic-sync-skills"
 expect_file "$MOSAIC_HOME/bin/mosaic-quality-apply"
 expect_file "$MOSAIC_HOME/bin/mosaic-quality-verify"
+expect_file "$MOSAIC_HOME/bin/mosaic-orchestrator-run"
 
 # Claude runtime file checks (copied, non-symlink).
 for rf in CLAUDE.md settings.json hooks-config.json context7-integration.md; do
diff --git a/bin/mosaic-orchestrator-run b/bin/mosaic-orchestrator-run
new file mode 100755
index 0000000..9e934e0
--- /dev/null
+++ b/bin/mosaic-orchestrator-run
@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.mosaic}"
+CTRL="$MOSAIC_HOME/rails/orchestrator-matrix/controller/mosaic_orchestrator.py"
+
+if [[ ! -f "$CTRL" ]]; then
+  echo "[mosaic-orchestrator] missing controller: $CTRL" >&2
+  exit 1
+fi
+
+exec python3 "$CTRL" --repo "$(pwd)" "$@"
diff --git a/rails/orchestrator-matrix/README.md b/rails/orchestrator-matrix/README.md
new file mode 100644
index 0000000..1e9e4d6
--- /dev/null
+++ b/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.
diff --git a/rails/orchestrator-matrix/adapters/README.md b/rails/orchestrator-matrix/adapters/README.md
new file mode 100644
index 0000000..ad93ae8
--- /dev/null
+++ b/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.
diff --git a/rails/orchestrator-matrix/controller/__pycache__/mosaic_orchestrator.cpython-311.pyc b/rails/orchestrator-matrix/controller/__pycache__/mosaic_orchestrator.cpython-311.pyc
new file mode 100644
index 0000000000000000000000000000000000000000..b40171d301af4432dfec0ce94217953e2663ed75
GIT binary patch
literal 14282
zcmcgTZEPDycDv+~T$0N#eNnV!nT};iw5=~&wqw~&Vn<FaJCS{{@+HUN(cHC6nIe_l
zWn?kbRhI@RZ5Xf;_+aHu!LjWnr(AqJ0X?Ap(JPWe+WN;8*cBEqv4wC33jfGI1xbs*
zzxv)RMRIBB>T828S8rx#-h91z^X9!bqhESFE()H1_~K^b+;)ok5Bykr7$ZV|vkH-0
z6i<y(Jk48@^n_*9LSx*Tw2oRy$c)-ZXdktc&@t*DAv?;F&^hWPp=;DdLiebfgxn|x
zA(Qk>ct^cZXD{z~j~VsxeLM%DpWnm#APn$(`FaTJoD|>B@8dVWXB(~O_w!*$Yv2#?
zZ4fr{Px2iQHt`4f-4F)(0lpi;W+BA)T(;m?#Ci)QY=Xb$PvGk_Od`)GG<?CI@w^M;
zI!i?kWseRDvLH?*QVB^;#KUPZeo2sIF(#+Qa6Fxo#dI<$h~bOy`C?j%0g4=xE{Ay`
zDU8MBL^{>|71kJ`b$2Y4O3Nfo8isG{(bTkV7X>*ZrgSUR885X>0xLlHqrZ6<BDW~H
zDsQ~p%K{luRThbwaIqfpjF)DTqRb;L*w!$rLo;p8QlHYp5xZ{TWu4_?vLGiW1l^iS
zPw6a1v*{FkX5_f;Oh{><#Y9a0l==oMd>HGwl%5cJlIeIX8RLPFJ(3vjnIN?4x{yxG
zNX^L}F_uV5J=Nsxf=a~1m7WTfOQoXKSlyG;x&t~Ag@(mCXb}ITb^x=~iraJj(2b|B
zJ^j(1g+mKZtL|Nzd)GbpzGe45)qOy7A5fSBq90IoW-=yUddMM6CN6ZJflznw!o^r7
zDT_$Bcr~T%kU-|<4n%HIIjR8RqmP+}k|jr<Mcnf2RhIz%x7@aV0<C;jZfPGiW09+7
zXS_U@Ig5D?;}#xPCQq5m)6`jNJJm-?%#`Jd^>u2Brm5E{8h$+FM3`Zn79ZL&^2M$v
zKc#h6NX659A~hCabh~f`*j>_@^rVo|nQ<u%Fqw|=5vy1a-4+`G==4PidlU|b#Q=Ug
z5hIGoVi>-g;7|Gxz${gC`)(Y%cIfJn>qk~8+7>MOn)2SF({m$qEi|{c5X^^EXGC*G
zFtcUx2P?k%>(ldrtGVmBRV$>B<O=v2vA#u6Nn0=W-FM%umt0Acu-kvvaMWl0!p9t~
zcYM)A1JoJd@R-gF15>X*?XSTU;<S%LapT!=Qt8{4+DQQxC{OWPc?_Yx@&xnNETotx
zdB&2n6v~UZx+Kr=w%c}dJHR|v*<HaJN2VoDj?P(m$8Gi#XzjCdi!_z97949h)gkXR
z_XF8yJ!VU}*Jn29HCtWZT0B=Xz7kuyhDScN=#I&lD5QV|S;C6Z^yMtmEl*79^pw~P
zHHaYqUm+bqlG+m~9*`f>u832&8zpty#AQAq>h7t8d?_krE?!Jr(d|YkwqOlg0Ki;l
zpi<kEn2-hCAqtbpSX_uO2A6L`3@fxMZiSeHv<GHi<8~?bwqS7kUdX`Oq(1@xZfDr{
zPTgY~mzl<SesM%$8dYYG#_Um;Jw=!Io@>*xYtwxH!lA_`b#ssE>eXDmv(FZt+>PdI
z&2!rej(oG~?9`l{tCYpow0Lxd<*qyD+UDuPHid0d**1-BgGiBe-f&!V%rRFz*FAa9
zstu4y2?D;xvfm=8q^%btYh)cPJ7r`4>eRcZ<`|V})R;yXgz-u!U%v=+9dlWK?_!R5
z9lsCI0Cl(UHqKWRMW}8g9}m5JA}*f;`Mx_0d);}{VnS8}=A*y)FNl2qi;1`L%x&8v
zO9GcrndPD3@*_LTQEI#_b8|FL*DfsH@#xarXi1=)U4Ky!3Cs?Uh;7iWPRA-t4gAar
zDJdfg(U=rZB*dM75wVNAAP{#WAl%!FF~Y(&WMK&;b3Z2SLqOOS$64l9E;b3GoR5-;
z5f4EYZjsVI0YHZJX-v~Sre&FFDU2))Dol&Y9MqVD3UjdNY`EtPEjvT=+ZP>*69jdy
z=IliodSvNni3fke+;q+FTa*=lzv}PT{QXO^>OZ8ihc))F!X8E$PUOA;P<$Uj@m-Zh
z>RS(#WcbFYM27#i>u9(2i*DxV9>*8^Xn?wl3^XcFPr|ZBjVzkrVflmlm60G!XT&&U
zObC(`8xwSPLXcx9^&d8xSvH&tlWm|{FmgaM!nt!00nMyxKhIHe6?d(_cbl~WvuFj;
zY{^-xdC`oWV{*2feUeUq-o3z@xw|AjEyEEOgeERV7_xX6`Y0Yj@Du>uiP{=a0Yuu<
znD`8WqW~f{!W1Iz5;~K~0JUrg`-x5!aTv^HuC1mD35f&@hmWBUxP*y>Tw=Kskcr$Y
zodYmS{bwCz3l!P<2hE#58eBN};R_2dsLc_rIa1uzRt&Zln_5;v;SWO#A&B93b9mlc
zIJO#aI$f(2fUj+w&HgO~VATu^ea;b2PfWy8yl#z8@j9DKj}gK2&?jdmlft<~O5Pm?
zxpY2WHC+^n05Y*lu&;nfvivXicgy<w`vxM(3j1z#FQ5~~!`nAzgr8BoBS!&bKeCxw
zi0tEK0k&2bhGtfxDcMuW9WOID@8n%MYRoF5Zd7`5w7Cr#mq6(mFAGjnDlsS#1r58~
z?oWWPK11Fj&kQq0&De6xcv(N0wVb5hrK?j0sq?#M>^WPZs;#y1pexzUJtCuCmx_;K
zUhm2=g{rYvYBf`6#<AhdaDQ@UJUPeuGxKNaO%C2$@K$<PiREhM{GtWad0%NW5uXIa
z%65{qxXxwW=flsQe(}Yl!-E51vY+V8g_v|HYwb$LVdbBM5-1$`bVeqjAc{I83s+=u
z6J$N4&t=*3;p49jjSPf!XldQO2=xNpb}^ZeF6k~Qb74|U$3eX6wlio%lmyF}p)<#I
z``MAf(=U&Rr%AKM#-uY-v4jk!Mmmv-u;LJ8k#32n5XlM)7;H4CQTIR}Co^(1ekqf>
z3>Hc<0j4JdmWv>vmPw>fSpYf3Oe!i}5|T+V2APBKCw&0&8n-;|z0>!Y&@vM$v@JC#
zOh{$+Ys`Ly*<W-9Zfv=>Wlk!*n%|;2yEJFlDiyHpU8*m#?i<c)PNnYPM~)Aj3mAcS
zam)w-s_cNq4k+wE3G=G^x;yV)@r5+s)}p6=?&bOC6|QZ?UqAQk`|M42rGCrJrvYg7
zZN)%iv9V><<M6w_rT~14AkVD&skZjKrw9hoJBqK}c#93qH&1~w=LGu)Kz^{uh3;|T
zWiDK3P`P%EYgf4TBImm?bZuykzk2%m={)?PjvLe0rmwzp{hd5h9!cL%#@<idOel4I
z@GdqOAwZSgqp^DwcF*c|7&;k00be5}zC}<;TQ5fT?RBu)D9%4ucPscoaDIy#=+FWk
zin~K$I*3~N+h_L=?zeuqpBWr*e0hWh2<`=80(5dv&KcarVFSax{9+<0tS`D-V0JgQ
z$a%VYf6mbx2x<#oV~LxEjd|ZK08>5s@XTYiWcwakvYT3}@eG*z3Sz=BoOQlaQix`B
z3#bTZq4!zNNRtzCQkc<gB+R;vM5Oi%=$CzfXsl!Fm>@&K1x$z|-~pJO0YNa|ctMPo
zHsa{oJc<cGMIAuG-F23_&-(AN&C6`_{N|72i*3K@{8i^t|D8H@=V5K<VYU5;)_z1~
zpVHW;{^;~y3(mEETwfUZ<!gWQ+Tz%fsO}ihb_}T74r$vCsm{Zi^RR)m<zs7M=&!xM
z@T$%p&Dpc+U~G0nFR<arrH2hkaBrM5t9s|-z&hmzcTl1WyZ{koDA<p}Gc>SF8KpXc
z?i(|yc}vON$mHlaI7-h_*S8U+-#TolVh+^D(cMCem!PVMMMQ!Sa!P2|t|?L8$wd5e
zGzG#qik%lzkcTvvP^$w$=5Iv1u9*N>*x+e-^4gPgC*~8XyHj&_E)IdWOL6Zj)(7*a
z@V9EExc&FtzI?wy5+@kF>8J>fIGshuS`@8jJ2>4gCP3zbgDz=WX}BE|!i>Pi4}<{=
zDGS^9j1^)Q5`zJQ`vTK!5MxNp4lx^vIZXPpmA8*k3EE7$88*ijswV@QG#<pR!F5(^
z**T|NRx&{00Wwy+X_Bvc)8-xKHT^DK?JUXFxIAWDIhSPN*|R34Dd*atm!LwK+cvi~
z<L2Et7tf(KE&JBSR;!=^hKFEOD`G&eoU@i*pvqNIE5{Hu!@E$!kTYD)o#S}l|IjMO
z`yXkQ$#LfKK#S-GEIm0JAIQO&_&UDctmr+0*Ff+Z`KDUDoIU3Tr78H4!9yP4mu8X@
z`pDoVuSp^G=4vQxR%bVynN9p=^GM7yQz)ygYh%N(MlJN^e9{}$$}{*Bs_0)S$u}ly
zcyI%}mhYig{+wS7$iYhMIe*TT^O~J}GuZbuzvZ#GuNC=#-wL?lM>t|5J~VU1Hkj=#
zd>z(+?mFYCoq3-6{<xBV0#<0HDJtj7Q8|y925*2=m<i0(<pTWn%OJ@>=3f7^DAJY-
z{EYg@@_(jF<NqIBOl!wcT32MH;S2#Kb}ZCrJm5_LT5h<G+Rf``vT4ILP>V@}=~vG`
zG1CBHW3C>y)xVu-GOea2bKQ@%CWE=4L|<>OkxCsz+H~@fTo7lhmh()U65N1Ont@ZA
zfm3ix2D7TBg`K4qcCFt+s)c7~8fwbyCaa>8@5(iU#Oo#{ncBYP8rL^bb3y1$56E_q
zIF-{%n!5grT!Xla?**RvpZAqMvYyRrbr1Ba7bN)J+McBL{aLG{zq~HY^*@#@F!AXI
zGUoe~7pC@V)&)|sB1$$~34P|7*buL^2CtFdw@~AsHr8BZ|8Ukt)YNV~O3S*?X(<?S
z5Ao|s-6?+UNN!BRQws@>DJ7ymX7^Nzh9@$TOb)4IiB$NV4wBO`5I)!4-F<!r{a=|l
z96k%ri5G#lvm6-IaFCknLOiH7lS+YlYACDN2~igKXiSb+bYCftD5U6Eb!8^;R2Z|x
zE4WUku|f}4)E$$g#8^rIq{=~V)-wWG;kB$RM=(om==Q0!cv%p$&99O$EL;)d89Yjd
zE|XrsQ4lx;vP7Bh%GwBR441)KXjk{w+8nz5BAhNm7o0{2-OTPEP8%onC1g0+4;$?Q
z#fa~)Y_cE;K^X>0@!fE=A&O}+>n1%msv8keIAnK}y1Q1Pkr~GGCm2EkXMz{PU^Z2`
zV=)~}Bwo-xZ)IZ1gghOETLXfWt;6&1Zn$d@zudhxYOaLRg(z9?OU49+@oONQ4OEqw
z1j-70*7H1Mg^iCI45M=;j8acKv)0H!7z`2OeVIj4I$<#2FomhrxpEZA=OyDWCuO~4
zLMz|l(<uQ-I*}HIaH-#<r&8Ex4cty;I*5M>ZHYg^200u}w8YU7uNcN0w2yRGLQ157
z6sb7)0?>ZbU9ZHF8R0n22eFEXZA$#r;$AF<E@#~aY@V1TRwwZRiLXOyBqXL0V-mqz
zh-R!f<Mhf{aU@RM-o$?_5xdA;>KT5J^=1@|!s+1zTx-DUa8%eTjDt9@h;0mh=n0<K
z%eqC3>vUAN;Xozb6-y?eC7dqtJuJy!y3P_ZKpEX(5F{?4EL!t!JrWxJc3hWHpwd`U
zFl@zJPzJ3^>E~e2f~^<`&A*@qI%iK-#p*WAN7cIBv!{x_;C#F43(uY?LfY$UUHj~*
z2VCRac;Ud}u|k*1^=e%2?D1lt=~n22(ENeIF~fl~dve7MSRc2k?heh}fu}g9=@oCY
z5_(bf4r|_Fg&lt24$bdW-8(e*j@d!5Q4y)J=xfMl9(V(DZMQl<=$!8_w5oNzT3xT|
z?bEz{v(FbBTW1IJ%|9M49R<J#oJ%#WFrNH4G=Ear)T1)J8q=#Vy`-Z{{M|O?iPP|^
z+!>8K1D)O4K6_koZC06<l}+0|j4VWEkLP!*Owg!ghsuOCCaf^w2aGrW&iv`cSC<l>
zx7_^;m5FLhRAHhkBz<`C`K8xCXO)w@$_N@GD2#9)sP(F{X{Yh3zMVief3vc=uW$f>
z@v8p5*&%ExG2fsvts2v+Fs%<<o;-i!(zQ!-(}gEg?+(qoLv^)luJ(Jb-OH}ss;gUb
zb;EhE+q+6xZO7@A`lh+JZ)HEo7CIM?slgsC*mEzqcR9FM>3{C7MGc<Pf~VB_7qt2p
z?$y7vT>p|<Kcdx-<k_OT9;obu3hE+@olApvB5K{BRyUY`_C8kav^5k%+wx5QwX5Eh
zmhB%7EeyfOIh73+o6kV()vKNrHZZqyernOBwC+{eevR!{*!~r^ZthUQvp98!{d~7_
zW<+`U4eiW%m3>oV-&EK)i`zT$HpRPDWy342J3dS-B=WX=Qe`(Al?j#OYhQg{##xKc
zA1qu_xgL${`SJ1DV|lvhaOQvT?$qqmhW#7-+@drO!uy#0?7Tau{NS}eyr{CH8at}6
zqmSK7?DZ~~(Qu#fs&##Lrj(aPmBeLbZxUXWozU0`g`EKRYF@t2`EQ)Kc4987ayv9`
zhr*p)Z2HZnUu{}Ctwsj5$RH%#wcrwJge4f+HTweb-qhKK=v4|~p269c-#>Ws;H{@W
zcv`J*1J^K2r7wt6*;wQn2>F$8|I*l<>AT&^Xhyj#Aso%9?Asdqw!*%>(%3qGWihmL
zLTx;vH6FR@$~)!)MR(m??Aqb{;T5iF?j5D=z@6adk-Kjy=ckm348rqMDtATWt|;Wa
zA8O5?1k|E`bJ4%O=nn#K7yYe8|NeqQ@$ZLs@q`h6?QwX#;H~xmPa*JA&c=J}=4E#C
zA`7Hyc^+PsJ)yBD6!PA81Xd~57Nv`!wi5SkZU1n3VH!T(RN0o&0DG4@?i{+yDX&~q
z*)feBQ^<RNBaR(d<AguSoDbHM9L25MA5TQULWTp&`JmF&VZ18aaUYK=H_bnJGgWK}
z|NO*HPZZu%Tl%$@{$gm$&zpbRT-c?Cy0uVuv88j>ZO5}q0AJgjcy<W@m!W;N0es?X
z-Z(29P2x6Ee#-YGh8gs?ReO3W_W<FRLXAZ*gE!5H%~GzZ6ydFM`LGXm2dLF}%w7(1
zdjhOu(*>c8YP9nXp1tif+u3j=w-LTeuJW^h--x^I`2_m$S-CHyY?UW(t&flRV(4oB
z**G2mktau2jwQ`{_hVU;a7%>uqPLRw5uYU-(ei#0W8mlz(jR@y)RV&1wk3GS7_>iS
zJWMM+<K=_B+jVA-6j%ZE;Kjfz9Hl46)cTRYvuZ2&*Yc}FzJYHv*Cz!`eW|gop|v2`
z`Sf_%%P6+VJ1RBeeFQjeG;snP%i6)4S}~3&zS&G=qgE3}C}#m{cN4T!whQ5V^P|Vt
zPB@2utR8g8kxD<u@kSzf<gT?C%wK(VduF=S_Bb`QoszpNW!vDUFnATKN4cf8%<F`D
za<8e>=^2NqR4X0_KmP20zoUX4QZtSpIZ~_<PSI18aToOZZzEfWv%5=|mifoI<qTJo
z+;Gks2Zb8Vv8=tT3l9&ntuFzT5^yDYI*bPi;m*?4*?}-zzleZELGFt(a1c9*h0>_Q
zgO&}pK@^NoAsabk92SRTGFS{?w8GWPaOr%+u+rcz2Qi|+`n1R5*t+;LpnBHT)int>
zu)8E7{uK(9Y}*<51Qj?8f>aRSjwQ*}Y&1O+sZ2T}LH)cCvBGg8Tn!@qGAeR(8&{Hb
zuKIRy)@|5+hWXuou5@j=8s&U=A^|2Yv}mA$1x4!&o|%1xUSZuKq+%Dq_<Sz=()z{u
zghUXa$Kg^ZO!uJi0yLPPqzmEBQf)^r#*&f{F)Ysw`jtwXXeebjz)PmnlZI&>#_2qg
zwTF?WM|4^m$!>M6-)oq?$w?S>cFX$t#7qWSgmgA0j=`NwNzlDV#j(r;+)O%ypQ6si
zcyJk%(sWB2Zf3#3BCw1&kCbzfQiuRfj?&d^ogsI#8SE(We58|a3*u%(w}F+HlHn%(
zv?QK^geu#SL5>sA8q!%DS`^p?H~=rP+oYr*OzPH&*cCl+N|?Toj*0vb@{X99ly&Fv
zD{+BvJ6x;6tEJd)2D?<TAoUWH7#1TjC!M9+4`4T2g)8xOt|l-O;FJ-62VMGi_>*3T
zy&5j8dm1%Qo6;9mJU>)DKh!)woPDmyxb88*WhOY!{`!gAkxzHs-lZIVLt%m{b6#W4
zE6n*SjKvn^@EFOvq%oHi=29h(`}N*C7Uifp*B!X$ZdrD>sP0zH4c68JfAA(ZKeF(;
z>hI9}9rye_%l;lPV>Gm6ioWLggQ~Bs@FUf?&#)5Dt93iUa&$M{b8lI8Z&BS_HTPCL
ziVUo<9>qJj^bP=c|84Id;9A5hD*KAYz5<b=&!2zmfd^Dkup&Jjnx_K>>JHo(xHd4C
zC^W8Fl56!`P}#V~#uYYB3f_0P-<w{g7-*$odtqqt%AF>);Tf&rnY<JFh^jKExdEka
zK;;f;+#!WKWVFXP71zkpK>+Z6KKSK}Mhu|JysR-VE6mHQ7MHDi)#7w^uQYcoI+vcj
z^NQL$sDY_5RIJDQ=AJz({)U^bkM_>LRcQM~m%6!E+uUnVNb&c5_uYywjJGoIP__g}
zSNc_MpT_M|I5>!HnCqMCTfvT6oZS^b@D40(SLzPH`@8r*jw{@d$_;7U5JXlu|MinU
zk>>m6`GpBJxLXVER=F;X>rx(h;qJwEa2?p$jbQ-BBcU?!&;0|>^-%xP6FRZo`mb&$
z!iJ-^6Rp;}tv2}3*=Q75G8zSOji=wln*#Svak~~95TFnz{|sT|qqb(s-)7E#!pJAL
zQb~DoHFZBCk@_)TM3pV#H*OaaBy>$1jvV41LM4#6AdNI~X_2HoQ^q@rv116z)vnzj
zBA6#Ji`0Fp93z-`v=5jUFqL2u{|)INZ^p!2xD<}A6!9_wQXboc^2C!w>L>0b5<?*%
zR)#7fW{IpQ+9I2EM>NW(<I$+@ibgMH&<z`nilAmu;>QSZFB9Q}-MHf`E@JF61TQ04
zLh$zpo&%uUVJ`zwY|IVb!!ktQUW^?=fSxeJ`<1{LULhdTkjNjL`BZEI+SgrYrzP-Y
z9S5(ZhzHZ;h5+#`J!B8V#+gY9Pl;bb2JURqRe*4}m!|Ji&nwjP_o*io^LwB2&5~b{
zYE;(VBITYXzar(FCBGu&oh82_6;RgRBITMTzbgE4!6t<=y{mSbei9a^39t+e3)T$0
zb{a0kn?aqGhU>*<u!-u}wd!l6!9rUH^fu6NIo}MrZHR0JeunmA52}GTMdSA)@Pf6C
y24P?Z!!*Tk`RuYaq*y~mS3`d1+{oO>`>))5MRm1kt`@kc4c9rCO^{2b>c0VC39|G6

literal 0
HcmV?d00001

diff --git a/rails/orchestrator-matrix/controller/mosaic_orchestrator.py b/rails/orchestrator-matrix/controller/mosaic_orchestrator.py
new file mode 100755
index 0000000..7843a19
--- /dev/null
+++ b/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())
diff --git a/rails/orchestrator-matrix/protocol/event.schema.json b/rails/orchestrator-matrix/protocol/event.schema.json
new file mode 100644
index 0000000..1d4d1d2
--- /dev/null
+++ b/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
+}
diff --git a/rails/orchestrator-matrix/protocol/task.schema.json b/rails/orchestrator-matrix/protocol/task.schema.json
new file mode 100644
index 0000000..af97a29
--- /dev/null
+++ b/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
+}
diff --git a/templates/repo/.mosaic/README.md b/templates/repo/.mosaic/README.md
index 44f88bf..f61cf37 100644
--- a/templates/repo/.mosaic/README.md
+++ b/templates/repo/.mosaic/README.md
@@ -29,3 +29,19 @@ Verify enforcement:
 ```bash
 ~/.mosaic/bin/mosaic-quality-verify --target .
 ```
+
+## Optional Matrix Orchestrator Rail
+
+Repo-local orchestrator state lives in `.mosaic/orchestrator/`.
+
+Run one cycle:
+
+```bash
+~/.mosaic/bin/mosaic-orchestrator-run --once
+```
+
+Run continuously:
+
+```bash
+~/.mosaic/bin/mosaic-orchestrator-run --poll-sec 10
+```
diff --git a/templates/repo/.mosaic/orchestrator/config.json b/templates/repo/.mosaic/orchestrator/config.json
new file mode 100644
index 0000000..8ede0fb
--- /dev/null
+++ b/templates/repo/.mosaic/orchestrator/config.json
@@ -0,0 +1,19 @@
+{
+  "enabled": false,
+  "transport": "matrix",
+  "matrix": {
+    "control_room_id": "",
+    "workspace_id": "",
+    "homeserver_url": ""
+  },
+  "worker": {
+    "runtime": "codex",
+    "command_template": "",
+    "timeout_seconds": 7200
+  },
+  "quality_gates": [
+    "pnpm lint",
+    "pnpm typecheck",
+    "pnpm test"
+  ]
+}
diff --git a/templates/repo/.mosaic/orchestrator/logs/.gitkeep b/templates/repo/.mosaic/orchestrator/logs/.gitkeep
new file mode 100644
index 0000000..8b13789
--- /dev/null
+++ b/templates/repo/.mosaic/orchestrator/logs/.gitkeep
@@ -0,0 +1 @@
+
diff --git a/templates/repo/.mosaic/orchestrator/results/.gitkeep b/templates/repo/.mosaic/orchestrator/results/.gitkeep
new file mode 100644
index 0000000..8b13789
--- /dev/null
+++ b/templates/repo/.mosaic/orchestrator/results/.gitkeep
@@ -0,0 +1 @@
+
diff --git a/templates/repo/.mosaic/orchestrator/state.json b/templates/repo/.mosaic/orchestrator/state.json
new file mode 100644
index 0000000..a225315
--- /dev/null
+++ b/templates/repo/.mosaic/orchestrator/state.json
@@ -0,0 +1,4 @@
+{
+  "running_task_id": null,
+  "updated_at": null
+}
diff --git a/templates/repo/.mosaic/orchestrator/tasks.json b/templates/repo/.mosaic/orchestrator/tasks.json
new file mode 100644
index 0000000..561ea0a
--- /dev/null
+++ b/templates/repo/.mosaic/orchestrator/tasks.json
@@ -0,0 +1,16 @@
+{
+  "tasks": [
+    {
+      "id": "EXAMPLE-001",
+      "title": "Example orchestrator task",
+      "description": "Replace this with a real task and command",
+      "status": "pending",
+      "runtime": "codex",
+      "command": "",
+      "quality_gates": [],
+      "metadata": {
+        "source": "bootstrap-template"
+      }
+    }
+  ]
+}