dos-kernel 0.22.0__py3-none-win_amd64.whl

dos/skills/dos-replan/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: dos-replan
+description: Garden a repo's plan portfolio from accumulated evidence — detect closures (a queue item whose phases now `dos verify` as shipped is done), track cooldown state, and surface the 0-2 items the operator must actually decide via the `dos decisions` queue. Read-only on code/data; writes only its queue + cooldown state. Driven by `dos` verbs + the workspace's `dos.toml`; names no host path or convention. Use after a burst of dispatches, when the backlog looks drained, or when recurring findings start hurting throughput. The DOS reference planning-sweep workflow (SKP Axis 5).
+---
+
+# 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
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+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 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 `log`s
+  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):
+
+```bash
+$ 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:
+
+```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"}
+```
+
+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:
+
+```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"}
+```
+
+Step 6 reconcile — feed the dispositions to the gate; a stale stamp returns exit 4:
+
+```bash
+$ 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.

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

@@ -0,0 +1,114 @@
+---
+name: dos-replan-loop
+description: Run /dos-replan on a fixed cadence for a bounded number of iterations, then stop — an unattended planning-refresh sweep. A thin recurring wrapper over /dos-replan plus an optional guarded release; the release guard reads the workspace's trunk from config rather than assuming a branch name. Driven by `dos` verbs + the workspace's `dos.toml`. The DOS reference planning-loop workflow (SKP Axis 5).
+---
+
+# 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:**
+
+```bash
+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`.
+
+## 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.
+
+```bash
+$ 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.
+
+```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"}
+```
+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.
+
+```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"}
+```
+NOT_SHIPPED via the **none** rung (exit 1) — git ancestry has not stamped it; this phase is still in flight.
+
+```bash
+$ 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.
+
+```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/**"]}
+```
+You asked for `src`; the arbiter handed back `benchmark` (exit 0, `outcome:acquire`) — a live lease made `src` contended, and the admission kernel refused to double-book the busy region.
+
+## 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/skills/dos-self-improve/SKILL.md

@@ -0,0 +1,213 @@
+---
+name: dos-self-improve
+description: Run a self-improving work loop where the kernel — not the agent's say-so — decides whether each candidate change actually improved the codebase. The propose→verify→measure→keep-or-revert cycle with one rule no prior auto-improver enforced: a candidate is KEPT only if a witness the candidate's author did not write CONFIRMS it improved (the test suite green on a clean worktree, the truth syscall clean, and a strictly-measured metric gain). Otherwise it is REVERTED. The keep/revert/escalate decision is the kernel's typed `improve` verdict (`dos improve`), not inline prose; a run of non-keeps trips a breaker that ESCALATEs to a human. Each candidate is applied in an ISOLATED git worktree so the kernel adjudicating it is never the kernel being rewritten. Driven entirely by `dos` verbs + the workspace's own `dos.toml` — no host-specific paths, lanes, or commit conventions. The DOS reference recursive-self-improvement loop (SKP Axis 5, docs/280).
+---
+
+# 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
+
+| Step | Who | What |
+|---|---|---|
+| **Propose** one scoped change | YOU (a subagent) | the capable, *untrusted* step — the only place intelligence enters the loop |
+| **Verify + measure** | `dos` verbs | run the suite, run the truth syscall, measure the metric — all on an isolated worktree |
+| **Keep / revert / escalate** | `dos improve` | the kernel's typed verdict over the env-authored facts — NOT your opinion |
+| **Merge / discard / escalate** | YOU | carry out the kernel's verdict |
+
+The kernel contributes ZERO intelligence to the proposal — only the refusal to
+keep an unwitnessed one. That asymmetry is the whole design.
+
+## Inputs
+
+- `--metric <name>` (required) — what "improvement" means for THIS workspace, as a
+  non-negative integer the environment measures, higher = better. The reference
+  metric 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
+
+```bash
+dos doctor --workspace . --json
+dos arbitrate --workspace . --lane <LANE>
+```
+
+Then establish the baseline — and this gate is non-negotiable:
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+# (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.**
+
+```bash
+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>" --json
+```
+
+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:
+  ```bash
+  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.
+  ```bash
+  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):
+  ```bash
+  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.
+
+## 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/skills/dos-supervise-loop/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: dos-supervise-loop
+description: Keep a target population of worker dispatch-loops alive across a workspace's lane roster — the supervisor cadence (the init/PID-1 analogy for a fleet). Each tick reads the active lane taxonomy from `dos doctor --json`, asks the kernel for a spawn/reap/flag plan via `dos loop --target N --json`, launches one `/dos-dispatch-loop` per SPAWN, scavenges only STALLED leases, and SURFACES (never kills) a SPINNING worker. The spawn/reap/flag decision is the kernel's typed `supervise()` verdict, not inline prose — the supervisor only carries out the plan. Driven entirely by `dos` verbs + the workspace's `dos.toml`. The DOS reference supervisor workflow (SKP Axis 5).
+---
+
+# 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
+
+```bash
+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 scavenge, per FLAG surface
+
+For each lane in the plan's `reap` list (a STALLED worker): release/scavenge its
+lease so the lane is free to refill on the next tick. The worker is not making
+progress by the kernel's temporal verdict, so its claim on the lane is the only
+thing being reclaimed — the lane returns to the roster as a spawn candidate.
+
+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 — Sleep, re-tick, stop on interrupt or --max-ticks
+
+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.
+
+## 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:
+
+```bash
+$ 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:
+
+```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)."}
+```
+
+You asked for `src`; a live lease made it contended, so the arbiter redirected to
+`benchmark` — exit `0` (acquire). The redirect IS admission refusing a busy region.
+
+Per run, fold ONE digest instead of re-reading state files (no `claimed` field):
+
+```bash
+$ 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:
+
+```bash
+$ 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.