ns-gitlab-board-sync

GitLab ボード同期

ローカルの SDD 計画／実行状態を既存の GitLab イシューに反映します。イシューは作成しません。

前提条件

1. GitLab MCP が利用可能であること — すべてのツール呼び出しで mcp-gitlab-usage に従います
2. GitLab MCP サーバーが複数ある場合：どれを使うか人間に確認します
3. docs/context/gitlab-sync-config.md が検証済みであること
4. 計画後の一括処理の場合：gitlab-issue-feature-map.md が存在すること

設定

想定されるフィールドについては、references/gitlab-sync-config.template.md を参照してください。

• project_id、milestone_id、assignee_default
• status_backlog、status_in_progress、status_done、status_blocked
• rf_label_format、base_branch、work_branch、mr_target_branch

不明なステータスラベルは list_project_labels で確認し、人間に確認します。

フロー C — 実装前の読み取り

タスクに GitLab イシューの IID が記載されている場合：

1. read_issue で説明と最近のコメントを読み取ります
2. アクセスできなくても処理を妨げないようにします — 警告を記録して続行します
3. このフローではイシューを変更しません

フロー A — 計画後の一括処理

マップ内の各イシューについて（exclude_issues を除く）：

1. マイルストーンを検証します（プロジェクトとグループ）
2. update_issue で milestone_id を設定します
3. 1 回の set_issue_labels で remove_labels と add_labels をアトミックに実行します（RF、ステータス、担当チーム）
4. assign_issue を実行します
5. リンクされたタスクのヘッダーから set_issue_estimate を設定します（秒）。ただし time_stats.time_estimate が空の場合のみ — 上書きはしません。60 未満の値はスキップします

フロー B — タスクごとの実行同期（レガシー 1:1）

相互排他： delivery-units.md に issue_iid がある場合は、フロー B を実行しません。担当元 = ../ns-spec-driven/references/delivery-units.md の GitLab ステータス／消化時間（SSoT）。

タスクの行がそれぞれ独自の GitLab イシューに 1:1 で対応している場合（delivery units ファイルがない、または未公開ユニットでレガシーの gitlab-issue-feature-map.md がある場合）：

タスク開始時（コーディング前）

remove: status_backlog
add: status_in_progress

コーディング開始時に START_TIME ／ START_EPOCH を記録します（実時間に基づく add_issue_spent_time のため。../ns-execution-gitlab-issue/references/time-tracking.md を参照）。

タスク完了時（検証後）

すでに status_in_progress の場合のみ：

remove: status_in_progress
add: status_done, RF: NNN
add_issue_spent_time
add_issue_comment (internal=true)

バックログから完了へ一度に変更してはいけません。

フロー D — デリバリーユニットごと

SSoT の行がフロー D の場合（issue_iid が公開済みでローカル実行、G なし）のみ実行します。G がライフサイクルを管理している場合は、フロー D 全体をスキップします。

ユニット開始時（ユニット内のタスクのコーディング前）

remove: status_backlog
add: status_in_progress

ユニットのコーディング開始時に START_TIME ／ START_EPOCH を記録します（ユニット単位の消化時間に実時間を使用）。

ユニット完了時（ユニットの検証とレビュー承認後）

すでに status_in_progress の場合のみ：

remove: status_in_progress
add: status_done
add_issue_comment (internal=true)

ローカルのみ（SSoT のフロー D の行）：ユニットごとに 1 回 add_issue_spent_time を含めます（estimate_sum ではなく実時間を使用）。spent_posted を yes に設定します。

バックログから完了へ一度に変更してはいけません。ユニット内のタスクごとに add_issue_spent_time を実行してはいけません。G が同じイシューを管理している場合、フロー D を実行してはいけません。

アンチパターン

誤り	正しい方法
update_issue の assignee	assign_issue
1 回の遷移で 2 回ラベルを呼び出す	1 回のアトミックな set_issue_labels
手動で Milestone: ラベルを設定する	update_issue の milestone_id
消化時間に set_issue_estimate を使う	実時間に基づく期間で add_issue_spent_time を使う
すでに見積もりが設定されているときに set_issue_estimate を使う	スキップ — 既存の値を維持する
計画／estimate_seconds を消化時間の duration として使う	エポック時刻の差分のみを使う（time-tracking.md）
内部メモに公開コメントを使う	internal: true

参考資料

ファイル	用途
references/gitlab-sync-config.template.md	設定の初期化
mcp-gitlab-usage	ツールのスキーマとゲート
../ns-spec-driven/references/delivery-units.md	GitLab ステータス／消化時間（SSoT）