3. Operations

オペレーションレイヤー仕様書

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

Li+operations.md はイベント発生時にオンデマンドで読み込む。毎セッション必須ではない。 ブランチ作成、コミット、PR、マージ、リリース、マイルストーン割り当て、ラベル判断、Discussions 参照時に参照する。

---

イベント駆動トリガー

トリガー	対象セクション
act_now	ブランチとラベルフロー
on_commit	コミットルール
on_pr	PR 作成
on_ci	CI ループ
on_review	PR レビュー
on_merge	マージ
on_release	人間確認が必要な操作

---

ブランチ運用

着手タイミング（三段階）

着手意思は対話の空気から判断する。チェックリストで確認しない。不明瞭な場合は機械的にではなく、感じをもって聞く。

タイミング	ラベル	ブランチ
NOW（今やる）	in-progress	作成する
SOON（近いうち）	backlog	作成しない
SOMEDAY（いつか）	deferred	作成しない

ライフサイクルラベルは「いつ着手するか」、成熟度ラベルは「どこまで収束したか」。ライフサイクルラベルを成熟度の代用にしない。

trigger mode でも issue の作成・本文更新とブランチ準備は待たない。人間トリガーの対象は実装開始と PR レビューである。

repo-first の作業面

高注意で扱うのは、main のような保護された共有ブランチである。issue にリンクした個人ブランチは通常の実装面として扱う。リポジトリ全体を過度に「間違えてはいけない場所」とみなさない。

ローカル確認はブランチ作業と両立する。push の前でも後でも実行してよい。ただし、作業継続性の正本は issue にリンクしたブランチ側に置く。ローカルで動いたことだけを完了条件にしない。

ブランチ作成

issue リンクは常に必須。リンクは GitHub への初回 push より前に実行する。sub-issue にはブランチを作らない。ブランチを持つのは実際に PR を出す作業単位（親 issue）だけ。

ブランチ作成前にローカルとリモートの存在確認を行う。リモートに既存ブランチがある場合、後からリンクは張れない。

# 存在確認
local:  git branch --list {branch-name}
remote: gh api repos/{owner}/{repo}/branches/{branch-name}  # 404 = not exists

# ブランチ作成 + issue リンク
gh issue develop {issue_number} -R {owner}/{repo} --name {session-branch} --base main

# アサイニー設定
gh api repos/{owner}/{repo}/issues/{issue_number}/assignees --method POST -f 'assignees[]=liplus-lin-lay'

ローカルエラー時の対処：gh issue develop がローカルで失敗してもGitHub 側では成功する場合がある。リンク済みブランチを確認してから判断する。

gh api graphql -f query='{ repository(owner:"{owner}",name:"{repo}") { issue(number:{number}) { linkedBranches { nodes { ref { name } } } } } }'

リンク済みならそのブランチを使用する。リンクなしならリトライまたは人間にエスカレーションする。

引き継ぎ

トークン上限、セッション切断、モデル切り替えなどで作業が中断されそうな時は、issue にリンクした個人ブランチへ中間状態を push してよい。引き継ぎ時の正本は、会話ログではなく issue body + linked branch + commit / PR state である。

意味のある進捗をローカルワークスペースや一時的な会話だけに閉じ込めない。

---

ドキュメント同期と要求仕様の責務

docs/ を正本とする。Wiki は反映先であり、正本にしない。

実装変更を含む PR は、対応する docs/ の更新を同一 PR 内に含める。「後で docs を直す」という分割は禁止する。AI はコンテキスト圧縮で記憶を失うため、ドキュメントが唯一の真実の源になる。

配布向けプロジェクトでは、最低限の docs/ として要求仕様書を持つ。新規・小規模プロジェクトではまず1ファイルの要求仕様書を作ればよい。規模が大きい場合は分割してよい。

実装を始める前に、対応する要求仕様書を先に作成または更新する。挙動変更・バグ修正・仕様変更では、まず要求仕様書の該当箇所を変更し、コードとテストはその仕様差分を実装・検証するために更新する。

Li+ の挙動や運用ルールに効く判断は、番号付き要求仕様書（1–9）と対応するプログラムファイルへ固定する。補助メモや実験ログを残してもよいが、それを正本にしない。要求仕様書は可読性が向上する場合に分割してよい。

PR タイトルには変更の影響範囲を含める。

# bad:  fix(config): negative duration handling
# good: fix(config): treat negative durations as below-minimum rather than error

---

コミットルール

言語

• タイトル：ASCII 英語のみ、1行
• ボディ：日本語 + issue 番号

日本語タイトルは禁止。英語のみボディは禁止。ボディは省略不可。

ボディの内容

変更要約 + 意図または背景 + issue 番号。最低1文の日本語を含める。

プッシュ

プライマリは git push。git が使えない環境では GitHub API フォールバック（blob/tree/commit/ref 作成）を使う。複数ファイル時は tree 作成後にファイル数を検証し、減少していた場合はコミット中止する。

# プライマリ
git push origin {session-branch}:{target-branch}

# フォールバック（単一ファイル）
gh api repos/{owner}/{repo}/contents/{path}  # PUT base64 sha

# フォールバック（複数ファイル）
1. create blobs: gh api .../git/blobs  # per file
2. create tree:  gh api .../git/trees  # verify count after
3. create commit: gh api .../git/commits
4. update ref:   gh api .../git/refs/heads/{branch}

チャット出力制限：長い出力は途中で止まることがある。物理的な制限であり、破損ではない。必要に応じてチャンキングする。

---

PR 作成

PR 本文形式

issue ごとのブロック形式で記述する。親 issue → Refs #xxx、クローズ済み子 issue → Refs sub #xxx。各ブロックに2〜3行の要約を書く。詳細は issue を参照。deferred・open のまま残す子 issue は含めない。

PR 作成後、CI ループへ即座に移行する。人間の指示は不要。

---

CI ループ

CI ループは PR 作成とは独立したタスクである。PR 作成後または修正リコミット後に開始する。

step 1: 最新コミット SHA 取得

gh pr view {pr} -R {owner}/{repo} --json headRefOid --jq '.headRefOid'

step 1.5: マージ可能状態の確認

gh pr view {pr} -R {owner}/{repo} --json mergeStateStatus --jq '.mergeStateStatus'

• CONFLICTING → 自動 rebase を試行（git fetch origin main && git rebase origin/main）。成功なら git push --force-with-lease で CI ループを step 1 から再開。失敗なら git rebase --abort → issue コメント → 人間にエスカレーション。
• BLOCKED / UNKNOWN → 待機して再確認（GitHub が計算中の可能性）。

step 2: 全チェックランの完了を待機

mcp__github-webhook-mcp が利用可能な場合：

• get_pending_status を60秒間隔でポーリング
• check_run の pending があれば list_pending_events → get_event で SHA 一致を確認 → mark_processed
• 全チェックランが完了するまで収集

利用不可の場合：

gh api repos/{owner}/{repo}/commits/{sha}/check-runs --jq '.check_runs[] | {name,status,conclusion}'

全ての status=="completed" になるまで sleep で繰り返す。

step 3: 結論判定

• CI FAIL = いずれかの conclusion=="failure"
• CI PASS = 全て conclusion が success / skipped / neutral

CI PASS → PR レビューへ移行。 CI FAIL → 修正してリコミット（CI ループを step 1 から再開）。ループ安全閾値（3回）を超えた場合は issue コメントに外部化し、人間に委ねる。

---

PR レビュー

レビューの基準は repository state first である。issue 本文、リンク済みブランチの差分、PR 本文、CI 結果を読む。ローカルで動いたことだけではレビュー完了にしない。

レビュー承認確認：

mcp__github-webhook-mcp が利用可能な場合：

• get_pending_status を60秒間隔でポーリング
• pull_request_review の pending があれば list_pending_events → get_event で当該 PR を確認 → mark_processed

利用不可の場合：

• 人間がレビュー完了を通知するまで待機（ポーリングしない）
• 通知を受けたら確認：

gh pr view {pr} -R {owner}/{repo} --json reviewDecision --jq '.reviewDecision'

• APPROVED → マージへ移行。
• CHANGES_REQUESTED → レビューコメントを読んで修正し CI ループを再開する。

---

マージ

Auto-merge フロー

PR 作成直後に auto-merge を有効化する。

gh pr merge {pr} -R {owner}/{repo} --auto --squash

レビュー承認後、GitHub auto-merge がスカッシュマージとブランチ削除を自動処理する。

手動マージフロー

マージ戦略（squash / merge / rebase）を人間に確認してから実行する。

gh pr merge {pr} -R {owner}/{repo} --{strategy}

PR 本文に Refs #xxx が含まれていると、マージ時にプラットフォームが issue を自動クローズする。

実機テストはマージ後に main 上で行う。マージゲートにはしない。

---

実行モード

LI_PLUS_EXECUTION_MODE によって AI の自律度を切り替える。未設定の場合、セッション開始時に AI が対話で設定する。

モード	着手タイミング	PR レビュー
trigger（デフォルト）	人間が判断	人間がレビュー
auto	AI が判断	AI がレビュー

両モード共通：issue 作成・クローズ・修正はアサイニー（AI）の責任。情報不足時は人間に確認する。リリースは常に人間の確認が必要。

trigger mode で実装開始の合図が出たら、ローカル専用の作業空間ではなく issue にリンクした個人ブランチを主作業面として使う。

---

人間確認が必要な操作

「待って」「止めて」「まって」と言われたら即座に停止する。

確認が必要な操作：

• リリース作成（バージョン種別とターゲットタグ）— 実行前に CD チェックが必要
• ブランチ削除（リンクされた issue がクローズされる可能性がある場合）
• force push
• trigger mode のみ：issue 選択、issue 実行開始

リリース前 CD チェック

リリース作成前に CD の完了を確認する。CD PASS なら人間に確認してリリース作成へ。CD FAIL なら人間にエスカレートし、リリースは作成しない。

mcp__github-webhook-mcp が利用可能な場合：

• get_pending_status を60秒間隔でポーリング
• workflow_run の pending があれば list_pending_events → get_event で conclusion を確認 → mark_processed

利用不可の場合：

• gh api で全 CD チェックが完了するまでポーリングする。

バージョン種別

バージョン	適用条件
patch	バグ修正・設定・ルール変更
minor	新機能・動作変更
major	破壊的変更・仕様非互換

バージョン種別の判断は人間が行い、AI は実行のみを担う。バージョン番号はプレリリースを含む直近のリリースを基準にする。

リリースルール

• AI が作成するリリースは必ずプレリリースとする
• latest への昇格は実機テスト後に人間が判断する
• リリースタグ・タイトルはプロジェクト固有の規約に従う
• リリース body は GitHub generated release notes を使う（--generate-notes を渡す。--notes "" で空 body を渡さない）

バージョン番号はプレリリースを含む直近のリリースを基準にする（latest stable のみではない）。

gh release list --limit 1  # プレリリースを含む

リリースタグ・タイトル規約

プロジェクトの docs/ または CI/CD 設定を確認してから作成する。

プロジェクト種別	タグ形式	タイトル形式
Li+ language（デフォルト）	build-YYYY-MM-DD.N	Li+ {version}
npm パッケージ	v{semver}	v{semver}

CD workflow がタグを作成するプロジェクトでは、既存の CD 作成タグを使い、新規タグを作らない。npm version を使うプロジェクトでは、npm version コマンドがタグを作成する。

---

マイルストーン

マイルストーンはリリース単位。同じリリースで出荷する issue をグループ化する。

すべての issue に作成時点でマイルストーンを付与する。該当するマイルストーンがない場合は、人間にどのマイルストーンに入れるか確認する、または新規作成を提案する。

マイルストーン名はバージョン番号（例: v1.2.0）。説明には一行テーマ＋スコープの箇条書きを記載する。

作成：人間が新しいリリーススコープを決定した時。クローズ：リリースが公開された時。リリース前にクローズしない。

sub-issue は親のマイルストーンを継承する。

---

ラベル運用

有効ラベルの辞書はタスクレイヤー仕様書を正本とし、本文書では運用ルールと廃止履歴を扱う。

すべての issue に作成時点でタイプラベルを1つ以上、成熟度ラベルを1つ付与する。ライフサイクルラベルは状態変化時に適用する。

廃止されたラベル

ラベル	廃止理由
done	issue の closed 状態と冗長
tips	docs ラベル + issue body で代替

ラベルの追加・変更・廃止を行った場合はタスクレイヤー（Li+github.md）も合わせて更新する。

---

通知 API

GET    /notifications?all=false                -> 200  inbox 確認
PATCH  /notifications/threads/{id}             -> 205  既読（Inbox に残る）
PUT    /notifications {"read":true}            -> 205  全既読
DELETE /notifications/threads/{id}             -> 204  完了（Inbox から除去）

scope = notifications（classic PAT）

通知 API の生操作はオペレーションレイヤーから参照してよい。ただし、前景関連性判定、claim、ack/read、consume/done、mention、cleanup の意味論は 5. Notifications を正本とする。

---

Discussions

Discussions は外部ユーザーの入口。bot が常駐し、issue 作成と issue 読込が可能。コミット・コード変更はできない。

外部ユーザーが Discussions に投稿 → bot が issue を作成 → AI が issue から実装する。

---

進化

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