{"id":50985899,"url":"https://github.com/anthony-chaudhary/dos-kernel","last_synced_at":"2026-06-21T13:00:49.784Z","repository":{"id":363916413,"uuid":"1265531036","full_name":"anthony-chaudhary/dos-kernel","owner":"anthony-chaudhary","description":"Catch your AI agents when they lie about what they shipped — verifies claims against git instead of believing the agent.","archived":false,"fork":false,"pushed_at":"2026-06-17T21:47:23.000Z","size":63169,"stargazers_count":8,"open_issues_count":103,"forks_count":3,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-06-17T23:22:24.670Z","etag":null,"topics":["agent-monitoring","agent-orchestration","agents","ai-agents","autonomous-agents","claude","claude-code","claude-plugin","cli","developer-tools","hooks","llm-agents","mcp","mcp-server","model-context-protocol","multi-agent","python","trust","verification"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/dos-kernel/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/anthony-chaudhary.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-06-10T21:25:11.000Z","updated_at":"2026-06-17T21:47:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/anthony-chaudhary/dos-kernel","commit_stats":null,"previous_names":["anthony-chaudhary/dos-kernel"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/anthony-chaudhary/dos-kernel","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anthony-chaudhary%2Fdos-kernel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anthony-chaudhary%2Fdos-kernel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anthony-chaudhary%2Fdos-kernel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anthony-chaudhary%2Fdos-kernel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/anthony-chaudhary","download_url":"https://codeload.github.com/anthony-chaudhary/dos-kernel/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anthony-chaudhary%2Fdos-kernel/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34610829,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-21T02:00:05.568Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-monitoring","agent-orchestration","agents","ai-agents","autonomous-agents","claude","claude-code","claude-plugin","cli","developer-tools","hooks","llm-agents","mcp","mcp-server","model-context-protocol","multi-agent","python","trust","verification"],"created_at":"2026-06-19T19:00:19.262Z","updated_at":"2026-06-21T13:00:49.775Z","avatar_url":"https://github.com/anthony-chaudhary.png","language":"Python","funding_links":[],"categories":["Applications","MCP Support","Development Tools \u0026 Utilities"],"sub_categories":["Tools","MCP Servers"],"readme":"\u003c!-- GENERATED FILE — do not edit README.md directly.\n     The source of truth is docs/readme/ (one file per section, assembled\n     in filename order). Edit the part, then run:\n         python scripts/build_readme.py\n     tests/test_readme_assembly.py pins this file to the parts. --\u003e\n\n# DOS — the Dispatch Operating System\n\n\u003e ### Catch your AI agents when they lie about what they shipped.\n\n[![PyPI](https://img.shields.io/pypi/v/dos-kernel)](https://pypi.org/project/dos-kernel/)\n[![Python versions](https://img.shields.io/pypi/pyversions/dos-kernel)](https://pypi.org/project/dos-kernel/)\n[![CI](https://github.com/anthony-chaudhary/dos-kernel/actions/workflows/ci.yml/badge.svg)](https://github.com/anthony-chaudhary/dos-kernel/actions/workflows/ci.yml)\n[![verified by DOS](https://github.com/anthony-chaudhary/dos-kernel/actions/workflows/dos-gate.yml/badge.svg)](https://github.com/anthony-chaudhary/dos-kernel/actions/workflows/dos-gate.yml)\n[![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)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/anthony-chaudhary/dos-kernel/blob/master/LICENSE)\n\n\u003e 📊 **See it run on real repos:** the **[scoreboard](https://anthony-chaudhary.github.io/dos-kernel/scoreboard/)**\n\u003e scores 15 popular AI-built repos (roborev, open-interpreter, crewAI, autogen, …)\n\u003e — how much agents wrote, which ones, and whether each commit's claim is backed\n\u003e by its own diff. Score yours: `dos commit-audit --sweep --workspace . BASE..HEAD`.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg 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%\"\u003e\n  \u003cbr\u003e\n  \u003cem\u003eThe whole pitch in one recording: the agent claims two features shipped; git backs one.\n  \u003ccode\u003edos verify\u003c/code\u003e answers from the commits, the lie exits \u003ccode\u003e1\u003c/code\u003e, and a gate on that\n  exit code refuses the false \"done\". Every line is the real CLI's verbatim output —\n  \u003ca href=\"https://github.com/anthony-chaudhary/dos-kernel/blob/master/scripts/build_caught_lie_cast.py\"\u003e\u003ccode\u003escripts/build_caught_lie_cast.py\u003c/code\u003e\u003c/a\u003e re-records it whenever the output changes.\u003c/em\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/anthony-chaudhary/dos-kernel/master/docs/assets/loop-hero.svg\" alt=\"Two agent fleets side by side. Left, no referee: agents all report 'done!', every report is believed, and silent corruption (lies, collisions, spin) piles up into a codebase that 'sorta works' and can't be changed. Right, DOS adjudicates: dos verify reads git and the run branches to SHIPPED (exit 0, land it) or NOT_SHIPPED (exit 1, re-dispatch — caught), and that verdict steers the next step.\" width=\"100%\"\u003e\n  \u003cbr\u003e\n  \u003cem\u003eRun a fleet of agents on one repo. The left loop just feels like progress; the right one you can steer.\n  The only difference is a verdict DOS reads from the real world — here, git — never the agent's word.\u003c/em\u003e\n\u003c/p\u003e\n\nAn AI agent will tell you it finished. DOS checks the real world instead of\ntaking its word — and the nearest piece of the real world is your git history.\nAn agent says it shipped the login endpoint; did it? Run one command,\n`dos verify`, and it answers from the artifacts the work left behind, not from\nwhat the agent typed: a commit backs the claim → `SHIPPED`, exit `0`; nothing\nlanded → `NOT_SHIPPED`, exit `1`. The agent's story never enters into it. (Git\nis just the first witness DOS reads; the file tree, the clock, a CI status, a\ntest environment's own state are others — anything the agent didn't author.)\n\n```bash\ndos verify AUTH AUTH1   # → SHIPPED      AUTH AUTH1 e62f74d   (exit 0)\ndos verify AUTH AUTH2   # → NOT_SHIPPED  AUTH AUTH2           (exit 1)\n```\n\nThat's the smallest version. It scales up, too: point a dozen agents at one\nrepo — in CI, in a fleet, racing on the same files — and DOS also tells you\nwhich ones are stepping on each other, which one is spinning in circles, and\nwhich claim of \"done\" is real. Every answer comes from the artifacts (git, the\nfile tree, the clock), never the narration. It works on a plain `git` repo with\nzero config and gets smarter the more you tell it, and the only thing you ever\ninstall is one small Python package.\n\n\u003e ⚡ **Just add it — two commands, zero decisions.** From the repo where your\n\u003e agent works:\n\u003e\n\u003e ```bash\n\u003e pip install dos-kernel\n\u003e dos init --hooks auto   # finds the agent runtime(s) you already use, wires in the checks\n\u003e ```\n\u003e\n\u003e From then on: your agent can't tell you **\"done\"** unless the work actually\n\u003e landed, two agents can't silently overwrite each other's files, and a run\n\u003e that stalls gets flagged instead of quietly spinning. Nothing about your\n\u003e workflow changes, and you don't need to learn any of the vocabulary below to\n\u003e be covered. It prints the one config file it wrote; deleting the `dos hook`\n\u003e entries there undoes it. (No runtime detected? It says so and lists the\n\u003e names to pick from — it never guesses.)\n\n\u003csub\u003e**v0.28.0** · 5,600+ tests · CI: Python 3.11–3.13 on Linux + a Windows 3.13\nsmoke run · the only runtime dependency is **PyYAML** · **MIT**.\u003c/sub\u003e\n\n\u003e 🧭 **Where to go next:** the [why \u0026 evidence](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/guide/why-a-referee.md) (plain-words story, the 20-lines-of-bash answer, what's proven),\n\u003e [wire it into your stack](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/guide/wire-it-in.md) (MCP · hooks · install), the\n\u003e [syscall + CLI reference](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/guide/cli-reference.md), or, **reading this as an AI agent?**, [AGENTS.md](https://github.com/anthony-chaudhary/dos-kernel/blob/master/AGENTS.md) — build/test/check in three lines. The full map is the router just below.\n\n\u003e 🔤 **Five words the rest of this page leans on.** A **plan** is a named goal\n\u003e (`AUTH`); a **phase** is one shippable step of it (`AUTH1`); a **lane** is the\n\u003e slice of the file tree one agent may touch; the **oracle** is the part of DOS\n\u003e that reads the evidence and rules; a **stamp** is the mark a shipped phase\n\u003e leaves in a commit subject (`AUTH1: …`) — the thing the oracle greps for.\n\u003e That's the whole vocabulary.\n\n\u003ca id=\"who-this-is-for\"\u003e\u003c/a\u003e\n\u003ca id=\"the-plain-words-version\"\u003e\u003c/a\u003e\n\n## In plain words\n\nA coding agent does work, then tells you how it went. Usually the story is true;\nsometimes it's the cheerful *\"all work completed!\"* from a worker that shipped\nnothing. With one agent you catch that yourself by re-reading its output — a real\ntax you already pay. Run twenty at once and that tax stops being payable: nobody\nreads everything, each worker grades its own homework, and the unchecked problems\npile up quietly until the codebase *sorta* works and nobody can safely change it.\nDOS is the referee that never reads the story — it reads what happened (the\ncommit, the file, the clock) and hands you a verdict no narration can move. It\ncosts about an afternoon, has one runtime dependency, and stays in its lane: it\ntells you *what happened*, never whether the code is *good* — quality stays with\nyour tests and reviews. ([The full plain-words version](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/guide/why-a-referee.md#the-plain-words-version).)\n\n## Measured, not asserted\n\nEvery number here is scored against a fact the agent can't fake (a test\nenvironment's DB state, git history). A DOS gate caught **15 \"I shipped it\" lies\nin 258 tasks across two models with zero false alarms**; the same referee stopped\n**6 of 8** silent collisions on one shared record; quitting doomed runs at the\nright moment saved **~11% of fleet compute with 0 of 1,634 winners wrongly\nkilled**; and the reward-set admission label lifted acceptance precision **60% →\n100%** by purging poison a self-graded collector keeps. The methodology, the two\nmoney-moment figures, and the projected-vs-bet honesty gradient are in\n**[what's proven and what's still a bet](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/guide/why-a-referee.md#whats-proven-and-whats-still-a-bet)**.\n\n## Where the rest of the docs are\n\nThis page keeps the hook, the demo, and the failure it fixes. Everything deeper\nlives on a focused page — find the question you arrived with and jump:\n\n| You're asking… | Go to |\n|---|---|\n| *\"What is this in plain words, and why should my team care? Is it real?\"* | [Why a referee](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/guide/why-a-referee.md) — the plain-words story, the 20-lines-of-bash / Temporal answers, and the full proven/bet evidence |\n| *\"Show me it working, fast.\"* | [Try it in 60 seconds](#try-it-in-60-seconds), just below — one command |\n| *\"I already run agents — how do I wire the verdict into **my** stack?\"* | [Wire it in](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/guide/wire-it-in.md) — MCP, runtime hooks, the exit-code tier, fleet frameworks, and the install matrix |\n| *\"What's the full command / syscall surface?\"* | [The syscall ABI \u0026 CLI reference](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/guide/cli-reference.md) — every verb, the three live screens, the verdict journal |\n| *\"I run a fleet every day — how do I watch it, triage it, debug it?\"* | [Operating a fleet](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/guide/operating-a-fleet.md) + [Debug a stuck fleet](https://github.com/anthony-chaudhary/dos-kernel/blob/master/examples/playbooks/06_debug-a-stuck-fleet.md) |\n| *\"How do I bend it to my org without forking it?\"* | [Extending it](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/guide/extending.md) — the seven axes, the docs index, the playbooks |\n| *\"What is actually proven, and can I re-run it?\"* | [For researchers](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/guide/for-researchers.md) — claims → invariants → reproduction |\n| *\"I'm an AI agent orienting in this repo.\"* | **[AGENTS.md](https://github.com/anthony-chaudhary/dos-kernel/blob/master/AGENTS.md)** — what DOS is in three lines, build/test/check, the ~5 files worth reading |\n| *\"What surfaces are stable and what's the deprecation window?\"* | **[docs/STABILITY.md](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/STABILITY.md)** — the compatibility promise, what the version number means, and what will never break |\n\n## Try it in 60 seconds\n\nGot a terminal? This runs the whole thing in a throwaway repo — one command\nscaffolds it, makes a real commit, verifies it, and cleans up after itself:\n\n```bash\npip install dos-kernel      # PyYAML is the only runtime dep\ndos quickstart              # → SHIPPED AUTH AUTH1 … then NOT_SHIPPED AUTH AUTH2\n```\n\nOne `SHIPPED`, one `NOT_SHIPPED`: the first is a claim git can back, the second\nis a claim nothing landed for. That contrast is the product. The demo closes\nwith a router to wherever you already run agents — a Claude Code / Cursor tab\n(`dos init --hooks`), an MCP host, a CI step, or a fleet — so your next move is\none line, not a docs dig. (Add `--keep ./demo` to keep the repo and poke at it.\nDon't even want the install? `uvx --from dos-kernel dos quickstart` runs the\nsame demo ephemerally — nothing left behind.) The same thing by hand, in five\nlines, is **[docs/QUICKSTART.md](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/QUICKSTART.md)**.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/anthony-chaudhary/dos-kernel/master/examples/demo/verify-moment.svg\" alt=\"The dos verify money-moment. Two equally-confident agent claims, checked against git. Left, what the agent claims (forgeable): 'Shipped AUTH1 — the login endpoint is done' and 'AUTH2 is done too — all work completed!'. Right, what git actually records: one real commit e389e8b 'AUTH1: ship the login endpoint', and no commit anywhere mentions AUTH2. The two verdicts: dos verify AUTH AUTH1 finds the token in a real commit subject → SHIPPED, exit 0, via grep-subject; dos verify AUTH AUTH2 finds it nowhere → NOT_SHIPPED, exit 1, via none. The confident AUTH2 claim collapses the instant no commit backs it.\" width=\"100%\"\u003e\n  \u003cbr\u003e\n  \u003csub\u003e\u003cem\u003eTwo equally confident claims, one verdict each — \u003ccode\u003eSHIPPED\u003c/code\u003e for the one git can back, \u003ccode\u003eNOT_SHIPPED\u003c/code\u003e for the one nothing landed for. Every string is verbatim output of \u003ca href=\"https://github.com/anthony-chaudhary/dos-kernel/blob/master/examples/demo/verify_demo.sh\"\u003e\u003ccode\u003eexamples/demo/verify_demo.sh\u003c/code\u003e\u003c/a\u003e. \u003ca href=\"https://github.com/anthony-chaudhary/dos-kernel/blob/master/examples/demo/verify_visual.html\"\u003eStep through it locally\u003c/a\u003e for the click-through version (it's an HTML file — clone the repo and open it in a browser; GitHub shows its source, not the running page).\u003c/em\u003e\u003c/sub\u003e\n\u003c/p\u003e\n\nThe smallest real win: in a CI step or dispatch loop, replace the line that\ntrusts an agent's \"done\" with `dos verify PLAN PHASE` and branch on its exit\ncode (`0` shipped / `1` not). No parsing, no plan, no config — the\n[CI integration cookbook](https://github.com/anthony-chaudhary/dos-kernel/blob/master/examples/playbooks/cookbook-ci-integration.md) walks it\nend-to-end. To run it on a repo shaped like yours, start with\n[Onboard a repo in 10 minutes](https://github.com/anthony-chaudhary/dos-kernel/blob/master/examples/playbooks/01_onboard-a-repo.md).\n\nPoint the same witness at a **review queue** when commits pile up faster than\nanyone can read them. [Residual review](https://github.com/anthony-chaudhary/dos-kernel/blob/master/examples/residual_review/)\nfolds `commit-audit`'s per-commit verdict into three bands — **CLEARED** (the\ndiff witnessed the claim, so spend ~0 attention re-asking \"did it do what it\nsaid\"), **RESIDUAL** (a claim git couldn't back — the human's 100%), and the\nno-claim rest. On this repo's own last 200 commits it cleared 170 of 171\ncheckable claims: that's the re-review you skip, proven by git rather than a\nmodel's confidence score. (CLEARED means the change's *shape* matched its\nclaim — **not** that the code is correct; correctness review still applies to\nevery commit. The band can only ever ask for *more* eyes, never fewer.)\n\n*Next level up — wire the verdict into your own stack: [Wire it in](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/guide/wire-it-in.md).*\n\n## What goes wrong in a fleet\n\nRun a pile of agents at once with nobody refereeing, and here's how it goes:\neach worker reports its own success, and you believe the reports, because what\nelse is there to go on? The unchecked problems pile up quietly — a lie here,\ntwo agents clobbering the same file there, a little scope creep, one worker\nspinning in circles — until the codebase *sorta* works and nobody can safely\nchange it.\n\nThe trouble is you launched the agents and then let them grade their own\nhomework. DOS gives you the missing signal — a verdict from ground truth — so\nthe loop closes. Here is the same fleet under both regimes:\n\n\u003c!-- Don't reference the diagram's left/right in prose. Mermaid decides where\n     disconnected subgraphs land (GitHub stacks them vertically), so a positional\n     caption is a claim about a render nobody verified — name the subgraph\n     titles instead; those travel with the boxes wherever the renderer puts\n     them. --\u003e\n\u003cdetails open\u003e\n\u003csummary\u003eThe two regimes as a flowchart — \u003cstrong\u003eNO REFEREE:\u003c/strong\u003e you believe the narration; \u003cstrong\u003eDOS ADJUDICATES:\u003c/strong\u003e you steer on a verdict\u003c/summary\u003e\n\n```mermaid\nflowchart LR\n  subgraph OPEN[\"NO REFEREE — you believe the narration\"]\n    direction TB\n    A1[\"agent: 'done!'\"] --\u003e B1[[\"believed\"]]\n    A2[\"agent: 'done!'\"] --\u003e B1\n    A3[\"agent: 'done!'\"] --\u003e B1\n    B1 --\u003e C1[\"silent corruption piles up\u003cbr/\u003e(lies · collisions · spin)\"]\n    C1 --\u003e D1[\"'sorta works' — can't be changed\"]\n  end\n  subgraph CLOSED[\"DOS ADJUDICATES — you steer on a verdict\"]\n    direction TB\n    A4[\"agent: 'done!'\"] --\u003e V{{\"dos verify\u003cbr/\u003ereads git\"}}\n    V --\u003e|in git ancestry| S[\"SHIPPED (exit 0)\"]\n    V --\u003e|found nowhere| N[\"NOT_SHIPPED (exit 1)\"]\n    S --\u003e L[\"land it\"]\n    N --\u003e R[\"re-dispatch / flag — caught\"]\n    R -.verdict steers the loop.-\u003e A4\n  end\n```\n\n\u003c/details\u003e\n\nHere are the failures a fleet actually produces, each next to the ground truth\nthat quietly contradicts the worker's story — and the verdict DOS hands back:\n\n| A worker… | …but the ground truth is | DOS verdict |\n|---|---|---|\n| says it shipped a unit of work | no commit ever landed | `verify` → **caught lie** |\n| tried, but the commit silently failed | no commit ever landed | `verify` (the flake — indistinguishable from a lie *without* git) |\n| edits files another worker owns | two agents, one shared file | `arbitrate` → **refuse** the second |\n| overruns the file region it claimed | footprint reaches beyond the declared tree | `scope-gate` → **REFUSE** (before the write lands) |\n| reports \"making progress\" | 0 commits, only a fresh heartbeat | `liveness` → **SPINNING** |\n\nThe first row is the most common one. The classic tell is a cheerful one-liner,\n*\"all work completed!\"*, from a worker that did little or nothing. DOS never\nreads that line; it reads the ground truth, so the claim collapses the instant\nno artifact backs it (more in\n[docs/108](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/108_the-cheap-lie-and-the-narration-taxonomy.md)). That's also\nwhat makes it cheap to adopt: `verify` needs no plan, no registry, no config,\nand the exit code *is* the verdict — any shell or CI step can branch on it\nwithout parsing a word.\n\n\u003csub\u003e*Prefer to watch it move?* The two loops are also a self-contained animation you\nstep through one frame at a time — clone the repo and open\n[`docs/assets/loop_visual.html`](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/assets/loop_visual.html) in a browser. (It's an\nHTML file, so GitHub shows its source rather than running it — open it locally.)\u003c/sub\u003e\n\n**Lease scope — single filesystem today.** The verification half (`verify`,\n`commit-audit`, `liveness`) travels across machines freely because it reads git\nhistory. The admission half (`arbitrate`, lane leases) is local-filesystem only:\nthe WAL lives on one disk, and workers on separate machines share no\nserialization point. A fleet that runs all its workers on one machine or in one\nshared filesystem is fully covered; a fleet spanning multiple hosts should treat\n`dos arbitrate` as advisory (not a hard mutex) until a remote-lease driver\nships. See [docs/366](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/366_single-filesystem-lease-boundary.md) for the\ndesign.\n\n### How far you take it\n\nIt works on a plain `git init` with zero config, and gets smarter the more you\ntell it. You don't adopt a framework and pick a tier; you start at the shallow\nend and it keeps paying off as you wade deeper — the same kernel the whole way:\n\n- **Zero config.** Point `dos verify PLAN PHASE` at a plain git\n  repo — no plan, no registry, no `dos.toml`. It answers from commit history\n  alone (`via grep-subject` / `via none`). This is the whole of\n  [QUICKSTART](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/QUICKSTART.md) and the day-one CI win above.\n- **Tell it your structure.** `dos init` writes a `dos.toml` (lanes, paths,\n  ship grammar as data); add a plan doc and `dos plan` lays each phase's\n  *claim* beside the oracle's verdict. Here's [exactly what a plan file looks\n  like](https://github.com/anthony-chaudhary/dos-kernel/blob/master/examples/plans/example-plan.md) (copyable, round-trips with the built-in\n  reader), and four worked [example workspaces](https://github.com/anthony-chaudhary/dos-kernel/tree/master/examples/workspaces).\n- **Teach it your own types.** Declare your own block reasons, gate\n  verdicts, output renderers, admission predicates, a model-backed judge, a\n  custom plan dialect, or a whole host driver — all as workspace policy,\n  never a fork. The map is **[docs/HACKING.md](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/HACKING.md)** (seven extension\n  axes) + the copy-me **[`examples/dos_ext/`](https://github.com/anthony-chaudhary/dos-kernel/tree/master/examples/dos_ext)**.\n\n### How you plug it in\n\nThat slope is how deep your config goes. The other axis is how you call the\nreferee at all — and you adopt through whichever surface matches how you\nalready work, not by restructuring your stack. The same kernel verdicts are\nreachable through every row here, lowest-friction first:\n\n| Surface | Adopt it when… | The move |\n|---|---|---|\n| **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). |\n| **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 \u003cruntime\u003e` 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). |\n| **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). |\n| **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). |\n| **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). |\n| **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). |\n| **Skill pack** | you run agents in Claude Code and want the workflow, not just the verdict | `dos init --skills` drops editable `SKILL.md` screenplays that wire the syscalls into a snapshot → audit → gate → take-a-lane loop. See [QUICKSTART §2](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/QUICKSTART.md). |\n| **Driver** | your lanes must be *computed*, or you add a provider-backed judge | write one `dos/drivers/\u003chost\u003e.py` (a `LaneTaxonomy` + a config factory), loaded by name, never imported by the kernel. The map is [HACKING.md](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/HACKING.md). |\n\nThe two axes are independent: a zero-config repo can adopt through any surface,\nand a deeply-configured one still answers over the same CLI and MCP tools.\nStart at the top row — it's the one that costs nothing to try. The first two\nrows also compose: MCP advises (the agent checks its own work), hooks enforce\n(the host stops a bad action) — wire both for the full loop.\n\nThose surfaces are the upstream half of the value chain — who calls the\nreferee. The same verdicts also flow downstream, to the systems that act on\nthem: every adjudication lands in a verdict journal that `dos export` drains to\nyour observability stack (Datadog / Honeycomb / Grafana —\n[docs/266](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/266_the-verdict-exporter-shipping-the-journal-to-where-dashboards-live.md)),\n`dos notify` pushes what-needs-a-human to Slack, `dos reward` gates what a\nfine-tune may train on, and `dos attest` mints a signed receipt a skeptic can\ncheck without loop access\n([docs/246](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/246_dos-attest-the-portable-signed-receipt.md)). One kernel, one\nverdict vocabulary, from the agent's tool call to your dashboard.\n\n*Next level up — run it every day: [Operating a fleet](#operating-a-fleet).*\n\n## Citation\n\nThe ideas here are written up in a paper — *\"Verification Is All You Need — But\nNot Where You Think\"* — on the out-of-loop referee for agent fleets. A built PDF\nlives at [`paper/releases/`](https://github.com/anthony-chaudhary/dos-kernel/tree/master/paper/releases); the arXiv preprint is in\npreparation. Until the arXiv ID lands, cite the repository:\n\n```bibtex\n@misc{dos_kernel,\n  title        = {Verification Is All You Need --- But Not Where You Think},\n  author       = {Chaudhary, Anthony},\n  howpublished = {\\url{https://github.com/anthony-chaudhary/dos-kernel}},\n  note         = {DOS --- the Dispatch Operating System; arXiv preprint in preparation},\n  year         = {2026}\n}\n```\n\n## License\n\nMIT — see [LICENSE](https://github.com/anthony-chaudhary/dos-kernel/blob/master/LICENSE).\n\n\u003c!-- The marker below is the official MCP Registry's PyPI ownership proof: the\n     registry only accepts a server.json naming the `dos-kernel` PyPI package if\n     this exact token appears in the published package README. Keep it intact. --\u003e\n\u003c!-- mcp-name: io.github.anthony-chaudhary/dos-kernel --\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanthony-chaudhary%2Fdos-kernel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fanthony-chaudhary%2Fdos-kernel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanthony-chaudhary%2Fdos-kernel/lists"}