Vercel Root Directory 修正 実施手順書（API完全自動化版）

1. 現状の把握

1.1 Vercelプロジェクト設定（読み取り実施済）

1.2 現行本番の状態（ロールバック用に記録）

1.3 プレビューデプロイが失敗している原因

1.4 現状の"本番だけ動いている"仕組み

• 本番: GitHub Actions（.github/workflows/deploy.yml）が working-directory: ./frontend を明示指定して vercel deploy --prod を実行。CLI経由の場合はカレントディレクトリの内容がアップロードされるため Root Directory設定を回避できている
• プレビュー: Vercelの Git連携（自動）と GHAの両方が走る。Git連携側は Root Directory = . のため失敗する

1.5 frontend/ から親ディレクトリ参照の有無（researcher 実証済）

2. 実施方式の選定（REST API を採用）

2.1 検討した3案

2.2 REST API が本タスクに適する理由

• Vercel公式仕様で PATCH /v9/projects/{idOrName} の rootDirectory フィールド更新が明記されている
• Root Directory 変更の Save 操作（API PATCH でも同じ）は既存デプロイ・エイリアス・環境変数に影響しない（researcher が公式ドキュメントで裏付け済）
• 実行主体を W層に閉じられるため、CEO のブラウザ操作をゼロにできる（CEO 指示の要件を満たす）
• スクリプト化することでロールバックも同じ経路で実行でき、手順の再現性が高い

3. 実施前チェックリスト（API版）

すべてのAPI呼び出しは以下の共通ヘッダーを使う。$VERCEL_TOKEN は W層ローカル環境変数または ~/.vercel/auth.json から取得（9章参照）。teamId は クエリで指定。

export VERCEL_TOKEN="..."
export TEAM_ID="team_bjNOf7D5Ocbim0GFcZjFvjph"
export PROJECT="shift-scheduler-ai"
export API="https://api.vercel.com"

3.1 VERCEL_TOKEN の疎通確認（GET /v2/user）

curl -sS -H "Authorization: Bearer $VERCEL_TOKEN" \
  "$API/v2/user" | jq '{username: .user.username, email: .user.email}'

期待: {"username":"...", "email":"..."} が返る。401 の場合はトークン失効。

• HTTP 200 が返る
• 期待するユーザー（info-mnml 系）が識別される

3.2 現行プロジェクト設定のスナップショット（GET /v9/projects/{project}）

curl -sS -H "Authorization: Bearer $VERCEL_TOKEN" \
  "$API/v9/projects/$PROJECT?teamId=$TEAM_ID" \
  | jq '{id, name, framework, rootDirectory, buildCommand, outputDirectory, nodeVersion}' \
  | tee /tmp/vercel_project_before_20260702.json

期待: rootDirectory: null（= . と同義）または "."、その他は 1.1 の記載通り。

• rootDirectory が null または "." であることを確認
• framework が "vite" であることを確認

3.3 現行本番デプロイのスナップショット（GET /v6/deployments）

curl -sS -H "Authorization: Bearer $VERCEL_TOKEN" \
  "$API/v6/deployments?projectId=prj_1atBNQYyVnXbrisEdejO4XA7J3nA&teamId=$TEAM_ID&target=production&limit=5" \
  | jq '.deployments[] | {uid, url, state, target, created, aliasAssigned}' \
  | tee /tmp/vercel_deployments_before_20260702.json

期待: 先頭行に uid: "dpl_DBWQTztKF4kpqA7Abz8kpjr31Beq"、state: "READY"、target: "production"。

• 現行本番デプロイID dpl_DBWQTztKF4kpqA7Abz8kpjr31Beq が返る
• state が READY

3.4 現行本番エイリアスのスナップショット（GET /v4/aliases）

curl -sS -H "Authorization: Bearer $VERCEL_TOKEN" \
  "$API/v4/aliases?projectId=prj_1atBNQYyVnXbrisEdejO4XA7J3nA&teamId=$TEAM_ID&limit=20" \
  | jq '.aliases[] | {alias, deploymentId, created}' \
  | tee /tmp/vercel_aliases_before_20260702.json

期待: alias: "shift-scheduler-ai-sepia.vercel.app" の deploymentId が dpl_DBWQTztKF4kpqA7Abz8kpjr31Beq。

• sepia エイリアスが dpl_DBWQTztKF4kpqA7Abz8kpjr31Beq に紐づいている

3.5 環境変数一覧のスナップショット（GET /v9/projects/{project}/env）

curl -sS -H "Authorization: Bearer $VERCEL_TOKEN" \
  "$API/v9/projects/$PROJECT/env?teamId=$TEAM_ID" \
  | jq '.envs[] | {key, target, type, updatedAt}' \
  | tee /tmp/vercel_env_before_20260702.json

期待: 12エントリ（8キー × 環境）。値は返らない（暗号化）。以下の8キーが揃っていることを確認する。

• 8キーすべてが返る
• 合計12エントリ
• Basic Auth 系の2キーが production に存在する

4. 実施ステップ（API版）

4.1 Root Directory 変更（PATCH /v9/projects/{project}）

curl で1回の PATCH を発行するだけで完了する。以下はコード例（実行はまだしない。M層承認後に W層が実施）。

curl 版

curl -sS -X PATCH \
  -H "Authorization: Bearer $VERCEL_TOKEN" \
  -H "Content-Type: application/json" \
  "$API/v9/projects/$PROJECT?teamId=$TEAM_ID" \
  -d '{"rootDirectory": "frontend"}' \
  | jq '{id, name, rootDirectory, updatedAt}'

Python 版（W層 researcher / coder がオンザフライ実行）

import os, httpx, json

VERCEL_TOKEN = os.environ["VERCEL_TOKEN"]
TEAM_ID = "team_bjNOf7D5Ocbim0GFcZjFvjph"
PROJECT = "shift-scheduler-ai"

with httpx.Client(base_url="https://api.vercel.com", timeout=30.0) as client:
    resp = client.patch(
        f"/v9/projects/{PROJECT}",
        params={"teamId": TEAM_ID},
        headers={"Authorization": f"Bearer {VERCEL_TOKEN}"},
        json={"rootDirectory": "frontend"},
    )
    resp.raise_for_status()
    data = resp.json()
    print(json.dumps({
        "id": data["id"],
        "name": data["name"],
        "rootDirectory": data["rootDirectory"],
        "updatedAt": data.get("updatedAt"),
    }, indent=2))

4.2 変更確認（GET /v9/projects/{project}）

curl -sS -H "Authorization: Bearer $VERCEL_TOKEN" \
  "$API/v9/projects/$PROJECT?teamId=$TEAM_ID" \
  | jq '{rootDirectory, framework, buildCommand, outputDirectory}' \
  | tee /tmp/vercel_project_after_20260702.json

• rootDirectory が "frontend" になっている
• 他のフィールド（framework / buildCommand / outputDirectory）は変化なし

4.3 環境変数の再確認（GET /v9/projects/{project}/env）

curl -sS -H "Authorization: Bearer $VERCEL_TOKEN" \
  "$API/v9/projects/$PROJECT/env?teamId=$TEAM_ID" \
  | jq '.envs[] | {key, target, type}' \
  | tee /tmp/vercel_env_after_20260702.json

diff /tmp/vercel_env_before_20260702.json /tmp/vercel_env_after_20260702.json

期待: diff がゼロ行（環境変数はRoot Directory変更の影響を受けない）。

4.4 自動再デプロイは走らないことの確認（GET /v6/deployments）

curl -sS -H "Authorization: Bearer $VERCEL_TOKEN" \
  "$API/v6/deployments?projectId=prj_1atBNQYyVnXbrisEdejO4XA7J3nA&teamId=$TEAM_ID&limit=5" \
  | jq '.deployments[] | {uid, state, target, created}'

期待: 最上段は依然として dpl_DBWQTztKF4kpqA7Abz8kpjr31Beq。新規デプロイは作成されていない。

5. 本番影響ゼロの根拠

5.1 現行本番エイリアスが動かない理由

5.2 API で継続稼働を確認する手順

4.1 の PATCH 直後、以下2つのAPIで sepia の指し先が変わっていないことを機械的に確認できる。

# (a) alias → deploymentId の紐づけ確認
curl -sS -H "Authorization: Bearer $VERCEL_TOKEN" \
  "$API/v4/aliases/shift-scheduler-ai-sepia.vercel.app?teamId=$TEAM_ID" \
  | jq '{alias, deploymentId, projectId}'

# 期待: deploymentId が "dpl_DBWQTztKF4kpqA7Abz8kpjr31Beq" のまま

# (b) 本番デプロイ一覧で先頭が otzjjwe68 のまま
curl -sS -H "Authorization: Bearer $VERCEL_TOKEN" \
  "$API/v6/deployments?projectId=prj_1atBNQYyVnXbrisEdejO4XA7J3nA&teamId=$TEAM_ID&target=production&limit=1" \
  | jq '.deployments[0] | {uid, state}'

# 期待: {"uid": "dpl_DBWQTztKF4kpqA7Abz8kpjr31Beq", "state": "READY"}

5.3 変更中に本番エイリアスが別デプロイに切り替わるリスク

6. 検証手順（API版）

6.1 本番URL疎通確認（curl で Basic Auth 継続動作）

# 401 が返り、WWW-Authenticate: Basic が付与されていることを確認
curl -sS -o /dev/null -w "HTTP %{http_code}\n" \
  "https://shift-scheduler-ai-sepia.vercel.app/"

curl -sSI "https://shift-scheduler-ai-sepia.vercel.app/" \
  | grep -i "www-authenticate"

• HTTP 401 が返る（Basic Auth 保護が継続）
• WWW-Authenticate: Basic realm=... ヘッダーが返る
• 認証情報（Basic Auth）を付与した curl で 200 が返る（値は Vercel 上で暗号化保存されているため、CEOがブラウザで一度確認する方が安全）

6.2 sepia が otzjjwe68 に紐づいたままであることを再確認

curl -sS -H "Authorization: Bearer $VERCEL_TOKEN" \
  "$API/v4/aliases/shift-scheduler-ai-sepia.vercel.app?teamId=$TEAM_ID" \
  | jq '.deploymentId'

# 期待: "dpl_DBWQTztKF4kpqA7Abz8kpjr31Beq"

6.3 ダミーPRでプレビュー成功確認（API版）

1. ローカルで軽微な変更（例: README末尾に空行1個追加）を行い、feature branch を作成:

   cd ~/Dev/mnml/shift
   git checkout -b test/vercel-root-dir-verify
   echo "" >> README.md
   git add README.md
   git commit -m "test: verify vercel preview after root dir fix"
   git push origin test/vercel-root-dir-verify

2. GitHubで PR を作成（ドラフトPRでよい）。以下で作成可能:

   gh pr create --draft \
     --title "test: verify vercel preview after root dir fix" \
     --body "verification only. do not merge."

3. 数分後、プレビューデプロイの状態を API で確認:

   curl -sS -H "Authorization: Bearer $VERCEL_TOKEN" \
     "$API/v6/deployments?projectId=prj_1atBNQYyVnXbrisEdejO4XA7J3nA&teamId=$TEAM_ID&target=preview&limit=5" \
     | jq '.deployments[] | {uid, state, target, meta: .meta.githubCommitRef, created}'

   期待: 最新のfeature branch（test/vercel-root-dir-verify）を meta.githubCommitRef に持つプレビューデプロイが state: "READY" になっている（Vercel Git連携経由）。
4. ビルドログを確認して "Missing script: build" が消えていることを確認:

   DEPL_ID=$(curl -sS -H "Authorization: Bearer $VERCEL_TOKEN" \
     "$API/v6/deployments?projectId=prj_1atBNQYyVnXbrisEdejO4XA7J3nA&teamId=$TEAM_ID&target=preview&limit=1" \
     | jq -r '.deployments[0].uid')
   
   curl -sS -H "Authorization: Bearer $VERCEL_TOKEN" \
     "$API/v3/deployments/$DEPL_ID/events?teamId=$TEAM_ID&limit=200" \
     | jq -r '.[] | .text' | grep -Ei "build|error|missing" | head -30

5. プレビューURLを curl で疎通確認（本番と同じく 401 Basic Auth が返るはず）:

   PREV_URL=$(curl -sS -H "Authorization: Bearer $VERCEL_TOKEN" \
     "$API/v6/deployments?projectId=prj_1atBNQYyVnXbrisEdejO4XA7J3nA&teamId=$TEAM_ID&target=preview&limit=1" \
     | jq -r '.deployments[0].url')
   curl -sS -o /dev/null -w "HTTP %{http_code}\n" "https://$PREV_URL/"

6. 確認完了後、ドラフトPRをクローズし、ブランチを削除:

   gh pr close --delete-branch $(gh pr view --json number -q .number)

7. ロールバック手順（API版）

7.1 Root Directory を元に戻す（frontend → null）

curl -sS -X PATCH \
  -H "Authorization: Bearer $VERCEL_TOKEN" \
  -H "Content-Type: application/json" \
  "$API/v9/projects/$PROJECT?teamId=$TEAM_ID" \
  -d '{"rootDirectory": null}' \
  | jq '{rootDirectory, updatedAt}'

# 期待: {"rootDirectory": null, ...}

戻すだけの操作は再デプロイを起動しないため、本番URLへの影響は「なし」。

7.2 万が一エイリアスが別デプロイに切り替わった場合の即時復元

1. 現状の sepia 指し先を確認:

   curl -sS -H "Authorization: Bearer $VERCEL_TOKEN" \
     "$API/v4/aliases/shift-scheduler-ai-sepia.vercel.app?teamId=$TEAM_ID" \
     | jq '{alias, deploymentId}'

2. 元の dpl_DBWQTztKF4kpqA7Abz8kpjr31Beq に再エイリアス（POST /v2/aliases）:

   curl -sS -X POST \
     -H "Authorization: Bearer $VERCEL_TOKEN" \
     -H "Content-Type: application/json" \
     "$API/v2/aliases?teamId=$TEAM_ID" \
     -d '{
       "alias": "shift-scheduler-ai-sepia.vercel.app",
       "deploymentId": "dpl_DBWQTztKF4kpqA7Abz8kpjr31Beq"
     }' | jq '{alias, deploymentId, status}'

   参考: 公式では POST /v13/deployments/{id}/aliases も使えるが、deploymentId を直接指定できる /v2/aliases を採用（コマンド1回で済む）。
3. 再度 GET /v4/aliases/shift-scheduler-ai-sepia.vercel.app で指し先が dpl_DBWQTztKF4kpqA7Abz8kpjr31Beq に戻ったことを確認
4. 本番URLを curl で疎通確認（HTTP 401 と WWW-Authenticate: Basic が返ることを確認）

8. main push 凍結期間の運用

8.1 凍結が必要な理由

Root Directory 変更 PATCH 直後は再デプロイは走らないが、その後の main への push は Vercel Git連携経由でも成功するようになる。GHA workflow（deploy.yml）も同じ push を契機に vercel deploy --prod を実行するため、両方が並列に本番デプロイを作成し、成功した方に sepia エイリアスが切り替わるrace condition が発生する。

検証が完了するまでの間、main への push を止めることでこの race を回避する。

8.2 凍結期間の目安

8.3 凍結の周知手順（W層が実行）

1. 開始時: Slack の #dev チャンネルに以下を投稿（M層 shift 経由）:

   【MAIN凍結】shift-scheduler-ai リポジトリの main への push を一時凍結します
   - 対象リポジトリ: MNML-LLC/shift-scheduler-ai の main ブランチ
   - 期間: 本投稿から検証完了通知まで（見積30分〜1時間）
   - 理由: Vercel Root Directory 変更の検証中
   - feature branch への push / PR 作成は OK
   - main へのマージのみ待機
   - 完了は同スレッドに通知

2. 凍結中の防御: 万が一に備え、GitHub Branch Protection Rule で main への直接 push と PR マージを一時的にブロックすることも検討可能（researcher/coder が M層承認後に API で操作）:

   # 現状の保護ルール確認（読み取り）
   gh api repos/MNML-LLC/shift-scheduler-ai/branches/main/protection
   
   # 凍結中のみ enforce_admins を true にする（M層承認後の書き込み）
   # gh api -X PATCH repos/MNML-LLC/shift-scheduler-ai/branches/main/protection/enforce_admins

   ※ 本手順書では読み取りのみ。実際の書き込みは M層承認が別途必要。
3. 解除時: 検証完了後、同じ Slack スレッドに解除通知:

   【MAIN凍結解除】検証完了。main への push/マージを再開できます
   - 実施内容: Root Directory を frontend に変更
   - 本番稼働確認: sepia が dpl_DBWQTztKF4kpqA7Abz8kpjr31Beq に紐づいたまま継続稼働
   - プレビュー成功確認: 済み

8.4 凍結違反時の対応

凍結中に他者が誤って main に push した場合:

1. 即座に GET /v6/deployments?target=production&limit=3 で新デプロイの状態を確認
2. 新デプロイが READY かつ sepia が新デプロイに切り替わっている場合、7.2 の手順で dpl_DBWQTztKF4kpqA7Abz8kpjr31Beq に再エイリアスして復元（M層承認必須）
3. その後、通常の検証手順に戻る

9. 実装先の指定（W層オンザフライ実行）

9.1 実行主体

9.2 VERCEL_TOKEN の取得元（優先順位）

1. W層ローカル環境変数: echo $VERCEL_TOKEN で取得可能なら最優先
2. ~/.vercel/auth.json: Mac mini 上の Vercel CLI ログイン済トークン。以下で取得:

   jq -r '.token' ~/.vercel/auth.json

   ※ このファイルは vercel CLI が管理。CEO が過去に一度 vercel login 済み。
3. GitHub Secret: gh secret list --repo MNML-LLC/shift-scheduler-ai で VERCEL_TOKEN の存在確認は可能だが、値は取得不可（GitHub仕様）。W層ローカルからの API 呼び出しには使えないため、1 または 2 を使う

9.3 実行フロー

1. M層 shift が本手順書を CEO にレビュー依頼
2. CEO 承認後、M層 shift が researcher に <<DELEGATE>>: 3章（実施前チェックリスト）の全スナップショット取得を実行
3. researcher の報告を受けて M層 shift が Slack で「MAIN凍結」宣言（8.3）
4. M層 shift が coder に <<DELEGATE>>: 4章（PATCH 実行）を実行
5. coder の報告を受けて researcher に <<DELEGATE>>: 6章（検証手順）を実行
6. 検証完了後、M層 shift が Slack で「MAIN凍結解除」宣言
7. M層 shift が CEO に完了報告

9.4 セキュリティ

• スクリプト実行ログ・API レスポンスに VERCEL_TOKEN を出力しない（curl の -v は使わない）
• 環境変数の値（BASIC_AUTH_CREDENTIALS 等）は API では返らない（暗号化保存されているため）。ログに含める心配はない
• スナップショットファイル（/tmp/vercel_*_20260702.json）は検証完了後に削除:

  rm /tmp/vercel_project_before_20260702.json \
     /tmp/vercel_project_after_20260702.json \
     /tmp/vercel_deployments_before_20260702.json \
     /tmp/vercel_aliases_before_20260702.json \
     /tmp/vercel_env_before_20260702.json \
     /tmp/vercel_env_after_20260702.json

10. shift-scheduler-ai-liff の判定

10.1 調査結果

10.2 判定

11. 未確認事項・CEO確認事項

11.1 CEO判断を仰ぐべき事項

• 実施タイミング: main push 凍結（30分〜1時間）のタイミングを CEO に決めてもらう。他の作業と競合しない時間帯（例: 平日夜間、休日朝）を推奨
• Vercel Git連携の存続方針: 現状、Vercel Git連携（自動デプロイ）と GHA workflow の両方が走っている。Root Directory修正後は両方成功するようになるが、mainへのpush毎に「2つの並列デプロイが同一の本番エイリアスを取り合う」状態になる。将来的にどちらかに一本化すべきか、CEO判断が必要
  • 案X: Vercel Git連携をDisconnect、GHAのみに一本化
  • 案Y: GHAを廃止、Vercel Git連携のみに一本化
  • 案Z: 現状維持（両方走らせるが冪等なので実害なし）
  ※ この判断は本手順書のスコープ外。別Issueで検討することを推奨

11.2 実施しないこと（明示的な非スコープ）

• Vercel Git連携のDisconnect / Reconnect
• 環境変数の追加・削除・書き換え
• vercel.json（リポジトリ側）の変更
• GHAワークフロー deploy.yml の変更
• Basic Auth設定・認証情報の変更
• 本手順書に記載された PATCH/POST API の事前実行（M層承認前）

設計完了チェックリスト

前提条件

• W層ローカル（Mac mini）に有効な VERCEL_TOKEN がある（環境変数 or ~/.vercel/auth.json）
• W層ローカルから api.vercel.com へのHTTPS疎通が可能
• M層 shift が CEO 承認を取得している
• Slack #dev チャンネルへの投稿権限がある（凍結周知用）

副作用・影響範囲

• PATCH 時点では既存デプロイ・エイリアス・環境変数に影響なし（Vercel公式仕様で裏付け済）
• 次回のmain push時に、Vercel Git連携経由の本番デプロイが成功するようになる → 本番エイリアスsepiaが新デプロイに移動する（内容は同一コミット由来）
• プレビューデプロイが正常化する（Vercel Git連携経由のみ。GHA経由は元から成功しているので変化なし）
• backend/ ディレクトリはVercelビルドの対象外になる（現状もそう。Railwayが担っているため影響なし）
• 凍結期間中、main へのマージが待機になる（他PRの遅延リスク）

代替案（却下理由）

リスク・懸念事項

• PATCH 実施後、次回のmain push時に本番エイリアスが新デプロイに移動する（Vercel Git連携とGHAの両方が成功するため）。内容は同一コミット由来のため機能的影響はゼロだが、「稼働中のデプロイIDが変わる」という状態変化はある
• 凍結期間中に他者が誤って main に push するリスク。8章の運用ルール（Slack宣言 + 必要に応じてBranch Protection強化）で緩和する
• Vercel REST API の rootDirectory フィールド仕様が将来変わる可能性は低いが、実施直前にresearcherが最新の公式ドキュメント（https://vercel.com/docs/rest-api/reference/endpoints/projects）を再確認すること
• ~/.vercel/auth.json のトークンが失効している場合、CEOに vercel login を依頼する必要が発生する（ブラウザ操作が不可避）。3.1 の疎通確認で早期検出する

architect W層 / 2026-07-02 改訂（API完全自動化版）/ DESIGN_vercel_root_dir_shift_scheduler.html