Windsurf rules

1<!-- Generated by EEIK generate_adapters.py on 2026-08-10 — do not edit by hand -->
2---
3trigger: always_on
4---
5 
6# Golden Rules — this project
7 
8Non-negotiable engineering standards. Apply to all generated and edited code.
9 
10# Golden Rules Standard
11 
12**Applies To:** All projects, all languages, all domains  
13**Enforced By:** `code-reviewer` agent, CI/CD hooks, `security-auditor` agent  
14**Status:** Non-negotiable
15 
16---
17 
18## The 12 Golden Rules
19 
20These rules apply to every line of code committed to any EEIK-managed project. They are not preferences — violation of a BLOCKER rule prevents merge.
21 
22---
23 
24### Rule 1 — Constructor Injection Only
25 
26**No `@Autowired` on fields. All injected fields are `final`.**
27 
28```java
29// ❌ VIOLATION — field injection
30@Service
31public class OrderService {
32    @Autowired
33    private OrderRepository orderRepository;
34}
35 
36// ✅ CORRECT — constructor injection
37@Service
38public class OrderService {
39    private final OrderRepository orderRepository;
40 
41    public OrderService(OrderRepository orderRepository) {
42        this.orderRepository = orderRepository;
43    }
44}
45```
46 
47**Why:** Fields cannot be `final`. Cannot test without Spring context. Dependencies are invisible.
48 
49---
50 
51### Rule 2 — No Hardcoded Secrets
52 
53**No credentials, API keys, passwords, or AWS account IDs in source code.**
54 
55```java
56// ❌ VIOLATION
57String apiKey = "sk-live-abc123...";
58String dbPassword = "SuperSecret123";
59 
60// ✅ CORRECT — environment variable or Secrets Manager
61String apiKey = System.getenv("API_KEY");
62// or via @Value, or SecretsManagerClient
63```
64 
65**Why:** Source code is version-controlled and shared. Secrets in code become public.
66 
67---
68 
69### Rule 3 — SLF4J, Not System.out
70 
71**Use `log.info(...)` with parameterised messages. Never `System.out.println()`.**
72 
73```java
74// ❌ VIOLATION
75System.out.println("Processing order: " + orderId);
76 
77// ✅ CORRECT
78log.info("Processing order id={}", orderId);
79```
80 
81**Why:** `System.out` bypasses the logging framework — no level control, no structured output, no MDC context.
82 
83---
84 
85### Rule 4 — No SELECT *
86 
87**Always specify explicit column lists in SQL.**
88 
89```sql
90-- ❌ VIOLATION
91SELECT * FROM orders WHERE customer_id = :customerId;
92 
93-- ✅ CORRECT
94SELECT id, customer_id, status, total_amount, created_at
95FROM orders
96WHERE customer_id = :customerId;
97```
98 
99**Why:** Schema additions silently increase payload size and break mapping. Query plans are harder to optimise.
100 
101---
102 
103### Rule 5 — Parameterised Queries Only
104 
105**No SQL string concatenation. Use named parameters.**
106 
107```java
108// ❌ VIOLATION — SQL injection risk
109String sql = "SELECT * FROM orders WHERE id = '" + orderId + "'";
110 
111// ✅ CORRECT
112String sql = "SELECT id, status FROM orders WHERE id = :orderId";
113namedJdbcTemplate.queryForObject(sql, Map.of("orderId", orderId), rowMapper);
114```
115 
116**Why:** String concatenation enables SQL injection. Non-negotiable security rule.
117 
118---
119 
120### Rule 6 — java.time Only (Java projects)
121 
122**No `java.util.Date`, `java.util.Calendar`, or `java.sql.Timestamp`.**
123 
124```java
125// ❌ VIOLATION
126Date now = new Date();
127Calendar cal = Calendar.getInstance();
128 
129// ✅ CORRECT
130Instant now = Instant.now();
131LocalDate today = LocalDate.now();
132ZonedDateTime zonedNow = ZonedDateTime.now(ZoneId.of("Europe/London"));
133```
134 
135**Why:** `Date` and `Calendar` are mutable, non-thread-safe, and poorly designed. `java.time` is ISO 8601-correct.
136 
137---
138 
139### Rule 7 — jakarta.* in Spring Boot 3.x (Java projects)
140 
141**No `javax.*` imports in Spring Boot 3.x code.**
142 
143```java
144// ❌ VIOLATION in Spring Boot 3.x
145import javax.persistence.Entity;
146import javax.validation.constraints.NotNull;
147 
148// ✅ CORRECT
149import jakarta.persistence.Entity;
150import jakarta.validation.constraints.NotNull;
151```
152 
153**Why:** Spring Boot 3.x requires Jakarta EE 10. `javax.*` causes `ClassNotFoundException` at runtime.
154 
155---
156 
157### Rule 8 — Conventional Commits
158 
159**All commit messages follow `type(scope): description` format.**
160 
161```
162# ❌ VIOLATION
163"fix stuff"
164"wip"
165"updated OrderService"
166 
167# ✅ CORRECT
168feat(orders): add order cancellation endpoint
169fix(payments): handle null amount in authorisation
170chore(deps): upgrade Spring Boot to 3.3.0
171test(orders): add Testcontainers integration test for cancellation
172```
173 
174**Types:** `feat`, `fix`, `refactor`, `test`, `chore`, `docs`, `perf`, `ci`, `build`, `revert`
175 
176---
177 
178### Rule 9 — No Partial Implementations
179 
180**Every committed method body is complete. No `// TODO implement this` in production code.**
181 
182```java
183// ❌ VIOLATION
184public BigDecimal calculatePremium(Policy policy) {
185    // TODO: implement premium calculation
186    return null;
187}
188 
189// ✅ CORRECT — if not yet implementable, throw explicitly
190public BigDecimal calculatePremium(Policy policy) {
191    throw new UnsupportedOperationException(
192        "Premium calculation not yet implemented — tracked in TD-042"
193    );
194}
195```
196 
197---
198 
199### Rule 10 — No Empty Catch Blocks
200 
201**Every catch block at minimum logs the exception.**
202 
203```java
204// ❌ VIOLATION
205try {
206    publishEvent(event);
207} catch (Exception e) {
208    // swallowed
209}
210 
211// ✅ CORRECT
212try {
213    publishEvent(event);
214} catch (Exception e) {
215    log.error("Failed to publish event type={} id={}: {}", 
216               event.getType(), event.getId(), e.getMessage(), e);
217}
218```
219 
220---
221 
222### Rule 11 — No Thread.sleep() in Tests
223 
224**Use Awaitility for async assertions.**
225 
226```java
227// ❌ VIOLATION
228Thread.sleep(2000);
229assertThat(orderRepository.findById(id)).isPresent();
230 
231// ✅ CORRECT
232await().atMost(5, SECONDS).until(() ->
233    orderRepository.findById(id).isPresent()
234);
235```
236 
237---
238 
239### Rule 12 — Optional.get() Only with Guard
240 
241**Never call `Optional.get()` without a preceding `isPresent()` or use `orElseThrow()`.**
242 
243```java
244// ❌ VIOLATION
245Order order = orderRepository.findById(id).get(); // NoSuchElementException risk
246 
247// ✅ CORRECT
248Order order = orderRepository.findById(id)
249    .orElseThrow(() -> new OrderNotFoundException(id));
250```
251 
252---
253 
254## Enforcement
255 
256| Severity | Rules | Gate |
257|----------|-------|------|
258| BLOCKER (pre-merge) | 2 (no secrets), 5 (SQL injection) | CI security scan |
259| BLOCKER (code review) | 1, 3, 4, 6, 7, 9, 10, 12 | `code-reviewer` agent |
260| MAJOR (code review) | 8, 11 | `code-reviewer` agent |
261 
262Rules 1–12 are checked by the `code-reviewer` agent on every PR review.
263 
264