103 lines
1.9 KiB
Markdown
103 lines
1.9 KiB
Markdown
# 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.
|