246 lines
3.7 KiB
Markdown
246 lines
3.7 KiB
Markdown
# GUARDRAILS
|
|
|
|
These systems are **currently working** and must **not be broken by AI refactors**.
|
|
|
|
AI tools must **prefer minimal changes** and avoid architecture changes unless explicitly instructed.
|
|
|
|
---
|
|
|
|
# Core Principle
|
|
|
|
If a task can be solved with a **small change**, the AI must **not perform a large rewrite**.
|
|
|
|
---
|
|
|
|
# Git Workflow Rules
|
|
|
|
The AI must **NEVER commit directly to `master` or `main`.**
|
|
|
|
All changes must be made via a branch.
|
|
|
|
## Branch naming conventions
|
|
|
|
Feature work:
|
|
|
|
feature/<short-description>
|
|
|
|
Bug fixes:
|
|
|
|
fix/<short-description>
|
|
|
|
Examples:
|
|
|
|
feature/supabase-public-endpoint
|
|
fix/smoke-check-url
|
|
fix/magic-link-auth
|
|
|
|
## Required workflow
|
|
|
|
1. Create a branch from `master`
|
|
2. Make the required changes
|
|
3. Commit changes to that branch
|
|
4. Show the diff
|
|
5. Do **not merge automatically**
|
|
6. Raise a pull request
|
|
7. User performs merge after review
|
|
|
|
---
|
|
|
|
# Infrastructure Protection
|
|
|
|
The AI must **not modify infrastructure** unless explicitly instructed.
|
|
|
|
This includes:
|
|
|
|
- DNS records
|
|
- reverse proxy configuration
|
|
- SSL certificates
|
|
- server networking
|
|
- firewall rules
|
|
- Proxmox configuration
|
|
- VM/LXC creation
|
|
- Nginx Proxy Manager configuration
|
|
- Supabase server configuration
|
|
|
|
These systems are **managed manually**.
|
|
|
|
---
|
|
|
|
# CI/CD
|
|
|
|
The Jenkins pipeline currently **builds and deploys the application**.
|
|
|
|
Deployment process:
|
|
|
|
docker save → scp → docker load
|
|
|
|
The AI must **not change the deployment architecture** without instruction.
|
|
|
|
Allowed CI changes:
|
|
|
|
- fixing pipeline bugs
|
|
- improving reliability
|
|
- adding environment variables
|
|
- improving logs
|
|
|
|
Not allowed:
|
|
|
|
- replacing Jenkins
|
|
- replacing Docker deployment
|
|
- changing deployment host
|
|
- introducing Kubernetes
|
|
- major CI architecture changes
|
|
|
|
---
|
|
|
|
# Container
|
|
|
|
Container name:
|
|
|
|
plesk-agency-portal
|
|
|
|
Deployment path:
|
|
|
|
/opt/plesk-agency-portal
|
|
|
|
The AI must **not rename containers or paths** without explicit approval.
|
|
|
|
---
|
|
|
|
# Reverse Proxy
|
|
|
|
Reverse proxy is managed by:
|
|
|
|
Nginx Proxy Manager
|
|
|
|
Public application URL:
|
|
|
|
https://portal.rdbcloud.co.uk
|
|
|
|
Supabase public endpoint:
|
|
|
|
https://supabase.rdbcloud.co.uk
|
|
|
|
The AI must **not change reverse proxy configuration**.
|
|
|
|
---
|
|
|
|
# Authentication
|
|
|
|
Authentication system:
|
|
|
|
Supabase Magic Link
|
|
|
|
Required environment variables:
|
|
|
|
NEXT_PUBLIC_SUPABASE_URL
|
|
SUPABASE_URL
|
|
NEXT_PUBLIC_SUPABASE_ANON_KEY
|
|
|
|
The AI must **not replace the authentication system**.
|
|
|
|
---
|
|
|
|
# Environment Variables
|
|
|
|
Secrets must **never be committed to the repository**.
|
|
|
|
Secrets must come from:
|
|
|
|
- Jenkins credentials
|
|
- environment variables
|
|
- deployment configuration
|
|
|
|
Never commit:
|
|
|
|
API keys
|
|
private tokens
|
|
database passwords
|
|
service keys
|
|
|
|
---
|
|
|
|
# Docker
|
|
|
|
Docker is used for **build and deployment**.
|
|
|
|
The AI may:
|
|
|
|
- update Dockerfile
|
|
- fix build issues
|
|
- improve caching
|
|
|
|
The AI must **not introduce complex container orchestration**.
|
|
|
|
Not allowed:
|
|
|
|
kubernetes
|
|
docker swarm
|
|
nomad
|
|
terraform
|
|
|
|
Unless explicitly requested.
|
|
|
|
---
|
|
|
|
# Database
|
|
|
|
Database system:
|
|
|
|
Supabase Postgres
|
|
|
|
The AI must **not perform destructive database changes**.
|
|
|
|
Not allowed automatically:
|
|
|
|
DROP TABLE
|
|
DROP COLUMN
|
|
DELETE large datasets
|
|
schema rewrites
|
|
|
|
Schema changes must be **reviewed first**.
|
|
|
|
---
|
|
|
|
# Safe Refactoring Rules
|
|
|
|
Allowed:
|
|
|
|
- small code improvements
|
|
- bug fixes
|
|
- performance improvements
|
|
- logging improvements
|
|
- type fixes
|
|
- lint fixes
|
|
|
|
Avoid:
|
|
|
|
- large rewrites
|
|
- framework changes
|
|
- directory restructuring
|
|
- renaming large parts of the codebase
|
|
|
|
Unless specifically requested.
|
|
|
|
---
|
|
|
|
# When AI Is Unsure
|
|
|
|
If the AI is unsure:
|
|
|
|
1. Explain the risk
|
|
2. Ask for clarification
|
|
3. Do **not proceed with risky changes**
|
|
|
|
---
|
|
|
|
# Priority Order
|
|
|
|
When making decisions, the AI must prioritise:
|
|
|
|
1. **Do not break production**
|
|
2. **Respect guardrails**
|
|
3. **Make minimal safe changes**
|
|
4. **Preserve deployment pipeline**
|
|
5. **Follow branch workflow**
|