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

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/:

What Must NEVER Sync

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:

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:

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:

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:

Heir Configuration Drift Signals

Heir → Master Promotion

6-Step Promotion Workflow

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:

Skill Inheritance Classification

Curation Rule

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

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

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:

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.