docs: expand drift prevention rules with AI-specific guardrails

ANTI_DRIFT_GUARDRAIL.md

@@ -1,21 +1,76 @@
-# ZLH Frontend Guardrails
+# Anti-Drift Guardrails
 
-This file is intended for Codex / AI agents and human contributors.
+This document exists to prevent architectural regression
+caused by convenience changes, AI tooling, or incomplete context.
 
-## Primary Objective
+---
-ZeroLagHub's frontend is a **control surface**, not a game UI.
 
-## Guardrails
+## Primary Drift Risk: Frontend Shortcuts
-- Prefer boring, predictable UI over clever abstractions
+
-- Do not introduce new visual metaphors without removing an old one
+The most common drift vector is:
-- No "sci-fi" effects unless strictly informational
+
-- Avoid abstractions that hide client/server boundaries
+**Frontend → Agent**
+
+This is **always wrong**, regardless of environment.
+
+---
+
+## Guardrail Rules (Hard)
+
+- Browsers never call agents
+- Browsers never see container IPs
+- Agents never expose CORS headers
+- API is the only control plane
+
+---
+
+## Codex / AI-Specific Guardrails
+
+When using AI tools:
+
+- Explicitly forbid frontend → agent calls
+- Require API-only control paths
+- Reject changes that "just work" via shortcuts
+- Prefer deletion over convenience
+
+If AI introduces direct agent calls:
+- The change is invalid
+- The prompt must be corrected
+
+---
+
+## Status & State Drift
+
+- UI state is observational
+- Pollers are authoritative
+- Buttons express intent only
+- No optimistic state transitions
+
+---
+
+## Restart Semantics
+
+- Restart is agent-defined
+- Restart is not "stop + start" in UI
+- Restart must preserve PTY continuity where possible
+
+---
 
 ## Terminal & Realtime UI Rules
 - Terminal components must be isolated and client-only
 - No terminal logic in shared utilities
 - No implicit socket initialization at import time
 
+---
+
+## UI Philosophy
+- Prefer boring, predictable UI over clever abstractions
+- Do not introduce new visual metaphors without removing an old one
+- No "sci-fi" effects unless strictly informational
+- Avoid abstractions that hide client/server boundaries
+
+---
+
 ## When Unsure
 Default to:
 - Removing code
@@ -24,6 +79,18 @@ Default to:
 
 Silence is better than instability.
 
+---
+
+## Enforcement Rule
+
+If behavior and documentation disagree:
+
+> **Documentation wins.**
+
+This file exists to stop slow erosion of system integrity.
+
+---
+
 ### Enforcement Note (Dec 28)
 
 If portal code references: