docs(drive): specify oversized file handling for sync [skip deploy]

[pocketsharkk]

使用者遇到的問題

WSPC Drive 使用者的 library 裡有一個 291 MB 的 heart-rate.jsonl，dashboard 顯示 DRIVE_PATH_ERROR: HTTP 413，看起來像路徑出錯，其實是檔案太大被拒收。使用者不知道上限是多少；CLI 也會先把整個檔案讀進記憶體、整檔送出才被拒。檔案每天 append，所以即使 CLI 0.13.0 已會記住拒收，每次變動仍會再整檔上傳一次。

背景

• WSPC Todo：tod_01M2S85BY0A38RM37TMNC4KTDY。本 PR 只新增 spec，實作另開 ready-for-agent Todo。
• Server 有 100 MiB 的單檔硬上限（sadcoderlabs/wspc packages/drive/worker/src/limits.ts:2），沒有 multipart／resumable upload，也沒有透過 API 公開上限。因此 Todo 原本列的 chunked upload 解不了問題：換傳輸方式仍會被同一個上限擋下。
• 相關：Permanent Upload Rejection spec（docs(drive): specify permanent upload rejection handling [skip deploy] #133／feat(drive): stop re-uploading permanently rejected files and ignore excluded watch events #134）、sadcoderlabs/wspc-drive#92（app 已能辨識 FILE_TOO_LARGE）。
• Product Review Brief 已經過使用者核准，三個決策如下：
  1. 本 milestone 不支援 >100 MiB 同步，只做明確錯誤。
  2. CLI 寫死 100 MiB 上限，上傳前先檢查大小。
  3. 大小資訊只放在 message，event contract 不變。

問題出在哪裡

• 上傳前沒有大小檢查：executeDrivePathAction() 直接 readStableUploadBody() 讀整檔再 api.uploadFile()。
• driveHttpError() 只從 body 取 code。edge 回的 413 沒有 JSON body，drivePathErrorSummary() 就退回 DRIVE_PATH_ERROR，失去「太大」的語意。

修法（spec 內容）

• 新增 docs/superpowers/specs/2026-09-18-drive-oversized-file-design.md，內容如下：
  • Oversized File（scan size_bytes > 104857600）在決策為 upload 時：不讀、不傳，每輪回報 FILE_TOO_LARGE、retryable: false，message 帶實際大小與上限；該檔不計入 progress total，也不寫入 state.json。
  • 任何 HTTP 413 若 body 沒有 code，一律視為 FILE_TOO_LARGE。
  • Oversized File 的判定先於 Permanent Upload Rejection 的略過判定。舊版 CLI 留下的拒收紀錄，會依既有的 CLI version 規則清除。
• CONTEXT.md 新增 Oversized File 詞彙；README roadmap 加上連結。

這個 PR 不修什麼

只新增 spec，不改程式。讓大檔可以同步、server 公開上限、conflict 流程的大小預檢，都列在 spec 的 Out of Scope 與後續方向。

測試

文件變更，沒有 regression test 可寫。已執行 git diff --check。內文引用的程式位置都已逐一核對：server limits.ts:2、files-service.ts:181、errors.ts:47，本 repo spec/openapi.json 的 drive_file_upload responses，以及 .github/workflows/pr.yml:10。另在本機量測 sparse file：blocks: 0，hash 約 91 ms。

未完成驗收

無（本 PR 範圍）。Spec 的 AC 1–9 由實作 Todo 驗收。

🤖 Generated with Claude Code

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}