Skip to content

Commit 06c11c7

Browse files
committed
rebase(baton): single-commit rebuild on upstream main — payload unchanged
1 parent 1b72162 commit 06c11c7

37 files changed

Lines changed: 6903 additions & 13 deletions

‎assets/baton/icon.png‎

184 KB
Loading
Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
{
2+
"name": "baton",
3+
"version": "0.4.4",
4+
"description": "Deterministic ticket/DAG/subagent control plane over OpenSpec changes: a local Python CLI computes the task frontier and returns session actions; the main session dispatches each task packet to a subagent in an isolated git worktree, and only a sealed receipt with green verification counts as done. Bundles the baton skill and the CLI.",
5+
"description_i18n": {
6+
"en": "Deterministic ticket/DAG/subagent control plane over OpenSpec changes: a local Python CLI computes the task frontier and returns session actions; the main session dispatches each task packet to a subagent in an isolated git worktree, and only a sealed receipt with green verification counts as done. Bundles the baton skill and the CLI.",
7+
"zh-CN": "OpenSpec 变更的确定性 ticket/DAG/子代理控制面:本地 Python CLI 计算任务前沿并返回会话动作;主会话把任务包派发到隔离 git worktree 中的子代理,只有验证全绿的密封回执才算完成。内置 baton 技能与控制面 CLI。"
8+
},
9+
"author": {
10+
"name": "Lumos-789",
11+
"url": "https://github.com/Lumos-789"
12+
},
13+
"homepage": "https://github.com/Lumos-789/baton",
14+
"repository": "https://github.com/Lumos-789/baton",
15+
"license": "MIT",
16+
"keywords": [
17+
"openspec",
18+
"subagents",
19+
"ticket-dag",
20+
"workflow",
21+
"deterministic-scheduling"
22+
],
23+
"skills": "skills"
24+
}

‎external_plugins/baton/CHANGELOG.md‎

Lines changed: 340 additions & 0 deletions
Large diffs are not rendered by default.

‎external_plugins/baton/LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 Lumos-789
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎external_plugins/baton/README.md‎

Lines changed: 250 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,250 @@
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

Comments
 (0)