5. Notifications

通知レイヤー仕様書

本文書は Li+ プログラムの通知レイヤーの仕様を定義する。 要求（何を満たすか）と仕様（どう振る舞うか）を一体として記述する。

通知レイヤーは、GitHub Notifications API、webhook、ローカル state dir、将来の受動受信をまたいで共通に使う意味論を定義する。polling か push かは transport の違いであり、通知の ownership と前景会話への出し方は本文書を正本とする。

---

目的

Li+ は前景セッションで軽量な通知差分を扱うが、共有 queue を雑に排水すると別 AI や別セッションの作業面を壊す。通知レイヤーは、通知の確認、所有、既読化、完了、会話への言及、清掃を分離し、前景スレッドの安定性を守る。

特に以下を満たす：

• 前景セッションに関係する通知だけを選択して扱える
• 関係のない通知を勝手に消費しない
• 重要な前景外通知だけを例外的に会話へ出せる
• 明らかに無害で放置された stale 通知だけを清掃できる
• 将来 transport が受動受信へ変わっても上位意味論を変えない

---

基本操作

通知レイヤーは次の操作を区別する。

操作	意味
inspect	未処理通知を読む。ownership は変えない
claim	現在の前景セッションがその通知を担当対象として確保する
ack/read	読んだことを記録する。Inbox から消すとは限らない
consume/done	処理済みまたは意図的破棄として active queue から外す
mention	現在の会話へ通知を出す
cleanup	応答不要な stale 通知を janitor 的に片づける

claim は ack/read でも consume/done でもない。所有権の宣言であり、会話への言及や queue からの除去とは別に扱う。

---

前景セッションの既定

各ユーザーターンの先頭で、前景セッションは通知源を1回だけ inspect してよい。確認自体は内部 housekeeping であり、確認中であることや empty/no-op 結果を会話へ出さない。

前景一致判定は可能な限り機械的に行う。優先する手掛かりは以下：

• 現在扱っている repository
• 現在の issue / PR / Discussion 番号
• 現在の linked branch
• 進行中タスクと直接結び付く workflow / check / review 対象

既定動作は次のとおり：

• 前景一致した通知だけを claim 対象にできる
• 前景一致した通知だけを ack/read または consume/done 候補にできる
• 関連性が安価に判定できない通知は mention せず、consume/done もしない
• 判断不能時の既定は「黙る・残す」に倒す

---

例外的な会話言及

前景外通知でも、重要性が高い場合に限り mention を許可する。これは queue ownership とは別判断であり、mention したからといって自動で consume/done しない。

例外候補：

• 外部人間からの Discussion / issue / PR コメント
• 現在の作業を止めうる failure / blocking / review request
• 自分たち以外からの明示的な呼びかけ

曖昧な通知は例外扱いしない。

---

マルチ AI 共有キュー

Codex と Claude Code など複数の AI が同じ repository の通知 queue を共有する場合、一方の前景セッションが他方の通知を勝手に排水してはならない。

そのため、transport が許すなら通知 state は次を持てる形が望ましい：

• claimed_by
• claimed_at
• consumed_at
• reason

transport 自体に claim が無い場合は sidecar metadata で補う。どちらも使えない場合、破壊的な consume/done より preserve を優先する。

drain all pending events は暫定 helper 実装として存在しても、上位意味論の正本にはしない。

---

清掃（Janitor）

前景一致しない通知でも、明らかに誰の応答も不要で、かつ一定時間以上放置された無害通知だけは cleanup してよい。

清掃候補：

• 自分たちが発行した check_run / workflow_run の success
• 重複している自動生成通知
• 後続イベントで意味を失った generated artifact

清掃禁止：

• 人間の comment / Discussion / review
• failure / blocking / changes requested
• ownership が曖昧な通知
• relevance を安価に判定できない通知

清掃は relevance 判断の代替ではない。安全に無視できるものだけを対象にする。

---

Transport Binding

理想の意味論は GitHub Notifications API に寄せる。

意味論	GitHub Notifications API	Webhook / local state fallback
inspect	GET /notifications?all=false	pending event の一覧取得
ack/read	PATCH /notifications/threads/{id}	read 相当の state 更新
consume/done	DELETE /notifications/threads/{id}	pending queue から除去
claim	API 非対応。sidecar で補う	sidecar または state file で補う

transport は polling でも push でもよい。前景一致判定、例外的 mention、janitor cleanup の規則は transport によって変えない。

---

他レイヤーとの接続

Operations Layer: CI / review / release 待機で必要なイベント種別を定義するが、共有 queue の ownership と cleanup 規則は通知レイヤーを再定義しない。

Adapter Layer: 各ターン先頭で transport を inspect し、前景へ渡す summary を整える。関連性判断と destructive consume の正本は通知レイヤーに従う。

---

進化

再構築・削除・最適化はすべて許容する。構造の一貫性のみ維持する。