execute-gitlab-issue

GitLab イシューの実行

GitLab イシューの状態を、ステータス、ブランチ／ワークツリーのライフサイクル、MR、コメント、デリバリー、レビューゲートまで一貫して管理します。実際のコーディングは code-autonomous エンジン（Phase 2）に委任します。

ハーネスの検出

../nextstage-harness/references/harness-discovery.md を参照してください。MCP を呼び出す前に mcp-gitlab-usage を読んでください。

入力

変数	必須
ISSUE_URL	はい
SOURCE_BRANCH	いいえ — 省略された場合は Gate 1 で解決
{product_root}	ワークスペース内に複数の製品がある場合

イシューごとにワークツリー、ブランチ、MR、コミットをそれぞれ 1 つ使用します（モノレポモデル — リポジトリごとのループ処理はありません）。

• WORKTREE_ROOT = {product_root}/.worktrees/{ISSUE_ID}
• WORK_BRANCH = work/{ISSUE_ID}-{ISSUE_SLUG}

Phase 0 — コンテキスト

1. {product_root} を解決します（factory：apps/{slug}/、standalone：リポジトリのルート）。
2. 製品のコンテキストを読み込みます。../nextstage-harness/references/artifact-layout.md の実装起動ルールに従ってください。
3. .worktrees/ が gitignore に含まれていることを確認します（references/worktree-setup.md を参照）。

Phase 1 — 準備

最初の操作（必須。いずれかのゲートより前に実行）

MCP 経由でイシューに status_in_progress（Em andamento）を適用します。この呼び出しが失敗した場合は、直ちに中止して人間の介入を待ってください。進行中としてマークされていないイシューに対して、以降の処理は実行しません。

Gate 0 — 既存ブランチ／MR の再利用

イシューには、すでに作業ブランチがある場合があります（例：人間のレビュアーから差し戻された場合）。Gate 1 の前に検出し、重複するブランチ／MR を作成しないようにします。

1. list_issue_merge_requests — source_branch が work/{ISSUE_ID}-* に一致するオープン中の MR を探し、その source_branch と target_branch を記録します。
2. 2 つ目の手掛かりとして git ls-remote --heads origin "work/{ISSUE_ID}-*" を実行します。
3. 見つかった場合 → REUSE_MODE = true、WORK_BRANCH = {existing branch}、SOURCE_BRANCH = {existing MR target} とします。以下の WORK_BRANCH の導出をスキップし、Gate 1 もスキップします（ブランチがリモートにまだ存在することのみ再検証します）。
4. 見つからない場合 → REUSE_MODE = false とし、Gate 1 に進みます。

Gate 1 — SOURCE_BRANCH（必須、ブロッキング。REUSE_MODE = true の場合はスキップ）

SOURCE_BRANCH は references/source-branch-resolution.md のみを使って解決します（優先順位：人間 → イシュー本文 → 製品ルール → マイルストーン／バージョンの検出 → 必須の develop フォールバック）。

• 現在のチェックアウトや場当たり的な推測から、決して推定しないでください。
• 検出されたバージョン相対の develop_*／develop-*、または develop フォールバック以外のブランチを、決して自動的に使用しないでください。その他のベース（homolog、release/* など）には、この実行中に人間による明示的な確認が必要です。
• イシューに記載されていても、main／master は常に SOURCE_BRANCH として無効です。

解決後、同じリファレンスに従ってリモート上で検証します（fetch、ls-remote、_ ↔ - の代替名）。必須の develop フォールバックがリモートに存在しない場合は、正確なエラーを出して中止します。オペレーターには一度だけ確認します。

Gate 1.5 — 単一ワークツリー（モノレポ）

references/worktree-setup.md に従って WORKTREE_ROOT を作成します。常に {product_root}/.worktrees/{ISSUE_ID} を使用し、.cursor/ 配下には作成しません。この ISSUE_ID 用のワークツリーがすでに存在し、別の実行で使用中の場合は、明示的な再開でない限り中止します。メインのチェックアウトや main／master／SOURCE_BRANCH 上で実装してはいけません。git worktree add が失敗した場合は、正確なエラーを出して中止します（「作業を続けるため」にメインのチェックアウトへフォールバックしてはいけません）。Phase 2 の前に、分離は必須のゲートです。

MCP のセットアップ

• due_date が空の場合：現在の日付 + 5 営業日。
• START_TIME = ISO 8601 UTC タイムスタンプ。
• code-autonomous エンジンがプランに基づく見積もりを返したら、set_issue_estimate を一度実行します（Phase 2、step 2）。

フェーズ 2 — 実行（委任）

1. MCP を使用してイシューのペイロード全体（タイトル、説明、コメント、添付ファイル）を読み取ります。
2. Engine モードで code-autonomous スキルを呼び出し、イシューのペイロード、{product_root}、WORKTREE_ROOT、WORK_BRANCH、SOURCE_BRANCH を渡します。エンジンは計画の深さを自ら判断し、疑義プロトコルを実行して、WORKTREE_ROOT 内で実装（単一エージェントまたはマルチエージェント）をディスパッチします。「Engine モード」の意味と返される内容については、code-autonomous の references/routing.md を参照してください。
3. エンジンの初回呼び出しで返された見積もりを使用して、set_issue_estimate を呼び出します。
4. 疑義エスカレーション契約 — エンジン自体は GitLab の状態を変更しません。ユニットの結果の代わりに、または結果に加えて破壊的な疑義イベントが返された場合：
   • status_blocked（Em Impedimento）を適用します。
   • イシューの作成者（read_issue の @{author.username}）に言及し、質問、選択肢、推奨する既定の選択肢を含むコメントを投稿します。
   • 同じ質問を対話型チャットにも投稿して、回答を待ちます。
   • 回答を受け取ったら（チャットおよび／またはイシューコメント）、記録し、ステータスを status_in_progress（Em andamento）に戻して、解決した疑義をコンテキストに追加したうえでエンジンを再度呼び出します。
5. それ以外では途中確認を行いません — フェーズ 4 のレビューゲートまで、このループが唯一の一時停止ポイントです。

フェーズ 3 — 提出

1. プッシュ前に、1 つの Conventional Commit にスカッシュします（<type>(#{ISSUE_ID}): <imperative description in English>、type は feat/fix/refactor/test/docs/chore）。エンジンはフェーズ 2 で作業単位ごとに内部チェックポイントコミットをワークツリーに残す場合があります。ここでそれらをスカッシュし、提出ごとに 1 コミットとする原子性を保ちます。帰属情報については ../nextstage-harness/references/agent-git-identity.md を参照してください。
2. WORK_BRANCH をプッシュします。
3. add_issue_spent_time（ELAPSED_SECONDS = max(1, ceil(END_TIME - START_TIME))）を実行します。
4. フェーズ 4 が Approved を返した後に限り、ステータスを status_done（Dev 100%）にします。それ以前に設定してはいけません。
5. references/delivery-report.template.md を使用して、内部提出コメント（internal: true）を投稿します。

フェーズ 4 — レビューゲート（ブロッキング、回数制限付き修正ループ）

1. Issue review モード（ISSUE_URL）で code-reviewer を呼び出します。読み取り専用の正式なゲートで、内部 GitLab コメントを投稿します。
2. 最大 3 ラウンドでループします。
   • Approved → フェーズ 3 のステータス／コメントのクローズ処理に進みます（Dev 100%）。
   • Rejected で残りラウンドがある場合 → 指摘事項を修正作業単位として、同じワークツリー／ブランチで code-autonomous を再度呼び出し、その後再レビューします。
   • Blocked、またはラウンド数の上限に達した場合 → status_blocked（Em Impedimento）にし、指摘事項を投稿して終了します。Dev 100% にしてはいけません。
3. 最終出力：Fatto! + MR_URLS + Code Review: {verdict} — code-reviewer が返した verdict 文字列をそのまま使用します。

停止して人間に確認する

条件	アクション
ゲート 1：リモートに develop のフォールバックがない	停止 — 1 回だけ確認する
ゲート 1：人間の確認がない、許可されていないベースブランチ	停止 — 1 回だけ確認する
ワークツリーの競合（同じイシュー、別の実行）	明示的な再開指示がない限り停止する
受け入れ条件が曖昧、または矛盾している	停止 — 1 回だけ確認する
MCP が利用不可、または認証に失敗	停止 — ブロッカーを伝える
project_id の 3 点セットが確認されていない	mcp-gitlab-usage に従って停止する
gitlab-sync-config.md に基づく保護対象／ベースブランチでの作業	停止
破壊的な操作（イシューの削除、main/master への強制プッシュ）	停止 — 人間による明示的な承認が必要
イシューにプロダクト上の決定が記載されていない	停止 — 1 回だけ確認する
エンジンが破壊的な懸念を報告した	フェーズ 2 のステップ 4 に従って一時停止／再開 — 完全停止ではない

MCP ツールの契約と確認ゲートについては、mcp-gitlab-usage を参照してください。

関連スキル

スキル	役割
mcp-gitlab-usage	すべての GitLab ツール
gitlab-board-sync	ステータスラベルの意味
code-reviewer	フェーズ 4 のゲート
code-autonomous	フェーズ 2 の実行エンジン
code-coder	GitLab 以外でのアドホックな実装

参照資料

ファイル	使用する場面
references/source-branch-resolution.md	ゲート 1 — マイルストーン／バージョンの検出、develop のフォールバック、リモートの検証
references/worktree-setup.md	ISSUE_ID → run_id の上書き（標準的な仕組みは nextstage-harness に記載）
references/mr-conventions.md	MR のタイトル、ドラフト、関連付け、再利用の注記
references/delivery-report.template.md	フェーズ 3 の内部向けデリバリーコメント