Fleet Management

Fleet Management

Maintain cognitive architecture consistency across all heir projects from Master Alex.

The Challenge

Master Alex evolves continuously — new skills, refined instructions, fixed defects. Heir projects run stale brains unless actively synchronized. Manual updates across 50+ projects is error-prone and tedious.

Fleet Operations Model

┌─────────────────────────────────────────────────────────────────┐
│  Master Alex (.github/)                                         │
│    ↓ sync-to-heir.cjs                                           │
│  Heir Template (heir/.github/)                                  │
│    ↓ upgrade-brain.cjs                                          │
│  Fleet (C:\Development\*\.github/)                              │
└─────────────────────────────────────────────────────────────────┘

Tools

Workflow

Phase 1: Prepare Master

Before fleet upgrade, ensure Master Alex is healthy:

# 1. Run brain QA
node .github/muscles/brain-qa.cjs

# 2. Verify zero failures
# Check: "0 failing" in queue depth

# 3. Sync to heir template
node scripts/sync-to-heir.cjs

Phase 2: Audit Fleet

Discover what needs updating:

# Audit all projects in C:\Development
node scripts/upgrade-brain.cjs --mode Audit

# Audit specific projects
node scripts/upgrade-brain.cjs --mode Audit --include "health,pbi"

Output shows:

• Project count and brain formats
• Custom CI needing manual curation
• Workflows and memory to preserve
• Total files affected

Phase 3: Upgrade Fleet

Two-phase approach — mechanical batch + semantic curation:

# Dry-run first (always!)
node scripts/upgrade-brain.cjs --mode Upgrade --dry-run

# Execute upgrade
node scripts/upgrade-brain.cjs --mode Upgrade

# Or full pipeline: Audit → Upgrade → Verify
node scripts/upgrade-brain.cjs --mode Full

The script:

1. Renames .github/ → .github-backup-YYYYMMDD/ (atomic, instant rollback available)
2. Installs fresh brain from extension source
3. Restores non-brain content (workflows, episodic memories, domain knowledge)
4. Saves old copilot-instructions.md as .backup.md for identity curation

Phase 4: Verify

Confirm deployments succeeded:

node scripts/upgrade-brain.cjs --mode Verify

Checks:

• .alex-brain-version stamp matches expected
• All brain subdirectories present with correct file counts
• copilot-instructions.md is v8 format
• hooks.json registry exists

Phase 5: Curate

Projects with custom CI need manual curation:

# Scan backups for custom content
node .github/muscles/brain-upgrade.cjs --mode Scan

# Review each project's backup
# Merge project-specific content back into fresh CI
# Delete backup when satisfied

Exclusions

Some projects are excluded by default:

Override with -Include or modify -Exclude parameter.

Rollback

If something goes wrong:

# Rollback specific project
node scripts/upgrade-brain.cjs --mode Rollback --include "projectname"

# Manual rollback (any time before backup deletion)
# Remove .github/ and rename .github-backup-YYYYMMDD-HHMMSS/ to .github/

Scheduled Maintenance

Run fleet health checks weekly via GitHub Actions or manual invocation:

node scripts/upgrade-brain.cjs --mode Audit

Version Stamps

Each upgraded project gets .github/.alex-brain-version:

8.0.1

Check fleet versions:

Get-ChildItem C:\Development -Directory | 
  ForEach-Object { 
    $v = Join-Path $_.FullName ".github\.alex-brain-version"
    if (Test-Path $v) { 
      "$($_.Name): $(Get-Content $v)" 
    }
  }

Drift Detection

Detect when heir projects have diverged from master:

# Compare heir brain to source
node scripts/audit-heir-sync-drift.cjs

# Or check manually
# Source: heir/.github/ (generated by sync-to-heir.cjs)
# Target: each project's .github/

Best Practices

1. Always dry-run first — node scripts/upgrade-brain.cjs --mode Upgrade --dry-run
2. Audit before upgrade — Know what you're changing
3. Verify after upgrade — Confirm success before deleting backups
4. Keep backups until satisfied — .github-backup-* is your rollback path
5. Curate custom CI — Don't lose project-specific identity
6. Commit after curation — Track the upgrade in git history

Common Issues