dos-kernel AGENTS.md

AGENTS.md — orientation for an AI agent working in this repo

You are an AI agent reading this repo to understand it or change it. This file is your front door: what DOS is in three lines, how to build and check your work, the short list of files actually worth reading, and the rules the kernel enforces on its own contributors. It is deliberately short and navigational — the detail lives behind the links.

Fitting, given what DOS is: the kernel exists to not believe an agent's self-report. So don't take this file on faith either — every claim here is one you can check with a dos command or a git read, and where that's the point, the command is shown. (Human-oriented? Read README.md instead; it is the same story written for a person browsing GitHub.)

What DOS is (the 30-second version)

DOS is a small, deterministic kernel that referees a fleet of AI agents working on a shared git repo. Every agent narrates — "I shipped it," "tests pass," "still making progress." DOS treats all of that as a claim, not a fact, and hands back a verdict read from ground truth the agent could not have authored: git history, the file tree, a clock, an environment's own state.

• verify — did (plan, phase) actually ship? (from git ancestry, never the agent's word)
• arbitrate — may this agent take this lane, or does it collide with one already running?
• liveness — is the run ADVANCING, or just SPINNING / STALLED?
• refuse — say no with a reason a machine can act on.

Nothing here is coding-specific: a repo declares its own rules (lanes, paths, ship-stamp grammar) as data in dos.toml; the kernel supplies only the machinery. Reach it from the dos CLI, an MCP server, or import dos.

Run it yourself first — the 60-second proof

Before reading anything, watch the core idea happen:

pip install -e .       # editable install from this clone (PyYAML is the only runtime dep)
dos quickstart         # scaffolds a throwaway repo, commits, then:
                       #   SHIPPED AUTH AUTH1 … (via grep-subject)   exit 0
                       #   NOT_SHIPPED AUTH AUTH2 … (via none)        exit 1