rebar AGENTS.md

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 + test, and make test selects exactly what CI's gating ubuntu-latest, py3.13 cell selects (not integration and not external) — a superset of every other matrix cell — so it is the locally checkable half of Verified, with nothing to enumerate and nothing to drift.

It costs 20-25 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 -- 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).

Codex environment rule: use the current worktree's virtualenv for every development command. A prior source .venv/bin/activate does not persist across separate Codex shell-tool calls, so prepend it explicitly, for example env PATH="$PWD/.venv/bin:$PATH" make lint and env PATH="$PWD/.venv/bin:$PATH" make typecheck. If .venv is absent, run the canonical bootstrap from docs/local-dev-env.md (make venv, activate it, then make install), or create the worktree with make worktree name=<branch>, which provisions it. Use make venv rather than a bare python3 -m venv — it pins the interpreter to the version CI tests (.github/python-version.txt) instead of inheriting the host's ambient python3. Before reporting a lint/typecheck failure, rerun with the worktree .venv/bin first on PATH; ambient Ruff or a missing ambient mypy is an environment error, not repository evidence. This is the non-interactive Codex equivalent of the activated repo-venv shell used by Claude Code.