geneseed 4.9.4 → 4.14.0

package/src/skills/spring-boot/logging.md

@@ -0,0 +1,89 @@
+# {{SKILL}}: spring-boot — logging
+
+{{CREDIT:piomin-spring-boot:skills/logging-patterns/SKILL.md}}
+
+SLF4J through Spring Boot's logging, with structured (JSON) output where logs are machine-read. Structured output is a good default for deployed environments and CI because fields parse directly (`jq`, log platforms, an AI assistant reading logs); keep readable text for local development.
+
+## Structured logging (built in)
+No extra dependency. Pick a format per target:
+
+```yaml
+logging:
+  structured:
+    format:
+      console: logstash   # also: ecs, gelf
+```
+
+`logging.structured.format.file` does the same for file output. A custom Logback or Log4j2 config must use Boot's structured encoder or layout (`StructuredLogEncoder` / `StructuredLogLayout` fed by `CONSOLE_LOG_STRUCTURED_FORMAT`), or the property has no effect.
+
+Profile split so developers keep readable logs:
+
+```yaml
+---
+spring:
+  config:
+    activate:
+      on-profile: "!local"
+logging:
+  structured:
+    format:
+      console: logstash
+```
+
+Run locally with the `local` profile for plain text. With Micrometer Tracing present, Boot adds `[traceId-spanId]` to every log line by default; change the format with `logging.pattern.correlation`. Whether they appear as JSON fields depends on the format; confirm in a real log line.
+
+## Writing log statements
+```java
+private static final Logger log = LoggerFactory.getLogger(OrderService.class);
+
+log.info("Order created id={} customer={}", order.id(), order.customerId()); // parameterized
+log.error("Payment failed for order {}", order.id(), e);                      // exception last, stack trace kept
+```
+- Placeholders, never string concatenation. Guard only genuinely expensive arguments with `isDebugEnabled()`.
+- Pass the exception as the final argument; do not log `e.getMessage()` alone.
+- Log an exception once, where it is handled, not at every layer it passes through.
+- Never log secrets, tokens, passwords or personal data; log identifiers.
+- Lombok's `@Slf4j` is fine where the project uses Lombok; otherwise declare the logger as above.
+
+| Level | Meaning |
+|-------|---------|
+| ERROR | Something failed and needs attention |
+| WARN | Unexpected but handled (fallback used, retry succeeded) |
+| INFO | Business events (order created, job finished) |
+| DEBUG | Technical detail (queries, outbound calls) |
+| TRACE | Verbose internals |
+
+## MDC for correlation
+MDC attaches key-value context to every log line written by the current thread. Set it at the edge in a filter and always clear it in `finally`.
+
+```java
+@Component
+@Order(Ordered.HIGHEST_PRECEDENCE)
+class MdcFilter extends OncePerRequestFilter {
+    @Override
+    protected void doFilterInternal(HttpServletRequest req, HttpServletResponse res, FilterChain chain)
+            throws ServletException, IOException {
+        String header = req.getHeader("X-Request-Id");
+        // client-supplied: accept only a short, safe value
+        String id = header != null && header.matches("[A-Za-z0-9-]{1,64}") ? header : UUID.randomUUID().toString();
+        MDC.put("requestId", id);
+        try {
+            chain.doFilter(req, res);
+        } finally {
+            MDC.remove("requestId");
+        }
+    }
+}
+```
+
+MDC is thread-local, so it does not follow work handed to another thread (virtual or platform). For executor tasks, copy the context with a `TaskDecorator` (`MDC.getCopyOfContextMap()` before, `MDC.setContextMap(...)` inside the task, `MDC.clear()` in `finally`) and register it on the executor you use; check that Boot applies it to your executor in the version you run.
+
+Useful fields for incident analysis: `requestId`, user or tenant id, and a duration on slow-path logs. Keep them to identifiers, not payloads.
+
+## Quick reference
+| Need | Use |
+|------|-----|
+| JSON console | `logging.structured.format.console: logstash` |
+| Per-package level | `logging.level.com.example.orders: DEBUG` |
+| Correlate a request | MDC `requestId` set in a filter |
+| Follow one request in JSON logs | `jq 'select(.requestId == "abc")' app.log` (field name depends on MDC key and format) |

package/src/skills/spring-boot/security.md

@@ -0,0 +1,112 @@
+# {{SKILL}}: spring-boot — security
+
+{{CREDIT:piomin-spring-boot:skills/spring-boot/references/security.md}}
+
+Spring Security 7. Default posture for an API: a stateless OAuth2 resource server that validates JWTs issued by an identity provider. Do not write your own token issuer, JWT filter or password store unless the task is explicitly to build an authorization server; that code is where the security bugs live.
+
+## Resource server
+Properties first (Boot builds the decoder from them):
+
+```yaml
+spring:
+  security:
+    oauth2:
+      resourceserver:
+        jwt:
+          issuer-uri: https://auth.example.com
+          audiences:
+            - orders-api
+```
+
+```java
+@Configuration
+@EnableWebSecurity
+@EnableMethodSecurity
+class SecurityConfig {
+
+    @Bean
+    SecurityFilterChain api(HttpSecurity http) throws Exception {
+        http
+            .cors(Customizer.withDefaults())
+            .sessionManagement(s -> s.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
+            .authorizeHttpRequests(auth -> auth
+                .requestMatchers("/actuator/health/**").permitAll()
+                .requestMatchers("/api/admin/**").hasRole("ADMIN")
+                .anyRequest().authenticated())
+            .oauth2ResourceServer(oauth2 -> oauth2.jwt(Customizer.withDefaults()));
+        return http.build();
+    }
+}
+```
+
+- Lambda DSL only; `.and()` chaining and `authorizeRequests` are gone in Security 7.
+- Disabling CSRF is acceptable only for a stateless, bearer-token API with no cookie-based session. If any endpoint authenticates with a cookie, keep CSRF on.
+- `cors(Customizer.withDefaults())` picks up a `CorsConfigurationSource` bean; define that bean with explicit origins.
+- Default JWT algorithm trust is RS256 only; widen it deliberately if the provider signs otherwise.
+
+## Mapping claims to authorities
+The default converter maps the `scope` claim to `SCOPE_` authorities. For roles in another claim:
+
+```java
+@Bean
+JwtAuthenticationConverter jwtAuthenticationConverter() {
+    var authorities = new JwtGrantedAuthoritiesConverter();
+    authorities.setAuthoritiesClaimName("roles");
+    authorities.setAuthorityPrefix("ROLE_");
+    var converter = new JwtAuthenticationConverter();
+    converter.setJwtGrantedAuthoritiesConverter(authorities);
+    return converter;
+}
+```
+
+Wire it with `oauth2.jwt(jwt -> jwt.jwtAuthenticationConverter(jwtAuthenticationConverter()))`.
+
+## Validate audience
+An issuer check alone accepts any token that issuer minted for any API. The `audiences` property in the YAML above makes Boot require the `aud` claim. Define your own `JwtDecoder` bean only when you need custom validators; it replaces the property-driven decoder, audiences included.
+
+## Method security
+`@EnableMethodSecurity` turns on `@PreAuthorize` and `@PostAuthorize`. Authorize in the service layer, next to the data, not only on URL patterns. The legacy Access API (`AccessDecisionManager`, voters) moved to the separate `spring-security-access` module; `@Secured` still works via `@EnableMethodSecurity(securedEnabled = true)`, but prefer `@PreAuthorize`.
+
+```java
+@PreAuthorize("hasRole('ADMIN') or #ownerId == authentication.name")
+public Order find(String ownerId, Long id) { ... }
+```
+
+## Testing
+Use the `jwt()` request post processor with MockMvc (`SecurityMockMvcRequestPostProcessors.jwt()`; default token has `scope=read`), or `@WithMockUser` for method security. Always test the 401 (no token) and 403 (wrong authority) paths, not only success.
+
+## TLS with SSL bundles
+Configure server and client TLS with SSL bundles (named key material). Reloading works only when the consuming component supports it (Tomcat and Netty servers) and only through the file watcher, so the material must be on the file system with a `file:` location; a `classpath:` bundle cannot reload.
+
+```yaml
+spring:
+  ssl:
+    bundle:
+      pem:
+        server:
+          reload-on-update: true
+          keystore:
+            certificate: "file:/etc/ssl/app/tls.crt"
+            private-key: "file:/etc/ssl/app/tls.key"
+server:
+  ssl:
+    bundle: server
+```
+
+Tune detection with `spring.ssl.bundle.watch.file.quiet-period` (default 10s). Apply a bundle to an outbound `RestClient` with the `RestClientSsl` helper (it replaces any request factory you set earlier; use a separate `client` bundle with a `truststore` for the upstream, not the server's keystore bundle), or build a factory when you need more than SSL:
+
+```java
+RestClient client(RestClient.Builder builder, RestClientSsl ssl) {
+    return builder.baseUrl("https://internal-service").apply(ssl.fromBundle("client")).build();
+}
+// more than SSL:
+// var settings = HttpClientSettings.ofSslBundle(bundles.getBundle("client")).withReadTimeout(Duration.ofSeconds(5));
+// builder.requestFactory(ClientHttpRequestFactoryBuilder.detect().build(settings))
+```
+
+## Checklist
+- HTTPS everywhere outside local dev; secrets from env or mounted files ([spring-boot/cloud.md](cloud.md) covers config trees).
+- Validate issuer and audience; keep token lifetimes short; never log tokens.
+- Passwords (if you must store any): `PasswordEncoder` from `PasswordEncoderFactories`/BCrypt, never a plain hash.
+- Rate-limit authentication endpoints at the gateway or proxy.
+- Ask the `spring-security` agent for review (it hands the generic audit to `security`) when the change touches authentication or authorization.

package/src/skills/spring-boot/web.md

@@ -0,0 +1,112 @@
+# {{SKILL}}: spring-boot — web layer
+
+{{CREDIT:piomin-spring-boot:skills/spring-boot/references/web.md}}
+
+Controllers, validation, error handling and outbound HTTP for a Spring MVC service.
+
+## Controller
+Thin: bind, validate, delegate, shape the response. Create returns `201` with a `Location` header; delete returns `204`.
+
+```java
+@RestController
+@RequestMapping("/api/v1/users")
+class UserController {
+    private final UserService service;
+
+    UserController(UserService service) { this.service = service; }
+
+    @GetMapping
+    PagedModel<UserResponse> list(@PageableDefault(size = 20, sort = "createdAt") Pageable pageable) {
+        return new PagedModel<>(service.findAll(pageable));
+    }
+
+    @PostMapping
+    ResponseEntity<UserResponse> create(@Valid @RequestBody UserCreateRequest request) {
+        UserResponse user = service.create(request);
+        URI location = ServletUriComponentsBuilder.fromCurrentRequest()
+                .path("/{id}").buildAndExpand(user.id()).toUri();
+        return ResponseEntity.created(location).body(user);
+    }
+
+    @DeleteMapping("/{id}")
+    @ResponseStatus(HttpStatus.NO_CONTENT)
+    void delete(@PathVariable Long id) { service.delete(id); }
+}
+```
+
+Version the path (`/api/v1`). Use GET for reads, POST/PUT/PATCH/DELETE for state changes; never change state on GET.
+
+## DTOs and validation
+Records for request and response. Constraints sit on the record components (`jakarta.validation.constraints`); `@Valid` on the controller parameter triggers them. Put the entity-to-DTO mapping in a static factory or a mapper, not in the controller.
+
+```java
+public record UserCreateRequest(
+        @NotBlank @Email String email,
+        @NotBlank @Size(min = 8, max = 100) String password,
+        @Min(18) Integer age) {}
+```
+
+A custom constraint is an annotation with `@Constraint(validatedBy = ...)` plus a `ConstraintValidator`; the validator may be a Spring bean and inject a repository. A uniqueness check in a validator is advisory only; the database constraint is the truth, so also handle `DataIntegrityViolationException` (409).
+
+## Errors: Problem Details
+Enable RFC 9457 responses for Spring's own exceptions:
+
+```yaml
+spring:
+  mvc:
+    problemdetails:
+      enabled: true
+```
+
+Return `ProblemDetail` from your own handlers so every error shares one shape. Extending `ResponseEntityExceptionHandler` keeps the framework exceptions on that shape too.
+
+```java
+@RestControllerAdvice
+class ApiExceptionHandler extends ResponseEntityExceptionHandler {
+
+    @ExceptionHandler(ResourceNotFoundException.class)
+    ProblemDetail notFound(ResourceNotFoundException ex) {
+        return ProblemDetail.forStatusAndDetail(HttpStatus.NOT_FOUND, ex.getMessage());
+    }
+
+    @ExceptionHandler(DataIntegrityViolationException.class)
+    ProblemDetail conflict(DataIntegrityViolationException ex) {
+        return ProblemDetail.forStatusAndDetail(HttpStatus.CONFLICT, "Resource already exists");
+    }
+}
+```
+
+A domain exception can carry its own problem by extending `ErrorResponseException`. Never put stack traces or SQL text in `detail`; log the exception server-side and return a generic message for the catch-all 500.
+
+## Outbound HTTP
+Blocking calls use `RestClient`; build it from the injected `RestClient.Builder` so Boot's customizers (timeouts, SSL, observability) apply.
+
+```java
+@Bean
+RestClient pricingClient(RestClient.Builder builder) {
+    return builder.baseUrl("https://api.example.com").build();
+}
+
+Quote fetch(String id) {
+    return pricingClient.get().uri("/quotes/{id}", id)
+            .retrieve()
+            .onStatus(status -> status.value() == 404, (req, res) -> {
+                throw new ResourceNotFoundException("Quote " + id);
+            })
+            .body(Quote.class);
+}
+```
+
+Prefer an `@HttpExchange` interface when the remote API has several operations (see [spring-boot/cloud.md](cloud.md)). `WebClient` is for reactive or streaming code only.
+
+## CORS
+Prefer one bean over scattered annotations. With Spring Security on the classpath configure CORS in the security chain ([spring-boot/security.md](security.md)); otherwise `WebMvcConfigurer.addCorsMappings`. List explicit origins; `allowedOrigins("*")` cannot be combined with credentials.
+
+## Quick reference
+| Need | Use |
+|------|-----|
+| Page and sort | `Pageable` + `@PageableDefault` |
+| Bad input | `@Valid` -> 400 Problem Details |
+| Missing resource | 404 via your exception handler |
+| Duplicate | 409 from the DB constraint |
+| Slow upstream | `spring.http.clients.connect-timeout` / `read-timeout` |

package/src/skills/spring-boot.md

@@ -0,0 +1,57 @@
+# {{SKILL}}: spring-boot
+
+> {{DESC_SPRING_BOOT}}
+
+{{CREDIT:piomin-spring-boot:skills/spring-boot/SKILL.md}}
+
+{{CREDIT:piomin-spring-boot:skills/conventions/SKILL.md}}
+
+**Trigger:** writing or changing a Spring Boot application (Spring Boot 4, Spring Framework 7, Java 21+) — controllers, services, configuration, security, HTTP clients, logging, cloud-native deployment. Load it for any Spring Boot task, then read the side file the task needs. It does not replace the core review or refactor skills; for a Spring review or refactor, load those and use this one for the framework facts.
+
+Target stack: Spring Boot 4 / Spring Framework 7 / Spring Security 7 / Hibernate 7 / Jakarta EE 11 / Java 21+. Check the project's actual versions first (`pom.xml` or `build.gradle`); if it is still on Boot 3, say so and do not apply the Boot 4 rows below blindly.
+
+## Working loop
+1. Read the build file, `application.yml` and the existing package layout. Match what the project already does (Maven or Gradle, its CI, its test style) before adding anything.
+2. Confirm the design for anything beyond a small change: endpoints, DTOs, transaction boundaries, who authenticates.
+3. Implement in layers, then run the project's own test command and read the output.
+
+## Conventions
+- Layering: controller (HTTP, validation) -> service (business logic, transactions) -> repository. Keep the package layout the project already has; for a new app a flat feature-or-layer split under one root package is fine (`com.example.<app>`).
+- Constructor injection only; one constructor needs no `@Autowired`. Lombok is allowed where the project uses it.
+- DTOs are records. JPA entities are not records. Never return an entity from a controller.
+- `@Valid` on every request body; `@Transactional(readOnly = true)` on read services, `@Transactional` on mutating methods.
+- Typed config: `@ConfigurationProperties` records instead of scattered `@Value`.
+- Errors: one `@RestControllerAdvice`, Problem Details responses.
+- Blocking outbound HTTP: `RestClient`, or an `@HttpExchange` interface. `WebClient` only for reactive or streaming code. Do not mix blocking and reactive in one call path.
+- Jakarta namespaces only (`jakarta.persistence`, `jakarta.validation`, `jakarta.servlet`).
+- Secrets from the environment or mounted files, never committed config.
+- Tests: positive and negative cases; Testcontainers with `@ServiceConnection`; `@MockitoBean` for slice-test collaborators.
+- Baseline properties worth enabling: `spring.threads.virtual.enabled: true`, `spring.mvc.problemdetails.enabled: true`, `server.shutdown: graceful`.
+
+## Boot 4 pitfalls
+Removed or renamed in Boot 4 (do not write them): `@MockBean` and `@SpyBean`, `ClientHttpRequestFactories`, `javax.persistence` (now `jakarta.persistence`), Spring Security 6 idioms such as `authorizeRequests` and `.and()` chains. <!-- banned: ok -->
+
+| Old habit | Boot 4 / Framework 7 reality |
+|-----------|------------------------------|
+| Mock beans in slice tests | `@MockitoBean`, `@MockitoSpyBean` (`org.springframework.test.context.bean.override.mockito`) |
+| Hand-built request factories | `ClientHttpRequestFactoryBuilder` with `HttpClientSettings` |
+| Security configuration | Spring Security 7: lambda DSL, `authorizeHttpRequests` |
+| `org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest` | `org.springframework.boot.webmvc.test.autoconfigure.WebMvcTest`: slices moved to per-technology modules; import from the new packages |
+| Jackson 2 (`com.fasterxml.jackson`) | Jackson 3 is the default (`tools.jackson`); Jackson 2 support is deprecated, `spring.jackson.use-jackson2-defaults` eases migration |
+| `@DynamicPropertySource` for container URLs | `@ServiceConnection` on the container |
+| MockMvc status assertions via Hamcrest | `MockMvcTester` (AssertJ) or `RestTestClient` with `@AutoConfigureRestTestClient` |
+| OpenFeign for declarative clients | `@HttpExchange` interfaces, registered with `@ImportHttpServices` |
+| Zipkin-only tracing setup | `spring-boot-starter-opentelemetry`, `management.opentelemetry.tracing.export.otlp.*` |
+| Starters assumed to pull everything | Boot 4 starters are modular; add the matching starter or test starter for each technology, and read the migration guide when a class vanishes |
+
+## Side files
+- **Web/REST** -> read [spring-boot/web.md](spring-boot/web.md) and follow it.
+- **Security (OAuth2 resource server, method security, SSL bundles)** -> read [spring-boot/security.md](spring-boot/security.md) and follow it.
+- **Cloud-native (config, gateway, resilience, tracing, Kubernetes, images)** -> read [spring-boot/cloud.md](spring-boot/cloud.md) and follow it.
+- **Modern Java in Spring code (records, sealed types, pattern matching, null safety)** -> read [spring-boot/java-modern.md](spring-boot/java-modern.md) and follow it.
+- **Logging and structured logs** -> read [spring-boot/logging.md](spring-boot/logging.md) and follow it.
+
+## Done when
+- The project's build and tests pass, read from real output; no deprecated Boot 2/3 idiom was introduced; every new endpoint validates input and has a negative test.
+
+<!-- INCLUDE: skills/_self-improvement.md -->

package/src/skills/spring-data-jpa/patterns.md

@@ -0,0 +1,68 @@
+# {{SKILL}}: spring-data-jpa — outbox, saga, CQRS
+
+{{CREDIT:piomin-spring-boot:skills/design-patterns/SKILL.md}}
+
+Use when a write must also publish an event, a business process spans services, or reads and writes need separate models. If a plain `@Transactional` method does the job, do not add these.
+
+## Transactional outbox
+
+Dual write (save, then publish to a broker) can lose or duplicate the event. Write the event row in the same transaction as the state change; a separate relay publishes it.
+
+```java
+@Entity
+public class OutboxEvent {
+    @Id @GeneratedValue(strategy = GenerationType.UUID) UUID id;
+    String aggregateId;
+    String type;
+    @Column(columnDefinition = "text") String payload;
+    boolean published;
+    // constructor, getters
+}
+
+@Service
+class OrderService {
+    @Transactional
+    public Order place(OrderRequest req) {
+        Order order = orders.save(Order.from(req));
+        outbox.save(new OutboxEvent(order.getId().toString(), "OrderPlaced", json(order)));
+        return order;                         // both rows commit or neither does
+    }
+}
+
+@Component
+class OutboxRelay {
+    @Scheduled(fixedDelay = 1000)             // needs @EnableScheduling on a config class
+    @Transactional
+    void relay() {
+        for (OutboxEvent e : outbox.findTop100ByPublishedFalseOrderByIdAsc()) {
+            publisher.send(e);                // broker client; may throw, row stays unpublished
+            e.setPublished(true);
+        }
+    }
+}
+```
+
+- Delivery is at-least-once: consumers dedupe on the event id.
+- Several relay instances will pick the same rows. Use a single relay, or a row-claiming query verified for your database (not covered here), or a lock.
+- Delete or archive published rows on a schedule.
+- In-process alternative: publish a Spring `ApplicationEvent` and handle it with `@TransactionalEventListener` (default phase `AFTER_COMMIT`). The handler runs only if the transaction commits, and it is not durable: a crash after commit loses the event. Use it for in-JVM side effects, the outbox table for anything that must survive a crash. If the listener must write to the database again, annotate it `@Transactional(propagation = Propagation.REQUIRES_NEW)`.
+
+## Saga
+
+| Style | Mechanism | Pick when |
+|-------|-----------|-----------|
+| Choreography | each service reacts to the previous service's event and emits its own (events through the outbox) | few steps, no central owner |
+| Orchestration | one `OrderSaga` component sends commands, tracks state in its own table, issues compensations | many steps, branching, need to see where a flow is stuck |
+
+- Every step has a compensating action (cancel, refund, release); compensations must be idempotent.
+- Persist saga state (`STARTED`, `PAYMENT_DONE`, `FAILED`, ...) with `@Version` so concurrent events cannot both advance it.
+- Timeouts are events too: a scheduled job moves stale sagas to compensation.
+- Messaging infrastructure (Spring Cloud Stream, plain Kafka or AMQP clients) is project-specific and not verified here; keep the saga logic behind a small publisher interface.
+
+## CQRS
+
+Split only when read and write shapes diverge. Smallest useful form, same database:
+
+- Write side: aggregate entities and `@Transactional` command services.
+- Read side: projection or DTO-record repository methods (or a view) behind a `@Transactional(readOnly = true)` query service; never return entities.
+- A separate read store fed by outbox events adds eventual consistency: show it in the API (version or timestamp) and accept stale reads.

package/src/skills/spring-data-jpa.md

@@ -0,0 +1,81 @@
+# {{SKILL}}: spring-data-jpa
+
+> {{DESC_SPRING_DATA_JPA}}
+
+{{CREDIT:piomin-spring-boot:skills/jpa-patterns/SKILL.md}}
+
+{{CREDIT:piomin-spring-boot:skills/spring-boot/references/data.md}}
+
+**Trigger:** a Spring Data JPA / Hibernate task in a Spring Boot project: entities, repositories, N+1 queries, `LazyInitializationException`, transactions, locking, projections, Flyway or Liquibase migrations, soft delete, or a transactional outbox. Spring-specific; for generic query or schema work outside Spring, do not load it.
+
+Target stack: Spring Boot 4, Hibernate 7, Jakarta Persistence (`jakarta.persistence.*` only).
+
+## Symptom to fix
+
+| Symptom | Fix |
+|---------|-----|
+| N+1 SELECTs | `@EntityGraph(attributePaths = "books")` or `JOIN FETCH`; as a mitigation only, `hibernate.default_batch_fetch_size` (batch fetching mitigates N+1, it does not solve it) |
+| `LazyInitializationException` | fetch what the use case needs inside the transaction (graph / `JOIN FETCH`) or return a DTO; do not flip associations to `EAGER` |
+| Slow list endpoints | `Pageable` (`Slice` when no total is needed), interface or record projections, indexes |
+| Lost updates | `@Version` (optimistic); `@Lock(LockModeType.PESSIMISTIC_WRITE)` only for hot rows |
+| Slow read-only service | `@Transactional(readOnly = true)` on the class, override on writes |
+| Transaction ignored | self-invocation bypasses the proxy: call through another bean |
+
+## Entities
+
+```java
+@Entity
+@SoftDelete                       // Hibernate: adds a deleted-flag column, filters reads
+public class Author {
+    @Id @GeneratedValue(strategy = GenerationType.UUID)
+    private UUID id;
+    @Version private long version;
+    @OneToMany(mappedBy = "author", fetch = FetchType.LAZY)
+    private List<Book> books = new ArrayList<>();
+    // getters/setters, or Lombok if the project uses it
+}
+```
+
+- Every to-one and to-many is `LAZY`; decide fetching per query, not on the mapping.
+- `@SoftDelete(strategy = ...)` takes `ACTIVE`, `DELETED`, or `TIMESTAMP`; the default stores a deleted flag.
+- `GenerationType.UUID` generates the id in Java; `IDENTITY` and `SEQUENCE` need the database.
+- Equality on entities: id-based with a stable hash, or business key. Never include lazy collections in `equals`/`toString`.
+
+## Repositories and projections
+
+```java
+public interface AuthorRepository extends JpaRepository<Author, UUID> {
+    @EntityGraph(attributePaths = "books")
+    List<Author> findByNameStartingWith(String prefix);
+
+    record AuthorName(UUID id, String name) {}
+    List<AuthorName> findAllBy(Pageable pageable);          // DTO projection
+
+    @Modifying(clearAutomatically = true)
+    @Query("update Author a set a.name = :name where a.id = :id")
+    int rename(UUID id, String name);
+}
+```
+
+- Interface projections are built from tuple queries; DTO records need an all-args constructor and no column aliases in `@Query` JPQL.
+- Bulk `@Modifying` queries bypass the persistence context: `clearAutomatically = true` or reload.
+- Return DTOs from the web layer, never entities.
+
+## Transactions and open-in-view
+
+- Put `@Transactional` on service methods, not repositories or controllers.
+- `spring.jpa.open-in-view` defaults to `true` in a web app (the EntityManager stays open through view rendering). Set it to `false` and fetch explicitly; it hides N+1 otherwise.
+- Detect N+1: `spring.jpa.show-sql=true` is enough for a quick look; assert query counts in a `@DataJpaTest` for regressions.
+
+## Migrations
+
+Schema is owned by migrations, not `ddl-auto`: `spring.jpa.hibernate.ddl-auto=validate` (or `none`) with Flyway or Liquibase, whichever the project already uses. In Boot 4 add the starter (`spring-boot-starter-flyway`), not just the Flyway core jar, or auto-configuration does not apply; Postgres and MySQL also need `flyway-database-postgresql` / `flyway-mysql`. Migration files are immutable once merged; add a new one.
+
+## Outbox, saga, CQRS
+
+Event-publishing alongside a DB write (dual-write problem), distributed workflows, read/write model split: read [spring-data-jpa/patterns.md](spring-data-jpa/patterns.md).
+
+## Done when
+- No lazy collection is touched outside a transaction; hot queries show one SELECT per use case in the SQL log; schema changes ship as a migration; imports are `jakarta.persistence`.
+
+<!-- INCLUDE: skills/_self-improvement.md -->

package/src/skills/spring-testing.md

@@ -0,0 +1,93 @@
+# {{SKILL}}: spring-testing
+
+> {{DESC_SPRING_TESTING}}
+
+{{CREDIT:piomin-spring-boot:skills/testing-patterns/SKILL.md}}
+
+{{CREDIT:piomin-spring-boot:skills/spring-boot/references/testing.md}}
+
+**Trigger:** writing or fixing tests in a Spring Boot project: unit tests of services, `@WebMvcTest` / `@DataJpaTest` slices, `@SpringBootTest` integration tests, Testcontainers, mocking beans. Spring-specific; core test discipline lives in the test-gates and develop skills.
+
+Target stack: Spring Boot 4, JUnit 5, Mockito, AssertJ.
+
+## Pick the narrowest test
+
+| Goal | Tool |
+|------|------|
+| Service logic | plain JUnit + `@ExtendWith(MockitoExtension.class)`, no Spring context |
+| Controller mapping, validation, serialization | `@WebMvcTest(X.class)` + `MockMvcTester` + `@MockitoBean` |
+| Repository queries, mappings | `@DataJpaTest` against the real database engine |
+| Whole app over HTTP | `@SpringBootTest(webEnvironment = RANDOM_PORT)` + `@AutoConfigureRestTestClient` |
+| Whole app, no server | `@SpringBootTest` + `@AutoConfigureMockMvc` |
+
+Boot 4 split the test support into modules: slice annotations live in `org.springframework.boot.<module>.test.autoconfigure` (e.g. `org.springframework.boot.data.jpa.test.autoconfigure.DataJpaTest`); `@AutoConfigureTestDatabase` is in `org.springframework.boot.jdbc.test.autoconfigure`. Let the IDE import them. Use the matching test starter (`spring-boot-starter-data-jpa-test`, and so on) so each slice is on the classpath.
+
+## Mocking beans
+
+The Boot-era mock-bean annotations are gone in Boot 4. Use `@MockitoBean` and `@MockitoSpyBean` (from `org.springframework.test.context.bean.override.mockito`).
+
+```java
+@WebMvcTest(UserController.class)
+class UserControllerTests {
+    @Autowired MockMvcTester mvc;
+    @MockitoBean UserService users;
+
+    @Test
+    void unknownUserIs404() {
+        given(users.find("x")).willThrow(new UserNotFoundException("x"));
+        assertThat(mvc.get().uri("/users/x")).hasStatus(HttpStatus.NOT_FOUND);
+    }
+}
+```
+
+`MockMvcTester` is AssertJ-based (`assertThat(mvc.get().uri(...)).hasStatusOk()`); do not mix it with the `expectStatus()` chain, which belongs to the other clients. Security: `@WithMockUser` still works on slices; `@Import` your security config.
+
+## Full-server test
+
+```java
+@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
+@AutoConfigureRestTestClient
+class UserApiTests {
+    @Autowired RestTestClient client;
+
+    @Test
+    void createReturns201() {
+        client.post().uri("/users").contentType(MediaType.APPLICATION_JSON)
+              .body(new UserRequest("a@example.com"))
+              .exchange()
+              .expectStatus().isCreated();
+    }
+}
+```
+
+`RestTestClient` resolves relative URIs against the running server; it also supports AssertJ-style assertions through its response type. Customize through a `RestTestClientBuilderCustomizer` bean.
+
+## Real dependencies with Testcontainers
+
+Prefer `@ServiceConnection`: Boot derives connection details, no property wiring.
+
+```java
+@TestConfiguration(proxyBeanMethods = false)
+class ContainersConfig {
+    @Bean @ServiceConnection
+    PostgreSQLContainer postgres() { return new PostgreSQLContainer("postgres:16"); }
+}
+
+@DataJpaTest
+@Import(ContainersConfig.class)
+class AuthorRepositoryTests { /* ... */ }
+```
+
+- Testcontainers 2 containers are non-generic and live in per-module packages (`org.testcontainers.postgresql.PostgreSQLContainer`, artifact `testcontainers-postgresql`).
+- The default `replace = NON_TEST` already keeps a `@ServiceConnection` data source; `replace = NONE` is only needed for a non-test `DataSource` you defined yourself.
+- Where `@ServiceConnection` has no support for the container, use `@Testcontainers` + `@Container static` + `@DynamicPropertySource` to register the properties.
+- Share one container configuration across tests so the context cache is reused.
+
+## Rules
+
+- Test behaviour through the public seam; do not assert on mock call counts unless the call is the behaviour.
+- Slice tests load only what they need; reaching for `@SpringBootTest` to test one controller is a smell.
+- Never replace the database engine with H2 when production runs another one; dialect differences hide bugs.
+- No `Thread.sleep`: wait on the condition with a bounded timeout.
+
+<!-- INCLUDE: skills/_self-improvement.md -->

package/src/skills/wayfinder.md

@@ -2,6 +2,8 @@
 
 > {{DESC_WAYFINDER}}
 
+{{CREDIT:mattpocock-skills:skills/engineering/wayfinder/SKILL.md}}
+
 **Trigger:** a piece of work too large for one session and still in the fog —
 the destination can be named but the route to it cannot; the user says
 "wayfinder" or asks to chart a big effort before building anything.
@@ -27,7 +29,8 @@ the destination can be named but the route to it cannot; the user says
    `wayfinder:<type>` label (or a `Type:` line), which names how it resolves:
    - **research** (agent alone) — a fact the decision waits on, from docs, an API or
      the web: a subagent runs the [research {{SKILL}}](research.md). Fire every research
-     ticket in parallel as soon as the map is charted.
+     ticket in parallel as soon as the map is charted. Then stop: charting is one session's work and
+     resolves no ticket itself.
    - **prototype** (with the user) — a rough artifact to react to when "how should it
      look or behave" is the question: the [prototype {{SKILL}}](prototype.md).
    - **grilling** (with the user, the default) — an interview through the
@@ -45,7 +48,10 @@ the destination can be named but the route to it cannot; the user says
    `Status: claimed`) so concurrent sessions skip it. Resolve it as its type says — read
    the label, the body never states it — write the decision into the ticket,
    gist-and-link it on the map, close it. At most one ticket per session (research
-   tickets excepted). New questions become tickets.
+   tickets excepted). New questions become tickets; fog the answer made specifiable
+   graduates to tickets and leaves **Not yet specified**; a ticket the answer invalidates
+   is updated or closed, and one now past the destination is closed with an **Out of
+   scope** line.
 5. In everything the user reads, refer to the map and tickets **by name**,
    never by bare issue number — the id rides inside the name's link.
 6. Stop when the frontier is empty: nothing left to decide means the way is