|
| 1 | +<p align="center"><img src="assets/baton/icon.png" width="88" height="88" alt="Baton icon"></p> |
| 2 | + |
| 3 | +<h1 align="center">Baton</h1> |
| 4 | + |
| 5 | +<p align="center"><a href="#regression"><img src="https://img.shields.io/badge/tests-pytest%20green-brightgreen" alt="Tests"></a> |
| 6 | +<a href="#"><img src="https://img.shields.io/badge/python-3.10%2B-blue" alt="Python"></a> |
| 7 | +<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-yellow" alt="License: MIT"></a> |
| 8 | +<a href="https://github.com/Lumos-789/baton"><img src="https://img.shields.io/github/stars/Lumos-789/baton?style=social" alt="Stars"></a></p> |
| 9 | + |
| 10 | +> The sole ticket / DAG / session-subagent control plane over OpenSpec changes. |
| 11 | +> A local CLI exposes deterministic session actions; the main session |
| 12 | +> delegates each assignment with the DSH `subagent` tool, binds the child id, |
| 13 | +> and reconciles the completion notice against a sealed receipt. |
| 14 | +
|
| 15 | +**[Discussions](https://github.com/Lumos-789/baton/discussions)** |
| 16 | + |
| 17 | +## The problem it solves |
| 18 | + |
| 19 | +OpenSpec is strong on spec-driven decomposition (proposal -> tasks -> archive) |
| 20 | +but does not execute. Baton turns an approved change into finished work, |
| 21 | +deterministically: the main session never decides ticket state itself. It |
| 22 | +forwards the deterministic `actions` returned by the Baton CLI to DSH |
| 23 | +subagents verbatim, then reconciles each completion notice against a **sealed |
| 24 | +receipt** (the assignment's verification commands run green in an isolated |
| 25 | +worktree). Free-text subagent output is ignored. |
| 26 | + |
| 27 | +A sealed receipt is hash-bound evidence produced locally by `receipt.py` |
| 28 | +(task-packet hash + clean, advanced HEAD + exit-0 verification results). The |
| 29 | +whole receipt body is covered by a canonical `sha256` digest (`receiptHash`), |
| 30 | +so an edited `exitCode`, `changed_files`, `commit_sha` or a lease claim from |
| 31 | +another ticket is rejected before any merge. It is integrity evidence, not a |
| 32 | +cryptographic proof against a hostile subagent (the digest has no secret). |
| 33 | + |
| 34 | +The change's tasks and the execution share the same granularity (one |
| 35 | +assignment ~ one task), and three seams are bridged deterministically: |
| 36 | + |
| 37 | +| Seam | Baton's answer | |
| 38 | +|---|---| |
| 39 | +| Dependency (section-order DAG -> what to run next) | `SessionController.actions()` computes the frontier fresh every call and atomically claims distinct tasks | |
| 40 | +| Concurrency (<=5 parallel tasks) | one isolated git worktree per assignment; integration serialized by a repository-scoped lock | |
| 41 | +| State (subagent done -> task resolved) | a sealed receipt is the only success evidence; the controller integrates the branch, finalizes the attempt, and flips the task's `[x]` in tasks.md | |
| 42 | + |
| 43 | +**Baton is the conductor. `SessionController` is the sole deterministic |
| 44 | +scheduler; the main session is a mechanical forwarder; OpenSpec is the plan |
| 45 | +face.** |
| 46 | + |
| 47 | +## Install (DSH) |
| 48 | + |
| 49 | +Baton is a DSH bundle: one package mounts the `baton` skill. Execution goes |
| 50 | +through the bundled Python CLI (`scripts/session_control.py`). It requires DSH |
| 51 | +`0.2.1-rc.2` or newer, a profile that provides the `subagent` tool (the shipped |
| 52 | +`dsh-base` does), and Python 3.10+ on `PATH`. |
| 53 | + |
| 54 | +```bash |
| 55 | +# From a checkout |
| 56 | +dsh plugin add /path/to/baton |
| 57 | + |
| 58 | +# Once published |
| 59 | +dsh plugin add dsh-openspec-baton |
| 60 | +``` |
| 61 | + |
| 62 | +Verify the bundle (self-contained, needs only `python3` + `git`; drives the |
| 63 | +real CLI against a temp git repo and exits 0 when healthy): |
| 64 | + |
| 65 | +```bash |
| 66 | +python3 tests/cli_smoke.py |
| 67 | +# CLI SMOKE PASS: actions dispatch, status snapshot, error exit - all green |
| 68 | +``` |
| 69 | + |
| 70 | +The package name is `dsh-openspec-baton` to avoid colliding with the unrelated |
| 71 | +`dsh-baton` plugin. The repository and brand remain `baton`. |
| 72 | + |
| 73 | +## Install (ZCode) |
| 74 | + |
| 75 | +The same repository also carries a ZCode plugin form |
| 76 | +(`.zcode-plugin/plugin.json`): it mounts the identical |
| 77 | +`skills/baton/SKILL.md`; the skill drives the same |
| 78 | +`python3 scripts/session_control.py` CLI. Python 3.10+ must be reachable as |
| 79 | +`python3`. |
| 80 | + |
| 81 | +## Quick start |
| 82 | + |
| 83 | +```bash |
| 84 | +# In your business project, write an OpenSpec change (the project's normal |
| 85 | +# openspec/AGENTS.md workflow) and get it approved: |
| 86 | +# openspec/changes/<change-id>/proposal.md + tasks.md (unchecked N.M tasks) |
| 87 | +``` |
| 88 | + |
| 89 | +`tasks.md` is the ticket source. Sections are phases, tasks carry `N.M` ids, |
| 90 | +and a task is blocked by every task in earlier sections (tasks within one |
| 91 | +section run in parallel). Minimal shape: |
| 92 | + |
| 93 | +```markdown |
| 94 | +# Tasks: add-login |
| 95 | + |
| 96 | +## 1. Backend |
| 97 | + |
| 98 | +- [x] 1.1 token endpoint |
| 99 | +- [ ] 1.2 session persistence |
| 100 | + |
| 101 | +## 2. Frontend |
| 102 | + |
| 103 | +- [ ] 2.1 login form |
| 104 | +``` |
| 105 | + |
| 106 | +`[x]` = resolved, `[ ]` = ready (no draft state); the exact parsing rules are |
| 107 | +in [docs/ticket-format.md](docs/ticket-format.md). |
| 108 | + |
| 109 | +Then ask the session: |
| 110 | + |
| 111 | +``` |
| 112 | +run baton on <project_path> <change-id> |
| 113 | +``` |
| 114 | + |
| 115 | +The skill drives `actions` -> `subagent` -> `bind` -> completion notice |
| 116 | +-> `reconcile` until the batch returns `complete`. |
| 117 | + |
| 118 | +## Architecture |
| 119 | + |
| 120 | +``` |
| 121 | +main session (mechanical forwarder - no model-driven state decisions) |
| 122 | + |- session_control.py <project> <change> actions --session-id ... --capacity<=5 |
| 123 | + | -> SessionController.actions(): recover/reconcile sealed receipts, |
| 124 | + | compute frontier, atomically claim, prepare isolated worktrees + |
| 125 | + | immutable Task Packets, return dispatch/recover/resolve_merge/ |
| 126 | + | wait/blocked/complete actions |
| 127 | + |- subagent(dispatch.prompt, cwd=dispatch.cwd) -> child id |
| 128 | + |- session_control.py <project> <change> bind <assignment_id> <claim_token> <agent_id> |
| 129 | + |- runtime sends the subagent completion notice |
| 130 | + |- session_control.py <project> <change> reconcile ... --agent-terminal ... |
| 131 | + -> sealed receipt -> succeeded + integrated; otherwise unknown + recover |
| 132 | +
|
| 133 | +SessionController (the sole deterministic scheduler) |
| 134 | + |- durable plan store (.dsh/baton/queue.db): revisions, attempts, leases, |
| 135 | + | sealed receipts, completion facts |
| 136 | + |- isolated assignment worktrees + a shared integration worktree |
| 137 | + |- serial git integration; merge conflicts preserved (never auto-aborted) |
| 138 | + `- latest-plan completion (all required tickets verified + integrated) |
| 139 | +``` |
| 140 | + |
| 141 | +## Capabilities |
| 142 | + |
| 143 | +**Session-subagent execution** (sole path): |
| 144 | +- **Deterministic scheduling** - claim, lease, worktree, receipt verification, |
| 145 | + integration, completion are all scripted; the model never decides state. |
| 146 | +- **Isolated worktrees** - one branch per assignment; capacity <= 5 sliding |
| 147 | + window; integration serialized by a repository-scoped lock. |
| 148 | +- **Sealed receipts** - `scripts/receipt.py verify` / `seal` is the only |
| 149 | + accepted success evidence; a completion notice without a receipt flips the |
| 150 | + attempt to `unknown`. |
| 151 | +- **Fixed 7200 s leases** - a claim's lease is hardcoded to 7200 s (2 h): there |
| 152 | + is no CLI flag and no renewal entry point. A lease that runs out is judged |
| 153 | + `lease-expired` (the attempt flips to `unknown` with that `failure_code`) and |
| 154 | + the ticket is re-dispatched by the next `actions` call. |
| 155 | +- **Operator escape hatches, both guarded** - `abandon <assignment_id>` retires |
| 156 | + a stuck attempt: it releases the lease and drops the attempt's eligibility |
| 157 | + for reconcile, while its worktree, branch, commits, packet and receipt stay |
| 158 | + on disk for audit. Abandoning an attempt that is plausibly still working |
| 159 | + (active, no failure evidence, no receipt, less than 80% of its lease spent) |
| 160 | + is refused with the judgment data unless `--force` - so a session taking |
| 161 | + over a run cannot silently destroy live work. `adopt <assignment_id>` is the |
| 162 | + reverse hatch: an abandoned attempt whose sealed receipt arrived late is |
| 163 | + re-verified and integrated instead of thrown away (a newer sealed successor |
| 164 | + refuses the adopt and lists both evidence sets for a human choice). |
| 165 | +- **Relay-safe judgments** - `status` shows per attempt a `relay` block: |
| 166 | + `elapsedSec` / `leaseRemainingSec` / `leaseElapsedFraction`, |
| 167 | + `receiptExists`, worktree liveness signals and a `suggestedAction` |
| 168 | + (`wait` / `reconcile` / `adopt` / ...). The dispatch prompt tells subagents |
| 169 | + to refresh a `progress` heartbeat in the run directory (outside the |
| 170 | + worktree, so it never dirties a seal), and `status` reports its age - |
| 171 | + "alive" is read from data, not guessed. |
| 172 | + |
| 173 | +**Control plane**: |
| 174 | +- **OpenSpec-native cognitive phase** - "use baton to finish X" means the |
| 175 | + session runs the project's OpenSpec workflow (align -> write the change -> |
| 176 | + user approves), then drives execution to `complete`. No self-built |
| 177 | + Grill/Brief/approval state machine. |
| 178 | +- **Live plan = edit tasks.md** - add tasks or sections at runtime; the next |
| 179 | + `actions()` call records a new plan revision and the frontier is recomputed. |
| 180 | + In-flight packets stay immutable. |
| 181 | +- **Verification is change-wide and persisted** - `--verify "<cmd>"` (top-level, |
| 182 | + repeatable) is persisted with the run on the first claim, so later packets - |
| 183 | + including ones prepared by `reconcile` - reuse it; passing it again is an |
| 184 | + explicit override. There is no per-task verification override. |
| 185 | + |
| 186 | +**Observability**: `scripts/ticket_board.py` produces a pure static HTML |
| 187 | +Kanban board over a project's OpenSpec changes (zero process, zero port, |
| 188 | +colored feature tags, open via `file://`): |
| 189 | + |
| 190 | +```bash |
| 191 | +python3 scripts/ticket_board.py build-all /path/to/project |
| 192 | +# → .dsh/baton/board-all.html (every change on one board) |
| 193 | +python3 scripts/ticket_board.py build /path/to/project <change-id> |
| 194 | +# → .dsh/baton/<change-id>/board.html |
| 195 | +# <change-id> is optional for build/scan when the project has exactly one |
| 196 | +# change — the common day-one case — and the omission fails loud (naming the |
| 197 | +# dir or the candidates) on zero or several. |
| 198 | +``` |
| 199 | + |
| 200 | +Clicking a card shows the copy-paste `check` / `uncheck` commands (runnable |
| 201 | +from any directory); a flip rewrites any built board in place — just reload |
| 202 | +the page. |
| 203 | + |
| 204 | +## Bundle contents |
| 205 | + |
| 206 | +| Path | Purpose | |
| 207 | +|---|---| |
| 208 | +| `index.js` | mounts the bundled `skills/` provider | |
| 209 | +| `cordis.patch.yml` | DSH bundle insert row (`dsh-openspec-baton`) | |
| 210 | +| `.zcode-plugin/plugin.json` | ZCode plugin manifest (same skill) | |
| 211 | +| `skills/baton/SKILL.md` | the `baton` skill (actions -> subagent -> reconcile) | |
| 212 | +| `scripts/session_control.py` | the control-plane CLI (`actions`/`bind`/`reconcile`/`status`/`cleanup`/`abandon`/`adopt`) | |
| 213 | +| `scripts/` | deterministic controller, plan store, receipts | |
| 214 | + |
| 215 | +## History |
| 216 | + |
| 217 | +Baton v1 drove an external `ralph.sh` loop. v2 brought the loop into Python. |
| 218 | +v3 replaced the subprocess model with subagents but still used a shared PRD + |
| 219 | +`passes` flags. v4 retired the PRD/passes protocol and made |
| 220 | +`SessionController` the sole deterministic scheduler. v5 adopted |
| 221 | +OpenSpec as the single plan face - the change's `tasks.md` is the ticket source |
| 222 | +(section-order DAG, `[x]` write-back), and the self-built cognitive/amendment |
| 223 | +engines are retired. **v6 (current)** drops the local MCP adapter: the CLI is |
| 224 | +the only control surface while the plugin is still iterating. |
| 225 | + |
| 226 | +## Requirements |
| 227 | + |
| 228 | +- **DSH** `0.2.1-rc.2` or newer, with `subagent` available (`dsh-base`) |
| 229 | +- **Python 3.10+** (`python3` on macOS/Linux, `python` on Windows) + pytest |
| 230 | +- A **git** target project (the controller prepares isolated worktrees) |
| 231 | +- The target project uses **OpenSpec** (`openspec/changes/<id>/tasks.md`) |
| 232 | + |
| 233 | +## Regression |
| 234 | + |
| 235 | +The standard regression entry - full pytest suite (incl. temp-git-fixture |
| 236 | +e2e), a live CLI smoke test, and a docs/file consistency |
| 237 | +check: |
| 238 | + |
| 239 | +```bash |
| 240 | +./tests/regression.sh |
| 241 | +``` |
| 242 | + |
| 243 | +## Documentation |
| 244 | + |
| 245 | +- [docs/architecture.md](docs/architecture.md) - why the deterministic control plane is the core IP |
| 246 | +- [docs/ticket-format.md](docs/ticket-format.md) - the OpenSpec change -> ticket mapping spec |
| 247 | + |
| 248 | +## License |
| 249 | + |
| 250 | +MIT |
0 commit comments