markitect-main/examples/design-patterns/CopyFirstMigration.md

# Design Principle: Copy First Migration

## Meta
- **Name:** Copy First Migration
- **ShortName:** CopyFirst
- **Version:** 0.1
- **Status:** Draft
- **Tags:** refactoring, migration, safety, testing, legacy
- **RelatedPrinciples:** Don’t Repeat Yourself, Safe Refactoring, Test Pyramid, Capability-Based Testing

---

## Intent
Enable safe refactoring and structural migration of codebases by preserving
existing, working functionality until the new implementation is fully verified.

This principle prioritizes **reversibility, confidence, and continuity** over
speed or elegance.

---

## CoreStatement
Never move code directly; always copy first and delete only after verified
behavioral equivalence is established.

---

## Scope

### InScope
- Large-scale refactors or directory restructurings
- Technology or language migrations (e.g. JS → new JS layout, JS → Python integration)
- Legacy code stabilization
- Safety-critical or business-critical systems
- Situations with incomplete test coverage

### OutOfScope
- Greenfield development
- Trivial refactors with full and trusted test coverage
- One-off throwaway scripts
- Performance-driven rewrites where duplication is unacceptable

---

## InterpretationGuidelines

### What “Copy First” Means
- The original code remains untouched and functional
- The new version is treated as **experimental until proven**
- Deletion is a **final, explicit act**, not an implicit side effect

### Common Misinterpretations
- “This is inefficient because it duplicates code”  
  → Duplication is intentional and temporary
- “Moving files is faster”  
  → Speed is not the optimization target here
- “Tests alone are enough”  
  → Tests are necessary but not sufficient without behavioral comparison

---

## DetectionHeuristics

### Structural Signals
- Files or modules being relocated across directories or packages
- Parallel implementations during migration
- Introduction of a new architectural boundary

### Semantic Signals
- Code paths that must remain behaviorally identical
- Business rules with high regression risk
- Legacy logic that is poorly documented but relied upon

### Change-Cost Signals
- Rollbacks are expensive or disruptive
- Failures would impact production or customers
- Migration spans multiple commits or teams

---

## DiagnosticQuestions
1. What breaks if this migration is wrong?
2. Do we have a known-good reference implementation?
3. Can both old and new code paths run in parallel?
4. How quickly can we revert if a defect is found?
5. What is the minimal proof of behavioral equivalence?

---

## RecommendedActions

### Low-Risk Actions
- Copy files to the new location instead of moving
- Preserve original imports and entry points
- Add logging or tracing for comparison

### Medium-Risk Actions
- Introduce dual-track execution (old + new)
- Add integration tests targeting both implementations
- Compare outputs, side effects, and error behavior

### High-Risk Actions
- Switch production usage to the new implementation
- Remove old code only after full verification
- Collapse duplicated paths once confidence is established

---

## AcceptanceCriteria
- Original code remains functional until final removal
- New code passes all existing tests
- New integration tests validate identical behavior
- Dual-track comparisons show no regressions
- Deletion of old code is deliberate and reversible up to the final step

---

## AntiPatterns
- Moving files directly without a fallback
- Refactoring and migration in a single irreversible step
- Deleting “unused” code before equivalence is proven
- Assuming test parity guarantees behavioral parity
- Big-bang migrations without rollback paths

---

## Tradeoffs
Applying Copy First Migration intentionally:
- Introduces temporary duplication
- Increases short-term codebase size
- Slows perceived progress

These costs are justified by dramatically reduced risk and higher confidence
during complex migrations.

---

## AgentUsage

### When to Apply This Lens
- During directory, module, or architecture migrations
- When refactoring legacy or poorly understood code
- When safety and uptime matter more than speed
- When rollback must remain possible at all times

### When to Suspend This Lens
- In greenfield projects
- When full test coverage and confidence already exist
- For trivial mechanical refactors

### Expected Agent Output
- Identification of migration boundaries
- Copy-first migration plan with explicit stages
- Test strategy (unit, integration, dual-track)
- Rollback points and deletion criteria
- Clear signal for when old code may be removed

xxx