github-issue-state-management

name	github-issue-state-management
description	GitHub Issueのラベルとメタデータを使用した環境状態管理。worktree/ホスト環境すべてからアクセス可能なSingle Source of Truth

GitHub Issue 状態管理

Single Source of Truth: GitHub Issue のラベルとメタデータによる環境状態管理

---

概要

なぜ GitHub Issue で管理するのか？

課題（ローカルファイル）	解決策（GitHub Issue）
worktree間でファイル共有不可	Issue は全環境で同一
並列実行時の競合リスク	ラベル操作は GitHub がアトミック処理
ローカルファイルのため可視性が低い	GitHub UI で状態が一目瞭然

---

ラベル体系

ステータスラベル（排他: 1つのみ）

ラベル	説明	色（推奨）
env:active	作業中	#0E8A16 (緑)
env:blocked	人間の介入が必要	#D93F0B (赤)
env:pr-created	PR作成済み	#1D76DB (青)
env:merged	マージ完了	#6F42C1 (紫)

Phase ラベル（排他: 1つのみ）

ラベル	説明
phase:0-branch	ブランチ作成
phase:1-env	環境構築
phase:2-design	設計書参照
phase:3-check	設計書実現性チェック
phase:4-red	テスト作成（Red）
phase:5-green	実装（Green）
phase:6-refactor	リファクタリング
phase:7-review	レビュー依頼/修正
phase:8-stress	ストレステスト（任意）
phase:9-approval	ユーザー承認待ち
phase:10-pr	PR作成
phase:11-ci	CI監視
phase:12-merge	マージ & クリーンアップ

領域ラベル（任意: 複数可）

ラベル	説明
area:backend	バックエンド
area:frontend	フロントエンド
area:infra	インフラ
area:database	データベース

---

メタデータ管理

Issue Body へのメタデータ埋め込み

Issue 作成時または環境開始時に、Issue body の末尾に以下のブロックを追加：

<!-- ENV_METADATA
env_id: abc-123-def
branch: feature/issue-42-user-auth
env_type: worktree
worktree_path: .worktrees/issue-42
created_at: 2026-01-17T10:00:00Z
last_updated_at: 2026-01-17T15:30:00Z
-->

フィールド定義

フィールド	型	必須	説明
env_id	string	✅	worktree 識別子
branch	string	✅	Git ブランチ名
env_type	string	✅	worktree / host
worktree_path	string		worktree 使用時のパス
pr_number	string		PR作成後に設定（途中再開時のCI監視に必要）
created_at	string	✅	作成日時（ISO 8601）
last_updated_at	string	✅	最終更新日時（ISO 8601）

メタデータの抽出

# Issue body からメタデータを抽出
gh issue view 42 --json body -q '.body' | \
  grep -oP '(?<=<!-- ENV_METADATA)[\s\S]*?(?=-->)' | \
  grep -E '^[a-z_]+:' | \
  sed 's/^/  /'

---

Blocked 状態の詳細記録

Blocked コメント形式

Blocked 発生時は、ラベル変更と共に以下形式のコメントを追加：

## Blocked: [reason_code]

**Description**: [問題の詳細説明]

**Suggested Action**: [推奨される解決アクション]

**Context**:
- [関連情報1]
- [関連情報2]

**Blocked at**: 2026-01-17T14:00:00Z

---
> このコメントは `env:blocked` ラベルと連動しています。
> 問題解決後、ラベルを `env:active` に変更し、このコメントに「Resolved」と返信してください。

Blocked Reason コード

Reason	説明	推奨アクション
design_ambiguity	設計書実現性チェックNG	設計書修正
review_loop_exceeded	レビュー3回失敗	設計書見直し
dependency_missing	依存Subtask未完了	依存解決待ち
external_blocker	外部要因（API未提供等）	人間エスカレーション
ci_persistent_failure	CI 3回連続失敗	手動調査必要

---

API 操作

主要関数（CLI ラッパー）

関数	用途	コマンド例
register_env	環境開始時に登録	issue-state.sh register 42 abc-123 feature/auth worktree
update_phase	Phase更新	issue-state.sh phase 42 5-green
set_blocked	Blocked状態に設定	issue-state.sh block 42 design_ambiguity "設計に矛盾"
clear_blocked	Blocked解除	issue-state.sh unblock 42
get_state	現在の状態取得	issue-state.sh get 42
list_active	アクティブな環境一覧	issue-state.sh list

直接 gh コマンド

# 環境登録（ラベル追加）
gh issue edit 42 --add-label "env:active,phase:1-env,area:backend"

# Phase 更新（ラベル入れ替え）
gh issue edit 42 --remove-label "phase:4-red" --add-label "phase:5-green"

# Blocked 設定
gh issue edit 42 --remove-label "env:active" --add-label "env:blocked"
gh issue comment 42 --body "## Blocked: design_ambiguity..."

# PR作成済みに更新
gh issue edit 42 --remove-label "env:active" --add-label "env:pr-created"

# 状態取得（JSON）
gh issue view 42 --json number,title,labels,body,comments

# アクティブな環境一覧
gh issue list --label "env:active" --json number,title,labels

# Blocked な環境一覧
gh issue list --label "env:blocked" --json number,title,labels

---

必須更新ポイント (NON-NEGOTIABLE)

トリガー	アクション	ラベル操作
環境作成開始	ラベル追加 + メタデータ埋め込み	+env:active, +phase:1-env
Phase 遷移	ラベル入れ替え	-phase:X, +phase:Y
Blocked 発生	ラベル変更 + コメント追加	-env:active, +env:blocked
Blocked 解除	ラベル変更	-env:blocked, +env:active
PR 作成	ラベル変更	-env:active, +env:pr-created, +phase:10-pr
PR マージ	ラベル変更	-env:pr-created, +env:merged, +phase:12-merge
環境削除	ラベル削除	全 env:*, phase:* ラベルを削除

---

セッション復旧（途中再開）

resume コマンド（推奨）

# 復旧情報をJSON形式で取得
bash .opencode/skill/github-issue-state-management/scripts/issue-state.sh resume 42

出力例:

{
  "issue_number": 42,
  "status": "env:active",
  "phase": "5-green",
  "env_id": "abc-123-def",
  "branch": "feature/issue-42-user-auth",
  "env_type": "worktree",
  "action": "reopen_environment",
  "command": "environment_open with env_id=abc-123-def"
}

復旧判定マトリクス

ステータス	Phase	アクション	具体的な操作
env:active	0-branch	環境作成	environment_create(from_git_ref=branch)
env:active	1-env〜6-refactor	環境再開	environment_open(env_id=...)
env:active	7-review〜8-stress	レビュー再開	環境を開いてレビューループを継続
env:active	9-approval	承認待ち	ユーザーに承認ゲートを提示
env:active	10-pr〜11-ci	CI監視	gh pr checks <pr_number>
env:blocked	-	人間の介入	Blockedコメント確認 → 解決 → unblock
env:pr-created	-	PR確認	gh pr view で状態確認
env:merged	-	クリーンアップ	環境削除（残っている場合）
(なし)	-	初期化	register で環境を登録

手動復旧手順（参考）

# 1. アクティブな環境を検索
gh issue list --label "env:active" --json number,title,labels

# 2. 特定 Issue の復旧情報を取得
bash .opencode/skill/github-issue-state-management/scripts/issue-state.sh resume 42

# 3. 出力された action/command に従って再開

---

並列実行時のルール

Actor	責任
Sisyphus	作業完了後、自身で phase ラベルを更新可能
Main agent (Sisyphus)	複数 Issue を並列処理する場合、各 Issue を独立して管理

競合回避:

• 同一 Issue への同時編集は避ける（既存ルールと同じ）
• ラベル操作は GitHub がアトミックに処理するため、ファイルベースより安全

---

ラベル初期設定

リポジトリに必要なラベルを一括作成：

# ステータスラベル
gh label create "env:active" --color "0E8A16" --description "作業中"
gh label create "env:blocked" --color "D93F0B" --description "人間の介入が必要"
gh label create "env:pr-created" --color "1D76DB" --description "PR作成済み"
gh label create "env:merged" --color "6F42C1" --description "マージ完了"

# Phase ラベル
gh label create "phase:0-branch" --color "FBCA04" --description "ブランチ作成"
gh label create "phase:1-env" --color "FBCA04" --description "環境構築"
gh label create "phase:2-design" --color "FBCA04" --description "設計書参照"
gh label create "phase:3-check" --color "FBCA04" --description "設計実現性チェック"
gh label create "phase:4-red" --color "FBCA04" --description "TDD Red"
gh label create "phase:5-green" --color "FBCA04" --description "TDD Green"
gh label create "phase:6-refactor" --color "FBCA04" --description "リファクタリング"
gh label create "phase:7-review" --color "FBCA04" --description "レビュー"
gh label create "phase:8-stress" --color "FBCA04" --description "ストレステスト"
gh label create "phase:9-approval" --color "FBCA04" --description "承認待ち"
gh label create "phase:10-pr" --color "FBCA04" --description "PR作成"
gh label create "phase:11-ci" --color "FBCA04" --description "CI監視"
gh label create "phase:12-merge" --color "FBCA04" --description "マージ完了"

# 領域ラベル
gh label create "area:backend" --color "C2E0C6" --description "バックエンド"
gh label create "area:frontend" --color "C2E0C6" --description "フロントエンド"
gh label create "area:infra" --color "C2E0C6" --description "インフラ"
gh label create "area:database" --color "C2E0C6" --description "データベース"

---

CLI スクリプト

使用方法:

bash .pi/skills/github-issue-state-management/scripts/issue-state.sh <command> [args...]

コマンド	説明	使用例
register	環境を登録	issue-state.sh register 42 abc-123 feature/auth worktree
phase	Phase を更新	issue-state.sh phase 42 5-green
block	Blocked 状態に設定	issue-state.sh block 42 design_ambiguity "説明"
unblock	Blocked を解除	issue-state.sh unblock 42
pr-created	PR作成済みに更新	issue-state.sh pr-created 42 25
merged	マージ完了に更新	issue-state.sh merged 42
get	状態を取得	issue-state.sh get 42
list	アクティブ一覧	issue-state.sh list
resume	途中再開情報を取得	issue-state.sh resume 42
init-labels	ラベル一括作成	issue-state.sh init-labels

エラーリトライ

スクリプトはネットワークエラーやGitHub APIのレート制限に対して自動リトライを行います。

設定	環境変数	デフォルト
最大リトライ回数	MAX_RETRIES	3
リトライ間隔（秒）	RETRY_DELAY	5

レート制限時: 60秒待機後にリトライ ネットワークエラー時: RETRY_DELAY秒待機後にリトライ

# カスタムリトライ設定
MAX_RETRIES=5 RETRY_DELAY=10 bash issue-state.sh phase 42 5-green

---

ハードブロック (違反禁止)

違反	結果
環境開始時にラベル未追加	FORBIDDEN - 復旧不可
Phase 遷移時にラベル未更新	FORBIDDEN - 状態不整合
Blocked 時にコメント未追加	FORBIDDEN - 理由が不明

---

変更履歴

日付	バージョン	変更内容
2026-01-17	1.0.0	初版作成