ADR-0026: slice_id自動同期GitHub Actionsの導入

• Status: Accepted
• Mode: Standard
• Kruchten Type: Existence
• Scope: platform
• Implementation Status: Done (sync_slice_id.yml GitHub Actions 実装済)
• 起案者: [email protected]
• 起案日時 (JST): 2026-05-13 01:00
• 承認日時 (JST): 2026-05-13 01:15
• Deciders: [email protected] (単独)

Kruchten Type は ADR-0031 (2026-05-13) で遡及追加。分類根拠は ADR-0031 §決定セクションおよび docs/adr/README.md の Kruchten 3 分類ガイドを参照。 Status / Mode / Scope は 2026-06-11 に遡及追加 (ADR-0031 corrigendum パターン)。出典: Status = 旧形式「## ステータス」節の機械転記 / Mode = 旧 README §既存 ADR 一覧の推定値 (git 履歴) / Scope = ADR-0049 4 層分類の遡及付与 (PR レビューで確定)。

コンテキスト

1.1 背景 (Background)

ADR-0021 で「UC 軸 SSoT + 技術軸 Cross-Reference」の二重ビュー方針を採用したが、Gate 3 のレビュー時点で懸念点 D1（Markdown 二重メンテ）が明示的に積み残されていた。

1.2 現状 (Current State / As-Is)

usecase_dev_mapping.md（UC 軸）と todo_master_tables.md（技術軸）の slice_id 列は現在手動で同期されており、Single Source of Truth (SSoT) として usecase_dev_mapping.md を扱っているが、技術軸ファイルへの反映は人手によるコピー作業に依存している。

1.3 課題 (Problem)

276 件の MAS 案件を対象に月複数回の更新が発生するため、手動同期では必ず同期漏れが発生し、ドリフト (UC 軸と技術軸の slice_id 不一致) が監査トレーサビリティを損なう。ADR-0021 の Gate 3 で懸念点 D1 として明示済の問題。

1.4 制約・要件 (Constraints & Requirements)

判断基準として以下の 4 点を満たす必要がある:

• 自動化率: 手動操作ゼロで slice_id 列が常に最新を保てること
• 障害安全性: sync 失敗時に即座に検知・Issue 起票できること
• 手動上書き耐性: 誤った手動編集を次回 cron で自動修正できること
• 実装コスト: 既存 GitHub Actions 基盤（markdown-link-check.yml）を流用できること

1.5 目標 (Goals / To-Be)

GitHub Actions による自動同期基盤を導入し、ADR-0021 の二重ビュー運用を持続可能にする。Non-Goals: todo_master_tables.md の slice_id 以外の列の同期、UC 軸以外の SSoT 化。

決定

GitHub Actions ワークフロー sync_slice_id.yml と Node.js スクリプト .github/scripts/sync_slice_id.mjs を新規作成し、usecase_dev_mapping.md を SSoT として todo_master_tables.md の slice_id 列を自動同期する。トリガーは usecase_dev_mapping.md の push / PR / 毎日 JST 02:00 cron（UTC 17:00）とし、差分検出時は chore/auto-sync-slice-id-{date} ブランチで自動コミット + PR 作成、障害発生時は actions/github-script で auto-sync-broken ラベル付き Issue を自動起票する。あわせて .github/pull_request_template.md を新規作成し、slice_id 必須欄・Walking Skeleton 4 要素チェック・実行時間見積もり欄を運用に組み込む。

検討した代替案 (Alternatives Considered)

• 案 A【採用】GitHub Actions による自動同期: 既存の Actions 基盤（markdown-link-check.yml）を流用でき、障害時の Issue 起票・手動再実行（workflow_dispatch）・cron による定期修正が容易。GitHub ネイティブで追加インフラ不要。
• 案 B【不採用】Cloudflare Workers Cron から同期: Decision Pipeline と同じ Workers 基盤を活用できるが、GitHub API 認証・リポジトリへの書き込み権限管理が複雑になる。Actions の方が GitHub ネイティブで権限モデルが単純なため不採用。
• 案 C【不採用】手動同期（規則のみ定義）: 実装コストがゼロだが ADR-0021 の Gate 3 懸念点 D1（Markdown 二重メンテ）を解消できない。276 件 × 月複数回の更新で必ず漏れが発生し、監査時のトレーサビリティが損なわれるため不採用。

影響 (Consequences)

5.1 正の影響 (Good)

• ADR-0021 の懸念点 D1（Markdown 二重メンテ）が技術的に解消され、二重ビュー方針が持続可能になる
• 手動操作ゼロで slice_id 列のドリフトを防止でき、監査トレーサビリティが向上
• 誤った手動編集も次回 cron（JST 02:00）で自動修正される
• PR テンプレートにより Walking Skeleton 4 要素（認証/DDL/監査ログ/Feature Flag）の遵守が CI レベルで担保される
• GitHub Actions 無料枠内（月 2,000 分）で運用でき、追加コストなし

5.2 負の影響 (Bad)

• .github/workflows/sync_slice_id.yml、.github/scripts/sync_slice_id.mjs、.github/pull_request_template.md の新規ファイル 3 点の保守責任が発生
• todo_master_tables.md の slice_id 列が自動更新対象となるため、当該列への手動編集は次回 sync で上書きされる前提を周知する必要がある
• 実装コスト合計 約 5.5 時間（スクリプト 3h / ワークフロー 1h / PR テンプレ 0.5h / テスト 1h）

5.3 中立・トレードオフ (Neutral / Trade-offs)

• sync ワークフローが 3 連続失敗した場合、ADR-0021 撤退トリガー (a) のカウント対象となる (リスク)
• usecase_dev_mapping.md の Markdown 構造が変わると sync_slice_id.mjs のパーサーが破損する可能性 (リスク、→ Issue 自動起票で検知)

撤退条件 (Rollback Plan)

以下のいずれかに該当した場合、2 週以内に廃止 ADR を起案する:

• sync ワークフローが 3 連続失敗（ADR-0021 撤退トリガー (a) のカウント対象）
• 手動メンテの工数が自動化メリットを上回ると月次レビューで判断した場合

判定指標としては、auto-sync-broken ラベルの Issue 起票頻度、workflow_dispatch による手動再実行回数、月次レビューでの運用工数見積もりを用いる。代替案としては案 C（手動同期）への一時的フォールバック、または案 B（Cloudflare Workers Cron）への再評価を行う。

完了条件 (観測可能な指標)

• workflow_dispatch で手動実行し、todo_master_tables.md の slice_id 列が usecase_dev_mapping.md と一致すること
• usecase_dev_mapping.md を不正形式に編集した際に Issue が自動起票されること（label: auto-sync-broken）
• 新規 PR 作成時に pull_request_template.md のチェックボックスが表示されること

Confirmation (準拠確認 / Fitness Function)

本セクションは ADR-0036 (Accepted 2026-05-14) で遡及追加された。ADR-0031 パターン (業界標準準拠メタデータ後付け = 誤字修正範疇) に準拠する遡及で本文の意思決定内容は不変。

• 検証手段: Pipeline Gate 2 (consistency) + LiteLLM ログ集計
• 実行頻度: PR ごと
• 違反時の対応: 自動 fail

参照 (References)

• 関連 ADR: ADR-0021（二重ビュー方針 / Gate 3 懸念点 D1 / 撤退トリガー (a)）に準拠
• 関連 PR/Issue: -（要追記）
• 外部資料:
  • .github/workflows/sync_slice_id.yml（新規）
  • .github/scripts/sync_slice_id.mjs（新規）
  • .github/pull_request_template.md（新規）
  • docs/_internal/todo_master_tables.md（slice_id 列が自動更新対象）
  • docs/_internal/usecase_dev_mapping.md（SSoT として更新トリガー源）
  • 既存基盤: .github/workflows/markdown-link-check.yml