docs(handoff): Linear backlog 同步交接文件

CLAUDE.md

@@ -10,13 +10,75 @@
 - **單裝置架構**：每個帳號固定一個 deviceId，不支援多裝置、不支援多裝置同時登入。
 - **新登入踢舊連線**：同一帳號的新登入階段（session）會踢掉舊的登入階段，確保同時只有一個活躍連線。
 
-## Linear 進度追蹤
+## Linear 開發治理規範（Claude Code × Linear）
 
-- **單一事實來源**：所有開發進度一律以 Linear 追蹤（team `SENTRY 核心團隊`、initiative `SENTRY Messenger`）。iOS 完整 App 與 App Clip 的工作歸 project **`Messenger iOS`**；web（iOS Safari／PWA）的工作歸 project **`Messenger iOS Web`**。
-- **設計與議題自動建 issue**：所有設計（架構方案、安全機制、方案評估）與議題（新功能、bug、技術債、重構）在開工前必須自動建立對應的 Linear issue；重大架構／安全決策以「決策紀錄：…」形式的 issue 留檔（含決策理由與否決方案）。
-- **自動爬取與處理**：每次工作階段開始時，自動爬取（`list_issues`）相關 project 的 issue 現況，比對 repo 實際狀態，處理可處理的項目；發現 issue 與現況不符時主動更新。
-- **自動更新狀態**：工作進行中隨進度更新 issue 狀態（待辦清單 → 準備執行 → 進行中 → 待審查 → 已完成／已取消／已阻塞）。程式碼已合併但尚待實機驗證者用「待審查」；PR 合併後把 PR 連結附到 issue。
-- **不重複建檔**：建 issue 前先以 query 查詢避免重複；已存在者以更新（`save_issue` 帶 `id`）代替新建。
+> Linear 是本 repo 的**唯一工作真相來源**。以下規範適用於每一次 Claude Code session。
+>
+> **實際座標**：Team `SENTRY 核心團隊`（issue 前綴 `SEN`）、Initiative `SENTRY Messenger`。
+> iOS 完整 App 與 App Clip 的工作歸 project **`Messenger iOS`**；web（iOS Safari／PWA）的工作歸 project **`Messenger iOS Web`**；後端（data-worker / D1 / R2）沿用同 team，掛回對應功能 issue。
+
+### 1. Linear 是唯一工作真相來源
+
+- 所有**尚未完成、需追蹤、需決策、需驗收、或可能影響後續開發**的事項，都必須存在於 Linear issue。
+- 待辦**不得只**留在 session 對話、`TODO` 註解、commit message、PR 描述、個人記憶或臨時文件；這些位置可放補充資訊，但不能取代 Linear issue。
+
+### 2. 動工前先搜尋 Linear（禁止重複建檔）
+
+- 修改程式碼前，先以下列條件搜尋（`list_issues` / 關鍵字查詢）：repo 名、project 名、功能名、模組名、錯誤訊息、相關關鍵字、可能的舊名或同義詞。
+- 處理原則：**相同** issue → 直接更新原 issue；**高度重疊** → 更新原 issue，不得另建；**部分相關** → 先建立關聯再決定是否開子 issue；**完全無相符** → 才新建。
+- 已存在者一律以 `save_issue` 帶 `id` 更新，不得為求方便另開重複 issue。
+
+### 3. 新 issue 最低完整度
+
+新 issue 至少包含：可搜尋的具體標題、Team、Project、Assignee、Priority、正確狀態、問題背景、目標、範圍、**不包含的範圍**、驗收條件、技術／產品限制、相關檔案／模組／路徑、Parent 或相關 issue、關係（Blocks／Blocked by／Related to）、以及 Milestone（若該 project 已有適用者）。
+
+標題禁止只寫「修 Bug／優化／重構／處理問題／待確認」，須寫出**具體元件＋行為＋問題**，例如「Messenger iOS：掛斷視訊通話後未同步通知對端」。
+
+### 4. 父 issue 與可執行子 issue 分開
+
+- 父 issue 表示一個交付目標／MVP／大型範圍，**不承載大量細節實作**。
+- 實際工作拆成可驗收的子 issue，子 issue 必須設 Parent；父 issue 狀態依子 issue 與整體驗收更新。
+- 不得因父 issue 已存在就把所有衍生工作塞進同一描述，也不得把父 issue 與子 issue 當成同層級待辦。
+
+### 5. 開始實作前更新 issue
+
+正式改碼前：將處理中的 issue 設為**進行中**，並在 issue 留下本次**執行計畫**（預計修改的模組、預計驗證方式、已知風險或待確認事項）。計畫需精簡，但足以讓下一個 session 不依賴本次對話即可理解方向。
+
+### 6. 開發中發現衍生事項
+
+符合任一條件時**建立衍生 issue**：超出目前範圍／本 session 無法合理完成／需不同負責人／需產品或架構決策／會阻擋其他工作／是獨立缺陷或風險或技術債／需後續驗收部署觀察／為避免擴大變更而暫不處理。
+
+不需另開的情況：只是目前實作的小步驟、可在本 issue 範圍內直接完成、無獨立驗收價值、不需後續追蹤——此時仍把資訊更新回目前 issue。
+
+衍生 issue 建立後**必須設定至少一項關係**（Parent／Blocks／Blocked by／Related to），不得留下孤立 issue。
+
+### 7. 產品決策與技術實作分開
+
+遇未拍板的產品或架構選擇時，建立或更新**「決策：…」issue**：列出選項、各選項影響、建議方案、是否阻擋實作。未獲決策前不得把個人假設當成正式產品方向；可先做不影響決策結果的中立工作，但須在 issue 註明。
+
+### 8. 程式碼存在 ≠ issue 完成
+
+issue 需歷經 **Implemented → Integrated → Verified → Done** 四階段（本 team 無自訂狀態時，用現有狀態＋issue 留言明確標示階段；「程式碼已合併但尚待實機驗證」用**待審查**）。**禁止因「程式碼看起來已存在」就關閉 issue**。關閉前至少核對：實際入口可用、串接完成、測試通過、錯誤路徑已處理、權限與安全條件符合、驗收條件逐項達成、部署／migration 完成、文件是否需更新。
+
+### 9. 測試與驗收紀錄
+
+issue 完成前須在 Linear 記錄：執行了哪些測試、測試結果、未執行的測試及原因、已知限制、可能回歸風險、是否需人工驗收、是否需部署後觀察。不得只寫「已完成／測試正常」而無具體內容。
+
+### 10. Commit／PR 與 Linear 互相連結
+
+取得 commit／PR 資訊時更新回 issue，至少記錄：branch、commit SHA 或連結、PR 連結、主要變更、相關測試、部署／migration 注意事項。commit 與 PR 標題盡量包含 Linear issue ID（如 `SEN-83`）。
+
+### 11. Session 結束前完整同步
+
+每次 session 結束前對本次處理的所有 issue 做一次同步：更新狀態、寫入完成內容／主要檔案模組／測試結果／commit 或 PR／剩餘工作／阻擋事項；建立所有需後續追蹤的衍生 issue 並確認關係正確；確認沒有待辦只存在於本次 session；確認已完成 issue 符合驗收條件後才關閉。工作未完者，留言須足以讓全新 session 不依賴本次對話即可接手。
+
+### 12. 決策與設計留檔
+
+所有設計（架構方案、安全機制、方案評估）與重大架構／安全決策，以 issue 形式留檔（決策類用「決策：…」標題，含決策理由與否決方案），不得只留在對話或 commit。
+
+### 13. 每次 session 起始自動爬取
+
+session 開始時自動 `list_issues` 爬取 `Messenger iOS` / `Messenger iOS Web` 現況，比對 repo 實際狀態，處理可處理項目，發現 issue 與現況不符時主動更新。
 
 ## 資料庫
 

outputs/LINEAR-BACKLOG-SYNC.md

@@ -0,0 +1,74 @@
+# Linear Backlog Sync — 待辦交接（給下一個 Session）
+
+> 用途：本 session（2026-07-02）建立 CLAUDE.md「Linear 開發治理規範（13 條）」並完成本輪原生遷移的 Linear 建檔，但 **session 後段 Linear MCP 斷線**，尚有 issue 回填未完成。此文件讓**全新 session 不依賴當時對話**即可接手。
+>
+> 依 `CLAUDE.md`「§11 Session 結束前完整同步」：待辦不得只留在對話，故落成此檔。**待辦本體仍以 Linear 為唯一真相來源**——本檔僅為交接索引，完成後即可刪除或標記 done。
+
+## 0. 先決條件（阻擋中）
+
+- ⚠️ **Linear MCP 需重新授權**才能操作（`mcp__Linear__*`）。非交互環境無法跑 OAuth。
+- 新 session 起手先確認 Linear 工具可用：`ToolSearch "select:mcp__Linear__list_issues,mcp__Linear__save_issue,mcp__Linear__save_comment,mcp__Linear__get_issue"`。搜不到 → 請使用者到 claude.ai 連接器設定 / `claude mcp` 重新授權 Linear，再繼續。
+
+## 1. Linear 座標（實際值）
+
+- **Team**：`SENTRY 核心團隊`（issue 前綴 `SEN`，id `fbebc7ee-da86-4276-8f8e-3f26d53bb9b3`）
+- **Initiative**：`SENTRY Messenger`
+- **Projects**：
+  - `Messenger iOS`（id `ba80ded1-8f7e-4acc-a1c8-e87bc3a08a96`）— 完整 App + App Clip + 後端對應功能
+  - `Messenger iOS Web`（id `4da496b8-12f6-4de2-a24c-1ca609ddf39c`）— web（iOS Safari／PWA）
+- **常用 label**：`Engineering`、`類型／功能`、`類型／錯誤`、`類型／決策`、`範圍／前端`、`Security Critical`
+
+## 2. 本輪已建檔 issue（現況快照）
+
+| Issue | 標題 | 狀態 | 備註 |
+|---|---|---|---|
+| SEN-78 | 原生 WebRTC 通話 P0–P3（UseNativeCalls） | 已完成 | 實機雙機驗證通過 |
+| SEN-79 | 原生帳號 WS（Option B, UseNativeAccountSocket） | 待審查 | 程式已合併，待開旗標實機驗證 |
+| SEN-80 | Tier 1 NSE 原生解密推播預覽 | 已完成 | |
+| SEN-81 | Tier 2 背景媒體下載（URLSession background） | 待審查 | 待開旗標實機驗證 |
+| SEN-82 | Tier 3 原生加密本地快取（UseNativeLocalCache） | 待審查 | 含 cache-first UNSAFE 決策；待驗證 |
+| SEN-83 | Bug：原生視訊掛斷未同步到對端 | 進行中 | 等未掛斷端 `[NativeCall]` log |
+| SEN-86 | 原生視訊 face-blur v1 微調 | 進行中 | 等實機 orientation/mirroring/scale 回饋 |
+| SEN-87 | 內嵌 Web Bundle（CORS 未解） | 待辦 | Low，暫緩理由已寫明 |
+| SEN-88 | App Clip NFC 入口與完整化 | 已完成 | |
+| SEN-89 | 決策：P4 不降 Keychain 保護 | 已完成 | |
+| SEN-91 | Web 端原生模式整合（getUserMedia 閘門／WS 介接） | 已完成 | project = Messenger iOS Web |
+
+> 注意：以上 id 依當時建立為準；接手時務必先 `list_issues` / `get_issue` 核對現況（可能已被他人更新），**禁止重複建檔**（CLAUDE.md §2）。
+
+## 3. 待補的 Linear 同步工作（本 session 未完成）
+
+### 3.1 回填驗收紀錄 + commit/PR 連結（CLAUDE.md §8、§9、§10）
+對三張「待審查」issue，逐一以 `save_comment` 補上具體紀錄，不得只寫「已完成」：
+
+- **SEN-79 / SEN-81 / SEN-82** 各補：
+  - 已執行的驗證（CI 僅編譯，未做實機/通話/推播/WS/快取驗證——需明確標示「未執行的測試及原因」）
+  - 對應 branch、commit SHA、PR 連結（見 §4）
+  - 依 `Implemented → Integrated → Verified → Done`，目前皆停在 **Integrated，待 Verified（實機）**——留言標明階段
+  - 可能回歸風險、是否需部署後觀察、旗標預設值（皆預設關）
+
+### 3.2 SEN-83（掛斷 bug）補執行計畫（CLAUDE.md §5）
+- 設為進行中（已是），留言補「等未掛斷端 `[NativeCall] tearDown / dismissCallUI` log 判定訊號層 vs UI 層」的**執行計畫**與 blocked 說明，關聯 PR #112（診斷 log）。
+
+### 3.3 新建決策 issue（CLAUDE.md §7、§12）
+- 標題：**「決策：導入 Claude Code × Linear 開發治理規範」**
+- Project：`Messenger iOS`（或視為 team 級；擇一並註明）
+- 內容：背景（Linear 定為唯一真相來源）、選項/結論（13 條規範已上線）、關聯 **PR #114**、commit `138fe8e`
+- 關係：`Related to` 上述所有 SEN-78~91（治理規範適用全體）
+
+## 4. 相關 commit / PR（供回填）
+
+- **PR #113**（已合併，`5d16c84`）：CLAUDE.md 加入 Linear 進度追蹤（5 條初版）
+- **PR #114**（已合併，`138fe8e`）：擴充為「Linear 開發治理規範（13 條）」——**治理規範正式上線**
+- 本輪原生遷移 PR：#87/#90/#91/#92/#94/#97（通話）、#95/#96（帳號 WS）、#99（Tier1）、#100（Tier2）、#101/#102（Tier3）、#103/#104（安裝/內嵌修）、#105/#107/#108/#110/#111（沒聲音/視訊修復鏈）、#112（face-blur + 掛斷診斷）
+- 開發分支：`claude/qr-code-stored-value-routing-vcwnyw`
+
+## 5. 仍需使用者決策 / 無法由 AI 代完成
+
+1. **Linear 重新授權**（阻擋所有 issue 操作，最優先）。
+2. **實機驗證**：SEN-79/81/82 從「待審查 → 已完成」需開對應旗標做實機驗證（通話音訊/視訊、推播預覽、背景 WS、加密快取）。CI 只編譯不能測，AI 無法代驗——需使用者實機執行並回報，才可依 §8 逐項核對後關閉。
+3. **face-blur（SEN-86）/ 掛斷（SEN-83）** 需實機回饋（log / 視覺）才能收斂。
+
+## 6. 完成後動作
+
+- 依 CLAUDE.md §11 做完整同步後，本檔可刪除（`git rm outputs/LINEAR-BACKLOG-SYNC.md`）或在頂端標記 `✅ DONE` 並記錄完成 session 日期。