ci(observability): verify CSS mirror instead of mutating runner

.gitea/workflows/cd.yaml

@@ -160,7 +160,7 @@ jobs:
       - name: AI 觀測台 Pre-deploy 靜態 QA
         if: steps.observability_qa.outputs.needed == 'true'
         run: |
-          bash ./scripts/quick_review.sh --sync-observability-css
+          bash ./scripts/quick_review.sh --check-observability-css
           bash ./scripts/quick_review.sh --observability-qa --skip-production
 
       # ── 模式 A：僅同步 Python 檔案（最常見，~10s） ────────────────────────

docs/guides/deployment_sop.md

@@ -48,6 +48,7 @@ ssh -J wooo@192.168.0.110 ollama@192.168.0.188 \
 本地先跑：
 ```bash
 ./scripts/quick_review.sh --sync-observability-css
+./scripts/quick_review.sh --check-observability-css
 ./scripts/quick_review.sh --observability-qa
 ```
 
@@ -72,7 +73,7 @@ QA 套件會檢查：
 
 CD 也會自動判斷觀測台相關變更：
 
-- Deploy 前跑 `./scripts/quick_review.sh --sync-observability-css`。
+- Deploy 前跑 `./scripts/quick_review.sh --check-observability-css`，確認 CSS mirror 已提交一致，不在 runner 內偷偷修。
 - Deploy 前跑 `./scripts/quick_review.sh --observability-qa --skip-production`。
 - Deploy 後跑 `./scripts/quick_review.sh --observability-smoke --base-url https://mo.wooo.work --timeout 12`。
 - 若變更與觀測台無關，CD 會跳過這組額外 QA，避免拖慢一般後端部署。

docs/guides/observability_ui_governance.md

@@ -54,6 +54,7 @@ python3 scripts/check_observability_ui.py
 
 ```bash
 python3 scripts/sync_observability_css.py
+python3 scripts/sync_observability_css.py --check
 ```
 
 或透過既有 quick review 選單執行第 8 項完整 QA 套件、第 6 項靜態 UI guard、第 9 項 CSS mirror sync：
@@ -66,6 +67,7 @@ python3 scripts/sync_observability_css.py
 
 ```bash
 ./scripts/quick_review.sh --sync-observability-css
+./scripts/quick_review.sh --check-observability-css
 ./scripts/quick_review.sh --observability-qa
 ```
 

docs/memory/observability_ui_qa_guardrails_20260505.md

@@ -26,6 +26,7 @@ Claude Code Phase 38→55 完成 AI 觀測台 10 頁，但前端曾出現以下
 
 ```bash
 ./scripts/quick_review.sh --sync-observability-css
+./scripts/quick_review.sh --check-observability-css
 ./scripts/quick_review.sh --observability-qa
 ```
 
@@ -42,6 +43,7 @@ Claude Code Phase 38→55 完成 AI 觀測台 10 頁，但前端曾出現以下
 
 ```bash
 python3 scripts/sync_observability_css.py
+python3 scripts/sync_observability_css.py --check
 bash scripts/check_observability_suite.sh
 ```
 
@@ -53,7 +55,7 @@ bash scripts/check_observability_suite.sh
 - Production smoke 必須看到 `觀測台 CSS: HTTP 200, markers=ok`。
 - 觀測台頁面清單、URL、`active_page`、內容 marker 不要分散維護，先改 `scripts/observability_contract.py`。
 - `quick_review.sh --observability-qa` 預設打 production `https://mo.wooo.work`；測 staging/localhost 時要明確帶 `--base-url`。
-- Gitea CD 會偵測觀測台 template/CSS/route/QA script/guide 變更：deploy 前跑 CSS sync + static QA，deploy 後跑 production smoke。
+- Gitea CD 會偵測觀測台 template/CSS/route/QA script/guide 變更：deploy 前跑 CSS mirror check + static QA，deploy 後跑 production smoke。CD 不會偷偷修 mirror；若 check fail，先本地跑 sync 後提交。
 
 ## 已鎖住的回歸
 

scripts/quick_review.sh

@@ -83,7 +83,7 @@ run_observability_css_sync() {
     fi
 
     echo -e "${GREEN}🎨 同步 AI觀測台 CSS 到 Flask static path...${NC}"
-    python3 "$OBSERVABILITY_CSS_SYNC"
+    python3 "$OBSERVABILITY_CSS_SYNC" "$@"
 }
 
 # 非互動入口：給部署腳本、CI、或 Codex session 直接呼叫。
@@ -106,7 +106,12 @@ if [ $# -gt 0 ]; then
             ;;
         --sync-observability-css)
             shift
-            run_observability_css_sync
+            run_observability_css_sync "$@"
+            exit $?
+            ;;
+        --check-observability-css)
+            shift
+            run_observability_css_sync --check
             exit $?
             ;;
         --observability-help)
@@ -114,6 +119,8 @@ if [ $# -gt 0 ]; then
 AI observability quick-review flags:
   --sync-observability-css
       Sync static/css/observability-system.css to web/static/css mirror.
+  --check-observability-css
+      Verify CSS mirror is already committed and in sync.
   --observability-ui
       Run static UI/template/navigation guard only.
   --observability-smoke [--base-url URL] [--timeout SEC]

scripts/sync_observability_css.py

@@ -13,6 +13,7 @@ This helper keeps the two files byte-identical so deploys do not regress into
 
 from __future__ import annotations
 
+import argparse
 import shutil
 from pathlib import Path
 
@@ -23,20 +24,38 @@ TARGET = ROOT / "web/static/css/observability-system.css"
 
 
 def main() -> int:
+    parser = argparse.ArgumentParser(description="Sync or check observability CSS mirror")
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help="Only verify source and Flask static mirror are byte-identical.",
+    )
+    args = parser.parse_args()
+
     if not SOURCE.exists():
         print(f"ERROR: missing source CSS: {SOURCE.relative_to(ROOT)}")
         return 1
 
-    TARGET.parent.mkdir(parents=True, exist_ok=True)
+    if not args.check:
+        TARGET.parent.mkdir(parents=True, exist_ok=True)
+
     source_bytes = SOURCE.read_bytes()
     target_bytes = TARGET.read_bytes() if TARGET.exists() else b""
 
     if source_bytes == target_bytes:
-        print("Observability CSS sync: already in sync")
+        action = "check" if args.check else "sync"
+        print(f"Observability CSS {action}: already in sync")
         print(f"- source: {SOURCE.relative_to(ROOT)}")
         print(f"- target: {TARGET.relative_to(ROOT)}")
         return 0
 
+    if args.check:
+        print("Observability CSS check: FAIL")
+        print(f"- source: {SOURCE.relative_to(ROOT)}")
+        print(f"- target: {TARGET.relative_to(ROOT)}")
+        print("- fix: python3 scripts/sync_observability_css.py")
+        return 1
+
     shutil.copyfile(SOURCE, TARGET)
     print("Observability CSS sync: synced")
     print(f"- source: {SOURCE.relative_to(ROOT)}")