docs: update DELIVERY_PROCEDURE to v1.1 — add self-verify, version strategy, rollback, deploy details

AGENTS.md

@@ -672,3 +672,9 @@ docs_v1.0/M4_workspace/YYYY-MM-DD_<topic>_test_report.md (測試報告)
 4. M4 透過 git log 查看
 
 詳細規範見 `docs_v1.0/M4_workspace/M4_NOTIFICATION_PROTOCOL.md`。
+
+## Delivery Procedure
+
+完整交付程序（M4_workspace → M5 → Release → Deploy → Public）見：
+
+`docs_v1.0/REFERENCE/DELIVERY_PROCEDURE.md`

docs_v1.0/REFERENCE/DELIVERY_PROCEDURE.md

@@ -1,20 +1,26 @@
 # 交付程序：M4_workspace → M5 → Public Release
 
 **Date**: 2026-05-13
-**Version**: 1.0
+**Version**: 1.1
 
 ---
 
 ## 流程總覽
 
 ```
-M4 回報問題 → M5 修復 → 驗證 → Release package → Deploy → Public
+M4 回報問題 → M5 修復 → M5 自驗 → Release package → Deploy → M4 驗證 → Public Release
+                                   ↑                                      ↓
+                                   └── 失敗回退 ──────────────────────────┘
 ```
 
 ---
 
 ## Phase 1：M4 回報（M4_workspace/）
 
+---
+
+## Phase 1：M4 回報（M4_workspace/）
+
 M4 將問題寫入 `docs_v1.0/M4_workspace/YYYY-MM-DD_<topic>.md`，格式：
 
 ```markdown
@@ -82,6 +88,58 @@ M4 將問題寫入 `docs_v1.0/M4_workspace/YYYY-MM-DD_<topic>.md`，格式：
 
 ---
 
+## Phase 2.5：M5 內部自驗
+
+Release 前先自驗，降低 M4 測試失敗的機率。
+
+### 自驗清單
+
+| # | 項目 | 方法 |
+|---|------|------|
+| 2.5.1 | Rust build | `cargo build` / `cargo test` |
+| 2.5.2 | API 測試 | `bash api_test.sh` → 全 passed |
+| 2.5.3 | 場景驗證 | 抽 1 個 CUT segment，用 MaskFormer 或 PaliGemma 確認 scene type |
+| 2.5.4 | SQLite 驗證 | `python3 export_sqlite.py {uuid}` → vec0 tables 正確 |
+| 2.5.5 | Identity 驗證 | TMDB 演員 + auto PERSON count 合理 |
+| 2.5.6 | TKG 驗證 | edges > 0, nodes > 0 |
+| 2.5.7 | file_info.json | `momentry_version` + `momentry_build` 正確 |
+
+### 自驗不通過
+
+```
+❌ cargo build → 修復編譯錯誤 → 重新 commit
+❌ api_test → 修復 → 重新 commit
+❌ 場景驗證 → 確認是 bug 還是 flicker → 必要時開 issue
+```
+
+### 回應文件規範
+
+```markdown
+# {主題} — 回覆
+
+**Date**: YYYY-MM-DD
+**From**: M5
+**To**: M4
+**Ref**: `YYYY-MM-DD_source_file.md`
+
+---
+
+## 修正
+
+| # | 項目 | 狀態 | Commit |
+|---|------|:--:|--------|
+| 1 | {問題 A 修復} | ✅ | `abc1234` |
+| 2 | {功能 B 新增} | ✅ | `abc1234` |
+
+## 檔案變更
+
+| 檔案 | 說明 |
+|------|------|
+| `path/to/file` | 改動摘要 |
+```
+
+---
+
 ## Phase 3：Release Package
 
 ### 時機
@@ -142,29 +200,73 @@ tar tzf release/files/{uuid}_v{timestamp}.tar.gz
 
 ## Phase 4：Deploy
 
-### 測試環境 (dev, port 3003)
+### 前置檢查
 
 ```bash
-# 解包
+# 1. 確認伺服器正常
+curl -s http://localhost:3003/health
+# 預期: {"status":"ok","version":"1.0.0","build_git_hash":"d34bcae",...}
+
+# 2. 確認資料庫可連線
+/Users/accusys/pgsql/18.3/bin/psql -U accusys -d momentry -c "SELECT version()"
+
+# 3. 解包
 tar xzf release/files/{uuid}_v{timestamp}.tar.gz -C /tmp/deploy/
 cd /tmp/deploy/{file_uuid}
+```
 
-# 執行 deploy（9 步驟）
+### 執行 deploy
+
+```bash
 bash deploy.sh
 ```
 
 ### 預期輸出
 
 ```
-  [0/9] Checking system version and build...
+  [0/9] Checking system version and build...          ✅ Server v1.0.0 matches
-  [1/9] Verifying package...
+  [1/9] Verifying package...                           ✅
-  [2/9] Pre-cleaning existing identities...
+  [2/9] Pre-cleaning existing identities...             ✅
   [3/9] Importing DB data...
-  [4/9] Copy video...
+        Importing dev_videos.sql...                     COPY 1
-  [5/9] Setting status=completed
+        Importing dev_chunk.sql...                      COPY 2407
-  [6/9] Copying output files...
+        Importing dev_chunk_vectors.sql...               COPY 2407
-  [7/9] Installing vec0.dylib...
+        Importing dev_face_detections.sql...             COPY 70691
+        Importing dev_identities.sql...                  COPY 441
+        Importing dev_identity_bindings.sql...           COPY 18635
+        Importing dev_tkg_nodes.sql...                   COPY 6457
+        Importing dev_tkg_edges.sql...                   COPY 21028
+  [4/9] Copy video...                                   ✅
+  [5/9] Setting status=completed                        ✅
+  [6/9] Copying output files...                         ✅ N files
+  [7/9] Installing vec0.dylib...                        ✅ /tmp/vec0.dylib
   [8/9] Verify deployment...
+        Chunks:    2407
+        Faces:     70691
+        Identities: 417
+        TKG nodes: 6457
+        TKG edges: 21028                               ✅
+```
+
+### Deploy 失敗處理
+
+| 失敗點 | 原因 | 處理方式 |
+|--------|------|---------|
+| Step 0: 版本檢查 | server version ≠ package version | 取得 matching upgrade package |
+| Step 3: 任 table 匯入失敗 | FK constraint、duplicate key | 檢查該 table 的 sql/*.sql 內容，修復後再跑 |
+| Step 4: 影片複製 | 磁碟空間不足 | `df -h` 確認，清理後重跑 |
+| Step 8: 驗證 row count 不符 | import 不完整 | 逐 table 比對 COPY count vs actual count |
+
+> 每個 table 獨立 import（各含 auto-commit），單一 table 失敗不會 rollback 其他 table。
+> 重新執行 `bash deploy.sh` 會先清掉該 file 的 identity 和資料後重新 import。
+
+### 驗證後確認
+
+```bash
+# 確認所有 table row count 正確
+for tbl in videos chunk chunk_vectors face_detections identities identity_bindings tkg_nodes tkg_edges; do
+    echo "$tbl: $(psql -U accusys -d momentry -t -A -c "SELECT COUNT(*) FROM dev.$tbl WHERE file_uuid='$UUID'" 2>/dev/null)"
+done
 ```
 
 ### Production (port 3002)
@@ -187,14 +289,41 @@ SERVER_URL=http://localhost:3002 bash deploy.sh
 
 ## Phase 5：Public Release
 
+### 版本策略
+
+| Bump | 幅度 | 適用時機 | 範例 |
+|------|:----:|---------|------|
+| **patch** | 0.0.x | Bug fix only，無 API 變更 | 1.0.0 → 1.0.1 |
+| **minor** | 0.x.0 | 新功能、模型替換、API 向後相容 | 1.0.0 → 1.1.0 |
+| **major** | x.0.0 | Breaking change、schema 遷移 | 1.0.0 → 2.0.0 |
+
+> 目前版本 `1.0.0`，所有已完成的變更（YOLO 替換、座標修復、pipeline 重排）尚未 bump。
+
 ### 條件
 
 - [ ] M4 驗證通過（deploy test 全部綠色）
 - [ ] 所有 open issues 已回應或關閉
-- [ ] 版本號已 bump（Cargo.toml → build.rs → BUILD_VERSION）
+- [ ] API 文件與實際行為一致（或已開 doc issue 追蹤 M4 更新）
+- [ ] 版本號已 bump（`Cargo.toml` → `build.rs` → `BUILD_VERSION`）
 - [ ] package 已上傳到 `release/files/`
 - [ ] 變更已 `git commit` + `git push`
 
+### M4 驗證失敗的回退
+
+```
+M4 deploy test ❌
+    ↓
+M5 分析失敗原因
+    ├── Bug → 回到 Phase 2 修復 → 重新 commit（不 bump 版本）
+    ├── Script 錯誤 → 修復 deploy.sh → 重新 commit
+    └── Package 內容缺漏 → 重新 `cargo run --bin release -- package`
+    ↓
+M5 重新通知 M4（新 *response.md + git commit）
+M4 重新測試
+```
+
+### Release Info 產出
+
 ### Release Info 產出
 
 ```markdown