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:

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.