feat(orchestrator): board-roll.sh — auto-roll LIVE board to LEDGER under byte cap (#868)

feat(orchestrator): board-roll.sh - auto-roll LIVE board to LEDGER under byte cap

Closes #868

packages/mosaic/framework/tools/orchestrator/README.md

@@ -0,0 +1,85 @@
+# orchestrator/ tools
+
+Helper scripts for r0 coordinator / orchestrator sessions — mission lifecycle,
+session health, continuation, and board maintenance. See
+`framework/guides/ORCHESTRATOR-PROTOCOL.md` for the surrounding process.
+
+| Script | Purpose |
+|--------|---------|
+| `mission-init.sh` | Initialize a new orchestration mission (manifest, scratchpad, TASKS.md). |
+| `mission-status.sh` | Show the mission progress dashboard. |
+| `session-run.sh` | Generate continuation context and launch the target runtime. |
+| `session-resume.sh` | Crash recovery for dead orchestrator sessions. |
+| `session-status.sh` | Check agent session health. |
+| `continue-prompt.sh` | Generate the continuation prompt for the next session. |
+| `board-roll.sh` | Keep a LIVE orchestration board under its byte cap by rolling the oldest entries to its LEDGER. |
+| `smoke-test.sh` | Behavior smoke checks for the coord continue/run workflows. |
+| `test-board-roll.sh` | Regression harness for `board-roll.sh`. |
+| `_lib.sh` | Shared functions sourced by the above (state files, TASKS.md parsing, locks). |
+
+## board-roll.sh
+
+Coordinator boards (`MOS-ORCHESTRATION-BOARD-LIVE.md`, `MS-LEAD-BOARD-LIVE.md`)
+follow a **"< 8 KB LIVE"** discipline: the LIVE board is the only file loaded on
+resume, so it must stay small, and history lives in an append-only LEDGER. When a
+board write would push LIVE over its cap, coordinators otherwise hand-trim and
+retry every time — an observed 38 ABORT-OVER-CAP cycles in one 24 h window.
+`board-roll.sh` automates that trim mechanically and reversibly: the audit trail
+is moved to the LEDGER instead of being hand-deleted.
+
+### Contract (conservative — it never guesses what is safe to move)
+
+The LIVE board opts in by wrapping its aging archival ticks in an explicit roll
+zone. Everything **outside** the markers (title, protocol blockquote, curated
+always-current `##` sections) is pinned and never touched:
+
+```markdown
+# MOS ORCHESTRATION BOARD — LIVE state
+> protocol blockquote … (pinned)
+
+## 🟦 Curated always-current section (pinned)
+…
+
+<!-- BOARD-ROLL:START -->
+### 2026-07-22 (mid²²) — newest tick, stays longest
+…
+### 2026-07-20 (dawn) — oldest tick, rolled first
+…
+<!-- BOARD-ROLL:END -->
+```
+
+Inside the zone, entries are delimited by a heading marker (default `### `) and
+are assumed **newest-first (top) → oldest-last (bottom)**. `board-roll.sh` moves
+whole oldest (bottom-most) entry blocks out of the zone and appends them verbatim
+to the LEDGER, one at a time, until LIVE is back under the cap or the zone is
+empty. If the board has no markers, it exits `3` and changes nothing — adding the
+markers is a deliberate opt-in by the board owner.
+
+### Usage
+
+```bash
+board-roll.sh --live <LIVE.md> --ledger <LEDGER.md> [options]
+
+  --live   <path>    LIVE board file (required)
+  --ledger <path>    append-only LEDGER file (required; created if absent)
+  --cap    <bytes>   size ceiling for LIVE (default 8192)
+  --marker <prefix>  entry-heading prefix inside the roll zone (default "### ")
+  --dry-run          report what would move; change nothing
+  -h, --help         show help and exit 0
+```
+
+Only **one** roll zone is supported. If a board carries more than one
+`BOARD-ROLL:START`/`END` pair, `board-roll.sh` refuses (exit `3`, zero changes)
+rather than span first-START..last-END and relocate the curated content between
+the zones — consolidate the ticks into a single zone instead.
+
+Exit codes: `0` LIVE under cap (already, or after rolling) — on `--dry-run`, a
+plan exists or nothing to do · `2` usage / argument / IO error · `3` cannot meet
+the cap (no markers, **more than one marker pair**, or the pinned sections alone
+exceed the cap and need a manual trim).
+
+Writes are atomic (temp file + `mv`, LEDGER first) so a failure never leaves a
+board half-written; line endings are normalized to LF on rewrite. `--dry-run`
+first is recommended when wiring it into a board update protocol.
+
+Run the regression suite with `bash test-board-roll.sh`.