# Anti-Drift Guardrails

This document exists to prevent architectural regression
caused by convenience changes, AI tooling, or incomplete context.

---

## Primary Drift Risk: Frontend Shortcuts

The most common drift vector is:

**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
- Leaving a comment
- Asking for review

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:
- CSRF
- Cookies for auth
- Pterodactyl
- APIv1 routes

That code must be removed or refactored before merge.