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

.github/

.github/

instructions/

prompts/

config/

agents/

muscles/

skills/

What Must NEVER Sync

user-profile.json

episodic/

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:

package.json

*(available)*

Rule: Personal identity belongs ONLY in

user-profile.json

Layer 3: Pipeline Validation Gate

Post-copy regex scan that blocks packaging on violations:

/\bFirstName\s+LastName\b/g

/[\w.-]+@[\w.-]+\.\w+/g

/[A-Za-z0-9]{32,}/

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:

user-profile.json

copilot-instructions.md

*(available)*

goals.json

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:

inheritance

Heir Configuration Drift Signals

package.json

Leakage Prevention Patterns

Master-Only Content Categories

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

inheritance: "master-only"

Dual Filtering Strategy (2026-02-14 Fix)

Problem:

cleanBrokenSynapseReferences()

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()

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

.github/skills/

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:

dataclass

interface

raise Exception

throw new Error

**kwargs

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?"

master-only

inheritable

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

npx vsce publish

git push

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.