Status: v1 Review cadence: Monthly Owner: Governance / Maintainer Related: EPIC #193 / docs/pages/guides/governance/documentation-management.md
PlanGate の Issue 運用 (Issue 必須セクション / Label taxonomy / Milestone mapping) を正本化する。
ドキュメント配置・更新ルールは docs/pages/guides/governance/documentation-management.md が正本。本ドキュメントは Issue / Label / Milestone 側 を扱う。
すべての PlanGate roadmap issue は以下のセクションを持つ。
| Section | Purpose |
|---|---|
| Why | この Issue が必要な背景・問題・コスト |
| What | scope / out-of-scope / suggested files / suggested outputs |
| Acceptance Criteria | チェック可能な完了条件（チェックボックス箇条書き） |
| Non-goals | 明示的にやらないこと、誤解防止 |
| Labels | 付与するラベル一覧 |
| Milestone | 紐付ける milestone |
| Parent EPIC / Roadmap | 親 EPIC / ロードマップ doc / 関連 PR の引用 |
軽微な bug / typo は bug_report.yml / feature_request.yml テンプレートで OK。Roadmap PBI は plangate-roadmap-task.yml を使う。
PlanGate ラベルは 4 軸で分類する。複数軸を組み合わせて付与する。
| Label | 用途 |
|---|---|
enhancement |
新規機能追加・改善 |
bug |
不具合修正 |
documentation |
ドキュメント変更が主体 |
governance |
運用ルール・ガバナンス変更 |
refactor |
振る舞いを変えないリファクタリング |
security |
セキュリティ関連 |
| Label | 用途 |
|---|---|
area:cli |
bin/plangate 関連 |
area:hooks |
scripts/hooks/ 関連 |
area:eval |
eval-runner / eval-cases 関連 |
area:schema |
schemas/ 関連 |
area:workflow |
docs/workflows/ 関連 |
area:metrics |
metrics 関連 |
area:docs |
公開 docs / pages 関連 |
| Label | 用途 |
|---|---|
priority:P0 |
直近 milestone の必須項目 |
priority:P1 |
次 milestone 候補 |
priority:P2 |
中期計画 |
priority:P3 |
着手未定 |
| Label | 用途 |
|---|---|
status:blocked |
他 Issue / 外部要因で着手不可 |
status:in-progress |
着手中 |
status:needs-review |
レビュー待ち |
status:wontfix |
対応しない判断 |
note: 既存 Issue にこれらのラベルが未付与でも、新規 Issue 作成時から徹底する。一括 backfill は scope 外（Non-goals）。
vMAJOR.MINOR.PATCH の semver。次期予定 milestone は EPIC で先に作成する。
milestone をまたいで移動する場合（次期へ繰越など）は、Issue コメントに 理由 + 移動日 を残す。
新しい roadmap PBI を作成するときに通すチェックリスト。
- [ ] Title が `PBI-HI-NNN: <短い説明>` などロードマップ規約に沿っている
- [ ] Why / What / Acceptance Criteria / Non-goals が揃っている
- [ ] Suggested files / outputs が記載されている
- [ ] Parent EPIC / Roadmap doc / Related PR が冒頭で引用されている
- [ ] Labels (kind + priority、必要なら area) が付与されている
- [ ] Milestone が EPIC の表に従って付与されている
- [ ] 該当 milestone が GitHub 上に存在する（なければ先に作成）
- [ ] Acceptance Criteria は AI / human が機械的に検証できる粒度になっている
- [ ] EPIC の child policy / scope と矛盾していない
- [ ] documentation-management.md の Directory policy と矛盾していない
GitHub Issue テンプレートは .github/ISSUE_TEMPLATE/ 配下に置く。
| Template | 用途 |
|---|---|
bug_report.yml |
バグ報告 |
feature_request.yml |
軽量な機能要望 |
plangate-roadmap-task.yml |
EPIC #193 等の roadmap PBI |
config.yml |
テンプレート選択画面の設定 |
plangate-roadmap-task.yml は Section 2 / 5 を強制するために事前にスキャフォールドを提供する（Why / What / AC / Non-goals / Labels / Milestone を必須入力）。
EPIC issue は以下を満たす。
このガバナンスは新規 Issue 作成時から適用する。既存 Issue について：
closes #N / fixes #N / resolves #N（merge 時に自動 close）Refs: #N / Part of #N / Related to #N#N 言及は linkage 宣言ではなく、issue-link チェックを満たさない#N は同一行に書く。scripts/check-pr-issue-link.sh の判定は
grep ベースで行指向のため、Part of と #1180 が改行で分かれていると
linkage として検出されず WARN になる（例: Part of の直後で改行して次行に
#1180 を置いたケース）。折り返しは keyword と番号の後ろで行うhotfix #123 / prefix #123 / xrefs #456 のような
語末一致（hotfix → fix、xrefs → refs）は linkage 宣言として扱われないdocumentation ラベルを付ければ issue-link チェックを skip 可能（PR <!-- skip-issue-link-check --> でも可）scripts/check-pr-issue-link.sh は 1 行の判定を stdout に出す。exit code は
常に 0（4 値はいずれも merge をブロックしない）。
| 出力 | 条件 | 意味 |
|---|---|---|
PASS |
closing keyword（closes / fixes / resolves）あり |
この PR の merge で issue が閉じる |
NOTICE |
非クローズ型リンク（Refs: / Part of / Related to）のみ |
リンクはあるが「閉じない」と宣言している状態。意図どおりならそのままでよい |
WARN |
issue 参照がゼロ | linkage 宣言が無い。追記するかラベル / skip marker で対象外にする |
SKIP |
skip marker / chore / documentation ラベル |
検査対象外 |
NOTICE を PASS と分けているのは、Refs: #N の参照先が issue とは限らず
PR も混在するため（例: PR #1187 → #1169、PR #1195 → #1158 / #1184 は
いずれも PR）。判定器は issue と PR を区別しないので、NOTICE を PASS へ
丸めると「本来 closing すべきなのに書き忘れた PR」を検出する手段がゼロになる。
NOTICE はその弱いシグナルを残すための段であり、強制力は増やさない
（成功側の判定 / CI は緑のまま）。この PR で issue が完結するなら
closes #N に書き換えること。
CI 側の可視面は GitHub Actions の注釈（WARN → ::warning:: /
NOTICE → ::notice::）。いずれも Actions UI と checks サマリには出るが、
PR タイムラインにはコメントを残さない。