Copilot instructions

1---
2applyTo: "**/legacy/**/*.java, **/migration/**/*.java, **/*.cbl, **/*.cob, **/*.rpgle, **/cobol/**/*.java, **/modernization/**/*.java"
3---
4 
5## Context
6 
7This instruction file applies to legacy system modernisation work: COBOL-to-Java migration, RPG IV / RPGLE to Java conversion, Spring Framework 4/5 to Spring Boot 3.x upgrades, and `javax.*` to `jakarta.*` namespace migrations. The guiding principle is **controlled, incremental migration** using the Strangler Fig pattern — never a big-bang rewrite. All legacy behaviour must be preserved exactly; the Anti-Corruption Layer (ACL) isolates modern code from legacy data models.
8 
9---
10 
11## Coding Standards
12 
13- **Strangler Fig only:** Migrate by route/feature, running old and new code simultaneously; switch traffic via feature flag
14- **Anti-Corruption Layer (ACL):** Always introduce an ACL adapter when modern code calls legacy systems; never expose legacy data models to the domain layer
15- **Parallel run first:** Run new implementation in shadow mode (write-only, no traffic served) before switching; compare outputs
16- **javax → jakarta:** In Spring Boot 3.x, every `javax.*` import must be `jakarta.*`; use `spring-boot-migration` or IDE migration tool
17- **No big-bang rewrites:** Never attempt to migrate an entire COBOL program in a single step; decompose into functions
18- **Preserve business rules exactly:** Copy business logic verbatim before optimising; document every deliberate deviation
19- **Feature flags for cutover:** Use LaunchDarkly or Spring `@ConditionalOnProperty` to control legacy/modern routing
20- **Data migration is separate:** Schema migrations run independently of code changes; use Flyway with phased scripts
21 
22---
23 
24## Preferred Patterns
25 
26### Strangler Fig Router
27 
28```java
29// ✅ CORRECT — feature-flagged routing to legacy or modern implementation
30@Service
31@RequiredArgsConstructor
32public class OrderServiceRouter {
33 
34    private final LegacyOrderService legacyOrderService;
35    private final ModernOrderService modernOrderService;
36    private final FeatureFlags flags;
37 
38    public Order placeOrder(PlaceOrderCommand cmd) {
39        if (flags.isEnabled("modern-order-service", cmd.customerId())) {
40            return modernOrderService.placeOrder(cmd);
41        }
42        return legacyOrderService.placeOrder(cmd);
43    }
44}
45```
46 
47### Anti-Corruption Layer
48 
49```java
50// ✅ CORRECT — ACL translates legacy COBOL copybook structure to domain model
51@Component
52public class LegacyOrderAdapter implements OrderPort {
53 
54    private final LegacyOrderServiceClient legacyClient;
55 
56    @Override
57    public Order findById(OrderId orderId) {
58        LegacyCustRec legacyRecord = legacyClient.fetchOrder(orderId.value());
59        return Order.builder()
60            .id(OrderId.of(legacyRecord.getOrdId().trim()))
61            .customerId(legacyRecord.getCustId().trim())
62            .totalAmount(new BigDecimal(legacyRecord.getTotalAmt()).movePointLeft(2))
63            .status(mapLegacyStatus(legacyRecord.getOrdSts()))
64            .build();
65    }
66 
67    private OrderStatus mapLegacyStatus(String legacyCode) {
68        return switch (legacyCode.trim()) {
69            case "OP" -> OrderStatus.OPEN;
70            case "CL" -> OrderStatus.CLOSED;
71            case "CA" -> OrderStatus.CANCELLED;
72            default -> throw new UnknownLegacyStatusException(legacyCode);
73        };
74    }
75}
76 
77// ❌ WRONG — leaking legacy model into the domain layer
78public Order findById(String id) {
79    LegacyCustRec rec = legacyClient.fetchOrder(id);
80    return rec;  // LegacyCustRec used as domain object — coupling
81}
82```
83 
84### javax → jakarta Migration
85 
86```java
87// ✅ CORRECT — Spring Boot 3.x uses jakarta.*
88import jakarta.persistence.Entity;
89import jakarta.persistence.Id;
90import jakarta.validation.constraints.NotNull;
91import jakarta.servlet.http.HttpServletRequest;
92import jakarta.transaction.Transactional;
93 
94// ❌ WRONG — javax.* in Spring Boot 3.x [BLOCKER]
95import javax.persistence.Entity;
96import javax.persistence.Id;
97import javax.validation.constraints.NotNull;
98import javax.servlet.http.HttpServletRequest;
99import javax.transaction.Transactional;
100```
101 
102### COBOL Field Mapping (PIC clause → Java type)
103 
104```java
105// COBOL:   05 CUST-ID         PIC X(10).
106// Java:    String customerId;  // trim() required — fixed-width padded with spaces
107 
108// COBOL:   05 ORDER-AMT       PIC 9(7)V99.
109// Java:    BigDecimal amount = new BigDecimal(raw).movePointLeft(2);
110 
111// COBOL:   05 ORDER-DATE      PIC 9(8).  (YYYYMMDD)
112// Java:    LocalDate date = LocalDate.parse(raw, DateTimeFormatter.BASIC_ISO_DATE);
113 
114// COBOL:   05 STATUS-FLAG     PIC X(1).  ('Y'/'N')
115// Java:    boolean active = "Y".equals(raw.trim());
116```
117 
118---
119 
120## Anti-Patterns — Do NOT Generate
121 
122```java
123// WRONG: big-bang rewrite — replace all legacy code at once [BLOCKER]
124// Never migrate 50,000 lines of COBOL in a single sprint
125 
126// WRONG: javax.* in Spring Boot 3.x [BLOCKER]
127import javax.persistence.Entity;
128 
129// WRONG: legacy model leaking into domain [MAJOR]
130public LegacyCustRec getOrder(String id) {
131    return legacyClient.fetchOrder(id);  // legacy type in public API
132}
133 
134// WRONG: silent field truncation [MAJOR]
135String customerId = legacyRecord.getOrdId();  // missing .trim() — trailing spaces cause lookup failures
136 
137// WRONG: direct DB join across legacy and modern schemas [MAJOR]
138// SELECT o.order_id, c.email FROM legacy_orders o JOIN modern_customers c ON o.cust_id = c.id
139// Cross-schema joins tightly couple two bounded contexts
140 
141// WRONG: hardcoded feature flag value [MINOR]
142if (true) {  // should be flags.isEnabled("feature-name")
143    return modernService.process(cmd);
144}
145```
146 
147---
148 
149## Dependencies & Versions
150 
151| Technology | Version | Notes |
152|-----------|---------|-------|
153| Spring Boot | 3.x | Requires Java 17+; `jakarta.*` namespace exclusively |
154| spring-boot-properties-migrator | 3.x | Auto-migrates deprecated property names on startup |
155| openrewrite | 8.x | Automated refactoring; `UpgradeSpringBoot_3_2` recipe |
156| LaunchDarkly Java SDK | 7.x | Feature flags for Strangler Fig routing |
157| spring-cloud-config | 4.x | Externalise feature flag config for phased rollout |
158 
159---
160 
161## Migration Verification
162 
163After each migration phase:
164 
1651. **Functional equivalence:** Run the legacy and modern implementations in parallel with identical inputs; assert output equality
1662. **Data mapping:** Verify every COBOL PIC clause maps to the correct Java type (trim strings, scale decimals, parse dates)
1673. **javax → jakarta:** Run `grep -r "import javax\." src/main/java/` — must return zero results in Spring Boot 3.x modules
1684. **No cross-context joins:** Run `grep -r "legacy_\|LEGACY_" src/main/java/` in modern service modules — must return zero results
1695. **Feature flag coverage:** Every cutover point has a named feature flag; no hardcoded `if (true)` routing
170