Layered memory migration should preserve meaningful legacy SOUL/RULES guidance

[chubes4]

Summary

The layered memory migration creates the new structure, but it can still leave sites with generic scaffold files while meaningful legacy instructions remain stranded in the old agent/ directory.

This was observed on Extra Chill multisite after migrating to layered memory.

What happened

events.extrachill.com

Legacy agent/SOUL.md contained critical operational guidance:

• when to use skip_item
• multi-day festival rules
• recurring event handling with occurrenceDates
• taxonomy guidance
• ticket URL preservation and timezone guidance

But the modern layered files ended up as:

• shared/RULES.md = generic scaffold
• agents/chubes/SOUL.md = generic scaffold

So the filesystem migration completed structurally, but meaningful instructions were effectively lost from the active prompt path.

wire.extrachill.com

Wire had similar drift patterns during migration work:

• legacy SOUL.md and USER.md had richer site-specific guidance
• some modern layered files existed, but site/user guidance was inconsistent across layers

Why this is bad

The migration appears successful because the new files exist, but active agent behavior regresses because the useful content never gets promoted into the new layered files.

This is especially dangerous for sites where SOUL.md contains operational policy, not just identity fluff.

Root problem

The migration currently copies files into the new structure, but scaffold creation plus partial migration states can still result in active layered files being generic while richer legacy guidance remains in agent/.

Even worse, the new layered architecture splits concerns across:

• shared/SITE.md
• shared/RULES.md
• agents/{slug}/SOUL.md
• agents/{slug}/MEMORY.md
• users/{id}/USER.md

A rich legacy SOUL.md may need to be split across RULES.md and SOUL.md, not just copied blindly.

Proposed fix

Add a migration and/or repair step that:

• detects when layered SOUL.md or RULES.md are still generic scaffolds
• compares them against richer legacy agent/SOUL.md
• promotes meaningful operational guidance into the active layered files
• avoids overwriting richer existing layered files
• provides a CLI repair command for already-migrated installs

Suggested heuristics

• if layered file only contains scaffold placeholders/comments, treat it as replaceable
• if legacy SOUL.md contains headings like When to use skip_item, taxonomy rules, quality standards, or workflow instructions, treat it as meaningful content
• optionally split clearly operational sections into RULES.md and keep identity/voice in SOUL.md

Reproduction

Observed on:

• events.extrachill.com
• wire.extrachill.com

The migration created the layered directories, but active prompts were missing important legacy instructions until manually restored.