Fleet Management

---
name: fleet-management
description: "Keep heir projects synchronized with Master Alex brain updates — audit drift, upgrade brains, verify deployments"
lastReviewed: 2026-01-01
---

# 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

| Script | Purpose | Location |
|--------|---------|----------|
| `upgrade-brain.cjs` | Fleet-wide brain upgrade | `scripts/` |
| `sync-to-heir.cjs` | Master → Heir template sync | `scripts/` |
| `brain-upgrade.cjs` | Per-project upgrade + post-upgrade curation (trifecta muscle) | `.github/muscles/` |

## Workflow

### Phase 1: Prepare Master

Before fleet upgrade, ensure Master Alex is healthy:

```powershell
# 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:

```bash
# 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:

```bash
# 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:

```bash
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:

```powershell
# 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:

| Project | Reason |
|---------|--------|
| `AlexMaster` | Source of truth — never overwrite |
| `AlexMaster_Legacy` | Archive |
| `GCX_*` | Custom CI, manual sync |

Override with `-Include` or modify `-Exclude` parameter.

## Rollback

If something goes wrong:

```bash
# 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:

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

## Version Stamps

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

```
8.0.1
```

Check fleet versions:

```powershell
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:

```bash
# 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

| Issue | Solution |
|-------|----------|
| "backup already exists" | Delete old backup or use different date |
| "missing brain subdirectory" | Verify extension brain is synced |
| "version mismatch" | Re-run upgrade or check source version |
| CI lost project identity | Restore from `.backup.md` or backup dir |