feat(design): support new Claude Design handoff bundle (gzip+tar)

[gpwork4u]

Summary

實跑 benchmark（請假系統 design）時發現 SpecFlow 的 design 攝取與當前 Claude Design 匯出格式不相容——這是比 prompt 瘦身更關鍵的可靠度 gap：任何用新版 Claude Design 的專案會在第一步翻車。

stacked on #8（base = refactor/slim-prompts-dedup）

問題

項目	舊 sync-design 假設	實際	後果
URL	claude.ai/com 單頁	api.anthropic.com	抽不到 URL
格式	純 HTML	gzip+tar bundle	存成 index.html 是二進位
結構	單一 HTML	README + chats/ + project/*.jsx	testid 在 .jsx，gate grep 不到

Changes

• sync-design.sh：偵測 bundle(tar) vs html；解開 bundle 攤平 project/（index.html + *.jsx + css + screenshots）+ 保留 chats/ 與 BUNDLE-README.md；URL 支援 api.anthropic.com；metadata 標註格式與「元件在 *.jsx」「chats 是意圖來源」
• engineer.md pixel-perfect gate：grep 改掃整個 design-source/（bundle 落 *.jsx）
• spec-writer.md：bundle 模式先讀 chats/ 反推意圖

Test Plan

• sandbox 用真實 bundle 跑 sync-design.sh 全程通過：10 元件檔 + chats + 截圖 + 完整 metadata
• selftest.sh 8/8 PASS
• ⚠️ 已知：design export URL 為短時效（實測數分鐘後 404）— 文件已提示過舊要重 export

🤖 Generated with Claude Code

[gpwork4u]

追加：發現③ testid 合約語義修正（同分支）

實跑請假系統 bundle 時 grep data-testid specs/design-source/*.jsx = 0 個 — prototype 根本沒 testid。暴露 workflow 假設「從 design 抽 testid」對 Claude Design prototype 不成立。

已修（commit 隨本 PR）：

• ui-designer：design 有 testid 就沿用；沒有（常態）→ 依元件結構發明 kebab-case testid 作為測試合約；字串仍忠實照搬
• tech-lead：解除「不自創 testid」硬規則 → 照單吸收 ui-designer 發明的 testid
• engineer：frontend 實作時把 contracts.ts 的 data-testid 加到元件
• spec-writer：testid grep=0 屬正常，AC 用 {TESTIDS.xxx} placeholder

→ design 角色澄清為「提供視覺/結構/字串」，testid 是團隊在 contract phase 擁有的合約。

[gpwork4u]

追加：發現④ orchestration gap（同分支，start skill Phase 3.8）

實跑 demo 的 spec→tech-lead 階段揪出：spec-writer/tech-lead 寫的 specs/ 停在 working tree 未進版控時，worktree-isolated 的 engineer/qa/ui 從 origin clone 讀不到 spec/contract → 會憑空亂寫。tech-lead 當下只好為 contracts 開 PR 才進得了版控。

已修：start skill 新增 Phase 3.8 hard gate — spawn lane 前 commit specs/ 到 main（受保護則開 PR 合併）+ 確認 contracts.ts 在 main 才放行。

Benchmark run 結果（gpwork4u/leave-demo）

瘦身 + bundle + testid 修正後的 opus 雙 agent 在真實請假系統 bundle 上全跑通：

• spec-writer：讀 chats 反推 13 feature + Epic/Sprint/milestone + 12 MVP 假設（65K tok）
• tech-lead：0-testid prototype → 發明 56 testid + 完整 contracts.ts + 15 issue 標 lane + wave 分析（99K tok）

→ 證實發現③修正有效（testid 發明流程端到端成立）、瘦身後的 spec-writer/tech-lead prompt 在真實專案可靠執行。

[gpwork4u]

追加：發現⑤（最嚴重）+ engineer 真實驗證

從 leave-demo 跑一個 backend engineer（issue #3：Prisma schema+seed+auth+RBAC+10 unit tests，PR #19 merged，contract 全 import）→ 驗證瘦身後 engineer.md 可驅動正確行為，且 engineer 回報了具體可改進處。

🔴 發現⑤（最嚴重）contract-check.sh 形同虛設：report() 在 echo|while 的 subshell 裡累加 VIOLATIONS，計數丟失 → 腳本永遠 exit 0，contract 防漂移核心從未真正擋過任何 PR。已修（主 shell add_violations），並把 selftest §4 從「驗語法」升級為「驗違規 exit 1 / 乾淨 exit 0」功能測試讓它永不回歸。

順帶修：

• contract-check Check 2/5 只擋雙引號 "/api/" → 改 char class 同抓單引號 '/api/'
• engineer.md Step 4 路徑 bug（overview.md→specs/overview.md）
• engineer.md 澄清 docker 自驗是開發期選配非收尾 gate（消除與「收尾禁止先搞懂」的歧義）
• engineer.md 補「turn 將盡先 push 保 deliverable」

selftest 8/8（含新的 contract-check 功能驗證）。

[gpwork4u]

追加：frontend engineer 驗證 + 發現⑥⑦

從 leave-demo 跑 frontend engineer（issue #9：登入+AppShell+導覽，PR #20 merged）。正面驗證：bundle 格式下 pixel-perfect gate 好用（一次找對 *.jsx）、從 contract 加 testid 流程順、deliver-first/contract import 無雷。又揪出兩個真實 bug：

• 🔴 ⑥ frontend-scaffold.sh 摧毀 backend：backend+frontend 共用一個 dev/ 時，scaffold 把 Vite 骨架寫進 dev/ 根 → 覆蓋 backend 已 merged 的 package.json/tsconfig.json。修：偵測 backend package.json → 隔離 scaffold 到 dev/web/（contracts 路徑連動），純前端維持 dev/ 根。
• ⑦ contract-check full 模式掃 node_modules：第三方 .d.ts 的 data-testid 範例被誤報。與⑤交互危險：過去被 subshell bug 抵銷成 exit 0；我修了⑤之後若不 prune node_modules，每個有 node_modules 的 frontend local-checks 都會誤擋。修：prune node_modules/dist/build/coverage/.next。⑤⑦ 一起修才安全。

至此 benchmark 共揪 7 個可靠度缺陷全修，backend + frontend 兩個 engineer lane 實跑驗證通過。selftest 8/8。

[gpwork4u]

追加：pipeline + qa lane 驗證 + 發現⑧–⑫（共 12 個缺陷）

跑完 pipeline engineer（#15 PR#21 merged）與 qa engineer（#17 PR#22，88 test 1:1 對 88 AC）。至此 5 種 agent 全驗過（spec/tech-lead/backend/frontend/pipeline/qa）。

新增 5 個缺陷（多數是發現⑤「contract-check 永遠 exit 0」修好後浮現的連鎖）：

• 🔴 ⑪ local-checks 用 full mode → 任一 lane 既有 contract 債卡死所有 lane push。改 --diff origin/main。
• 🔴 ⑧ kit §3 compose 範本單一 app → contracts 在 build context 外、雙子專案無指引（套舊範本的 backend Dockerfile 其實 build 不起來）。補 context=repo root + 雙子專案。
• ⑫ contract-check Check 5 誤判 consumer lane：模板插值 [data-testid="${TESTIDS.x}"] 被當新 contract → frontend/qa 結構性紅燈。改只算真 literal。
• ⑨ ready-and-merge 誤判 CI billing/infra 失敗 deadlock：偵測 billing/startup_failure/BlobNotFound → exit 2。
• ⑩ 無 workflow YAML lint：kit 補 push 前 yaml.safe_load。

發現⑤的價值再確認：修好「防漂移閘門從未運作」後，原本被它隱藏的 ⑦⑪⑫ 三個誤報全部浮現——必須一起修，否則修了⑤反而讓所有 frontend/qa PR 卡死。這正是「可靠度」最深的一層。

⚠️ gpwork4u 帳號的 GitHub Actions 被 billing 擋住（BlobNotFound startup 失敗），sprint e2e 與 #22 merge 無法完成——屬環境非程式。

[gpwork4u]

追加：完整 Sprint 1 跑完 + 發現⑬（共 13 個缺陷）

用 benchmark 把請假系統 Sprint 1 完整跑完並收尾（跳過 billing 擋住的 CI、admin merge）：6 lane 全 PR merged、87 unit + 88 e2e、milestone 關閉。

Sprint review 真的抓到跨 lane CRITICAL（per-PR 看不到的）：

• C-1 seed 密碼跨 lane 不一致：backend seed password123 vs qa demo1234，spec 未定義 → e2e 登入全失敗。已修（PR#35，qa 對齊 + 寫進 spec SoT 並關 bug #34）。這正面證明「sprint-end 一次性 review」設計的價值。

發現⑬ code-review / verifier agent 深挖不寫報告：兩個唯讀 agent 逐檔深挖、耗盡 turn 前都沒寫出報告檔（產出指令原在 prompt 末端）。修：agent 開頭結構性強制「報告檔骨架是第一個 Write 動作、邊查邊填、抽查代表性檔即可」（同 deliver-first 的 all-or-nothing 精神）。

至此 benchmark 共揪 13 個可靠度缺陷全修，全 5 種 agent + 完整 sprint 流程（spec→plan→6 lane→review→verify→close）實跑驗證。selftest 8/8。