[CLAUDE] Docs: P0-2 eoffice trắng màn — hotfix bundle local D6lFjgKF + gotcha #92 khắc thật (runner build-env nhiễm, CẤM push code tới khi vá) [skip ci]

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs/gotchas.md

@@ -1455,6 +1455,18 @@ for h in resp.points:    # ← .points không phải iterable trực tiếp
 
 **Luật:** (1) verifier tuyên "đang chờ CI" phải đo **`repo.updated_at ≥ thời-điểm-push`** trước — head khớp chưa đủ; (2) sau restart service có re-index/warm-up: **phép đo latency trong cửa sổ đó là số bẩn**, khai rõ hoặc đợi lắng; (3) SQLEXPRESS trên máy nhỏ: **pin `max server memory` ngay lúc setup** (ghi vào runbook), đừng để default unbounded.
 
+### 92. Runner build-env NHIỄM — CI exit-0 + byte-match CI↔prod nhưng bundle CRASH runtime; "build thành công" ≠ "bundle sống" (Session 189 + 191)
+
+**Triệu chứng (2 ca cùng chữ ký):** deploy CI xanh trọn — test gate pass, bundle rotate, **byte-match CI↔prod từng byte**, smoke HTTP 200 — nhưng mở trang = **trắng màn**. Console: `Uncaught TypeError: Cannot read properties of null (reading 'useState')` ngay dòng đầu bundle. Ca-1 @S189 (P0 sau #486, cả 2 app, outage 15'). Ca-2 @S191 (sau **#600**: fe-user chết / fe-admin sống — nhiễm KHÔNG đồng đều).
+
+**Chữ ký đo được:** bundle CI **lệch size local đáng kể CÙNG commit** dù local build deterministic (2 lần build local ra đúng 1 hash): ca-2 fe-user CI 1.803.881B vs local 1.700.709B (**+103KB**) · fe-admin CI 1.819.492B vs local 1.780.807B (**+39KB**, đang sống nhưng cùng lò). `useState null` = React bị resolve trùng/lệch bản trong graph — dấu node_modules/npm-cache hỏng trên runner (di chứng đêm disk-0-byte #89, npm-cache SYSTEM 12,76GB ghi dở).
+
+**Vì sao lọt 2 lần:** verify deploy đo **file-integrity** (hash CI-log ↔ prod) + **HTTP status** — cả hai đều là tính chất của FILE, không phải của CHƯƠNG TRÌNH. Bundle nhiễm vẫn thắng mọi phép đo đó. Giả thuyết "root-cause = disk, deploy.yml tự xóa node_modules fresh mỗi run nên #92 đóng được" (S190) bị ca-2 **bác**: xóa node_modules không cứu nếu **npm cache** là nguồn nhiễm (`npm ci` kéo lại từ cache hỏng).
+
+**Fix chuẩn (đã chứng ×2):** build local từ HEAD (env lành) → so hash 2 lần build (determinism = control dương) → scp `dist/` đè app chết, **GIỮ bundle hỏng trên đĩa** (index.html cũ = rollback 1 giây) → verify bằng **console + read_page** (form render, load-mới sạch lỗi), KHÔNG chỉ curl.
+
+**Luật:** (1) verify deploy FE phải có **1 phép đo RUNTIME** (console error sau load / marker JS thực thi) — file-integrity + HTTP 200 chưa đủ; (2) bundle CI lệch local >vài KB cùng commit khi local deterministic = **ĐỎ**, chặn trước khi ship; (3) sau sự cố hạ tầng (disk-0, kill-process giữa ghi): coi **mọi cache** của toolchain trên máy đó là nghi phạm — dọn `npm cache` + workspace RỒI MỚI tin build; (4) vá gốc phải **verify bằng dispatch-run + smoke runtime**, tới lúc đó **CẤM push code** (build mới sẽ đè hotfix bằng bundle nhiễm).
+
 ## Checklist debug bug mới
 
 1. Build pass không? → fail → check using + package version compat