docs(drive): specify permanent upload rejection handling [skip deploy]

[pocketsharkk]

使用者遇到的問題

wspc-drive 使用者的 library 裡有一個 291 MB 的 heart-rate.jsonl，server 每次都拒收（HTTP 413）。從 2026-09-15 起，app 大約每 5 秒就重讀、重傳整個 291 MB 一次，三天累積 444 次失敗，到 2026-09-18 還在持續。這個 PR 只新增設計 spec，定義修正後的行為，不改程式碼。

背景

• WSPC Todo：tod_01M2S8NHVDB66Y6971M4D1269V；相關：tod_01M2S85BY0A38RM37TMNC4KTDY（413 錯誤碼、大檔上傳）。
• 沿用的 spec：docs/superpowers/specs/2026-06-21-drive-sync-watch-design.md、docs/superpowers/specs/2026-07-24-drive-sync-exclude-rules-design.md。
• 證據來自受影響 library 的 .wspc-drive/debug.log：最近 71 次 sync_start 中有 60 次由 trigger: local 觸發，而同期 71 次 fs_event 全部是 root .DS_Store，但 .wspc-drive/ignore 早就排除了 **/.DS_Store*。

問題出在哪裡

有兩件事疊在一起：

1. executeDrivePathAction() 上傳失敗時，錯誤只放進該輪 summary.path_errors，不寫入 state.json。下一輪 decideDriveAction() 仍判定 upload_update，於是整檔重傳。平常上傳失敗多半是暫時性的，下一輪重傳本來就是對的，所以一直沒人注意到；只有 server 永遠拒收的檔案會變成無限重傳。
2. runDriveWatch() 對 excluded path 的 fs event 照樣排程 sync。exclude rules spec 當初刻意延後 watcher 端過濾，理由是這些 sync 什麼事都不會做，這個前提平常成立。但只要有一個失敗檔，每輪 sync 就是一次 291 MB 上傳。Finder 持續改寫 .DS_Store，就形成了迴圈。

修法

新增 docs/superpowers/specs/2026-09-18-drive-permanent-upload-rejection-design.md：

• 新增 Permanent Upload Rejection 的定義：上傳收到 401／403／408／409／429 以外的 HTTP 4xx。發生時在 state.json 的 optional upload_rejections 記下該檔的 mtime_ms、size_bytes、sha256 與 CLI version。之後的輪次若 fingerprint 與 CLI version 都相同，就不再上傳，但每輪仍回報同一筆 path_errors，dashboard 照樣顯示「1 file needs attention」。
• 檔案內容或 mtime 改變、檔案被刪除／改名／排除，或 CLI 升級後，就會重試或清除紀錄。CLI 升級這個條件看起來多餘，但不能省：少了它，之後大檔上傳修好時，已被拒收的檔案不會自動恢復。
• watch 會過濾 excluded path 的 fs event，ignore 變動時重新載入規則。
• README.md roadmap 加上連結；CONTEXT.md 新增 Permanent Upload Rejection 詞條。

這個 PR 不修什麼

• 程式行為完全不變，實作由後續的 ready-for-agent Todo 處理。
• 大檔 chunked upload 與 FILE_TOO_LARGE 錯誤碼仍歸 tod_01M2S85BY0A38RM37TMNC4KTDY。
• 同一個大檔若一直只回 5xx，retry cap 不在本 spec 範圍內。

已知副作用

無。只有文件變動。

測試

只有文件變動，regression test 不適用。已確認 spec 引用的函式、欄位與 script（npm run typecheck、npm test、npm run build）都存在於目前的 main。

未完成驗收

無（spec PR 本身沒有驗收項目；AC 12 的 live 驗收在實作發佈後進行）。

🤖 Generated with Claude Code

---

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