Investigate promoting migrated legacy instructions from fenced blocks to active policy sections

[ssheld]

Problem

When scripts/new-project.sh runs with --migrate-existing-root-md, legacy root policy content is appended under ## Migrated Legacy ... as a fenced ```md block in agent-vault/AGENTS.md, agent-vault/CLAUDE.md, and agent-vault/GEMINI.md.

Root wrappers now include the agent-specific files, so migrated content is visible. However, because the migrated instructions are embedded as quoted/fenced legacy text, models may treat them as reference material rather than active operating rules.

This creates a reliability gap: important migrated commands/constraints/architecture guidance can be present but not consistently followed.

Proposed Solution

Investigate and likely patch migration behavior so critical legacy instructions are promoted into active markdown sections (outside code fences), while preserving raw provenance.

Candidate approach

1. Keep current raw backup behavior under agent-vault/context/updates/<timestamp>/.
2. Preserve original legacy text for auditability (optional appendix section).
3. During migration, copy key sections from legacy root files into normal markdown in agent-vault/<policy>.md (not fenced), for example:
   • Project
   • Commands
   • Architecture
   • Constraints / Gotchas
4. Add clear migration markers so users can manually review/edit promoted sections.
5. Update README docs for the new migration semantics.
6. Add smoke tests (or script-level verification) showing promoted instructions appear in active policy context.

Investigation Questions

• Should promotion be default for --migrate-existing-root-md, or behind an additional flag?
• Should we keep both promoted and raw sections, or only promoted + backup files?
• Are there parser/client edge cases (Claude/Gemini/Codex) that should influence section format?

Success Criteria

• Migrated critical guidance is represented in active instruction sections (not only fenced blocks).
• Generated root wrappers + policy files provide predictable instruction visibility and adherence.
• Behavior is documented and covered by reproducible migration verification.