dos-kernel 0.22.0__py3-none-win_amd64.whl

dos/skills/dos-class-cycle/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: dos-class-cycle
+description: One automatic plan-class lifecycle tick. Reads the DECLARED class set + transition list from the workspace `[lifecycle]` table (not a hardcoded taxonomy), evaluates each trigger, spawns a read-only JUDGE-rung adjudicator (the `dos.judges` seam — advisory, fail-to-abstain) to approve/defer each candidate transition, applies the gated transitions as plan-meta edits + one commit per cycle, and logs to the run archive. Failsafes (per-cycle cap, per-plan cooldown, a veto class) are `[lifecycle]` data; the judge content is a host `dos.judges` driver. Every path/class comes from `dos doctor --json`. Use to garden a plan portfolio's lifecycle automatically, judge-gated. The DOS lifecycle gardener (SKP Axis 5, docs/207 Phase 5c).
+---
+
+# 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
+
+```bash
+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 verify`s 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:
+
+```bash
+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/skills/dos-dispatch/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: dos-dispatch
+description: End-to-end plan-and-ship for one lane — snapshot the portfolio with /dos-next-up, take a lane lease via `dos arbitrate` so parallel dispatches don't collide, gate the empty case via `dos gate`, ship the packet, and archive the run under the configured run dir. Driven entirely by `dos` verbs + the workspace's `dos.toml`; names no host path, lane, or commit convention. Use when you want to plan and ship the next batch on one lane in a single command, with concurrency safety. The DOS reference dispatch workflow (SKP Axis 5).
+---
+
+# dos-dispatch — the generic chained snapshot→ship cycle
+
+> **The concurrency-safe dispatch.** It chains `/dos-next-up` (the packet) to a
+> ship, but first takes a **lane lease** through the admission kernel so several
+> dispatches on disjoint lanes run in parallel without editing the same files.
+> The "may I run on this lane" decision is the kernel's (`dos arbitrate`), not
+> inline prose. Every path/lane comes from `dos doctor --json`; nothing is
+> hardcoded.
+
+The shape: **discover → take a lane → snapshot → gate → ship → archive.** The
+lane taxonomy and the run-dir location are data (`[lanes]`, `[paths]`); the
+admission and the gate verdict are kernel syscalls.
+
+## Inputs
+
+- `--lane <name>` (optional) — the lane to dispatch on (a name from the active
+  `[lanes]`). Omitted = a bare auto-pick: the arbiter picks a free lane from the
+  `autopick` ladder.
+- `--leases <json>` (optional) — the live leases other dispatches hold, as a JSON
+  list of `{lane, lane_kind, tree}` (the arbiter keys exclusivity on `lane_kind`,
+  so include it — `cluster`/`keyword`/`global`). In a real loop these come from a
+  status query; for a single dispatch this is usually `[]`.
+
+## Step 0 — Discover the layout + the lane taxonomy
+
+```bash
+dos doctor --workspace . --json
+```
+
+Read `lanes` (the taxonomy), `paths.next_packets` (packet output), and
+`paths.runs` (the run dir to archive under). **Use these; never hardcode a lane
+name or a run path.**
+
+## Step 1 — Take a lane lease (the admission kernel)
+
+Ask the kernel whether this dispatch may run on the requested lane, given the
+live leases. The arbiter runs the tree-disjointness algebra over the lanes'
+declared trees — two dispatches on disjoint trees both ADMIT; overlapping trees
+COLLIDE.
+
+```bash
+dos arbitrate --workspace . --lane <LANE> --kind cluster --leases '<LIVE_LEASES>'
+```
+
+Read the `LaneDecision` JSON: `{outcome, lane, tree, reason, free_clusters, …}`.
+
+- `outcome: "acquire"` → admitted. `lane` is the lane to run on (may differ from
+  the request when auto-pick reassigned it); `tree` is its file tree. Proceed.
+- `outcome: "refuse"` → not admitted. `reason` explains why; `free_clusters`
+  lists lanes you could pick instead. **Stop** (or retry on a free lane). Do not
+  force — `--force` is an operator-only override, not an automation default.
+
+The exit code mirrors the outcome (0 = acquire, 1 = refuse), so the screenplay
+can branch on it directly.
+
+## Step 2 — Snapshot the portfolio (the packet)
+
+Run `/dos-next-up` scoped to the acquired lane:
+
+```
+/dos-next-up --scope <LANE>
+```
+
+It writes a packet under `paths.next_packets` and returns its path + a gate
+verdict. Capture the packet path and its `.dispositions-<tag>.json` sidecar.
+
+## Step 3 — Gate the empty case (typed verdict)
+
+Before shipping, classify the packet so an empty packet doesn't launch a no-op
+ship:
+
+```bash
+dos gate --workspace . <paths.next_packets>/.dispositions-<tag>.json
+```
+
+Branch on the exit code (the verdict IS the code):
+
+- `0` **LIVE** → there is dispatchable work; proceed to Step 4 (ship).
+- `3` **DRAIN** → empty backlog; **skip the ship**, archive a no-op, report drained.
+- `4` **STALE-STAMP** → shipped-but-unstamped drift; skip the ship, surface the
+  drift for reconciliation (a `/dos-replan` can stamp it).
+- `5` **BLOCKED** → picks blocked; skip, surface.
+- `6` **RACE** → lost a render race; retry the snapshot once.
+
+## Step 4 — Ship the packet (LIVE only)
+
+Launch the packet's dispatch list (the per-pick prompts `/dos-next-up` rendered).
+How you ship is host-shaped — the generic baseline launches each pick's prompt as
+its own agent. Record what shipped.
+
+## Step 5 — Archive the run
+
+Write a run record under `paths.runs` (the run dir from `dos doctor --json`): the
+lane, the packet path, the gate verdict, and what shipped. Commit it with a
+generic subject — **read your trunk and ship-grammar from config; do not hardcode
+a commit prefix.** (`dos doctor --json`'s `stamp` names the active grammar.)
+
+## Step 6 — Release the lane lease
+
+If you took a cross-process `dos lease` for the archive, release it:
+
+```bash
+dos lease --workspace . release <owner>
+```
+
+The lane lease itself is advisory state in `live_leases`; a real loop
+(`/dos-dispatch-loop`) threads it forward. A single dispatch simply finishes.
+
+## 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.22.0`); copy-paste, then read the RUNG.
+
+```bash
+$ 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.
+
+```bash
+$ 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 busy).","tree":["benchmark/**"]}
+```
+exit 0 (**acquire**) — but you asked for `src` and got `benchmark`: a live lease made
+`src` contended, so the admission kernel redirected rather than double-book. Run on
+`lane` (= `benchmark`), not your request. exit 1 (**refuse**) would mean stop / pick from `free_clusters`.
+
+```bash
+$ 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.
+
+```bash
+$ 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.
+
+```bash
+$ 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`.

dos/skills/dos-dispatch-loop/SKILL.md

@@ -0,0 +1,254 @@
+---
+name: dos-dispatch-loop
+description: Run /dos-dispatch on a recurring cadence, alternating with /dos-replan when the backlog drains — the dispatch→replan→dispatch cycle. The continue/stop/next-mode decision is the kernel's typed loop decision, not inline prose: each iteration is classified (`dos gate`) into a verdict and the loop's counters (drained-twice, the unclear/dirty-zero breakers, the iteration cap) drive the next step. Several loops on disjoint lanes run concurrently, each taking its own lane lease via `dos arbitrate`. Driven entirely by `dos` verbs + the workspace's `dos.toml`. The DOS reference loop workflow (SKP Axis 5).
+---
+
+# 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).
+
+The last two are the docs/207 anti-churn rungs: the loop stops re-picking work it
+cannot move, instead of burning the cap re-confirming a known hold.
+
+## 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
+
+```bash
+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:
+
+```bash
+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 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:
+
+```bash
+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 `log`s 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):
+
+```bash
+$ 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 busy).","tree":["benchmark/**"]}
+```
+
+→ exit `0` (`acquire`); the redirect IS the admission kernel refusing a collision.
+
+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):
+
+```bash
+$ 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):
+
+```bash
+$ 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):
+
+```bash
+$ 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`.