heir-sync-management

# Heir Sync Management

> Safely synchronize cognitive architecture from Master to Heirs without contamination.

**Scope**: Master-only skill. Covers sync pipelines, PII protection, drift detection, skill promotion, and clean-slate distribution.

## Core Concepts

| Concept | Definition |
|---------|-----------|
| **Heir** | Platform-specific deployment inheriting Master's DNA (VS Code, M365, Codespaces) |
| **Deployment Channel** | Delivery mechanism for an heir (Marketplace, Teams Package, devcontainer push) |
| **Integration** | Cross-heir communication (OneDrive Sync, GitHub Cloud) |
| **Translation Heir** | Heir requiring format/schema conversion (e.g., M365 — export pipeline) |
| **Deployment Heir** | Heir needing only configuration, no code translation (e.g., Codespaces — devcontainer.json) |
| **Contamination** | Master-specific data leaking into heir packages |
| **Drift** | Heir diverging from Master's architecture over time |
| **Promotion** | Elevating heir-developed capabilities back to Master |

**Rule**: Never confuse delivery mechanism with inheritance relationship — the "what" (identity/DNA) stays constant, only the "how" (delivery) varies.

## Sync Architecture

### What Gets Synced

The sync script (`sync-architecture.js`) copies these folders from Master `.github/` to Heir `.github/`:

| Folder | Content |
|--------|---------|
| `instructions/` | Procedural memory |
| `prompts/` | Episodic memory |
| `config/` | Configuration (with exclusions) |
| `agents/` | Agent definitions |
| `muscles/` | Execution scripts |
| `skills/` | Skills (filtered by inheritance) |

### What Must NEVER Sync

| Item | Why |
|------|-----|
| `user-profile.json` (real) | Contains personal name, email, preferences |
| `episodic/` memories | Session-specific to Master |
| Master-only skills | Only useful for managing the Master repo |
| API keys, PATs, secrets | Environment-specific credentials |
| Working memory with populated P5-P7 | Gives new users pre-filled slots instead of clean defaults |

## 3-Layer PII Protection

Every sync pipeline must implement three independent defense layers:

### Layer 1: Exclusion List

Files that are never copied, period:

```javascript
const EXCLUDED_CONFIG_FILES = [
  'user-profile.json',      // Personal data
  'MASTER-ALEX-PROTECTED.json', // Kill switch marker
  'goals.json',             // Session-specific
];
```

### Layer 2: Source File Sanitization

Scan all files being copied for hardcoded personal data:

| Pattern | Action |
|---------|--------|
| Real names in source headers | Replace with team/org name |
| Email addresses in code | Replace with placeholder |
| Personal names in `package.json` | Use organization name |
| Populated P5-P7 working memory slots | Reset to `*(available)*` |

**Rule**: Personal identity belongs ONLY in `user-profile.json`. All other files use team/org names.

### Layer 3: Pipeline Validation Gate

Post-copy regex scan that blocks packaging on violations:

| Check | Regex Example | On Match |
|-------|--------------|----------|
| Real name in files | `/\bFirstName\s+LastName\b/g` | EXIT 1 |
| Email addresses | `/[\w.-]+@[\w.-]+\.\w+/g` | EXIT 1 (except templates) |
| API keys | `/[A-Za-z0-9]{32,}/` in non-code files | WARNING |
| Populated P5-P7 | Check copilot-instructions Memory Stores | EXIT 1 |

**Anti-pattern**: Manual checklists. The copy function itself must be architecturally incapable of leaking.

## Clean Slate Distribution

### Template Generation

Simply excluding personal files leaves heirs without expected file structure. Generate fresh templates:

| File | Master Version | Heir Template |
|------|---------------|--------------|
| `user-profile.json` | Real user data | Empty with defaults + setup instructions |
| `copilot-instructions.md` | Populated P5-P7 | P5-P7 set to `*(available)*` |
| `goals.json` | Active session goals | Empty goals array |

### Post-Sync Reset Sequence

After copying files, apply these transformations:

1. **Reset environment-specific values** — P5-P7 slots, session state
2. **Generate template files** — Fresh starters with clear defaults
3. **Remove broken synapse references** — Master synapse IDs that don't exist in heir
4. **Validate file structure** — Ensure all expected files exist (even if empty templates)

## Drift Detection

### Pre-Release Checklist

Run these validations before every release:

| Check | Method | Fail Condition |
|-------|--------|---------------|
| Skill count match | Count Master inheritable vs Heir skills | Mismatch |
| File hash comparison | SHA256 of synced files | Divergence without override |
| Inheritance field validation | All skills have `inheritance` in synapses | Missing field |
| Orphan reference detection | Grep for files referenced but not present | Broken references |
| Config drift | Compare heir config against Master template | Unexpected values |

### Heir Configuration Drift Signals

| Signal | Indicates |
|--------|----------|
| Heir P5-P7 slots populated | Sync overwrote clean defaults |
| Heir has master-only skills | Exclusion filter not working |
| Heir synapse IDs don't resolve | Broken references from Master copy |
| Heir `package.json` has personal name | Sanitization missed |

## Heir → Master Promotion

### 6-Step Promotion Workflow

| Step | Action | Output |
|------|--------|--------|
| 1. **Discover** | Review heir DK/skill files for portable knowledge | Candidate list |
| 2. **Create Skill** | Write SKILL.md in Master's `.github/skills/` | New skill file |
| 3. **Compare Gaps** | Diff heir knowledge against Master's existing coverage | Gap analysis |
| 4. **Implement** | Port patterns, translate code (Python→TS if needed) | Working code |
| 5. **Test** | Validate in Master context | Passing tests |
| 6. **Document** | CHANGELOG entry, ROADMAP update | Release-ready |

### Consolidation During Promotion

Heirs naturally create granular one-capability-per-skill files during experimentation. During promotion:

1. **Identify clusters** — Group related heir skills by domain
2. **Choose anchor skill** — Pick the broadest skill in the cluster
3. **Merge content** — Absorb related skills into the anchor
4. **Deduplicate** — Remove redundancy from the merge
5. **Mark inheritance** — Set the promoted skill as inheritable

**Anti-pattern**: Promoting every heir skill as-is without consolidation review causes skill sprawl.

### Code Translation Patterns (Heir → Master)

When porting from Python heirs to TypeScript Master:

| Python | TypeScript |
|--------|-----------|
| `dataclass` | `interface` |
| `raise Exception` | `throw new Error` |
| `**kwargs` | Optional config object |
| `async def` | `async function` |
| `try/except` | `try/catch` |

## Skill Inheritance Classification

### Curation Rule

Ask: "Is this skill ONLY useful for managing the Alex repo itself?"

| Answer | Classification | Example |
|--------|---------------|---------|
| Yes, master-repo only | `master-only` | release-preflight, heir-curation |
| No, any developer benefits | `inheritable` | deep-thinking, meditation, security-review |

### Truly Master-Only Skills (small list)

Only a few skills are genuinely master-only:

- `heir-curation` — Managing what heirs receive
- `heir-sync-management` — This skill
- `master-alex-audit` — Master workspace auditing
- `release-preflight` — Marketplace publishing
- `release-process` — Release pipeline

## Heir Type Comparison

| Heir | Type | Translation | Deploy Mechanism | Maintenance Cost |
|------|------|-------------|-----------------|------------------|
| **VS Code Extension** | Source | Compile only | `npx vsce publish` | Low |
| **M365 Copilot Agent** | Translation | Full export/schema mapping | Teams Developer Portal | High |
| **GitHub Codespaces** | Deployment | None (same extension) | `git push` devcontainer.json | Very Low |

Everything else should be inheritable unless it references Master-specific file paths or workflows.

## Heir-Specific Positioning

Each platform heir must position against its **native competitor**, not a generic category:

| Heir | Compares Against | Not Against |
|------|-----------------|-------------|
| VS Code Extension | GitHub Copilot (native) | "AI assistants" generically |
| M365 Agent | Microsoft 365 Copilot | "AI assistants" generically |

Store descriptions, README headers, and comparison tables must use platform-specific language and keywords.

## Release Pipeline Integration

The release script must enforce sync before packaging:

1. Run `sync-architecture.js` (copies Master → Heir)
2. Apply post-sync transformations (clean slate)
3. Run PII validation gate (blocks on contamination)
4. Check `BUILD-MANIFEST.json` timestamp (prevents stale packaging)
5. Package and publish

**Rule**: It must be impossible to publish stale content through the official release process.