rebar: Instructions file for Codex

rebar — agent & contributor guide

rebar is an event-sourced ticket system + Jira reconciler exposed as a Python library (import rebar), a CLI (rebar), and an MCP server (rebar-mcp), all over one git-backed store. This file is rebar's canonical guidance for coding agents and contributors. It is AGENTS.md — the cross-vendor standard read natively by a growing set of agent harnesses (Codex, Cursor, Copilot's coding agent, Zed, Amp, Jules, and others) — so one source serves every tool. Claude Code reads it through a one-line @AGENTS.md import in CLAUDE.md (proven in Claude Code 2.1.211); that is why the canonical content lives here, not in a Claude-specific file. Keep this file lean: an @-import loads at launch and does not reduce context, so already-documented topics are one-line pointers into docs/, not restated sections.

For internals see docs/architecture.md, docs/event-schema.md, docs/concurrency.md, and docs/migrations.md (the idempotent ensure-registry). The docs/ index is docs/README.md.

Bootstrap the env with make install (not a bare pip/uv pip install) so the pre-commit hook is wired — that hook is the commit gate that runs make lint (ruff check + format-check) on every git commit. A bare editable install skips it; if you are in such a checkout run make hooks once to (re)install and verify the hook. When developing rebar itself — running the gates/LLM ops or testing config — run the repo checkout's build, not a stale global install (which silently ignores newer config keys and may lack the [agents] extra): see docs/local-dev-env.md.

Before you PUSH, run make verify — make lint is NOT the CI contract. make lint (+ make typecheck, together make check) is the commit gate: fast, check-only, wired into the pre-commit hook. It cannot be the whole story, because a large family of this repo's invariants is enforced by pytest rather than by a lint script — the ratchets' own baseline-vs-tree comparisons, the public-API surface census, CI-workflow parity, generated- artifact and docs drift, whole-tree AST policy scans (roughly seventy modules). On 2026-09-04 three separate changes were pushed red by exactly those tests after their authors ran make lint and make typecheck and saw green (bug 1035-bed7-c855-4732). make verify = lint + typecheck + the bare-pytest import-convention guard + test, and make test runs exactly the two pytest selections CI's gating ubuntu-latest, py3.13 cell runs, in order — the default tier (not integration and not external), then the integration tier (integration and not live) — a superset of every other matrix cell, so it is the locally checkable half of Verified. tests/unit/test_ci_workflow_parity.py asserts both against the workflow, so the two cannot drift silently (bug a8af-ac33-74aa-4ccd). not live keeps tests that reach a real Jira out even when your shell exports Jira credentials; they run only on an explicit pytest -m live (bug 5f29-9bed-5a47-4a25, docs/jira-sync-setup.md). The import-convention guard is intentionally called out and run with the BARE pytest console script: python -m pytest injects the checkout root onto sys.path, so it can false-green tests.-rooted imports that fail under make test and CI.

It costs 25-30 minutes (measured twice on one six-performance-core host at the default PYTEST_WORKERS=4: 22 min 25 s and 26 min 04 s wall for lint + typecheck + ~19.2k tests, plus ~3 min 40 s for the 200-test integration tier -- the spread is host load, so plan for the top of the range; make test PYTEST_WORKERS=8 on a bigger box). That is the price of the contract, and it is stated here so you can plan for it rather than kill it: it is still cheaper than a 15–20 minute Verified -1 round trip, and it is the only local command that lets you say "I verified this" and be right. Run it once before git push gerrit, not on every commit — that is why it is a separate target and not part of the hook. Do not wrap it in a timeout (see the bounding section: it is a bounded workload that terminates with a verdict).