Legacy System Healing ## Research Foundation This module synthesizes ideas from multiple validated sources. Each technique is cited. | Source | Key Contribution | Citation | |--------|-----------------|----------| | Amazon AGI Lab (2026) | Friction-as-semantics, agents as universal API over legacy UIs | [amazon.science blog](https://www.amazon.science/blog/how-agentic-ai-helps-heal-the-systems-we-cant-replace) | | Michael Feathers (2004) | Characterization testing, dependency-breaking techniques, seams | Working Effectively with Legacy Code, Prentice Hall | | Martin Fowler (2004) | Strangler Fig pattern for incremental replacement | [martinfowler.com/bliki/StranglerFigApplication](https://martinfowler.com/bliki/StranglerFigApplication.html) | | Eric Evans (2003) | Anti-Corruption Layer to isolate legacy from modern code | Domain-Driven Design, Addison-Wesley | | RepoMod-Bench (2026) | System-boundary testing for behavioral equivalence | arXiv:2602.22518 | | Model-Driven Modernization (2026) | Observability + contract tests for conformance | arXiv:2602.04341 | | HEC (2025) | Equivalence verification via equality saturation | arXiv:2506.02290 | | VAPU (2025) | Multi-agent pipeline for autonomous legacy updates | arXiv:2510.18509 | | Code Reborn (2025) | AI-driven COBOL-to-Java, 93% accuracy | arXiv:2504.11335 | | AWS Transform (2025-2026) | Decomposition agents, semantic seeding, domain grouping | [AWS blog](https://aws.amazon.com/blogs/migration-and-modernization/accelerate-your-mainframe-modernization-journey-using-ai-agents-with-aws-transform/) | | GitHub Copilot (2025) | 3-agent pattern: extract logic, generate tests, generate modern code | [github.blog](https://github.blog/ai-and-ml/github-copilot/how-github-copilot-and-ai-agents-are-saving-legacy-systems/) | --- ## When to Load This Module - loki heal command invoked - Working with legacy codebases (COBOL, FORTRAN, old Java, PHP 5, Python 2, jQuery-era JS) - Brownfield modernization projects - --target flag used with loki migrate - Codebase archaeology / knowledge extraction tasks --- ## Core Principles ### 1. Friction is Semantics (Amazon AGI Lab) Source: Amazon AGI Lab -- "The logic behind legacy systems reveals itself most clearly through friction." System quirks are not bugs. They are the real behavior. The modal that appears late encodes a sequencing rule. The field that refuses input until another value is saved. The form that resets because a backend job restarted midflow. These behaviors ARE the semantics. ``yaml friction_detection: rule: "Before 'fixing' any quirk, verify it is not an undocumented business rule" action: "Document in .loki/healing/friction-map.json" classification: business_rule: "Keep and document. Gate 10 blocks removal." true_bug: "Fix with characterization test proving the fix." unknown: "Keep until classified. NEVER remove unknown friction." ` **Friction Map Schema:** `json { "frictions": [ { "id": "friction-001", "location": "src/billing/invoice.py:234", "behavior": "Sleep 2s before committing transaction", "classification": "business_rule|true_bug|unknown", "evidence": "Prevents race condition with external payment gateway callback", "discovered_by": "archaeology_scan", "timestamp": "2026-01-25T10:00:00Z", "safe_to_remove": false } ] } ` ### 2. Characterize Before Modifying (Feathers) **Source:** Michael Feathers, *Working Effectively with Legacy Code* (2004) A characterization test describes the ACTUAL behavior of existing code, not the INTENDED behavior. It is a change detector, not a correctness proof. Mark Seemann (2025) emphasizes: "Write an assertion that you know will fail" -- this prevents tautological tests. `yaml characterization_testing: feathers_recipe: 1: "Use a piece of code in a test harness" 2: "Write an assertion that you KNOW will fail" 3: "Let the failure tell you what the actual behavior is" 4: "Change the test so that it expects the behavior the code produces" 5: "Repeat -- the test now documents the actual behavior" key_distinction: | Characterization tests capture WHAT THE CODE DOES. Unit tests verify WHAT THE CODE SHOULD DO. When these differ, the characterization test wins during healing -- because users depend on actual behavior, not intended behavior. seemann_2025: | "A characterization test is a falsifiable experiment. The implied hypothesis is that the test will fail. If it does not fail, you've falsified the prediction." (Mark Seemann, Nov 2025) ` ### 3. Strangler Fig Pattern (Fowler) **Source:** Martin Fowler, 2004. Named after strangler figs that gradually grow around a host tree. Do NOT rewrite. Gradually replace components while both old and new run simultaneously. A facade/proxy routes traffic to old or new based on readiness. ``yaml strangler_fig: steps: 1: "Identify system boundaries (not arbitrary c