ns-execution-gitlab-issue

GitLab イシューの実行

外部 GitLab の ISSUE_URL の優先度 1 のエントリです。delivery-units.md に unit + issue_iid が記載されている場合（外部 URL ではない場合）は、以下の SDD ユニットモードを使用します。全体のルーティング：../../ns-harness/references/code-skill-routing.md。

ルーティング（最初に読む）

エントリ優先度 1。ハーネステーブル：../../ns-harness/references/code-skill-routing.md。トリガーフレーズ：references/entry-triggers.md。

ハンドオフ	対象
フェーズ 2 の実行（外部、単一ユニット）	coder-agent → 既存のワークツリー内の ns-coder — ns-autonomous はスキップ（planning-decision.md の単一ユニット、スポーンゲート）
フェーズ 2 の実行（外部、複数ユニット）	ns-autonomous（Engine モード）
フェーズ 2 の実行（SDD ユニット）	../../ns-coder/references/run-implementation.md（ユニットタスクのみ）
MR／ステータス／時間／コメント	mcp-gitlab-usage
フェーズ 4 のレビュゲート	reviewer-agent → ns-reviewer。その後、Code Review: Approved の場合に限り、セッション内で ns-judge を実行
却下後の修正ループ（外部、単一ユニット）	coder-agent / ns-coder（同じワークツリー、A なし）
却下後の修正ループ（外部、複数ユニット）	ns-autonomous → C2（同じワークツリー。A／C2 からこのスキルに再入しない）
却下後の修正ループ（SDD ユニット）	coder-agent → ns-coder / run-implementation（同じワークツリー、ns-autonomous なし）

G は納品まで単独の GitLab ライフサイクルオーナーであり続けます。A の配下で実行する外部の複数ユニットでは、このスキルを再度開いてはいけません。外部の単一ユニットと SDD ユニットのフェーズ 2 では A をスキップします。

セッションの起動

../../ns-harness/references/session-boot.md を参照してください。MCP 呼び出しの前に、そこでセッションの起動を完了してください（ブロッキング）。セッションの起動後に mcp-gitlab-usage を読みます。

入力

変数	必須
ISSUE_URL	外部イシューモードでは必須
unit + issue_iid	SDD ユニットモードでは必須（delivery-units.md から取得）
SOURCE_BRANCH	いいえ — 省略された場合はゲート 1 で解決

外部イシューモード（優先度 1 は変更なし）：イシューごとに単一のワークツリー、単一のブランチ、単一の MR、単一のコミット：

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

SDD ユニットモード — ns-spec-driven が公開済みのデリバリーユニットをディスパッチする場合：

• 入力：delivery-units.md から取得した unit ID（例：unit-001）+ issue_iid — 外部の ISSUE_URL ではありません
• WORKTREE_ROOT = .worktrees/{unit}
• WORK_BRANCH = work/{unit}-{slug}（delivery-units.md / source-branch-resolution.md に従う）
• SOURCE_BRANCH = delivery-units.md のヘッダーに記録された、バージョン解決済みのブランチ（ゲート 1 では同じルールを使用。ヘッダーに設定済みの場合は再検出をスキップ）
• フェーズ 2 のコーディング：ns-autonomous Engine ではなく、ユニットタスクのみを対象とする ../../ns-coder/references/run-implementation.md
• ステータス／作業時間：このスキルがライフサイクルを担当します（最初のアクション + フェーズ 3）。フロー D はスキップしてください。../ns-spec-driven/references/delivery-units.md の **GitLab ステータス／作業時間（SSoT）**を参照します
• add_issue_spent_time はフェーズ 3 でユニットごとに1 回（実経過時間）実行します。タスクごとでも、見積もりの合計でもありません

フェーズ 0 — コンテキスト（MCP の前に起動）

1. セッションの起動（ブロッキング） — MCP 呼び出しの前に ../../ns-harness/references/session-boot.md を完了します。
2. .worktrees/ が gitignore に登録されていることを確認します（references/worktree-setup.md を参照）。
3. 最初の MCP 呼び出しの前に mcp-gitlab-usage を読みます。
4. モードの判定： 外部の ISSUE_URL → 外部イシューモード。delivery-units.md から取得した unit + issue_iid → SDD ユニットモード — 以下で WORKTREE_ROOT、WORK_BRANCH、ISSUE_ID の代替値を設定します。
5. 受け入れ条件の不足（任意の事前ステップ）： AC がない、矛盾している、または自律コーディングに不十分な場合は、先に /ns-requirements-enricher を実行します。エンリッチャーが完了するか、人間が明示的にスキップするまではフェーズ 1 を開始しないでください（status_in_progress にせず、コーディングもしない）。

フェーズ 1 — 準備

最初に行うこと（必須、どのゲートよりも先）

MCP 経由で、課題に status_in_progress（進行中）を適用します。この呼び出しに失敗した場合は、直ちに中止して人間の介入を待ちます。進行中としてマークされていない課題に対して、以下の処理は一切実行しません。

ゲート 0 — 既存ブランチ／MR の再利用

課題に作業ブランチがすでに存在する場合があります（例：人間のレビュー担当者から返却された場合）。重複するブランチ／MR を作成しないよう、ゲート 1 の前に検出します。

外部課題モード：

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}-*" を実行します。

SDD ユニットモード：

1. list_issue_merge_requests — source_branch が work/{unit}-* に一致するオープン中の MR を探します。
2. git ls-remote --heads origin "work/{unit}-*" を実行します。
3. delivery-units.md の行に mr_url がある場合は、これを優先して再利用します。

両モード共通（再利用の判断）：

4. 見つかった場合 → REUSE_MODE = true、WORK_BRANCH = {existing branch}、SOURCE_BRANCH = {existing MR target} とします。以下の WORK_BRANCH の導出とゲート 1 をスキップします（ブランチがリモート上にまだ存在することだけを再確認します）。
5. 見つからなかった場合 → REUSE_MODE = false とし、ゲート 1 に進みます。

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

SDD ユニットモード： delivery-units.md のヘッダーにすでに SOURCE_BRANCH が記録されている場合は、それを使用します。人間がこの実行を上書きしない限り、再検出は行いません。

外部課題モード： references/source-branch-resolution.md のみを使って解決します（優先順位：人間 → 課題のテキスト → プロダクトルール → マイルストーン／バージョンの検出 → 必須の develop フォールバック）。

• 現在のチェックアウトや場当たり的なヒューリスティックから推測することは絶対に避けてください。
• 検出されたバージョン相対の develop_*／develop-* または develop フォールバック以外のブランチを自動的に使用することは絶対に避けてください。その他のベース（homolog、release/*、main、master など）には、この実行中の人間による明示的な確認が必要です。
• main／master を SOURCE_BRANCH として使用できるのは、この実行中に人間から明示的な承認があった場合のみです。自動的に使用してはいけません。課題のテキストで名前が指定されているだけでは不十分です（確認は一度だけ求めます）。

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

ゲート 1.5 — 単一のワークツリー（モノレポ）

references/worktree-setup.md に従って WORKTREE_ROOT を作成します。

• 外部課題モード： .worktrees/{ISSUE_ID}
• SDD ユニットモード： .worktrees/{unit}

.cursor/ の下には作成しないでください。この ID 用のワークツリーがすでに存在し、別の実行で使用中の場合は、明示的な再開でない限り中止します。メインのチェックアウトまたは main／master／SOURCE_BRANCH 上では実装しないでください。git worktree add が失敗した場合は、正確なエラーを出して中止します（メインチェックアウトへのフォールバックは禁止）。分離はフェーズ 2 に進むための必須ゲートです。

MCP のセットアップ

• due_date が空の場合：現在の日付に 5 営業日を加えます。
• ここでは START_TIME を設定しないでください。経過時間の計測はフェーズ 2 で開始します（references/time-tracking.md を参照）。

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

外部イシュー・モード

1. MCP でイシューのペイロード全体（タイトル、説明、コメント、添付ファイル）を読み取ります。下記の見積もりゲートのため、time_stats.time_estimate を確認してください。
2. 最初のコーディング呼び出しの直前、今すぐ START_TIME ／ START_EPOCH を設定します（UTC ＋ Unix エポック）。references/time-tracking.md を参照してください。
3. 計画深度ゲート — A を呼び出す前に、イシューのペイロードに対して ../ns-autonomous/references/planning-decision.md のヒューリスティックを適用します。
   • 単一ユニット（ファイル数が 5 以下／受け入れ条件が 1 段落で、実質的な DAG がない）：ns-autonomous をスキップします。利用可能な場合は coder-agent（それ以外は ns-coder）を WORKTREE_ROOT ／ WORK_BRANCH 内で必ずディスパッチします。ディスパッチの内容は実装のみとし、レビューはフェーズ 4 に延期します（クローズごとに 1 回レビューする ../../ns-harness/references/subagent-dispatch.md の「Review」を参照）。
   • 複数ユニット（Requirements＋tasks の経路）：イシューのペイロード、WORKTREE_ROOT、WORK_BRANCH、SOURCE_BRANCH を渡して、ns-autonomous をエンジンモードで呼び出します。エンジンが計画の深度と疑義プロトコルを決定し、ユニットをディスパッチします。ns-autonomous の references/routing.md を参照してください。
4. 見積もり（初回呼び出し時のみ）： time_stats.time_estimate が空（0 ／欠落）かつワーカー／エンジンが estimate_seconds を 60 以上で返した場合のみ、set_issue_estimate を呼び出します。見積もりがすでに存在する場合、または値が 60 未満の場合はスキップします。上書きや 1 秒の見積もり設定は決して行いません。詳細なルールは references/time-tracking.md を参照してください。
5. 疑義エスカレーションの契約 — エンジンは GitLab の状態を変更しません。エンジンが破壊的な疑義イベントを返した場合（複数ユニットの経路のみ）：
   • PAUSE_START のエポックを記録します（待機時間は作業時間から除外します）。
   • status_blocked（Em Impedimento）を適用します。
   • 質問、選択肢、推奨される既定の対応を記載したコメントを、イシューの作成者（read_issue の @{author.username}）にメンションして投稿します。
   • 同じ質問を対話チャットにも提示して、回答を待ちます。
   • 回答を受け取ったら（チャットおよび／またはイシューのコメント）、待機時間を PAUSED_SECONDS に加算し、ステータスを status_in_progress（Em andamento）に戻して、解決した疑義を追記したうえでエンジンを再度呼び出します。
6. それ以外では途中確認は不要です。このループで一時停止するのはフェーズ 4 のレビューゲートまでです。

SDD ユニット・モード

1. issue_iid に対して read_issue を実行します。説明には実行チェックリストとレビュー用チェックリストがあります。
2. ユニット内の最初のタスクの前に START_TIME ／ START_EPOCH を設定します。
3. WORKTREE_ROOT 内で、ユニットのタスクに限定して ../../ns-coder/references/run-implementation.md を実行します。引き継ぎ行はタスクごとに維持します。ここでは Flow D を使用しません（ステータス／作業時間の管理は G が担当します）。
4. ns-autonomous エンジンはスキップします。タスクごとの add_issue_spent_time もスキップします。
5. 公開時の見積もりはタスクの見積もりの合計（delivery-units.md の estimate_sum）とします。タスクごとに再見積もりはしません。

フェーズ 3 — デリバリー

1. プッシュ前に、Conventional Commit を 1 つにスカッシュします（<type>(#{issue_iid}): <imperative description in English>。type は feat/fix/refactor/test/docs/chore）。外部モードでは、イシュー識別子として ISSUE_ID をメッセージに使用できます。1 回のデリバリーを 1 コミットで原子的に保つため、内部チェックポイントのコミットをスカッシュします。アトリビューションについては ../../ns-harness/references/agent-git-identity.md を参照してください。
2. WORK_BRANCH をプッシュします。
3. フェーズ 4（レビューゲート）を実行します。フェーズ 4 で Code Review: Approved と Delivery Review: Approved の両方が返されるまで、END_TIME、作業時間、Dev 100% を設定しないでください。
4. Approved の場合のみ — 時刻とボードを同時に締めます。
   • 今すぐ END_TIME ／ END_EPOCH を設定します。
   • references/time-tracking.md に従い、duration = ELAPSED_SECONDS（エポック差分から PAUSED_SECONDS を差し引いた値）で add_issue_spent_time を実行します。duration に estimate_seconds や計画上の見積もりを使用してはなりません。このスキルがライフサイクル全体を実行する場合、作業時間の記録担当は 1 つだけです。delivery-units.md の該当行で spent_posted を yes に設定し、Flow D が二重に記録しないようにします。
   • ステータスを status_done（Dev 100%）にします。
   • references/delivery-report.template.md を使用して、内部デリバリーコメント（internal: true）を投稿します。

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

基準となるルール：../ns-reviewer/references/review-gate-workflow.md。

1. 必須：利用可能な場合は reviewer-agent（利用できない場合は ns-reviewer）を Issue review mode で呼び出します — ISSUE_URL または project_id + issue_iid（SDD unit mode）を渡します。ブリッジ／スキルが AGENTS.md を読み込んだ後、レビューワークフローを読み込みます。読み取り専用の コード ゲートで、内部 GitLab コメントを投稿します。AC／requirements.md は解析しません。禁止： 人間がこの実行を明示的に依頼しない限り、タスクサブエージェント（senior-tech-lead-reviewer、bugbot、security-review）やその代替手段を使用すること。許可： ハーネスの reviewer-agent。../../ns-harness/references/subagent-dispatch.md を参照してください。レビューワーは judge をディスパッチしてはなりません。
2. コードループは review-gate-workflow.md の Code 順序付き契約に従います（最大 3 回；Approved = 10）。マップごとにコーダーの対象は 1 つです — 決して分割しません：
   • コール 1／コール 2 が Rejected で残りラウンドがある場合 → マップをそのまま渡し、外部の単一ユニット： coder-agent／ns-coder（同じワークツリー）；外部の複数ユニット： ns-autonomous（同じワークツリー）を1 つの修正ユニットとして使用（マップを分割しない）；SDD unit： coder-agent／run-implementation（同じワークツリー）。次のレビューワープロンプトには delta + 以前のマップ ID を含め、reviewer-agent を使用します（利用可能な場合は必須、利用できない場合は ns-reviewer）。START_TIME を維持します；消費済み／Dev 100% にはしません。judge は使用しません。
   • コール 3 は、その前の 2 回目のコーダー実行後にのみ行います（delta で残存箇所が見つかった場合、および／または Critical が発生した場合）。コール 3 が 10 ではない場合、または Blocked の場合、またはラウンドを使い切った場合 → status_blocked（Em Impedimento）を設定し、指摘事項を投稿して停止します。Blocked の場合、コーダーは実行しません。END_TIME、消費済み、Dev 100% は設定しません。judge は使用しません。
3. Code Review: Approved の場合に限り、セッション内で ../ns-judge/SKILL.md を読み込みます（synthesis から --mode issue --ac-file を使用）。Python は任意です。Delivery Review: Approved は 10 の場合に限ります。Judge が Rejected の場合は、修正マップに従います；プロダクトファイルが変更された場合は、コードレビューを再実施し（Approved が必須）、その後 judge を再実施します。judge のラウンドは最大 3 回です。
4. 両方が Approved → フェーズ 3 のステップ 4（END + 消費時間 + Dev 100% + デリバリーコメント）。
5. 最終出力：Fatto! + MR_URLS + Code Review: {verdict} + Delivery Review: {verdict} — 返された文字列を正確に使用します。

停止して人間に確認する

条件	対応
ゲート 1：リモートに develop のフォールバックがない	停止 — 1 回だけ確認する
ゲート 1：デフォルト以外のベース（main／master／homolog／…）で、今回の実行に対する人間の明示的な確認がない	停止 — 1 回だけ確認する
ワークツリーの競合（同じ issue、別の実行）	明示的な再開指示がない限り停止
受け入れ基準が曖昧または矛盾している	停止 — 先に /ns-requirements-enricher を実行する；フェーズ 1 のコーディングは開始しない
MCP が利用できない、または認証に失敗した	停止 — ブロッカーを伝える
project_id の 3 要素が確認されていない	mcp-gitlab-usage に従って停止
gitlab-sync-config.md に基づき、保護／ベースブランチで作業する場合	停止
破壊的操作（issue の削除、main/master への force-push）	停止 — 人間の明示的な指示が必要
プロダクト上の判断が issue に記載されていない	停止 — 1 回だけ確認する
エンジンが破壊的な疑いを報告した	フェーズ 2 のステップ 4 に従って一時停止／再開 — ハードストップではありません

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

関連スキル

スキル	役割
/ns-requirements-enricher	AC が不完全な場合の任意の事前ステップ — Phase 1 の前
mcp-gitlab-usage	すべての GitLab ツール
ns-gitlab-board-sync	ステータスラベルの意味
ns-reviewer	Phase 4 のコードゲート（利用可能な場合は 必ず reviewer-agent を使用）
ns-judge	Code Review: Approved 後、セッション内での Phase 4 の納品証明
ns-autonomous	Phase 2 のエンジン。複数ユニットの場合のみ
ns-coder	外部の単一ユニットと SDD ユニットのコーディング。GitLab 以外のアドホックな作業

参照資料

ファイル	使用するタイミング
references/source-branch-resolution.md	ゲート 1 — マイルストーン／バージョンの検出、develop へのフォールバック、リモートの検証
references/worktree-setup.md	ISSUE_ID → run_id のオーバーライド（標準的な仕組みは ns-harness に記載）
references/mr-conventions.md	MR のタイトル、ドラフト、リンク付け、再利用に関する注記
references/delivery-report.template.md	Phase 3 の内部納品コメント
references/time-tracking.md	見積もりの未入力時のみの補完、実作業時間の実時間計測と一時停止のルール