dos-kernel 0.22.0__py3-none-win_amd64.whl

dos/skills/dos-goal-gate/SKILL.md

@@ -0,0 +1,269 @@
+---
+name: dos-goal-gate
+description: Ground a "keep working until the goal is met" stop condition in a witness the agent did not author, instead of letting the agent self-certify "done". A harness goal/Stop-hook condition is normally checked by the model re-reading its OWN work — consistency, not grounding. This skill turns the operator's goal into checkable EFFECT claims and wires `dos hook stop` so the Stop is refused until git ancestry (a shipped phase) or an effect read-back corroborates the claimed effect. Driven by `dos` verbs and the workspace's own `dos.toml` — no host-specific paths, lanes, or commit conventions. Use when you want a self-stopping agent (or a `/loop` worker) to be unable to declare a goal complete on its own say-so. The single-agent self-stop analogue of `dos-witness-claim`.
+---
+
+# 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.**
+
+```bash
+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:
+
+```bash
+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 2 — State the goal as checkable effects (the decomposition)
+
+A goal is met when its **effects** are present in the world. Translate the prose
+goal into a list of named, checkable effects — and **abstain rather than invent**.
+An effect you cannot name an identifier for is not a passable goal; it is a
+**NO_CLAIM** to surface for the operator, never a test you fabricate (docs/134).
+
+Map each effect to its witness rung:
+
+| Effect the goal asserts | Witness (byte-author ≠ agent) | Verb today |
+|---|---|---|
+| "(plan, phase) is shipped" | git ancestry + ship-stamp grammar | `dos verify` (Step 2a) — SHIPPED |
+| "this terminal result is real" (a transcript is in play) | harness authorship marker | `dos verify-result` — SHIPPED |
+| "I created file X / inserted row Y / sent message Z / deployed" | a fresh GET / state-diff / OS exit / counterparty record | **no CLI verb** (Step 2b) — Python-API gap |
+
+The first two are shipped CLI verbs. The third is the open seam — handled
+honestly in Step 2b. The goal's "done" is the **conjunction** of all its effects'
+witnesses: every one CONFIRMED/SHIPPED, or the goal is not met.
+
+### Step 2a — git-phase effects: ask the truth syscall
+
+For each `(plan, phase)` the goal names, never trust "I committed it" and never
+grep commit subjects yourself:
+
+```bash
+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:
+
+```python
+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:
+
+```bash
+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/skills/dos-next-up/SKILL.md

@@ -0,0 +1,231 @@
+---
+name: dos-next-up
+description: Snapshot a repo's phased-plan portfolio and produce a parallel-agent dispatch packet, driven entirely by `dos` verbs and the workspace's own `dos.toml` — no host-specific paths, lanes, or commit conventions. Walks the configured plans glob, audits each candidate pick against `dos verify` for its true shipped/unshipped status, renders a self-contained packet to the configured output dir, and reports a typed gate verdict via `dos gate`. Use when you want a "where are we / what's next / who-does-what" snapshot of any repo that has a few plan docs and real commits. This is the DOS reference workflow (SKP Axis 5); a host may use it, fork it, or ignore it.
+---
+
+# 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.**
+
+```bash
+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:
+
+```bash
+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).
+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:
+
+```json
+{
+  "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:
+
+```bash
+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):
+
+```bash
+$ dos doctor --workspace . --json
+# dos_version 0.22.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`:
+
+```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"}
+```
+↳ 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:
+
+```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"}
+```
+↳ RUNG `source="none"`: no positive git/registry evidence → a live pick.
+
+Step 4 — gate the packet; the verdict IS the exit code:
+
+```bash
+$ 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/skills/dos-promote/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: dos-promote
+description: The visibility-inverse of lifecycle-demote. Run `dos pickable` over every declared unit; for each HELD unit, surface it with its typed HoldReason and the derived unblock action (DRAFT_CLASS→promote-to-active, UNPARSEABLE→inspect-the-deriver, OPERATOR_GATED→raise-a-decision, SOAK_OPEN→wait, DEPENDENCY_UNMET→ship-the-prerequisite). The only auto-applied action is a safe mechanical reclassify (gated, one commit); everything else is surfaced for a human via `dos decisions`. Every path/lane/class comes from `dos doctor --json`. Use when units are stuck un-pickable and you want each one's typed reason + the right unblock move. The operator-facing half of the shipped `pickable` gate (SKP Axis 5, docs/207 Phase 5b).
+---
+
+# 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
+
+```bash
+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:
+
+```bash
+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):
+
+```bash
+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:
+
+| Hold | Unblock action |
+|---|---|
+| `DRAFT_CLASS` | promote the plan draft→active (the workspace's `lifecycle` default→next class) |
+| `OPERATOR_GATED` | raise an operator decision (`dos decisions add`) |
+| `SOAK_OPEN` | wait for the soak to close — surface the deadline, do NOT promote |
+| `DEPENDENCY_UNMET` | ship the named prerequisite first |
+| `UNPARSEABLE` | inspect the deriver / backfill the doc's phase grammar |
+
+A host may declare a richer reason→action map in `dos.toml`; absent one, this
+default routing (documented on the `HoldReason` enum) is used.
+
+## Step 4 — Auto-enact ONLY the safe mechanical reclassify
+
+The single auto-applied action is the **DRAFT→active promotion** of a plan whose
+draft phases are demonstrably wanted — a mechanical plan-meta `classification:`
+edit + ONE commit, gated. Read the trunk + ship grammar from `dos doctor --json`'s
+`stamp`; **do not hardcode a commit prefix.** Everything else — a decision, a
+soak wait, a dependency, an unparseable doc — is surfaced for a human, never
+auto-applied (those are real judgment calls).
+
+## Step 5 — Surface the rest
+
+```bash
+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`.