1.9 KiB
1.9 KiB
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.