docs(memory): record observability UI QA guardrails

docs/memory/README.md

@@ -18,6 +18,7 @@
 | `feedback_db_metadata_import.md` | SQLAlchemy metadata / `create_all()` 漏表鐵律 | 新增 model、修 schema、排查 fresh env 漏表時 |
 | `db_connection_pool_singleton_20260430.md` | PostgreSQL `too many clients` 連線池放大事故與 DatabaseManager singleton 修正 | 排查 DB 連線數暴增、route 內反覆初始化 DatabaseManager、SQLAlchemy engine/pool 行為時 |
 | `project_phase38_56_observability_war_room.md` | Phase 38→56 AI 觀測台戰役落地盤點、已知缺口與後續拆分方向 | 接續觀測台頁面、Telegram 指令、scheduler probe、AutoHeal/CodeReview L2 入口、Chart.js polish 或 deploy_doctor 時 |
+| `observability_ui_qa_guardrails_20260505.md` | AI 觀測台 UI/UX guard、production smoke、CSS mirror 與 quick review 非互動入口 | 修改 `/observability/*` 前端、側欄、topbar、Chart.js、CSS 或部署觀測台前端變更時 |
 | `project_phase3f_cleanup_roadmap.md` | ADR-017 執行矩陣與階段紅線 | 正在做 3f 模組化收尾時 |
 | `code_modularization_inventory_20260430.md` | Python 大檔盤點、分層規範與拆分工作項目 | 新增功能、拆大檔、審查是否違反模組化治理時 |
 | `schema_inventory_baseline.md` | DB 表分類與 drift 基線 | 要收斂 migration / ORM / raw SQL 真相時 |

docs/memory/observability_ui_qa_guardrails_20260505.md

@@ -0,0 +1,60 @@
+# AI 觀測台 UI QA Guardrails（2026-05-05）
+
+## 背景
+
+Claude Code Phase 38→55 完成 AI 觀測台 10 頁，但前端曾出現以下問題：
+
+- 側欄第二/三層字色太暗，看不清楚。
+- 側欄背景回退成近純黑，偏離暖咖啡設計規範。
+- 觀測台頁面 typography / spacing / button / table / chart 容器不一致。
+- `observability-system.css` 在 template 有 link，但 production `/static/css/observability-system.css` 曾 404。
+- 前端互動曾外露 `Error: ...`、`unknown`、SQL/Jinja raw error 類文案。
+
+## 現行治理入口
+
+- UI 規範 guide：`docs/guides/observability_ui_governance.md`
+- 部署 SOP：`docs/guides/deployment_sop.md`
+- 頁面契約 SOT：`scripts/observability_contract.py`
+- 靜態 UI guard：`scripts/check_observability_ui.py`
+- Production smoke：`scripts/check_observability_pages.py`
+- 一鍵 QA：`scripts/check_observability_suite.sh`
+- CSS mirror sync：`scripts/sync_observability_css.py`
+
+## 必跑指令
+
+修改觀測台 template、route、shell、topbar、CSS 後：
+
+```bash
+./scripts/quick_review.sh --sync-observability-css
+./scripts/quick_review.sh --observability-qa
+```
+
+等效直接指令：
+
+```bash
+python3 scripts/sync_observability_css.py
+bash scripts/check_observability_suite.sh
+```
+
+## 重要陷阱
+
+- `static/css/observability-system.css` 是 canonical CSS。
+- `web/static/css/observability-system.css` 是 Flask production static route 實際服務用 mirror。
+- 兩者必須 byte-identical；guard 會檢查，不一致時跑 `sync_observability_css.py`。
+- Production smoke 必須看到 `觀測台 CSS: HTTP 200, markers=ok`。
+- 觀測台頁面清單、URL、`active_page`、內容 marker 不要分散維護，先改 `scripts/observability_contract.py`。
+
+## 已鎖住的回歸
+
+- Times / Georgia / serif 標題字型。
+- 超大 hard-coded clamp title。
+- 圖表 inline `style="height:..."`。
+- 靜態 inline width。
+- 純白 hover/card surface。
+- raw SQL/Jinja exception 外露。
+- raw `alert('Error: ...')` / `unknown` 前端文案。
+- 側欄純黑背景。
+- 側欄第二/三層低對比文字。
+- 觀測台 URL 有側欄連結但 Flask route 不存在。
+- 觀測台頁面 200 但內容 marker 缺失。
+- CSS link 存在但 production static asset 404。