---
name: dist-renderer/index.html commit protocol — CF Pages deploy 整合性 (STEP 1072 fix incident)
description: ★★★★★ 2026-05-11 STEP 1072 deploy fix incident 教訓. 新 UI/route 追加時は dist-renderer/index.html を必ず commit (CF Pages root entry HTML) — 漏れると新 bundle deploy しても旧 HTML が古い bundle 読み続けて新 route 不在 React app が起動
type: feedback
originSessionId: 42f100d8-b702-4b4b-a14f-b23a9209d888
---
# CF Pages Deploy 整合性 Protocol (永続)

STEP 1072 (`#/quantum-microscope` route 追加) で発生した **deploy 整合性 incident** の永続教訓.

## 症状

新 route を追加 + commit + push 後、 production で:
- `https://rei-aios.pages.dev/#/<new-route>` が top page (旧 React app) を表示
- 新 route 未認識 → ReiLauncher にもメニュー entry なし
- console error なし (silent fall-through)

## Root Cause

1. CF Pages root URL (`/`) は **`dist-renderer/index.html`** を serve する (NOT `app.html`)
2. `dist-renderer/index.html` は **vite build の output ではない** (vite は `app.html` のみ更新)
3. `sync-index-html-bundle.ts` script が `index.html` を git restore + bundle ref update する設計
4. **しかし commit に `dist-renderer/index.html` を含めずに push** すると:
   - CF Pages は新 bundle (`app-XXX.js`) を deploy
   - **しかし `index.html` 旧 bundle ref のまま**
   - → 旧 React app (新 route 不在) が起動

## 永久 Protocol — 新 UI/route 追加時必須

```bash
# 1. dev:build 実行 (既存)
npm run dev:build

# 2. ★ 必須 file 全て git add (一つでも漏れると deploy 不整合) ★
git add src/renderer/                          # source
git add dist-renderer/index.html               # ★ critical — CF Pages entry HTML
git add dist-renderer/app.html                 # vite build output
git add dist-renderer/assets/app-*.js          # new bundle (vite hash-named)
git add dist-renderer/assets/app-*.css         # new CSS
git add dist-renderer/data/<new-dir>/          # data mirror (新 lens の場合)

# 3. verify (commit 前)
grep "app-" dist-renderer/index.html           # 新 hash 参照確認
git diff --cached --stat dist-renderer/        # 5+ file 期待

# 4. commit + push
git commit -m "..."
git push origin main

# 5. CF Pages deploy 完了 verify (~2-3 分)
curl -s https://rei-aios.pages.dev/ | grep -oE "app-[A-Za-z0-9_-]+\.js"
# → ↑ ↑ ↑ ローカル `dist-renderer/index.html` と一致するべき
```

## 忘れがちな file (commit 必須)

| file | 重要度 | 理由 |
|---|---|---|
| `dist-renderer/index.html` | ★★★★★ | CF Pages root entry HTML (最重要) |
| `dist-renderer/app.html` | ★★★ | vite build output reference |
| `dist-renderer/assets/app-*.js` | ★★★★ | 新 bundle (vite が hash 名で auto-rename) |
| `dist-renderer/assets/app-*.css` | ★★★ | 新 CSS (同上) |
| `dist-renderer/data/<lens>/latest.json` | ★★★ | data mirror (新 lens のみ) |

## Monitor で deploy 完了確認

```bash
# Monitor tool で auto-wait (recommended)
until curl -s "https://rei-aios.pages.dev/" 2>/dev/null | grep -q "app-XXXXX.js"; do
  sleep 15
done
echo "DEPLOYED: app-XXXXX.js now live"
```

## 関連 protocol

- `docs/SITE_COVERAGE_MAP.md` 末尾 — 同 protocol 公開版 (将来 audit 用)
- `feedback_site_coverage_map_protocol.md` ★★★★★ — Site Coverage Map 親 protocol
- `feedback_site_activity_log_protocol.md` ★★★★★ — Activity Log と相補

## incident timeline

- STEP 1072 commit `7a50237e` push (2026-05-11) — `dist-renderer/index.html` 未含有
- 藤本さん観測: 「`#/quantum-microscope` がトップページ表示」
- 調査: production bundle = `app-f076YO5A.js` (旧) vs local = `app-BpmlqG5T.js` (新)
- `dist-renderer/index.html` が deleted local + git tracked 古い bundle ref
- 修正 commit `634fedc1` (`index.html` bundle ref 更新) → `8900e561` (protocol 永続記録)
- Monitor 確認: 約 1 分 30 秒で deploy 完了 verified