dos-dispatch
dos-dispatch is a concurrency-safe workflow that chains snapshot, lease acquisition, gating, and shipping operations into a single command for dispatching work on a single lane. Use it when you need to plan and execute the next batch within a lane while preventing parallel dispatches from colliding through kernel-managed lane admission, with all paths and lane taxonomy sourced dynamically from dos.toml rather than hardcoded values.
git clone --depth 1 https://github.com/anthony-chaudhary/dos-kernel /tmp/dos-dispatch && cp -r /tmp/dos-dispatch/src/dos/skills/dos-dispatch ~/.claude/skills/dos-dispatchSKILL.md
# dos-dispatch — the generic chained snapshot→ship cycle
> **The concurrency-safe dispatch.** It chains `/dos-next-up` (the packet) to a
> ship, but first takes a **lane lease** through the admission kernel so several
> dispatches on disjoint lanes run in parallel without editing the same files.
> The "may I run on this lane" decision is the kernel's (`dos arbitrate`), not
> inline prose. Every path/lane comes from `dos doctor --json`; nothing is
> hardcoded.
The shape: **discover → take a lane → snapshot → gate → ship → archive.** The
lane taxonomy and the run-dir location are data (`[lanes]`, `[paths]`); the
admission and the gate verdict are kernel syscalls.
## Inputs
- `--lane <name>` (optional) — the lane to dispatch on (a name from the active
`[lanes]`). Omitted = a bare auto-pick: the arbiter picks a free lane from the
`autopick` ladder.
- `--leases <json>` (optional) — the live leases other dispatches hold, as a JSON
list of `{lane, lane_kind, tree}` (the arbiter keys exclusivity on `lane_kind`,
so include it — `cluster`/`keyword`/`global`). In a real loop these come from a
status query; for a single dispatch this is usually `[]`.
## Step 0 — Discover the layout + the lane taxonomy
```bash
dos doctor --workspace . --json
```
Read `lanes` (the taxonomy), `paths.next_packets` (packet output), and
`paths.runs` (the run dir to archive under). **Use these; never hardcode a lane
name or a run path.**
## Step 1 — Take a lane lease (the admission kernel)
Ask the kernel whether this dispatch may run on the requested lane, given the
live leases. The arbiter runs the tree-disjointness algebra over the lanes'
declared trees — two dispatches on disjoint trees both ADMIT; overlapping trees
COLLIDE.
```bash
dos arbitrate --workspace . --lane <LANE> --kind cluster --leases '<LIVE_LEASES>'
```
Read the `LaneDecision` JSON: `{outcome, lane, tree, reason, free_clusters, …}`.
- `outcome: "acquire"` → admitted. `lane` is the lane to run on (may differ from
the request when auto-pick reassigned it); `tree` is its file tree. Proceed.
- `outcome: "refuse"` → not admitted. `reason` explains why; `free_clusters`
lists lanes you could pick instead. **Stop** (or retry on a free lane). Do not
force — `--force` is an operator-only override, not an automation default.
The exit code mirrors the outcome (0 = acquire, 1 = refuse), so the screenplay
can branch on it directly.
## Step 2 — Snapshot the portfolio (the packet)
Run `/dos-next-up` scoped to the acquired lane:
```
/dos-next-up --scope <LANE>
```
It writes a packet under `paths.next_packets` and returns its path + a gate
verdict. Capture the packet path and its `.dispositions-<tag>.json` sidecar.
## Step 3 — Gate the empty case (typed verdict)
Before shipping, classify the packet so an empty packet doesn't launch a no-op
ship:
```bash
dos gate --workspace . <paths.next_packets>/.dispositions-<tag>.json
```
Branch on the exit code (the verdict IS the code):
- `0` **LIVE** → there is dispatchable work; proceed to Step 4 (ship).
- `3` **DRAIN** → empty backlog; **skip the ship**, archive a no-op, report drained.
- `4` **STALE-STAMP** → shipped-but-unstamped drift; skip the ship, surface the
drift for reconciliation (a `/dos-replan` can stamp it).
- `5` **BLOCKED** → picks blocked; skip, surface.
- `6` **RACE** → lost a render race; retry the snapshot once.
## Step 4 — Ship the packet (LIVE only)
Launch the packet's dispatch list (the per-pick prompts `/dos-next-up` rendered).
How you ship is host-shaped — the generic baseline launches each pick's prompt as
its own agent. Record what shipped.
## Step 5 — Archive the run
Write a run record under `paths.runs` (the run dir from `dos doctor --json`): the
lane, the packet path, the gate verdict, and what shipped. Commit it with a
generic subject — **read your trunk and ship-grammar from config; do not hardcode
a commit prefix.** (`dos doctor --json`'s `stamp` names the active grammar.)
## Step 6 — Release the lane lease
If you took a cross-process `dos lease` for the archive, release it:
```bash
dos lease --workspace . release <owner>
```
The lane lease itself is advisory state in `live_leases`; a real loop
(`/dos-dispatch-loop`) threads it forward. A single dispatch simply finishes.
## Out-of-scope findings — file an issue, don't widen the lane
Shipping on one lane surfaces work that belongs to another: a bug in a
different tree, a missing test, a doc that drifted from the code. Do not absorb
it into this run's commits — the lease covers ONE lane's tree, and a widened
diff is exactly the collision the admission kernel exists to prevent. Do not
let it evaporate either. If the workspace has a public issue tracker (on a
GitHub-hosted repo, the `gh` CLI), capture it there, then return to the leased
lane:
1. **Dedupe first.** Search before filing — `gh issue list --search
"<keywords>"` — and comment on the existing issue rather than opening a twin.
2. **File it as a claim.** The body carries a checkable **done-condition** (the
command or observable that would witness it resolved), a lane guess, and
where you found it. No done-condition yet = not an issue yet — it is
design-shaped work for the workspace's planning surface.
3. **Leak-check the drafted body BEFORE posting.** Issue text is public output
that leaves through a door no tracked-file publication gate scans. Never
include a machine-absolute path, a hostname, or a personal identifier; write
paths workspace-relative. If the workspace ships a publication leak-scanner,
pipe the draft through it first (write the body to a file outside the repo,
scan it, post with `--body-file`); a hit is a refusal, not a warning.
4. **Close only by ancestry, never by narration.** The honest close is
`Fixes #N` in the commit BODY of the change that resolves it — the platform
closes the issue when that commit lands on the trunk, an ancestry check the
claimant didn't author (the same witness `dos veAdjudicate a GitHub issue's "this is resolved" claim from witnesses the claimant didn't author — then close it carrying the evidence, or refuse with the typed gap. Use when an issue looks already-solved, after landing a fix that should have closed one, or to sweep open issues for silently-resolved ones.
Pick the next most important open GitHub issue this agent can actually complete, make its done-condition true, land it with witnesses (suite + parity + commit-audit), and priority-tag every issue touched along the way. Use when asked to "work the backlog", "complete the next most important issue", or to fix a specific issue number end-to-end.
Cut a versioned release of the DOS kernel — bump the version, draft release notes, commit, tag, push to master, and create a GitHub release. The tag push triggers the gated PyPI publish pipeline (publish.yml); the skill surfaces the run and its approval gate.
Promote an already-shipped rolling release (vX.Y.Z) of the DOS kernel to a named stable channel — gated on a green kernel suite + a green third-party CI run on the candidate + a clean truth syscall + a soak window. Writes an evidence file and adds a stable/<codename> git tag on the same commit. Does NOT bump versions or build new artifacts.
One automatic plan-class lifecycle tick. Reads the DECLARED class set + transition list from the workspace `[lifecycle]` table (not a hardcoded taxonomy), evaluates each trigger, spawns a read-only JUDGE-rung adjudicator (the `dos.judges` seam — advisory, fail-to-abstain) to approve/defer each candidate transition, applies the gated transitions as plan-meta edits + one commit per cycle, and logs to the run archive. Failsafes (per-cycle cap, per-plan cooldown, a veto class) are `[lifecycle]` data; the judge content is a host `dos.judges` driver. Every path/class comes from `dos doctor --json`. Use to garden a plan portfolio's lifecycle automatically, judge-gated. The DOS lifecycle gardener (SKP Axis 5, docs/207 Phase 5c).
Run /dos-dispatch on a recurring cadence, alternating with /dos-replan when the backlog drains — the dispatch→replan→dispatch cycle. The continue/stop/next-mode decision is the kernel's typed loop decision, not inline prose: each iteration is classified (`dos gate`) into a verdict and the loop's counters (drained-twice, the unclear/dirty-zero breakers, the iteration cap) drive the next step. Several loops on disjoint lanes run concurrently, each taking its own lane lease via `dos arbitrate`. Driven entirely by `dos` verbs + the workspace's `dos.toml`. The DOS reference loop workflow (SKP Axis 5).
Ground a "keep working until the goal is met" stop condition in a witness the agent did not author, instead of letting the agent self-certify "done". A harness goal/Stop-hook condition is normally checked by the model re-reading its OWN work — consistency, not grounding. This skill turns the operator's goal into checkable EFFECT claims and wires `dos hook stop` so the Stop is refused until git ancestry (a shipped phase) or an effect read-back corroborates the claimed effect. Driven by `dos` verbs and the workspace's own `dos.toml` — no host-specific paths, lanes, or commit conventions. Use when you want a self-stopping agent (or a `/loop` worker) to be unable to declare a goal complete on its own say-so. The single-agent self-stop analogue of `dos-witness-claim`.
Snapshot a repo's phased-plan portfolio and produce a parallel-agent dispatch packet, driven entirely by `dos` verbs and the workspace's own `dos.toml` — no host-specific paths, lanes, or commit conventions. Walks the configured plans glob, audits each candidate pick against `dos verify` for its true shipped/unshipped status, renders a self-contained packet to the configured output dir, and reports a typed gate verdict via `dos gate`. Use when you want a "where are we / what's next / who-does-what" snapshot of any repo that has a few plan docs and real commits. This is the DOS reference workflow (SKP Axis 5); a host may use it, fork it, or ignore it.