agent-gate: Instructions file for Codex

AGENTS.md — agent-gate

Portable agent instructions. Read by Cursor (local + cloud agents), Claude Code, Codex, and Grok Bot cloud-agent runs. Keep this file under ~150 lines. Procedures live in .cursor/skills/. Scoped rules live in .cursor/rules/*.mdc. Review rules live in .cursor/BUGBOT.md. There is no CLAUDE.md. This file is the source of truth.

What this repo is

agent-gate (PyPI: mcp-agent-gate) is an MCP server an agent calls on its own work before it claims done: a fail-closed checklist, then an append-only sha256 receipt ledger. The core is stdlib; agent_gate/server.py is the thin MCP adapter. The bar this repo holds itself to is the CI coverage gate: pytest fails if line coverage of agent_gate drops below 90%. Reproduce with the test command below. README also says the tree is "currently 97% covered"; that sentence is a published number — see Known traps before treating it as a live measurement.

• Status: active · License: MIT · Package: mcp-agent-gate
• Entry points: console script agent-gate = agent_gate.server:main (verified in pyproject.toml). Also python -m agent_gate.server.
• Part of: the governed-agent stack (rag-guard · graph-guard · agent-gate · crucible · oracle-gate · agent-cost-attribution · bow · fleet-mode)

Commands (run these; do not guess)

pip install -e ".[dev]" pytest-cov
# lint: n/a — no ruff or mypy config
# typecheck: n/a
python -m pytest -q --cov=agent_gate --cov-report=term-missing --cov-fail-under=90
python scripts/check_receipts.py
# eval: n/a — there is no eval harness and no --check scorer
PYTHONPATH=. python3 examples/demo.py   # manual; sleeps; hashes include timestamps

A task is not done until the pytest command passes and the output is pasted in the PR. scripts/check_receipts.py recomputes the fail-closed examples quoted in the README and checks the 90% floor is still the floor.

Non-negotiables

1. No employer data. Ever. This is personal work on personal equipment. Never add, paste, paraphrase, or "anonymize" anything from an employer's systems, documents, tickets, chats, or datasets: no workforce data, internal URLs, or confidential or export-restricted material. No employer names in any file, no internal acronyms, no realistic HR records. Synthetic data only, generated by a committed script with a fixed seed. If a prompt looks like it came from work, stop and ask. scripts/scan_blocked_terms.py enforces this in CI with no exempt files.
2. Receipts over hype. Every number in README, docs, PR descriptions, or posts must be reproducible from a committed command. Link the command and the artifact (CI log or scripts/check_receipts.py). No "blazing fast", "SOTA", or "production-grade" without a measurement.
3. Honest benchmarks. Report nulls and regressions at the same prominence as wins. State n, seeds, model + version, date, and cost when a comparison exists. This repo does not run model comparisons. Never delete an inconvenient run; mark it superseded with a reason.
4. Fail closed. Gates, validators, and guards deny on error, timeout, missing input, or unparseable output. Gate.evaluate passes a check only on literal True. Never weaken a guard to make a test pass. Never catch-and-ignore exceptions in a decision path.
5. Tests and CI are the definition of done. New behavior ships with a test that fails without it. Bug fixes ship with a regression test. Do not lower --cov-fail-under=90. Do not mark tests skip/xfail to get green. tests/test_server.py skips only when the mcp SDK is missing; CI installs it.
6. Model never grades its own output. Prefer mechanical verdicts (tests, schema checks, verify_chain()). Where a judge model is needed, use a different model lineage from the author and record both.
7. Irreversible = human-gated. No force-push, no history rewrite, no publishing to PyPI, no tagging releases, no posting anywhere. Open a PR; a human merges.