dos-kernel 0.22.0__py3-none-win_amd64.whl

dos/skills/dos-unstick/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: dos-unstick
+description: Sweep the run-archive trail of BLOCKED/DRAIN verdicts, normalize each to a canonical cause via the recurring-wedge fold, cluster by recurrence × stall-cost, and propose ONE structural fix per recurring cause — a contract/oracle/preflight change, never a one-off unblock. Read-only on code; surfaces via `dos decisions`. The cause taxonomy is `[reasons]` data; every path/lane comes from `dos doctor --json`. Use when a fleet keeps stalling on the same thing across runs and you want the structural fix, not another manual unblock. The DOS operator remediation sweep (SKP Axis 5, docs/207 Phase 5a).
+---
+
+# dos-unstick — the recurring-blocker remediation sweep
+
+> **Stop the cause, not the instance.** A one-off unblock fixes today's stall;
+> `/dos-unstick` asks the different question — *what keeps blocking progress
+> across runs, and what one change would unblock it?* It mines the run archive,
+> normalizes every blocker to a canonical **cause key**, clusters the recurring
+> ones, ranks by recurrence × measured stall-cost, and proposes a **structural**
+> fix per cluster. Read-only; it writes no code and surfaces findings, never acts.
+
+The shape: **mine the trail → key each blocker → cluster the recurring ones →
+rank → propose a structural fix → surface.** The recurrence fold is the kernel's
+(`recurring_wedge`); the cause TAXONOMY is `[reasons]` data — a host adds a cause
+by declaring a reason, never by editing this skill.
+
+## Inputs
+
+- `--runs <N>` (optional) — how many most-recent runs to sweep (default: a recent
+  window). `--since <Nd|Nh>` overrides with a time window.
+- `--min-recurrence <N>` (optional) — a cause is "recurring" at N+ distinct runs
+  (default 2 — the `recurring_wedge` `DEFAULT_MIN_RECURRENCE`).
+
+## Step 0 — Discover the layout + the cause taxonomy
+
+```bash
+dos doctor --workspace . --json
+```
+
+Read `paths.runs` (the run-archive dir to sweep) and run `dos man wedge` to read
+the **closed reason vocabulary** — the canonical cause keys this workspace knows.
+**Use these; never hardcode a run path or a cause string.** A cause the workspace
+cares about is a declared `[reasons]` entry, surfaced by `dos man wedge`.
+
+```bash
+dos man wedge
+```
+
+## Step 1 — Mine the run-archive trail
+
+Read the run records under `paths.runs` (read each once, sequentially — no
+tailing/polling, the very anti-pattern this sweep exists to surface). For each
+run that STOPPED on a BLOCKED / DRAIN / STALLED outcome, capture: the run id, the
+iteration, the blocker text, and the measured stall cost (`$`/wall) if recorded.
+
+> **No host evidence reader is wired by default.** A host that curates a
+> postmortem stream or a hand-ranked next-hits file can expose it as a
+> `dos.evidence_sources` driver hook; the generic sweep reads only the run-archive
+> verdicts. **`log` a one-line note when a host evidence source is not consulted**
+> — no silent gap (the `/dos-dispatch-loop` discipline).
+
+## Step 2 — Key each blocker to a canonical cause
+
+Normalize each blocker text to ONE cause key from the declared `[reasons]`
+vocabulary (the host's cue table maps an Outcome-cell string to a key — the same
+kernel-catalog ↔ host-cue split `dos man wedge` documents). A blocker that maps to
+no declared cause is keyed `UNCATEGORIZED` (surfaced as a gap, never dropped).
+
+## Step 3 — Cluster the recurring causes (the kernel fold)
+
+Feed the keyed blockers to the recurrence fold. It clusters by cause key, ranks by
+recurrence (dominant) × stall-cost (the tie-break), and tells you whether the
+cause the CURRENT sweep hit spans `>= min-recurrence` distinct runs:
+
+The fold is `recurring_wedge.classify_recurring_wedge` — pure, frozen-data-in,
+verdict-out. A cluster spanning ≥ `min-recurrence` runs is **recurring** (worth a
+structural fix); a one-off is noise the sweep cannot help.
+
+## Step 4 — Propose ONE structural fix per recurring cluster
+
+For each recurring cluster, propose a **structural** change — a contract edit, an
+oracle rung, a preflight check — that would stop the cause RECURRING, not a
+one-off unblock of today's instance. Rank the proposals by the cluster's
+stall-score (recurrence × cost). The cause→fix mapping is the host's `[reasons]`
+fix-sketch (the reason's documented remediation), not a literal in this skill.
+
+## Step 5 — Surface, don't act
+
+Route each proposal to the operator-decision queue:
+
+```bash
+dos decisions add  # the routing surface; the proposal is a finding, not an edit
+```
+
+This skill is **read-only**: it writes no code, edits no plan, takes no lease. A
+recurring cause is a finding for a human (or a follow-up plan), not an
+auto-applied change — the structural fix is a real engineering decision.
+
+## What this skill deliberately does NOT do (no silent gap)
+
+- **No auto-unblock.** It proposes the structural fix; a human applies it. A loop
+  that auto-unblocks would paper over the recurring cause, the exact failure mode.
+- **No curated postmortem / next-hits ingestion** unless a host wires a
+  `dos.evidence_sources` hook. `log` when it is not consulting one.
+- **No trajectory mining** by default (the heavier read) — the run-archive
+  verdicts are the generic floor.
+
+## Anti-patterns
+
+- ❌ Proposing a one-off unblock for a 3-run recurring cause — that is the bug
+  this skill exists to replace. Recurring ⇒ structural.
+- ❌ Hardcoding a cause string or a run path — read the vocabulary from
+  `dos man wedge` and the path from `dos doctor --json`.
+- ❌ Tailing/polling the run dir — read each record once; polling is the waste
+  this sweep surfaces in others.

dos/skills/dos-witness-claim/SKILL.md

@@ -0,0 +1,251 @@
+---
+name: dos-witness-claim
+description: Route a subagent's actionable claims through the witness rung instead of folding its return string. For any worker whose deliverable is a CHECKABLE EFFECT — a shipped git phase, a created file, a DB row, a sent message — do NOT believe what the worker said it did; extract the claim at the boundary, gather an independently-authored read-back, and fold ONLY the confirmed effects. Driven by `dos` verbs and the workspace's own `dos.toml` — no host-specific paths, lanes, or commit conventions. Use at a `parallel()`/`pipeline()` barrier, a synthesis step, or any fold site where one agent's output becomes another's input. This is the DOS reference pattern for the docs/197 §7(2) witness-routing stage; the seam below is honest about which steps have a CLI verb and which are Python-API-only today.
+---
+
+# dos-witness-claim — fold the witnessed effect, never the narrated one
+
+> **This is the screenplay for the one move the whole substrate exists to make:**
+> when a subagent hands you a result, the result is a *claim*, not a fact. A claim
+> re-narrating the agent's own work is **consistency, not grounding** (docs/138).
+> Belief is earned only by a read-back whose **byte-author is not the judged
+> agent** (a fresh GET, a git existence check, an OS exit code, a state diff). This
+> skill never decides ground truth itself — it shells `dos` verbs and reads the
+> verdict. The kernel decides; the skill narrates.
+
+The shape is domain-free: **discover the layout → classify the claim type →
+witness it on a non-forgeable rung → fold ONLY confirmed.** The *policy* (which
+lanes, which plan grammar, where state lives) is data the screenplay reads from
+`dos doctor --json`, never literals it hardcodes.
+
+**The seed-2 payoff.** This makes the worker's MODEL TIER irrelevant to trust. A
+weak worker and a strong worker face the SAME witness gate: both have their
+claimed effect re-read from a surface they did not author. A confident, fluent,
+frontier-strength narration of a success the world does not corroborate is exactly
+the silent fail this gate catches (docs/177) — and a weak worker that actually
+shipped the effect passes it. Distrust is aimed at the *byte-author of the
+evidence*, not at the worker's eloquence.
+
+## Inputs
+
+- A set of subagent **results** to fold (return strings + their transcript paths),
+  e.g. the children of a `parallel()` barrier or a `pipeline()` stage. A result is
+  the thing you are tempted to interpolate directly (`${result}`) — don't.
+- For each result, the **effect it claims** (a `(plan, phase)`, a created file
+  path, a DB row key, a sent-message id). If the worker emitted no checkable
+  effect, that is a real outcome (NO_CLAIM), not a pass — see Step 2.
+
+## Step 0 — Discover the workspace layout (one call)
+
+Run the doctor verb and read the result. **This is the WCR on-ramp: every
+path/lane/exit-code below comes from here, never a literal.**
+
+```bash
+dos doctor --workspace . --json
+```
+
+Parse the JSON object. The fields this skill uses:
+
+- `exit_codes.verify` — `{shipped, not_shipped, contract_error}`. Branch on these,
+  never on parsing the prose, for the **git-phase** claim type (Step 3a).
+- `exit_codes."verify-result"` — `{healthy, unreadable, dead, contract_error}`
+  (`dead=3`). Branch on these for the **terminal-state** witness (Step 3, the
+  prerequisite gate every claim type runs first).
+- `paths.plans_glob` / `lanes` / `stamp` — the host's plan grammar and lane
+  taxonomy, if a claim names a `(plan, phase)`.
+- `git` — if `false`, the git-existence witness (Step 3a) has no history to read;
+  every git-phase claim will be `source="none"`. Say so; do not silently pass it.
+
+You may also read `admission_predicates` and `overlap_policy` here, but they are
+not load-bearing for witnessing — they describe the arbiter, not the witness rung.
+
+## Step 1 — For each result: is the worker even ALIVE? (the terminal-state gate)
+
+**Run this BEFORE you read the worker's return string at all.** A return string is
+worthless if the "worker" was a harness-synthesized death (a rate-limit / quota /
+auth / server error the harness wrote and the worker never authored). ~32% of real
+subagents return such a string (docs/197 §2), and it survives a naive
+`.filter(Boolean)` to be banked as a finished finding.
+
+```bash
+dos verify-result --workspace . --transcript <agent-transcript.jsonl>
+echo "exit=$?"
+```
+
+Branch on `exit_codes."verify-result"`:
+
+- `3` **DEAD** — the terminal record was harness-authored (`message.model ==
+  "<synthetic>"`, the unforgeable authorship marker). **Do NOT fold this result.**
+  Route the worker's OWN unit for re-dispatch, and **count it in the denominator**
+  (a 4-of-7 fan-out is 4/7, never silently 7/7). The catch is grounding because it
+  read a DIFFERENT byte-author than the worker — the harness, not the model.
+- `0` **HEALTHY** — a real terminal result; proceed to Step 2. (`0` also covers
+  **UNREADABLE**, the fail-safe floor: a read fault never fabricates a death. An
+  UNREADABLE result is *not* trusted as confirmed — it simply isn't classified
+  DEAD; its effect still must be witnessed in Step 3.)
+- `2` — a contract error (no transcript). Fix the wiring; do not treat as HEALTHY.
+
+This step is itself the cheap, shipped form of "byte-author ≠ judged agent": the
+liveness of the worker is read from the harness's own authorship marker.
+
+## Step 2 — Classify the claim TYPE (so you know which witness to ask)
+
+For each HEALTHY result, decide what checkable effect it claims. **Extract the
+claim at the boundary — abstain, never invent.** Free prose ("I'm done", "shipped
+the auth work") yields NO claim: there is no honest way to derive the effect's
+*identifier* from prose without inventing it (docs/134 §2.1). A claim you cannot
+name is a **NO_CLAIM** — surface it for a human, do not manufacture one to witness.
+
+Map each named claim to its witness rung:
+
+| Claim type | What the worker asserts | Witness (byte-author ≠ agent) | Verb today |
+|---|---|---|---|
+| **git phase** | "(plan, phase) shipped" | git ancestry + ship-stamp grammar | `dos verify` (Step 3a) — SHIPPED |
+| **terminal state** | the result itself is real | harness authorship marker | `dos verify-result` (Step 1) — SHIPPED |
+| **created file / DB row / sent message / deploy** | "I created X / inserted row Y / sent Z" | a fresh GET / state-diff / OS exit / counterparty record | **NO CLI verb** (Step 3b) — Python API gap |
+
+The first two are shipped CLI verbs. The third is the open seam — handled honestly
+in Step 3b.
+
+## Step 3 — Witness the claim on a non-forgeable rung
+
+### Step 3a — git-phase claims: ask the truth syscall
+
+For a `(plan, phase)` claim, never trust the worker's "I committed it" and never
+grep commit subjects yourself:
+
+```bash
+dos verify --workspace . <PLAN> <PHASE> --json
+echo "exit=$?"
+```
+
+Read the `ShipVerdict`: `{shipped, source, sha?}`. Branch on `exit_codes.verify`
+(`shipped:0`, `not_shipped:1`, `contract_error:2`), and **read the rung**:
+
+- `source: "registry"` — the strongest git ship; a ship row exists. Fold it.
+- `source: "grep-subject"` — a commit *subject* carried the phase token. SHIPPED,
+  but weaker — a subject can flip the verdict even if little was built. Fold it,
+  but mark the rung; do not treat it as equal to `registry`.
+- `source: "none"` — no positive git evidence. The worker CLAIMED the phase but
+  git does not corroborate it. **Do NOT fold the claim** — this is the narrated
+  success the world does not back. Surface it; route the unit for re-dispatch.
+
+This is grounding because git is a witness the worker did not author: the commit's
+existence in ancestry is a fact about the repository, not about the worker's prose.
+
+### Step 3b — created-file / DB-row / sent-message claims: the read-back gap
+
+**There is NO `dos verify-effect` (or `dos witness`) CLI verb.** The effect-witness
+join is shipped in the kernel as a **Python API**, not a command — exactly like
+`tool_stream` has no `dos tool-stream` verb (see EXAMPLES.md Recipe 5). So for any
+effect outside git, the skill documents the pattern and **logs the gap at
+runtime**, rather than pretending a verb exists.
+
+The pattern (kernel modules, all pure; the read-back I/O lives in a `drivers/*`
+witness, never in the skill):
+
+```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 at the boundary
+
+# (a) Extract the claim from the worker's terminal text (boundary read done already).
+#     extract_claims fires only on an explicit ID-shaped token or a DOS-CLAIM:
+#     marker — free prose yields []. That [] is a NO_CLAIM, not a pass.
+
+# (b) Gather a read-back from a witness the agent did not author. A real witness
+#     (a fresh HTTP GET, an OS exit code, a state-snapshot diff) lives in a driver
+#     registered under the `dos.evidence_sources` entry-point group; the skill
+#     resolves it by name and runs it at the boundary:
+source = resolve_evidence_source("<your-witness-name>")   # built-in `null` if none wired
+facts = gather_evidence(source, subject="<effect key>", config=cfg)
+
+# (c) Fold ONLY confirmed: the join is capped by the read-back's accountability.
+verdict = witness_effect(EffectClaim(key="<effect key>", narrated="<what worker said>"),
+                         (facts,))
+# verdict.verdict -> CONFIRMED | REFUTED | UNWITNESSED | NO_CLAIM
+# verdict.believe -> True ONLY on CONFIRMED (a non-forgeable witness saw it PRESENT)
+```
+
+The load-bearing rule, enforced structurally by `believe_under_floor`: a read-back
+on the **forgeable floor** (`AGENT_AUTHORED` — the agent re-reading its own
+surface, a pasted receipt, an mtime) is recorded but **structurally incapable** of
+granting belief. Belief requires a `OS_RECORDED` / `THIRD_PARTY` witness. So the
+worst a lying same-surface read-back can do is be ignored (a safe-direction
+no-op), never manufacture a CONFIRMED.
+
+**The four outcomes a consumer routes on:**
+
+- **CONFIRMED** — fold it. A non-forgeable witness re-read the world and the effect
+  is PRESENT.
+- **REFUTED** — do NOT fold; RED-flag it. A non-forgeable witness re-read and the
+  effect is ABSENT (the silent frontier-fail made visible). Route for re-dispatch.
+- **UNWITNESSED** — do NOT fold as confirmed. No accountable witness was reached
+  (or only a forgeable-floor read). The honest abstain — surface it; this is the
+  runtime gap to log (see "What this skill does NOT do").
+- **NO_CLAIM** — the worker asserted no checkable effect. Nothing to witness;
+  surface it for a human. NOT a pass.
+
+**Log the gap, never silently skip it.** The first time a non-git effect needs
+witnessing and **no `dos.evidence_sources` driver is wired** (so `gather_evidence`
+returns `null` → UNWITNESSED), emit a one-line `log` naming the unwitnessed effect
+and the missing witness — so the capability gap is surfaced at runtime, not buried
+here. An UNWITNESSED effect must be reported up, never laundered into the fold.
+
+## Step 4 — Partition the fold and carry coverage forward
+
+Fold the results into three buckets, and **carry the count into whatever consumes
+the fold** (a synthesis prompt, a downstream stage):
+
+- **CONFIRMED / SHIPPED** → folded. These are the only results another agent's
+  input may be built from.
+- **REFUTED / NOT_SHIPPED / DEAD** → routed for re-dispatch, **counted in the
+  denominator**. A fan-out of N that confirmed M is M/N — never silently N/N.
+- **UNWITNESSED / NO_CLAIM** → surfaced for a human; held out of the fold.
+
+The coverage fact (`confirmed M of declared N`, plus the bucket each result landed
+in) is data the synthesizer must SEE — a synthesis told "7/7 returned" when only
+4/7 were witnessed will confidently launder the gap.
+
+## What this skill deliberately does NOT do (no silent gap)
+
+- **No model-judge over the return TEXT.** It NEVER asks a model (or a heuristic,
+  or itself) "does this return string *look* right / complete / successful?" That
+  is the docs/197 §4d wishful trap: a judge reading the worker's own narrated bytes
+  is re-deriving the author's output — **consistency, never grounding**. Belief
+  comes only from a read-back whose byte-author is not the worker. (A JUDGE rung
+  exists — the `dos.judges` seam — but it is advisory, fail-to-abstain, and applies
+  to the *residue the oracle ABSTAINED on*, fed independent evidence, never the
+  worker's own string as a substitute for the witness.)
+- **No `dos verify-effect` verb (there isn't one).** Non-git effects are witnessed
+  via the Python API of Step 3b, and the gap is logged at runtime. The skill does
+  not pretend a CLI verb exists where it does not (the EXAMPLES.md Recipe 5
+  discipline).
+- **No host evidence source baked in.** Which witness re-reads a created file or a
+  DB row is a `dos.evidence_sources` driver the host wires; the skill resolves it
+  by name, never names a host backend as a literal.
+- **No enforcement.** It REPORTS a fold partition and proposes a re-dispatch; it
+  does not kill a worker or block a write. DOS is a PDP, not a PEP.
+
+## Anti-patterns
+
+- ❌ Interpolating `${result}` (a worker's return string) directly into a synthesis
+  prompt — that folds the worker's self-report as ground truth. Witness first.
+- ❌ Treating a non-empty return string as success — a harness-synthesized death is
+  non-empty and survives `.filter(Boolean)`. Run `dos verify-result` first.
+- ❌ Asking a model "is this output complete/correct?" — consistency, not
+  grounding. Gather a read-back from a surface the worker did not author.
+- ❌ Counting only the workers that returned a string in the denominator — a DEAD or
+  UNWITNESSED result must be counted, or a 4/7 fan-out launders as 7/7.
+- ❌ Folding an UNWITNESSED / NO_CLAIM result "because it probably worked" — abstain
+  surfaces it; it never folds as confirmed.
+- ❌ Naming a specific lane, plan dir, or witness backend as a literal — read the
+  active layout from `dos doctor --json` and resolve witnesses by name.
+
+## The one rule under this skill
+
+A subagent's result is a **claim with a byte-author**. Fold it only when a witness
+whose byte-author is *not the worker* corroborates the claimed effect. The worker's
+model tier, its confidence, and its eloquence are irrelevant to that gate — which
+is the whole point: the part that decides ground truth is never the part being
+judged.