dos-kernel 0.26.0__tar.gz → 0.27.0__tar.gz

{dos_kernel-0.26.0/src/dos_kernel.egg-info → dos_kernel-0.27.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dos-kernel
-Version: 0.26.0
+Version: 0.27.0
 Summary: Dispatch Operating System — the domain-free trust substrate for fleets of autonomous agents (verdict spine, ship oracle, structured refusal, lane arbiter, correlation spine).
 Author: Anthony Chaudhary
 License: MIT
@@ -69,6 +69,12 @@ Dynamic: license-file
 [![commit-claims](https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2Fanthony-chaudhary%2Fdos-kernel%2Fmaster%2Fdocs%2Fscoreboard%2Fanthony-chaudhary%2Fdos-kernel%2Fbadge.json)](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/scoreboard/methodology.md)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/anthony-chaudhary/dos-kernel/blob/master/LICENSE)
 
+> 📊 **See it run on real repos:** the **[scoreboard](https://anthony-chaudhary.github.io/dos-kernel/scoreboard/)**
+> takes this same check public — for 15 popular AI-built repos (roborev,
+> open-interpreter, crewAI, autogen, …) it shows how much of each was written by
+> agents, which agents, and whether every commit's claim is backed by its own
+> diff. One command scores yours: `dos commit-audit --sweep --workspace . BASE..HEAD`.
+
 <p align="center">
   <img src="https://raw.githubusercontent.com/anthony-chaudhary/dos-kernel/master/docs/assets/caught-lie-cast.svg" alt="A terminal recording of the caught lie. The agent reports: Done! Shipped the login endpoint (AUTH1) and the password reset (AUTH2). git log shows one commit — AUTH1: ship the login endpoint. dos verify AUTH AUTH1 answers SHIPPED (exit 0); dos verify AUTH AUTH2 answers NOT_SHIPPED via none (exit 1) — caught. The exit code is the verdict: gate the agent's done on it and a false claim cannot land." width="100%">
   <br>
@@ -86,7 +92,7 @@ Dynamic: license-file
 </p>
 
 An AI agent will tell you it finished. DOS checks the real world instead of
-taking its word — and the nearest piece of the real world is your git history.
+taking its word. The nearest piece of the real world is your git history.
 
 An agent says it shipped the login endpoint. Did it? Run one command,
 `dos verify`, and it answers from the artifacts the work actually left behind,
@@ -127,7 +133,7 @@ zero config, and the only thing you ever install is one small Python package.
 > entries there undoes it. (No runtime detected? It says so and lists the
 > names to pick from — it never guesses.)
 
-<sub>**v0.26.0** · 3900+ tests · CI: Python 3.11–3.13 on Linux + a Windows 3.13
+<sub>**v0.27.0** · 5,600+ tests · CI: Python 3.11–3.13 on Linux + a Windows 3.13
 smoke run · the only runtime dependency is **PyYAML** · **MIT**.</sub>
 
 > 🧭 **Want it in plain words first?** What DOS is, what it catches, and what
@@ -160,6 +166,7 @@ your job title, and every section hands off to the one above it.
 
 | You're asking… | Start at | Then |
 |---|---|---|
+| *"I vibe-code with an AI — did it actually do what it said?"* | ["Did my AI actually do it?" in 30 seconds](https://github.com/anthony-chaudhary/dos-kernel/blob/master/examples/playbooks/00b_did-my-ai-do-it.md) — one command on your own repo | the [plain-words version](#the-plain-words-version) of why it works |
 | *"What is this, in plain words, and why should my team care?"* | [the plain-words version](#the-plain-words-version), just below — no code | hand the [60-second demo](#try-it-in-60-seconds) to whoever runs your agents |
 | *"Show me it working, fast."* | [Try it in 60 seconds](#try-it-in-60-seconds) | [what goes wrong in a fleet](#what-goes-wrong-in-a-fleet) without it |
 | *"I already run agents — how do I wire the verdict into **my** stack?"* | [How you plug it in](#how-you-plug-it-in) | [the MCP lie detector](#give-your-agent-a-lie-detector-mcp) · [Install](#install) |
@@ -174,12 +181,15 @@ its own front door: **[AGENTS.md](https://github.com/anthony-chaudhary/dos-kerne
 
 A coding agent does some work, then tells you how it went. Usually the story is
 true. Sometimes it isn't — the cheerful *"all work completed!"* from a worker
-that actually shipped nothing is the single most common failure in agent
-fleets. With one agent you catch that yourself, because you read its work
-before trusting it.
-
-Run twenty agents at once and nobody reads everything. Each worker grades its
-own homework, you believe the reports because what else is there to go on, and
+that actually shipped nothing is one of the most common, and most expensive,
+failures in agent fleets. With one agent you catch that yourself, because you read its work
+before trusting it — which is a real cost you're already paying, you just
+haven't called it one: re-reading the output is the tax for taking the report
+on faith.
+
+Run twenty agents at once and that tax stops being payable — nobody reads
+everything. Each worker grades its own homework, you believe the reports
+because what else is there to go on, and
 the unchecked problems pile up quietly — a false "done" here, two agents
 overwriting the same file there, one worker spinning in circles burning money.
 None of it is loud. The codebase ends up *sorta* working, and nobody can safely
@@ -243,6 +253,7 @@ dos init .                                       # writes one dos.toml
 git init -q
 git config user.email you@example.com            # skip if you have a global git identity
 git config user.name  "You"
+git config commit.gpgsign false                  # this throwaway repo has no signing key
 echo 'def login(): ...' > login.py
 git add -A
 git commit -m "AUTH1: ship the login endpoint"   # stamp AUTH1 shipped: <PHASE-ID>: <message>
@@ -375,7 +386,7 @@ reachable through every row here, lowest-friction first:
 |---|---|---|
 | **MCP server** | you drive an agent through an MCP host (Claude Desktop, Cursor, Cline, an Agent-SDK app) | add one line to the host config (`{ "command": "dos-mcp" }`) and ask the agent to `dos_verify` its own last claim — **zero code**. The *advisory* path (the agent asks). See [Give your agent a lie detector](#give-your-agent-a-lie-detector-mcp). |
 | **Runtime hooks** | you run an agent loop (Claude Code, Cursor, Codex CLI, Gemini CLI) and want the verdict to *act*, not just be available | `dos init --hooks <runtime>` wires the verdict into that host's own hook config — a refused call is **denied before it runs**, a false "done" is **refused**. The *enforcement* path (the host denies). One command, no hand-edited YAML. See [QUICKSTART](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/QUICKSTART.md) + [docs/221](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/221_the-cross-vendor-hook-installer.md). |
-| **CLI exit-code** | you have a shell pipeline or CI step that trusts an agent's "done" | replace that step with `dos verify PLAN PHASE` and branch on the exit code (`0` shipped / `1` not) — **the verdict *is* the exit code**. The day-one win above. |
+| **CLI exit-code** | you have *any* command-running environment — a CI step, a `pre-push` hook, or an agentic CLI like **aider** whose lint/test-cmd trusts a "done" | branch on a `dos` verb's exit code (`dos verify`: `0` shipped / `1` not; `dos commit-audit`: `0` clean / `1` over-claim) — **the verdict *is* the exit code**, no hook adapter and no MCP client. The honest tier for hook-less hosts (Windsurf, Warp, Zed). The [exit-code tier cookbook](https://github.com/anthony-chaudhary/dos-kernel/blob/master/examples/playbooks/cookbook-exit-code-tier.md). |
 | **Python API** | your dispatcher/orchestrator is already Python | `import dos` and call the pure syscalls (`dos.oracle.is_shipped`, `dos.arbiter.arbitrate`, …) — state-in / verdict-out, no subprocess. The [Python cookbook](https://github.com/anthony-chaudhary/dos-kernel/blob/master/examples/playbooks/cookbook-python-api.md). |
 | **Fleet framework** | your fleet already runs on LangGraph, CrewAI, AutoGen, or the OpenAI/Claude Agents SDK | bolt the referee onto the framework's own seam — a referee node, a termination condition only git can satisfy, an output guardrail with a git tripwire. One function, no rewrite; every seam executed against the real framework. The [fleet-framework cookbook](https://github.com/anthony-chaudhary/dos-kernel/blob/master/examples/playbooks/cookbook-fleet-frameworks.md). |
 | **Swarm runtime** | your agents run on **Hermes, OpenClaw**, or a SwarmClaw-style autonomous swarm — privileged tools, shared memory docs / task boards, and **no lock manager** for either | drop a two-function adapter into the tool-execution loop: `guard_action` refuses an arbitrary-exec command **before it runs**, and `acquire_lease` / `release_lease` bracket each shared-state write so the lost update never lands. No `import dos` — it shells the CLI; Hermes' `pre_tool_call` hook also speaks DOS natively (`dos hook pretool --dialect hermes`). The runnable, A/B-measured [Hermes / OpenClaw worked example](https://github.com/anthony-chaudhary/dos-kernel/tree/master/examples/hermes_integration) + [docs/278](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/278_integrating-dos-with-hermes-and-openclaw-the-missing-lock-manager-for-agent-swarms.md). |
@@ -430,6 +441,40 @@ truth) — covered in [Three live projections](#three-live-projections-read-only
 below and walked end-to-end in
 **[Debug a stuck fleet](https://github.com/anthony-chaudhary/dos-kernel/blob/master/examples/playbooks/06_debug-a-stuck-fleet.md)**.
 
+### "I could write this in 20 lines of bash"
+
+You could — and that instinct is correct. The core of `dos verify` really is
+"grep git history for a stamp." DOS is that script taken seriously across the
+six places the 20-line version quietly breaks:
+
+1. **The stamp grammar is forgeable** unless it's a *closed, declared*
+   vocabulary the agent can't widen on the fly — a bare grep believes any
+   string the agent learns to print.
+2. **Concurrent agents need a crash-safe lease journal**, not a grep: deciding
+   whether two workers may touch the same tree is arbitration, and it has to
+   survive a kill mid-write.
+3. **"Spinning vs. stalled" is a failure detector with FLP edges**, not a
+   timeout — a wedged run and a slow-but-live one look identical to `sleep`.
+4. **One verdict shape has to render byte-identically across hosts** to be a
+   standard a fleet can depend on, instead of a different ad-hoc check per tool.
+5. **A skeptic-checkable signed receipt** (`dos attest`) is something a bash
+   script the agent's own host runs simply cannot mint.
+6. **`commit-audit` (claim-vs-diff) isn't greppable** — it reads what the diff
+   *did* against what the subject *said*.
+
+The load-bearing point under all six: a script your agent's own host runs can't
+credibly be *the part that doesn't believe the agent*. The whole value is being
+the layer that is structurally not talked past — and that's exactly the thing a
+home-grown check, run inside the loop it's auditing, can't be.
+
+This also answers the most sophisticated objection — **"doesn't durable
+execution (Temporal) already do this?"** Durable execution guarantees the step
+*ran* and durably records what it *returned*; if an agent step returns
+`"deployed successfully"`, the history correctly records that the step *said
+so*. DOS adjudicates exactly that residue: the claim against the world. They're
+orthogonal layers. (The full comparison — evals, guardrails, in-toto, CI — is
+in **[docs/ALTERNATIVES.md](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/ALTERNATIVES.md)**.)
+
 The referee grows along two axes: deterministic *verdicts* that read artifacts
 (`verify`, `liveness`, `scope`), and provider-backed *judges* — a model, a
 debate — that rule on what no deterministic check can, kept outside the kernel
@@ -508,13 +553,13 @@ run (every number, hash, and ID is a verbatim read-off — never a hand-typed
 dramatization):
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/anthony-chaudhary/dos-kernel/master/benchmark/agentprocessbench/writeadmit/gate-moment.svg" alt="The DOS write-admission gate catching a real over-claim. A live gemini-2.5-pro agent on a tau2 airline task reports 'You are all set! Your reservation number is HATHAT' — a confident write the agent authored. The witness is the environment DB-hash the agent wrote zero bytes of: gold hash 9f2c…gold vs the agent's resulting hash 4b7e…actual, so db_match = False — the booking it swore it made is not in the database. The gate verdict: a confident write REFUTED by an OS_RECORDED witness → GATE BLOCK, the phantom never reaches the next agent. Result across two models: J = 10 of 120 over-claims caught and blocked off the DB-hash, 9 of 9 honest writes admitted, zero correct work blocked, an identical 8.3% over-claim rate on the mid model and the strong one." width="100%">
+  <img src="https://raw.githubusercontent.com/anthony-chaudhary/dos-kernel/master/benchmark/agentprocessbench/writeadmit/gate-moment.svg" alt="The DOS write-admission gate catching a real over-claim: a live agent reports a booking it never made, the environment DB-hash (gold vs. actual) shows the booking is not in the database, and the gate BLOCKS the confident-but-false write before it reaches the next agent. The numbers are in the bullets and caption." width="100%">
   <br>
   <sub><em><strong>It catches the lie and blocks it.</strong> A confident booking, refuted by the DB-hash the agent couldn't author, blocked before a downstream agent inherits the phantom. <a href="https://github.com/anthony-chaudhary/dos-kernel/blob/master/benchmark/agentprocessbench/writeadmit/gate_visual.html">Step through it locally</a> (an HTML walkthrough — clone and open in a browser; GitHub shows its source).</em></sub>
 </p>
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/anthony-chaudhary/dos-kernel/master/benchmark/agentprocessbench/writeadmit/f2-moment.svg" alt="The DOS coordination payoff: a stale write clobbering a cancellation, then prevented. Two live agents act on one shared reservation NM1VX1, each having planned its tool-calls against the same original state, neither aware of the other. A1 cancels the reservation (DB-hash a3f1…afterA1). Under naive replay, A2's add-bag — computed on the original active state — blindly re-activates the reservation and adds a bag, silently overwriting A1's cancellation (composed hash 77c2…naive, a real lost update). Under the arbiter, dos.arbiter leases the region reservations/NM1VX1 to A1, refuses A2's overlapping lease, and A2 re-plans against the post-A1 cancelled state and correctly declines — the DB-hash matches the serialized-correct value and no update is lost. Across six natural conflict pairs drawn from the real task distribution, J = 4 of 6 clobbers were structurally prevented off the DB-hash." width="100%">
+  <img src="https://raw.githubusercontent.com/anthony-chaudhary/dos-kernel/master/benchmark/agentprocessbench/writeadmit/f2-moment.svg" alt="The DOS coordination payoff: two live agents act on one shared reservation, neither aware of the other. Under naive replay the second agent's stale write silently overwrites the first's cancellation — a real lost update. Under the arbiter, the region is leased to the first agent, the second's overlapping lease is refused, it re-plans against the true post-cancellation state, and no update is lost. The numbers are in the bullets and caption." width="100%">
   <br>
   <sub><em><strong>It prevents the collision.</strong> A stale add-bag clobbers a cancellation under naive replay; the arbiter serializes the two agents on the same region so neither overwrites the other. <a href="https://github.com/anthony-chaudhary/dos-kernel/blob/master/benchmark/agentprocessbench/writeadmit/f2_visual.html">Step through it locally</a> (an HTML walkthrough — clone and open in a browser).</em></sub>
 </p>
@@ -531,8 +576,10 @@ prevented at a 32-agent fleet) projects these real per-run rates onto fleet
 math — it's geometry on top of measured numbers, not a measured fleet run.
 
 **🎲 A bet — stated as one.** Where this goes if the floor holds: a frozen,
-cross-vendor trust standard (the "deny" message is already byte-identical
-across Claude Code, Codex, and Qwen — a de-facto standard waiting to be named),
+cross-vendor trust standard (the "deny" message already renders from one
+verdict across every wired host, and is byte-identical on the ones that share
+Claude Code's envelope — Codex and Claude Cowork, pinned in
+`tests/test_hook_dialect.py` — a de-facto standard waiting to be named),
 a shared arbiter for real-world effects, the claim-vs-reality corpus only a
 neutral party can hold, and a notary that proves what an agent did *to a
 skeptic who wasn't in the room* (the mechanism already ships — `dos attest`
@@ -599,6 +646,18 @@ thinks to. The per-host wiring for Cursor / Codex / Gemini is in
 **[the MCP README](https://github.com/anthony-chaudhary/dos-kernel/blob/master/src/dos_mcp/README.md)** — all four are MCP clients, so this
 works on every one of them with zero code.
 
+**Building a legal agent?** `dos_citation_resolve` is the same lie-detector
+aimed at the failure class that gets lawyers sanctioned: a fabricated case
+citation (the *Mata v. Avianca* class). Wired in as an MCP tool, it checks each
+cite the agent emits *before* the brief is written — a pre-effect gate, not a
+post-hoc document scan — by resolving it against a third-party reporter the
+model didn't author (CourtListener), and abstains rather than guess when it has
+no corpus access. It witnesses existence and quote-fidelity, never whether the
+case supports your argument. The sourced walkthroughs:
+[catch fabricated citations inside your agent](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/answers/catch-fabricated-legal-citations-in-my-ai-agent.md),
+[avoid an AI-citation sanction](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/answers/largest-ai-hallucination-sanction-how-to-avoid.md),
+and [the ABA Opinion 512 duty](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/answers/aba-512-verify-ai-citations-duty.md).
+
 **Gemini CLI users get a one-liner.** DOS ships a `gemini-extension.json`
 manifest at the repo root, so the whole referee — the MCP server plus a context
 file that tells the model to gate its own done-claims — installs as one Gemini
@@ -613,6 +672,12 @@ The same manifest is what Google's auto-indexed
 [extensions gallery](https://geminicli.com/extensions/) crawls, so the listing
 is automatic.
 
+**Browsing an MCP registry?** A repo-root `smithery.yaml` lists DOS on
+[Smithery](https://smithery.ai), the de-facto MCP-server registry. It declares a
+**local stdio** launch (`uvx --from 'dos-kernel[mcp]' dos-mcp`) on purpose: DOS
+adjudicates *your* git repo, so it runs next to it rather than in a hosted
+sandbox that couldn't see your history. No API key — DOS is deterministic.
+
 ### …then make the verdict *act* (hooks)
 
 To go from "the agent can ask" to "the host won't let a bad call through", wire
@@ -661,45 +726,53 @@ honest caveat, carried on the install note itself: the Cowork app doesn't
 *fire* hooks yet — anthropics/claude-code#63360 — so until that closes,
 Cowork's working DOS surface is the advisory one above.)
 
-Under the installer sits a pluggable dialect seam: the verdict is decided
-once, then rendered into whatever JSON shape the host parses
-([docs/217](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/217_the-cross-vendor-hook-dialect-seam.md)) — so a runtime the
-installer doesn't cover yet can still consume the same hooks. A sixth shipped
-dialect speaks **Hermes**: `dos hook pretool --dialect hermes` emits the
-`{"decision": "block", "reason": …}` object Hermes' `pre_tool_call` shell hook
-reads (wire it in `cli-config.yaml`). A new host's dialect is a driver, never a
-kernel edit.
-
-The flip side of that honesty: a host with **no** hook seam gets **no** dialect.
-ByteDance's **Trae** was proved out and ships no user-scriptable hook system in
-its personal/international editions (no lifecycle events, no deny/allow stdout
-contract; its CN-enterprise edition announced one on 2026-06-09 with no
-published grammar yet), so DOS binds to it advisory-only — the MCP server in
-`.trae/mcp.json` (read alike by IDE-mode Agent, SOLO mode, and TRAE CLI), a
-verify-before-"done" rule in `.trae/rules/project_rules.md`, the generic
-skills in `.trae/skills/` — and `dos init --hooks trae` fails loud rather than
-writing config Trae would never read
-([docs/294](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/294_trae-advisory-only-the-host-with-no-hook-seam.md)).
-An invented envelope would be fake enforcement, which is the exact failure the
-dialect seam exists to prevent.
-
-Because these hooks run on *every* tool call, the core kernel logic on the hot
-path is reimplemented in native Go — a `dos-hook` binary that ports the actual
-decision predicates (the conjunctive-only lease-admission and
-prefix-disjointness floor, the `verify()` grep rung, self-modify, the marker
-budget, the WAL) rather than just shelling out to Python. It serves the
-per-call verdict in ~10 ms — 16–43× faster than shelling
-`python -m dos.cli hook …` (~0.25–0.8 s, dominated by interpreter cold-start) —
-and is byte-identical to the Python kernel on the gated decision (the docs/124
-parity contract, pinned by Go parity tests). It owns the common fast path and
-falls back to the always-available Python verb for anything it doesn't yet
-serve, so a machine without the binary degrades cleanly with no wiring change
-([docs/125](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/125_go-hook-fastpath-build-plan.md),
-[docs/270](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/270_go-hook-fastpath-benchmarks.md)). You don't build it
-yourself: the per-platform wheels bundle the binary, so a wheel install gets
-the native fast path with no Go toolchain — and any platform without a bundled
-binary (including a plain source install) just runs the pure-Python path
-([docs/286](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/286_shipping-the-go-binary-through-pypi-per-platform-wheels.md)).
+Under the installer sits a pluggable **dialect seam**: the verdict is decided
+once, then rendered into whatever JSON shape each host parses — so a host the
+installer doesn't cover yet (a seventh dialect speaks **Hermes**) is a driver,
+never a kernel edit. Its honest flip side: a host with *no* hook seam gets *no*
+dialect. ByteDance's **Trae** ships no user-scriptable hook system, so DOS binds
+it **advisory-only** (MCP + a verify-before-"done" rule + the skills) and
+`dos init --hooks trae` fails loud rather than writing an invented envelope Trae
+would never read — fake enforcement is the exact failure the seam prevents.
+([docs/217](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/217_the-cross-vendor-hook-dialect-seam.md) ·
+[docs/294](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/294_trae-advisory-only-the-host-with-no-hook-seam.md))
+
+Because these hooks run on *every* tool call, the hot-path predicates are
+reimplemented in a native Go `dos-hook` binary — byte-identical to the Python
+kernel on the gated decision (the docs/124 parity contract) but ~16–43× faster
+(~10 ms vs. interpreter cold-start), bundled in the per-platform wheels with a
+clean fall-back to the always-available pure-Python path on any platform without
+it ([docs/124](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/124_the-go-core-build-plan-and-the-parity-contract.md),
+[docs/125](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/125_go-hook-fastpath-build-plan.md),
+[docs/270](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/270_go-hook-fastpath-benchmarks.md),
+[docs/286](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/286_shipping-the-go-binary-through-pypi-per-platform-wheels.md)).
+
+### …and when your host has neither (the exit-code tier)
+
+MCP is the **advisory** tier (the agent *asks*); hooks are the **enforcement**
+tier (the host *blocks*). Both ask DOS to speak the host's language — an MCP
+client, or a per-host hook dialect. The third tier asks nothing: **any
+environment that runs a command** reads a `dos` verb's exit code, because every
+verb already follows the universal Unix convention (`0` = ok, non-zero = a
+verdict). The verdict *is* the exit code.
+
+That tier is what reaches the long tail no dialect will ever cover, and it is
+the **honest** surface for a hook-less host (Windsurf, Warp, Zed today): rather
+than invent a fake enforcement envelope a host would never read, DOS rides the
+one contract every runner already has.
+
+```bash
+# aider runs --test-cmd after every edit and feeds a non-zero exit back to the
+# model's auto-fix loop — so a kernel verdict drops into a top-tier CLI agent
+# with NO hook machinery and NO MCP client, in one flag:
+aider --test-cmd 'dos commit-audit --workspace . HEAD' --auto-test
+```
+
+The same one line is a `pre-push` gate, a Jenkins/Buildkite stage, a `Makefile`
+target, or a `package.json` script. The full set of runnable recipes — aider, a
+git `pre-push` hook, and a generic command step, plus `dos hook-exit` for
+wrapping a *non-DOS* script onto the intervention ladder — is
+**[the exit-code tier cookbook](https://github.com/anthony-chaudhary/dos-kernel/blob/master/examples/playbooks/cookbook-exit-code-tier.md)**.
 
 *Next level up — what to watch once a fleet runs through these hooks: [Operating a fleet](#operating-a-fleet).*
 
@@ -764,8 +837,8 @@ contract, the JUDGE-rung seam. The full map is in **[CLAUDE.md](https://github.c
 
 ## Install
 
-Pick the row that matches how you work — the full matrix (every OS, every
-channel, upgrade/uninstall, WSL, troubleshooting) is in
+Requires **Python 3.11+**. Pick the row that matches how you work — the full
+matrix (every OS, every channel, upgrade/uninstall, WSL, troubleshooting) is in
 **[docs/INSTALL.md](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/INSTALL.md)**:
 
 ```bash
@@ -804,29 +877,21 @@ its own install location, so the ground truth stays legible as the codebase
 grows. (The full separation contract — mechanism in the package, policy in the
 workspace's `dos.toml` — is in **[CLAUDE.md](https://github.com/anthony-chaudhary/dos-kernel/blob/master/CLAUDE.md)**.)
 
-For most repos that one `dos.toml` is the whole policy surface — but when your
-lanes must be *computed* (from runtime state, an env var, a monorepo manifest)
-rather than listed, or you add a provider-backed JUDGE, you write a small
-**driver** instead: a `dos/drivers/<host>.py` exposing a `LaneTaxonomy` constant +
-a `<host>_config` factory, loaded by name via `dos --driver <host>` and never
-imported by the kernel. Copy [`dos/drivers/workshop.py`](https://github.com/anthony-chaudhary/dos-kernel/blob/master/src/dos/drivers/workshop.py)
-as the template; the full driver/plugin map is in **[docs/HACKING.md](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/HACKING.md)**.
+For most repos that one `dos.toml` is the whole policy surface. When your lanes
+must be *computed* rather than listed, or you add a provider-backed JUDGE, you
+write a small **driver** instead — loaded by name, never imported by the kernel;
+the driver/plugin map and a copy-me template are in
+**[docs/HACKING.md](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/HACKING.md)**.
 
 ### Claude Code plugin — hooks + MCP + skills in one install
 
 If you drive a fleet with Claude Code, the lowest-friction way to bind the
 verdict to the runtime is the bundled plugin under
-[`claude-plugin/`](https://github.com/anthony-chaudhary/dos-kernel/tree/master/claude-plugin) — it packages all three runtime surfaces at
-once:
-
-- the **hooks** (`PreToolUse` → deny a structurally-refused call · `PostToolUse` →
-  re-surface a stalled tool stream · `Stop` → refuse to stop on an unverified
-  claim) — all fail-safe (they emit nothing and exit 0 on any error, so they never
-  break a turn);
-- the **MCP server** (`dos_verify` / `dos_arbitrate` / `dos_commit_audit` /
-  `dos_refuse_reasons` … as tools the model calls directly);
-- the **generic skill pack** (the domain-free dispatch screenplays), namespaced as
-  `/dos-kernel:dos-next-up`, `/dos-kernel:dos-dispatch`, …
+[`claude-plugin/`](https://github.com/anthony-chaudhary/dos-kernel/tree/master/claude-plugin) — it packages all three runtime surfaces
+at once: the **hooks** (`PreToolUse` deny · `PostToolUse` sensor · `Stop` verify,
+all fail-safe), the **MCP server** (`dos_verify` / `dos_arbitrate` / … as tools
+the model calls), and the **generic skill pack** (the domain-free dispatch
+screenplays, namespaced `/dos-kernel:dos-next-up`, …):
 
 ```bash
 # 1. The plugin ships JSON + markdown; the brains ship as the pip package, so
@@ -848,90 +913,39 @@ with the source are in **[claude-plugin/README.md](https://github.com/anthony-ch
 
 ## CLI
 
-One `dos` entrypoint over the syscalls (see [QUICKSTART.md](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/QUICKSTART.md) for
-a runnable tour of the core ones):
+One `dos` entrypoint over the syscalls. Here are the dozen verbs you reach for
+first (see [QUICKSTART.md](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/QUICKSTART.md) for
+a runnable tour) — the **full reference, every verb grouped, is
+[docs/CLI-REFERENCE.md](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/CLI-REFERENCE.md)**:
 
 ```bash
-# --- the syscalls ---
+# --- the core verdicts ---
 dos verify PLAN PHASE                  # truth: did (plan,phase) ship? (works with no plan)
 dos commit-audit [REF] [--sweep]       # truth: does a commit's SUBJECT match its own diff? (--sweep = drift rate over a range)
-dos verify-result --transcript T       # fold-site witness: did a subagent's terminal record DIE (harness 429/quota)? (exit 3 = DEAD)
-dos coverage --declared N              # fan-out coverage: how many of N declared workers REALLY returned a result vs died?
 dos liveness --run-id R --start-sha S  # temporal: ADVANCING / SPINNING / STALLED?
-dos resume --run-id R                  # the resume verdict: replay a run's intent ledger, re-verify against git, PROPOSE the continuation
-dos complete --run-id R [--diverged]   # completion verdict: is the WHOLE declared job done? (residual = declared − verified)
-dos rewind --run-id R [--fire SIGNAL]  # conversation-rewind verdict: PROPOSE excising dead-end turns (never truncates)
-dos status --run-id R                  # the folded fact: one fail-closed digest of a run (liveness + verified progress + lease)
-dos arg-provenance --tool T --args J [--new-key K]  # did the model MINT this id/FK, or RESOLVE it from env bytes? (exit 0 believe / 3 UNSUPPORTED)
-dos arbitrate --lane L --kind K --leases '[…]'   # admission: may a lane start without collision? (decision only — journals nothing; hold via lease-lane)
-dos scope-gate --lane L [--staged]     # binding pre-effect scope gate: may this PROPOSED write land in its lane? (ALLOW/REFUSE)
-dos lease {acquire,release,status} OWNER         # the cross-process archive lock
-dos lease-lane {acquire,release,heartbeat,live}  # durable lane lease over the pure arbiter (write-back to the WAL)
-dos run-id mint PROCESS                # mint a correlation run-id
-dos id-alloc {allocate,peek} SCOPE     # atomically allocate a never-reused, monotonic id for a scope
-dos journal {tail,replay,seq,compact}  # the lane write-ahead log
-dos halt --handle H                    # the reap verb: emit the stop-plan for a live run/lease
-dos pickable / enumerate / cooldown / reconcile  # picker substrate: anything pickable? why-not? tried recently? did the claim hold?
-
-# --- workspace & inspection ---
+dos status --run-id R                  # one fail-closed digest of a run (liveness + verified progress + lease)
+dos resume --run-id R                  # replay a run's intent ledger, re-verify against git, PROPOSE the continuation
+
+# --- admission (let a lane in, or refuse the collision) ---
+dos arbitrate --lane L --kind K --leases '[…]'   # may a lane start without collision? (decision only)
+dos scope-gate --lane L [--staged]     # binding pre-effect scope gate: may this PROPOSED write land? (ALLOW/REFUSE)
+
+# --- workspace & live projections ---
 dos init [DIR]                         # scaffold a dos.toml workspace config
 dos doctor [--json] [--check]          # report the active workspace + taxonomy + predicates
-dos lint [--strict] [--json]           # dead policy in this workspace's own dos.toml? (unreachable lanes, dangling refs)
-dos man {wedge,lane} [ID]              # the self-describing manual over the registries
-dos exit-codes [VERB]                  # print the verdict-IS-the-exit-code table (all verbs or one)
-dos gate PACKET                        # typed empty-packet verdict (LIVE/DRAIN/STALE-STAMP/…)
-dos judge wedge RUN_TS                 # adjudicate a no-pick verdict (deterministic)
-dos judge-eval --judge N --cases C     # score a JUDGE-rung adjudicator against labelled claims
-dos overlap-eval --policy P --cases C  # score an overlap scorer by false-admit rate (the disjointness backtest)
-dos intervention-eval --cases C        # score an intervention policy by NET task delta (not verdict accuracy)
-dos tool-stream-eval --cases C         # score a stall-reader policy by NET recovery (not detection accuracy)
-dos precursor-gate-eval --cases C      # score a precursor grammar by recall vs false-refute waste
-dos memory {recall,verify}             # re-verify recalled agent-memory at read time (RECALL_FRESH/STALE/UNVERIFIABLE)
-dos health --lane L                    # pre-dispatch lane-health gate (overlap + recurring-blocker → route)
-dos scout                              # pre-dispatch chooser: pick the next activity before leasing a lane
-dos trace RUN_ID                       # walk one run across spine + intent ledger + WAL + git, joined by run_id
-
-# --- agent-host binding (Claude Code / MCP) ---
-dos guard [--verify-on-stop] -- CMD…   # wrap a headless agent launch: inject the DOS MCP server (+ optional verify-on-stop Stop hook)
-dos hook {pretool,posttool,stop}       # the live agent-host hook surface (PreToolUse deny / PostToolUse sensor / Stop verify)
-
-# --- live projections (read-only TUIs) ---
 dos top [--once] [--json]              # live fleet watchdog: lanes, leases, verdicts, commits
-dos decisions [N]                      # the operator-decision queue (list + drill-in TUI)
-dos plan [--once] [--json]             # work-terrain board: every phase, the plan's claim vs the oracle's verdict
-dos watch --track R [--budget-ms M]    # the watchdog driver: poll liveness for tracked runs + propose halts on spin/hang
-dos loop --target N [--watch] [--json] # supervisor (init/PID-1): keep N dispatch-loops alive — emits a spawn/reap/flag plan
-
-# --- loop-economics & reliability verdicts (pure; exit code is the verdict) ---
-dos productivity --deltas 5,3,1,0      # is the run still doing work? PRODUCTIVE / DIMINISHING / STALLED
-dos efficiency --work W --tokens N     # did the tokens buy work? EFFICIENT / COSTLY / WASTEFUL
-dos breaker --consecutive N --max-consecutive M  # has this failure class tripped? CLOSED / OPEN (+ escalation rung)
-dos hook-exit --code N                 # map a shell hook's exit code → PASS / BLOCK / WARN
-dos exec-capability --command "…"      # does this command grant arbitrary exec? BOUNDED / GRANTS_ARBITRARY_EXEC
-dos improve --suite-passed --truth-clean --work W --baseline-work B  # self-improving loop: KEEP / REVERT / ESCALATE
-dos reward --claim --witness {confirm,refute,none}   # may a fine-tune TRAIN on this trajectory? ACCEPT / REJECT_POISON
-
-# --- observability: the verdict journal → your dashboards ---
-dos observe [--run R] [--json]         # project the verdict journal: every kernel adjudication, folded by run/syscall/verdict
-dos helped [--since TS] [--json]       # the operator rollup: how many things DOS productively caught for you
-dos export [--to file|statsd|otlp] [--since SEQ]  # drain the journal outward (Datadog / Honeycomb / Grafana); null = report only
-dos notify {decisions,top} [--notifier slack|webhook --channel NAME]  # push what-needs-a-human / what's-running to where the operator is; null = render only
-
-# --- portable proof (third-party verifiable, no loop access) ---
-dos attest --claim KEY {--accept-cmd CMD | --before P --after P}  # mint an HMAC-signed receipt over an effect-witness verdict
-dos verify-receipt --receipt R         # the skeptic's side: check the signature with the shared key alone (fails LOUD on tamper)
-
-# --- cross-project (machine-local index) ---
-dos projects                           # the projects DOS has served
-dos learn AXIS                         # aggregates over resolved decisions
-dos reindex                            # rebuild the central store from the .dos/ dirs
+dos decisions [N]                      # the operator-decision queue (what's waiting on you)
+dos plan [--once] [--json]             # every phase: the plan's claim vs the oracle's verdict
 ```
 
 Most verbs take `--workspace .` (or honor `$DISPATCH_WORKSPACE` / cwd) and
 `--json` for machine-readable output. For verdict-bearing commands (`verify` /
-`liveness` / `gate`) **the exit code is the verdict.** A pluggable `--output
-<name>` renderer (the `dos.renderers` entry-point group) is covered in
-[HACKING.md](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/HACKING.md).
+`liveness` / `gate`) **the exit code is the verdict** (`dos exit-codes` prints
+the table). The other ~55 verbs — the picker substrate, loop-economics
+verdicts, observability exporters, portable-proof attestation, the eval
+harnesses — and the pluggable `--output <name>` renderer
+([HACKING.md](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/HACKING.md)) are all in
+**[docs/CLI-REFERENCE.md](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/CLI-REFERENCE.md)**.
 
 ### Three live projections (read-only TUIs)
 
@@ -1064,6 +1078,11 @@ for a copy-me skeleton.
 - **[docs/FAQ.md](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/FAQ.md)** — the arriving questions ("how do I
   verify an agent's claim?", "does it need an LLM?"), each answered in one
   self-contained block.
+- **[docs/answers/](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/answers/README.md)** — the answer corpus: one
+  sourced, self-contained page per high-intent question ("how to verify an AI
+  agent actually did the work", "how to stop two AI agents overwriting each
+  other"), each carrying an evidence table where every number links to the file
+  that proves it.
 - **[docs/ALTERNATIVES.md](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/ALTERNATIVES.md)** — DOS and the
   alternatives: evals, framework guardrails, Temporal, in-toto, plain CI —
   what each does well, what DOS adds, and when NOT to use DOS.
@@ -1103,8 +1122,11 @@ back verbatim:
   (liveness), an [infra monorepo](https://github.com/anthony-chaudhary/dos-kernel/blob/master/examples/playbooks/05_infra-monorepo.md) (refusals).
 - [**Debug a stuck fleet** + FAQ](https://github.com/anthony-chaudhary/dos-kernel/blob/master/examples/playbooks/06_debug-a-stuck-fleet.md) —
   symptom → the one command that diagnoses it.
-- Three cookbooks: [from Python](https://github.com/anthony-chaudhary/dos-kernel/blob/master/examples/playbooks/cookbook-python-api.md),
-  [CI / MCP integration](https://github.com/anthony-chaudhary/dos-kernel/blob/master/examples/playbooks/cookbook-ci-integration.md), and
+- Four cookbooks: [from Python](https://github.com/anthony-chaudhary/dos-kernel/blob/master/examples/playbooks/cookbook-python-api.md),
+  [CI / MCP integration](https://github.com/anthony-chaudhary/dos-kernel/blob/master/examples/playbooks/cookbook-ci-integration.md),
+  [the exit-code tier](https://github.com/anthony-chaudhary/dos-kernel/blob/master/examples/playbooks/cookbook-exit-code-tier.md) — *any* command-running
+  environment (aider, a git `pre-push`, a generic runner) reads a `dos` verb's
+  exit code, no hook adapter or MCP client needed — and
   [fleet frameworks](https://github.com/anthony-chaudhary/dos-kernel/blob/master/examples/playbooks/cookbook-fleet-frameworks.md) — LangGraph,
   CrewAI, AutoGen, the OpenAI/Claude Agents SDK — with every framework recipe also
   shipped as a runnable, suite-pinned file under