rebar

rebar

エージェントの群れ向けに構築された、イベントソーシング方式で Git に裏付けられたチケットストア兼 Jira 調整ツールです。1 つのストアを Python ライブラリ、CLI、MCP サーバーとして公開します。

• 3 つのインターフェース、1 つのストア — rebar を CLI（rebar）、Python ライブラリ（import rebar）、または MCP サーバー（rebar-mcp）として利用できます。
• トラッカーはリポジトリ内にあります — チケットは tickets Git ブランチ上の追記専用イベントログです。データベースもデーモンも不要で、クローンのたびに一緒に持ち運べます。
• 並列エージェント向けに構築 — アトミックなクレーム、収束するマージ、来歴リンクにより、多数のエージェントやセッションが作業を失うことなく同時に書き込めます。
• 任意の LLM ゲート — 作業前にチケットの 計画 を、クローズ前に 完了 を、マージ前に コード をレビューできます。
• 双方向 Jira 同期 — レベルトリガー型の調整ツールがチケットと Jira を同期し、チームメイトが状況を把握できます。
• 2 つの独立したゲートで実運用 — rebar 自身の main への変更はすべて、Gerrit で取り込まれる前に、LLM によるコードレビュー と CI の両方を通過する必要があります。

インストール

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

クイックスタート

CLI または Python ライブラリを使って、1 件のチケットを最初から最後まで処理します。JSON ブロックは MCP サーバーの設定で、エージェントは MCP 経由で同じループを実行できます。コマンドの正式なリファレンスは rebar --help（および rebar <command> --help）です。

# CLI: one ticket through init -> create -> ready -> claim -> close
rebar init
tid=$(rebar create task "Add a login page" -o json | python3 -c 'import json,sys; print(json.load(sys.stdin)["id"])')
rebar ready                                              # lists it as ready to work
rebar claim "$tid"                                       # open -> in_progress
rebar transition "$tid" in_progress closed              # in_progress -> closed

import rebar                                            # the same loop via the Python library
tid = rebar.create_ticket("task", "Add a login page")
rebar.claim(tid)
rebar.transition(tid, "in_progress", "closed")

{ "mcpServers": { "rebar": { "command": "uvx", "args": ["--from", "nava-rebar[mcp]", "rebar-mcp"] } } }

ループはこれで完了です。初期化 → 作成 → 準備完了 → クレーム → クローズ。CLI と Python のブロックはそれぞれ、1 件のチケットを最初から最後まで処理します（すべての手順で同じ ID を引き継ぎ、ID のハードコードはありません）。JSON は MCP サーバーの設定です。クライアントに追加すると、エージェントは MCP ツール経由で同じループを実行できます。状態はリポジトリを通じて共有されるため、多数のエージェント（および Jira 経由のチームメイト）が互いの作業を妨げずに連携できます。

動作の仕組み

rebar は、専用の tickets Git オーファンブランチ（.tickets-tracker/ にあるワークツリー）上に、追記専用イベントログとしてチケットを保存します。チケットの状態はイベントを再生して計算され、書き込みのたびに自動でコミットおよびプッシュされるため、ストアはすぐに共有されます。レベルトリガー型の調整ツールが、チケットと Jira を双方向に同期します。ブランチ名とワークツリーディレクトリは設定可能です（tracker.branch / tracker.dir — 設定を参照）。チケットが数千件に達しても、読み取りはサブ秒で完了します。実測値と Git の増加に関する見通しについては、docs/scale-envelope.mdを参照してください。

ドキュメントは docs/ にあります。対象者別（ユーザー／運用担当者／コントリビューター／エージェント）に分類されたドキュメント索引、または日常的な作業向けのユーザーガイドから始めてください。

rebar を選ぶ理由

リポジトリに対してコーディングエージェントを実行するなら、いずれは 複数 を同時に実行したくなります。そうなると、エージェントが連携するための共有の場所が必要です。しかし、ほとんどのトラッカーはその用途を想定して作られていません。

• 動作が重いです。 常に気を配る必要のあるデーモンや、稼働させ続けるローカルデータベースが必要で、依存関係も複雑なため、定期的なアップグレードでマシン間の作業追跡が壊れることがあります。
• コードと一緒に持ち運べません。 状態がリポジトリの外に保存されるため、新しくクローンしてもチケットは付いてきません。
• Git の履歴と競合します。 作業ブランチに書き込むトラッカーでは、チケットの頻繁な変更がソースコードのコミットに入り込みます。
• 並行処理への対応がありません。 2 つのエージェントが同じ作業を取得したり、互いの状態を上書きしたりするのを防げません。また、編集が並行するとマージコンフリクトが発生し、手作業で解決するか、変更を失うことになります。
• 規模が大きくなると行き詰まります。 チケットが数百件を超えると、速度と使いやすさが低下します。

rebar は、トラッカーをリポジトリの一部にすることでこれらを解決します。 チケットは専用の tickets orphan ブランチ（gitignore 対象の worktree からリンク）に追記専用のイベントログとして保存され、現在の状態はそのログを高速かつ決定論的にリプレイして得られます。この 1 つの判断が、あらゆる面で効果を発揮します。

• インフラ不要で、完全に持ち運び可能です。 データベースもデーモンも不要で、必要なのは git と軽量な Python のインストールだけです。リポジトリをクローンすれば、トラッカーも一緒に取得できます。
• コミットに干渉しません。 チケットのイベントは専用ブランチに保存され、ソースコードの履歴には一切触れません。書き込みはすべて自動でコミットおよびプッシュされるため、アクティビティはリアルタイムで共有されます。
• 並行処理を前提に設計されています。 各イベントにはグローバルに一意なファイル名が付くため、並行する書き込みはクリーンな和集合としてマージされ、まれに競合するフォークが発生しても決定論的に解決されます。データが失われることなく、すべてのクローンが同じ状態に収束します。claim はアトミックな楽観的並行制御プリミティブであり、エージェントは互いの作業を妨げずに作業を取得できます。
• 拡張性を考慮して構築されています。 イベントログとキャッシュされたリプレイにより、チケットが増えても高速さを保ちます。

この基盤に加えて、rebar はエージェントが並行して作業する際に実際に必要となる機能を提供します。

• Jira との双方向同期 — エージェントは rebar で作業し、チームメイトは Jira で作業します。レベルトリガー型のリコンサイラーが両者を同期します。CI で自動的に実行する方法については、docs/jira-sync-setup.md（GitHub Actions の reconcile-bridge + heartbeat-canary のセットアップ）を参照してください。
• 競合を考慮したスケジューリング — チケットに影響するファイルが記録されるため、next-batch は同じファイルで衝突しない作業を並行するエージェントに割り当てます。
• スクラッチ領域 — サブエージェントが互いにメモを渡すための、チケットごとの非表示チャネルです。
• 構造に基づく品質ゲート — 明確さ、受け入れ基準、ディスパッチ準備状況、およびリポジトリ全体の健全性をチェックし、作業をディスパッチ可能な状態に保ちます。
• LLM レビューゲート (任意). 作業開始前にエージェントの計画を、チケットを閉じる前に完了内容を、マージ前にコードをレビューできます。計画レビューとコードレビューでは、共通の 4 パスカーネルを使用します。検出器が根拠を提示し、独立した検証器がそれぞれの主張を、アトミックな「はい」または「いいえ」の質問で検証します。何をブロックするかは決定論的なポリシーによって判断されます。計画または完了のレビューに合格すると、DSSE エンベロープとして操作証明書が記録されます。このエンベロープには、署名環境の Ed25519 キーで生成された、PAE バイトに対する SSHSIG 署名が含まれます。証明書では、その環境がプリンシパルとして指定されます。この結果、レビュー対象の作業について機械的に検証可能なプロセス記録が得られます。
• 来歴リンク — discovered_from により、新たに発生した作業を、それを表面化させたチケットに結び付けます。
• 1 つのストア、3 つのインターフェース — CLI、Python ライブラリ、または MCP サーバーから操作できます。

要件

システム要件：

• Python ≥ 3.11
• git は実行時の前提条件です。ストアが Git の orphan ブランチと worktree を使用するためです。実行エンジンは Python のインプロセス処理を使用し、bash や jq は必要ありません。
• 開発、テスト、CI には Git 2.38 以降が必要です。最低バージョンは .github/git-version-floor.txt で宣言されています。Git がその最低バージョンに満たない場合、テストスイートと CI は失敗します。
• オプションの S3 修復パスを使用するデプロイには、Git 2.38 以降が必要です。このパスでは git merge-tree --write-tree を実行するためです。
• 外部ロックバイナリは必要ありません。 書き込みの直列化には、Python 標準ライブラリのみで構成した二段階のロックを使用します。fcntl.flock(LOCK_EX) によるアドバイザリロックと、アトミックな mkdir ロック（src/rebar/_store/lock.py）を組み合わせているため、util-linux の flock バイナリ（またはその他の外部ツール）には依存しません。 mkdir のロックにより、fcntl.flock の信頼性が低い環境（特定のネットワークファイルシステムなど）でも相互排他が維持されます。
• acli（Atlassian CLI） — Jira Cloud の調整／ブリッジパスで必須となる外部バイナリです。Cloud への変更を伴う bridge／reconcile はすべてこれを呼び出すため、PATH にインストールする必要があります（インストール手順：docs/jira-sync-setup.md）。[jira-datacenter] の Data Center パスでは不要です。こちらは jira Python ライブラリを使用します。

Python の依存関係。 基本インストール（pip install nava-rebar）では、rebar CLI、import rebar ライブラリ、軽量なワークフローエンジンが提供されます。ワークフロー DSL ローダー用の pyyaml>=6、スキーマレジストリとワークフロー入出力の検証用の jsonschema>=4.18、JSON Schema の $ref 解決用の referencing>=0.30 がインストールされます。それ以外では、エンジンのコアと調整機能は Python 標準ライブラリを使用します。その他の依存関係はすべてオプションの追加機能として提供され、基本インストールを軽量に保つため、必要に応じて遅延インポートされます。CI ではこの境界を検証します。

• オプションの実行時機能 — 提供する機能に応じてインストールしてください。
  • [mcp] は mcp>=1.28.1,<2 と pyjwt[crypto]>=2.10,<3 を使用する rebar-mcp サーバーをインストールします。
  • [agents] — LLM エージェント運用フレームワークとエージェント型ワークフローのステップ（rebar review-plan、code_review ワークフロー）：プロバイダーに依存しない pydantic-ai ランタイム（pydantic-ai-slim[anthropic]）と json-repair。
• 開発およびオーサリング用の追加機能 — rebar の実行や提供には不要です。
  • [tracing] — 診断用の OpenTelemetry OTLP トレースシンクです（書き込み専用で、rebar の判断に読み戻されることはありません）。
  • [dev] — テスト／lint／型チェック用ツール（pytest、ruff、mypy、hatchling）。pip install -e '.[dev]' では [agents] も自己参照するため、検証テストがスキップされずに実行されます。また、テストスイート全体の実行に必須です（インターフェースの同等性テストでは MCP サーバーをインポートするため、mcp がない場合はスキップされずエラーになります）。

インストールとテストを参照してください。

インストール

rebar は単一の Python パッケージ（PyPI ディストリビューション nava-rebar）として提供されます（インポートパッケージとコマンド名は引き続き rebar／rebar-mcp です）。用途に合ったチャンネルを選んでください。（いずれの場合もシステム要件は、git（rebar の開発／テストには ≥ 2.38。詳細は要件を参照）と python3（≥ 3.11）です。書き込みの直列化には、外部バイナリを必要としない組み込みの fcntl.flock と mkdir によるロックを使用します。Jira Cloud の調整／ブリッジパスでは、acli を PATH にインストールする必要があります（docs/jira-sync-setup.md を参照）。一方、[jira-datacenter] の Data Center パスでは不要です。）

Homebrew（CLI）

brew install navapbc/rebar/rebar
# or: brew tap navapbc/rebar && brew install rebar

rebar CLI（および数式の venv 内の rebar ライブラリ）をインストールします。Homebrew 経由で MCP サーバーを利用する場合は、以下の pipx/uvx を使って [mcp] エクストラをインストールしてください。

PyPI — pipx / pip

ランタイム（本番環境）— 実際に使用するものをインストールします：

pipx install nava-rebar              # isolated CLI on PATH: rebar (+ lean workflow engine)
pip  install nava-rebar              # library: import rebar  (runtime deps: pyyaml, jsonschema, referencing)
pip  install 'nava-rebar[mcp]'       # + MCP server: rebar-mcp
pip  install 'nava-rebar[agents]'    # + LLM agent ops + agentic workflow steps (rebar.llm)
pip  install 'nava-rebar[tracing]'   # + OTLP trace sink (write-only)
pip  install 'nava-rebar[agents,tracing]'        # the union, if you want it all

基本インストールでは、追加のエクストラなしでスクリプトベースのワークフロー（rebar workflow new/validate/show/run）を実行できます。エージェント型のワークフローステップと rebar review-plan には [agents] が必要です。エンジンの用途、つまりワークフローを作成する場合と独自の op を作成する場合の使い分け、YAML DSL、3 パスのレビュー方式、プロンプトライブラリと評価の接点については、docs/workflow-engine.md を参照してください。

[agents] エクストラは、省略可能なLLM エージェント操作フレームワーク（rebar.llm）を追加します。ライブラリ、CLI、MCP インターフェースを通じてチケットとコードをレビューする、ツールを使用するエージェントを提供します。モデルクラスは [tool.rebar.llm.model_classes] または REBAR_LLM_<CLASS>_MODEL、REBAR_LLM_MODEL_PROVIDER、REBAR_LLM_BASE_URL で設定します。単一の REBAR_LLM_MODEL 変数は非推奨です。詳しくは docs/llm-framework.md を参照してください。

[agents] エクストラは、Claude に使用する Anthropic プロバイダーをインストールします。Bedrock には nava-rebar[agents,bedrock] が必要です。ChatGPT と OpenAI 互換のエンドポイントには、[agents] と pydantic-ai-slim[openai] が必要です。Gemini には、[agents] と pydantic-ai-slim[google] が必要です。エージェント操作を使用しない限り、rebar コアが LLM スタックを必要としたり、インポートしたりすることはありません。

MCP サーバー — MCP Registry から

MCP Registry に io.github.navapbc/rebar として登録されています。Registry 対応の MCP クライアントでは、この名前を指定して追加できます。または、クライアント設定に直接登録できます（uvx を使えば事前インストールは不要です）：

{
  "mcpServers": {
    "rebar": {
      "command": "uvx",
      "args": ["--from", "nava-rebar[mcp]", "rebar-mcp"],
      "env": { "REBAR_ROOT": "/path/to/your/repo" }
    }
  }
}

（すでに nava-rebar[mcp] を pip/pipx でインストール済みの場合は、代わりに "command": "rebar-mcp" を使用してください。）サーバーフラグ：REBAR_MCP_READONLY=1 を設定すると、読み取りツールのみが公開されます。変更を伴うブリッジツール（bridge_run、bridge_sync、bridge_pause、bridge_resume）には REBAR_MCP_ALLOW_JIRA_SYNC=1 が必要です。どちらのフラグも、大文字と小文字を区別しない任意の真値を受け付けます — 1、true、yes（前後の空白は許容されます）。それ以外（未設定を含む）は無効です。

プライベートリポジトリの取得認証情報（コード読み取りゲート）

LLM によるコード読み取りゲート review_plan、verify_completion、review_code、scan_spec は、デフォルトでアテステーションモードになります。これらは origin から選択した ref を取得し、ピン留めされた SHA の不変スナップショットを読み取ります。REBAR_ROOT がプライベートリポジトリを指すサーバーでは、Git 認証情報ヘルパー、デプロイキー、またはサーバーのクローン内のトークンを使った読み取り認証情報が必要です。認証情報がない場合、アテステーションモードは修正方法のメッセージを表示してフェイルクローズし、GIT_TERMINAL_PROMPT=0 によってターミナルでのプロンプト表示を無効にします。source=local は取得を行わず、現在のチェックアウトを読み取り、結果に署名することもありません。スナップショットガイドでは、これらの仕様、環境の Ed25519 キーを使って PAE バイト列に対する SSHSIG 署名を付与した DSSE エンベロープの操作証明書の信頼モデル（各証明書はその環境に帰属します）、一時ストレージ、ディスク容量のしきい値、EFS または NFS のロック設定について説明しています。

ソースから

git clone https://github.com/navapbc/rebar && cd rebar
pip install .              # library + CLI (runtime deps: pyyaml, jsonschema, referencing)
pip install '.[mcp]'      # + MCP server (FastMCP)
# Developing rebar itself — the full dev environment (test/lint/type tooling +
# the agents stack so the LLM validation tests RUN, not skip), installed through
# the committed uv.lock (or `make install`, which adds the pre-commit gate):
uv sync --extra dev

pipx によるソースインストールと古い uv。 pipx install "<path>[agents]" が pipx needs uv>=0.9.17 と表示されて rebar のインストール前に停止する場合、 古いホスト uv が選択されています。pipx の pip バックエンドを使って、 同じソースインストールを再試行してください。

pipx install --backend pip "<path>[agents]"

これはホストの pipx/uv ツールチェーンの不整合であり、rebar のパッケージングの不具合ではありません。

変更に貢献しますか？ GitHub は読み取り専用ミラーです。main は Gerrit の 2 票による承認ゲート（LLM-Review + Verified/CI）を通じてのみ更新されます。初めて貢献する方は、 まず分かりやすい手順書 docs/your-first-change.md をご覧ください。詳しい リファレンスは CONTRIBUTING.md にあります（Gerrit からクローンし、 refs/for/main にプッシュし、両方の票が通ったら Gerrit で通常の Submit を実行して取り込みます。main は Rebase-If-Necessary なので、Gerrit が最新のコミットにリベースし、サーバー側で取り込みます）。

パッケージングに関する注意 — rebar がディスクに展開されてインストールされる理由。 ライブラリ、CLI、 MCP サーバー、および読み書きコア全体は Python のプロセス内で実行されます。サブプロセスとして実行される コンポーネントは、Jira のリコンシリエーター処理（python -m rebar.reconciler）だけです。jira-capability-probe.py スクリプトとエイリアス単語リストは、 パッケージのデータとして src/rebar/_engine/ に含まれ、実際のディスク上のファイルから起動・ 読み込みされるため、パッケージはディスク上の実ディレクトリに展開してインストールする必要があり、 zipimport / zip セーフなバンドル（zipapp、shiv、 PEX、Lambda の zip）はサポートされていません。標準的なインストール方法はすべてこの要件を満たします。 pip/pipx の wheel（hatchling は展開形式でビルドします）、編集可能インストール、Homebrew はいずれも実ファイルを配置します。 engine_dir() は最初のリコンシリエーター呼び出し時にエンジンディレクトリがディスク上にあることを検証し、 ない場合は明確なエラーで失敗します。

上級者向け（任意）— セルフホストのコードレビューでコミットをゲートする。 通常の rebar の利用には必要ありません。 main へのすべてのコミットが取り込まれる前に自動で LLM レビューを受けるようにしたい場合は、 AWS 上で Gerrit と rebar のレビューボットをセルフホストできます（このボットは MCP サーバーが公開するものと同じ rebar.llm レビューカーネルをインポートします）。そのうえで GitHub を読み取り専用ミラーにし、 LLM-Review の票が通った後に限り Gerrit 経由で更新します。サーバーのセットアップについては docs/gerrit-aws-setup.md をご覧ください。(このリポジトリはまさにこの構成で運用されています。上記の貢献者向けの注意と CONTRIBUTING.md をご覧ください。)

CLI

すべてのサブコマンドを網羅した、常に最新の完全なコマンドリファレンスは、docs/cli-reference.md を参照してください。CLI 自身のヘルプデータから生成されています。基本的な使い方は、rebar init → rebar create <type> "<title>" → rebar ready → rebar claim <id> → rebar transition <id> <current> <target> です。

サブコマンドの概要を確認するには、rebar help、rebar --help、または rebar -h を実行してください。特定のサブコマンドについて確認するには、rebar <subcommand> --help または rebar help <subcommand> を実行してください。末端のコマンドでは、-- より前の任意の位置に正確な --help または -h トークンがあると、コマンドを実行せずに使用方法が表示されます。ネストされたコマンド群では、引き続き子コマンドへのルーティングが行われます。先頭のヘルプフラグはコマンド群のヘルプを表示しますが、rebar bridge preview --help や rebar audit show --help のような形式では、子コマンドのヘルプが表示されます。

リポジトリのルートは REBAR_ROOT から解決されます。設定されていない場合は、作業ディレクトリの git トップレベルが使用されます。

構造化出力。 データを返すすべてのコマンドは、標準の --output json フラグ（短縮形は -o json）で機械可読な JSON を出力します。--output llm を指定すると、show／list／ready 向けにトークン数を抑えた形式が出力されます。それぞれ異なる JSON 形式は JSON Schema で文書化され、CI で CLI、ライブラリ、MCP 全体にわたって検証されます。コマンドごとの仕様とスキーマの信頼できる参照元については、docs/output-schemas.md を参照してください。

作業の割り当て。 rebar claim <id> は、オープンなチケットを in_progress にアトミックに移行します。--assignee を省略すると、claim は ticket.default_assignee を使用します。明示的に指定した --assignee はその設定を上書きし、Jira で解決可能なメールアドレスまたは accountId である必要があります。

validate によるリポジトリ全体の健全性チェック。 rebar validate にはチケット ID を指定しません。ストア全体をスキャンし、重大／大／小／警告の指摘事項に分類されたトラッカー全体の健全性スコア（1～5、終了コード 0～4）を出力します（--output json、--terse、--verbose）。チケット ID を渡すとエラーになります。（rebar には、<id> を指定してチケットがディスパッチ可能な作業として適切な構造になっているかを検証する、チケットごとの構造ゲートもあります。すべてのタイプで ## Acceptance Criteria チェックリストが必要です。チケットテンプレートとゲートのリファレンスについては、docs/plan-review-criteria-guide.md を参照してください。）

作業のクローズ。 rebar transition <id> in_progress closed は、タスク、バグ、ストーリー、またはエピックをクローズします。バグをクローズする場合は、--class も必要です。完了検証は任意で、デフォルトでは無効です。verify.require_completion_verification_for_close = true を設定すると、通常の作業チケットをクローズするたびに、ステータス変更が記録される前に検証が実行されます。

リンク。 rebar link <id1> <id2> <relation> では、7 種類の関係のいずれかを指定する必要があります。blocks、depends_on、relates_to、duplicates、supersedes、discovered_from、caused_by です。rebar unlink <source> <target> [relation] では、関係の指定は任意です。関係を指定しない場合、同じ順序のペアに対して最近作成された有効なリンクが削除されます。関係を指定すると、その関係だけが削除され、ペア間のほかの関係は保持されます。ブロッキングリンクは作成時に親階層へ昇格される場合があるため、unlink では昇格後の祖先側エンドポイントを指定する必要があります。

プランレビューまたは完了検証に合格すると、操作証明書が記録されます。この証明書は DSSE エンベロープであり、署名環境の Ed25519 キーで生成された、PAE バイト列に対する SSHSIG 署名を含みます。そのプリンシパルは、その環境を識別します。コードレビューゲートはレビューシステムを通じて判定を報告し、このチケット証明書は作成しません。rebar sign コマンドとライブラリのインターフェイスでは、これら 2 つのゲート以外でもマニフェスト証明書を添付できます。docs/manifest-signing.md を参照してください。

ブロッキングリンクの階層昇格

ブロッキングの依存関係（blocks、depends_on）に限り、rebar はリンクの両端を親階層に昇格させ、同程度の階層にあるチケット間（エピック↔エピック、ストーリー↔ストーリー、タスク／バグ↔タスク／バグ）に依存関係を設定します。その際、REDIRECT: A→B promoted to … という注記を出力します。ブロッキング以外の関係（relates_to、duplicates、supersedes、discovered_from、caused_by）は、昇格せず、指定どおりにリンクします。

ストアは書き込みのたびに自動コミットし、自動プッシュします

rebar のすべての書き込み（create、edit、transition、claim、link、…）は、そのイベントを tickets ブランチに自動コミットし、origin リモートがある場合はそのブランチを origin/tickets に自動プッシュします。そのため、ローカルのチケット操作は直ちにリモートと共有されます。テスト用／作業用のチケットも含まれるため、tickets リモートを共有しているリポジトリで作業する際は注意してください。プッシュはベストエフォートです。origin リモートがなければ何もプッシュされず、プッシュに失敗しても（自動マージできない non-fast-forward やネットワーク接続がない場合など）、書き込み自体は失敗しません。その場合、ローカルコミットは保持され、ブランチは分岐した状態になります。ローカルの tickets ブランチが origin/tickets より先行している場合、rebar store fsck は PUSH_PENDING を報告するため、未プッシュの操作を確認できます。プッシュ／マージ再試行のアルゴリズムについては、docs/concurrency.md を参照してください。

ローカル、オフライン、または読み取り専用での実行。 ストアからリモートに接続させたくない場合、この自動同期は設定で変更できます（設定キーと環境変数名の一覧は docs/config.md を参照してください）。

• sync.push（環境変数 REBAR_SYNC_PUSH） — always（デフォルト）は各書き込みを同期的にプッシュします。async はバックグラウンドでプッシュするため、書き込みごとのネットワーク遅延によって一括処理が直列化されません。off はコミットをローカルに保持し、プッシュしません（fsck は引き続き PUSH_PENDING を表示します）。
• sync.pull（環境変数 REBAR_SYNC_PULL） — on（デフォルト）はリモートからのフェッチを読み取りに許可します（下記の鮮度ポリシーを参照してください）。off は完全にローカルでのリプレイを行います（オフライン作業、頻繁なループ処理、または同期済みの書き込み直後など）。同じ効果を得るには、単一の読み取りサブコマンドに --no-pull を渡してください（例：rebar list --no-pull）。
• mcp.readonly（環境変数 REBAR_MCP_READONLY=1） — MCP 経由で読み取りツールのみを提供するため、書き込みは発生せず、コミットもプッシュも行われません。

どれほどの規模まで対応できるでしょうか？チケット数が数千件になっても、読み取りは1秒未満です。書き込み速度はイベントごとの git コミットによって制限されます（約25～30件／秒）。実測値の例、git の増大に関する予測、圧縮／メンテナンス用コマンドについては docs/scale-envelope.md を、一括 NDJSON エクスポート／インポートについては docs/import-export.md を参照してください。

CLI、ライブラリ、MCPで読み取り時の鮮度ポリシーを統一

すべての読み取り（show、list、ready、search、deps）では、まず頻度を制限した（1分に1回以下）ベストエフォートの git fetch と、ローカルの tickets ブランチと origin/tickets の再収束を行います。そのため、読み取り結果には最大1分以内に共同作業者のプッシュが反映されます。これは、CLI、ライブラリ（rebar.list_tickets()、…）、MCP の読み取りツールの3つのインターフェースすべてに共通する単一の契約です。すべてが1つの読み取り実装を経由します。（以前は CLI の読み取りだけが同期していたため、主要なエージェント向けインターフェースである MCP の読み取りが最も古い状態になる問題がありましたが、こうした不一致は解消されています。）完全にローカルでのリプレイを行うためにこのフェッチを省略するには、sync.pull=off を設定するか、--no-pull を渡してください。上記のローカル、オフライン、または読み取り専用での実行を参照してください。影響を受けるのはネットワーク経由のフェッチ／マージのみです。ローカルの reduce／キャッシュ処理は変わりません。詳細については docs/concurrency.md を参照してください。

オンディスクストアは人間が読める形式ではありません — rebar で読み取ってください

tickets ブランチは、rebar の内部ストレージ形式であり、人が読むためのドキュメントではありません。各チケットは、追記専用の JSON イベントファイル（${hlc}-${uuid}-${TYPE}.json）で構成されるディレクトリです。チケットの現在の状態は、これらのイベントをリデューサーで再生して得られます。ここから、次の 2 つのことが分かります。

• **順序どおりには並んでいません。**イベントファイル名には Hybrid Logical Clock と UUID が使われ、クローン間では和集合としてマージされます。そのため、1 つのチケットのファイルは上から下へ読める物語ではなく、リデューサーが並べ替えて畳み込んで初めて意味を持つ、順序のない集合です。単独の EDIT／STATUS／TAG_DELTA ファイルから分かるのは差分であり、チケットそのものではありません。
• **現在の状態は計算されるものであり、保存されていません。**ブランチ上でコンパイル済みの「現在の」チケットを保持するものは、ローカルにある再構築可能な .cache.json（gitignore 対象）だけです。生ファイルを手作業で読むと誤解を招きます。後のイベントが前のイベントを上書きする場合があり、SNAPSHOT が多数のイベントを畳み込む場合もあります。また、並行するフォークは決定論的なルールで解決されるため、自分で適用する必要があります。

そのため、チケットの状態を確認するために .tickets-tracker/ ワークツリーを cat しないでください。代わりに、リデューサーを実行する読み取りコマンドを使ってください。CLI では rebar show <id>、rebar list、rebar deps <id>、rebar search <query>、ライブラリでは対応する呼び出し（rebar.show_ticket(...)）、または MCP 読み取りツールを使います。

参考として、docs/sample-ticket-log.jsonl は、基礎となるデータの実際の形式を示す小さな合成イベントログ（1 行につき 1 イベント）です。2 つのエージェントが扱うエピックと子チケットを通じて、作成／クレーム／コメント／リンク／タグ／ファイルへの影響／署名／遷移を実例で示しています。行は意図的にタイムスタンプ順ではありません。それが要点です。イベント本体のスキーマは docs/event-schema.md に記載されています。

Python ライブラリ

import rebar

rebar.init_repo(repo_root="/path/to/repo")
tid = rebar.create_ticket("story", "Add login page", priority=2)
ticket = rebar.show_ticket(tid)                 # TicketState
tickets = rebar.list_tickets(status="open")     # list[TicketState]
try:
    rebar.transition(tid, "open", "in_progress")
except rebar.ConcurrencyError:
    ...                                          # ticket changed since last read

preview = rebar.bridge_preview(only=[tid])       # typed, non-mutating Jira plan
run = rebar.bridge_run(profile="dry-run")         # captured scheduled-run result; prints nothing
sync = rebar.bridge_sync(max_changes=10)         # typed, explicitly mutating sync
status = rebar.bridge_status(max_age_seconds=3600)
# Durable operator controls and the live six-step capability check:
rebar.bridge_pause("maintenance")
rebar.bridge_resume()
access = rebar.bridge_check_access()

# Legacy reconcile(mode=...) is not a Python API; use explicit bridge operations.
audit = rebar.bridge_fsck()                       # offline bridge audit

# Sign a DSSE operation certificate by applying SSHSIG to its PAE bytes with the environment's Ed25519 key and principal.
rebar.sign_manifest(tid, ["unit tests: PASS", "security review: clean"])
verdict = rebar.verify_signature(tid)            # {"verified": True, "verdict": "certified", ...}

# Native, in-process reads (no subprocess):
from rebar import reduce_all_tickets, reduce_ticket

**型付き戻り値の契約。**スキーマに基づく rebar.* 関数には、rebar.types の TypedDict（例：TicketState、TransitionResult、ClaimResult）で型注釈が付けられているため、型チェッカーは戻り値にどのキーが含まれるかを把握できます。これらは正規の JSON Schema から生成され、保証されるキーを記述します。戻り値は通常の dict のままで、実行時の形状は拡張可能です（追加のキーが含まれる場合があります）。つまり、これは最低限の保証であり、閉じた集合ではありません。型注釈や TypedDict へのアクセスには、次のようにインポートしてください。

from rebar.types import TicketState, TransitionResult

t: TransitionResult = rebar.transition(tid, "open", "in_progress")

安定した例外インターフェース。rebar.RebarError（基底クラス）と、そのサブクラスである rebar.ConcurrencyError が公開例外です。RebarError には .returncode（基盤エンジンの終了コード）と .stderr が含まれます。ConcurrencyError（終了コード 10）は、ステータスに依存する操作（transition／claim／reopen）で楽観的同時実行制御の競合に負けたことを意味します。再読み込みして再試行し、強制実行はしないでください。すべての rebar の失敗を一律に処理するには、RebarError を捕捉してください。

**依存しても安定しているもの。**rebar のバージョンは 0.x です。CLI、--output json スキーマ、rebar.* ファサード、MCP ツール、イベントのワイヤ形式、設定キーそれぞれの安定性マトリックスと、「1.0 より前に変更される可能性がある」の意味については、docs/api-stability.md を参照してください。

MCP サーバー

rebar-mcp          # stdio transport

チケット操作を MCP ツールとして公開します。ゲートの段階（読み取り専用／LLM ゲート／書き込みゲート）ごとにまとめた完全なツールリファレンスは、docs/mcp-reference.md を参照してください（サーバー自身のレジストラーから生成されています）。明示的な bridge_preview、bridge_run、bridge_sync、bridge_status、bridge_pause、bridge_resume、bridge_check_access、bridge_fsck ツールを使用してください。以前の MCP reconcile(mode=...) 互換ツールは、現在は登録されていません。run/sync/pause/resume には REBAR_MCP_ALLOW_JIRA_SYNC=1 が必要です。REBAR_MCP_READONLY=1 を設定すると、すべての変更操作がブロックされます。MCP クライアントに登録する方法（レジストリ名 io.github.navapbc/rebar、または直接 uvx を使用する設定）については、上記のインストール → MCP サーバーを参照してください。

**メンテナー向け：**レジストリマニフェストは server.json にあります。mcp-publisher CLI を使って公開／更新してください（docs/releasing.md を参照）。レジストリは、次のアノテーションを使って PyPI パッケージの所有権を検証します（PyPI の長い説明文となるこの README に記載されています）。

mcp-name: io.github.navapbc/rebar

ライセンス

Apache-2.0 — LICENSE を参照してください。

設定

rebar は、pyproject.toml の [tool.rebar] または単独の rebar.toml（上位ディレクトリをたどって最も近いものを使用し、.git で探索を停止）から TOML 設定を読み込みます。見つからない場合は、ユーザー設定 ~/.config/rebar/config.toml にフォールバックします（$XDG_CONFIG_HOME を尊重します）。優先順位は高い順に、rebar -c SECTION.KEY=VALUE／CLI フラグ > REBAR_<SECTION>_<KEY> 環境変数 > プロジェクト設定 > ユーザー設定 > 組み込みのデフォルト値です。rebar config は、解決された値と、それぞれの値がどのレイヤーに由来するかを表示します。

[tool.rebar]
verify.require_completion_verification_for_close = true  # gate work-ticket close on a PASS
                                           # completion verdict (signed onto the ticket);
                                           # fail-closed. Default false.
ticket.display_mode = "auto"               # auto | canonical | alias | short
compact.threshold   = 10
sync.push = "always"                       # always | async | off
sync.pull = "on"                           # on | off
mcp.readonly = false
scratch.base_dir = ""                      # default <repo>/.rebar/scratch
tracker.dir    = ".tickets-tracker"        # store worktree/symlink dir (env REBAR_TRACKER_DIR)
tracker.branch = "tickets"                 # orphan branch the event log lives on (env REBAR_TRACKER_BRANCH)

キーの全一覧、REBAR_<KEY> 環境変数名、非推奨のエイリアスについては、docs/config.md を参照してください。

クローズゲートが有効な場合、クローズへの遷移時に、選択したコード参照に対して完了検証を実行します。検証に合格すると、操作証明書の DSSE エンベロープを記録します。このエンベロープには、署名環境の Ed25519 キーで生成された、PAE バイト列に対する SSHSIG 署名が含まれます。証明書のプリンシパルは、その環境を識別します。検証済みのコードに変更があった場合は、遷移を再度実行してください。--force=<reason> を指定するとゲートをバイパスし、証明書は記録されません。

rebar は、リポジトリのルートにある .rebar/ 以下に書き込み可能な状態を保持します。scratch ストアのデフォルトは <repo>/.rebar/scratch/ です（scratch.base_dir／REBAR_SCRATCH_BASE_DIR で上書きできます）。一度限りの移行スタンプも .rebar/ 以下に書き込まれます。

テスト

[dev] エクストラをインストールした環境（venv を推奨）からテストスイートを実行してください。インターフェースのパリティテストは MCP サーバーをインポートするため、mcp エクストラのない素のインタープリターではスキップされず、エラーになります。

uv sync --extra dev && source .venv/bin/activate  # locked install: pytest, mcp, ruff, mypy
pytest -m "not integration"                   # the single entry point (CI runs this)
pytest tests/interfaces                       # interface-parity tier only
pytest tests/scripts                          # engine/reconciler tier only

pytest が唯一のエントリーポイントです。エンジンはプロセス内で動作する純粋な Python です（bash エンジンとその .sh テストスイートは、bash から Python への移行で削除されました。docs/bash-migration.md を参照してください）。CI（.github/workflows/test.yml）では、プッシュおよび PR ごとに、Ubuntu と macOS で pytest -m "not integration" を実行します。integration ティア（稼働中の Jira／ネットワークを使用）はデフォルトの実行から除外されています。認証情報を指定して pytest -m integration を実行すると、明示的に実行できます。

Python テストスイートは、対象ごとに分かれています。

• tests/scripts、tests/unit — プロセス内エンジン（reducer、graph、reconciler）。
• tests/interfaces — git を基盤とする単一のストアで、ライブラリ、CLI、MCP の各インターフェースが同一に動作することを検証します。
  • test_parity.py は、3 つすべてのインターフェースで各操作を実行します（インターフェース間の整合性チェックも実施します。1 つのインターフェースで書き込み、他のインターフェースで読み取ります）。
  • test_surface.py は、インターフェースごとの機能範囲を固定します（例：MCP に init はなく、classify もありません）。
  • test_library.py／test_cli.py／test_mcp.py は、各インターフェース固有の動作（型付き例外、終了コードの受け渡し、読み取り専用／ライブゲート）をテストします。