NDF Factory: 承認ゲートの通知（Slack を含む）と Web からの承認 #2173

親: #2168（Neural Development Factory）。前提: #2171（実行ジョブの token の検証・進捗の受け口。閉じた）・#2186（実行の制御への再開。閉じた）。承認待ちの一覧（読むだけの画面と API の listApprovalRequests）は #2430 が作る（設計 PR #2570 はマージ済み。一覧を #2430 が受け持つことは利用者が了承済み）。この課題はその画面へ答える操作と通知を足す。受け入れ条件 1・3 の「対応待ち」の一覧と #2430 の一覧との関係は、着手の前に見直す（#2430 の未決 3）。画面の土台は #2382（閉じた）、オフラインで読む形は #2383、API と MCP の形は #2384（閉じた。委任の token は factory/api/src/delegations/ と factory/api/src/auth/resolve.ts にある）に合わせる。

形と契約は サービス全体の確定仕様 の「進捗の事象の種類と受け口」「実行ジョブの指示」と、契約の定義と型・進捗の受け口・実行ジョブの token、実行の制御とランナー にある。この課題は集約「承認の依頼」の持ち主で、gate.answered の書き手、承認の依頼の答えを読む経路（GET /run-jobs/approval-requests/{approvalRequestId}/answer）の実装、実行の制御への再開の要求（requestResume）の呼び手である（確定仕様の「受け持つ課題」の #2173 の行）。

依頼（原文）

• 承認ゲートで通知。Slack通知も設定可能

（書き手: 利用者、日付: 2026-10-30。#2168 の構想を伝えた会話の原文のうち、この課題が受け持つ行。全文は #2169 の「依頼（原文）」にある）

承認ゲート以外のユーザー問い合わせは原則hookで止めてAIが判断するように強制する必要があります。
どうしても判断が不可能な場合(金銭的コストがかかるなど)の場合のみ、AskUserQuestionを出して判断を求めます。

（書き手: 利用者、日付: 2026-10-31。#2206 の「依頼（原文）」。この課題の「判断」の扱いの出所）

承認ゲートに達したスプリントを利用者へ通知し、Web から承認して工程を続けられるようにする。

（書き手: 起票者、日付: 2026-10-30。この課題の旧本文の「何をするか」）

1. 承認ゲート（設計 Pull Request のマージ・本番系へ届く操作）に達すると利用者へ通知が届く（Neural Development Factory: NDF を Web UI で操作できる Software Factory のサービスにする #2168 の条件 7）
2. Slack の通知先を設定できる
3. Web から承認すると工程が続く
4. 承認ゲートの数は増やさない（2 つのまま）

判断（gate.reached の種類「判断」）は、NDF の hook が通した問い合わせだけになる（#2206、2026-10-31 の利用者の方針）。 費用がかかるなど AI が決められないものに限る。画面は承認と分け、判断しなかった理由と見込みの費用を先に出す（モック https://claude.ai/artifact/MYL6CPBTsm6JFTNgtiwY2J ）

（書き手: 起票者、日付: 2026-10-30・2026-10-31。旧本文の「受け入れ条件（案）」。条件 1〜3 は上の利用者の原文と #2168 の受け入れ条件 7 の書き起こし、条件 4 は #2168 の方針の表から引いたもの）

• 承認の判断材料は必ず仕様書とコードまで辿れる。設計文書の節（決定の記録と依拠する確定仕様）は画面の中で開き、コードは GitHub の PR の差分へ飛ばす（差分の閲覧は作らない）。ゲート 2 は中身の行ごとに課題・差分・確定仕様へのリンクを持つ（モック https://claude.ai/artifact/MYL6CPBTsm6JFTNgtiwY2J の「承認ゲートで承認する」）

（書き手: 起票者、日付: 2026-10-31。旧本文の「画面の方針（2026-10-31 の利用者の指摘、モックで確かめる）」。利用者の指摘の原文は課題に無いため、利用者の文としては扱わず、指摘の中身（材料から仕様書とコードへ辿れる・差分の閲覧は作らない）を利用者の方針として読む）

利用者の指示で、マイルストーン「25 Neural Development Factory」の説明にスプリント MVV を置いた（操作性と UX 重視・画面先行・オフライン利用・AI からも人と同じく使える・国や地域を越えて使える。#2168 の方針の表にも同じ行がある）。この課題の画面は #2382（UX の土台）の上に作り、#2383（オフラインで読める）と #2384（API と MCP から画面と同じ操作）の形に合わせる。

（書き手: 起票者、日付: 2026-11-02。旧本文の「前提にする方針」。スプリント MVV そのものは利用者が承認済み）

起票者の推定

題・本文のうち、利用者の指示の原文に無く起票者が推して足した条件。承認ゲート 1 で利用者が確かめるまで、利用者の決定として扱わない。

目的

• スプリントの実行が承認ゲートか判断で止まったことを、利用者が CLI のセッションの前にいなくても知れる状態にする（Neural Development Factory: NDF を Web UI で操作できる Software Factory のサービスにする #2168 の受け入れ条件 7）
• 利用者が Web の画面から、材料を読んで承認・差し戻し・判断への答えを確定でき、確定するとスプリントの実行が新しい実行ジョブで続く状態にする
• 承認を求める種類をゲート 1・ゲート 2 の 2 つのまま保ち、判断と知らせを承認と見分けられる状態にする

前提

• 前提 1: 承認の依頼は、進捗の記録に gate.reached が追記されたことを引き金に、この課題のサービスが 1 件作る。1 つの gate.reached から作る依頼は 1 件で、同じ事象を 2 度読んでも 2 件目を作らない。追記を知る手段（表のストリーム・定期の読み出し）は設計で決める
• 前提 2: 承認の依頼の種類は gate1・gate2・decision の 3 つで、答えを「承認か差し戻し」で求めるのは gate1・gate2 だけである。decision は指示の本文だけを答えとして受ける（確定仕様の I11 と「resume の手順」の表）
• 前提 3: Web の通知は、画面の中の「対応待ち」（答えの無い承認の依頼と未読の知らせ）の一覧と、ナビゲーションに出す件数である。画面は開いている間 30 秒ごとに読み直す（NDF Factory: スプリントの一覧（フェーズ）と詳細（工程・PR・CI・承認ゲート） #2172 の前提 7 と同じ間隔の設定を使う）。ブラウザの押し出しの通知とメールは作らない
• 前提 4: 知らせは、答えを求めない通知である。対象は attention、issue.request_resolved の drafted、decision の承認の依頼の 3 つで、Slack と画面の両方へ出す。decision.delegated（AI が代わりに判断した記録）は知らせにしない（NDF Factory: スプリントの一覧（フェーズ）と詳細（工程・PR・CI・承認ゲート） #2172 が詳細に出す）
• 前提 5: Slack の通知先は、アカウントごとに 1 つの Slack の Incoming Webhook の URL とする。URL は秘密として扱い、保存した後は画面と API に値を返さず、末尾の数字だけを見せる。保存の手段は持ち込んだキーの保存（NDF Factory: スプリントの実行の制御とランナー #2186 の model-credential）と同じ形（Secrets Manager に置き、サービスは ARN だけを持つ）に合わせ、置き場の作成はインフラ（private リポジトリ）が持つ。チームのアカウントで通知先を設定・消去できるのは管理者だけで、個人のアカウントでは持ち主が行う
• 前提 6: 判断の材料に出す「判断しなかった理由」と「見込みの費用」は、gate.reached（decision）の material の本文にあるものを出す。material に無ければその欄に「記録なし」と出し、進捗の事象の形は変えない
• 前提 7: 設計文書の節を画面の中で開く操作は、材料の本文にある、そのスプリントの実行のリポジトリの .md ファイルへのリンク（GitHub の URL）だけに効く。読み出しは GitHub App の導入の token（NDF Factory: スプリントの実行の制御とランナー #2186 の GitHub の口）で、Pull Request の head のコミットのファイルを読み、Markdown として出す。ほかのリポジトリ・ほかの拡張子・外部の URL は新しいタブで開くリンクのまま出す
• 前提 8: ゲート 2 の「中身の行ごとのリンク」は、NDF の承認資料（development-workflow の references/approval-request.md の「対象が複数あるとき」）が行ごとに書く生の URL をリンクとして出すことで満たす。材料の本文を構造へ読み替える解釈は持たない。NDF の承認資料の形は変えない
• 前提 9: Web からの答えは、答えた人が resolveAccount で解決できるアカウントのスプリントの実行の依頼に限り、チームのアカウントでは席を持つ人なら誰でも答えられる。gate.answered の「答えた人のアカウント」は解決の結果の accountId を使う
• 前提 10: 答えの確定はオンラインでだけ行う。オフラインで押した答えは確定させず、つながってから依頼がまだ答えを待っているかをサーバーで照らして確定する（スプリント Value 3）。端末への保存と同期の中身は NDF Factory: つながらないときも、最後に受け取ったスプリントの一覧・詳細・承認資料を端末で読める #2383 が持ち、この課題は画面が NDF Factory: つながらないときも、最後に受け取ったスプリントの一覧・詳細・承認資料を端末で読める #2383 の形を使うところまでを持つ
• 前提 11: 答えを確定できるのは人の Cognito の token だけである。NDF Factory: 画面で行える操作を API と MCP からも同じく行える（機能から起こした配列の入出力・委任の認証・追記だけの操作の記録） #2384 の委任の token（AI のエージェント・MCP のクライアント）は依頼と材料を読めるが、答えの確定は 403 になる（スプリント Value 4）。委任の token の見分けには NDF Factory: 画面で行える操作を API と MCP からも同じく行える（機能から起こした配列の入出力・委任の認証・追記だけの操作の記録） #2384 が入れた factory/api/src/auth/resolve.ts の isDelegationAuthorization を使う
• 前提 12: 答えを保存した後の順序は、答えを依頼へ保存する → gate.answered を IAM ロールの署名で書く → requestResume を呼ぶ、である。requestResume が sprint_run_busy を返したら時間をおいて呼び直し、not_awaiting_approval・not_found なら答えを保存したまま依頼を「再開できない」として画面に理由を出す
• 前提 13: 1 つの依頼への答えは 1 つである。答え済みの依頼へ 2 度目の答えを送ると 409 を返し、先の答えを変えない
• 前提 14: Slack へ送れなかった通知は、画面の対応待ちには必ず出し、Slack へは決めた回数まで送り直す。回数と間隔は設計で決める。送れなかったことは通知先の画面に最後の失敗の日時として出す
• 前提 15: 画面の文言は国際化の仕組み（factory/web/src/i18n/）で持ち、日時は UTC で受けて利用者の時刻帯で出す（スプリント Value 5）。Slack へ送る文の言語は日本語の 1 つとし、言語を足すときに送る側のコードを書き換えずに済む形にする

対象範囲

含む:

• 承認の依頼の集約（作成・保存・答え・状態）と、gate.reached から依頼を作る処理
• 知らせの作成（前提 4）と、画面の対応待ちの一覧・件数
• Slack の通知先の設定・消去・試しに送る操作と、Slack への送信
• 承認の画面（材料の表示・設計文書の節を開く・承認・差し戻し・判断への答え）と、一覧と詳細（NDF Factory: スプリントの一覧（フェーズ）と詳細（工程・PR・CI・承認ゲート） #2172）からの導線
• 答えの保存・gate.answered の書き込み・requestResume の呼び出し
• 答えを読む経路 GET /run-jobs/approval-requests/{approvalRequestId}/answer の実装と、進捗の受け口の保存済みの答えの口（factory/api/src/progress/saved-answers.ts の savedAnswersFromEnv）を本物の読み出しへ替えること
• これらの API の経路と OpenAPI（factory/contracts/openapi/）。入出力は配列で受け渡す（スプリント Value 2）
• 画面の地図（ndf-factory-screen-map.md）の「承認」の行を「未定・予定」から経路のある行へ直すこと

含まない:

• 承認ゲートの数と置き場所の変更（NDF の development-workflow が持つ）
• NDF の hook と ask.jsonl（hook: 承認ゲートの外の問い合わせを止めて AI に判断させ、費用がかかる判断だけを人へ回す #2206。閉じた）、NDF の承認資料の形
• 差分の閲覧（GitHub の Pull Request へ飛ばす）
• ブラウザの押し出しの通知（Web Push）・メール・Slack 以外のチャットへの通知
• Slack App（OAuth でワークスペースへ入れる形）・Slack の画面から答えるボタン
• 端末への保存・暗号化・同期（NDF Factory: つながらないときも、最後に受け取ったスプリントの一覧・詳細・承認資料を端末で読める #2383）、MCP の接続と委任の token と操作の記録の仕組み（NDF Factory: 画面で行える操作を API と MCP からも同じく行える（機能から起こした配列の入出力・委任の認証・追記だけの操作の記録） #2384）
• 開発ループの人の判断待ちへの答え（開発ループの確定仕様 の決定どおりループの行に持ち、承認の依頼にしない）
• Secrets Manager の置き場・IAM ロール・DynamoDB の表・表のストリームなどインフラの定義（private リポジトリ）

ドメインイベント

用語

受け入れ条件

承認の依頼と通知:

• 1. gate.reached（kind が gate1）が追記されると、そのスプリントの実行の承認の依頼が 1 件でき、対応待ちの一覧に種類「ゲート 1」・リポジトリ・課題の番号・Pull Request の URL・止まった日時で出る。gate2 も同じく「ゲート 2」で出る
• 2. 同じ gate.reached を 2 度処理しても、承認の依頼は 1 件のままである
• 3. attention・issue.request_resolved（outcome が drafted）・gate.reached（decision）が追記されると、知らせが対応待ちに出る。decision.delegated は対応待ちに出ない
• 4. 通知先を設定したアカウントでは、条件 1 と 3 の承認の依頼と知らせごとに Slack へ 1 通送り、本文に種類・リポジトリ・課題の番号と承認の画面の URL が入る。材料の本文と秘密は入らない。通知先が無いアカウントでは送らず、対応待ちには出る

承認の画面:

• 5. 承認の画面に材料（material）が Markdown で出て、本文の URL はリンクになる。Pull Request の差分へのリンクは GitHub を新しいタブで開き、画面に差分は出ない
• 6. 材料にある、そのスプリントの実行のリポジトリの .md ファイルへのリンクを押すと、Pull Request の head のコミットのその文書が画面の中に出る。ゲート 2 の材料の行ごとの URL（課題・差分・確定仕様）はそれぞれリンクとして出る
• 7. 判断の依頼の画面は承認の画面と別の見出しを持ち、「判断しなかった理由」と「見込みの費用」の欄を答えの入力欄より上に出す。material に無い欄は「記録なし」と出る。判断の画面に承認と差し戻しのボタンは無く、指示の本文の入力欄と送るボタンだけがある
• 8. ゲートの依頼で承認すると答え（approved）が保存され、gate.answered（decision が approved、答えた人のアカウントは resolveAccount の accountId）が 1 件残り、requestResume が依頼の識別子で 1 度呼ばれる。差し戻しは本文を必須とし、rejected で同じ流れになる
• 9. 答え済みの依頼へ答えを送ると 409 で、保存済みの答えと gate.answered は変わらない。requestResume が not_awaiting_approval を返すと、依頼は「再開できない」になり画面に理由が出る。sprint_run_busy なら送り直し、最後に通れば 1 度だけ再開される
• 10. API は 3 つ目の種類の承認を受け付けない。gate.reached の kind が gate1・gate2・decision のどれでもない値の依頼は作られず、承認を求める欄は画面に 2 種類だけある

通知先:

• 11. 個人のアカウントの持ち主とチームのアカウントの管理者は、通知先の URL を保存・消去でき、保存後の読み出しは URL の値を返さない（末尾の 4 字だけを返す）。チームの席の人の保存・消去は 403 になる
• 12. https://hooks.slack.com/ で始まらない URL は 400 invalid_request で、保存されない
• 13. 「試しに送る」で Slack へ 1 通送り、Slack が 2xx 以外を返したら状態のコードを画面に出す。保存した URL の値は応答・ログ・進捗の事象に出ない

答えを読む経路と受け口:

• 14. GET /run-jobs/approval-requests/{approvalRequestId}/answer は、実行ジョブの token の sprint_run_id と依頼の属する実行が一致し答えが保存済みのとき 200 で kind・decision・body・gate を返す。別の実行の依頼・存在しない依頼は同じ本文の 403、答えがまだ無いと 409、token が無効なら 401 を返す
• 15. 進捗の受け口の api の経路は、保存済みの答えと一致する gate.answered を 202 で残し、一致しないもの・未保存のものを 403 にする。今の 503 の既定は使われない
• 16. 利用者の Cognito の token で gate.answered を受け口へ送ると拒まれる（確定仕様の I28 のまま）

認可・オフライン・委任:

• 17. 承認の依頼の一覧・材料・答えの経路は、他人のアカウント・存在しないアカウント・そのアカウントに属さない依頼・存在しない依頼のどれでも、403 forbidden を同じ本文で返す
• 18. つながりの状態がオフラインのとき、承認・差し戻し・送るのボタンは押せず「つながってから確定します」が出る（ApprovalActions の既存の振る舞い）
• 19. NDF Factory: 画面で行える操作を API と MCP からも同じく行える（機能から起こした配列の入出力・委任の認証・追記だけの操作の記録） #2384 の委任の token（または、それを模した偽の token）で答えを送ると 403 で、答えは保存されない。依頼の一覧と材料は読める
• 20. API が 401 を返すと、画面は token を消してログインの画面へ移る

退行:

• 21. factory/ の npm run check（CI の factory-check）と境界の検査（python3 scripts/check-service-boundary.py）が通る
• 22. 既存の経路（スプリントの一覧と詳細・実行の制御・開発ループの答え）の項目の名前と型は変わらない（足すだけ）。開発ループの人の判断待ちは承認の依頼を作らない

非機能の条件

影響

検証手段

前提とする取り決め

境界

未決

🤖 Generated with Claude Code

進行

モード: —

• 要求と受け入れ条件 — 2026-11-02 13:06
• 作業場所の用意
• 設計 — 2026-11-04 13:07
• 素材の収集と出典の確定
• ドキュメント再構成
• ドキュメントレビュー
• 計画
• 実装
• 構造改善
• 実装レビュー
• 完了判定
• Pull Request
• 確定仕様化
• 後片付け
• 配布
• 体裁レビュー
• リリース後テスト
• 振り返り
• 棚卸し