Claude e961e2cb23 Make deployment safeguards safer - support temporary hybrid deployment ...

CONTEXT:
The monorepo IS being deployed temporarily to Railway (service: BlackRoad-Operating-System,
project: gregarious-wonder, domain: app.blackroad.systems) to get BR-95 desktop UI online
quickly while satellite infrastructure is being built. This is explicitly temporary.

This commit adds stronger safeguards that:
1. Acknowledge the temporary deployment
2. Prevent it from becoming permanent
3. Ensure migration plan exists and is tracked
4. Provide automated validation at multiple checkpoints

CHANGES:

1. TEMPORARY_DEPLOYMENT.md (NEW) - Complete Migration Plan
   - Documents current temporary hybrid deployment
   - Explains why temporary deployment was chosen
   - Provides 4-phase migration plan to satellites
   - Lists allowed temporary deviations
   - Includes success metrics and governance

2. DEPLOYMENT_ARCHITECTURE.md - Updated with Hybrid Mode
   - Added "Current Status: Temporary Hybrid Deployment" section
   - Clarified current state vs target state
   - Updated deployment status (temporarily deployed, should not be permanent)
   - Added allowed temporary deviations
   - Timeline for migration (6-10 weeks)

3. scripts/validate_deployment_config.py - Smarter Validation
   - check_railway_toml(): Now distinguishes temporary vs permanent deployment
     * Allows temporary deployment with warnings
     * Errors on permanent deployment without "temporary" marker
     * Checks for migration plan references
   - check_env_files(): Context-aware validation
     * Warnings for temporary monorepo URLs in ALLOWED_ORIGINS
     * Errors for hardcoded monorepo URLs elsewhere
     * Allows temporary deviations with migration warnings
   - check_migration_plan(): NEW function
     * Checks for TEMPORARY_DEPLOYMENT.md or MIGRATION_TO_SATELLITES.md
     * Warns if temporary deployment lacks migration plan
   - Better error messages with actionable guidance

4. .githooks/pre-commit (NEW) - Local Validation
   - Runs validation script before each commit
   - Checks railway.toml for "temporary" marker
   - Scans staged files for hardcoded monorepo URLs
   - Prevents accidental permanent deployment
   - Bypassable with --no-verify if needed

5. .githooks/setup.sh (NEW) - Easy Hook Installation
   - Configures Git to use .githooks/ directory
   - Makes hooks executable
   - Tests validation script
   - User-friendly setup process

6. .githooks/README.md (NEW) - Hook Documentation
   - Installation instructions
   - Hook descriptions
   - Troubleshooting guide
   - Development guidelines

7. .github/workflows/validate-deployment-config.yml (NEW) - CI Validation
   - Runs on PRs touching deployment configs
   - Validates deployment configuration
   - Checks for temporary markers
   - Checks for migration plan
   - Comments on PRs with results
   - Prevents merge of invalid configs

SAFETY IMPROVEMENTS:

✅ BEFORE: Strict "never deploy monorepo" policy (unrealistic given current state)
✅ AFTER: Pragmatic "temporary OK, permanent forbidden" policy

✅ BEFORE: Manual validation only
✅ AFTER: Automated validation at 3 checkpoints (pre-commit, CI, validation script)

✅ BEFORE: No migration tracking
✅ AFTER: Complete migration plan with timeline and governance

✅ BEFORE: Binary pass/fail validation
✅ AFTER: Warnings vs errors based on context

VALIDATION RESULTS:

Expected output from validation script:
⚠️  WARNING: Monorepo is being deployed TEMPORARILY
⚠️  WARNING: Temporary monorepo reference in ALLOWED_ORIGINS
✅ PASSED: railway.toml acknowledges temporary monorepo deployment
✅ PASSED: Migration plan documentation exists
✅ PASSED: Satellite sync configuration complete

GOVERNANCE:

- Weekly reviews to track migration progress
- Monthly updates to TEMPORARY_DEPLOYMENT.md
- Automated reminders if migration stalls
- Hard deadline: 12 weeks to migrate or re-evaluate

USE CASES:

1. Developer adds monorepo to Railway without "temporary" marker
   → Pre-commit hook catches it, blocks commit
   → CI catches it, blocks PR merge

2. Developer updates railway.toml and removes "temporary" marker
   → Pre-commit hook warns about migration status
   → CI requires migration plan update

3. Developer adds hardcoded monorepo URL
   → Pre-commit hook catches it in staged files
   → Validation script errors on non-ALLOWED_ORIGINS usage

4. Weekly review finds migration behind schedule
   → TEMPORARY_DEPLOYMENT.md tracks status
   → Team can escalate or adjust timeline

MIGRATION PATH:

Current: Temporary monorepo deployment
→ Phase 1 (2-4 weeks): Prepare satellites
→ Phase 2 (1-2 weeks): Deploy satellites
→ Phase 3 (2-3 weeks): Migrate traffic
→ Phase 4 (1 week): Deprecate monorepo
→ Future: Pure satellite architecture

See: TEMPORARY_DEPLOYMENT.md for complete details

FILES CHANGED: 7 files, 890 insertions(+), 30 deletions(-)

2026-01-24 04:26:59 +00:00

13 KiB

Executable File

Raw Blame History

View Raw