
dos-kernel
Bundles the DOS hooks + MCP server + the generic skill pack into one install. Requires the dos-kernel Python package (pip install 'dos-kernel[mcp]').
- version
- 0.30.0
- GitHub stars
- 22
Install
/plugin install dos-kernel@dosRun it inside Claude Code after adding the marketplace with /plugin marketplace add anthony-chaudhary/dos-kernel.
Contents
Discovered from sourceSkills 18
dos-class-cycle — the judge-gated plan-lifecycle tick
Garden the portfolio, but never alone. A plan's class (active / done / parked / …) should track reality — a done plan should not sit "active," a long-idle one should park.
/dos-class-cycleruns ONE tick of that gardening: it evaluates the declared triggers, asks a JUDGE-rung adjudicator (advisory, fail-to-abstain) to approve each candidate transition, applies only the gated ones, and logs the cycle. The class set, the legal transitions, and the failsafes are declared data ([lifecycle]) — a 2-class repo and a richly- classed one run the identical mechanism.
The shape: read the declared lifecycle → evaluate triggers → build candidates
(deterministic order) → judge each → enact gated transitions → log. The cycle
is domain-free mechanism; the taxonomy is [lifecycle] policy; the judge content
is a host dos.judges driver.
Inputs
--dry-run(optional) — evaluate + judge but enact nothing (a preview cycle).
Step 0 — Read the declared lifecycle + the layout
dos doctor --workspace . --json
Read lifecycle — the declared classes, transitions (each {from, to, trigger, auto}), veto_class, max_transitions_per_cycle, and
per_plan_cooldown_hours — and paths (the plan + run dirs). Use these; never
hardcode a class name, a trigger, or a cap. A repo that declared only
active/done cycles with those two; a repo with a richer taxonomy declares more.
Step 1 — Evaluate each declared trigger → candidate transitions
For each declared transition, evaluate its trigger against the portfolio (the
plan-meta classes, the run-archive history, git). A trigger that fires on a plan
proposes that plan for that from→to transition. Build the candidate list in a
DETERMINISTIC order (plan id ascending) so a replay is byte-stable.
Skip a plan that is:
- in the
veto_class(never auto-transitioned — a human moves it by hand), or - transitioned within
per_plan_cooldown_hours(the per-plan cooldown), or - already past
max_transitions_per_cyclecandidates this tick (the cap).
The trigger evaluator is the host's (an opaque trigger token like
all_phases_shipped / idle_30d — the kernel never interprets it). A natural
ground-truth trigger: a plan whose dos enumerate residual is empty AND every
unit dos verifys SHIPPED is a real all_phases_shipped → done candidate.
Step 2 — Judge each candidate (the JUDGE rung, advisory)
A class transition is a judgment call, so it goes to the JUDGE rung — a non-deterministic adjudicator that rules on the residue the deterministic checks left. Resolve the active judge by name and ask it to approve / defer each candidate:
dos judge-eval --judge <name> # the judge seam; built-in `abstain`, shipped `llm`, or a dos.judges plugin
The judge is hedged by the four disciplines (deterministic-first, advisory-only,
fail-to-abstain — a raise/bad-return becomes ABSTAIN, never APPROVE —
abstention-first). The judge content (the prompt) is a host dos.judges driver;
this skill spawns it via the seam and reads its verdict. An ABSTAIN defers the
transition to a human (the safe direction — the kernel never auto-applies on an
abstention).
Step 3 — Enact the gated transitions (auto only where declared)
For each candidate the judge APPROVED and whose declared transition has
auto = true, enact it: rewrite the plan-meta classification: to the to
class, ONE commit per cycle. Read the trunk + ship grammar from dos doctor --json's stamp; do not hardcode a commit prefix. A transition with
auto = false, or one the judge deferred/abstained on, is surfaced for a human —
never enacted.
Step 4 — Log the cycle (even a 0-transition tick)
Write a cycle record under paths.runs: the candidates, the judge verdicts, the
applied transitions, and the failsafe state (cap/cooldown/veto). A heartbeat row
every cycle — even one that applied nothing — so the gardener's history is
auditable.
What this skill deliberately does NOT do (no silent gap)
- No host class taxonomy. Classes/transitions/failsafes are
[lifecycle]data; this skill carries none. A transition naming an unknown class is a config error the kernel raises at load, not a silent skip. - No judge content. The adjudicator prompt is a host
dos.judgesdriver; the skill resolves + spawns it, fail-to-abstain. Forcing the prompt generic would re-couple the kernel. - No transition past a failsafe. The per-cycle cap, the per-plan cooldown, and the veto class are hard gates; the cycle never exceeds them.
Anti-patterns
- ❌ Applying a transition the judge ABSTAINED on — abstention defers to a human; the kernel never auto-applies on an abstention (the fail-to-abstain floor).
- ❌ Hardcoding
ACTIVE/PARK/TOMBor a trigger likeidle_14d— read the declared set fromdos doctor --json'slifecycle. - ❌ Exceeding
max_transitions_per_cyclein one tick — a runaway judge must not churn the whole portfolio; the cap is the backstop.
dos-dispatch-loop — the generic dispatch⇄replan cadence
The unattended plan-and-ship loop. It runs
/dos-dispatchrepeatedly and falls to/dos-replanwhen a lane drains, stopping on a typed, kernel-decided condition (not a prose guess). The stop/continue logic is the kernel'sloop_decide.decide— the loop carries counters, the kernel decides. Several loops on disjoint lanes run in parallel, each holding its own lane lease.
The stop conditions are the kernel's, in one place:
- iteration cap — reached
max_iterations(default 10). - drained-twice — a DRAIN after a productive
/dos-replanthat itself followed a DRAIN (the lane is genuinely exhausted). - consecutive-unclear — the dispatch subprocess is failing systematically.
- rate-limited — a usage window is exhausted (don't burn launches).
- launch-failed — a subprocess never started.
- pick-held-invariant — the next unit is held ONLY by a reason a re-dispatch cannot change (draft-class / operator-gated / soak-open / dependency-unmet); re-dispatching it would re-block identically, so honest-STOP + surface the hold.
- pick-cooldown — the next unit was attempted-and-didn't-move inside its cooldown window AND nothing fresher is offerable; re-dispatching it would re-storm a known drain (the ~5%-shipping re-pick loop the bare loop hit).
- not-ratcheting — the OUTER RATCHET (docs/351): the loop has run too many
iterations in a row with no witnessed net gain — the reconcile-VERIFIED
ship-count (Step 3) is not rising, even though each iteration reported SHIPPED.
The loop is running but not improving (the "spinning, narrating progress while
net-shipping nothing real" failure that worsens the longer the loop runs). The
verdict is the kernel's
improveESCALATE, read VERBATIM — not the loop's self-report. Hand the judgment back to a human.
Conditions 6–7 are the docs/207 anti-churn rungs (the loop stops re-picking work
it cannot move); condition 8 is the docs/351 ratchet (the loop stops when it is
moving but not improving — RSI made first-class here, the same improve keep-gate
the /dos-self-improve loop uses, now gating each dispatch iteration's net gain).
Inputs
--lane <name>(optional) — focus the whole loop on one lane (fixed for the run; a bare loop auto-picks a free lane at Step 0).--gate hard|soft|drive(defaulthard) — the verdict policy.hardroutes a non-LIVE verdict through/dos-replan;soft/drivestop on a true DRAIN;driveself-heals a STALE-STAMP inline.--max-iterations <N>(default 10).
Step 0 — Pre-flight: take the lane, read the taxonomy
dos doctor --workspace . --json
dos arbitrate --workspace . --lane <LANE> --kind cluster --leases '<SIBLING_LEASES>'
The arbiter ADMITs a free lane (or auto-picks one); a REFUSE means a sibling loop
already holds an overlapping lane — pick a free one from free_clusters or exit.
Initialise the loop counters (iteration=1, the breakers at 0).
Step 1 — Pick-selection: skip held + cooled units (the anti-churn gate)
Before a dispatch iteration offers a unit, screen the candidate unit set so the
loop never re-storms work it cannot move (the docs/207 §6 throughline). For each
candidate, in order:
dos pickable <UNIT> --state '<host-gathered state>' # OFFERABLE=0; HELD=per-reason code
dos cooldown <UNIT> # CLEAR=0; RECENTLY_ATTEMPTED=3
- A
pickableexit of 0 (OFFERABLE) and acooldownexit of 0 (CLEAR) → this unit is dispatchable; offer it and proceed to the iteration. - A
pickableHELD by a re-dispatch-CURABLE reason (IN_FLIGHT / SOFT_CLAIMED / STALE_CLAIM / UNPARSEABLE) or acooldownof 3 (RECENTLY_ATTEMPTED) → skip this unit, try the next candidate (the skip-to-next is pick-selection's job). - A
pickableHELD by a re-dispatch-INVARIANT reason (DRAFT_CLASS=10 / OPERATOR_GATED=11 / SOAK_OPEN=12 / DEPENDENCY_UNMET=13) → carry that verdict into Step 2; the kernel will honest-STOP on it (don't re-dispatch a unit a re-dispatch cannot un-gate).
When EVERY remaining candidate is skipped (all cooled / curably-held), carry the
last cooldown RECENTLY_ATTEMPTED (or the invariant pickable hold) into Step 2
as the loop's pre-dispatch evidence — the kernel turns "nothing fresh is offerable"
into the pick-cooldown / pick-held-invariant honest-STOP. Do not re-dispatch
the cooled/held unit yourself — that is the re-pick storm this gate prevents.
Step 1b — Run one iteration
For a dispatch iteration, invoke /dos-dispatch --lane <LANE> (it snapshots,
gates, and ships). For a replan iteration, invoke /dos-replan. Capture the
iteration's outcome:
- a dispatch iteration that reached the gate carries a typed verdict — get it
from
dos gateover the packet's dispositions sidecar (LIVE/DRAIN/STALE-STAMP/ BLOCKED/RACE). - a replan iteration carries a productivity signal (did it refill/garden?).
Step 2 — Decide continue / replan / stop (the kernel decides)
This is the load-bearing step: the decision is a kernel mechanism, not prose.
Feed the iteration outcome + the carried counters to the loop decider. In code a
host calls dos.loop_decide.decide(state, outcome); the screenplay's job is to
construct the typed IterationOutcome and read the returned LoopDecision:
action: "continue"→ run the next iteration innext_mode(dispatchorreplan); ifreconcileis set (a soft/drive STALE-STAMP), run an inline stamp-reconcile pass first. Carrynext_stateforward (the updated counters).action: "stop"→ the loop ends; reportstop_reason(one of the five above) andsurface(whether it needs operator attention).action: "retry-same-iter"→ a transient overload; sleepbackoff_secondsand re-run the SAME iteration.
The drained-twice rule is the kernel's: a DRAIN counts toward an early stop ONLY
after a productive /dos-replan. A STALE-STAMP or BLOCKED gate routes to
/dos-replan (under hard) but never arms a false drained-twice stop — that is
the structural fix the typed gate exists for.
The pre-dispatch evidence from Step 1 rides into the decision too: the kernel reads
the carried Pickability (→ pick-held-invariant stop) and Cooldown (→
pick-cooldown stop). So the loop's continue/stop is driven END-TO-END by kernel
rungs — the honest-STOP that used to be a per-run human override is now a kernel
rule, not prose the loop re-applies each iteration.
Step 2b — Gather the outer-ratchet verdict (docs/351, the RSI rung)
One more piece of in-flight evidence rides into decide(): the outer ratchet,
the verdict on whether this iteration produced a witnessed net gain or the loop is
spinning while narrating progress. The work-metric is the cross-run KEEP the loop
already computes in Step 3 — the count of picks dos reconcile confirms VERIFIED
(exit 0) against git ancestry, NOT the SHIPPED self-report. Carry a cumulative
baseline of VERIFIED picks across iterations and ask the kernel:
# work = the carried cumulative VERIFIED count + this iteration's VERIFIED picks;
# baseline_work = the carried cumulative count BEFORE this iteration.
# suite/truth come from the gate being LIVE and reconcile not flagging QUIET_INCOMPLETE.
dos improve --workspace . \
$( [ "$GATE_LIVE" = 1 ] && echo --suite-passed ) \
$( [ "$RECONCILE_CLEAN" = 1 ] && echo --truth-clean ) \
--work "$VERIFIED_TOTAL" --baseline-work "$VERIFIED_BASELINE" \
--consecutive-reverts "$RATCHET_REVERTS" --max-reverts 3 --json
Branch on the verdict (the exit code): 0 KEEP — net gain witnessed, raise the
baseline (VERIFIED_BASELINE=$VERIFIED_TOTAL), reset RATCHET_REVERTS=0; 3 REVERT
— no net gain this iteration, bump RATCHET_REVERTS; 4 ESCALATE — the breaker is
open. Pass the verdict as loop_decide.decide's ratchet evidence. When it is
ESCALATE the kernel STOPs the loop with not-ratcheting (condition 8): N iterations
of "SHIPPED" that all reconcile QUIET_INCOMPLETE accrue reverts and stop the loop
instead of burning the cap — the exact failure the bare loop hit (motion without
measured progress). This is the same improve keep-gate the /dos-self-improve loop
uses, now gating each dispatch iteration's net gain; the metric is the non-forgeable
reconcile-VERIFIED count (git ancestry), never the loop's word.
Step 3 — Reconcile each claimed pick (the cross-run KEEP)
A dispatch iteration that SHIPPED claims picks done — but a claim is a
self-report. Before the archive drops a claimed pick from the residual, reconcile
its claim against ground truth so a quietly-incomplete pick re-enters the pickable
set next iteration, flagged:
dos reconcile <UNIT> --claimed-done --plan <PLAN> --phase <PHASE> # oracle from git
Branch on the exit code (the verdict IS the code):
0VERIFIED → the oracle confirms it shipped; it leaves the residual.3QUIET_INCOMPLETE → CLAIMED done but the oracle says NOT_SHIPPED — KEEP it in the residual, flagged; it re-enters the pickable set next iteration so the host routes it (a verifier pass //dos-replan/ a finding). Do NOT believe the claim — only ground truth removes work (the FQ-336 touch-counts-as-ship false-DRAIN is exactly what this catches).4HONEST_OPEN → not claimed, not shipped; honest open work, stays in the residual.
This is the cross-run KEEP wired at the boundary that runs the write (the
CLAUDE.md "wire the contract into the step that runs the write" rule).
Step 4 — Archive + release (and leave the lane's tree clean)
When the loop stops, write a loop record under paths.runs (the run dir from
dos doctor --json: the per-iteration verdicts, the reconcile flags, the stop
reason) and release the lane lease. Commit with a generic subject read from config
— no hardcoded prefix.
Leave the tree clean for the lane you held — an unattended loop must not strand
its own writes. A loop that ships work but leaves it uncommitted is the bug the
oracle catches next session: dos verify answers from git ancestry, so an
uncommitted change is a phase the kernel reports NOT_SHIPPED (the "a commit IS the
ship-stamp" contract). So at close-out, commit your lane's writes — driven by the
same dos verbs the loop already uses, with generic git:
- Commit your lane's writes by explicit pathspec — stage exactly the files
under the lane region you leased (the
treeglobsdos arbitratehanded back), then commit naming those paths:git add <lane paths>;git commit -m "<subject>" -- <lane paths>. Never a baregit add -A— when sibling loops hold disjoint lanes on the same tree, a blanket add sweeps another loop's in-flight edits into your commit. The lane lease you held names exactly which paths are yours; commit only those. - Confirm the tree is clean for your lane before you exit.
git status --porcelain -- <lane paths>over the region you leased should come back empty once you have committed. If it does not, you stranded durable work —logit and commit it (or, if a path turns out to belong to a still-live sibling lease — checkdos arbitrate/the lane journal — leave it for that loop). Either way the loop must not exit leaving its own lane dirty off a self-reported "done". - Scratch is not stranded work. Short-lived probe output (a host's scratch
convention — temp dirs,
*.err, leading-underscore probes) is deletable noise, not a phase to ship;rmit or leave it gitignored, don't commit it into the lane.
This close-out is what keeps an unattended fleet's tree clean and well-organized across runs: each loop commits its own lane and confirms it left nothing behind, so the trunk never accumulates anonymous WIP from a loop that stopped mid-write.
DOS-repo note (not part of the generic skill): when this loop runs in the DOS kernel repo itself, that repo ships an advisory
scripts/git_hygiene.py --strictthat mechanizes the "is my lane clean?" check above (exit 1 on stranded durable work, lease-aware). It is a DOS-repo convenience, not adosverb — a foreign workspace uses the genericgit statusform above. Both express the same discipline.
What this skill deliberately does NOT do (no silent gap, CLAUDE.md heavy tier)
- No soft-claim lease core. It coordinates loops by lane lease
(
dos arbitrate), not the per-pick soft-claim machinery that stays host-side.logthis when a sibling lane is busy rather than waiting on a soft-claim. - No value-greedy focus scheduler. It picks by lane order + the gate verdict, not a host's per-iteration focus ranking. That scheduler is the heavy tier.
- No rate-limit predictive monitor / resume manifest. It stops on a RATE_LIMITED outcome and reports it; it does not pre-empt or auto-resume. A host adds that as a driver concern.
It logs each of these the first time it would have used them, so the capability
gap is named, never silent.
Worked example (live transcript)
The cadence loop, by hand. Take a lane, keep the WAL beat alive, ask the kernel if the run is moving. Every line is a real
dosverb; the heartbeat is theHEARTBEATop the trajectory-audit cross-signal reads.
Step 0 — take a lane. You ask for src; a live lease made it contended, so the
arbiter auto-picks a free cluster lane instead (it never double-books a region):
$ dos arbitrate --workspace . --lane src
{"auto_picked":true,"free_clusters":[],"lane":"benchmark","lane_kind":"cluster","outcome":"acquire","pick_count":null,"reason":"auto-picked free cluster lane benchmark (requested src was refused: lane src would edit the orchestrator's own running code … (SELF_MODIFY) …).","tree":["benchmark/**"]}
→ exit 0 (acquire); the redirect IS the admission kernel refusing an
inadmissible region, with the real reason named in the parenthetical (a free,
admissible lane you name is granted directly).
Keep the beat alive across iterations — acquire once, heartbeat each pass,
release at the end. The HEARTBEAT op is what makes SPINNING reachable from
real evidence (a beat is not an event):
$ dos lease-lane acquire --workspace . --lane benchmark # writes ACQUIRE to the WAL
$ dos lease-lane heartbeat --workspace . --lane benchmark # writes HEARTBEAT each iteration
$ dos lease-lane release --workspace . --lane benchmark # writes RELEASE when the loop stops
Ask the kernel if the run is moving (the temporal verdict, from git delta — never the loop's "making progress" self-report):
$ dos liveness --workspace . --run-id R --start-sha 80d4f30
→ exit 0 = ADVANCING · 3 = SPINNING · 4 = STALLED (2 contract-error).
Drive the loop off the exit code, not stdout prose.
Read the beat back from the WAL — an ACQUIRE/HEARTBEAT/REFUSE/RELEASE
sequence on generic lanes (ILLUSTRATIVE shape; dos journal replay folds it):
$ dos journal --workspace . tail 4
{"op":"ACQUIRE","lane":"benchmark","tree":["benchmark/**"]}
{"op":"HEARTBEAT","lane":"benchmark"}
{"op":"REFUSE","lane":"benchmark","reason":"lane benchmark is already held by a live loop — pick a different --lane or wait."}
{"op":"RELEASE","lane":"benchmark"}
→ the REFUSE row is the WAL recording the arbiter's "no" — a sibling loop's
overlapping lane, fossilized for dos decisions to surface.
Anti-patterns
- ❌ Re-implementing the stop conditions in prose — route every outcome through the kernel loop decision; the counters/breakers/cap are the kernel's.
- ❌ Counting a STALE-STAMP/BLOCKED toward drained-twice — only a true DRAIN after a productive replan counts (the kernel enforces this; don't second-guess it).
- ❌ Running two loops on overlapping lanes — the arbiter REFUSEs the second;
honor it, don't
--force.
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 fromdos 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 theautopickladder.--leases <json>(optional) — the live leases other dispatches hold, as a JSON list of{lane, lane_kind, tree}(the arbiter keys exclusivity onlane_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
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.
dos arbitrate --workspace . --lane <LANE> --kind cluster --leases '<LIVE_LEASES>'
Read the LaneDecision JSON: {outcome, lane, tree, reason, free_clusters, …}.
outcome: "acquire"→ admitted.laneis the lane to run on (may differ from the request when auto-pick reassigned it);treeis its file tree. Proceed.outcome: "refuse"→ not admitted.reasonexplains why;free_clusterslists lanes you could pick instead. Stop (or retry on a free lane). Do not force —--forceis 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:
dos gate --workspace . <paths.next_packets>/.dispositions-<tag>.json
Branch on the exit code (the verdict IS the code):
0LIVE → there is dispatchable work; proceed to Step 4 (ship).3DRAIN → empty backlog; skip the ship, archive a no-op, report drained.4STALE-STAMP → shipped-but-unstamped drift; skip the ship, surface the drift for reconciliation (a/dos-replancan stamp it).5BLOCKED → picks blocked; skip, surface.6RACE → 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:
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:
- Dedupe first. Search before filing —
gh issue list --search "<keywords>"— and comment on the existing issue rather than opening a twin. - 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.
- 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. - Close only by ancestry, never by narration. The honest close is
Fixes #Nin 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 witnessdos verifyrides).gh issue closeoff "I fixed it" is the self-report this kernel exists to refuse; non-commit closes (duplicate, wontfix) are operator moves an agent may propose, never execute.
What this skill deliberately does NOT do (no silent gap)
- No per-pick soft-claim leasing. It takes a lane lease (
dos arbitrate), not the heavy per-pick soft-claim core (CLAUDE.mdheavy tier). Two loops on the same lane serialize on the lane, not on individual picks. - No rate-limit resume / focus scheduler. Those are the host's heavy tier; a
generic dispatch ships once and archives.
/dos-dispatch-loopadds the cadence. - No host packet template / commit subject. It reads the ship grammar from
[stamp]and assembles a generic archive record.
Log the gap, never silently skip it. The first time the skill would have
reached for one of these (a per-pick soft-claim, a focus-scheduler pick, a
rate-limit resume), emit a one-line log naming what it is not doing — so the
capability gap is surfaced at runtime, matching /dos-dispatch-loop.
Worked example (live transcript)
The shape, run for real.
doctor → arbitrate → gate → ship → verify, with the actualLaneDecisionJSON and the exit codes that branch it. Captured against a live DOS workspace (dos 0.30.0); copy-paste, then read the RUNG.
$ dos doctor --workspace . --json
{ ... "lanes": {"concurrent": ["benchmark","docs","examples","scripts","spikes","src","tests"],
"exclusive": ["global"], "autopick": ["benchmark","docs",...,"tests"]},
"paths": {"plans_glob":"docs/**/*-plan.md","next_packets":".dos/verdicts","runs":".dos/runs"},
"stamp": {"style":"grep"}, "overlap_policy": {"active":"prefix"} }
The WCR on-ramp — lanes/paths/stamp are DATA. Nothing below is hardcoded.
$ dos arbitrate --workspace . --lane src
{"auto_picked":true,"free_clusters":[],"lane":"benchmark","lane_kind":"cluster","outcome":"acquire","pick_count":null,"reason":"auto-picked free cluster lane benchmark (requested src was refused: lane src would edit the orchestrator's own running code … (SELF_MODIFY) …).","tree":["benchmark/**"]}
exit 0 (acquire) — but you asked for src and got benchmark: the admission
conjunction refused the hint (here SELF_MODIFY — on the kernel's own repo src/**
IS the running kernel; a lane contended by a live lease redirects the same way,
with the real reason in the parenthetical), so the kernel redirected rather than
double-book. A free, admissible lane you name is granted directly. Run on
lane (= benchmark), not your request. exit 1 (refuse) would mean stop / pick from free_clusters.
$ dos gate --workspace . .dos/verdicts/.dispositions-benchmark.json
The verdict IS the code: 0 LIVE → ship; 3 DRAIN → skip + archive no-op; 4
STALE-STAMP / 5 BLOCKED → skip + surface; 6 RACE → retry the snapshot once.
$ dos verify --workspace . docs/82_liveness-oracle-plan liveness --json
{"phase":"liveness","plan":"docs/82_liveness-oracle-plan","rung":"direct","sha":"80d4f30","shipped":true,"source":"grep-subject","summary":"80d4f30 liveness: exclude the BIRTH acquire from the ADVANCING event count"}
exit 0 SHIPPED — but source is grep-subject, not registry: a commit subject
carrying the phase token flips this true even if little was built. Read the rung.
$ dos verify --workspace . docs/99_runtime-validation-and-the-actuation-boundary halt --json
{"phase":"halt","plan":"docs/99_runtime-validation-and-the-actuation-boundary","shipped":false,"source":"none"}
exit 1 NOT_SHIPPED (source=none) — git ancestry never stamped it. The oracle closes
the phase from git, never from "I'm done." Then /release cuts the version.
Anti-patterns
- ❌ Launching a ship on a 0-pick packet — gate first; DRAIN/STALE-STAMP skip.
- ❌
--force-ing past a refuse in automation — a refuse means a real collision; pick a free lane fromfree_clustersor stop. - ❌ Hardcoding a run dir or a commit prefix — read them from
dos doctor --json. - ❌ Absorbing an out-of-scope finding into the lane's commit — or dropping it. File an issue (dedupe → done-condition → leak-check), then stay in the leased tree.
dos-enforce-tune — the loop where DOS tunes its OWN enforcement, from outcomes
DOS is a sound PDP with no feedback from the PEP. The kernel decides an intervention verdict, a host acts on it, the act is journaled — but nothing fed whether the act was right back into the policy that drove it. This loop closes that. It learns the enforcement thresholds from the journal's own ground truth: a deny the operator later overrode is a false-DENY (too aggressive); a deny that stood is a held catch. The loop tunes the policy to drive false-DENIES down while holding the catches — and keeps an edit only if the kernel, not the agent, measures that it helped.
This is [[dos-self-improve]] pointed at the enforcement policy, with one twist: the
metric is not a generic count, it is the docs/143 net_task_delta of the policy over
labelled cases the loop did not author.
A self-tuner's fatal failure mode is grading its own homework — relabelling its outcomes so its policy edit looks good.
dos enforce-tunecloses that hole the same waydos improvedoes: the metric is computed BY THE KERNEL from cases the loop did not author (a frozen corpus ∪ the live enforcement journal). The loop cannot keep a policy edit by claiming it is better. The only path to KEEP is to actually movenet_task_delta.
What the kernel decides vs. what you do
| Step | Who | What |
|---|---|---|
| Read the outcomes | dos enforce-outcomes | the live false-DENY / held-catch ledger — what to tune toward |
| Propose ONE policy-knob edit | YOU (a subagent) | the untrusted step — edit [intervention_policy] / [intervention] ranks / [improve] in a worktree |
| Measure | dos enforce-tune | score the candidate policy's net_task_delta over the corpus, on the worktree |
| Keep / revert / escalate | dos enforce-tune (rides dos improve) | the kernel's typed verdict over env-authored facts — NOT your opinion |
| Merge / discard / escalate | YOU (or the autonomous cadence) | carry out the kernel's verdict |
Inputs
--cases <corpus.jsonl>(required) — the labelledInterventionCasecorpus the candidate policy is scored over (the docs/143 §13.2 ground truth). The reference corpus is the benchmark'sintervention_cases.jsonl.- the autonomous cadence (below) reads the
dos enforce-tuneEXIT CODE and merges on a KEEP. Run interactively WITHOUT auto-merge to inspect the verdict first (the safe default); let the cadence auto-merge once you trust it. Either way the verdict is the kernel's, and the runtime-logic rail still reverts a candidate that edited adjudication logic. --max-cycles <N>(default 5) — the backstop cap.--max-reverts <N>(default 3) — ESCALATE to a human after this many non-keeps in a row (the breaker).--lane <name>(optional) — the lane to take; a bare loop auto-picks a free one.
Step 0 — Read what enforcement is getting wrong
dos enforce-outcomes --workspace . --json
This folds the OP_ENFORCE journal into the false-DENY / held-catch ledger. A
standing false_denies count is the signal: the policy is refusing edits the
workspace genuinely makes. (The dos pulse heartbeat surfaces the same count when it
crosses the threshold, so an always-on operator sees it without asking.) Note the
targets being over-blocked — they tell you which way to tune (usually: loosen a rung
or raise a confidence bar so a marginal mint earns WARN, not BLOCK).
Step 1 — Pre-flight: take a lane, record the GREEN baseline net_task_delta
dos doctor --workspace . --json
dos arbitrate --workspace . --lane <LANE>
RID=$(dos run-id mint dos-enforce-tune \
| python -c "import sys,json;print(json.load(sys.stdin)['run_id'])")
python -m pytest -q # MUST be green to start
dos enforce-tune --cases <corpus> --suite-passed --truth-clean \
--baseline-work 0 --json --workspace . # read measured_work = the BASELINE policy's score
Record the baseline measured_work B. You cannot measure improvement from a red
baseline — if the suite is red, fix it first (an ordinary task, not a tuning cycle).
RID is the loop's correlation run-id; pass it with --observe on every
dos enforce-tune call so dos observe --loops can fold this always-on tuner's
trajectory while it runs (docs/383) — otherwise a long-lived cadence is invisible
between its commits.
Step 2 — Per cycle: propose ONE policy-knob edit in an ISOLATED worktree
The enforcement policy is the kernel's own config — editing it on the live tree is the SELF_MODIFY hazard ([[self-modification-hazard]]). Work in an isolated worktree:
git worktree add ../_et-candidate HEAD
Spawn ONE subagent with a tight brief, working in that worktree:
Improve DOS's enforcement policy to reduce false-DENIES without losing catches. Edit ONLY the policy KNOBS: the
[intervention_policy]confidence-gating values (on_high_confidence/on_low_confidence/floor/ceiling), the[intervention]ladder ranks, or the[improve]thresholds — indos.toml. Make the SMALLEST edit that should movenet_task_delta. Do NOT touch enforcement LOGIC (self_modify.py,admission.py,arbiter.py, the ladder code) — that edit will be reverted regardless of its metric. Commit your change. Return what you changed and why. If you cannot find a real improvement, say so — do not invent one.
Step 3 — Measure + decide (the kernel decides)
Gather the env-authored witnesses on the worktree, then ask the kernel:
cd ../_et-candidate && python -m pytest -q ; SUITE=$?
CHANGED=$(git diff --name-only HEAD~1 HEAD) # the candidate's diff — for the rail
dos enforce-tune --cases <corpus> \
--policy-toml ../_et-candidate/dos.toml \
--baseline-work "$B" \
$( [ "$SUITE" -eq 0 ] && echo --suite-passed ) \
--truth-clean \
--changed-files $CHANGED \
--max-reverts <N> \
--observe --run-id "$RID" --subject "cycle-$CYCLE" --json --workspace .
The --observe --run-id "$RID" --subject "cycle-$CYCLE" line records the cycle to the
verdict journal so dos observe --loops folds this loop's trajectory live (docs/383).
dos enforce-tune re-scores the CANDIDATE policy (loaded from its worktree dos.toml),
applies the runtime-logic rail to --changed-files, and rides dos improve. The
verdict IS the exit code:
0KEEP — suite green, truth clean, candidatenet_task_deltastrictly beatB, no runtime-logic edit. Witnessed. Go to Step 4-KEEP.3REVERT — a regression (suite red / a runtime-logic edit / truth dirty) or a no-op (the metric did not beatB). Go to Step 4-REVERT.4ESCALATE — the breaker is open (--max-revertsnon-keeps in a row). STOP.
Step 4 — Carry out the verdict
- KEEP — merge the worktree commit onto the lane, RAISE the baseline to the
candidate's
measured_work(the ratchet), reset the revert count. The autonomous cadence does this on exit 0; by hand:git merge --ff-only <sha>thenB=<measured_work>. - REVERT — discard the worktree candidate; the live policy is untouched. Bump the
revert count.
git worktree remove --force ../_et-candidate. - ESCALATE — discard, file a
dos decisionsentry with the kernel's reason, STOP. The loop has run dry of witnessed improvements; a person decides what matters next.
Re-create a fresh worktree off the (possibly advanced) lane HEAD and return to Step 2
until --max-cycles or an ESCALATE.
Always-on: the autonomous cadence
To run continuously, wire a durable scheduler (a cron / Windows Task via a gitignored
.dos/ runner — the dos pulse runner sibling pattern). The runner does ONE bounded
cycle per firing and merges on a KEEP by reading the exit code:
# per firing, in an isolated worktree the runner created off the lane HEAD:
dos enforce-tune --cases <corpus> --policy-toml <wt>/dos.toml \
--baseline-work "$B" --suite-passed --truth-clean \
--changed-files $(git -C <wt> diff --name-only HEAD~1 HEAD) \
--observe --run-id "$RID" --subject "cycle-$N" --workspace .
case $? in
0) git merge --ff-only <candidate-sha> ;; # KEEP — auto-merge + ratchet B
4) dos decisions ... ; exit 0 ;; # ESCALATE — surface to a human, stop
*) : ;; # REVERT — discard, leave the policy
esac
The cadence keeps ONE $RID across all its firings (persist it in the runner's .dos/
state), so every cycle folds into the SAME trajectory — an always-on tuner that would
otherwise be invisible between commits becomes a live curve in dos observe --loops.
Each firing is bounded (one cycle; over many firings the breaker + cap still hold),
so it always terminates — never an unbounded run. dos pulse keeps its observe leg,
so the heartbeat surfaces the false-DENY rate the loop acts on.
Watch the tuner live: dos observe --loops (every loop) or
dos observe --loops --run "$RID" (this tuner's full per-cycle curve) — the metric
high-water, the breaker N/max distance-to-escalate, and the ACTIVE/STALLED/ESCALATED
band, all folded from the kernel's own verdicts (docs/383).
Why the autonomous merge is safe
- The keep-bit is non-forgeable.
dos enforce-tuneKEEPs only on a kernel-measured strictnet_task_deltagain with the suite green and truth clean. A no-op or regression auto-REVERTs — the loop cannot narrate its way to a merge. - The breaker escalates to a human exactly when the loop runs dry — the human-in-the-loop seed, preserved even when fully autonomous.
- The runtime-logic rail reverts ANY candidate whose diff touched the kernel's
adjudication logic (
self_modify._DISPATCH_RUNTIME_FILES), regardless of its metric. The loop owns the policy KNOBS; the SELF_MODIFY guard still owns the LOGIC blast radius. A tuner that rewrote the arbiter to make a number go up is the self-modification hazard DOS refuses — refused here too, before merge.
What this skill deliberately does NOT do (no silent gap)
- No logic edits. The loop tunes thresholds/ranks, never the enforcement code. A logic edit is auto-reverted; the brief forbids it.
- No metric the loop can game.
net_task_deltais computed by the kernel from cases the loop did not author (the frozen corpus ∪ the live journal). A metric the subagent computes about itself is back to grading its own homework — refuse it. - No unbounded run. Every firing terminates into the cap or a human ESCALATE.
Anti-patterns
- ❌ Believing the subagent's "it's better" — re-measure via
dos enforce-tune; only the kernel verdict decides KEEP. - ❌ Editing enforcement LOGIC to move the metric — the runtime-logic rail reverts it.
- ❌ Tuning from a red baseline — fix the suite first; you cannot measure a gain you cannot see.
- ❌ Loosening the policy until false-DENIES hit zero — that tanks
coverage(catches held), whichnet_task_deltapenalizes; the kernel will REVERT an over-loosened candidate because the metric balances both.
dos-goal-fleet — wave-launched self-stopping goal workers, witnessed not narrated
A fleet that trusts each worker's "I'm done" is a fleet of silent fails. The move this skill makes is the one the whole substrate exists for: a worker's "the goal is met" is a claim with a byte-author, and the byte-author is the judged worker. So each child's stop is gated on
dos-goal-gate— it cannot declare done until a witness it did not write (git ancestry, an effect read-back) corroborates the goal's effects. The fleet launches the leaves; the kernel decides which ones actually landed. The skill narrates; it never rules.
Take an operator-supplied context describing several independent objectives, turn each into ONE headless worker armed with a single goal, and fire them in waves sized to whatever seat pool the host exposes — so the launch is load-balanced and no single account walls. This is the fan-out analogue of two sibling skills:
dos-goal-gateis one self-stopping leaf — a single agent whose "done" is grounded.dos-goal-fleetarms many such leaves at once. Each child runs the goal-gate discipline; this skill is the launcher and the rollup around them.dos-witness-claimis the fold — believing only the confirmed effects when many workers' results converge. Step 5 here is that fold, applied to the fleet's per-instance outcomes.
The shape is domain-free: decompose into independent goals → price the wave into
its serial/concurrent partition → arbitrate co-launch safety → wave-launch one
self-stopping child per goal → witness every claimed ship → roll up. Pricing the
partition is the default first move, not an optional optimization: concurrency is
earned per disjoint tree, never assumed for the wave. The policy (which lanes,
which plan grammar, how the host rotates accounts, which model a child runs) is
data read from dos doctor --json / dos.toml and from the host's own launch
convention — never a literal this screenplay hardcodes. A shipped generic skill names no host (the
litmus); the host-specific launch verb is a seam you fill in Step 3.
When to use this (and when not)
- Use it when the operator hands a context with 2+ independent objectives, each describable as a single goal condition (a visible deliverable), and wants them run concurrently rather than serially.
- Use
dos-goal-gatewhen it is one objective — just arm a single self-stopping agent; no fleet needed. - Use
dos-dispatch/dos-next-upwhen the work is already shaped as a phased-plan dispatch packet of disjoint repo tasks — that is packet-driven; this skill is goal-condition-driven over free-form objectives. - Use a single agent or a loop when the objectives are a sequenced plan — one goal waits on another's output. The fleet is for independent goals.
Never arm a loop spine. Do not goal-gate a dispatch-loop or a supervisor spine — those have their own typed stop authority.
dos-goal-fleetarms leaf objectives, which is exactly the sanctioned use.
Inputs
| Shape | What it looks like | Route |
|---|---|---|
| Explicit goal list | "goal 1: …, goal 2: …, goal 3: …" | one instance per listed goal |
| A context to decompose | a paragraph / doc / set of asks | Step 1: split into independent objectives, one instance each |
| A count + theme | "launch 5 workers to each find a bug in X" | derive 5 distinct goal conditions over X |
Step 0 — Discover the workspace layout, and the host's seat pool
Run the doctor verb once and read the result. Every path / lane / exit-code below comes from here, never a literal (the WCR on-ramp — EXAMPLES.md Recipe 0).
dos doctor --workspace . --json
The fields this skill uses:
lanes/lanes.trees— the lane taxonomy and each lane's file-tree, for thedos arbitrateco-launch check in Step 2.paths.plans_glob/stamp— the host's plan grammar and ship-stamp convention, for thedos verifyship-witness in Step 5.git— iffalse, the git-phase ship-witness (Step 5) has no history; every claimed ship resolvessource="none". Say so; do not silently pass it.runtime_hooks— which runtimes already havedos hook stopwired (Step 3).
The seat pool (sizes the waves). The wave size is the host's serving-account
count — read it from the host's own account/seat command, not from any verb
this kernel ships (DOS names no account mechanism). The skill needs one number,
SERVING = how many worker seats can run concurrently right now:
SERVING == 0(every seat walled) → STOP. Do not launch a paid child into a standing usage wall. Report the soonest reset the host exposes and offer to schedule the launch for after it.SERVING == 1→ rotation is a no-op; launch serially or in a wave of 1, and warn the operator that all goals share one seat's window.SERVING >= 2→ proceed; wave size =min(SERVING, total_goals, --max-concurrent).
Account rotation is a host seam, not a DOS verb. How launches spread across a seat pool — round-robin cursor, per-launch origin overlay, whatever — is the host's concern, wired into the launch command of Step 3. This skill only requires that the host's launch verb rotates seats per instance; it names no such mechanism itself. If the host has none, every child shares one seat — set
SERVING = 1and say so in the rollup.
Step 1 — Derive one goal per objective (the three-clause contract)
If the operator gave an explicit goal list, use it verbatim. Otherwise split the
context into independent objectives — each must stand alone, no cross-goal
dependency. For each objective write a goal condition stated as a checkable
effect, obeying three clauses (this is what makes the child's "done" witnessable
by dos-goal-gate, not self-certified):
- Deliverable as a visible effect — a
(plan, phase)the child will ship, a named file it will write, a commit it will land. State it as the thing a witness can later read back (dos verify, a fresh GET). Never "the work is good" — that has no byte-author but the worker. - The explicit-blocker escape clause — append literally: "— or the final report explicitly names why it could not be produced". Without it an honestly blocked child burns its whole turn ceiling re-trying. A blocked child that says why is a clean outcome, not a failure.
- No uppercase verdict tokens in the condition text (no
SHIPPED/BLOCKED/DONEliterals) — the condition is echoed into the child's log and any grep-based verdict scan must not false-match it. Lowercase prose.
Decompose into effects; abstain rather than invent. An objective you cannot name a checkable identifier for is not a passable goal — it is a NO_CLAIM to surface for the operator, never an effect you fabricate. This is the same decomposition
dos-goal-gateStep 2 spells out; the goal-gate wired into each child (Step 3) enforces it at the child's stop.
Write the derived (label, goal_condition, expected_paths, in_prompt_directives)
tuples to a plan file under the run dir (Step 2) and show them to the operator
before launching. If you derived the split (vs. the operator listing it),
pause and let the operator confirm or edit it — a wrong decomposition wastes a
whole wave.
Step 2 — Create the run dir and arbitrate co-launch safety
RUN_DIR="<host-scratch-root>/goal-fleet/$(date -u +%Y%m%dT%H%M%SZ)"
mkdir -p "$RUN_DIR" # always mkdir -p BEFORE any `>` redirect, or the shell
# silently creates an empty file in the parent (hygiene)
(<host-scratch-root> is the host's gitignored scratch dir, read from config or
chosen by the operator — not a literal this skill names.)
Price the whole wave first — the default first move, not an optimization. Before
the per-child loop below, price the entire proposed partition at once and emit its
serial/concurrent split — the three sets you then launch on: (1) the concurrent
set (the maximal disjoint group that may co-launch this wave), (2) the serialized
colliders (goals whose trees overlap a co-launched goal — held to a later wave,
sequenced behind the goal they collide with), and (3) the peer-blocked holds (next
paragraph). You compute this before you spend a single launch, instead of discovering
a collision only when the K-th child's arbitrate refuses, after the earlier children
already started. Run dos-plan-price on the wave; launch
its safe_now set, sequence the colliders, hold the rest.
Fold in live peer WIP, not just in-fleet geometry. The price is geometric over the
proposed trees, but a shared tree has a second collision source the lease WAL may not
show yet: a lane a peer is actively editing right now (uncommitted or untracked
files under that lane). A goal whose tree overlaps live peer WIP is hot — hold or
serialize it even when dos arbitrate would acquire (no lease is held) and the
in-fleet geometry is disjoint. Read the working tree's dirty/untracked set per lane and
treat a hot lane as a peer-blocked hold; co-launching into it risks cross-pollinating a
peer's in-flight work. The per-goal arbitrate below is still the unforgeable floor at
acquire time — the price (geometry + live-WIP) is the early-warning ahead of it,
not a replacement.
Collision check — the load-bearing safety step. Independent goals can still
touch overlapping files if they ship code. Two same-wave children writing the
same paths is the exact cross-pollution dos arbitrate exists to prevent. For
each goal, pass its expected_paths (from Step 1) and the leases already held by
the children you have already decided to co-launch this wave:
dos arbitrate --workspace . --lane <lane> --tree "<this goal's expected paths>" --json
outcome: "acquire"→ its file-tree is disjoint from the wave's other children; co-launch it.outcome: "refuse"→ it overlaps a child already in the wave; do not co-launch. Push it to a later wave (sequence it) or scope its claim narrower and re-arbitrate. Readfree_clustersfor a lane it could take instead.
For read-only / report goals there is no write collision — co-launch freely
(arbitrate still returns acquire). Only shipping goals need the gate. Prefer the
MCP form mcp__plugin_dos-kernel_dos__dos_arbitrate when running inside an agent
loop; the CLI form above is for a shell launcher.
Step 3 — Wire the goal-gate, then launch one self-stopping child per goal
First, wire the grounded Stop gate once per workspace (idempotent — merged into any existing hooks, never clobbering the operator's):
dos init --with-hooks --workspace . # the default runtime
# cross-runtime: dos init --hooks <runtime> --workspace . (preview with --dry-run)
This binds dos hook stop — the gate that refuses a child's stop while a
phase it claimed shipped is not backed by git. That refusal IS the grounded
form of "keep working until the goal is met": the child cannot end on its own
word that a phase shipped. This is the whole dos-goal-gate discipline; read that
skill for how it composes with a host's own model-judged goal command (they
AND — the grounded gate can only ever add a refusal, never loosen one).
Then launch each child as ONE headless worker subprocess. The launch command itself is the host's convention — this skill names no runtime binary, model, effort, or account flag. The host's launch verb must supply, per instance:
- The goal, armed as the runtime's stop-condition (so the child self-stops on
the goal). The grounded
dos hook stop(just wired) runs alongside it and vetoes a false done. - The in-prompt directives on stdin — context, scope, and the ship rules below. (A goal armed as a positional and directives on stdin compose; do not rely on a stdin goal line to gate — that is inert text the model only reads.)
- Seat rotation per instance — the host's account/origin overlay (Step 0),
evaluated before the launch so each child in the wave lands on a different seat.
If the host has none, every child shares one seat (
SERVING = 1). - A hard turn ceiling matched to the goal's weight (a light read/report is small; a ship is larger) — independent of the goal-gate, as a runaway backstop.
- The model / effort from the host's registry, never hardcoded here.
Per-instance launch hygiene (record into the run dir):
N=<instance-index>
ITER_DIR="$RUN_DIR/inst-$N"
mkdir -p "$ITER_DIR"
echo "[goal-fleet] inst-$N seat: ${<host seat id var>:-<default>}" > "$ITER_DIR/seat.txt"
# ... host launch verb ... > "$ITER_DIR/run.log" 2> "$ITER_DIR/run.err"
- Never merge stderr into the log (
2>&1) — stderr goes to the sibling.err; merging poisons the verdict scan with warnings / preflight banners. - In-prompt git rules (state them even though a host hook may also enforce):
the child may
git add/git commiton the current branch only if the goal calls for shipping; it may not push, tag, force-push, rewrite history, switch branches,git reset --hard,git clean,git restore, orgit checkout -- <tracked>. The orchestrator (you) never switches branches or leaves the worktree.
Step 4 — Fire in waves; one background task per instance
Launch each instance as a background task so the harness auto-notifies on exit — do not poll the log (wait-don't-poll). Wave discipline:
WAVE = min(SERVING, remaining_goals, --max-concurrent)(from Step 0).- Launch
WAVEinstances in one message, multiple background launches so they start concurrently — and so the host's per-launch seat cursor advances once per child, landing each on a different seat. - Wait for the wave's notifications (the harness re-invokes you on each exit). Do not start the next wave until the current one drains — this keeps concurrency ≤ the seat pool and lets walled seats reset between waves.
- Repeat until all goals are launched.
Re-read the seat pool between waves. If a live fleet (a dispatch-loop, a supervisor) is already consuming seats,
SERVINGoverstates your free headroom — re-run Step 0's seat read between waves and shrink the wave to the live count.
Same-wave goals that dos arbitrate refused in Step 2 go to a later wave (their
file-trees overlap a child already running) — never co-launched.
Step 5 — Per-instance outcome: witness, never narrate (the fold)
When an instance's task notification fires, read its result — and remember the
goal-gate is transcript-grounded for early-quit, not git-grounded for ship: it
proves the child didn't quit early, NOT that work landed. So fold only the
confirmed effects (this is dos-witness-claim applied to the fleet):
-
Did it meet the goal? Read the child's final result envelope in its
run.log. The honest-blocker escape clause means a blocked child names why in its final report — a clean outcome, recorded asblocked-with-reason, not a failure. -
Did a claimed ship actually land? Prove it by a witness the child did not author — never by its transcript:
dos verify --workspace . <PLAN> <PHASE> --json # SHIPPED only on real git evidence dos commit-audit --workspace . <claimed-sha> # subject vs its own diffRead the rung:
source: "registry"is the strongest ship;source: "grep-subject"is SHIPPED-but-weaker (a subject is forgeable);source: "none"means git does not back the claim — the narrated success the world doesn't corroborate. A goal met is not a ship verified. -
Effect outside git (a created file, a row, a sent message)? There is no
dos verify-effectCLI verb — gather an independently-authored read-back via thedos.evidence_sourcesseam (the Python-API pattern indos-goal-gateStep 2b) and fold only on CONFIRMED. Log the gap if no witness is wired; never launder an unwitnessed effect into "goal met". -
Auth/launch wall on turn 1?
is_error:true+ a not-logged-in message + zero cost = the seat didn't reach the child. Re-check that instance'sseat.txtand relaunch only that one instance.
Step 6 — Rollup + archive
Write a one-screen rollup to $RUN_DIR/rollup.md: per instance — label, seat
used, outcome (met / blocked-with-reason / auth-failed / errored), cost,
and any verified ship SHA (the dos verify / commit-audit verdict, not the
child's claim). Also record, per goal, which price bucket it came from — concurrent /
serialized-after / peer-blocked-hold — so the serial-vs-concurrent decision is
auditable. Tally seats used to confirm the spread actually happened:
grep -h seat "$RUN_DIR"/inst-*/seat.txt | sort | uniq -c
If every instance shows the same seat id, rotation did not engage (SERVING == 1,
or the host's overlay failed) — say so; do not imply a spread that didn't happen.
The run dir is local scratch (gitignored) — do not commit it. If any instance
shipped code and the tree is coherent, the operator (not this skill) decides
whether to push or release — dos-goal-fleet authorizes per-child commit, never
an outward-facing push.
Anti-patterns
- ❌ Deciding "the goal is met" by reading the child's last message. That is
consistency, not grounding — the worker judging its own bytes. Witness every
ship with
dos verify/commit-audit; fold only the confirmed (Step 5). - ❌ Co-launching two shipping goals without
dos arbitrate. Independent goals can still write the same files; arbitrate each child's tree before the wave and sequence the refusals (Step 2). - ❌ Launching the wave without first pricing it into its serial/concurrent partition. Concurrency is the default only for the priced-disjoint set; colliders are serialized and lanes with live peer WIP are held. Price first (Step 2), then launch the concurrent set and sequence the rest.
- ❌ Launching more concurrent instances than serving seats. That forces ≥2 onto one seat's window and defeats the load-balance; re-read the pool between waves.
- ❌ Naming a specific runtime binary, model, effort flag, or account mechanism in this skill. The launch verb and seat rotation are the host's seam (Step 3); this skill names no host (the litmus).
- ❌ Goal-gating a loop spine (a dispatch-loop, a supervisor). Those carry their own typed stop authority; arm only leaf objectives.
- ❌ Treating a
/goal-style model-judge as the ship oracle. The model-judge stops early-quitting (transcript-grounded); the git gate (dos hook stop) anddos verifyare what confirm a ship. They AND — the grounded gate only ever adds a refusal.
The one rule under this skill
Each child's "the goal is met" is a claim with a byte-author — the child. The
fleet lets a child stop only when dos hook stop finds git backs its claimed
phases, and folds a child's ship into the rollup only when dos verify /
commit-audit — a witness the child did not write — confirms it. The worker's
confidence and its fluent description of success are irrelevant to both gates,
which is the whole point: across a whole fleet, the part that decides a goal is
done is never the part being judged.
dos-goal-gate — gate "I'm done" on a witness, not on self-report
A completion condition the agent checks against its own narration is the exact failure DOS exists to fix. When an agent decides "the goal is met" by re-reading what it just wrote, the part deciding ground truth is the part being judged — that is consistency, not grounding (docs/138). This skill never decides done-ness by re-reading the transcript. It turns the goal into a set of checkable EFFECT claims, then wires the Stop decision so the agent cannot stop until a read-back whose byte-author is not the agent (git ancestry, an OS exit code, a fresh state read) corroborates each effect. The kernel decides; the skill narrates.
The shape is domain-free: state the goal as effects → wire the Stop gate →
on each stop, witness every effect → stop only when all are corroborated. The
policy (which plan grammar, which lanes, where state lives) is data read from
dos doctor --json, never literals this screenplay hardcodes.
Why this is not just "ask the model if it's done." A harness stop-condition ("keep going until X") is evaluated by a model reading the session — so a confident, fluent narration of an X that the world does not corroborate ends the work early (the silent fail of docs/177). The gate below replaces that judgment with a verdict over evidence the agent did not write: a phase is done when git says a commit backs it, not when the agent says it committed; a file exists when a fresh read finds it, not when the agent says it wrote it.
When to use this (and when not)
- Use it when a single agent self-paces toward a stated goal and you want its
"done" to be unfalsifiable-by-narration — a
/loopworker, a self-stopping task agent, or any run where the operator stated a completion condition. - Use
dos-witness-claiminstead when many workers' results are folded at aparallel()/pipeline()barrier — that skill is the fan-out fold analogue; this one is the single-agent self-stop analogue. Same witness discipline, different site. - This is advisory (a PDP, not a PEP — docs/99). It computes a Stop verdict and lets the runtime act on it via the user-owned hook seam. It blocks a false done; it never blocks a true one, and it never enforces beyond the Stop hook.
Inputs
- The operator's goal — the completion condition in plain words ("the auth refactor is shipped and the suite is green", "the migration plan's phases are all landed"). Free prose is the input, never the test.
- Optionally, a transcript path for the running session (the Stop event carries it; you rarely pass it by hand).
Step 0 — Discover the workspace layout (one call)
Run the doctor verb and read the result. Every path / lane / exit-code below comes from here, never a literal.
dos doctor --workspace . --json
The fields this skill uses:
exit_codes.verify—{shipped, not_shipped, contract_error}. Branch on these for a git-phase effect (Step 2a), never on parsing prose.exit_codes."verify-result"—{healthy, unreadable, dead, contract_error}(dead=3). Branch on these for the terminal-state witness when a transcript is in play.paths.plans_glob/lanes/stamp— the host's plan grammar, lane taxonomy, and ship-stamp convention, if a goal names a(plan, phase).git— iffalse, the git-existence witness (Step 2a) has no history; every git-phase effect resolvessource="none". Say so; do not silently pass it.runtime_hooks— which runtimes already have ados hook …Stop entry wired (so you know whether Step 1 still needs doing).
Step 1 — Wire the Stop gate (once per workspace)
The gate is dos hook stop: a Stop / SubagentStop hook that refuses to let the
agent stop while a confidently-CLAIMED phase is NOT corroborated by git. Wire it
into the runtime's settings — idempotent, merged into any existing hooks, never
clobbering the operator's own:
dos init --with-hooks --workspace . # Claude Code (the default runtime)
# cross-runtime: dos init --hooks <runtime> --workspace . (preview with --dry-run)
This binds three hooks; the load-bearing one here is Stop → dos hook stop.
On every stop it extracts the (plan, phase) the agent claimed and refuses the
stop (feeding the verdict back as the next instruction) if git does not back it.
That refusal IS the grounded form of "keep working until the goal is met": the
work cannot end on the agent's word that a phase shipped.
Two Stop hooks, opposite triggers — do not conflate them.
dos hook stopblocks a false done (the agent claimed a phase, git disagrees).dos hook marker(docs/259) blocks a premature give-up while a keep-alive budget is unspent, then gets out of the way. A host may wire both; this skill is about the first. If your goal is "don't stop polling yet," that isdos hook marker, not this gate.
Step 1a — How this composes with the harness /goal command
The Claude Code /goal <condition> command is itself a session-scoped Stop
hook — but a model-evaluated one: a fast model re-reads the session after each
turn and rules on whether the condition holds. That is precisely the
consistency-not-grounding shape this skill exists to fix — the judge is a model
reading the agent's own narration, with no witness the agent did not author.
You do not replace /goal; you wire dos hook stop (Step 1) alongside
it, and the harness combines them for you. Claude Code runs every matching Stop
hook in parallel and applies an ANY-block rule: the stop is refused if any
hook blocks it (a {"decision":"block",…} at exit 0, or exit 2). So with both
active, the agent may stop only when the /goal model-judge AND the grounded
git gate both allow it — a logical AND of "the narration reads done" and "ground
truth backs it." The grounded gate can only ever add a refusal the model-judge
missed; it never loosens /goal. That is the whole win: keep using /goal for
its fluent, free, prose-level check, and let dos hook stop veto the case where
the prose says done but git does not corroborate it.
The two hooks are independent — the gate does not read the goal text. A settings.json Stop hook receives the session/transcript, not the
/goalcondition string (the harness exposes no goal field to hooks). Sodos hook stopdoes not "check the goal"; it independently checks that every phase the agent claimed shipped is backed by git. The alignment between the two is the operator's job: state the goal as the same checkable effects the gate verifies (Step 2), so "the model thinks it's done" and "git backs every claimed phase" converge on the same finish line. Do not write the gate as if it parses the goal — it parses the agent's claims and asks git.
Step 1b — The Fable-5 guide's "check your last paragraph" is the advisory form of this gate
Anthropic's Claude Fable 5 prompting guide has a section, "Rare cases of early stopping," for a known failure: deep in a long session the model can end a turn on a text-only statement of intent ("I'll now run X") without the tool call, or pause to ask permission it already has. Its fix is a prompt:
Before ending your turn, check your last paragraph. If it is a plan, an analysis, a question, a list of next steps, or a promise about work you have not done ("I'll…", "let me know when…"), do that work now with tool calls. End your turn only when the task is complete or you are blocked on input only the user can provide.
That is the advisory version of this skill, and dos hook stop is the
enforced version that subsumes it. Same failure, opposite ends: the guide asks
the model to re-read its OWN last paragraph (consistency, not grounding — the same
shape Step 1a flags for /goal); the gate refuses the stop until a witness the
agent did not author backs the claimed effect. The prompt lowers the frequency of
"I'll now run X" early stops; the gate makes them impossible to get away with.
So a kernel reader migrating to Fable does not need to add the guide's prompt as a separate safeguard — the witness gate already covers that case. It is still fine to keep the prompt as defense-in-depth: it cuts the early stop before it happens, the gate catches the one that slips through. (An "I'll now run X" turn with no tool call and no shipped effect is exactly the unwitnessed-claim case the gate refuses — the operator sees a structured "your goal isn't witnessed yet, keep going," not a generic block.)
Step 2 — State the goal as checkable effects (the decomposition)
A goal is met when its effects are present in the world. Translate the prose goal into a list of named, checkable effects — and abstain rather than invent. An effect you cannot name an identifier for is not a passable goal; it is a NO_CLAIM to surface for the operator, never a test you fabricate (docs/134).
Map each effect to its witness rung:
| Effect the goal asserts | Witness (byte-author ≠ agent) | Verb today |
|---|---|---|
| "(plan, phase) is shipped" | git ancestry + ship-stamp grammar | dos verify (Step 2a) — SHIPPED |
| "this terminal result is real" (a transcript is in play) | harness authorship marker | dos verify-result — SHIPPED |
| "I created file X / inserted row Y / sent message Z / deployed" | a fresh GET / state-diff / OS exit / counterparty record | no CLI verb (Step 2b) — Python-API gap |
The first two are shipped CLI verbs. The third is the open seam — handled honestly in Step 2b. The goal's "done" is the conjunction of all its effects' witnesses: every one CONFIRMED/SHIPPED, or the goal is not met.
Step 2a — git-phase effects: ask the truth syscall
For each (plan, phase) the goal names, never trust "I committed it" and never
grep commit subjects yourself:
dos verify --workspace . <PLAN> <PHASE> --json
echo "exit=$?"
Read the ShipVerdict {shipped, source, sha?}, branch on exit_codes.verify,
and read the rung:
source: "registry"— the strongest git ship; a ship row exists. Effect met.source: "grep-subject"— a commit subject carried the phase token. SHIPPED, but weaker (a subject can flip the verdict even if little was built). Met, but mark the rung; do not treat it as equal toregistry.source: "none"— no positive git evidence. The agent CLAIMED the phase but git does not corroborate it. The effect is NOT met — this is the narrated success the world does not back. The goal is unmet; keep working.
This is grounding because git is a witness the agent did not author: a commit's existence in ancestry is a fact about the repository, not about the agent's prose.
Step 2b — created-file / DB-row / sent-message effects: the read-back gap
There is NO dos verify-effect (or dos witness) CLI verb. The
effect-witness join is shipped in the kernel as a Python API, not a command
(exactly as tool_stream has no dos tool-stream verb — see EXAMPLES.md Recipe
5). So for any effect outside git, document the pattern and log the gap at
runtime, rather than pretending a verb exists:
from dos.claim_extract import extract_claims # (a) abstain, never invent
from dos.effect_witness import EffectClaim, witness_effect
from dos.evidence import gather_evidence, resolve_evidence_source # (b) read-back
# (a) Extract the claim from the agent's terminal text. extract_claims fires only
# on an explicit ID-shaped token or a DOS-CLAIM: marker — free prose yields [].
# That [] is a NO_CLAIM (surface it), not a met effect.
# (b) Gather a read-back from a witness the agent did not author. A real witness
# (a fresh HTTP GET, an OS exit code, a state-snapshot diff) lives in a driver
# registered under the `dos.evidence_sources` entry-point group; resolve it by
# name and run it at the boundary:
source = resolve_evidence_source("<your-witness-name>") # built-in `null` if none wired
facts = gather_evidence(source, subject="<effect key>", config=cfg)
# (c) The effect is met ONLY on CONFIRMED — the join is capped by the read-back's
# accountability (believe_under_floor): a forgeable same-surface read-back
# (AGENT_AUTHORED) is recorded but structurally CANNOT grant belief.
verdict = witness_effect(EffectClaim(key="<effect key>", narrated="<what agent said>"),
(facts,))
# verdict.verdict -> CONFIRMED | REFUTED | UNWITNESSED | NO_CLAIM
# verdict.believe -> True ONLY on CONFIRMED
The load-bearing rule, enforced structurally by believe_under_floor: a read-back
on the forgeable floor (AGENT_AUTHORED — the agent re-reading its own surface, a
pasted receipt, an mtime) is recorded but structurally incapable of granting
belief. So the worst a lying same-surface read-back can do is be ignored, never
manufacture a CONFIRMED. Log the gap, never silently skip it: the first time a
non-git effect needs witnessing and no dos.evidence_sources driver is wired,
emit a one-line log naming the unwitnessed effect — surface it up, never launder
it into "goal met."
Step 3 — The gate's verdict is the stop decision
With the gate wired (Step 1), the runtime already enforces the git-phase rung on every stop. Your job in the screenplay is to keep the agent's claimed effects and the goal's effect-list aligned, and to read the gate's verdict honestly:
- All effects CONFIRMED / SHIPPED → the goal is met. The Stop hook emits
nothing (
{"checked": N, "ok": true}under--json) and the agent stops. This is the only path to "done." - Any effect
source: "none"/ REFUTED → the goal is unmet.dos hook stopemits{"decision": "block", "reason": "…"}, the runtime declines to stop, and the reason is fed back as the next instruction — keep working. The agent does not get to overrule this by asserting completion again. - Any effect UNWITNESSED / NO_CLAIM → you cannot say the goal is met. Surface
it for the operator; do not let the agent stop on an effect no accountable
witness reached. (The git-phase rung fails safe — a
source:"none"is treated as not-shipped, so the gate keeps working rather than passing an unproven claim.)
You can check the gate's reasoning out-of-band, before relying on it, by feeding a synthetic Stop event:
echo '{"transcript_path":"<session.jsonl>"}' | dos hook stop --workspace . --json
# {"ok": false, "reason": "DOS verify: you claimed … shipped, but git has no commit backing it …", "results": [...]}
# ok:false → the goal is NOT met; the agent will be kept working.
# ok:true → every claimed phase is corroborated; the agent may stop.
This is the same out-of-loop check as dos plan --once / dos commit-audit: a
verdict over ground truth, run from outside the loop that wrote the claim.
Anti-patterns
- ❌ Deciding "the goal is met" by re-reading the transcript / the agent's last message. That is consistency, not grounding — the agent judging its own bytes. Decompose into effects and witness each one.
- ❌ Treating "I committed the phase" as the phase shipping. Run
dos verify; asource:"none"means git does not back the claim, regardless of the narration. - ❌ Grepping commit subjects yourself to confirm a ship. The ship-stamp grammar
is
dos.toml[stamp]data the oracle reads — askdos verify, do not re-implement the rung (a subject is forgeable; let the oracle weigh the rung). - ❌ Letting the agent stop on an UNWITNESSED / NO_CLAIM effect "because it probably worked." Abstain surfaces it; it is never a met effect.
- ❌ Wiring
dos hook markerwhen you mean this gate (or vice versa). Marker bounds keep-alive polling; this gate refuses a false done. Opposite triggers. - ❌ Naming a specific lane, plan dir, ship prefix, or witness backend as a
literal — read the active layout from
dos doctor --jsonand resolve witnesses by name.
The one rule under this skill
"The goal is met" is a claim with a byte-author. Let the agent stop only when a witness whose byte-author is not the agent corroborates every effect the goal named. The agent's confidence and its fluent description of success are irrelevant to that gate — which is the whole point: the part that decides the goal is done is never the part being judged.
dos-next-up — the generic plan-and-ship snapshot
This is the baseline screenplay DOS ships, not a prerequisite. It drives the kernel syscalls (
verify,gate) against any repo whose layout lives indos.toml. It names no host directory, no host lane, and no host commit convention — every host specific comes fromdos doctor --json(paths/lanes, via WCR) ordos.toml [stamp](the ship grammar, via SCV). Copy it into your own skills dir, pointdosat your workspace, and it runs.
The shape is domain-free: discover the layout → walk the plans → audit each pick against the truth syscall → render a packet → gate the empty case. The policy (which lanes, which plan grammar, where output lands) is data the screenplay reads, never literals it hardcodes.
Inputs
--scope <name>(repeatable, optional) — narrow candidates to one lane (a name from the active[lanes]taxonomy) or one plan id. Omitted = all plans.--limit <N>(optional, default 5) — how many top picks to render.
Step 0 — Discover the workspace layout (one call)
Run the doctor verb and read the result. This is the WCR on-ramp: every path/lane below comes from here, never a literal.
dos doctor --workspace . --json
Parse the JSON object. The fields you use:
paths.plans_glob— the glob to walk for plan docs (whatever the workspace declared). Use this value; never assume a fixed plans directory.paths.next_packets— where the rendered packet is written (the configured output dir;.dos/verdictsunder the generic default).lanes.concurrent/lanes.exclusive/lanes.trees— the active lane taxonomy, if you need to group picks by lane or honor a--scope.stamp— the active ship-subject grammar (informational;dos verifyapplies it for you — you never grep subjects yourself).
If git is false, warn the operator: dos verify's git rung has no history to
read, so every pick will report source="none" unless a registry exists.
Step 1 — Walk the plans glob → candidate picks
List the plan docs under paths.plans_glob (relative to paths.root). For each
plan doc, read its phase headings to extract (plan_id, phase_id) candidate
pairs — the next not-yet-shipped phases. Keep this generic: a "phase" is a
heading the doc marks as a unit of work; you do not need the job's exact
frontmatter. If a --scope was given, keep only plans/lanes that match it.
Collect a flat list of candidate (plan, phase) picks. Do not rank by any
host-specific signal — order by plan-doc order, then truncate later.
Step 2 — Audit each candidate against the truth syscall
For each candidate pick, ask the kernel whether it already shipped — never trust the plan doc's own stamp, and never grep commit subjects yourself:
dos verify --workspace . <PLAN> <PHASE> --json
Read the ShipVerdict JSON: {shipped, source, sha?, plan, phase}. source
tells you how the kernel knows: registry (a ship row), grep (a commit
subject under the active [stamp] grammar), or none (no positive evidence).
This is the SCV payoff — a foreign repo whose commits read AUTH2: … is
recognized iff its dos.toml declares the matching [stamp].
Classify each pick into one of three dispositions — this is what the gate reads:
shipped: false, source: "none"→ live: a real next pick. Disposition{phase, live: true}.shipped: true, source: "registry"→ done, cleanly: a ship row exists. Disposition{phase, live: false, drop_reason: "shipped"}— drop it.shipped: true, source: "grep"→ a real git ship. Now check the plan doc: does its heading for this phase carry a SHIPPED stamp? If yes, drop it as a clean ship (as above). If no, this is a stale stamp — the work shipped in git but the plan doc lags — and you must encode it so the gate can catch the false-drain:{phase, live: false, drop_reason: "shipped", "ship_via": "direct", "plan_doc_stamped": false}.
The ship_via: "direct" + plan_doc_stamped: false pair is the exact shape
dos gate classifies as STALE-STAMP (a grep ship the plan doc doesn't reflect).
Do not put verify's source value into ship_via — ship_via is the gate's
own direct-ship marker, set to the literal "direct" only for an unstamped git
ship; a registry hit is a clean shipped drop, never STALE-STAMP.
Keep the first --limit live picks as the packet's dispatch list.
Step 3 — Render the dispatch packet
Assemble a self-contained markdown packet yourself (DOS ships no packet
template in the kernel — see the friction log: the [render] packet-template
seam is a named open axis). Write it under paths.next_packets, named
next-up-<UTC-date>-<N>.md. The packet has, generically:
- Header — the workspace root, the active lane taxonomy, the run timestamp.
- Portfolio snapshot — one row per plan: plan id, how many phases, how many verified shipped (from Step 2), the next live phase.
- Dispatch list — for each live pick, a self-contained prompt another agent
could be launched with: the plan id, the phase id, the plan-doc path, and the
one-line goal. Keep each prompt standalone (no shared context). The dispatch
list IS a proposed fan-out partition — if these picks are about to be launched
in parallel, price the partition first with
dos-plan-priceso a colliding set is caught before any agent launches, not when the colliding lease is refused mid-wave. - Already shipped — the picks Step 2 found
shipped: true, withsource/sha.
Alongside the packet, emit the gate sidecar so Step 4 can classify it — write
<paths.next_packets>/.dispositions-<tag>.json with the kernel's contract. One
entry per pick the packet considered, using the Step-2 classification:
{
"schema": "oc3-dispositions-v1",
"tag": "<tag>",
"dispositions": [
{"phase": "AUTH2", "live": true},
{"phase": "AUTH1", "live": false, "drop_reason": "shipped"},
{"phase": "AUTH3", "live": false, "drop_reason": "shipped",
"ship_via": "direct", "plan_doc_stamped": false}
]
}
In this example: AUTH2 is live (a dispatch-list pick); AUTH1 is a clean ship
(verify source was registry, or grep with the plan doc stamped) — a plain
shipped drop; AUTH3 is a stale stamp (verify source was grep but the
plan doc is unstamped) — ship_via: "direct" + plan_doc_stamped: false is what
makes dos gate return STALE-STAMP for it. A clean ship omits both fields (it
must NOT carry ship_via: "direct", or it would be misread as stale).
Step 4 — Gate the packet (typed verdict)
Classify the packet through the kernel so the outcome is a typed verdict, not a prose guess:
dos gate --workspace . <paths.next_packets>/.dispositions-<tag>.json
Read the exit code (the verdict IS the code):
0LIVE — the packet has dispatchable work; report the packet path and the dispatch count. This is the success case.3DRAIN — no live picks: a genuine empty backlog. Report "nothing to dispatch — the portfolio is drained."4STALE-STAMP — phases shipped in git but the plan docs lag. Report the drift (the operator should reconcile the stamps); this is NOT an empty backlog.5BLOCKED — picks exist but are blocked (a sibling claim / quota). Surface.6RACE — a concurrent render lost a lock race; retry once.2— a contract error (the sidecar was malformed). Fix the sidecar; do not treat it as DRAIN.
Step 5 — Return
Print the packet path and the gate verdict. Return the packet path as the
final line so a caller (e.g. dos-dispatch) can chain it:
Saved: <paths.next_packets>/next-up-<date>-<N>.md (verdict=<VERDICT>)
What this skill deliberately does NOT do (no silent gap)
- No soft-claim leasing. It does not register per-pick soft-claims (the heavy
lease core stays host-side,
CLAUDE.mdheavy tier).dos-dispatchtakes a lane lease viados arbitrate; the per-pick soft-claim is out of scope. - No host evidence sources. It does not read a host's curated ranking file or
a postmortem stream — those are host gardening inputs (an evidence-source hook
is a named open seam). It ranks by plan-doc order, audited by
dos verify. - No host packet template. It assembles a generic packet; the exact section
grammar / commit subject a host wants is the
[render]template seam (open).
Log the gap, never silently skip it. The first time the skill would have used
one of these (a soft-claim, a host evidence source), emit a one-line log naming
what it is not doing and why — so the capability gap is surfaced at runtime, not
just documented here.
Worked example (live transcript)
The shape, run for real against a
dosworkspace. Copy-pasteable verbs, actual captured output. The whole point is the last gloss on each block: read the RUNG, not the bareshippedboolean.
Step 0 — discover the layout (the WCR on-ramp):
$ dos doctor --workspace . --json
# dos_version 0.30.0; git true; stamp.style "grep" (generic, any/no dir prefix)
# paths.plans_glob "docs/**/*-plan.md"; paths.next_packets ".dos/verdicts"
# lanes.concurrent [benchmark, docs, examples, scripts, spikes, src, tests]
↳ every path/lane below is read from this object — never a literal.
Step 2 — audit a pick that DID ship. Read the source rung, not just shipped:
$ dos verify --workspace . docs/82_liveness-oracle-plan liveness --json
{"phase":"liveness","plan":"docs/82_liveness-oracle-plan","rung":"direct","sha":"80d4f30","shipped":true,"source":"grep-subject","summary":"80d4f30 liveness: exclude the BIRTH acquire from the ADVANCING event count"}
↳ RUNG source="grep-subject" (NOT bare grep): a commit SUBJECT carrying the
phase token flips this to SHIPPED even if little was built. Read the rung.
Step 2 — and a pick that has NOT shipped:
$ dos verify --workspace . docs/99_runtime-validation-and-the-actuation-boundary halt --json
{"phase":"halt","plan":"docs/99_runtime-validation-and-the-actuation-boundary","shipped":false,"source":"none"}
↳ RUNG source="none": no positive git/registry evidence → a live pick.
Step 4 — gate the packet; the verdict IS the exit code:
$ dos gate --workspace . .dos/verdicts/.dispositions-<tag>.json ; echo "exit=$?"
exit=0 # LIVE — dispatchable work (3=DRAIN, 4=STALE-STAMP, 5=BLOCKED, 6=RACE, 2=contract-error)
↳ exit-code 0 carried the verdict — LIVE, not a prose guess.
Anti-patterns
- ❌ Hardcoding a plans directory or an output directory — read both from
dos doctor --json(thepathsobject). - ❌ Greping commit subjects for a ship marker yourself — call
dos verify(it applies the active[stamp]grammar for you). - ❌ Treating a 0-pick packet as "drained" without
dos gate— a STALE-STAMP is a false drain, and only the typed gate distinguishes it. - ❌ Naming a specific lane as a literal — read the active
lanesfrom doctor.
dos-plan-price — price the fan-out before you launch it
DOS is a court; this skill asks it to quote a price first. Every other DOS trust surface reads the past or present tense:
verifyreads a commit that already shipped,arbitraterefuses a colliding acquire as the worker reaches the turnstile. A court rules after the collision. But the cheapest moment to catch a colliding fan-out is before any worker runs — and the kernel's own file-tree geometry can answer that forward question with zero new trust: the partition's overlap is a fact about glob prefixes, decidable without believing any agent's intent (docs/347, the predictive flip). This skill prices the proposed partition so a bad plan is refused with 0 agents launched, instead of the reactive court launching K-1 workers before the Kth acquire collides.
The shape is domain-free: discover the layout → collect the proposed partition →
price it from the un-authored geometry → act on the price → fall back to the
reactive lease floor. The policy (which lanes exist, where things live) is data
read from dos doctor --json, never literals.
When to use this (and when not)
- Use it right before a fan-out: a
dos-goal-fleetwave, ados-next-uppacket's dispatch list, or any "launch N agents over these trees" moment. The dispatch list IS a proposed partition; price it before you spend the launches. - Do not use it for a single agent (N=1 has no partition to price — the price
is trivially 0), or as a substitute for
dos arbitrateat acquire time. The price is a forward estimate; the lease arbiter is the unforgeable floor. This skill runs ahead of the floor, it does not replace it. - This is a layer-3 helper / screenplay (a PDP, docs/99). It mints no new verdict; it reads the kernel's pure geometry and narrates the price. The geometry is the judgment; this skill is the narrator.
The honest seam — no first-party verb yet (read this before Step 2)
There is no dos price-plan CLI verb today (it is filed as issue #178). The
un-forgeable primitive the price stands on IS shipped: dos._tree.lane_trees_disjoint,
the same agent-blind prefix geometry dos arbitrate already trusts. The reference
implementation that lifts that pairwise predicate into a whole-partition price is
the kernel's own experiment, examples/plan_price/plan_price.py (a clean
price_plan(agents) -> PlanPrice API and a --json main; docs/347).
So this skill shells/imports that example as the interim primitive and emits a
one-line log naming the gap — exactly the docs/345 discipline for a step whose
first-party verb does not exist yet. It never pretends a dos price-plan verb is
there. If the example (or the kernel) is absent, the predictive step degrades to
advisory and you fall straight to Step 4 (the dos arbitrate floor), which is
always available.
Step 0 — Discover the workspace once (the WCR on-ramp)
dos doctor --workspace . --json
Stash it. The fields this skill uses:
lanes.trees— the active lane→file-tree map. If a proposed worker is named by a lane rather than an explicit tree, resolve its tree from here (never a literal).paths.root— so declared trees are workspace-relative, comparable by the geometry.git— informational; the price needs no git history (it reads the proposed partition, which has no commits yet — that is the whole point).
Step 1 — Collect the PROPOSED partition
Build the list of agents the fan-out is about to launch, each with the file-tree it would be handed (globs). The source is whichever planner you are gating:
- A
dos-goal-fleetwave → one entry per objective, its declared scope. - A
dos-next-uppacket → one entry per dispatch-list pick, the plan's load-bearing files as its tree. - An operator's hand-written "these N agents over these trees" → as given.
Each entry is {name, tree: [glob, ...]}. An agent whose tree you cannot resolve —
an empty/unknown blast radius — is kept with an empty tree on purpose: the
geometry will (correctly, conservatively) price it as colliding with everything,
which is the signal "name this worker's scope before you launch it."
Step 2 — Price the partition BEFORE launch
Compute the price from the un-authored geometry. Shell the interim primitive and log the gap in the same breath:
# interim — no `dos price-plan` verb yet (#178); the example lifts the shipped
# `dos._tree.lane_trees_disjoint` predicate into a whole-partition price.
python examples/plan_price/plan_price.py --json
…or, for your own partition rather than the example scenarios, import the API:
from plan_price import Agent, price_plan # examples/plan_price/
price = price_plan([Agent(name, tree) for name, tree in proposed])
Then emit the gap note so it is surfaced at runtime, not just documented here:
log: predictive price is example-backed (examples/plan_price) pending the
first-party `dos price-plan` verb (#178); the underlying predicate
(dos._tree.lane_trees_disjoint) is the shipped kernel geometry.
The price (PlanPrice) carries:
collisions— the proposed pairs that provably overlap (one is a prefix of the other in the prefix algebra). These are the launches you must not spend yet.max_concurrency+safe_now— the largest set of proposed agents that can run at once with no collision (the maximum independent set on the collision graph), and their names. This is the honest "how many of these N can actually run together" — a number the per-acquire arbiter never computes.repartition— for each colliding agent, the narrowest private subtree that would clear it. A geometric suggestion (it cannot know the agent's true intent), so treat it as the shape of the fix, not the fix.expected_rework— a transparent contention price (monotone in collisions); ordinal, not a calibrated cost (calibration is #179).
Step 3 — Act on the price (the court → oracle move)
This is the value. Branch on the price before launching:
- 0 collisions → launch the full fan-out. The price added no friction (the falsifier: when the partition is truly disjoint, the lift is exactly 0).
- ≥1 collision → do not launch the colliding plan. Pick one:
- Launch only
safe_nowthis wave (the maximal disjoint set), and hold the colliding agents for a later wave; or - Apply the
repartitionsuggestion (narrow the colliding trees), re-run Step 2, and launch once the price is 0.
- Launch only
Either way you have refused the bad plan with 0 agents launched. Contrast the reactive court (Step 4): admitting agents one at a time, it only refuses when the colliding acquire arrives — by which point the earlier agents have already launched and are mutating the tree. The measured gap (docs/347): on a 4-agent plan with one hidden overlap, the reactive court launches 2 agents before it can refuse; the price refuses with 0.
Step 4 — The reactive floor still applies (EXAMPLES.md R2, dos arbitrate)
Pricing the plan does not replace the lease floor. Every worker still takes its lane lease at acquire time — the unforgeable check over the leases actually held:
dos arbitrate --workspace . --lane <lane> # honor the verdict; redirect on refuse
Be explicit about why both exist: the predictive price is a forward estimate over an
agent-declared (and therefore forgeable) partition — it reduces wasted launches
and surfaces the collision early, but it is not a guarantee. dos arbitrate over the
real WAL leases is the floor that cannot be talked around. Price first to save the
launches; arbitrate at acquire to be safe.
Step 5 — Return
Print the price and the recommended action, so a caller (dos-goal-fleet,
dos-next-up) can chain it:
Priced <N> agents: <C> collisions, max safe concurrency <M> (run now: <safe_now>).
Action: <LAUNCH_ALL | LAUNCH_SAFE_SET | REPARTITION_AND_REPRICE>.
Return the action as the final line so the launch step branches on it, not on prose.
What this skill deliberately does NOT do (no silent gap)
- No first-party verb. It shells
examples/plan_pricebecausedos price-plan(#178) is not built. It logs that gap every run rather than faking the verb. - No semantic collision detection. The price is geometric — it catches two
trees that overlap by prefix, not two disjoint trees whose intents conflict
(the docs/347 §5 ceiling, shared with
arbitrate). It moves collision latency earlier; it does not widen what geometry can see. - No leasing. It computes a price; it journals no lease. The lease is
dos arbitrate's job at acquire time (Step 4). The price is advisory until then.
Log the gap, never silently skip it. The first time the skill prices a partition
without the first-party verb, emit the one-line log from Step 2 — so the capability
gap is visible at runtime, not just here.
Anti-patterns
- ❌ Launching a plan the price flagged as colliding "because arbitrate will catch it anyway". That is the reactive court — you spend the launches you could have saved. Price first; launch the safe set or re-partition.
- ❌ Treating the price as the unforgeable floor and skipping
dos arbitrateat acquire. The price is a forward estimate over a forgeable declared partition; the lease arbiter is the floor. Do both. - ❌ Faking a
dos price-plancall. The verb does not exist yet (#178) — shell the example and log the gap. - ❌ Naming a specific lane or path as a literal — resolve trees from
dos doctor --json(lanes.trees). - ❌ Pricing a single agent. N=1 has no partition; the price is trivially 0.
dos-promote — surface every held unit + its unblock action
Make the invisible pickable. The picker silently drops a unit it cannot offer;
/dos-promotedoes the inverse — it runs the pre-dispatch gate (dos pickable) over every declared unit, and for each one that is HELD it surfaces the unit, its typed hold reason, and the derived unblock action. The hold reason → action routing is data, not a guess: aDRAFT_CLASShold wants a promotion, aSOAK_OPENhold wants the clock, anOPERATOR_GATEDhold wants a decision. This is the operator-facing half of the shippedpickableprimitive.
The shape: enumerate the units → gate each → route each hold to its action →
auto-enact only the safe mechanical reclassify → surface the rest. The gate and
the enumeration are kernel verbs (dos pickable, dos enumerate); the
reason→action routing is derivable from the HoldReason itself.
Inputs
--scope <lane>(optional) — limit to one lane from the active[lanes]. Omitted = every declared unit the workspace can see.
Step 0 — Discover the layout
dos doctor --workspace . --json
Read paths.plans_glob (where the plan docs live), lanes (the taxonomy), and
lifecycle.classes (the declared class set — which class is the workspace's
"draft" / "active"). Use these; never hardcode a plan path or a class name.
Step 1 — Enumerate the declared units
For each plan doc under paths.plans_glob, enumerate the units it declares:
dos enumerate <plan-doc> --json
Read units (the universe), remaining (the not-yet-shipped), and drift — a
drift[kind=unparseable] is itself a held-by-UNPARSEABLE signal (the
picker-invisibility cure: a typed refusal, never a silent drop). Collect the
remaining units across all plans as the candidate set.
Step 2 — Gate each candidate (the pre-dispatch verdict)
For each remaining unit, run the pre-dispatch gate over the unit's host-gathered state (its plan class, soak index, live claims):
dos pickable <UNIT> --state '<json>' --json
Branch on the exit code (the verdict IS the code — distinct per hold):
0OFFERABLE → a worker could pick it up now; NOT surfaced (it is not stuck).10DRAFT_CLASS → the plan is draft-class; the unblock is a promotion.11OPERATOR_GATED → blocked on a decision; raise it.12SOAK_OPEN → a soak deadline; wait (never promote — time un-gates it).13DEPENDENCY_UNMET → ship the prerequisite first.24UNPARSEABLE → inspect/fix the deriver or the doc; the unit is invisible.20–23IN_FLIGHT / SOFT_CLAIMED / STALE_CLAIM / COOLDOWN → a live/transient hold that clears on its own; surface as info, no action.
Step 3 — Route each hold to its unblock action (data, not a guess)
The action is derived from the typed HoldReason, not re-discovered per unit:
| Hold | Unblock action |
|---|---|
DRAFT_CLASS | promote the plan draft→active (the workspace's lifecycle default→next class) |
OPERATOR_GATED | raise an operator decision (dos decisions add) |
SOAK_OPEN | wait for the soak to close — surface the deadline, do NOT promote |
DEPENDENCY_UNMET | ship the named prerequisite first |
UNPARSEABLE | inspect the deriver / backfill the doc's phase grammar |
A host may declare a richer reason→action map in dos.toml; absent one, this
default routing (documented on the HoldReason enum) is used.
Step 4 — Auto-enact ONLY the safe mechanical reclassify
The single auto-applied action is the DRAFT→active promotion of a plan whose
draft phases are demonstrably wanted — a mechanical plan-meta classification:
edit + ONE commit, gated. Read the trunk + ship grammar from dos doctor --json's
stamp; do not hardcode a commit prefix. Everything else — a decision, a
soak wait, a dependency, an unparseable doc — is surfaced for a human, never
auto-applied (those are real judgment calls).
Step 5 — Surface the rest
dos decisions add # one row per held unit that needs a human
What this skill deliberately does NOT do (no silent gap)
- No auto-decision / auto-dependency-ship. Only the mechanical reclassify is auto; an OPERATOR_GATED / DEPENDENCY_UNMET hold is a human's call.
- No soak fast-forward. A SOAK_OPEN hold is surfaced with its deadline; the loop NEVER promotes past a soak (time is the only thing that un-gates it).
- No host class taxonomy. The draft/active classes come from
lifecycle.classes; a 2-class repo and a job-shaped repo both run this skill.
Anti-patterns
- ❌ Promoting a SOAK_OPEN unit — a soak is un-gated by the clock, not a promotion; promoting it re-introduces the very drain-trap the typed hold prevents.
- ❌ Auto-resolving an OPERATOR_GATED hold — that decision is the operator's.
- ❌ Hardcoding "DRAFT"/"ACTIVE" — read the class set from
dos doctor --json'slifecycle.classes.
dos-replan-loop — the generic recurring planning sweep
The thin loop. It is mostly sequencing: run
/dos-replan, run an optional auto-commit/release contract, increment a counter, schedule the next wakeup, and stop at the iteration cap. The one thing it must get right generically is the release guard — it reads the workspace's trunk from config, not a hardcoded branch name. (This repo's trunk ismaster, notmain— exactly the kind of host fact the guard must read, not assume.)
Inputs
--interval <seconds>(optional, default 600 — 10 minutes).--max-iterations <N>(optional, default 20).
Step 1 — First entry
Set the iteration counter to 1. Record the pre-existing dirty state of the tree
(so the auto-commit guard can tell what this sweep changed). Invoke the
/dos-replan Skill.
Step 2 — After /dos-replan finishes: the guarded release contract
If /dos-replan made garden-only writes, optionally commit + release them — but
only behind the guard. The guard reads the trunk from config, not a literal:
dos doctor --workspace . --json
There is no trunk field in the doctor report today (it is a host fact); resolve
it the generic way: git symbolic-ref --short refs/remotes/origin/HEAD (the
remote's default branch). Fail closed: if that cannot be resolved (no
origin/HEAD — common in fresh clones / CI checkouts), treat the trunk as
UNKNOWN and skip the release entirely (record the sweep only). Do NOT fall
back to "the current branch" — that would make the on-trunk check below trivially
true on any branch and let an auto-commit proceed off-trunk. Then the guard fires
only when ALL hold:
- the trunk is positively known (resolved above, not UNKNOWN), AND HEAD is
on it (the resolved default branch —
masterhere,mainelsewhere; never hardcode either). - the working-tree changes are docs/state-only (the replan queue + cooldown state, nothing in code).
- there is something to commit (a productive sweep).
If the guard passes, commit the garden writes with a generic subject and (if the
host wants it) call /release. If any condition fails — including an UNKNOWN
trunk — skip the release and just record the sweep — do not push code, do not
commit off-trunk.
Increment the counter; if it is below --max-iterations, schedule the next
wakeup --interval seconds out; else stop.
Step 3 — On wakeup re-entry
Parse the counter from the prior iteration, run /dos-replan, and re-run Step 2
again. Stop when the counter reaches --max-iterations.
The outer ratchet for this loop (docs/351)
This loop's "am I producing a witnessed net gain, or just spinning?" ratchet
already exists as the kernel's REPLAN_STALLED stop (loop_decide / docs/258,
#506): K consecutive UNPRODUCTIVE /dos-replan sweeps — replans that refilled or
gardened nothing — stop the loop and surface, because a sweep that did costly
nothing twice will not on a third identical pass. That IS the docs/351 outer ratchet
for a planning loop: its net gain is gardening/refill (a different metric than the
dispatch loop's reconcile-VERIFIED ship-count), so it does NOT fold under the
improve keep-gate — REPLAN_STALLED is its shaped equivalent. Same doctrine
across the loop roster: a loop that is running but not improving stops and hands
the judgment back, rather than burning the cap (the dispatch loop names this
not-ratcheting; this loop names it REPLAN_STALLED).
What this skill deliberately does NOT do (no silent gap)
- No hardcoded trunk. It resolves the default branch from git, so a
mastertrunk and amaintrunk are both handled — the SKP Phase 4 litmus. - No host release ceremony. The generic loop commits garden writes and
optionally calls
/release; it does not build artifacts or run a host's bespoke promotion gate (those are host/dev tooling, outside this loop).
Worked example (live transcript)
One replan cycle. The loop re-runs
dos verifyover the portfolio each cadence, then letsdos gatedecide DRAIN-vs-continue by exit code — the typed verdict, never the prose. Read the rung (source) and the code, not the headline.
$ dos doctor --workspace . --json | python -c "import sys,json;d=json.load(sys.stdin);print(d['paths']['plans_glob'])"
docs/**/*-plan.md
The WCR on-ramp: the portfolio is whatever matches plans_glob — host fact, read from config, not assumed.
$ dos verify --workspace . docs/82_liveness-oracle-plan liveness --json
{"phase":"liveness","plan":"docs/82_liveness-oracle-plan","rung":"direct","sha":"80d4f30","shipped":true,"source":"grep-subject","summary":"80d4f30 liveness: exclude the BIRTH acquire from the ADVANCING event count"}
SHIPPED via the grep-subject rung (exit 0) — a commit SUBJECT carrying the phase token flips it green; read the rung, not the bare verdict.
$ dos verify --workspace . docs/99_runtime-validation-and-the-actuation-boundary halt --json
{"phase":"halt","plan":"docs/99_runtime-validation-and-the-actuation-boundary","shipped":false,"source":"none"}
NOT_SHIPPED via the none rung (exit 1) — git ancestry has not stamped it; this phase is still in flight.
$ dos gate dispositions.json ; echo "exit=$?"
exit=3
dos gate returns the typed exit code: 3 = DRAIN (LIVE=0, DRAIN=3, STALE-STAMP=4, BLOCKED=5, RACE=6). Exit 3 means stop taking new work and let the in-flight phases settle this cycle — continue (LIVE=0) otherwise.
$ dos arbitrate --workspace . --lane src
{"auto_picked":true,"free_clusters":[],"lane":"benchmark","lane_kind":"cluster","outcome":"acquire","pick_count":null,"reason":"auto-picked free cluster lane benchmark (requested src was refused: lane src would edit the orchestrator's own running code … (SELF_MODIFY) …).","tree":["benchmark/**"]}
You asked for src; the arbiter handed back benchmark (exit 0, outcome:acquire) — the admission conjunction refused the hint (here SELF_MODIFY; a lane contended by a live lease redirects the same way) and the kernel named the real reason rather than double-book or false-narrate. A free, admissible lane you name is granted directly.
Anti-patterns
- ❌ Assuming the trunk is
main— resolve it; this repo's ismaster. - ❌ Committing off-trunk or committing code changes — the guard is docs/state + on-trunk only.
- ❌ Looping unbounded — the iteration cap is the stop; honor it.
dos-replan — the generic portfolio gardening sweep
The planning refresh that keeps the loop honest. Its domain-free core is small: a queue item whose phases now
dos verifyas shipped is closed; the operator should see only the 0-2 items that truly need a human. The heavy host-specific gardening passes (anchor reconciliation, soak-state drift, the postmortem evidence stream) are host driver hooks, scoped OUT of the generic baseline. Closure detection rides the truth syscall; the operator surface is thedos decisionsqueue.
The shape: read the queue → close what verifies as shipped → rank what's left →
surface only what needs a human. Closure is a kernel call (dos verify); the
operator inbox is the kernel's decisions projection.
Inputs
--force(optional) — run even if the no-op skip gate would fire (no new evidence since the last sweep).
Step 0 — Discover the layout
dos doctor --workspace . --json
Read paths (where the queue/cooldown state live) and stamp (the active ship
grammar dos verify applies). Read the active trunk from config if you will
gate a release later (see /dos-replan-loop).
Step 1 — No-op skip gate
If there is no new evidence since the last sweep (no new commits, no new findings)
and --force was not given, print one line and exit cheap — writing nothing.
This is the gate that keeps a recurring loop from doing 0-work sweeps; an
unproductive replan (this skip, or a 0/0/0 sweep) must NOT arm the loop's
drained-twice trigger (the kernel loop decision enforces that — report the
productivity honestly so /dos-dispatch-loop reads it right).
Step 2 — Closure detection (the domain-free core, via the truth syscall)
For each open item in the queue, ask the kernel whether its phases have shipped:
dos verify --workspace . <PLAN> <PHASE> --json
If every phase of a queue item now reports shipped: true, the item is closed
— move it from the open queue to the closed section. Never trust the plan doc's
own stamp; the truth syscall is the source. This is the auto-close pass that
keeps the queue from carrying already-shipped work as if it were pending.
Count the closures — this is part of the productivity signal Step 5 reports.
Step 3 — Cooldown-state tracking
Bump the cooldown timestamp in the configured state file so /dos-next-up knows
when this sweep last ran (the cooldown banner). Generic, no host specifics.
Step 4 — Rank what's left
Order the remaining open items by a domain-free signal (recency, how many phases remain). Do not impose a host's bespoke ranking — that's a driver hook.
Step 5 — Surface only what needs a human (the operator inbox)
The ruthless filter: of everything you swept, at most 0-2 items should reach
the operator — the ones no mechanism can resolve (a real decision-needed). The
kernel's operator inbox is the dos decisions queue; read it to see what is
already pending so you don't duplicate a row:
dos decisions --workspace . --json
The dos decisions projection is the generic operator inbox: a HUMAN-resolvable
row is one a mechanism (an ORACLE/JUDGE) cannot close.
Honesty about the write path (a named open seam). dos decisions is
read-only today — there is no generic dos verb to append a decision-needed
row (the queue's write path, home.append_decision, is currently reached only by
dos arbitrate --force's override capture). So the generic baseline surfaces
the 0-2 items in its operator summary (Step 6) and reads the existing queue here;
emitting a new decision row into the queue is a host/driver capability (the
named open seam — see docs/74-friction-log.md). Do not imply dos decisions
writes; it lists and drills in.
Step 5b — Concrete findings go to the issue tracker, not the inbox
A sweep surfaces more than closures: a bug in another lane, a missing test, a
doc that drifted from the code. The 0-2 operator slots are for decisions; a
concrete, public-subject finding with a checkable done-condition is work, and
its durable home is the workspace's public issue tracker (on a GitHub-hosted
repo, the gh CLI) — not the inbox, not a memory file, not silence. The filing
discipline is /dos-dispatch's "Out-of-scope findings" section: dedupe
first (gh issue list --search "<keywords>"); give the body a checkable
done-condition, a lane guess, and where you found it; leak-check the
drafted body before posting (issue text is public output no tracked-file gate
scans — no machine-absolute paths, hostnames, or personal identifiers; if the
workspace ships a publication leak-scanner, pipe the draft through it and treat
a hit as a refusal). An issue closes only via Fixes #N in the body of the
commit that resolves it — never gh issue close off your own narration.
Step 6 — Emit the operator summary
Print a terse summary: how many items closed (Step 2), how many remain, and the
0-2 that need a decision (with a pointer to dos decisions). Report the
productivity verdict honestly (PRODUCTIVE iff it closed/refilled/gardened
anything) — /dos-dispatch-loop reads this to decide drained-twice.
What this skill deliberately does NOT do (no silent gap)
- No host gardening passes. Anchor reconciliation, soak-state drift, the
postmortem evidence stream, gitignore drift — those are host-specific evidence
surfaces, scoped OUT of the generic baseline (a driver hook, or out of scope).
The generic sweep does closure detection + the operator surface, and
logs what it is skipping. - No host inbox file. It writes to the kernel's
dos decisionsqueue — the generic operator-inbox surface — not a host-specific pending-decisions file.
Worked example (live transcript)
The stale-stamp catch. A queue item points at a plan whose phase the doc still narrates as in-flight — but the grep rung sees a commit subject carrying the phase token, so
dos verifyflips it SHIPPED. Read the rung, not the bare verdict, then reconcile the queue.
Step 0 — discover the layout (the on-ramp every sweep runs):
$ dos doctor --workspace . --json
... "stamp": {"style": "grep", "grammar": "generic (any/no dir prefix)"} ...
... "exit_codes": {"gate": {"LIVE": 0, "DRAIN": 3, "STALE-STAMP": 4, "BLOCKED": 5, "RACE": 6}} ...
Step 2 — closure detection. Ask the truth syscall, never the plan doc's own stamp:
$ dos verify --workspace . docs/82_liveness-oracle-plan liveness --json
{"phase":"liveness","plan":"docs/82_liveness-oracle-plan","rung":"direct","sha":"80d4f30","shipped":true,"source":"grep-subject","summary":"80d4f30 liveness: exclude the BIRTH acquire from the ADVANCING event count"}
Verdict carried by the source: grep-subject rung — a commit SUBJECT containing
the phase token flips this to SHIPPED even if little was built. The doc lagging the
git fact IS the stale stamp; close the item from this rung, not from the doc.
Contrast — an item still genuinely in flight returns the none rung:
$ dos verify --workspace . docs/99_runtime-validation-and-the-actuation-boundary halt --json
{"phase":"halt","plan":"docs/99_runtime-validation-and-the-actuation-boundary","shipped":false,"source":"none"}
Step 6 reconcile — feed the dispositions to the gate; a stale stamp returns exit 4:
$ dos gate ./dispositions.json ; echo "exit=$?"
exit=4
gate exit 4 = STALE-STAMP — the plan doc lags the verified git fact; the
replan's reconciliation is to close the over-claimed item against the grep-subject
rung and drop the doc's self-narrated status. (Exit 0 = LIVE, 3 = DRAIN, 5 = BLOCKED.)
Anti-patterns
- ❌ Closing an item from its plan-doc stamp — close from
dos verifyonly. - ❌ Surfacing more than 0-2 items — the operator surface is ruthless by design; everything a mechanism can resolve stays out of it.
- ❌ Reporting an unproductive sweep as productive — it would arm a false drained-twice stop in the loop. Report honestly.
- ❌ Parking a concrete finding in the operator inbox (or dropping it) — the inbox is for decisions; file the finding as an issue with a done-condition.
dos-self-improve — the loop where DOS adjudicates its own improvement
The first self-improving work loop for DOS. It proposes a change, checks it, measures it, and keeps it only if a witness the change's author did not write confirms it improved — the green suite on a clean worktree, the truth syscall, and a strictly-measured metric gain. Everything else is reverted. The keep decision is the kernel's
improveverdict, not the loop's opinion of its own work. A run of candidates nothing accepts trips a breaker that hands the judgment back to a human.
This is the dispatch loop (/dos-dispatch-loop) turned inward on a codebase's
own source, with the one rule no prior auto-improver enforced:
A self-improving loop's fatal failure mode is grading its own homework — the agent that wrote the change is the same one that says "yes, this is better," so it learns to narrate improvement instead of making it.
dos improvecloses that hole: the keep-bit is a pure function of facts the loop did not author, so the loop cannot keep a change by claiming it is better. The only path to KEEP is to actually move a metric the environment measures.
The recursive-self-improvement literature names verification as the gating constraint ("requiring verification regimes enabling labs to confirm"; "human judgment on which problems matter remains the bottleneck"). This loop is that verification regime, with the human kept in the loop by construction — the breaker escalates to a person exactly when the loop runs dry of witnessed improvements.
What the kernel decides vs. what you do
| Step | Who | What |
|---|---|---|
| Propose one scoped change | YOU (a subagent) | the capable, untrusted step — the only place intelligence enters the loop |
| Verify + measure | dos verbs | run the suite, run the truth syscall, measure the metric — all on an isolated worktree |
| Keep / revert / escalate | dos improve | the kernel's typed verdict over the env-authored facts — NOT your opinion |
| Merge / discard / escalate | YOU | carry out the kernel's verdict |
The kernel contributes ZERO intelligence to the proposal — only the refusal to keep an unwitnessed one. That asymmetry is the whole design.
Inputs
--metric <name>(required) — what "improvement" means for THIS workspace, as a non-negative integer the environment measures, higher = better. The reference metric islint-clean= a large constant minus thedos lintfinding count (driving dead policy to zero); other honest metrics: a passing-property-test count, a coverage percent, a negated wall-clock budget. The kernel does not know the unit — it only compares magnitudes (theproductivity/efficiencywork-unit split).--max-cycles <N>(default 5) — the backstop cap (theITERATION_CAPanalogue).--max-reverts <N>(default 3) — ESCALATE to a human after this many candidates in a row that nothing accepted (the breaker).--lane <name>(optional) — the lane to take; a bare loop auto-picks a free one.
Step 0 — Pre-flight: take a lane, record the GREEN baseline
dos doctor --workspace . --json
dos arbitrate --workspace . --lane <LANE>
RID=$(dos run-id mint dos-self-improve \
| python -c "import sys,json;print(json.load(sys.stdin)['run_id'])")
RID is the loop's correlation run-id — pass it (with --observe) on every
dos improve call below so the kernel records each cycle under THIS loop, and an
operator (or DOS) can watch the whole trajectory live with dos observe --loops
(docs/383). A long RSI run is otherwise dark while it runs: without --observe the per-cycle
verdict evaporates and the only artifact is the final loop record (Step 5).
Then establish the baseline — and this gate is non-negotiable:
python -m pytest -q # MUST be green to start
<measure the metric> # e.g. dos lint --workspace . --json | (1000 - finding count)
You cannot measure improvement from a red baseline. If the suite is red, STOP
and surface it — fix the suite first (that itself is a separate, ordinary task,
not a self-improvement cycle). Record the baseline metric B.
Step 1 — Per cycle: propose ONE candidate in an ISOLATED worktree
The candidate edit is the SELF_MODIFY / global-lane hazard
([[self-modification-hazard]]): editing the kernel's own running path is exactly
what the arbiter refuses, and what would let a candidate rewrite the kernel that is
adjudicating it. So work in an isolated git worktree, never the live tree:
git worktree add ../_si-candidate HEAD
Spawn ONE subagent with a tight brief, working in that worktree:
Improve exactly ONE thing in this codebase that will move
<metric>. Make the SMALLEST diff that moves it. Do not touch tests to make them pass; do not weaken an assertion. Commit your change with a clear subject. Return what you changed and why. If you cannot find a real improvement, say so — do not invent one.
One candidate per cycle keeps the witness attributable (the commit-audit "one
commit, one claim, one diff" discipline). If the subagent returns "nothing to
improve," the cycle is a skip — not a revert; move on.
Step 2 — Gather the env-authored witnesses (on the worktree)
Every fact the kernel reads is measured by the ENVIRONMENT, never taken from the subagent's word:
# (1) the suite, on the candidate-only worktree — the runner authors the bit
cd ../_si-candidate && python -m pytest -q ; SUITE=$?
# (2) the truth syscall — git ancestry, the oracle authors the bit
dos commit-audit --workspace ../_si-candidate HEAD # claim vs its own diff
# (and, if the candidate claims a plan phase, dos verify it)
# (3) the metric, re-measured on the worktree AFTER the candidate
<measure the metric on ../_si-candidate> # → W
# (4) the tokens the subagent spent (the provider usage record) → T
A missing witness is a FAILING witness — if you cannot run the suite or the truth syscall, treat it as red/dirty (fail-safe). Never substitute the subagent's "tests pass" claim for the runner's exit code.
Step 3 — Ask the kernel: KEEP / REVERT / ESCALATE (the kernel decides)
This is the load-bearing step: the decision is a kernel mechanism, not prose.
dos improve --workspace . \
$( [ "$SUITE" -eq 0 ] && echo --suite-passed ) \
$( <truth clean> && echo --truth-clean ) \
--work "$W" --baseline-work "$B" --tokens "$T" \
--consecutive-reverts "$REVERTS" --max-reverts <N> \
--narrated "<the subagent's description>" \
--observe --run-id "$RID" --subject "cycle-$CYCLE" --json
The last line is the observability wiring (docs/383): --observe records this
verdict to the journal, --run-id "$RID" groups it with the rest of THIS loop, and
--subject "cycle-$CYCLE" tags the iteration — so dos observe --loops can fold the
loop's metric curve, breaker distance-to-escalate, and liveness while it runs.
The verdict IS the exit code — branch on it, do not re-read the prose:
0KEEP — suite green, truth clean,W > B(a strict env-measured gain), and not wasteful. The improvement is witnessed. Go to Step 4-KEEP.3REVERT — either a REGRESSION (suite red / truth dirty — the non-negotiable floor) or a NO-OP (safe butWdid not beatB). Go to Step 4-REVERT.4ESCALATE — the breaker is open (--max-revertsnon-keeps in a row). Go to Step 4-ESCALATE and STOP.
The --narrated text is carried for the operator and parsed for nothing — it
cannot move REVERT → KEEP (docs/234). Do not try to argue a candidate into a keep;
make the metric move or revert it.
Step 4 — Carry out the verdict
- KEEP — merge the worktree commit onto the lane, then RAISE the baseline to
W(the ratchet — the next candidate must beat the improved tree, not the original) and reset the revert count to 0:git merge --ff-only <candidate-sha> # or cherry-pick onto the lane B=$W ; REVERTS=0 - REVERT — discard the worktree candidate; the live tree is untouched. Bump the
revert count (
REVERTS=$((REVERTS+1))). The baseline is unchanged.git worktree remove --force ../_si-candidate - ESCALATE — discard the candidate, then file a human decision and STOP the
loop (the loop has run dry of witnessed improvements; a person decides what
matters next):
dos decisions ... # surface the escalation with the kernel's reason
Then re-create a fresh worktree for the next cycle (off the now-possibly-advanced
lane HEAD) and return to Step 1, until KEEP/REVERT cycles reach --max-cycles or
an ESCALATE stops the loop.
Step 5 — Archive + release
When the loop stops, write a loop record under paths.runs (the per-cycle
verdicts, the kept/reverted/skipped counts, the final baseline — the high-water
mark that measures how much the loop improved the codebase, and the stop reason),
and release the lane lease. Commit any kept improvements with a generic subject
read from config — no hardcoded prefix.
Watch it live (any time during the run). Because each cycle was --observed under
$RID, an operator or a supervising agent can fold the loop's trajectory from the
kernel's own verdict stream — no need to ask the loop how it is doing (docs/383):
dos observe --loops # every RSI loop: iteration, metric curve, breaker, liveness
dos observe --loops --run "$RID" # THIS loop's full per-cycle curve
A loop reads ACTIVE (a fresh cycle landed), STALLED (no cycle within the window —
wedged), or ESCALATED (the breaker handed back to a human). The metric high-water and
the breaker N/max distance-to-escalate come straight from the env-authored verdicts,
never the candidate's self-assessment.
Why this is the honest version of recursive self-improvement
- The keep-bit reads four env-authored facts — the suite exit, the truth syscall, the metric before, the metric after — and zero loop-authored bytes. A loop that learns to write "great improvement" in every commit gains exactly zero keep-probability, because the claim is not in the decision.
- The loop's default action on an unwitnessed candidate is undo, not keep — the abstention-first discipline at loop scale.
- The breaker escalates to a human precisely when the loop cannot find a witnessed improvement — the RSI literature's irreducible bottleneck, made a kernel rule rather than a hope.
What this skill deliberately does NOT do (no silent gap)
- No open-ended autonomy. The bound is the breaker + the cap; the loop terminates into a human decision, by construction. It does not run unbounded.
- No metric the loop can game. The metric must be measured by the environment
on the worktree, not reported by the subagent. A metric the subagent computes
about itself is back to grading its own homework —
logand refuse such a metric. - No test-weakening. A candidate that makes the suite pass by deleting an assertion REGRESSES the truth syscall / will be caught by a metric that counts real coverage; the brief forbids it and the green-suite floor is on the FULL suite, not a subset.
Anti-patterns
- ❌ Believing the subagent's "it's better" — re-measure every fact; only
dos improveover env-authored witnesses decides KEEP. - ❌ Editing the live tree — always work in an isolated worktree; the kernel adjudicating a candidate must not be the kernel being rewritten by it.
- ❌ Measuring improvement from a red baseline — fix the suite first; you cannot measure a gain you cannot see.
- ❌ Re-running a candidate the kernel reverted with a better-sounding commit message — the message is not in the decision; make the metric move.
dos-setup — confirm the plugin is wired, then point at the next move
The plugin ships JSON + markdown; the brains ship as a pip package. The bundled hooks shell
python -m dos.cli …and the bundled MCP server runspython -m dos_mcp.server— both need thedos-kernelpackage importable in the SAME Python that Claude Code launches. This skill verifies that one prerequisite and shows you what the plugin gave you. It is the only DOS skill that names the pip package; the rest are domain-free.
Step 1 — Is the kernel importable? (the one prerequisite)
python -c "import dos, dos_mcp; print('dos', dos.__version__)"
-
Prints a version → the package is installed and importable. Go to Step 2.
-
ModuleNotFoundError: dos→ the plugin's hooks/MCP cannot work yet. Install the package (the[mcp]extra pulls the MCP server framework the bundled server needs):pip install "dos-kernel[mcp]"Install it into the SAME interpreter Claude Code runs (the one
pythonresolves to here). Then re-run Step 1. Ifpythonis the wrong interpreter, the hooks will silently no-op (they fail safe, by design) and the MCP server will print an install hint in/mcp. -
ModuleNotFoundError: dos_mcp→ the core installed but not the MCP extra; re-run thepip install "dos-kernel[mcp]"line above.
Step 2 — Does the kernel see this workspace? (confirm wiring)
python -m dos.cli doctor --workspace . --json
A JSON object with lanes, paths, and stamp means the kernel is reading THIS
repo. Skim it once — those values are the layout the bundled skills and the MCP
dos_arbitrate / dos_verify tools read instead of hardcoding anything. If this
repo has no dos.toml, the lanes are auto-derived from your top-level directories
and everything still works (the generic default).
Step 3 — See it work end to end (60 seconds, throwaway repo)
Before reading the skills, watch the kernel make a real call. This runs in a disposable git repo and cleans up after itself:
python -m dos.cli quickstart --driver workshop
It scaffolds a repo under the workshop reference driver (a worked
host-policy pack with two concurrent lanes + one exclusive release lane), then
shows BOTH halves of DOS against real artifacts:
- the truth syscall —
AUTH1was committed → SHIPPED (exit 0);AUTH2was only claimed → NOT_SHIPPED (exit 1). The verdict comes from git, not the agent. - the admission kernel —
frontendandbackendacquire concurrently (their file trees are disjoint), whilereleaserefuses (it is exclusive and runs alone). This is the concurrency policy your own lanes will get.
workshop is the copy-me template for declaring your own lanes — see Step 5.
(The plain dos quickstart, no --driver, shows just the truth-syscall half.)
Step 4 — What the plugin bundled (so you know what you have)
-
Hooks (active on every Claude Code launch in this project, all fail-safe — they emit nothing and exit 0 if anything goes wrong, so they never break a turn):
- PreToolUse →
dos hook pretool: can DENY a structurally-refused call before it runs (e.g. a self-modify of the kernel's own path). Advisory by default — a behavioral deny needs a ruling handler wired; out of the box it only observes. - PostToolUse →
dos hook posttool: re-surfaces a stalled tool stream (a read-loop spinning on the same file) as advisory context. - Stop →
dos hook stop: refuses to stop on an unverified claim, so the loop does not close on "I'm done" the git history does not back.
Every one of those calls is counted and logged: the bundled native
dos-hookbinary appends one record per hook call to.dos/metrics/observations.jsonl, so the kernel emits evidence about its OWN behavior (docs/276). Read it back any time with/dos-kernel:dos-stats(or"${CLAUDE_PLUGIN_ROOT}/bin/dos-hook" stats --workspace .) — counts by verb/outcome, the delegate + stop-block rates, and per-verb latency. - PreToolUse →
-
MCP tools (the
dosserver — check/mcpshows it connected):dos_verify(did a claim actually ship, from git not self-report),dos_arbitrate(may two workers run concurrently without colliding),dos_commit_audit,dos_refuse_reasons/dos_check_reason,dos_status,dos_recall,dos_citation_resolve(does a cited legal case exist in a third-party reporter),dos_doctor. -
The generic skill pack — the domain-free dispatch screenplays, namespaced under this plugin. The usual first one to read is
/dos-kernel:dos-next-up(snapshot the portfolio) or/dos-kernel:dos-dispatch(plan-and-ship one lane safely). And/dos-kernel:dos-statsshows the kernel's own activity on this project.
Step 5 — Adopt DOS in this repo (optional, makes it yours)
The plugin works against any git repo with zero config. To make the layout explicit
and editable (a dos.toml with your lanes, and the skills as local files you can
tune), scaffold it:
python -m dos.cli init . # lanes auto-derived from your top-level dirs
python -m dos.cli init . --example workshop # OR start from the worked reference taxonomy
The bare form derives one concurrent lane per top-level source dir. The
--example workshop form scaffolds the same lanes the Step-3 demo used (two
concurrent clusters + an exclusive release lane) for you to rename to your real
concurrency topics. Both are optional — the bundled surfaces already work without
any dos.toml.
What this skill deliberately does NOT do
- It installs nothing. It only TELLS you the pip command if the import fails;
it never runs
pipfor you (that would mutate your environment without asking, and the target interpreter is ambiguous). You run the install. - It wires nothing. The hooks and MCP server are already wired BY the plugin; this skill confirms them, it does not re-install or edit any config file.
- It decides no ground truth. Like every DOS skill, it shells
dosverbs and reads the verdict; the kernel decides, the skill reports.
dos-skillify — make any skill ask a witness instead of believing itself
A skill is a screenplay, not a program — and most screenplays trust the worker. When a skill concludes "the fix shipped" because the agent said it committed, "the goal is met" by re-reading its own transcript, or "all 7 workers returned" by
filter(Boolean), the part deciding ground truth is the part being judged. That is consistency, not grounding (docs/138). This skill does not rewrite the job; it changes how the skill knows a step worked — it finds every belief-bit and replaces the self-check with adosverb whose byte-author is not the agent. The kernel decides; the converted skill narrates.
The shape is domain-free: parse the skill into claim-sites → classify each as
ADD / REPLACE / GUARD / LEAVE → emit an additive new copy + a report. The
policy (which lanes, which plan grammar, which exit codes) is data read from
dos doctor --json, never literals — which is exactly what lets the converted
skill run unchanged on a host with different lanes. Full design: docs/345.
When to use this (and when not)
- Use it when you have a skill (a
SKILL.md, an agent prompt, a workflow script) that sets belief bits from self-report and you want those seams grounded — your own skill, a vendored one, or a public skill you're preparing a variant of. - Do not use it to rewrite a skill's job, make it "smarter", or convert a pure-prose/taste skill that sets no checkable belief bit — there is no witness to add, and forcing one is the fake-witness anti-pattern this skill refuses.
- This is a layer-3 helper / screenplay (a PDP, docs/99). It shells existing
dosverbs and mints no new verdict. It produces a variant + a report; it decides no ground truth itself. Its OWN output is admitted by witness (Step 5).
The one rule under this skill
The converter is a judged agent. It must never claim "I made this skill DOS-aware" — it must produce a report whose every row a reviewer re-derives from the diff without trusting the converter. A converter that self-certifies its own output is the exact failure DOS exists to fix. That is why Step 4 (the report) and Step 5 (admit-by-witness) are not optional.
Step 0 — Discover the workspace once (the WCR on-ramp)
dos doctor --workspace . --json
Stash it. Every lane name, plans glob, and exit-code table the converted skill
references comes from here — never a literal. (EXAMPLES.md Recipe 0.) The fields
this skill uses: lanes / paths.plans_glob / stamp (so a converted
arbitrate / verify step names the host's real taxonomy), and exit_codes
(so a converted gate branches on $?, not prose).
Want a quick score first?
dos skillify --grade <path>(or--all) runs the deterministic part of this screenplay without an agent loop: it scans a skill and reports its DOS grounding signal (STRONG/MODERATE/WEAK) plus the belief-bits that look ungrounded, as review candidates. It is a static estimate, NOT this skill's precise per-bit verdict — use it to triage which skills are worth a full conversion pass, and to gate CI (--check). The classification below is the precise instrument; the verb is the cheap one.
Step 1 — Parse the source skill into claim-sites
Read the source SKILL.md (and any supporting files / prompt it references).
Walk it step by step. For each step, decide: does it set a belief bit? — a
place the skill concludes something is true and acts on it. Record each as
{step, span, claim_kind, evidence_today}. Prose that sets no belief bit is
left untouched.
A claim-site is recognized by what it concludes, not by a keyword (keywords seed the search; you confirm the conclusion). Map each to its claim-kind — the taxonomy is 1:1 with the EXAMPLES.md recipes, which is the whole spine:
| The step concludes… | claim_kind | Recipe | The dos verb the converted step uses |
|---|---|---|---|
| "(plan,phase) / this code shipped" | SHIPPED | R1 | dos verify — read the rung (registry > grep-subject > none), never the bare bool |
| "this commit did what its subject says" | COMMIT_HONEST | R1 | dos commit-audit — subject vs. its own diff |
| "keep working until the goal is met" | GOAL_DONE | R1b | dos hook stop wired alongside the harness goal (ANY-block) |
| "I created file / row / message / deploy" | EFFECT | R9/§2b | effect read-back — no CLI verb today; Python API + log the gap |
| "a CI / workflow run concluded GREEN/RED" | CI_GREEN | (issue-verify R-run) | the run's own conclusion field (gh run view --json conclusion, the dos.drivers.ci_status rung), never the run-log narration — driver-witnessed, no first-party CLI verb today; log the gap |
| "I'm editing these files (no collision)" | WRITE | R2 | dos arbitrate over the tree before writing; honor the redirect |
| "is there work / safe to proceed" | GATE | R3 | dos gate — branch on the exit code, not the printed line |
| "how is run R doing" | RUN_STATE | R4 | dos status — the digest with no claimed field |
| "this tool-loop is progressing" | LOOP_LIVE | R5 | tool_stream (Python API) — distrust repetition, not correctness |
| "this long job is alive" | ALIVE | R6 | dos lease-lane heartbeat + dos liveness |
| "this recalled memory is still true" | RECALL | R7 | dos recall — re-verify at read time |
| "all N fan-out workers returned a real result" | FANOUT | R9/R10 | dos verify-result + dos coverage --declared N |
| "this issue / ticket is resolved" | ISSUE_DONE | (issue-verify) | witness each effect, fold, then close |
| taste / intent / future work | UNWITNESSABLE | — | no witness exists → leave as prose, never fake a check |
The last row is load-bearing. A claim with no honest witness is not turned
into a dos call. It is recorded UNWITNESSABLE and surfaced in the report
(fail-to-abstain). Never manufacture a verb that can't actually ground the claim.
Step 2 — Classify each site: ADD / REPLACE / GUARD / LEAVE
Compare each site's evidence_today against its recipe's witness:
- Already shells the right
dosverb → LEAVE. (Idempotence: running this skill on an already-DOS skill must produce an all-LEAVE report. A non-LEAVE row on, e.g.,dos-goal-gateis a converter bug — see Step 6's self-test.) - Self-certifies (re-reads its own output, greps subjects itself, trusts a
return string,
filter(Boolean)s a fan-out) → REPLACE the self-check with the verb. - Concludes truth with no check at all → ADD the verb.
- Mutates shared state with no coordination → GUARD with
arbitrate/recallahead of it.
Step 3 — Emit the converted copy (additive, legible, never a rewrite)
Write a new skill dir — <name>-dos/SKILL.md. Never overwrite the
source (this is the political floor for the public-skill PR path, docs/345 §5,
and the safety floor for the operator's own skill). Edit only the classified
spans:
- Each edited hunk carries a one-line trailer tying it to its recipe, e.g.
<!-- dos:R1 verify — was: "I committed it, so it shipped" -->, so a reviewer sees why every hunk exists and what it replaced. - Add a
Step 0runningdos doctor --jsonif the source lacks one. - Extend the frontmatter
allowed-tools:withBash/PowerShellif you added adosshell-out (and thedos_*MCP tools if the host uses the MCP mount). - Add a top note: "DOS-aware variant of
<name>. The job is unchanged; the trust seams now ask a witness. Original: . Ifdosis not installed, the witness steps degrade to advisory — the original job still runs." The graceful-degrade clause removes the "now I depend on your tool" objection.
Keep the diff small. The job logic, the domain steps, the taste — untouched. If your diff is large, you are rewriting the skill, which is wrong.
Step 4 — Emit the conversion report (the audit artifact)
Write <name>-dos/CONVERSION.md: one row per claim-site —
{step, claim_kind, edit_kind, recipe, the resulting hunk} — plus a section
listing every UNWITNESSABLE site left as prose with why. This is the
artifact a maintainer reads to trust a PR (docs/345 §5) and the artifact the
benchmark scores (§6). It is the converter eating its own dogfood: the report
is the witness that the conversion did what it claimed, re-derivable from the
diff without trusting you.
Step 5 — Admit the converter's OWN output by witness (not by say-so)
The converter's deliverable is a checkable effect (the new files). Do not report "done" from your narration — witness it:
dos commit-audit --workspace . HEAD # the diff does the KIND of thing claimed (subject vs. diff)
If the conversion touched a tracked phase, also dos verify. Read the verdict
and report that, carrying the evidence — exactly as issue-verify closes an
issue carrying its witnesses, never on the claimant's word.
Step 6 — Report (and the idempotence self-test)
- Per skill: the
CONVERSION.mdtable + the count of ADD / REPLACE / GUARD / LEAVE / UNWITNESSABLE sites, and thecommit-auditverdict. - Idempotence self-test: run this skill on a known-already-DOS skill (e.g.
dos-goal-gate). Assert the report is all-LEAVE. A non-LEAVE row means the converter is churning a grounded skill — a bug to fix, not a finding. - Taxonomy-gap check: if a source skill has a belief bit whose
claim_kindis not in Step 1's table, that is an incomplete taxonomy — surface it (and, if it's a genuinely new witness shape, the recipe is missing too). Never force it into the nearest row.
Anti-patterns
- ❌ Rewriting the skill's job, prose, or taste. DOS touches the trust seams only; the diff must be small and every hunk traceable to one claim-site.
- ❌ Overwriting the source skill. The output is always a new copy
(
<name>-dos/). Replacing the original is both rude (the PR politics) and unsafe (the operator's working skill). - ❌ Manufacturing a
doscall for anUNWITNESSABLEclaim "so the skill looks grounded". An abstain surfaced in the report is the correct, honest output. - ❌ Reporting "I made it DOS-aware" without the
CONVERSION.md+ acommit-auditverdict. The converter that self-certifies is the failure DOS exists to fix. - ❌ Baking a host's lane name, plan dir, or exit code into the converted skill
as a literal — read
dos doctor --jsonand keep it data. - ❌ Hard-requiring
dosto keep the original job working. The witness steps degrade to advisory if the kernel is absent; the job never depends on it.
dos-stats — read the kernel's own activity log
The DOS hooks judge your agents from non-forgeable evidence. This skill turns that lens on the kernel itself. Every time a hook fires (before a tool call, after a read, on a stop), the bundled native
dos-hookbinary writes ONE line to a durable log describing what it decided. This skill folds that log into a report you read. It is the binary's own dogfood: the kernel emits evidence about its own adjudication, the same way it demands evidence from the agents it judges (docs/276).
What writes the log (so the numbers mean something)
The plugin's hooks call the bundled dos-hook binary on every tool call. On each
call the binary appends one record to .dos/metrics/observations.jsonl under this
workspace — the verb it ran, the decision it reached, the reason class, the dialect,
the exit code, how long it took. The log is append-only and local; nothing reads
it back until you run this. It is on by default and opt-OUT with DOS_HOOK_METRICS=0.
Step 1 — Fold the log into a report
The binary lives in the plugin bundle, so call it by its bundle path (the same launcher the hooks use picks the right binary for your machine):
"${CLAUDE_PLUGIN_ROOT}/bin/dos-hook" stats --workspace .
A populated run looks like this:
dos-hook stats — /your/project
observations 4
tool calls 3 adjudicated — 2 passed untouched (66.7%), 1 intervened (33.3%)
by verb posttool=1 pretool=3
by outcome deny=1 passthrough=3
by exit code 0=3 2=1
pretool rung admission=1 none=1 provenance=1
dialect claude-code=3
stream state ADVANCING=1
delegates 0 (native declined → Python)
stop blocks 0 (false-done refusals)
latency (ms) verb n mean p50 p95 max
posttool 1 2.29 2.29 2.29 2.29
pretool 3 5.32 5.32 5.42 5.42
If it says (no observations yet …) that is normal and correct — the log is
empty until the hooks have fired at least once. Make any tool call in this project
(read a file, run a command) and re-run; the count climbs.
Step 2 — Read the lines that matter
- observations / by verb — how many calls the kernel adjudicated, split by hook
(
pretool= before a tool runs,posttool= after a read,stop= on a stop,marker= the keep-alive budget). - tool calls — the intervention RATE: of every tool call adjudicated (one
pretoolrecord each), what share passed untouched vs was warned or denied. This is the "is the substrate a light touch or a nanny?" number — numerator and denominator come from the same log, so the percent cannot be argued with. A delegated call is counted in neither (Python decided it; see delegates). - by outcome —
passthrough(let it run),deny(refused a structurally-unsafe call, e.g. a self-modify of the kernel's own path),warn(advisory re-surface),block(a stop refused on an unverified claim). - delegates — how often the fast native path declined and fell back to Python.
The native binary exists to erase that cold-start, so a high delegate count is the
one number you want LOW;
0means the fast path is owning every call. - stop blocks — how many times verify-on-stop refused to let the loop close on a "done" the git history did not back. This is the headline safety number.
- reason class — which refusals fired (
SELF_MODIFY, a lane collision, …), when the kernel denied or warned. - latency (ms) — per-verb wall time. The native path's whole point is sub-30 ms (the docs/270 claim) — here it is, measured live and continuously on your machine.
- ⚠ panics — only appears if the fail-safe fired (a Go crash that recovered to a no-op so it never broke your turn). Non-zero here is worth a bug report.
Step 3 — Narrow the window or get the machine form (optional)
# only the last hour (or 30m, 15m, …) — the clock lives at this read-only boundary:
"${CLAUDE_PLUGIN_ROOT}/bin/dos-hook" stats --workspace . --since 1h
# the same aggregate as a JSON object, to pipe into jq or a dashboard:
"${CLAUDE_PLUGIN_ROOT}/bin/dos-hook" stats --workspace . --json
--since with an unreadable value (or omitted) folds everything; it never errors —
a read-only surface degrades to "show what we have."
What this skill deliberately does NOT do
- It changes nothing. It is a pure fold over a log the hooks already wrote — no
lease, no launch, no mutation. It does not even add to the log it reads (the
statsverb is the one verb that is NOT itself recorded, so it cannot count its own reads). - It does not decide ground truth. It reports counts; the kernel made the decisions those counts summarize, at the moment each hook fired.
- It is not a server. A hook is a one-shot process, so there is nothing to scrape;
the durable per-call log IS the cross-process surface, and this verb folds it on
demand. To watch it live, re-run it (or wrap it in
/loop).
dos-supervise-loop — the generic worker-population supervisor
The init/PID-1 of a dispatch fleet. It keeps
--targetworker dispatch-loops alive across the lane roster: each tick it counts live lane leases, classifies each worker's liveness, and fills the roster up to target by launching one/dos-dispatch-loopper free admissible lane. The what to do is a typed kernel verdict —dos loopemits a spawn/reap/flag plan; this skill only carries it out. It reaps a worker ONLY when the kernel says STALLED, never a healthy one, and it FLAGs a SPINNING worker to the operator rather than killing it (acting on a spin is not the supervisor's job).
The supervisor's whole contract is one rule the kernel owns: the population is
filled from the plan, not from a guess. A tick is gather evidence → ask dos loop → carry out spawn/reap/flag. The four dispositions are the kernel's:
- SPAWN — a free, admissible lane below target: launch one worker on it.
- REAP — a STALLED lease: scavenge it so the lane is free to refill.
- HOLD — an ADVANCING (or alive-counted SPINNING) worker: leave it alone.
- FLAG — a SPINNING worker (advisory) or an excess over target: surface it, do not kill it.
Inputs
--target <N>(default 1) — the desired live-worker population. The kernel caps the achievable population at the admissible count (how many roster lanes can simultaneously hold a worker given their disjointness); a--targetabove that yields a TARGET_UNREACHABLE verdict naming the fix.--max-concurrency <N>(optional, docs/283) — the derived-claim concurrency budget. On a DYNAMIC-CLAIM workspace (concurrent = [], where a lane is a HANDLE whose disjointness is enforced per-pick at acquire time, not by a fixed tree), the static admissible count is 1, so a--targetabove 1 is structurally unreachable. Declaring this budget lets the supervisor keep up to N workers alive on a fungible auto-pick handle WITHOUT pre-enumerating N disjoint trees — the arbiter still narrows each worker's per-pick claim at its Step 0. Declare ONE number, not N trees. Set it standing indos.toml [supervise] max_concurrency, or pass--max-concurrencyfor a one-off run. Off by default (admissible stays the static disjoint-lane count — byte-for-byte today's).--interval <seconds>(long default) — the wakeup cadence between ticks. A supervisor wakes rarely; it is a watchdog, not a busy-loop.--max-ticks <N>(optional) — stop after N ticks. Omit for an open-ended run that stops only on an operator interrupt.
Step 0 — Read the taxonomy, compute the plan
dos doctor --workspace . --json
dos loop --workspace . --target N --json
The doctor report carries the active lane roster (the concurrent + exclusive
lanes and their trees) — read it, never assume a lane name. dos loop then
gathers the evidence (the live lane leases from the journal + each lease's
liveness) and returns the typed plan: a verdict (AT_TARGET / FILLING /
OVER_TARGET / TARGET_UNREACHABLE), the alive/admissible/target tally, and
the spawn/reap/flag lane lists. This plan is the kernel's decision; the
remaining steps only enact it. If the verdict is TARGET_UNREACHABLE, read its
reason (the roster cannot reach the number) and stop — see the anti-patterns.
Step 1 — Launch one worker per SPAWN
For each lane in the plan's spawn list, launch a worker dispatch-loop focused
on that lane:
/dos-dispatch-loop --lane <LANE>
The worker takes its own lane lease via dos arbitrate at its Step 0 and
journals its ACQUIRE early — that early write is what shrinks the
double-spawn window: by the next tick the lease is visible in the journal, so
the supervisor counts it alive and does not launch a second worker on the same
lane. The supervisor itself never takes a lease; it only counts them and fills
the gap. Launch exactly the lanes the plan named — no more, no fewer.
Step 2 — Per REAP consult resume then scavenge, per FLAG surface
For each lane in the plan's reap list (a STALLED worker): before scavenging,
ask dos resume whether the run can be continued (docs/107, issue #19):
dos resume --workspace . --run-id <run_id> --json
The verdict shapes the action:
- RESUMABLE — the kernel minted a re-entry point and recorded a
RESUME_PROPOSEDon the ledger. Do NOT scavenge; the proposal surfaces automatically indos decisionsfor the operator to re-dispatch. The lane remains held until the operator acts. - DIVERGED — ground truth advanced past the resume point; re-dispatch would
overwrite fresh work. Do NOT scavenge; surface the decision to the operator
through the
RESUME_DIVERGEDrow indos decisions. There is no safe re-dispatch command for this case; a human must decide how to merge or retire the stale residual. - UNRESUMABLE or COMPLETE — no viable continuation (no intent, corrupt ledger, or all steps already verified). Scavenge as before: release the lease so the lane is free to refill on the next tick.
dos resume records DIVERGED as a decision, not as a proposal: it does not print a
re-dispatch command, but it does leave a durable RESUME_DIVERGED row for
dos decisions to project. For COMPLETE/UNRESUMABLE the scavenge path is
unchanged — only the RESUMABLE/DIVERGED branch is new.
For each lane in the plan's flag list (a SPINNING worker, or an excess over
target): surface it to the operator and move on. Do NOT kill a SPINNING
worker and do NOT reap an excess healthy one — a flag is advisory. Acting on a
spin (deciding a busy-but-not-advancing worker should be stopped) is an open
question the supervisor deliberately leaves to a human; its job is to make the
spin visible, not to adjudicate it.
Step 3 — Beat, sleep, re-tick, stop on interrupt or --max-ticks
At the END of each tick — after the plan is enacted — record the supervisor's own proof-of-fire, so its liveness is itself observable (the cron dead-man's switch, docs/384):
dos beat supervise --workspace .
A supervisor is an always-on job, and its deadliest failure is silent death: it
just stops ticking, and because a healthy supervisor on a quiet roster also does
nothing visible, the silence reads as "all fine." Declare [heartbeats] supervise = "<your --interval>" in dos.toml; then dos pulse / dos beat --check fold
the beat ledger into a FRESH/LATE/MISSING verdict, so a supervisor that has
stopped ticking surfaces as MISSING instead of going quiet. (The beat proves the
tick FIRED; the FLAG ratchet above is the did-it-progress half.)
Sleep --interval seconds, then re-run from Step 0: re-read the taxonomy,
recompute the plan, enact it. Each tick is independent and idempotent — it
re-derives the whole plan from the current journal state, so a missed or extra
tick self-corrects. A lane launched within the last cooldown window is treated
as pending (alive-or-coming) for the next tick, so a slow ACQUIRE does not
trigger a re-spawn.
Stop when the operator interrupts the run, or when --max-ticks is reached.
There is no "all done" terminal state — a supervisor's job is to stay up; it
ends only on an explicit bound or an interrupt.
The outer ratchet for this loop (docs/351)
A supervisor does not itself produce a net gain — it keeps a population alive — so
its docs/351 ratchet is at the population level, and it already exists as the
FLAG disposition: a worker the kernel classifies SPINNING (alive, but landing
zero forward delta — the per-worker liveness ground-truth verdict) is surfaced to
the operator, never killed. That is this loop's "running but not improving" signal:
a worker that is up but not making witnessed progress is flagged for a human, the
same doctrine the dispatch loop's not-ratcheting and the replan loop's
REPLAN_STALLED express at their own level. The supervisor's contract keeps the
act (reap/halt) a human-rung decision — it FLAGs the spin, it does not act on it
— so the ratchet here is "surface the worker that is not ratcheting," not an
auto-stop. (An optional aggregate "fleet not ratcheting" rung — K consecutive ticks
where every worker is FLAGGED — is a supervise.py policy change, deferred.)
What this skill deliberately does NOT do (no silent gap, CLAUDE.md heavy tier)
- No auto-kill of a SPINNING worker. A spin is FLAGged (advisory) and surfaced; the supervisor never terminates a busy worker. Acting on a spin is open research, deliberately left to the operator.
- No reap of a healthy worker to hit a number. A REAP fires ONLY on the kernel's STALLED verdict. An ADVANCING (or alive-counted SPINNING) worker is HELD even when the population is over target — the excess is FLAGged, not killed.
- No hardcoded lane or trunk. Every host fact — which lanes exist, their
trees, the ship grammar — comes from
dos doctor --jsonand the workspace'sdos.toml. The supervisor names the generic roster the kernel reports, nothing else. - No value-aware spawn ranking. It fills free admissible lanes in roster order; a yield-greedy "spawn the highest-value lane first" picker is a driver concern outside this loop.
Worked example (live transcript)
A supervisor tick, hand-run with real
dosverbs against this workspace (dos doctorreportsis_kernel_repo: true, 11 runtime files). The verdicts below are live-captured; the per-run digest is the antidote to re-reading state.
Step 0 — read the roster, then ask the kernel who is alive:
$ dos doctor --workspace . --json
# lanes.concurrent = [benchmark, docs, examples, scripts, spikes, src, tests]
# lanes.exclusive = [global] stamp.style = grep overlap_policy.active = prefix
A worker's lease is what the supervisor counts — and the arbiter never double-books:
$ dos arbitrate --workspace . --lane src
{"auto_picked":true,"free_clusters":[],"lane":"benchmark","lane_kind":"cluster","outcome":"acquire","pick_count":null,"reason":"auto-picked free cluster lane benchmark (requested src was refused: lane src would edit the orchestrator's own running code … (SELF_MODIFY) …)."}
You asked for src; the admission conjunction refused the hint (here SELF_MODIFY —
src/** is the running kernel on its own repo; a lane contended by a live lease
redirects the same way), so the arbiter redirected to benchmark — exit 0
(acquire), the real reason named in the parenthetical. A free, admissible lane
you name is granted directly.
Per run, fold ONE digest instead of re-reading state files (no claimed field):
$ dos status RUN_ID --json # ILLUSTRATIVE shape — folds liveness+ledger+lease+resume
# {"liveness":"SPINNING", ...} exit 3 (SPINNING) → this run is the FLAG candidate
dos status/dos liveness share the liveness exit codes — 0 ADVANCING (HOLD),
3 SPINNING (FLAG, advisory), 4 STALLED (REAP). On SPINNING the supervisor records
an OP_HALT proposal and surfaces it; it never signals the process. A worker can
be paused for clean re-entry instead:
$ dos halt --resumable # ILLUSTRATIVE — SUSPEND op; run-dir retained, dos resume continues it
Anti-patterns
- ❌ Re-spawning a pending lane — a worker launched last tick whose ACQUIRE has not yet journalled is alive-or-coming; the kernel marks it pending and the plan omits it. Honor that; do not double-launch.
- ❌ Reaping an ADVANCING worker — only a STALLED lease is a REAP. A worker that is moving keeps its lane; trust the temporal verdict, do not second-guess it.
- ❌ Killing a SPINNING worker — it is a FLAG, not a REAP. Surface it; let the operator decide.
- ❌ Running the supervisor where the roster cannot reach
--target— a TARGET_UNREACHABLE verdict means no further disjoint concurrent lanes exist to fill. Two honest fixes: (a) on a STATIC-tree roster, declare more disjoint concurrent lanes indos.toml [lanes]; (b) on a DYNAMIC-CLAIM roster (concurrent = [], per-pick disjointness), declare a--max-concurrencybudget (docs/283) so the supervisor rides a fungible auto-pick handle up to N workers — one number instead of N trees. Do NOT force the number by inventing fake disjoint trees a worker would over-claim.
dos-unstick — the recurring-blocker remediation sweep
Stop the cause, not the instance. A one-off unblock fixes today's stall;
/dos-unstickasks the different question — what keeps blocking progress across runs, and what one change would unblock it? It mines the run archive, normalizes every blocker to a canonical cause key, clusters the recurring ones, ranks by recurrence × measured stall-cost, and proposes a structural fix per cluster. Read-only; it writes no code and surfaces findings, never acts.
The shape: mine the trail → key each blocker → cluster the recurring ones →
rank → propose a structural fix → surface. The recurrence fold is the kernel's
(recurring_wedge); the cause TAXONOMY is [reasons] data — a host adds a cause
by declaring a reason, never by editing this skill.
Inputs
--runs <N>(optional) — how many most-recent runs to sweep (default: a recent window).--since <Nd|Nh>overrides with a time window.--min-recurrence <N>(optional) — a cause is "recurring" at N+ distinct runs (default 2 — therecurring_wedgeDEFAULT_MIN_RECURRENCE).
Step 0 — Discover the layout + the cause taxonomy
dos doctor --workspace . --json
Read paths.runs (the run-archive dir to sweep) and run dos man wedge to read
the closed reason vocabulary — the canonical cause keys this workspace knows.
Use these; never hardcode a run path or a cause string. A cause the workspace
cares about is a declared [reasons] entry, surfaced by dos man wedge.
dos man wedge
Step 1 — Mine the run-archive trail
Read the run records under paths.runs (read each once, sequentially — no
tailing/polling, the very anti-pattern this sweep exists to surface). For each
run that STOPPED on a BLOCKED / DRAIN / STALLED outcome, capture: the run id, the
iteration, the blocker text, and the measured stall cost ($/wall) if recorded.
No host evidence reader is wired by default. A host that curates a postmortem stream or a hand-ranked next-hits file can expose it as a
dos.evidence_sourcesdriver hook; the generic sweep reads only the run-archive verdicts.loga one-line note when a host evidence source is not consulted — no silent gap (the/dos-dispatch-loopdiscipline).
Step 2 — Key each blocker to a canonical cause
Normalize each blocker text to ONE cause key from the declared [reasons]
vocabulary (the host's cue table maps an Outcome-cell string to a key — the same
kernel-catalog ↔ host-cue split dos man wedge documents). A blocker that maps to
no declared cause is keyed UNCATEGORIZED (surfaced as a gap, never dropped).
Step 3 — Cluster the recurring causes (the kernel fold)
Feed the keyed blockers to the recurrence fold. It clusters by cause key, ranks by
recurrence (dominant) × stall-cost (the tie-break), and tells you whether the
cause the CURRENT sweep hit spans >= min-recurrence distinct runs:
The fold is recurring_wedge.classify_recurring_wedge — pure, frozen-data-in,
verdict-out. A cluster spanning ≥ min-recurrence runs is recurring (worth a
structural fix); a one-off is noise the sweep cannot help.
Step 4 — Propose ONE structural fix per recurring cluster
For each recurring cluster, propose a structural change — a contract edit, an
oracle rung, a preflight check — that would stop the cause RECURRING, not a
one-off unblock of today's instance. Rank the proposals by the cluster's
stall-score (recurrence × cost). The cause→fix mapping is the host's [reasons]
fix-sketch (the reason's documented remediation), not a literal in this skill.
Step 5 — Surface, don't act
Route each proposal to the operator-decision queue:
dos decisions add # the routing surface; the proposal is a finding, not an edit
This skill is read-only: it writes no code, edits no plan, takes no lease. A recurring cause is a finding for a human (or a follow-up plan), not an auto-applied change — the structural fix is a real engineering decision.
What this skill deliberately does NOT do (no silent gap)
- No auto-unblock. It proposes the structural fix; a human applies it. A loop that auto-unblocks would paper over the recurring cause, the exact failure mode.
- No curated postmortem / next-hits ingestion unless a host wires a
dos.evidence_sourceshook.logwhen it is not consulting one. - No trajectory mining by default (the heavier read) — the run-archive verdicts are the generic floor.
Anti-patterns
- ❌ Proposing a one-off unblock for a 3-run recurring cause — that is the bug this skill exists to replace. Recurring ⇒ structural.
- ❌ Hardcoding a cause string or a run path — read the vocabulary from
dos man wedgeand the path fromdos doctor --json. - ❌ Tailing/polling the run dir — read each record once; polling is the waste this sweep surfaces in others.
dos-witness-claim — fold the witnessed effect, never the narrated one
This is the screenplay for the one move the whole substrate exists to make: when a subagent hands you a result, the result is a claim, not a fact. A claim re-narrating the agent's own work is consistency, not grounding (docs/138). Belief is earned only by a read-back whose byte-author is not the judged agent (a fresh GET, a git existence check, an OS exit code, a state diff). This skill never decides ground truth itself — it shells
dosverbs and reads the verdict. The kernel decides; the skill narrates.
The shape is domain-free: discover the layout → classify the claim type →
witness it on a non-forgeable rung → fold ONLY confirmed. The policy (which
lanes, which plan grammar, where state lives) is data the screenplay reads from
dos doctor --json, never literals it hardcodes.
The seed-2 payoff. This makes the worker's MODEL TIER irrelevant to trust. A weak worker and a strong worker face the SAME witness gate: both have their claimed effect re-read from a surface they did not author. A confident, fluent, frontier-strength narration of a success the world does not corroborate is exactly the silent fail this gate catches (docs/177) — and a weak worker that actually shipped the effect passes it. Distrust is aimed at the byte-author of the evidence, not at the worker's eloquence.
Inputs
- A set of subagent results to fold (return strings + their transcript paths),
e.g. the children of a
parallel()barrier or apipeline()stage. A result is the thing you are tempted to interpolate directly (${result}) — don't. - For each result, the effect it claims (a
(plan, phase), a created file path, a DB row key, a sent-message id). If the worker emitted no checkable effect, that is a real outcome (NO_CLAIM), not a pass — see Step 2.
Step 0 — Discover the workspace layout (one call)
Run the doctor verb and read the result. This is the WCR on-ramp: every path/lane/exit-code below comes from here, never a literal.
dos doctor --workspace . --json
Parse the JSON object. The fields this skill uses:
exit_codes.verify—{shipped, not_shipped, contract_error}. Branch on these, never on parsing the prose, for the git-phase claim type (Step 3a).exit_codes."verify-result"—{healthy, unreadable, dead, contract_error}(dead=3). Branch on these for the terminal-state witness (Step 3, the prerequisite gate every claim type runs first).paths.plans_glob/lanes/stamp— the host's plan grammar and lane taxonomy, if a claim names a(plan, phase).git— iffalse, the git-existence witness (Step 3a) has no history to read; every git-phase claim will besource="none". Say so; do not silently pass it.
You may also read admission_predicates and overlap_policy here, but they are
not load-bearing for witnessing — they describe the arbiter, not the witness rung.
Step 1 — For each result: is the worker even ALIVE? (the terminal-state gate)
Run this BEFORE you read the worker's return string at all. A return string is
worthless if the "worker" was a harness-synthesized death (a rate-limit / quota /
auth / server error the harness wrote and the worker never authored). ~32% of real
subagents return such a string (docs/197 §2), and it survives a naive
.filter(Boolean) to be banked as a finished finding.
dos verify-result --workspace . --transcript <agent-transcript.jsonl>
echo "exit=$?"
Branch on exit_codes."verify-result":
3DEAD — the terminal record was harness-authored (message.model == "<synthetic>", the unforgeable authorship marker). Do NOT fold this result. Route the worker's OWN unit for re-dispatch, and count it in the denominator (a 4-of-7 fan-out is 4/7, never silently 7/7). The catch is grounding because it read a DIFFERENT byte-author than the worker — the harness, not the model.0HEALTHY — a real terminal result; proceed to Step 2. (0also covers UNREADABLE, the fail-safe floor: a read fault never fabricates a death. An UNREADABLE result is not trusted as confirmed — it simply isn't classified DEAD; its effect still must be witnessed in Step 3.)2— a contract error (no transcript). Fix the wiring; do not treat as HEALTHY.
This step is itself the cheap, shipped form of "byte-author ≠ judged agent": the liveness of the worker is read from the harness's own authorship marker.
Step 2 — Classify the claim TYPE (so you know which witness to ask)
For each HEALTHY result, decide what checkable effect it claims. Extract the claim at the boundary — abstain, never invent. Free prose ("I'm done", "shipped the auth work") yields NO claim: there is no honest way to derive the effect's identifier from prose without inventing it (docs/134 §2.1). A claim you cannot name is a NO_CLAIM — surface it for a human, do not manufacture one to witness.
Map each named claim to its witness rung:
| Claim type | What the worker asserts | Witness (byte-author ≠ agent) | Verb today |
|---|---|---|---|
| git phase | "(plan, phase) shipped" | git ancestry + ship-stamp grammar | dos verify (Step 3a) — SHIPPED |
| terminal state | the result itself is real | harness authorship marker | dos verify-result (Step 1) — SHIPPED |
| created file / DB row / sent message / deploy | "I created X / inserted row Y / sent Z" | a fresh GET / state-diff / OS exit / counterparty record | NO CLI verb (Step 3b) — Python API gap |
The first two are shipped CLI verbs. The third is the open seam — handled honestly in Step 3b.
Step 3 — Witness the claim on a non-forgeable rung
Step 3a — git-phase claims: ask the truth syscall
For a (plan, phase) claim, never trust the worker's "I committed it" and never
grep commit subjects yourself:
dos verify --workspace . <PLAN> <PHASE> --json
echo "exit=$?"
Read the ShipVerdict: {shipped, source, sha?}. Branch on exit_codes.verify
(shipped:0, not_shipped:1, contract_error:2), and read the rung:
source: "registry"— the strongest git ship; a ship row exists. Fold it.source: "grep-subject"— a commit subject carried the phase token. SHIPPED, but weaker — a subject can flip the verdict even if little was built. Fold it, but mark the rung; do not treat it as equal toregistry.source: "none"— no positive git evidence. The worker CLAIMED the phase but git does not corroborate it. Do NOT fold the claim — this is the narrated success the world does not back. Surface it; route the unit for re-dispatch.
This is grounding because git is a witness the worker did not author: the commit's existence in ancestry is a fact about the repository, not about the worker's prose.
Step 3b — created-file / DB-row / sent-message claims: the read-back gap
There is NO dos verify-effect (or dos witness) CLI verb. The effect-witness
join is shipped in the kernel as a Python API, not a command — exactly like
tool_stream has no dos tool-stream verb (see EXAMPLES.md Recipe 5). So for any
effect outside git, the skill documents the pattern and logs the gap at
runtime, rather than pretending a verb exists.
The pattern (kernel modules, all pure; the read-back I/O lives in a drivers/*
witness, never in the skill):
from dos.claim_extract import extract_claims # (a) abstain, never invent
from dos.effect_witness import EffectClaim, witness_effect
from dos.evidence import gather_evidence, resolve_evidence_source # (b) read-back at the boundary
# (a) Extract the claim from the worker's terminal text (boundary read done already).
# extract_claims fires only on an explicit ID-shaped token or a DOS-CLAIM:
# marker — free prose yields []. That [] is a NO_CLAIM, not a pass.
# (b) Gather a read-back from a witness the agent did not author. A real witness
# (a fresh HTTP GET, an OS exit code, a state-snapshot diff) lives in a driver
# registered under the `dos.evidence_sources` entry-point group; the skill
# resolves it by name and runs it at the boundary:
source = resolve_evidence_source("<your-witness-name>") # built-in `null` if none wired
facts = gather_evidence(source, subject="<effect key>", config=cfg)
# (c) Fold ONLY confirmed: the join is capped by the read-back's accountability.
verdict = witness_effect(EffectClaim(key="<effect key>", narrated="<what worker said>"),
(facts,))
# verdict.verdict -> CONFIRMED | REFUTED | UNWITNESSED | NO_CLAIM
# verdict.believe -> True ONLY on CONFIRMED (a non-forgeable witness saw it PRESENT)
The load-bearing rule, enforced structurally by believe_under_floor: a read-back
on the forgeable floor (AGENT_AUTHORED — the agent re-reading its own
surface, a pasted receipt, an mtime) is recorded but structurally incapable of
granting belief. Belief requires a OS_RECORDED / THIRD_PARTY witness. So the
worst a lying same-surface read-back can do is be ignored (a safe-direction
no-op), never manufacture a CONFIRMED.
The four outcomes a consumer routes on:
- CONFIRMED — fold it. A non-forgeable witness re-read the world and the effect is PRESENT.
- REFUTED — do NOT fold; RED-flag it. A non-forgeable witness re-read and the effect is ABSENT (the silent frontier-fail made visible). Route for re-dispatch.
- UNWITNESSED — do NOT fold as confirmed. No accountable witness was reached (or only a forgeable-floor read). The honest abstain — surface it; this is the runtime gap to log (see "What this skill does NOT do").
- NO_CLAIM — the worker asserted no checkable effect. Nothing to witness; surface it for a human. NOT a pass.
Log the gap, never silently skip it. The first time a non-git effect needs
witnessing and no dos.evidence_sources driver is wired (so gather_evidence
returns null → UNWITNESSED), emit a one-line log naming the unwitnessed effect
and the missing witness — so the capability gap is surfaced at runtime, not buried
here. An UNWITNESSED effect must be reported up, never laundered into the fold.
Step 4 — Partition the fold and carry coverage forward
Fold the results into three buckets, and carry the count into whatever consumes the fold (a synthesis prompt, a downstream stage):
- CONFIRMED / SHIPPED → folded. These are the only results another agent's input may be built from.
- REFUTED / NOT_SHIPPED / DEAD → routed for re-dispatch, counted in the denominator. A fan-out of N that confirmed M is M/N — never silently N/N.
- UNWITNESSED / NO_CLAIM → surfaced for a human; held out of the fold.
The coverage fact (confirmed M of declared N, plus the bucket each result landed
in) is data the synthesizer must SEE — a synthesis told "7/7 returned" when only
4/7 were witnessed will confidently launder the gap.
What this skill deliberately does NOT do (no silent gap)
- No model-judge over the return TEXT. It NEVER asks a model (or a heuristic,
or itself) "does this return string look right / complete / successful?" That
is the docs/197 §4d wishful trap: a judge reading the worker's own narrated bytes
is re-deriving the author's output — consistency, never grounding. Belief
comes only from a read-back whose byte-author is not the worker. (A JUDGE rung
exists — the
dos.judgesseam — but it is advisory, fail-to-abstain, and applies to the residue the oracle ABSTAINED on, fed independent evidence, never the worker's own string as a substitute for the witness.) - No
dos verify-effectverb (there isn't one). Non-git effects are witnessed via the Python API of Step 3b, and the gap is logged at runtime. The skill does not pretend a CLI verb exists where it does not (the EXAMPLES.md Recipe 5 discipline). - No host evidence source baked in. Which witness re-reads a created file or a
DB row is a
dos.evidence_sourcesdriver the host wires; the skill resolves it by name, never names a host backend as a literal. - No enforcement. It REPORTS a fold partition and proposes a re-dispatch; it does not kill a worker or block a write. DOS is a PDP, not a PEP.
Anti-patterns
- ❌ Interpolating
${result}(a worker's return string) directly into a synthesis prompt — that folds the worker's self-report as ground truth. Witness first. - ❌ Treating a non-empty return string as success — a harness-synthesized death is
non-empty and survives
.filter(Boolean). Rundos verify-resultfirst. - ❌ Asking a model "is this output complete/correct?" — consistency, not grounding. Gather a read-back from a surface the worker did not author.
- ❌ Counting only the workers that returned a string in the denominator — a DEAD or UNWITNESSED result must be counted, or a 4/7 fan-out launders as 7/7.
- ❌ Folding an UNWITNESSED / NO_CLAIM result "because it probably worked" — abstain surfaces it; it never folds as confirmed.
- ❌ Naming a specific lane, plan dir, or witness backend as a literal — read the
active layout from
dos doctor --jsonand resolve witnesses by name.
The one rule under this skill
A subagent's result is a claim with a byte-author. Fold it only when a witness whose byte-author is not the worker corroborates the claimed effect. The worker's model tier, its confidence, and its eloquence are irrelevant to that gate — which is the whole point: the part that decides ground truth is never the part being judged.
MCP servers 1
Sponsors
Details
- Marketplace
- anthony-chaudhary/dos-kernel
- Source
- claude-plugin
- Author
- Anthony Chaudhary
- Category
- Community