autonomous-dispatcher

自律型開発チームのディスパッチャー

GitHub の Issue をスキャンし、開発・レビューのタスクをディスパッチします。cron の 1 回の実行は、dispatcher-tick.sh（単一プロジェクト）または dispatcher-multi-tick.sh（複数プロジェクト）の 1 回の呼び出しに相当します。完全なステートマシン、各ステップの動作、各種不変条件は、ソースリポジトリの docs/pipeline/ に記載されています。これが仕様であり、このファイルはエージェントの呼び出し方法を定めるものです。

前提条件

• gh と jq が PATH に設定されていること。
• ローカルバックエンドの場合：$PROJECT_DIR を設定し、プロジェクトのルートを指定していること。プロジェクトごとの autonomous.conf を参照してください（scripts/autonomous.conf.example）。
• 複数プロジェクト／リモートバックエンドの場合：PROJECTS=() を宣言する dispatcher.conf を用意すること（scripts/dispatcher.conf.example）。
• autonomous-dev.sh と autonomous-review.sh に実行ビット（モード 100755）が設定されていること。上流で修正済みであり、dispatcher-tick.sh が毎回の実行時に自動修復します（#97）。

セキュリティに関する注意：このディスパッチャーは、GitHub Issue の内容を入力として処理します。公開リポジトリでは、誰でも Issue を作成できるため、Issue の内容は信頼できないものとして扱われます。autonomous ラベルを適用できるのは、信頼できるメンテナーだけであることを確認してください（GitHub のブランチルールセットまたは組織のポリシーを使用してください）。ディスパッチャーはラベル／コメントを読み取り、ヘルパースクリプトを介してローカルプロセスを起動するだけです。ソースコードを変更したり、ブランチにプッシュしたりすることはありません。

実行内容

cron が実行されたら（デフォルト：5 分ごと）、次のいずれかを 1 つ 実行します。

単一プロジェクトのデプロイ（ディスパッチャー 1 つにつきリポジトリ 1 つ）：

bash "$PROJECT_DIR/scripts/dispatcher-tick.sh"

複数プロジェクトのデプロイ（cron 1 つで複数のリポジトリを処理 — #62 を解決）：

DISPATCHER_CONF="$HOME/.autonomous/dispatcher.conf" \
  bash "$PROJECT_DIR/scripts/dispatcher-multi-tick.sh"

複数プロジェクト用のラッパーは、dispatcher.conf の PROJECTS=() を順に処理し、プロジェクトごとに dispatcher-tick.sh を 1 回実行します。プロジェクトごとの失敗は stderr に記録されますが、ほかのプロジェクトの処理は停止しません。スキーマについては scripts/dispatcher.conf.example を参照してください。

PROJECTS[] の各エントリーは、次の 2 つの形式のいずれかです。

• ローカルプロジェクト（ファイルパス）：このディスパッチャーのマシン上にある、プロジェクトごとの autonomous.conf へのパスです。ディスパッチャーとプロジェクトのソースは同じマシンにあります。ラッパーは、優先順位 1 の AUTONOMOUS_CONF パス（PR-4／[INV-14]）を介して設定ファイルを読み込みます。
• リモートプロジェクト（インラインのメタデータブロック）：AWS SSM 経由でアクセスするリモート開発マシン上にプロジェクトのソースがある場合に使用します。ディスパッチャーのマシンには、プロジェクトの autonomous.conf はありません。Issue のスキャンとディスパッチに必要な情報はすべて、dispatcher.conf 内でインラインに宣言します。EXECUTION_BACKEND=remote-aws-ssm と SSM_INSTANCE_ID によって、実際の dispatch-local.sh の呼び出しを aws ssm send-command 経由でリモートマシンにルーティングします（#62）。

どちらの形式でも、同じ 5 ステップのティックを実行します。

1. 並行実行ゲート — count(in-progress + reviewing) >= MAX_CONCURRENT の場合は中止します。
2. 新規 Issue のスキャン — autonomous のみが付いた Issue を見つけ、依存関係を確認し、dev-new をディスパッチします。
3. レビュー待ち Issue のスキャン — pending-review の Issue を見つけ、レビューをディスパッチします。
4. 開発待ち Issue のスキャン — pending-dev の Issue を見つけ、リトライ回数を確認し、dev-resume をディスパッチします（または上限に達している場合は停滞状態にします）。
5. 古い Issue の検出 — in-progress／reviewing の Issue に対してラッパーの PID を確認し、プロセスの生存／終了状態と PR／CI／アイドル状態のゲートに応じて処理します。

ロジックは scripts/dispatcher-tick.sh と、ヘルパーの scripts/lib-dispatch.sh にあります。各ステップが実装する仕様については、ソースリポジトリの docs/pipeline/dispatcher-flow.md を参照してください。

GitHub 認証 — ユーザートークンではなくアプリトークン

ディスパッチャー内のすべての gh 呼び出しでは、デフォルトのユーザートークンではなく GitHub アプリトークンを使用します。ラッパー（autonomous-dev.sh、autonomous-review.sh）は lib-auth.sh を介して独自に認証を処理し、ディスパッチャーの tick も独自に認証を処理します。

GH_AUTH_MODE=app の場合、dispatcher-tick.sh は事前検証後に gh-app-token.sh::get_gh_app_token を自動的に呼び出し、gh の呼び出し前に GH_TOKEN をエクスポートします（#91）。プロジェクトの autonomous.conf またはインラインメタデータブロックに必要な変数：

GH_AUTH_MODE=app
DISPATCHER_APP_ID=<numeric app id>
DISPATCHER_APP_PEM=<absolute path to PEM>

これらのいずれかが設定されていない場合、またはトークンの生成に失敗した場合、tick は FATAL メッセージとともに終了コード 1 で終了します。ユーザー認証へのサイレントフォールバックはありません。

トークンの有効期間は 1 時間で、対象リポジトリのみがスコープになります。dispatcher-tick.sh は通常 1 分もかからずに完了するため、1 つのトークンで tick 全体をカバーできます。GH_AUTH_MODE=token（デフォルト）または未設定の場合、ディスパッチャーは呼び出し元がコードホストの標準的な方法で提供するトークンを使用します。GitHub では GH_TOKEN または gh auth login セッション、GitLab（CODE_HOST=gitlab）では GITLAB_TOKEN または glab auth login セッションです。chp_*／itp_* プロバイダーシームは、存在する方を経由します。

ディスパッチヘルパー

dispatcher-tick.sh はタスクの種類ごとに dispatch() ヘルパーを呼び出し、設定された実行バックエンドに処理を振り分けます。**他の方法でエージェントプロセスを起動しないでください。**各バックエンドは nohup、入力検証、モード 0600 のログファイル、古いラッパーの強制終了（INV-09）を処理します。

現在のバックエンド：

EXECUTION_BACKEND	ドライバー	用途
local（デフォルト。未設定の場合も同様）	scripts/dispatch-local.sh	ラッパーがディスパッチャーと同じマシン上で実行される場合。
remote-aws-ssm	scripts/dispatch-remote-aws-ssm.sh	ラッパーが AWS Systems Manager 経由でアクセスするリモート開発用 EC2 上で実行される場合。ディスパッチャーは aws ssm send-command を送信し、リモートマシン上で dispatch-local.sh を呼び出します。

タスクごとのコマンド形式（両方のバックエンドで同じ形式で渡されます）：

種類	コマンド
新規開発タスク	dispatch dev-new ISSUE_NUM
レビュータスク	dispatch review ISSUE_NUM
開発タスクの再開	dispatch dev-resume ISSUE_NUM SESSION_ID

レーン GC の適用

adt-gc.sh は、INV-117 のレジストリ駆動の安全性判定に基づき、停止したレーンに残ったデータを定期的に回収します。組み込みのデフォルトは、すべてのプラットフォームで引き続き --dry-run です。P8 の安全性改善はマージされる可能性がありますが、デフォルトの切り替えと本番環境への適用は、issue #384 の少なくとも 2 週間にわたるクリーンな監視期間が完了するまで保留されます。明示的な ADT_GC_ENFORCE=1 または --kill には、認可された適用が必要です。有効なモードとホストの前提条件を確認するには、次を実行します。

bash "$PROJECT_DIR/scripts/adt-gc.sh" --doctor

定期タイマーと、各プロジェクトの任意実行 --quick の両方に適用される、マシン全体を対象とした即時ロールバックを行うには、次を実行します。

source "$PROJECT_DIR/scripts/lib-lane.sh"
mkdir -p "$ADT_STATE_ROOT"
printf 'ADT_GC_ENFORCE=0\n' > "$ADT_STATE_ROOT/adt-gc.conf"

ファイルを削除すると、環境による選択または組み込みのデフォルトである dry-run に戻ります。ロールバックファイルが存在する場合、環境変数による ADT_GC_ENFORCE=1 は無効になります。明示的な --dry-run／--kill は、どちらも確認せずに両方を上書きします。優先順位は CLI モード > 永続設定による拒否 > 環境変数 > 組み込み設定です。選択された値が無効な場合は警告し、dry-run に倒して失敗します。設定はデータとして解析され、ロールバック指定 1 件と任意の空行またはコメントのみを含める必要があります。ADT_STATE_ROOT が未設定の場合、lib-lane.sh は $HOME/.local/state/adt-state-root にあるモード 600 のホストポインターを解決します。このポインターは install-gc-timer.sh によってアトミックに書き込まれます。これにより、タイマーと任意実行のコレクターが使用する同じカスタムルートでロールバックが行われます。同じ lib-state-root.sh リゾルバーは、ローカルディスパッチャーのマーカーファイル読み取りにも使用され、リモート SSM の稼働確認にも埋め込まれます。

ディスパッチャーが絶対にしてはならないこと

ディスパッチャーは、ラベル付けとプロセス起動を行う調整役であり、コードを変更する役割ではありません。

• 対象リポジトリにコミットまたはプッシュしてはなりません。
• $PROJECT_DIR 内のソースファイルを変更してはなりません。
• GitHub API 経由でのイシューのラベル／コメントの読み取り、GitHub API 経由でのラベルの更新、および設定済みバックエンド（dispatch-local.sh または dispatch-remote-aws-ssm.sh）経由でのラッパープロセスのディスパッチのみを行わなければなりません。

コードの変更は、ラッパーによって起動された開発／レビューエージェントが行います。

環境変数

scripts/autonomous.conf から読み込まれます（dispatcher-tick.sh が lib-dispatch.sh の前に読み込みます）。

• REPO：owner/repo 形式の GitHub リポジトリ（例：myorg/myproject）
• REPO_OWNER、REPO_NAME：REPO を分割した形式（App トークンのスコープ設定に使用）
• PROJECT_ID：ログ／PID ファイル用のプロジェクト識別子（デフォルト：project）
• PROJECT_DIR：ローカルマシン上のプロジェクトルートの絶対パス
• MAX_CONCURRENT：並列タスクの最大数（デフォルト：5）
• MAX_RETRIES：イシューを stalled としてマークするまでの開発の最大再試行回数（デフォルト：3）
• DISPATCHER_APP_ID：ディスパッチャーボット用の GitHub App ID
• DISPATCHER_APP_PEM：GitHub App の秘密鍵 PEM ファイルのパス

Cron の設定（OpenClaw）

openclaw cron add \
  --name "Autonomous Dispatcher" \
  --cron "*/5 * * * *" \
  --session isolated \
  --message "Run the autonomous-dispatcher skill. Check GitHub issues and dispatch tasks." \
  --announce

ラベルの定義

ラベル	色	説明
autonomous	#0E8A16	自律型パイプラインで処理するイシューです
in-progress	#FBCA04	エージェントが開発中です
pending-review	#1D76DB	開発が完了し、レビュー待ちです
reviewing	#5319E7	エージェントがレビュー中です
pending-dev	#E99695	レビューに失敗し、追加の開発が必要です
approved	#0E8A16	レビューに合格しました。PR はマージ済みです（または no-auto-close が設定されている場合は手動マージ待ちです）
no-auto-close	#d4c5f9	autonomous と併用します。レビュー合格後の自動マージをスキップし、手動承認を必要とします
stalled	#B60205	イシューが再試行の最大回数を超過しました。手動での調査が必要です

状態遷移の詳細については、ソースリポジトリの docs/pipeline/state-machine.md を参照してください。

モデル戦略

タスク	モデル	理由
開発（autonomous-dev.sh）	Opus（デフォルト）	複雑なコーディング、アーキテクチャの判断
レビュー（autonomous-review.sh）	Sonnet（--model sonnet）	チェックリストの確認、Opus のクォータ競合を回避