NDF Factory: contracts と進捗の受け口 #2171

親: #2168（Neural Development Factory）。前提: #2169（確定仕様）・#2170（v10.26.0 で完了）。

形と契約は #2169 の確定仕様 docs/specifications/ndf-factory-service-boundary.md の「サービス全体の契約（子課題が実装する）」にある。この課題は集約「進捗の記録」（根: スプリントの実行の識別子ごとの列、エンティティ: 進捗の事象、値オブジェクト: 種類・発生の時刻・冪等の鍵）の持ち主である。2026-10-30 に旧「リポジトリの取り込みとスプリントの並列実行」を 2 本へ分けた前半で、後半の実行の制御とランナーは #2186 が受け持つ。

依頼（原文）

• Devin, Claude Webと同様、github リポジトリをとりこんで開発を進められる
• /ndf:development-workflow のsprintを並列で進めることが可能。
  • sprint一覧でそれぞれがどのフェーズを進めているかが化しかできる
• sprint詳細で進捗状況が可視化できる。

（書き手: 利用者、日付: 2026-10-30。#2168 の構想を伝えた会話の原文のうち、この課題の契約と受け口が下支えする 4 行。全文は #2169 の「依頼（原文）」にある。この課題は画面も実行も持たず、一覧・詳細・承認・課金が読む進捗の事象を受けて残す層を持つ）

親＋機能別の子課題（#2168 を親に子課題 6 本。最初のスプリントは置き場・ライセンスの切り離し・全体設計）

（書き手: 利用者、日付: 2026-10-30。分け方の問いへの回答）

サービスの子課題が共有する機械可読な契約（factory/contracts/）と、進捗の事象を受けて追記する進捗の受け口を作る。2026-10-30 に旧「リポジトリの取り込みとスプリントの並列実行」を 2 本へ分けた前半で、後半の実行の制御とランナーは #2186 が受け持つ。

（書き手: 起票者、日付: 2026-10-30。この課題の旧本文の「何をするか」。分けた経緯の利用者の原文は確かめられないため、利用者の文としては扱わない。範囲の行は確定仕様の「受け持つ課題」の #2171 の行（ゲート 1 で利用者が承認済み）から読む）

起票者の推定

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

目的

• 子課題（NDF Factory: スプリントの実行の制御とランナー #2186・NDF Factory: スプリントの一覧（フェーズ）と詳細（工程・PR・CI・承認ゲート） #2172・NDF Factory: 承認ゲートの通知（Slack を含む）と Web からの承認 #2173・NDF Factory: サブスクリプションと Bedrock の token 課金 #2174・NDF Factory: 手元のマシン（利用者の環境で、利用者の claude ログインで実行する） #2189）が、実行ジョブの指示と進捗の事象を同じ形で読み書きできるように、確定仕様の形を機械可読な定義と TypeScript の型にして 1 か所に置く
• ランナー・GitHub・承認の API から届く進捗の事象を、出所ごとに確かめてからスプリントの実行ごとの列へ 1 度だけ残し、一覧と詳細・承認・課金がそこから導ける状態にする
• 実行ジョブの token を受け口と NDF Factory: 承認ゲートの通知（Slack を含む）と Web からの承認 #2173 の両方が同じ手順で確かめられるようにし、NDF Factory: スプリントの実行の制御とランナー #2186 がその形で token を発行できる状態にする

前提

• 前提 1: DynamoDB の表・API の入口（API Gateway）・IAM のロール・Secrets Manager の秘密はインフラであり、private リポジトリ（owner = volare）が作る。この課題はその定義を書かず、受け取る変数の名前（表の名前・秘密の ARN・api の出所として認めるロールの ARN など）を factory/.env.example に足すだけにする（確定仕様の「データ・設定」。値は書かない、I6）
• 前提 2: 機械可読な定義は factory/contracts/ に置き、NDF Factory: Cognito の認証（Google・GitHub）とプランごとの利用量 #2170 が置いた factory/contracts/openapi/accounts.yaml はパスを変えずにその形へ含める。型の生成の道具と、生成した型をコミットするか検査の中で作るかは設計で決める。どちらでも、定義と型が食い違えば factory/ の npm run check が落ちる
• 前提 3: 実行ジョブの token は、この課題が形と検証を決め、NDF Factory: スプリントの実行の制御とランナー #2186 がその形で発行する。token が運ぶのは実行ジョブの識別子・sprint_run_id・期限で、account_id は載せない（NDF Factory: Cognito の認証（Google・GitHub）とプランごとの利用量 #2170 の約束）。「無効」は、形が違う・署名が合わない・期限が切れた・知らない鍵で作られたのどれかを指す。実行ジョブが終わった後に期限より前で token を取り消す仕組みは、実行ジョブの状態（NDF Factory: スプリントの実行の制御とランナー #2186 の集約）を読む必要があるため、この課題に含めない。期限の長さは実行ジョブの打ち切りの時間（NDF Factory: スプリントの実行の制御とランナー #2186 が実測で決める）から発行側が決める
• 前提 4: token の署名の形（共有の秘密か鍵の組か）と鍵の置き場は設計で決める。どちらでも、鍵は Secrets Manager の ARN（*_SECRET_ARN）だけで受け、値をこのリポジトリ・応答・ログに出さない
• 前提 5: gate.answered の照合が読む「承認の依頼の保存済みの答え」は NDF Factory: 承認ゲートの通知（Slack を含む）と Web からの承認 #2173 の集約で、NDF Factory: 承認ゲートの通知（Slack を含む）と Web からの承認 #2173 はまだ実装されていない。この課題は照合に要る読み出しを差し替えられる口（関数の型）として決め、テストは偽の実装で行う。本物の読み出しは NDF Factory: 承認ゲートの通知（Slack を含む）と Web からの承認 #2173 が同じ口で実装する
• 前提 6: api の出所の認証は、API Gateway の IAM 認可（SigV4 の署名の検証）を前提にし、受け口のコードは要求の文脈に載った呼び出し元の ARN が、変数で受けた NDF Factory: 承認ゲートの通知（Slack を含む）と Web からの承認 #2173 のサービスのロールの ARN と一致するかを確かめる。利用者の Cognito の token で届いた gate.answered は 401 か 403 で拒む
• 前提 7: github の出所では、受け口が GitHub の Webhook の本文（pull_request・check_run）を pr.updated・ci.updated へ翻訳する。宛先のスプリントの実行を Pull Request からどう引くかは未決（未決 1）。引けない Webhook と、扱わない種類の Webhook は 202 で受けて保存しない（GitHub は 2xx 以外を配達の失敗として記録し続けるため）
• 前提 8: 事象 1 件の大きさに上限を置き、超えたら 400 を返す。値は設計で DynamoDB の項目の上限（400 KB）より下に決める。gate.reached の承認資料の本文が上限を超える場合の扱い（本文を別の置き場へ移すなど）は、確定仕様の形を変えるため未決（未決 2）
• 前提 9: payload の鍵の名前と型は、確定仕様の表の意味を変えない詳細として設計で決め、factory/contracts/ に置く。意味を変える・項目を足すときは、確定仕様を直す Pull Request を先に出す（確定仕様の「サービス全体の契約」の冒頭）。phase.changed のフェーズの名前は NDF Factory: スプリントの一覧（フェーズ）と詳細（工程・PR・CI・承認ゲート） #2172 が集合を決めるため、この課題では列挙にせず文字列で受ける
• 前提 10: 実行の制御（NDF Factory: スプリントの実行の制御とランナー #2186）は受け口を通らず進捗の記録へ直に書く（確定仕様）。この課題は、受け口と同じ重複の拒否で 1 件を追記する関数を factory/api/src/index.ts から公開し、NDF Factory: スプリントの実行の制御とランナー #2186 はそれを source が control で呼ぶ
• 前提 11: 進捗の事象を読み出す経路（一覧と詳細の形）は NDF Factory: スプリントの一覧（フェーズ）と詳細（工程・PR・CI・承認ゲート） #2172 が持つ。この課題は表の形（確定仕様の「進捗の正本」の列）を守って書くだけにする

対象範囲

含む:

• factory/contracts/: 確定仕様の「実行ジョブの指示」「進捗の事象の種類と受け口」「進捗の正本」の列から起こした JSON Schema と、受け口の要求と応答の OpenAPI。TypeScript の型の生成と、定義と型の食い違いを落とす検査
• 進捗の受け口（factory/api/）: 出所（runner / api / github）ごとの認証、形の検査、出所と種類と識別子の照合、GitHub の Webhook の翻訳、冪等な追記、202 / 400 / 401 / 403 の応答
• 実行ジョブの token の検証（factory/api/）: token から実行ジョブの識別子と sprint_run_id を返し、無効なら拒む関数。factory/api/src/index.ts から公開する
• 実行の制御が直に書くための追記の関数（前提 10）と、gate.answered の照合の口（前提 5）
• 受け口の handler（Lambda の入口）と、factory/.env.example への変数の名前の追加
• 用語集への語の追加

含まない:

• GitHub App の導入とリポジトリの登録・実行の制御・ランナー・実行ジョブの token の発行（NDF Factory: スプリントの実行の制御とランナー #2186）
• 承認の依頼の保存と、答えを読む経路（NDF Factory: 承認ゲートの通知（Slack を含む）と Web からの承認 #2173。前提 5）
• 進捗の事象からの一覧と詳細の派生と読み出し（NDF Factory: スプリントの一覧（フェーズ）と詳細（工程・PR・CI・承認ゲート） #2172。前提 11）
• 使用量の台帳と請求（NDF Factory: サブスクリプションと Bedrock の token 課金 #2174）
• 実行ジョブの終わりで token を期限より前に取り消す仕組み（前提 3）
• インフラの定義（DynamoDB の表・API Gateway の IAM 認可の設定・ロール・秘密。private リポジトリ側。前提 1）
• 確定仕様の契約の形の変更。変えるなら設計 Pull Request で確定仕様を先に直す

提供する契約

使う契約

ドメインイベント

用語

受け入れ条件

契約（factory/contracts/）:

• 1. factory/contracts/ に、確定仕様の「実行ジョブの指示」の入力（SPRINT_RUN_ID から MODEL_CREDENTIAL_SECRET_ARN までの 11 項目と、START・EXECUTION_MODE による必須の違い）と、「進捗の事象の種類と受け口」の 10 種類の事象（共通の列と種類ごとの payload）が JSON Schema で置かれる。確定仕様の表の行と定義の項目が 1 対 1 に対応する
• 2. 受け口の要求と応答（202 / 400 / 401 / 403）が OpenAPI で置かれ、npm run lint:contracts が 0 で終わる
• 3. TypeScript の型が定義から生成され、定義を変えて型を作り直さないと factory/ の npm run check が落ちる

受け口の認証と照合（出所ごと）:

• 4. runner: 実行ジョブの token の無い・無効な要求は 401 を返し、保存しない
• 5. runner: token の実行ジョブと事象の job_id・sprint_run_id のどちらかが違えば 403 を返し、保存しない
• 6. runner: gate.answered・pr.updated・ci.updated を送れば 403 を返し、保存しない
• 7. runner: 冪等の鍵が token の実行ジョブの形（<job_id>:<seq>、job.finished だけ <job_id>:finished）でなければ 403 を返す
• 8. api: NDF Factory: 承認ゲートの通知（Slack を含む）と Web からの承認 #2173 のサービスのロールでない呼び出し元（利用者の Cognito の token を含む）は 401 か 403 を返し、保存しない
• 9. api: gate.answered 以外の種類は 403 を返す
• 10. api: 依頼の識別子・属するスプリントの実行・種類・答えた人・承認か差し戻しかのどれかが保存済みの答えと違うか、答えが未保存なら 403 を返し、保存しない
• 11. どの出所でも、source と認証の手段が食い違えば 403、種類が 10 種類のどれでもない・schema_version を知らない・payload か共通の列が定義と違えば 400 を返し、保存しない
• 12. github: X-Hub-Signature-256 が Webhook の秘密で合わなければ 401。合った pull_request・check_run は pr.updated・ci.updated として、冪等の鍵 github:<X-GitHub-Delivery の値> と確定仕様の at（受け取った時刻でなく対象の更新時刻）で残す
• 13. 事象 1 件が大きさの上限（前提 8）を超えれば 400 を返し、保存しない

追記と冪等（I10）:

• 14. 受け付けた事象は 202 を返し、sprint_run_id の列へ確定仕様の「進捗の正本」の列（order_key は <at>#<冪等の鍵>）で 1 件残る
• 15. 同じ冪等の鍵の 2 回目は、中身が違っても 202 を返し、1 件目を書き換えず 2 件目を保存しない。同じ鍵を同時に 2 本送っても残るのは 1 件
• 16. 受け口とこの課題の関数に、残った事象を書き換える・消す経路が無い

実行ジョブの token の検証:

• 17. 正しい token から、実行ジョブの識別子と sprint_run_id を返す
• 18. 形が違う・署名が合わない・期限が切れた・知らない鍵で作られた token を、それぞれ拒む（呼び出し側が 401 にできる失敗を返す）
• 19. 検証の関数と、テストで token を作る手段が factory/api/src/index.ts から使え、NDF Factory: スプリントの実行の制御とランナー #2186 が同じ形で発行できることを設計の契約に書く。token の値・署名の鍵は応答とログに出ない

直の追記:

• 20. 実行の制御が呼ぶ追記の関数で job.finished（source が control、冪等の鍵 <job_id>:finished）を書くと、ランナーの job.finished が先にあれば書かれず、無ければ 1 件残る

退行しないこと:

• 21. NDF Factory: Cognito の認証（Google・GitHub）とプランごとの利用量 #2170 のアカウントの API と accounts.yaml の経路・応答が変わらず、factory/ の npm run check と python3 scripts/check-service-boundary.py が 0 で終わる

非機能の条件

影響

検証手段

前提とする取り決め

境界

未決

🤖 Generated with Claude Code

進行

モード: —

• 要求と受け入れ条件 — 2026-10-30 15:03
• 作業場所の用意 — 2026-10-30 16:06
• 設計 — 2026-10-30 15:07
• 素材の収集と出典の確定
• ドキュメント再構成
• ドキュメントレビュー
• 計画 — 2026-10-30 16:06
• 実装 — 2026-10-30 16:06
• 構造改善 — 2026-10-30 17:24
• 実装レビュー — 2026-10-30 17:53
• 完了判定 — 2026-10-30 16:18
• Pull Request — 2026-10-30 16:40
• 確定仕様化 — 2026-10-30 23:54
• 後片付け — 2026-10-30 23:52
• 配布 — 2026-10-30 18:26
• 体裁レビュー
• リリース後テスト — 2026-10-30 23:52
• 振り返り — 2026-10-31 00:01
• 棚卸し — 2026-10-31 00:09

振り返り: #2171 (comment)

閉じた理由

実装（PR #2209）は develop へマージされ、本番 v10.26.1（PR #2218）で配布した。本文の進行はリリース後テスト・振り返り・棚卸しまで済み、振り返りの記録もこの課題のコメントにある。factory/contracts/ の JSON Schema・OpenAPI と進捗の受け口はリポジトリにあり、確定仕様（docs/specifications/ndf-factory-contracts-and-progress.md）も入っている。閉じ忘れとして閉じる。