Srdcheck

srdcheck

A shared rules rail for agents: named, cited checks with explicit boundaries, so every caller can use the same deterministic result without mistaking a partial check for global legality.

Machine verdicts over specific rules of the System Reference Document 5.2.1: cited when a rule is applied, reproducible, offline, and honest enough to refuse questions outside the shipped scope. The rules lawyer for agents — including an agent acting as the authorized DM.

Agents start here → [SKILL.md](SKILL.md) — the front door: when to call this, worked examples, MUST/MUST NOTs. Family contract: FAMILY.md.

Status: v0.9.0 alpha — young but real, building in the open. The kill tests that shaped the product — including the one that killed half our original idea — are in eval/RESULTS-phase0.md; the with/without-rails demo is in demo/mage-hand/; the truth scorecard below is generated by CI.

Runtime and operating-system guarantees are defined in the support matrix: Python 3.10–3.13, a full Ubuntu suite, and explicit installed-artifact smoke contracts on Windows and macOS.

Why this exists

A game increasingly runs not as one model but as *several agents sharing one evolving state* — a GM, player agents, a rules referee, tool-callers. The moment more than one mind adjudicates, the binding problem stops being any single agent's knowledge or attention budget and becomes consistency: five capable models will each read the SRD and rule on grapple, concentration, or a death save a little differently, and the shared game state quietly desyncs. No amount of individual intelligence guarantees they agree with *each other*, and every re-derivation is another chance to drift. The fix is a deterministic rail they all call — the same atoms, the same citations, the same verdict every time — so every applied-rule result carries one provenance any agent (or a human) can audit. Table rulings retain separate ruling lineage. That is where srdcheck stops being a convenience and becomes load-bearing.

Even at a table of one, the rail earns its place. A model running a game is a brilliant improviser with a finite attention budget: every mechanical micro-check it handles in-context — *is this legal, is that slot spent, does the reaction refresh this round* — spends tokens and attention that belong to the only work that needs a mind, the story. And the checks a model *can* answer, it cannot prove, cannot reproduce, and — as our own benchmark showed — will not refuse when the question is outside the rules' jurisdiction.

We tested this before building. Frontier models answered our SRD rules questions nearly perfectly — and confidently ruled on house rules, GM discretion, and content that doesn't exist in the SRD, where the only correct answer is "not my call." Small local models got 19–30% wrong with zero refusals. So srdcheck does not compete with what models know. It is a rail: structured facts in, a deterministic scoped result out, with citations whenever it applies a rule — and the *same* rail for every agent at the table.

What it is

srdcheck answers named, bounded questions such as: *does this proposal pass the modeled action-economy check?* and *which modeled budget option kinds remain?* See the generated capability and claim map for the canonical checked and unchecked scope of every tool.

• Verdicts, not vibes. Exit code 0 = passes the checked scope, 1 = conflicts with the checked scope, 2 = cannot adjudicate. Every applied rule carries its SRD citation; boundary refusals do not invent citations.
• Scope and provenance travel with the verdict. Verdict schema 4.0 keeps coverage_level, checked_scope, unchecked_scope, and assumptions on every result and separately reports asserted/consumed/derived/missing facts, the advisory rule_result, any scoped DM table_decision, and explicit state_mutation. Every legal explanation says it is legal only within that checked scope.
• Judge, never simulate. No dice, no narration, no owned game state. State comes in with the query; a verdict goes out. The kernel is a stateless pure function — embeddable in anyone's DM product, VTT, or agent.
• State commits fail closed. event.apply emits an idempotent transition proposal bound to the exact evaluated state; transition.commit rejects a stale/out-of-order proposal and returns the same semantic receipt on retry. The agent-DM or host still performs the atomic state write. See safe state transitions.
• Agent-DM rulings persist without hidden state. Supply a portable table-policy manifest and request/encounter/session/campaign IDs to existing query tools. Matching rulings apply automatically, remain distinct from the SRD result, and carry explicit table-authority lineage. See table policies.
• Deterministic and fast. No LLM call anywhere in the verdict path. Runs local and offline.
• Observable without recording the table. Opt-in metadata-only lifecycle events carry request/verdict IDs, versions, refusal class, and timing on stderr or a caller sink. Raw prompts, state, rulings, citations, and error messages are excluded by contract; SRDCheck persists nothing.
• For agents first. MCP + CLI, --pipe, --schema, tool.json at the repo root. Humans get plain-English *why* in the same payload; agents treat that prose as explanatory, not contractual.

• Rulesets are adapters. The kernel knows no game; all rule content loads from adapter packages, each carrying its own provenance manifest — source document, hash, license, attribution — that every applied-rule result cites through. The SRD 5.2.1 adapter ships in this repo as the reference implementation. Anyone can build an adapter for another ruleset — a community, a private table, or a publisher shipping a first-party adapter for their own IP — and their content never passes through this project. The adapter catalog points; it never hosts.

See docs/product-truths.md for the invariants this project holds itself to, docs/anatomy-of-a-turn.md for executable-today versus target examples, and docs/compatibility-policy.md for the N/N-1 machine contract and correction policy.

Maintainer and acquisition diligence lives in the takeover inventory, with linked architecture, release, incident-response, and support runbooks. Unchecked takeover items are explicit gaps, not implied readiness.

Show your work. A big context window can *read* the SRD; srdcheck's value is the layer above — a consistent, cited set of rule atoms and a shared schema that several agents can rely on without each re-deriving the rules into context and drifting apart. docs/atom-concordance.md is the audit trail for that layer: every rule the engine applies, mapped to the exact SRD text it's grounded in (forward and inverse), generated and CI-checked-fresh, with a verbatim-citation oracle proving each quote really is on its cited page. A machine-readable atom-concordance.json is the slim index an agent can load to know what the rail covers and where it came from.

What srdcheck does not check yet

Honesty is the product (truth T8), so the boundaries are stated, not implied. The current SRD adapter covers combat-turn fundamentals; it does not yet check:

• Feature prerequisites. turn.plan judges the turn's *action economy* — that you spent at most one action, one bonus action, one reaction, one spell slot. It does not verify that a feature actually grants a given action. A lone two-weapon-fighting offhand attack is "action-economy legal" even though the 2024 rules require the Attack action first; that prerequisite lives in the character's features, which this version doesn't model. The success message says so explicitly.
• Per-spell effects. Damage/HP, death saves, and saving throws are now modeled (the reducer folds damage/heal/death-save; save.check and concentration.check resolve caller-rolled saves), but *what a given spell does* — Fireball's 8d6, Hold Person's paralysis on a failed save — is the long-tail swamp and stays refused. srdcheck computes the save; it does not roll the dice or apply the spell's bespoke effect.
• Condition coverage is surface-specific. All 15 SRD conditions are registry-anchored and classified clause by clause, while each query claims only the effects it actually consumes: attack modifiers, modeled action economy and Speed, selected save/check effects, damage typing, immunity, and Reaction blocking through Incapacitated and its definitional embeds. The completeness oracle proves its named attack/turn surfaces; it does not imply that every condition clause is checked by every tool. Positional geometry, initiative order, and stealth/perception contests remain explicit boundaries.
• Content outside the SRD 5.2.1 — anything not in the SRD returns exit 2 from jurisdiction; in adapter 0.2.1 the name registries cover spells, creatures, conditions, classes, subclasses, species, feats, and backgrounds (census-anchored against the source text in CI). Background coverage is jurisdiction-only: it recognizes the four backgrounds actually present in SRD 5.2.1 (Acolyte, Criminal, Sage, and Soldier) but does not yet expose their mechanics as structured facts.
• Misspelled or unknown query fields refuse loudly (adapter 0.2.1): every query validates its params against the declared schema — an unrecognized field returns exit 2 naming the offender, never a silently-defaulted verdict. A drift oracle in CI keeps handlers and schemas from ever diverging again.
• Facts are requested only while they can change the result. A granted Mage Hand use refuses with missing-fact until its relevant distance and, when it carries or manipulates an object, weight are supplied. A prohibition or an already-exceeded limit is decisive and does not trigger an irrelevant repair loop. A turn.plan move requires explicit feet; omission is never treated as a zero-foot move.

Nonsensical inputs (negative Speed, a 99th-level spell, exhaustion past 6) return exit 2 rather than a confident-looking answer. When in doubt, srdcheck refuses — a wrong verdict is the only unforgivable bug.

Try it now

$ pip install git+https://github.com/chaoz23/srdcheck

$ python -m srdcheck jurisdiction "Fireball" # exit 0 — known content $ python -m srdcheck jurisdiction "Hexblade" # exit 2 — not in the SRD, honestly refused $ python -m srdcheck query mage-hand.use '{"kind": "attack"}' { "verdict": "illegal", "exit_code": 1, "why": "The hand can't attack.", "citations": [{"section": "SRD 5.2.1 p.145 'Spells > Mage Hand'", "page": 145, "quote": "The hand can't attack"}], "rule_ids": ["mage-hand.cant-attack"], "adapter": "srd-5.2.1@0.2.1", "coverage_level": "rule-surface-complete", "checked_scope": ["listed uses and prohibitions", "10-pound limit", "30-foot range for the proposal"], "unchecked_scope": ["fine-manipulation ambiguity", "duration or range trigger tracking across events", "narrative consequences"], "assumptions": ["the supplied use kind describes the proposal", "supplied weight and distance facts are accurate when relevant to the result"] } $ python -m srdcheck query mage-hand.use '{"kind": "attack"}' --table-evaluation

deterministic table.evaluation/1.0; status=findings, authority=self_attested

$ python -m srdcheck query save.check '{"modifier":2,"dc":10,"d20_result":12,"save_ability":"dex","saver_conditions":[]}' \ --table-evaluation --table-context '{"se