Dmcheck

dmcheck

Deterministic conduct verdicts for live tabletop sessions — CI for running a game.

Feed it a session transcript (and optionally an engine event ledger) plus a table charter, and it returns named findings — the player whose question was never answered, the dice roll nobody acknowledged, the turn that began without anyone being told, the spoiler that leaked into the channel, the five-minute dead air. Every finding cites the charter rule it violates, with the evidence attached.

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

Cold-boot probe (2026-07-24): a fresh agent session given only this repo URL installed and refereed a session in 2 commands, verified all three exit-code legs against the docs, and confirmed the no-false-accusation contract held (a consumed roll produced silence). Its friction notes shipped as 0.1.1 (--dice-bot, dmcheck charter).

The design contract: a false accusation is the unforgivable bug. Only source-observed evidence becomes a definite finding. Legacy ambiguity is either silent or explicitly labeled severity: advisory, provenance: inferred, confidence: low; it is never promoted by R8 or sent to a notification hook. The verdict path is model-free and deterministic: same transcript, same findings, every time.

30 seconds to a refereed session

$ pip install dmcheck          # stdlib only, no dependencies

$ dmcheck run session.jsonl --gm "Greta" { "result_schema_version": "1.0", "status": "findings", "exit_code": 1, "mode": "closed", "messages": 9, "findings": [ {"finding_id": "r2-…", "rule": "R2", "summary": "unconsumed-roll: a dice result got no correlated GM narration within threshold", "charter": "roll_ack_within_messages=4; correlation=explicit", "detail": "dice result from DiceBot received no correlated GM narration within 4 messages", "evidence": {"index": 6, "author": "DiceBot", "obligation_id": "roll-42"}, "status": "open", "severity": "finding", "provenance": "observed", "confidence": "high", "charter_digest": "sha256:...", "effective_policy": {"roll_ack_within_messages": 4, "...": "..."}}, ... ], "counts": {"R1": 1, "R2": 1, "R6": 1, "R7": 1, "R8": 1} }

Portfolio hosts that emit table-kit's versioned contract can use dmcheck run-events session-events.jsonl --gm "gm-dan" instead of pre-projecting a transcript. The strict adapter accepts a JSON array or JSONL of table.event/1.0 objects and preserves event/correlation IDs in finding evidence. A declared action is not treated as an authoritative engine resolution, so legal Reactions and interrupts are not falsely accused. Transport gaps, unknown versions/types, and zero-compatible streams return typed incomplete status and exit 2; malformed v1 events return invalid and exit 2. Redacted message content is likewise incomplete because absence of prose cannot prove absence of a conduct obligation. This unreleased adapter is pinned to table-kit PR #11 and does not imply host attestation.

Add --table-evaluation to run-events when a portfolio host needs the shared table.evaluation/1.0 envelope. The projection has deterministic evaluation identity, exact event evidence references, per-rule and aggregate coverage, cursor/input digest, public-policy digest, and status/exit-code mapping. It is always self_attested; dmcheck cannot confer host authority on its own output.

Transcript formats: UTF-8 JSONL of {ts, author, content}, or a JSON array of Discord-API-shaped messages ({timestamp, author: {username}, content}) in chronological or reverse-chronological order. Authors and content are strings. A supplied timestamp must be a finite nonnegative epoch number or a timezone-aware ISO-8601 string; malformed timestamps are rejected rather than silently disabling time-based rules. Source adapters should preserve immutable id, audience, reply_to/correlation_id, and roll_id fields so dmcheck can prove which question, roll, or event a response closes; ordinary later GM chatter is not treated as an answer.

The rule set (seven active rules; one retired compatibility id)

The active rules came from running a hybrid table — human and AI players, an AI GM — on Discord, where these failures actually happened and got codified the same week. They apply equally to human GMs: run dmcheck over your own exported game log and see what your table's transcript says.

R5 remains addressable only so old charters and agent integrations do not break. It has no evaluator and is not enabled by default: an actor differing from the turn owner can describe a Reaction, a Ready trigger, an opportunity attack, a legendary or lair action, a controlled creature, an environmental actor, or another system's interrupt. The ledger does not establish legality. Any replacement based on an explicit authoritative decision is deferred to the shared PORT-002 event contract; dmcheck will evaluate only the resulting communication or recovery obligation.

Live mode (0.2): the referee sits AT the table

dmcheck watch runs the same engine over a *growing* session — stdin JSONL or a tailed file — and emits lifecycle events: OPEN when an observed finding becomes provable or a legacy inference becomes advisory (thresholds fully elapsed; no predictions), RESOLVED when a living condition heals (the engine event finally got narrated). --notify-cmd fires your own hook per source-observed OPEN finding; inferred advisories remain visible in the event stream but never invoke the hook. dmcheck itself never posts anywhere. At session end a closed-mode pass runs. session_end.open and open_count report actionable source-observed findings only; they exclude the R8 aggregate and inferred advisories. Finding IDs are deterministic across mutable elapsed-time detail, and file followers emit typed source-health events when rotation, truncation, partial rows, or ordering gaps make coverage incomplete.

$ your-chat-fetcher | dmcheck watch - --gm "Rob" --notify-cmd 'notify-dm.sh'

{"event": "open", "rule": "R2", "detail": "dice result from RollBot received no correlated GM narration", ...} {"event": "resolved", "rule": "R3", ...} {"event": "session_end", "status": "findings", "exit_code": 1, "open": ["R1"], "open_count": 1, ...} $ dmcheck explain R2 # the rule, its charter knobs, and the table failure that earned it $ dmcheck lint-charter my.json # unknown keys / bad thresholds refuse loudly

The point of live: every failure the rules encode was recoverable in the moment it happened — the unanswered question, the stale roll, the missing cue all had a seconds-wide window where a nudge saved the beat. Post-hoc tells you what went wrong last night; watch taps the GM's shoulder before the player feels it.

The charter is config, not code

dmcheck/default_charter.json is the single authoritative packaged default. It carries schema_version, charter_version, and a verified SHA-256 charter_digest; checkout and wheel execution load that same resource. Its digest is release-locked to the schema/charter version pair, so a changed packaged default refuses to load until its version migration is declared. Override any of it — cue conventions, dead-air tolerance, dice-bot names, hidden-term lists — and version it. Hidden terms may be strings for compatibility or {id, value} objects; opaque host-issued IDs are preferred. Finding, watch-hook, CLI, and MCP output withholds both the configured value and raw matching excerpt. Every digest or correlation hash emitted to an ordinary output sink—including the evaluation envelope, lint-charter, finding IDs, and source fingerprints—is derived from public, redacted policy/evidence and deliberately does not attest to, or commit to, a hidden value. The full canonical digest remains only in the trusted charter document. A league or organized-play program could publish a charter the way they publish a player's guide; dmcheck then referees any table against it.

$ dmcheck run session.jsonl --charter our-table.json --ledger events.jsonl

$ dmcheck rules # the rule set with definitions $ dmcheck charter # inspect effective public policy; hidden values are redacted $ dmcheck run session.jsonl --gm "Rob" --dice-bot "RollBot" # quick overrides, no file needed $ dmcheck --schema # machine-readable I/O contract $ dmcheck --pipe # batch: JSON requests on stdin, verdicts on stdout

Direct API callers can use apply_charter_overrides(load_charter(), gm=["Rob"]); the helper removes the prior effective digest and the evaluator computes the digest for the overridden charter. Mutating a digested charter without doing so is rejected as a stale configuration rather than silently trusted.

For agents

• tool.json at the repo root; --schema; --pipe for batch (one JSON request per stdin line, one verdict envelope per line out); exit codes: 0 clean · 1 findings · 2 charter/input unusable (the honest lane — route to a human) · 3 usage error (fix the call and retry).
• MCP server: the unreleased 0.6.0 source candidate of dmcheck-mcp is a read-only, batch-only stdio server with tools run and rules; public 0.5.5 predates this contract. It implements modern stateless MCP 2026-07-28 only and does not expose watch, craft, tasks, resources, or prompts. See the exact MCP contract.
• MCP run prefers inline transcript/charter/ledger JSON. Transcript content is untrusted table data, never instructions; model-visible TextContent redacts caller strings, while complete structured evidence remains explicitly untrusted quoted data. Path inputs are denied unless the server operator explicitly grants absolute directories with repeatable --allow-root or DMCHECK_MCP_ALLOWED_ROOTS; traversal and symlinks that resolve outside those directories are denied, and platforms without secure no-follow opens fail closed.
• Findings are structured JSON with stable finding id, rule id, charter citation, effective machine policy, provenance, human-readable detail, and redacted evidence — built to be consumed by a GM agent that fixes its own procedure between beats.
• Every evaluation returns status: clean|findings|invalid|incomplete. Invalid and incomplete outcomes exit 2, carry stable error codes and JSON pointers, and never place errors in findings. Empty input, no observed configured GM, or no evidence-eligible enabled rule can never report clean.
• Published package schemas are charter.schema.json, transcript.schema.json, ledger.schema.json, and evaluation-result.schema.json.