a2acast AGENTS.md

a2acast — agent instructions

Cross-machine agent-to-agent mesh. One stdlib-only Python file (mesh.py) plus harness integrations for Claude Code, Codex CLI, and Copilot CLI. Tests in tests/test_mesh.py.

These rules exist because they were learned the expensive way. Read them before writing code, not after.

Hard constraints

• mesh.py is stdlib-only. No third-party imports, ever. It is meant to be curl-able and readable end to end. CI catches this (stdlib_only job, #140) and the local suite does too (StdlibOnlyTests); a third-party import fails before push. Stay vigilant — the test catches imports, not subtle misuse of a stdlib facility.
• Python 3.8+. requires-python = ">=3.8". No match statements, no X | Y unions evaluated at runtime, no 3.9+ stdlib.
• Tests: python3 -m unittest discover -s tests (python on Windows)

Writing security-relevant code

Anything touching crypto, identity, pins, certs, revocation, verdicts, or the wire format is security-relevant. So is anything on a #62 / #74 / #76 / #93 line.

1. Never claim a property you have not tested. A PR body is a hypothesis, not evidence. On 2026-07-25 three PRs in one batch each shipped a confident description asserting the exact property its code lacked — a rename guard that left both known seams open, a rollout gate that was send-side against a receive-side hazard, and a non-suppressibility mechanism that inverted into a suppression primitive. All three were caught only by reviewers reading the code. Write what the code does. If a guard is partial, say which case it misses.

2. Every security fix ships a test that fails without it. Not a test that passes with it — one that fails when the fix is reverted.

3. A guard must be load-bearing in both directions. Revert the fix: the attack test must fail. Disable the mechanism entirely: the legitimate-use test must fail. A guard that only ever blocks is a guard you can delete.