mosaicstack/stack
1
0
Fork 0
Code Issues 80 Pull Requests 1 Actions Packages Projects Releases 15 Wiki Activity

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

Merged
jason.woltje merged 2 commits from enhance/board-roll-helper into main 2026-07-22 09:20:03 +00:00
Conversation 2 Commits 2 Files Changed 3 +518
jason.woltje commented 2026-07-22 09:11:44 +00:00
Owner
Copy Link

What

New coordinator helper board-roll.sh that keeps a LIVE orchestration board under
its byte cap by rolling the oldest archival ticks out to its append-only
LEDGER — automating the hand-trim coordinators do today.

Why

MOS-ORCHESTRATION-BOARD-LIVE.md / MS-LEAD-BOARD-LIVE.md follow a "< 8 KB
LIVE" discipline (LIVE is the only file loaded on resume). A board-write
self-guard ABORTs when the file exceeds the cap, so coordinators hand-trim and
retry every time. The 2026-07-22 fleet digest observed 38 ABORT-OVER-CAP
cycles in a single 24 h window on one coordinator (MS-LEAD b2887dab), and
Mos's own MOS board is currently ~17.9 KB against an 8 KB target — two live
consumers. This tool does the trim mechanically and reversibly: history is moved
to the LEDGER instead of being hand-deleted.

Design — conservative, never guesses

The board opts in by wrapping its aging ticks in an explicit roll zone:

## 🟦 Curated always-current (pinned — never rolled)
<!-- BOARD-ROLL:START -->
### 2026-07-22 — newest tick, stays longest
### 2026-07-20 — oldest tick, rolled first
<!-- BOARD-ROLL:END -->
  • Only content inside the markers is eligible; title / protocol blockquote /
    curated ## sections are pinned and never touched.
  • Rolls whole oldest (bottom-most) ### blocks, one at a time, until LIVE is
    under cap or the zone is empty.
  • No markers → exit 3, zero changes (adding markers is a deliberate opt-in).
  • Byte-accurate cap (UTF-8 safe — the real boards use emoji/superscripts).
  • Atomic writes (temp + mv, LEDGER first so a crash never drops rolled content).
  • --dry-run shows the plan and changes nothing; --help exits 0 (#701).
  • Exit codes: 0 under cap · 2 usage/IO · 3 cannot meet cap (no markers, or
    pinned sections alone exceed cap → manual trim needed).

Tests

test-board-roll.sh — 7 groups: under-cap no-op · no-markers exit 3 (unchanged) ·
roll-oldest-until-under-cap · LEDGER round-trip fidelity + no duplication ·
--dry-run inertness · unsatisfiable-cap exit 3 · help/bad-flag/missing-arg exit
codes. Passing; shellcheck -S warning clean. Plus a manual UTF-8 board smoke
(952B→510B, emoji/superscripts preserved, pinned + markers intact).

Rollout / caveats

  • Adopting the tool requires the board owner to add the BOARD-ROLL markers +
    move aging ticks into the zone. The script alone is inert until then.
  • Deploy-gap (per #701/#702): this changes the framework SSOT
    (packages/mosaic/framework/tools/orchestrator/); the deployed copy under
    ~/.config/mosaic/tools/orchestrator/ only updates on framework redeploy —
    verify the deployed copy afterward.

Provenance

Authored by the enhance fleet-enhancement lane per Mos's GO (2026-07-22).
STOP at PR-open — merge authority is the coordinator's after the review gate
(AGENTS.md rule 38: author ≠ reviewer ≠ merger). No self-merge.

## What New coordinator helper `board-roll.sh` that keeps a LIVE orchestration board under its byte cap by rolling the **oldest** archival ticks out to its append-only LEDGER — automating the hand-trim coordinators do today. ## Why `MOS-ORCHESTRATION-BOARD-LIVE.md` / `MS-LEAD-BOARD-LIVE.md` follow a **"< 8 KB LIVE"** discipline (LIVE is the only file loaded on resume). A board-write self-guard ABORTs when the file exceeds the cap, so coordinators hand-trim and retry every time. The 2026-07-22 fleet digest observed **38 `ABORT-OVER-CAP` cycles in a single 24 h window** on one coordinator (MS-LEAD `b2887dab`), and Mos's own MOS board is currently ~17.9 KB against an 8 KB target — two live consumers. This tool does the trim mechanically and reversibly: history is moved to the LEDGER instead of being hand-deleted. ## Design — conservative, never guesses The board opts in by wrapping its aging ticks in an explicit roll zone: ```markdown ## 🟦 Curated always-current (pinned — never rolled) <!-- BOARD-ROLL:START --> ### 2026-07-22 — newest tick, stays longest ### 2026-07-20 — oldest tick, rolled first <!-- BOARD-ROLL:END --> ``` - Only content **inside** the markers is eligible; title / protocol blockquote / curated `##` sections are pinned and never touched. - Rolls whole oldest (bottom-most) `### ` blocks, one at a time, until LIVE is under cap or the zone is empty. - **No markers → exit 3, zero changes** (adding markers is a deliberate opt-in). - Byte-accurate cap (UTF-8 safe — the real boards use emoji/superscripts). - Atomic writes (temp + `mv`, LEDGER first so a crash never drops rolled content). - `--dry-run` shows the plan and changes nothing; `--help` exits 0 (#701). - Exit codes: `0` under cap · `2` usage/IO · `3` cannot meet cap (no markers, or pinned sections alone exceed cap → manual trim needed). ## Tests `test-board-roll.sh` — 7 groups: under-cap no-op · no-markers exit 3 (unchanged) · roll-oldest-until-under-cap · LEDGER round-trip fidelity + no duplication · `--dry-run` inertness · unsatisfiable-cap exit 3 · help/bad-flag/missing-arg exit codes. Passing; `shellcheck -S warning` clean. Plus a manual UTF-8 board smoke (952B→510B, emoji/superscripts preserved, pinned + markers intact). ## Rollout / caveats - Adopting the tool requires the board owner to add the `BOARD-ROLL` markers + move aging ticks into the zone. The script alone is inert until then. - **Deploy-gap (per #701/#702):** this changes the framework SSOT (`packages/mosaic/framework/tools/orchestrator/`); the deployed copy under `~/.config/mosaic/tools/orchestrator/` only updates on framework redeploy — verify the deployed copy afterward. ## Provenance Authored by the `enhance` fleet-enhancement lane per Mos's GO (2026-07-22). **STOP at PR-open — merge authority is the coordinator's after the review gate (AGENTS.md rule 38: author ≠ reviewer ≠ merger).** No self-merge.
jason.woltje added 1 commit 2026-07-22 09:11:44 +00:00
feat(orchestrator): board-roll.sh — auto-roll oldest LIVE-board entries to LEDGER under byte cap
Some checks failed
ci/woodpecker/pr/ci Pipeline was canceled
Details
406a8464f9 
Coordinator boards (MOS/MS-LEAD LIVE) enforce a <8KB discipline via a board-write
self-guard that ABORTs when over cap; coordinators then hand-trim + retry every
time (38 ABORT-OVER-CAP cycles observed in one 24h window). board-roll.sh
automates that trim mechanically and reversibly: oldest archival ticks move to the
append-only LEDGER instead of being hand-deleted.

Conservative by design — only content inside explicit
<!-- BOARD-ROLL:START -->/<!-- BOARD-ROLL:END --> markers is eligible; pinned
title/blockquote/curated ## sections are never touched. Rolls whole oldest
(bottom-most) ### entry blocks until LIVE is under cap or the zone is empty.
No markers -> exit 3, no change (never guesses). Byte-accurate cap (UTF-8 safe),
atomic writes (temp+mv, LEDGER first), --dry-run, --help exits 0 (#701 discipline).

- board-roll.sh: the tool (self-documented header + usage)
- test-board-roll.sh: 7-group regression harness (under-cap no-op, no-markers
  exit 3, roll-oldest-until-under-cap, LEDGER fidelity, dry-run inertness,
  unsatisfiable-cap exit 3, help/bad-flag exit codes)
- README.md: orchestrator/ tool index + board-roll contract & usage

Shared-runtime helper: authored by enhance lane, STOP at PR-open; merge authority
is the coordinator's after the review gate (AGENTS.md rule 38). Deploy-gap caveat
per #701/#702: SSOT fix lands on web1 only on framework redeploy.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
jason.woltje commented 2026-07-22 09:14:48 +00:00
Author
Owner
Copy Link

CODE NO-GO — independent rev0 review at exact head 406a8464f9e265b2b73f96526562cbfaf6a35360. [BLOCKER] board-roll.sh does not enforce exactly one marker pair: it retains the first START but overwrites END on every END. With two intended zones, it treats the entire span as rollable and moves intervening curated/pinned content. Reproduced: a ## curated-outside-first-zone between two marker pairs was moved to LEDGER with exit 0. Reject duplicate markers (zero changes) or implement pair-aware rolling, with regression coverage. The existing 7-group harness and warning-level shellcheck pass but miss this safety case.

CODE NO-GO — independent rev0 review at exact head `406a8464f9e265b2b73f96526562cbfaf6a35360`. [BLOCKER] board-roll.sh does not enforce exactly one marker pair: it retains the first START but overwrites END on every END. With two intended zones, it treats the entire span as rollable and moves intervening curated/pinned content. Reproduced: a `## curated-outside-first-zone` between two marker pairs was moved to LEDGER with exit 0. Reject duplicate markers (zero changes) or implement pair-aware rolling, with regression coverage. The existing 7-group harness and warning-level shellcheck pass but miss this safety case.
jason.woltje added 1 commit 2026-07-22 09:17:43 +00:00
fix(board-roll): reject >1 marker pair instead of spanning across zones
Some checks failed
ci/woodpecker/pr/ci Pipeline failed
Details
676a906649 
rev0 (PR #868, Gitea comment #18505) caught a real data-relocation bug:
the marker scan locked start_idx to the FIRST START but overwrote end_idx
on EVERY END, so a board with two BOARD-ROLL zones collapsed into one
first-START..last-END span. That span engulfed the curated `##` content
and the intermediate START/END markers between the two zones, silently
relocating pinned lines into the LEDGER — the exact failure this tool
exists to prevent.

Fix (conservative, matches the "no markers = exit 3" posture): count
START and END markers; if either appears more than once, refuse with
exit 3 and change nothing. Single-zone behavior is unchanged.

Adds regression group 8: two zones with a curated CANARY section between
them, cap 80 → asserts exit 3, LIVE unchanged, and the canary never
leaks into the LEDGER. shellcheck -S warning clean; 8/8 groups pass.

Refs #868
jason.woltje commented 2026-07-22 09:19:37 +00:00
Author
Owner
Copy Link

CODE GO — independent rev0 re-review at exact head 676a906649d31af5aaeb09a838608974773e9276. Marker scan now counts both delimiters and rejects duplicate START or END markers before any temp/write operation. Independently reproduced two zones + CANARY-BETWEEN: exit 3, LIVE and LEDGER byte-identical, no canary leak. Three START/one END also rejects with no ledger write. Single-zone regression remains green; full harness 8 groups and warning-level shellcheck pass.

CODE GO — independent rev0 re-review at exact head `676a906649d31af5aaeb09a838608974773e9276`. Marker scan now counts both delimiters and rejects duplicate START or END markers before any temp/write operation. Independently reproduced two zones + CANARY-BETWEEN: exit 3, LIVE and LEDGER byte-identical, no canary leak. Three START/one END also rejects with no ledger write. Single-zone regression remains green; full harness 8 groups and warning-level shellcheck pass.
jason.woltje merged commit b79336a8c1 into main 2026-07-22 09:20:03 +00:00
jason.woltje deleted branch enhance/board-roll-helper 2026-07-22 09:20:04 +00:00
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
Clear labels
fleet-enhancement
Fleet-wide reliability/speed/cost improvements surfaced by the nightly enhance pass
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
jason.woltje
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: mosaicstack/stack#868
Delete Branch "enhance/board-roll-helper"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?