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

Leakage Prevention Patterns

Master-Only Content Categories

Content that must NEVER sync to heirs falls into three categories:

Dual Filtering Strategy (2026-02-14 Fix)

Problem: cleanBrokenSynapseReferences() only filtered master-only skills, not master-only files.

Solution: Enhanced function with dual target detection:

// Master-only skills (from inheritance metadata)
skippedMasterOnly.some(removed => target.includes(removed))

// Master-only files (hardcoded registry)
masterOnlyFiles.some(file => target.includes(file))

Master-Only Files Registry:

• ROADMAP-UNIFIED.md — Master development roadmap
• alex_docs/architecture/ — Architecture documentation not deployed to heirs
• MASTER-ALEX-PROTECTED.json — Kill-switch marker

Content Transformation Rules

Some content needs adjustment not removal:

Implementation: applyHeirTransformations() in sync-architecture.js

Validation Cascade (4-Stage Quality Gate)

1. Sync: Copy files with skill/config exclusions
2. Transform: Apply heir-specific content adjustments
3. Validate: PII scan, master-only file detection
4. Audit: Count verification, synapse connection integrity

Fail-Fast: Any contamination detection halts the build (exit 1).

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.