Extending it, and the docs map

June 16, 2026 · View on GitHub

← Part of the DOS README. Bend DOS to your org without forking it — and the full documentation index and playbook set.

Hacking it

DOS is built to be extended without forking the package — add your own block reasons, gate verdicts, admission/safety predicates, output renderers (the dos.renderers entry-point group), and your own judge for the JUDGE rung (dos.judges, scored by dos judge-eval), all as workspace policy, not package edits. The block-reason vocabulary is fully data-driven: declare a reason in four lines of dos.toml and it becomes emittable, verifiable, refusable, and dos man wedge-documented through the same kernel calls a built-in uses. See docs/HACKING.md for the seven extension axes and the plugin model, and examples/dos_ext/ for a copy-me skeleton.

Documentation

  • docs/QUICKSTART.md — runnable 5-minute hello-world. Start here.
  • 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/ — 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 — 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.
  • docs/README.md — the docs index (guides vs. design notes vs. the dated build-journal; the numbers are chronology, not a reading order).
  • docs/HACKING.md — extend DOS without forking it.
  • docs/DOT_DOS.md — the .dos surface: what that directory is, why it's safe to delete, and the repo-resident state contract (policy in dos.toml, fossils under .dos/, verdicts in git) that keeps every host adapter thin.
  • docs/STABILITY.md — the compatibility promise: what you may depend on, what SemVer means here, how deprecations are announced (DosDeprecationWarning, a two-minor-release window), and what will never break.
  • CLAUDE.md / CONTRIBUTING.md — the architecture contract and how to send a change.
  • verify-action/ — the CI gate: a composite Action and a reusable workflow that run dos commit-audit on every PR and merge-queue group and post the verdict as the named dos-verify status check; make it required and GitHub enforces what the kernel decides (the verified by DOS badge is this gate on the kernel's own repo).
  • docs/releases/ — per-version release notes (the changelog).
  • The website — the README, condensed to one screen (good for sending to someone).

Playbooks & examples

examples/playbooks/ walks the syscalls end-to-end on anonymized real-world repo shapes — every command was run and its output pasted back verbatim:

  • Onboard a repo in 10 minutes — pip install → first verified ship, on any repo.
  • Four archetypes — a polyglot web-service fleet (concurrent lanes), an OSS library release (the stamp grammar), a data/ML pipeline (liveness), an infra monorepo (refusals).
  • Debug a stuck fleet + FAQ — symptom → the one command that diagnoses it.
  • Four cookbooks: from Python, CI / MCP integration, the exit-code tier — 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 — LangGraph, CrewAI, AutoGen, the OpenAI/Claude Agents SDK — with every framework recipe also shipped as a runnable, suite-pinned file under examples/fleet_frameworks/. Two seats ship as drivers in the package itself (docs/305): an OpenAI Agents SDK output guardrail that trips on a deliverable git can't see, and a CrewAI task guardrail that turns the retry loop into a do-the-work loop — one import line each.
  • Wire DOS into a Hermes / OpenClaw swarm — the offline, A/B-measured swarm-runtime example: the exec-capability gate refuses a prompt-injected command before it runs (real at a single agent), and the arbiter serves as the swarms' missing lock manager so the lost updates the runtime would silently incur drop to zero (value grows with fleet size; the honest K=1 falsifier is included). Both scoreboards read non-forgeable witnesses (docs/278).
  • Runnable examples/workspaces/ — cd in and run dos against a realistic lane taxonomy.

Next: evaluating the claims themselves → For researchers.