Skill optimization pass: routing, fail-closed gates, colour pipeline, memory integrity and canonical backport

[Hao0321]

目標與任務

相關 Issue：無（維護者直接要求的全面檢查與優化）

這個 PR 要解決什麼問題？
全面檢查 Video Autopilot Kit 的架構、視覺、美感、品質、規則與記憶。稽核找到多個「看起來綠、其實沒擋」的閘門、色彩矩陣錯誤、記憶可被重複計分或寫壞，以及文件與程式互相矛盾的規則。這個 PR 修正它們，並新增 scripts/canonical_backport.py，讓這些公開修改能先回寫到私有 canonical，再由 sync_canonical.py 正常同步。

變更範圍

• Skill 路由：公開 SKILL.md 依任務路由全部 56 份 references（大檔只讀指定章節），每次任務先讀 creator 記憶與 context packet，並定義完成標準。觸發描述加入中文需求詞。agent card 不再預設提供遠端審片連結。

• 回寫工具：canonical_backport.py 逐個 first-parent commit 重播並做三方合併，保留 BOM 與換行。公開版專用的改寫不寫回；--apply 失敗會整批還原；重跑結果是 ALREADY_APPLIED。另新增指令入口 scripts/hao_autopilot.py。

• 審片完整性：審片以 HMAC 綁定成片 sha256，拒絕自我認證。缺證據是明確的 REVIEW 缺口；NaN、布林與文字評分不計分。只有 CERTIFIED_95 算已認證或可發布。

• 閘門 fail-closed

  • 訪談來源必須標類型；共用佔位字偵測。
  • 合規章要有日期與複核人。
  • 片長必須是有限正數。
  • proof 圖以實際路徑或 hash 比對。
  • 對標合約凍結 hash。
  • gate_core 缺 fails 或零條檢查一律紅。

• 媒體 QA：WCAG 閃光、長黑段、全片 letterbox、Shorts true peak ≤ -1 dBTP、缺音軌或影軌、-inf 響度與特殊字元檔名，都會判為失敗或 UNVERIFIED。三態結果中，任何非 PASS 都擋交付。

• Workflow controller：resume --reaudit 處理過期或已用過的 audit receipt。state lock 改用 owner token，且只回收已死的持有者。plan 在 audit、apply 與 verify 時重新驗證。

• 記憶與學習

  • 成效 baseline 依平台、片型與窗口分開計算，排除早、晚與重複的擷取。
  • taste 至少要 5 次不同比較，再加 95% Wilson 信賴區間判斷偏好。
  • channel state 鎖定並原子寫入。
  • 學到的規則存在 data/knowledge_state.json，更新不會覆蓋。

• 色彩與特效：RGB 濾鏡以明確的 BT.709 轉換包住。identity LUT 的 PSNR 從 29.5 dB 提升到約 70 dB。HDR normaliser 統一為 npl=100。bloom、掃描線、halftone、whip 與 Ken Burns 的數學錯誤已修正。

• 更新器：中斷的更新會自動回滾（INTERRUPTED_TRANSACTION_RECOVERED／INTERRUPTED_TRANSACTION），並加上安裝鎖（LOCKED）。Windows 更新後改用子行程重啟；壓縮檔順序在各 OS 一致。

• 文件與規則：對齊程式的項目：

  • 調色順序與 LUT 強度
  • 本機審片 serve
  • 教學片節奏（以 pace_gate 為界）
  • 母帶響度 -14 LUFS／-1 dBTP
  • Signal Grid 改列為 legacy
  • voice 規則
  • 縮圖測試
  • 公開 DNA 數量

  另外，script_gate.load_vocab() 恢復可用。公開文件的審片人改用角色稱呼「創作者」（同步規則，canonical 保留原文）。

• 健康檢查：system_health --quick 新增各閘門、記憶、回寫工具、媒體 QA 與範例 02/04/05/06 的 self-test，並偵測 Python 3.9 import 時會崩潰的 X | Y 型別註記。

相容性影響（呼叫端要注意）：

• gate_core.make_assert 遇到沒有 fails 的 report 會 raise。
• 訪談 plan 要先填真的 CLUSTER。
• examples/PLAN_TEMPLATE.md 原樣會被擋，這是刻意的。
• Shorts 交付必須 30/1 fps；loop 為 required 時，首末幀相關係數要 ≥ 0.6。
• due_report 改回傳 actions_by_owner；outcome playbook 升到 schema 2。
• LUT 相關函式回傳完整的 BT.709 chain。
• 舊 pipeline.py 的 HDR 輸出會變亮（npl 250→100）。

AI 協助範圍：全部由 Claude Code 產生。七個修補包在隔離 worktree 由子代理完成；主代理逐一審 diff、cherry-pick，並重跑回歸測試。

驗證證據

環境：Linux、Python 3.12.3 與 3.9.25、ffmpeg 6.1.1。在乾淨匯出的樹上執行 CI 的全部步驟。為了模擬維護者同步後的狀態，匯出樹內的 receipt 只在暫存區刷新，沒有提交。

檢查	3.12	3.9
py_compile、public_skill_skeleton.py、sanitizer self-test（68 managed outputs）	✅	✅
public_privacy_gate.py --self-test	✅ GREEN	✅ GREEN
sync_canonical.py --self-test（含 reviewer role transform）	✅	✅
check_links / check_drift	✅ PASS	✅ PASS
architecture_gate.py audit	✅ GREEN（fail 0；review 55→51）	✅
system_health.py --quick	✅ HEALTH GREEN	✅ HEALTH GREEN
來源樹不被改動	✅	✅
release_manager.py selftest	✅（94 s）	✅（94 s）

• canonical 模擬：用 b449e7a 公開樹建立的擬 canonical 執行回寫。dry run 沒有 CONFLICT/ERROR；--apply 寫入 48 檔，重跑全部 ALREADY_APPLIED。只做改寫的檔案全部 ALREADY_APPLIED，canonical 保留原文。
• 私有樣式模擬：visual_director.py 與 channel_tracker.py 的私有樣式模擬，合併乾淨，重新同步後與公開檔逐 byte 相同。
• 各修補包：都在 3.12 與 3.9 跑過自己的 self-test 與 probe（修前重現、修後通過）。色彩 PSNR 與 WCAG 閃光等前後數據已記錄在各 commit 訊息與工作紀錄。

預期中的紅燈：這個 PR 改了 derived 檔，sync-receipt.json 的 output hash 會不一致。依 CONTRIBUTING，receipt 不手動修改，要等維護者回寫 canonical 並同步後重新產生。在那之前，CI 的 Quick health 與 reproducible-release 的 --verify-receipt 會紅。

未驗證：

• Windows／macOS 實機（交給 CI matrix）。
• 真實素材的成片視覺。
• 私有 canonical 的實際合併結果（需要維護者本機）。
• 範例 01／03（需要渲染）在本 PR 最終版尚未重跑。

安全、隱私與依賴

• 我已閱讀 diff，沒有私人資料、媒體、憑證或可存取的審片連結。
• 我有權以本專案 MIT 授權提供這些變更；第三方內容保留來源與授權。
• 本次涉及安裝／更新、外部指令、網路、依賴、workflow、發布、隱私或授權。

若勾選最後一項，說明目的、輸入來源、權限、風險與對應驗證：

• 更新器（release_manager.py、startup_update.py、install_or_upgrade.py）
  • 中斷回滾與安裝鎖只在安裝根目錄的 .video-autopilot/ 內寫檔。
  • 只有在恰好一筆 PENDING、而且受管檔符合新舊其中一版時，才會自動回滾；其他情況回報 INTERRUPTED_TRANSACTION，交由人工處理。
  • 錯誤訊息若含絕對路徑，只回報錯誤型別。
  • 驗證：release self-test 新增 8 個階段，包含實際 kill 子行程。
• 外部指令：新增的 ffmpeg 呼叫都是本機分析或轉檔，沒有網路。canonical_backport.py 只呼叫本機 git，寫入前會備份。
• 隱私：新的公開同步規則只改寫公開版文字。沒有新依賴，也沒有改 workflow 檔。

驗收與回復方式

驗收（維護者本機）：

git fetch origin; git checkout feat/skill-optimization-audit
python scripts/canonical_backport.py --canonical "$env:USERPROFILE\.codex\skills\video-autopilot" --workspace <公開 kit 資料夾的上一層> --base b449e7a
python scripts/canonical_backport.py --canonical "$env:USERPROFILE\.codex\skills\video-autopilot" --workspace <同上> --base b449e7a --apply
python scripts/sync_canonical.py --canonical "$env:USERPROFILE\.codex\skills\video-autopilot"
git status   # 應只剩 sync-receipt.json；提交並推上這個分支後 CI 應轉綠

• 私有 SKILL.md 不會自動回寫。--apply 會在備份資料夾輸出 SKILL.public-delta.diff，需要手動合併。
• 合併請用 merge commit（不要 squash），保留逐 commit 重播資訊。

已知限制與後續：

• audit.config.json 有 5 個架構例外在 2026-12-31 到期，2027-01-01 起 CI 會紅，需要重構或延期決定。
• loop 相關係數門檻 0.6 尚未用真片校準。
• color_calibration_lab._sample_image 擷取幀時仍未指定色彩矩陣。

回復：

• 公開 repo：revert merge commit。
• canonical：--apply 前的原檔在 .video-autopilot/backport/<時間>/，失敗時工具已自動還原。

共同貢獻

Claude Code（AI）：稽核、實作、測試與文件。維護者審查待進行。

🤖 Generated with Claude Code

https://claude.ai/code/session_01XLikBpKWqhMahFDuvVj6wh

---

Generated by Claude Code

[Hao0321]

CI 狀態（head f8a06cc）：7 個 job（verify ×6、reproducible-release）都停在同一步 sync_canonical.py --verify-receipt，錯誤是 SYNC RECEIPT RED: receipt output hash mismatch。不一致的是 30 個 derived 輸出：SKILL.md、agents/openai.yaml、workflow_contract.py、workflow_audit_binding.py、design_runtime/src/aesthetic_score.py，以及 25 份 references。在這一步之前的 privacy、sanitizer 與 sync self-test，CI 上都是 GREEN。

原因： 這個 PR 改了由私有 canonical 產生的 derived 檔，而 sync-receipt.json 記錄的是上次維護者同步時的 hash。依 CONTRIBUTING，receipt 不能手動修改，只能由維護者從 canonical 同步重新產生，所以這個 PR 內無法修正。這是固定的 hash 不一致，不是 flake，重跑結果不會變，所以我沒有 re-run。

解除方式： 維護者在本機依 PR 說明的「驗收與回復方式」操作：

1. 執行 canonical_backport.py，先 dry run，再加 --apply。
2. 執行 sync_canonical.py --canonical ...。
3. 把重新產生的 sync-receipt.json 提交到這個分支，CI 就會重跑。

本機驗證： 我在 Python 3.12 與 3.9 跑過全部 14 個 CI 步驟，receipt 只在暫存區刷新、沒有提交，結果都是綠的。

維護者本機的新版推上 main 之後，我會用 merge commit 把 main 合進這個分支並重新驗證。

---

Generated by Claude Code