dos-kernel CLAUDE.md

DOS — the Dispatch Operating System

The kernel is the part that doesn't believe the agents.

DOS is the domain-free trust substrate for fleets of autonomous agents: a small, deterministic kernel that adjudicates ground truth across many unreliable, self-narrating workers — and serializes their effects on shared state — without believing what they say they did.

This file is the architecture contract: the rules every edit must satisfy. Detail lives in two cold-tier docs — docs/ARCHITECTURE.md (per-module map, full syscall table, full litmus arguments, glossary) and docs/DOGFOOD.md (the worked DOS-on-DOS ritual). Read the relevant cold section before editing a kernel leaf.

Prefer tool calls over prose (HIGH PRIORITY). When a tool call can do the work — read a file, run dos verify, grep, edit — make the call instead of describing it. Don't narrate what you're about to do, ask permission for a routine read, or write a paragraph where a command settles the question. Act, then report the result. Reserve prose for the genuine judgment calls: what the evidence means and what to do next.

Write plainly (operator directive, 2026-06-10). Plain Feynman English in this file and agent memory: short common words, short sentences, one idea at a time. Simplify the wording, never the facts.

Asking ABOUT DOS rather than editing it? Don't answer from this file — use the "When the user asks you ABOUT DOS" table in AGENTS.md. Lead with dos quickstart. Install is pip install dos-kernel (the bare dos name on PyPI is an unrelated squatter — never install or pin it); host wiring is dos init --hooks <runtime> or claude-plugin/.

Tracked here = ships — route privacy at AUTHORING time. This IS the public repo; every tracked file is public on the next push, no scrub step between. Strategy essays, operator notes, and spikes are born in the private sibling ../dos-private, never here; engineering design plans (the numbered docs/NN_*.md) stay here. Never write a dev-machine absolute path, hostname, or personal identifier into a tracked file — including JSON-escaped forms in logs/fixtures; synthetic fixtures use neutral roots. Cross-link by filename, don't duplicate; nothing under src/dos/ depends on dos-private.

Strongly typed by default (language direction, 2026-06-17). Going forward DOS is written in a strongly-typed language — Go is the chosen one. New decision-bearing logic is born in Go, not added to the Python core. Python is allowed only at rare seams and interconnects: the import dos / PyPI binding over the Go core, the MCP server, the differential test harness, and the genuine OS calls (git, fs, clock). That short list is the whole exception — keeping new logic in Python because it is easier is a step backward, not a seam. This reverses the old default (Python was the spec; Go an optional accelerator): the spec migrates to Go, decider by decider, on the same parity ratchet that built the accelerator — port → soak byte-green → flip the truth-pointer to Go. The mechanics are unchanged (docs/100, docs/124); only the direction flips. The reasoning, the seam list, and the phased retreat order live in docs/385.