Lockage Introduction v0.9.6 (JA)

Lockage Introduction v0.9.6

https://github.com/tacck/lockage
https://www.npmjs.com/package/lockage

Transcript

1. MCP server · v0.9.6 · MIT License lockage 複数の AI エージェントが、 1 つの git リポジトリで協調して開発するために github.com/tacck/lockage
2. 背景 同じリポジトリに複数のエージェントを走らせると 01 02 03 同じファイルを同時に 書いて壊す 誰がどこを触っている か分からない 統合（マージ）がカオ スになる 作業場所が 1 つしかないと、変更 担当がぶつかっても、作業が終わ ばらばらに出来上がった成果を、 どうしが上書きし合う るまで気づけない 最後にまとめきれない lockage 02
3. コンセプト 分けて、見せて、1 本にまとめる lockage（ロッケージ）＝ 運河の閘門（こうもん）を船が通り抜けること。閘室で船を分け、水位を見ながら、1 隻ずつ通す 01 同じファイルを同時に書いて壊す → 作業場所を物理的に分ける 02 誰がどこを触っているか分から ない → 担当と変更を台帳で見せる 03 統合（マージ）がカオスになる → 統合の入口を 1 本にまとめる git worktree をエージェントごとに割り当てる claim・dirty set・board。警告するだけで止めない 直列のマージゲート。衝突しそうなら自動解決せず差し戻す エージェント同士は直接話さない。すべて SQLite の台帳 1 つを介してやり取りする lockage 03
4. 仕組み 物理隔離と、軽量な調整レイヤの 2 階層 LAYER 2 · SQLite claim・dirty set・board で「誰が何を担当しているか」を共有す 調整レイヤ る。警告するだけで、止めない LAYER 1 · git worktree エージェントごとに作業場所を分け、同じファイルを 2 人が同時に 物理隔離 書くこと自体を不可能にする lockage 04
5. warn-never-block 警告はする。 ブロックはしない。 hard lock を使わないので、デッドロックが起きない
6. 仕組み · claim_task タスクの取り合いを、原子的に防ぐ SQLite の BEGIN IMMEDIATE と Agent A claim_task(v=3) ok → v=4 Agent B claim_task(v=3) conflict version の CAS で claim を直列化する 後から来たエージェントは conflict を受け取るだ け。待たされずに、別のタスクへ移れる 同じ version で 2 人が取りに来ても、成功するのは 1 人だけ lockage 06
7. 仕組み · claim_files / dirty set 触る予定と、実際の変更を見せ合う claim_files(glob) dirty set これから触る範囲 実際に変えたファイル 例：src/auth/** publish_dirty で公開 他の人と重なっても警告だけ heartbeat などが git の状態から + 自動で計算 突き合わせた結果 overlaps 他の人の claim・dirty と重なった 相手には overlap の wake が届く → unclaimed 自分の宣言の外を変えた claim_files を呼び直す lockage 07
8. 仕組み · board board は、台帳に残る掲示板 kind 誰が書く 意味 相手を起こすか note エージェント 名乗り・連絡メモ 未読なら起こす question エージェント 行き詰まりの理由・質問 未読なら起こす handoff エージェント / system 引き継ぎ・差し戻しの通知 未読なら起こす ticket_ready サーバー チケットの全タスクが done 起こさない pr_opened / pr_updated / pr_merged lockage-publish PR の状態の記録 起こさない to_agent で宛先付き、なしで全員宛て lockage エージェントごとの既読カーソルで未読を 管理 heartbeat が未読件数を知らせ、 read_board で読む 08
9. 仕組み · task_done 統合は、1 本のマージゲートを通す 1-B · 直列マージゲート 1-C · 即マージ チケット配下のタスク（1 つでも） チケットの無い軽微なタスク チケット統合ブランチへ集約する 乖離が無ければ、その場で base ブランチへ lockage/ticket/<短縮ID> main needs_review lockage 衝突候補は 3-way プレチェックで検出し、自動解決せずに差し戻す 09
10. 仕組み · A2A wake 待つのは 1 回の long-poll だけ wait_for_unblock(agent_id) 依存が解消 自分宛の連絡 担当領域の重なり timeout 待っていたタスクが ready にな った board に自分宛か全体宛の投稿が 来た 他のエージェントが踏み込んで きた 何も起きなければ時間切れで戻る lockage 10
11. 使い方 · ライフサイクル 人間が触るのは、入口と出口だけ 01 02 03 04 05 06 07 起票 占有 隔離 作業 統合 PR 化 レビュー open_ticket create_task claim_task assign_ worktree claim_files publish_ dirty task_done lockagepublish PR を確認してマ ージ 全タスクが done になると ticket_ready が自動で立ち、エージ 本流への反映（PR のマージ）は、必ず人間の承認を通る ェントが lockage-publish を起動して PR を作る lockage 11
12. 使い方 · 提供ツール 37 のツールを、3 つの組で公開 組 誰が使うか ツール数 core エージェント（常に有効） 28 publisher lockage-publish が起動するサーバだ けで有効 6 maintenance 人間の保守・診断用 （LOCKAGE_TOOLSETS で有効化） 3 publisher の組はチケットを閉じるなどの後始末用なので、エージェントには見せない lockage 12
13. 使い方 · セットアップ プラグインを入れれば、サーバとルールがそろう 協調させる前提は 2 つだけ Claude Code の場合 同じ台帳を指す claude plugin marketplace add <path> claude plugin install lockage@lockage 全員が同じ LOCKAGE_DB を使う 一意な agent_id を名乗る Kiro は Power、Antigravity は agy plugin install で導入。clone やビルドは不要 起動時に決め、board で重複を確認 必要環境：Node.js 22.5 以上、git lockage 13
14. まとめ 複数エージェントでも、壊さず・迷わず・まとまる 壊さない 迷わない まとまる worktree で作業場所を物理的に分ける SQLite の台帳で担当を見える化。警告す るだけで止めない 直列マージゲートで統合し、PR のマージ は人間が決める github.com/tacck/lockage
15. エージェント間連携 9 つの連携と、wake を送るかどうか 1 名乗りと生存確認 board · lease 2 未読の note 仕事の分担 tasks · 依存 · tickets 3 task_ready 作業場所を分ける worktrees 台帳 4 変更範囲を見えるように 5 統合（マージゲート） 6 claims · dirty set マージキュー · board board · 既読カーソル 7 overlap 待機と起床 wait_for_unblock 8 受け取る側 未読の handoff 中断と引き継ぎ tasks · board wake なし 連絡（board） 未読の投稿 9 PR 化の連携 未読の handoff board · publish ロック wake なし 相手を起こすのは wake（task_ready・overlap）と、未読の board 投稿。オレンジの連携だけが起こせる lockage 15
16. エージェント間連携 1 / 9 名乗りと生存確認 起こす：未読の note post_board(note) 自分の agent_id を名乗る board read_board(kind:"note") 既存の名乗りと重複確認 Agent A list_claims 担当の重複も確認 新しく参加する ほぼ全ツールの呼び出し lease を 15 分延長 lockage kind:"note" で名乗りを残す 名乗った時点から全員宛ての未読を数 える 未読の note 待機中の B も起きる claims Agent B 誰がどの範囲を担当しているか すでに作業中 tasks · lease 15 分 post_board・task_done では延び ない blocked は切れても戻されない ━━ 情報の流れ lease 切れで open へ claim_task で拾い直せる ━━ 相手を起こす（wake・未読） 16
17. エージェント間連携 2 / 9 仕事の分担 wake あり：task_ready create_task(depends_on) タスクと依存を登録 list_tasks(ready_only) すぐ着手できるものだけ tasks status と version を持つ claim_task(version) 負けた側には conflict Agent A add_dependency 後から依存を張る 依存 DAG（blocks） Agent B 循環は add_dependency が拒否 計画を立てる 作業を取りに来る link_task_to_ticket チケットにまとめる tickets open_ticket で起票するまとまり task_ready 下流の担当者を起こす wake キュー 上流が done で依存が解けたら lockage ━━ 情報の流れ ━━ 相手を起こす（wake・未読） 17
18. エージェント間連携 3 / 9 作業場所を分ける assign_worktree 専用の作業場所を要求 worktree_path / branch ここだけで作業する wake なし worktrees 台帳 誰にどの worktree を割り当てたか list_worktrees で一覧 assign_worktree B も別の場所を要求 別の path と branch A とは重ならない git worktree add Agent A Agent B 自分の場所で作業 git リポジトリ 自分の場所で作業 agent ごとに別フォルダ・別ブランチ release_worktree 作業後に解放する 後片付け reclaim_orphan_worktrees release_ticket_worktrees lockage ━━ 情報の流れ ━━ 相手を起こす（wake・未読） 18
19. エージェント間連携 4 / 9 変更範囲を見えるようにする claim_files(glob) 触る範囲を宣言 wake あり：overlap list_claims / list_dirty 誰がどこを触っているか claims これから触る範囲（glob） 重なっていれば警告 止めはしない Agent A publish_dirty 変更したファイルを公開 これから変更する overlaps / unclaimed 重なりと宣言外の変更 claim_files 先に範囲を宣言済み dirty set Agent B 実際に変更したファイル heartbeat などで git から再計算 先に担当していた 重なりを検出 overlap 重なった相手を起こす wake キュー 宛先：重なった相手 lockage ━━ 情報の流れ ━━ 相手を起こす（wake・未読） 19
20. エージェント間連携 5 / 9 統合（マージゲート） task_done 作業をゲートに渡す 戻り値の needs_review 自分の差し戻しはここだけ マージゲート キューを 1 つずつ 3-way プレチェ ック 衝突なし → 統合ブランチ / base へ Agent B 他人の差し戻し Agent A task_done を呼 んだ 起こす：未読の handoff 未読の handoff B の次の待機を起こす board system 名義の handoff（宛先：B） 同じ実行で差し戻 されたタスクの 担当 全員分を投稿 process_merge_queue 保守用。差し戻しは全員分を投稿 lockage ━━ 情報の流れ ━━ 相手を起こす（wake・未読） 20
21. エージェント間連携 6 / 9 連絡（board） post_board note・handoff・question 起こす：未読の投稿 未読の投稿 次の待機で B が起きる board kind：note / handoff / question ticket_ready / pr_* Agent A 送る側 resolve_question question を解決済みに to_agent あり → 宛先付き to_agent なし → 自分以外の全員宛て heartbeat unread_count で件数を知る Agent B エージェントごとに既読位置を持つ 宛先にとって未読になる read_board(unread_only) 未読だけ読んで既読に 受け取る側 ticket_ready ほか サーバー / lockage-publish 記録なので未読に数えない lockage ━━ 情報の流れ ━━ 相手を起こす（wake・未読） 21
22. エージェント間連携 7 / 9 待機と起床 task_done 上流のタスクが完了 tasks post_board 相手にとって未読になる board 他の エージェント イベントを起こす 起こされる側 依存の解消・重なり wake が積まれる 待っているタスクが ready 自分宛て・全員宛ての未読 wake キュー task_ready・overlap タイムアウト 既定 60 秒 lockage ━━ 情報の流れ ① ready になった 依存がすべて解けた ② 未読の board 投稿 返した投稿は既読に Agent B ③ wake が届いた task_ready・overlap wait_for_unbloc k で待機 500ms ごとに DB を確認 ④ タイムアウト 何も起きなくても戻る ━━ 相手を起こす（wake・未読） 22
23. エージェント間連携 7 / 9 · 既読カーソル 作業中に届いた投稿も、取りこぼさない B の状態 作業中（待っていない） wait_for_unblock で待機 heartbeat が件数を知らせる board 投稿 読み始め lockage board_cursors 未読のまま残り、次の待機ですぐ起きる 返した投稿は既読になり、二重には起きない note（B 宛て） 自分宛て 全員宛て 最初（seq 0）から数える 起動前に届いた handoff も拾える 自分として初めて呼んだ時点から数える 過去の投稿は流れ込まない ━━ 情報の流れ ━━ 相手を起こす（wake・未読） 23
24. エージェント間連携 8 / 9 中断と引き継ぎ post_board(question) 先に理由を残す 起こす：未読の handoff 未読の handoff 起動前でも取りこぼさない board question と handoff の投稿 block_task 担当を持ったまま中断 Agent A 詰まった元の担当 resume_task 同じ A が再開する list_tasks(blocked) 放置・沈黙時間で孤児判断 tasks 引き継ぐ側 担当一式 担当・worktree・claim・dirty 1 つの CAS トランザクションで移す lockage Agent B in_progress ⇄ blocked ━━ 情報の流れ handoff_task 担当一式をまとめて移す ━━ 相手を起こす（wake・未読） 24
25. エージェント間連携 9 / 9 PR 化の連携 publisher_status PR 待ちなどの件数を見る 最後の task_done ticket_ready が立つ wake なし read_board ticket_ready を拾う board ticket_ready・pr_opened pr_updated・pr_merged Agent A 最後のタスクを done にして、 lockage-publish を起動する publish ロック チケット単位・TTL 300 秒 チケット / 統合ブランチ close_ticket_on_merge clear_integration_branch release_ticket_claims lockage ━━ 情報の流れ post_board pr_opened・pr_merged など acquire_publish_lock 二重処理を防ぐ release_publish_lock 終わったら解放 lockagepublish PR を作る 1 回き りのコマンド マージ後の後片付け チケットを閉じる ━━ 相手を起こす（wake・未読） 25