rebar

# rebar

[![PyPI version](https://img.shields.io/pypi/v/nava-rebar)](https://pypi.org/project/nava-rebar/)
[![Python versions](https://img.shields.io/pypi/pyversions/nava-rebar)](https://pypi.org/project/nava-rebar/)
[![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
[![CI](https://github.com/navapbc/rebar/actions/workflows/test.yml/badge.svg)](https://github.com/navapbc/rebar/actions/workflows/test.yml)

**An event-sourced, git-backed ticket store + Jira reconciler built for agent
swarms — one store, exposed as a Python library, a **CLI**, and an **MCP** server.**

![rebar's core loop: `rebar ready` → `rebar claim` → `rebar transition … closed`](docs/assets/rebar-demo.svg)

- **Three surfaces, one store** — drive rebar as a **CLI** (`rebar`), a Python
  library (`import rebar`), or an **MCP** server (`rebar-mcp`).
- **The tracker lives in the repo** — tickets are an append-only event log on a
  `tickets` git branch; no database, no daemon, and it travels with every clone.
- **Built for parallel agents** — atomic claims, convergent merges, and provenance
  links let many agents and sessions write at once without lost work.
- **Optional LLM gates** — review a ticket's *plan* before work, its *completion*
  before close, and its *code* before it merges.
- **Bidirectional Jira sync** — a level-triggered reconciler keeps tickets and Jira
  in step, so teammates stay in the loop.
- **Dogfooded through two independent gates** — every change to rebar's own `main`
  must pass an LLM code review **and** CI, on Gerrit, before it lands.

## Install

```bash
pipx install nava-rebar          # the `rebar` CLI (add [mcp] / [agents] for those extras)
brew install navapbc/rebar/rebar # or via Homebrew
```

## Quickstart

Run one ticket end-to-end with the CLI or the Python library; the JSON block is the
MCP server config so agents can drive the same loop over MCP. `rebar --help` (and
`rebar <command> --help`) is the authoritative command reference.

```bash
# CLI: one ticket through init -> create -> ready -> claim -> close
rebar init
tid=$(rebar create task "Add a login page" | tail -1)   # capture the new ticket id
rebar ready                                              # lists it as ready to work
rebar claim "$tid" --assignee alice                     # open -> in_progress
rebar transition "$tid" in_progress closed              # in_progress -> closed
```
```python
import rebar                                            # the same loop via the Python library
tid = rebar.create_ticket("task", "Add a login page")
rebar.claim(tid, assignee="alice")
rebar.transition(tid, "in_progress", "closed")
```
```json
{ "mcpServers": { "rebar": { "command": "uvx", "args": ["--from", "nava-rebar[mcp]", "rebar-mcp"] } } }
```

That's the whole loop — **init → create → ready → claim → close**. The CLI and Python
blocks each drive **one** ticket end-to-end (the same id threaded through every step, no
hard-coded id); the JSON is the MCP server config — add it to your client so an agent can
run the same loop via the MCP tools. State is shared through the repo so many agents (and
teammates via Jira) coordinate without stepping on each other.

## How it works

rebar stores tickets as an **append-only event log** on a dedicated `tickets` git
orphan branch (worktree at `.tickets-tracker/`); ticket state is computed by replaying
events, and every write auto-commits and pushes so the store is shared immediately. A
**level-triggered reconciler** bidirectionally syncs tickets with Jira. The branch name
and worktree dir are configurable (`tracker.branch` / `tracker.dir` — see
[Configuration](#configuration)). Reads stay sub-second into the thousands of tickets;
for measured numbers and git-growth expectations see
[`docs/scale-envelope.md`](docs/scale-envelope.md).

**Documentation** lives under [`docs/`](docs/README.md) — start with the
[docs index](docs/README.md) (grouped by audience: user / operator / contributor /
agent) or the day-to-day [user guide](docs/user-guide.md).

## Why rebar

If you run coding agents against a repo, you eventually want to run *several* at
once — and the moment you do, they need a shared place to coordinate. Most
trackers weren't built for that:

- **They're heavy.** A daemon to babysit or a local database to keep running,
  with dependencies thick enough that a routine upgrade can break your work
  tracking across machines.
- **They don't travel with the code.** State lives outside the repo, so a fresh
  clone doesn't come with its tickets.
- **They fight your git history.** A tracker that writes to your working branch
  tangles ticket churn into your source-code commits.
- **They have no concurrency story.** Nothing stops two agents from claiming the
  same work or clobbering each other's state, and concurrent edits produce merge
  conflicts you resolve by hand — or lose.
- **They buckle at scale.** Speed and usability fall off past a few hundred
  tickets.

**rebar's answer is to make the tracker part of the repo.** Tickets are an
append-only event log on a dedicated `tickets` orphan branch (linked in through a
gitignored worktree); current state is a fast, deterministic replay of that log.
That single decision pays off across the board:

- **Zero infrastructure, fully portable.** No database, no daemon — just git and a
  lightweight Python install. Clone the repo and the tracker comes with it.
- **No commit interference.** Ticket events live on their own branch and never
  touch your source history. Every write auto-commits and auto-pushes, so activity
  is shared in real time.
- **Concurrency by design.** Each event gets a globally-unique filename, so
  parallel writes merge as a clean union, and the rare conflicting fork resolves
  deterministically — every clone converges with no lost data. `claim` is an
  atomic, optimistic-concurrency primitive: agents grab work without stepping on
  each other.
- **Built to scale.** The event log plus cached replay stays fast as tickets grow.

On top of that foundation, rebar adds what parallel agent work actually needs:

- **Bidirectional Jira sync** — agents work in rebar, teammates work in Jira, and
  a level-triggered reconciler keeps the two in step. To run it **automatically** in
  CI, see [docs/jira-sync-setup.md](docs/jira-sync-setup.md) (the GitHub Actions
  reconcile-bridge + heartbeat-canary setup).
- **Conflict-aware scheduling** — tickets record their file impact, so
  `next-batch` hands parallel agents work that won't collide on the same files.
- **Scratch space** — an invisible per-ticket channel for subagents to pass notes
  to one another.
- **Structural quality gates** — clarity, acceptance-criteria, dispatch-readiness,
  and repo-wide health checks keep work dispatch-ready.
- **LLM review gates** *(optional)* — review an agent's *plan* before work starts,
  its *completion* before the ticket closes, and its *code* before it merges.
  Plan-review and code-review share one four-pass kernel — a finder cites evidence, a
  *separate* verifier tests each claim with atomic yes/no questions, and a
  **deterministic** policy (never the model) decides what blocks — so a review coaches
  with grounded, cited findings rather than a black-box score. A passing plan or
  completion review leaves an HMAC-signed attestation: a machine-checkable signal of
  rigorous agentic development, not vibe-coding.
- **Provenance links** — `discovered_from` ties emergent work back to the ticket
  that surfaced it.
- **One store, three interfaces** — drive it from the CLI, a Python library, or
  the MCP server.

## Requirements

**System prerequisites:**
- [Python](https://www.python.org) ≥ 3.11
- [`git`](https://git-scm.com) — required (the store is a git orphan branch +
  worktree). The engine is pure in-process Python; `bash` and `jq` are **not**
  required at runtime.
- **No external lock binary is required.** Write serialization uses a two-window
  lock built entirely from the Python standard library — a `fcntl.flock(LOCK_EX)`
  advisory lock plus an atomic `mkdir` lock (`src/rebar/_store/lock.py`) — so there
  is **no dependency on util-linux's `flock` binary** (or any other external tool).
  The `mkdir` window keeps mutual exclusion holding even where `fcntl.flock` is
  unreliable (e.g. some network filesystems).
- [`acli`](https://developer.atlassian.com/cloud/acli/) (Atlassian CLI) — only for
  **live** Jira reconciliation.

**Python dependencies.** A base install (`pip install nava-rebar`) — the `rebar`
CLI, the `import rebar` library, and the lean workflow engine — pulls only three
runtime dependencies: [`pyyaml`](https://pyyaml.org) (the workflow DSL loader),
[`jsonschema`](https://python-jsonschema.readthedocs.io) (the schema-registry +
workflow input/output-contract validator), and
[`referencing`](https://referencing.readthedocs.io) (the JSON Schema `$ref`
resolver `jsonschema` builds on); the engine core and reconciler are
otherwise stdlib-only. Everything else is an optional extra, lazy-imported so the
base stays light (CI enforces that):

- **Optional runtime capabilities** — install what you serve:
  - **`[mcp]`** — the [`rebar-mcp` server](https://modelcontextprotocol.io)
    (`mcp>=1.9`).
  - **`[agents]`** — the LLM agent-operations framework + agentic workflow steps
    (`rebar review`, the `code_review` workflow): the provider-agnostic
    [pydantic-ai](https://ai.pydantic.dev) runtime (`pydantic-ai-slim[anthropic]`)
    plus [`json-repair`](https://github.com/mangiucugna/json_repair).
- **Development & authoring extras** — not needed to run or serve rebar:
  - **`[eval]`** — prompt evaluation (`rebar prompt eval`) with
    [Inspect AI](https://inspect.aisi.org.uk); an authoring/CI capability.
  - **`[tracing]`** — an [OpenTelemetry](https://opentelemetry.io) OTLP trace sink
    (write-only; never read back into a rebar decision), for diagnostics.
  - **`[dev]`** — the test/lint/type tooling ([pytest](https://docs.pytest.org),