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@dos

Run it inside Claude Code after adding the marketplace with /plugin marketplace add anthony-chaudhary/dos-kernel.

Contents

Discovered from source

Skills 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-cycle runs 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_cycle candidates 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.judges driver; 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/TOMB or a trigger like idle_14d — read the declared set from dos doctor --json's lifecycle.
  • ❌ Exceeding max_transitions_per_cycle in 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-dispatch repeatedly and falls to /dos-replan when a lane drains, stopping on a typed, kernel-decided condition (not a prose guess). The stop/continue logic is the kernel's loop_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:

  1. iteration cap — reached max_iterations (default 10).
  2. drained-twice — a DRAIN after a productive /dos-replan that itself followed a DRAIN (the lane is genuinely exhausted).
  3. consecutive-unclear — the dispatch subprocess is failing systematically.
  4. rate-limited — a usage window is exhausted (don't burn launches).
  5. launch-failed — a subprocess never started.
  6. 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.
  7. 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).
  8. 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 improve ESCALATE, 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 (default hard) — the verdict policy. hard routes a non-LIVE verdict through /dos-replan; soft/drive stop on a true DRAIN; drive self-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 pickable exit of 0 (OFFERABLE) and a cooldown exit of 0 (CLEAR) → this unit is dispatchable; offer it and proceed to the iteration.
  • A pickable HELD by a re-dispatch-CURABLE reason (IN_FLIGHT / SOFT_CLAIMED / STALE_CLAIM / UNPARSEABLE) or a cooldown of 3 (RECENTLY_ATTEMPTED) → skip this unit, try the next candidate (the skip-to-next is pick-selection's job).
  • A pickable HELD 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 gate over 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 in next_mode (dispatch or replan); if reconcile is set (a soft/drive STALE-STAMP), run an inline stamp-reconcile pass first. Carry next_state forward (the updated counters).
  • action: "stop" → the loop ends; report stop_reason (one of the five above) and surface (whether it needs operator attention).
  • action: "retry-same-iter" → a transient overload; sleep backoff_seconds and 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):

  • 0 VERIFIED → the oracle confirms it shipped; it leaves the residual.
  • 3 QUIET_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).
  • 4 HONEST_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 tree globs dos arbitrate handed back), then commit naming those paths: git add <lane paths>; git commit -m "<subject>" -- <lane paths>. Never a bare git 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 — log it and commit it (or, if a path turns out to belong to a still-live sibling lease — check dos 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; rm it 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 --strict that mechanizes the "is my lane clean?" check above (exit 1 on stranded durable work, lease-aware). It is a DOS-repo convenience, not a dos verb — a foreign workspace uses the generic git status form 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. log this 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 dos verb; the heartbeat is the HEARTBEAT op 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 from dos doctor --json; nothing is hardcoded.

The shape: discover → take a lane → snapshot → gate → ship → archive. The lane taxonomy and the run-dir location are data ([lanes], [paths]); the admission and the gate verdict are kernel syscalls.

Inputs

  • --lane <name> (optional) — the lane to dispatch on (a name from the active [lanes]). Omitted = a bare auto-pick: the arbiter picks a free lane from the autopick ladder.
  • --leases <json> (optional) — the live leases other dispatches hold, as a JSON list of {lane, lane_kind, tree} (the arbiter keys exclusivity on lane_kind, so include it — cluster/keyword/global). In a real loop these come from a status query; for a single dispatch this is usually [].

Step 0 — Discover the layout + the lane taxonomy

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. lane is the lane to run on (may differ from the request when auto-pick reassigned it); tree is its file tree. Proceed.
  • outcome: "refuse" → not admitted. reason explains why; free_clusters lists lanes you could pick instead. Stop (or retry on a free lane). Do not force — --force is an operator-only override, not an automation default.

The exit code mirrors the outcome (0 = acquire, 1 = refuse), so the screenplay can branch on it directly.

Step 2 — Snapshot the portfolio (the packet)

Run /dos-next-up scoped to the acquired lane:

/dos-next-up --scope <LANE>

It writes a packet under paths.next_packets and returns its path + a gate verdict. Capture the packet path and its .dispositions-<tag>.json sidecar.

Step 3 — Gate the empty case (typed verdict)

Before shipping, classify the packet so an empty packet doesn't launch a no-op ship:

dos gate --workspace . <paths.next_packets>/.dispositions-<tag>.json

Branch on the exit code (the verdict IS the code):

  • 0 LIVE → there is dispatchable work; proceed to Step 4 (ship).
  • 3 DRAIN → empty backlog; skip the ship, archive a no-op, report drained.
  • 4 STALE-STAMP → shipped-but-unstamped drift; skip the ship, surface the drift for reconciliation (a /dos-replan can stamp it).
  • 5 BLOCKED → picks blocked; skip, surface.
  • 6 RACE → lost a render race; retry the snapshot once.

Step 4 — Ship the packet (LIVE only)

Launch the packet's dispatch list (the per-pick prompts /dos-next-up rendered). How you ship is host-shaped — the generic baseline launches each pick's prompt as its own agent. Record what shipped.

Step 5 — Archive the run

Write a run record under paths.runs (the run dir from dos doctor --json): the lane, the packet path, the gate verdict, and what shipped. Commit it with a generic subject — read your trunk and ship-grammar from config; do not hardcode a commit prefix. (dos doctor --json's stamp names the active grammar.)

Step 6 — Release the lane lease

If you took a cross-process dos lease for the archive, release it:

dos lease --workspace . release <owner>

The lane lease itself is advisory state in live_leases; a real loop (/dos-dispatch-loop) threads it forward. A single dispatch simply finishes.

Out-of-scope findings — file an issue, don't widen the lane

Shipping on one lane surfaces work that belongs to another: a bug in a different tree, a missing test, a doc that drifted from the code. Do not absorb it into this run's commits — the lease covers ONE lane's tree, and a widened diff is exactly the collision the admission kernel exists to prevent. Do not let it evaporate either. If the workspace has a public issue tracker (on a GitHub-hosted repo, the gh CLI), capture it there, then return to the leased lane:

  1. Dedupe first. Search before filing — gh issue list --search "<keywords>" — and comment on the existing issue rather than opening a twin.
  2. File it as a claim. The body carries a checkable done-condition (the command or observable that would witness it resolved), a lane guess, and where you found it. No done-condition yet = not an issue yet — it is design-shaped work for the workspace's planning surface.
  3. Leak-check the drafted body BEFORE posting. Issue text is public output that leaves through a door no tracked-file publication gate scans. Never include a machine-absolute path, a hostname, or a personal identifier; write paths workspace-relative. If the workspace ships a publication leak-scanner, pipe the draft through it first (write the body to a file outside the repo, scan it, post with --body-file); a hit is a refusal, not a warning.
  4. Close only by ancestry, never by narration. The honest close is Fixes #N in the commit BODY of the change that resolves it — the platform closes the issue when that commit lands on the trunk, an ancestry check the claimant didn't author (the same witness dos verify rides). gh issue close off "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.md heavy 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-loop adds 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 actual LaneDecision JSON 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 from free_clusters or 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-tune closes that hole the same way dos improve does: 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 move net_task_delta.

What the kernel decides vs. what you do

StepWhoWhat
Read the outcomesdos enforce-outcomesthe live false-DENY / held-catch ledger — what to tune toward
Propose ONE policy-knob editYOU (a subagent)the untrusted step — edit [intervention_policy] / [intervention] ranks / [improve] in a worktree
Measuredos enforce-tunescore the candidate policy's net_task_delta over the corpus, on the worktree
Keep / revert / escalatedos enforce-tune (rides dos improve)the kernel's typed verdict over env-authored facts — NOT your opinion
Merge / discard / escalateYOU (or the autonomous cadence)carry out the kernel's verdict

Inputs

  • --cases <corpus.jsonl> (required) — the labelled InterventionCase corpus the candidate policy is scored over (the docs/143 §13.2 ground truth). The reference corpus is the benchmark's intervention_cases.jsonl.
  • the autonomous cadence (below) reads the dos enforce-tune EXIT 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 — in dos.toml. Make the SMALLEST edit that should move net_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:

  • 0 KEEP — suite green, truth clean, candidate net_task_delta strictly beat B, no runtime-logic edit. Witnessed. Go to Step 4-KEEP.
  • 3 REVERT — a regression (suite red / a runtime-logic edit / truth dirty) or a no-op (the metric did not beat B). Go to Step 4-REVERT.
  • 4 ESCALATE — the breaker is open (--max-reverts non-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> then B=<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 decisions entry 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-tune KEEPs only on a kernel-measured strict net_task_delta gain 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_delta is 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), which net_task_delta penalizes; 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-gate is one self-stopping leaf — a single agent whose "done" is grounded. dos-goal-fleet arms many such leaves at once. Each child runs the goal-gate discipline; this skill is the launcher and the rollup around them.
  • dos-witness-claim is 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-gate when it is one objective — just arm a single self-stopping agent; no fleet needed.
  • Use dos-dispatch / dos-next-up when 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-fleet arms leaf objectives, which is exactly the sanctioned use.

Inputs

ShapeWhat it looks likeRoute
Explicit goal list"goal 1: …, goal 2: …, goal 3: …"one instance per listed goal
A context to decomposea paragraph / doc / set of asksStep 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 the dos arbitrate co-launch check in Step 2.
  • paths.plans_glob / stamp — the host's plan grammar and ship-stamp convention, for the dos verify ship-witness in Step 5.
  • git — if false, the git-phase ship-witness (Step 5) has no history; every claimed ship resolves source="none". Say so; do not silently pass it.
  • runtime_hooks — which runtimes already have dos hook stop wired (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 = 1 and 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):

  1. 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.
  2. 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.
  3. No uppercase verdict tokens in the condition text (no SHIPPED / BLOCKED / DONE literals) — 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-gate Step 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. Read free_clusters for 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 commit on 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, or git 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:

  1. WAVE = min(SERVING, remaining_goals, --max-concurrent) (from Step 0).
  2. Launch WAVE instances 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.
  3. 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.
  4. 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, SERVING overstates 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 as blocked-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 diff
    

    Read 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-effect CLI verb — gather an independently-authored read-back via the dos.evidence_sources seam (the Python-API pattern in dos-goal-gate Step 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's seat.txt and 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) and dos verify are 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 /loop worker, a self-stopping task agent, or any run where the operator stated a completion condition.
  • Use dos-witness-claim instead when many workers' results are folded at a parallel()/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 — if false, the git-existence witness (Step 2a) has no history; every git-phase effect resolves source="none". Say so; do not silently pass it.
  • runtime_hooks — which runtimes already have a dos 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 stop blocks 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 is dos 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 /goal condition string (the harness exposes no goal field to hooks). So dos hook stop does 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 assertsWitness (byte-author ≠ agent)Verb today
"(plan, phase) is shipped"git ancestry + ship-stamp grammardos verify (Step 2a) — SHIPPED
"this terminal result is real" (a transcript is in play)harness authorship markerdos verify-result — SHIPPED
"I created file X / inserted row Y / sent message Z / deployed"a fresh GET / state-diff / OS exit / counterparty recordno 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 to registry.
  • 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 stop emits {"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; a source:"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 — ask dos 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 marker when 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 --json and 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 in dos.toml. It names no host directory, no host lane, and no host commit convention — every host specific comes from dos doctor --json (paths/lanes, via WCR) or dos.toml [stamp] (the ship grammar, via SCV). Copy it into your own skills dir, point dos at 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/verdicts under 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 verify applies 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:

  1. Header — the workspace root, the active lane taxonomy, the run timestamp.
  2. Portfolio snapshot — one row per plan: plan id, how many phases, how many verified shipped (from Step 2), the next live phase.
  3. 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-price so a colliding set is caught before any agent launches, not when the colliding lease is refused mid-wave.
  4. Already shipped — the picks Step 2 found shipped: true, with source/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):

  • 0 LIVE — the packet has dispatchable work; report the packet path and the dispatch count. This is the success case.
  • 3 DRAIN — no live picks: a genuine empty backlog. Report "nothing to dispatch — the portfolio is drained."
  • 4 STALE-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.
  • 5 BLOCKED — picks exist but are blocked (a sibling claim / quota). Surface.
  • 6 RACE — 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.md heavy tier). dos-dispatch takes a lane lease via dos 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 dos workspace. Copy-pasteable verbs, actual captured output. The whole point is the last gloss on each block: read the RUNG, not the bare shipped boolean.

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 (the paths object).
  • ❌ 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 lanes from 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: verify reads a commit that already shipped, arbitrate refuses 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-fleet wave, a dos-next-up packet'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 arbitrate at 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-fleet wave → one entry per objective, its declared scope.
  • A dos-next-up packet → 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_now this wave (the maximal disjoint set), and hold the colliding agents for a later wave; or
    • Apply the repartition suggestion (narrow the colliding trees), re-run Step 2, and launch once the price is 0.

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_price because dos 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 arbitrate at acquire. The price is a forward estimate over a forgeable declared partition; the lease arbiter is the floor. Do both.
  • ❌ Faking a dos price-plan call. 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-promote does 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: a DRAFT_CLASS hold wants a promotion, a SOAK_OPEN hold wants the clock, an OPERATOR_GATED hold wants a decision. This is the operator-facing half of the shipped pickable primitive.

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):

  • 0 OFFERABLE → a worker could pick it up now; NOT surfaced (it is not stuck).
  • 10 DRAFT_CLASS → the plan is draft-class; the unblock is a promotion.
  • 11 OPERATOR_GATED → blocked on a decision; raise it.
  • 12 SOAK_OPEN → a soak deadline; wait (never promote — time un-gates it).
  • 13 DEPENDENCY_UNMET → ship the prerequisite first.
  • 24 UNPARSEABLE → inspect/fix the deriver or the doc; the unit is invisible.
  • 20–23 IN_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:

HoldUnblock action
DRAFT_CLASSpromote the plan draft→active (the workspace's lifecycle default→next class)
OPERATOR_GATEDraise an operator decision (dos decisions add)
SOAK_OPENwait for the soak to close — surface the deadline, do NOT promote
DEPENDENCY_UNMETship the named prerequisite first
UNPARSEABLEinspect 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's lifecycle.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 is master, not main — 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 — master here, main elsewhere; 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 master trunk and a main trunk 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 verify over the portfolio each cadence, then lets dos gate decide 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 is master.
  • ❌ 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 verify as 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 the dos decisions queue.

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 decisions queue — 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 verify flips 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 verify only.
  • ❌ 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 improve verdict, 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 improve closes 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

StepWhoWhat
Propose one scoped changeYOU (a subagent)the capable, untrusted step — the only place intelligence enters the loop
Verify + measuredos verbsrun the suite, run the truth syscall, measure the metric — all on an isolated worktree
Keep / revert / escalatedos improvethe kernel's typed verdict over the env-authored facts — NOT your opinion
Merge / discard / escalateYOUcarry 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 is lint-clean = a large constant minus the dos lint finding 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 (the productivity/efficiency work-unit split).
  • --max-cycles <N> (default 5) — the backstop cap (the ITERATION_CAP analogue).
  • --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:

  • 0 KEEP — suite green, truth clean, W > B (a strict env-measured gain), and not wasteful. The improvement is witnessed. Go to Step 4-KEEP.
  • 3 REVERT — either a REGRESSION (suite red / truth dirty — the non-negotiable floor) or a NO-OP (safe but W did not beat B). Go to Step 4-REVERT.
  • 4 ESCALATE — the breaker is open (--max-reverts non-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 — log and 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 improve over 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 runs python -m dos_mcp.server — both need the dos-kernel package 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 python resolves to here). Then re-run Step 1. If python is 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 the pip 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 — AUTH1 was committed → SHIPPED (exit 0); AUTH2 was only claimed → NOT_SHIPPED (exit 1). The verdict comes from git, not the agent.
  • the admission kernel — frontend and backend acquire concurrently (their file trees are disjoint), while release refuses (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-hook binary 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.

  • MCP tools (the dos server — check /mcp shows 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-stats shows 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 pip for 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 dos verbs 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 a dos verb 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 dos verbs 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_kindRecipeThe dos verb the converted step uses
"(plan,phase) / this code shipped"SHIPPEDR1dos verify — read the rung (registry > grep-subject > none), never the bare bool
"this commit did what its subject says"COMMIT_HONESTR1dos commit-audit — subject vs. its own diff
"keep working until the goal is met"GOAL_DONER1bdos hook stop wired alongside the harness goal (ANY-block)
"I created file / row / message / deploy"EFFECTR9/§2beffect 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)"WRITER2dos arbitrate over the tree before writing; honor the redirect
"is there work / safe to proceed"GATER3dos gate — branch on the exit code, not the printed line
"how is run R doing"RUN_STATER4dos status — the digest with no claimed field
"this tool-loop is progressing"LOOP_LIVER5tool_stream (Python API) — distrust repetition, not correctness
"this long job is alive"ALIVER6dos lease-lane heartbeat + dos liveness
"this recalled memory is still true"RECALLR7dos recall — re-verify at read time
"all N fan-out workers returned a real result"FANOUTR9/R10dos verify-result + dos coverage --declared N
"this issue / ticket is resolved"ISSUE_DONE(issue-verify)witness each effect, fold, then close
taste / intent / future workUNWITNESSABLE—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 dos verb → 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-gate is 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 / recall ahead 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 0 running dos doctor --json if the source lacks one.
  • Extend the frontmatter allowed-tools: with Bash/PowerShell if you added a dos shell-out (and the dos_* 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: . If dos is 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.md table + the count of ADD / REPLACE / GUARD / LEAVE / UNWITNESSABLE sites, and the commit-audit verdict.
  • 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_kind is 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 dos call for an UNWITNESSABLE claim "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 + a commit-audit verdict. 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 --json and keep it data.
  • ❌ Hard-requiring dos to 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-hook binary 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 pretool record 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; 0 means 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 stats verb 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 --target worker 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-loop per free admissible lane. The what to do is a typed kernel verdict — dos loop emits 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:

  1. SPAWN — a free, admissible lane below target: launch one worker on it.
  2. REAP — a STALLED lease: scavenge it so the lane is free to refill.
  3. HOLD — an ADVANCING (or alive-counted SPINNING) worker: leave it alone.
  4. 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 --target above 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 --target above 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 in dos.toml [supervise] max_concurrency, or pass --max-concurrency for 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_PROPOSED on the ledger. Do NOT scavenge; the proposal surfaces automatically in dos decisions for 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_DIVERGED row in dos 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 --json and the workspace's dos.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 dos verbs against this workspace (dos doctor reports is_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 in dos.toml [lanes]; (b) on a DYNAMIC-CLAIM roster (concurrent = [], per-pick disjointness), declare a --max-concurrency budget (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-unstick asks 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 — the recurring_wedge DEFAULT_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_sources driver hook; the generic sweep reads only the run-archive verdicts. log a one-line note when a host evidence source is not consulted — no silent gap (the /dos-dispatch-loop discipline).

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_sources hook. log when 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 wedge and the path from dos 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 dos verbs 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 a pipeline() 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 — if false, the git-existence witness (Step 3a) has no history to read; every git-phase claim will be source="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":

  • 3 DEAD — 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.
  • 0 HEALTHY — a real terminal result; proceed to Step 2. (0 also 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 typeWhat the worker assertsWitness (byte-author ≠ agent)Verb today
git phase"(plan, phase) shipped"git ancestry + ship-stamp grammardos verify (Step 3a) — SHIPPED
terminal statethe result itself is realharness authorship markerdos 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 recordNO 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 to registry.
  • 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.judges seam — 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-effect verb (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_sources driver 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). Run dos verify-result first.
  • ❌ 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 --json and 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