@damiangilgonzalez/harness 1.3.7

package/skills/spreadsheet-ops/scripts/verify.sh

@@ -0,0 +1,152 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# verify.sh — spreadsheet-ops artifact check. Read-only by default.
+#
+# What it proves about the artifacts this skill emits:
+#   1. Every generated *.py compiles (python -m py_compile) — valid syntax, real imports.
+#   2. Every generated *.xlsx opens with openpyxl and has at least one sheet with a
+#      non-empty first (header) row.
+#   3. Formula strings (anything matching a leading '=' inside the .py/.xlsx) are linted
+#      for the semicolon-as-argument-separator bug — the #1 locale formula failure.
+#
+# Targets, in order of precedence:
+#   - explicit paths passed as arguments (files or directories), OR
+#   - the current working directory (scanned for *.py and *.xlsx).
+#
+# It NEVER modifies your files and makes NO network/Google calls — cloud paths in this
+# skill are validated by structure, not live API requests.
+#
+# Exit code: 0 on pass OR on a clean/empty target (nothing to check is not a failure).
+# Non-zero ONLY when a found artifact is genuinely broken (won't compile, won't open,
+# missing header, or a semicolon-separated formula).
+
+YELLOW=$'\033[33m'; GREEN=$'\033[32m'; RED=$'\033[31m'; NC=$'\033[0m'
+skip() { printf '%s[skip]%s %s\n' "$YELLOW" "$NC" "$*"; }
+ok()   { printf '%s[ok]%s %s\n'   "$GREEN"  "$NC" "$*"; }
+err()  { printf '%s[fail]%s %s\n' "$RED"    "$NC" "$*"; }
+
+PY="$(command -v python3 || command -v python || true)"
+
+# Collect candidate files from args (files/dirs) or the cwd.
+PYFILES=(); XLSXFILES=()
+collect() {
+  local t="$1"
+  if [ -d "$t" ]; then
+    while IFS= read -r f; do PYFILES+=("$f"); done   < <(find "$t" -type f -name '*.py'   2>/dev/null)
+    while IFS= read -r f; do XLSXFILES+=("$f"); done < <(find "$t" -type f -name '*.xlsx' 2>/dev/null)
+  elif [ -f "$t" ]; then
+    case "$t" in
+      *.py)   PYFILES+=("$t") ;;
+      *.xlsx) XLSXFILES+=("$t") ;;
+    esac
+  fi
+}
+
+if [ "$#" -gt 0 ]; then
+  for t in "$@"; do collect "$t"; done
+else
+  collect "$PWD"
+fi
+
+if [ "${#PYFILES[@]}" -eq 0 ] && [ "${#XLSXFILES[@]}" -eq 0 ]; then
+  skip "no .py or .xlsx artifacts found to verify — nothing to check"
+  exit 0
+fi
+
+fail=0
+
+# 1. py_compile each Python file.
+if [ "${#PYFILES[@]}" -gt 0 ]; then
+  if [ -z "$PY" ]; then
+    skip "python not on PATH — skipping .py compile checks"
+  else
+    for f in "${PYFILES[@]}"; do
+      if "$PY" -m py_compile "$f" >/dev/null 2>&1; then
+        ok "compiles: $f"
+      else
+        err "does not compile: $f"; fail=1
+      fi
+    done
+  fi
+fi
+
+# 2. open each workbook, assert a sheet + non-empty header row (needs openpyxl).
+if [ "${#XLSXFILES[@]}" -gt 0 ]; then
+  if [ -z "$PY" ] || ! "$PY" -c "import openpyxl" >/dev/null 2>&1; then
+    skip "openpyxl not installed — skipping .xlsx structural checks"
+  else
+    for f in "${XLSXFILES[@]}"; do
+      if "$PY" - "$f" <<'PYEOF'
+import sys
+from openpyxl import load_workbook
+wb = load_workbook(sys.argv[1], read_only=True, data_only=False)
+if not wb.sheetnames:
+    sys.exit(1)
+ws = wb[wb.sheetnames[0]]
+row = next(ws.iter_rows(min_row=1, max_row=1, values_only=True), None)
+sys.exit(0 if row is not None and any(c is not None and str(c) != "" for c in row) else 1)
+PYEOF
+      then
+        ok "opens with header row: $f"
+      else
+        err "missing/unreadable or empty header row: $f"; fail=1
+      fi
+    done
+  fi
+fi
+
+# 3. lint formula strings for semicolon argument separators inside .py/.xlsx-as-text.
+# A formula is a token starting with '=' that contains '(' and a ';'. Commas are correct;
+# semicolons inside the parens are the locale bug this skill warns about.
+# The lint script reads stdin; pass it via -c so the piped file flows through as stdin
+# (a heredoc on `$PY -` would itself become stdin and shadow the file).
+LINT_PY='import sys, re
+bad = []
+pat = re.compile(r"=[A-Za-z_][A-Za-z0-9_.]*\([^)]*;[^)]*\)")
+for i, line in enumerate(sys.stdin, 1):
+    if pat.search(line):
+        bad.append((i, line.rstrip()))
+for i, l in bad:
+    print(f"  line {i}: {l}")
+sys.exit(1 if bad else 0)'
+lint_text() {
+  # reads stdin; prints offending lines; returns 1 if any found
+  "$PY" -c "$LINT_PY"
+}
+
+if [ -n "$PY" ]; then
+  for f in "${PYFILES[@]}"; do
+    if out="$(lint_text < "$f")"; then :; else
+      err "semicolon-separated formula in $f"; printf '%s\n' "$out"; fail=1
+    fi
+  done
+  # For .xlsx, extract embedded formula strings from the workbook XML via openpyxl text.
+  if [ -n "$PY" ] && "$PY" -c "import openpyxl" >/dev/null 2>&1; then
+    for f in "${XLSXFILES[@]}"; do
+      formulas="$("$PY" - "$f" <<'PYEOF'
+import sys
+from openpyxl import load_workbook
+wb = load_workbook(sys.argv[1], data_only=False)
+for ws in wb.worksheets:
+    for row in ws.iter_rows():
+        for c in row:
+            v = c.value
+            if isinstance(v, str) and v.startswith("="):
+                print(v)
+PYEOF
+)"
+      if [ -n "$formulas" ]; then
+        if out="$(printf '%s\n' "$formulas" | lint_text)"; then :; else
+          err "semicolon-separated formula in workbook $f"; printf '%s\n' "$out"; fail=1
+        fi
+      fi
+    done
+  fi
+fi
+
+if [ "$fail" -eq 0 ]; then
+  ok "all found artifacts pass"
+  exit 0
+fi
+exit 1

package/skills/spring-boot/SKILL.md

@@ -0,0 +1,350 @@
+---
+name: spring-boot
+description: "Use when building, reviewing, testing, securing or configuring a Spring Boot 4 / Framework 7 backend — controllers, services, Spring Data JPA, application.yml, SecurityFilterChain, slice tests. NOT plain modern-Java language work like records or virtual threads (that is `java`); NOT engine-level SQL schema/index/EXPLAIN (that is `postgresdb`)."
+tags: [java, spring, jpa, security, backend]
+recommends: [java, postgresdb, secure-coding, deployment]
+origin: risco
+---
+
+# Spring Boot backends (Boot 4 / Framework 7)
+
+A Spring Boot app is **a thin web layer delegating to a transactional service layer over
+Spring Data JPA repositories** — wired by constructor injection, configured by typed
+`@ConfigurationProperties`, locked down by a `SecurityFilterChain` bean. Controllers
+validate input and delegate; they never own business logic, transactions, or persistence.
+Hold that shape and most "where does this go?" questions answer themselves.
+
+**Pinned stack** (verify against the project's `pom.xml`/`build.gradle` — do not assume):
+Spring Boot 4.0 (GA 2025-11-20), Spring Framework 7, Java 17 baseline / Java 25 LTS, Jakarta
+EE 11 (`jakarta.*`, never `javax.*`), Jackson 3, Spring Security 7, Spring Data JPA /
+Hibernate 7, JUnit 5 + Testcontainers, Maven 3.9 / Gradle.
+
+If you are typing `WebSecurityConfigurerAdapter`, `@MockBean`, field `@Autowired`,
+`authorizeRequests`, or `javax.persistence` — **stop**. Those are the previous generation.
+The modern idioms below replace every one of them.
+
+## Boundaries
+
+- Plain Java language work (records, sealed types, virtual threads, streams, pattern
+  matching) with no Spring -> [`../java/SKILL.md`](../java/SKILL.md).
+- Async Python FastAPI -> [`../fastapi/SKILL.md`](../fastapi/SKILL.md). NestJS/Node ->
+  [`../nestjs/SKILL.md`](../nestjs/SKILL.md). Django -> [`../django/SKILL.md`](../django/SKILL.md).
+- Engine-level SQL: schema/index design, `EXPLAIN`, partitioning, zero-downtime DDL ->
+  [`../postgresdb/SKILL.md`](../postgresdb/SKILL.md) (this skill drives the JPA layer above it).
+- Language-agnostic injection/authz/secret theory ->
+  [`../secure-coding/SKILL.md`](../secure-coding/SKILL.md).
+- Dockerfile/Compose/CI/CD mechanics -> [`../deployment/SKILL.md`](../deployment/SKILL.md)
+  (keep only a build note here).
+
+## Project layout
+
+Package by feature, not by layer — colocation keeps a change to one feature in one folder.
+
+```text
+com.acme.shop
+├── order/
+│   ├── OrderController.java       // @RestController — web edge
+│   ├── OrderService.java          // @Service — @Transactional unit of work
+│   ├── OrderRepository.java       // extends JpaRepository<Order, Long>
+│   ├── Order.java                 // @Entity (jakarta.persistence)
+│   └── dto/CreateOrderRequest.java, OrderResponse.java   // records, never entities
+├── config/AppProperties.java      // @ConfigurationProperties record
+├── security/SecurityConfig.java   // SecurityFilterChain bean
+└── ShopApplication.java           // @SpringBootApplication
+```
+
+## Controllers
+
+`@RestController` + DTO records, `@Valid` on the body (Bean Validation, `jakarta.validation`)
+so business code can assume valid data, `ResponseEntity` for 201/`Location`, a
+`@RestControllerAdvice` for one error envelope. The controller parses, validates, delegates
+and maps — any branch with business meaning belongs in the service, where it is transactional
+and unit-testable without MVC. Boot 4 adds first-class versioning via a `version` attribute
+on the mapping — one controller serves many versions, no path duplication.
+
+```java
+@RestController
+@RequestMapping("/api/users")
+class UserController {
+    private final UserService users;
+    UserController(UserService users) { this.users = users; }   // constructor injection
+
+    @PostMapping(version = "1")                                  // Boot 4 API versioning
+    ResponseEntity<UserResponse> create(@Valid @RequestBody CreateUserRequest req) {
+        UserResponse body = users.create(req);
+        URI location = URI.create("/api/users/" + body.id());
+        return ResponseEntity.created(location).body(body);     // 201 + Location
+    }
+}
+
+record CreateUserRequest(@NotBlank String name, @Email String email) {}
+record UserResponse(Long id, String name, String email) {}
+```
+
+```java
+@RestControllerAdvice
+class ApiExceptionHandler {
+    @ExceptionHandler(MethodArgumentNotValidException.class)
+    ResponseEntity<ApiError> onInvalid(MethodArgumentNotValidException e) {
+        var details = e.getBindingResult().getFieldErrors().stream()
+            .map(f -> f.getField() + ": " + f.getDefaultMessage()).toList();
+        return ResponseEntity.badRequest().body(new ApiError("validation_failed", "Invalid request", details));
+    }
+}
+record ApiError(String code, String message, List<String> details) {}
+```
+
+**Bad -> Good** — never return the entity; it leaks columns and lazy-loads in the serializer:
+
+```java
+// Bad: leaks columns; lazy fields blow up in the serializer after the tx closes.
+@GetMapping("/{id}") User get(@PathVariable Long id) { return repo.findById(id).orElseThrow(); }
+// Good: map to a DTO inside the transactional service.
+@GetMapping("/{id}") UserResponse get(@PathVariable Long id) { return users.get(id); }
+```
+
+## Service + transactions
+
+Constructor-injected, `final` fields, `@Transactional` on the write path, `readOnly = true`
+on queries (lets Hibernate skip dirty checking). `@Transactional` belongs on service methods,
+never on a controller or repository: the transaction must wrap the unit of work, not the HTTP
+request or a single query.
+
+```java
+@Service
+class UserService {
+    private final UserRepository repo;
+    private final PasswordEncoder encoder;
+    UserService(UserRepository repo, PasswordEncoder encoder) { this.repo = repo; this.encoder = encoder; }
+
+    @Transactional
+    UserResponse create(CreateUserRequest req) {
+        var user = repo.save(new User(req.name(), req.email(), encoder.encode(req.rawPassword())));
+        return new UserResponse(user.getId(), user.getName(), user.getEmail());
+    }
+
+    @Transactional(readOnly = true)
+    UserResponse get(Long id) {
+        return repo.findById(id).map(this::toResponse).orElseThrow(() -> new NotFoundException(id));
+    }
+}
+```
+
+Two traps that produce "my `@Transactional` isn't rolling back":
+- **Self-invocation.** Calling `this.other()` inside the same bean bypasses the proxy, so its
+  `@Transactional` is ignored. Split into another bean or accept the outer transaction.
+- **Checked exceptions don't roll back by default.** Spring rolls back on `RuntimeException`
+  only; use `@Transactional(rollbackFor = ...)` for checked ones.
+
+**Bad -> Good** — field injection vs constructor:
+
+```java
+// Bad: not testable with `new`, hides missing beans until runtime, allows final-less mutation.
+@Autowired private UserRepository repo;
+// Good:
+private final UserRepository repo;
+UserService(UserRepository repo) { this.repo = repo; }
+```
+
+## JPA persistence
+
+`jakarta.persistence` imports (never `javax`). Spring Data gives you derived queries for free
+and `@Query` for the rest; `Pageable`/`Page` for paging.
+
+```java
+import jakarta.persistence.*;
+
+@Entity @Table(name = "users")
+class User {
+    @Id @GeneratedValue(strategy = GenerationType.IDENTITY) private Long id;
+    private String name;
+    @Column(unique = true) private String email;
+    @OneToMany(mappedBy = "user") private List<Order> orders = new ArrayList<>();
+    // getters; protected no-arg ctor for Hibernate
+}
+
+interface UserRepository extends JpaRepository<User, Long> {
+    Optional<User> findByEmail(String email);                       // derived query
+    Page<User> findByNameContaining(String q, Pageable page);       // paginated
+
+    @Query("select u from User u join fetch u.orders where u.id = :id")
+    Optional<User> findWithOrders(@Param("id") Long id);            // fetch join kills N+1
+}
+```
+
+**N+1 symptom:** iterating a lazy collection issues one query per parent. Fix with a
+`join fetch`, an `@EntityGraph`, or `@BatchSize`. **`LazyInitializationException`** means you
+touched a lazy field after the transaction (and its Hibernate session) closed — map to a DTO
+*inside* the `@Transactional` service, or fetch eagerly for that path. Relationship/cascade
+depth, projections, Specifications, optimistic locking and migration tooling are in
+[`references/jpa.md`](references/jpa.md).
+
+## Configuration & profiles
+
+```yaml
+# application.yml — no secrets committed here; import them at boot.
+spring:
+  config:
+    import: "optional:configtree:/run/secrets/"   # mount real secrets at runtime
+  datasource:
+    url: ${DB_URL}
+    username: ${DB_USER}
+    password: ${DB_PASSWORD}
+app:
+  invite-ttl: 24h
+  max-orders-per-day: 50
+---
+spring:
+  config:
+    activate:
+      on-profile: dev
+app:
+  max-orders-per-day: 5
+```
+
+```java
+@ConfigurationProperties(prefix = "app")
+record AppProperties(Duration inviteTtl, int maxOrdersPerDay) {}   // typed, validated at startup
+// register once: @EnableConfigurationProperties(AppProperties.class) on a @Configuration
+```
+
+**Bad -> Good** — scattered `@Value("${app.max-orders-per-day}")` strings vs one injected
+`AppProperties` record. One typed binding beats string keys sprinkled across the codebase and
+fails fast on a missing/mistyped key instead of NPE-ing later.
+
+## Security
+
+A single `SecurityFilterChain` bean with the lambda DSL, stateless for token APIs, JWT via the
+resource server.
+
+```java
+@Configuration
+@EnableMethodSecurity                                            // enables @PreAuthorize
+class SecurityConfig {
+    @Bean
+    SecurityFilterChain api(HttpSecurity http) throws Exception {
+        http
+          .csrf(csrf -> csrf.disable())                          // OK: stateless token API, no cookies
+          .sessionManagement(s -> s.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
+          .authorizeHttpRequests(auth -> auth
+              .requestMatchers(HttpMethod.POST, "/api/users").permitAll()
+              .requestMatchers("/api/admin/**").hasRole("ADMIN")
+              .anyRequest().authenticated())
+          .oauth2ResourceServer(o -> o.jwt(Customizer.withDefaults()));
+        return http.build();
+    }
+
+    @Bean PasswordEncoder passwordEncoder() { return new BCryptPasswordEncoder(); }
+}
+```
+
+Order `requestMatchers` from most specific to least — the first match wins, so a broad
+`permitAll` placed early opens routes you meant to lock. Full JWT/OAuth2 client, method
+security, CORS, and CSRF posture (token vs cookie apps) live in
+[`references/security.md`](references/security.md). For the language-agnostic authz/secret
+principles behind these rules, see [`../secure-coding/SKILL.md`](../secure-coding/SKILL.md).
+
+## Testing
+
+Pick the narrowest slice that exercises what you changed — `@SpringBootTest` only when you
+genuinely need the full context:
+
+| Slice | Loads | Use for | Collaborators |
+|---|---|---|---|
+| `@WebMvcTest` | web layer + Security + MockMvc | one controller's HTTP contract | `@MockitoBean` the service |
+| `@DataJpaTest` | JPA + in-memory/TC DB, rolls back per test | repository queries, mappings | real repo, test DB |
+| `@SpringBootTest` | full context | end-to-end / integration | real beans, Testcontainers |
+
+`@MockBean`/`@SpyBean` are removed — use `@MockitoBean`/`@MockitoSpyBean` from
+`org.springframework.test.context.bean.override.mockito`.
+
+```java
+@WebMvcTest(UserController.class)
+class UserControllerTest {
+    @Autowired MockMvc mvc;
+    @MockitoBean UserService users;                              // not @MockBean
+
+    @Test void rejectsBlankName() throws Exception {
+        mvc.perform(post("/api/users").contentType(MediaType.APPLICATION_JSON)
+                .content("{\"name\":\"\",\"email\":\"a@b.co\"}"))
+           .andExpect(status().isBadRequest());
+    }
+}
+```
+
+Integration DB via Testcontainers + `@ServiceConnection` (auto-wires connection details, no
+`@DynamicPropertySource`):
+
+```java
+@TestConfiguration(proxyBeanMethods = false)
+class ContainersConfig {
+    @Bean @ServiceConnection
+    PostgreSQLContainer<?> postgres() { return new PostgreSQLContainer<>("postgres:17"); }
+}
+```
+
+Slice deep dive, container reuse, `MockMvcTester`/`WebTestClient`, and the CI gate are in
+[`references/testing.md`](references/testing.md).
+
+## HTTP clients & resilience
+
+Outbound calls: declare an `@HttpExchange` interface and register it — no manual
+`RestTemplate`/`HttpServiceProxyFactory` boilerplate.
+
+```java
+@HttpExchange("/v1")
+interface BillingClient {
+    @GetExchange("/invoices/{id}") Invoice invoice(@PathVariable String id);
+}
+// register: @ImportHttpServices(group = "billing", types = BillingClient.class) on a @Configuration
+```
+
+`RestClient` is the modern synchronous client for ad-hoc calls. For built-in resilience,
+`@Retryable` and `@ConcurrencyLimit` are core in Framework 7 — no extra Spring Retry
+dependency for the basics.
+
+## Anti-patterns
+
+| Anti-pattern | Why it's wrong | Do instead |
+|---|---|---|
+| Extend `WebSecurityConfigurerAdapter` | Removed in Security 6/7 | `SecurityFilterChain` bean + lambda DSL |
+| `@Autowired` on a field | Untestable, hides missing beans till runtime | constructor injection, `final` fields |
+| `@Transactional` on a `@RestController` | Tx must wrap the unit of work, not the request | put it on the service method |
+| Business branching in the controller | Not transactional, needs MVC to test | move the decision into the `@Service` |
+| Return the `@Entity` from a controller | Leaks columns, lazy-loads in serializer (LIE) | map to a DTO record inside the tx |
+| Request body reaching the service unvalidated | Business code can no longer assume valid data | `@Valid` + `jakarta.validation` at the edge |
+| Scattered `@Value("${...}")` config keys | String keys, no validation, fails late | one typed `@ConfigurationProperties` record |
+| Use `@MockBean` / `@SpyBean` | Replaced in Boot 4 | `@MockitoBean` / `@MockitoSpyBean` |
+| `import javax.persistence` / `javax.validation` | Jakarta EE 11 baseline | `jakarta.*` |
+| `authorizeRequests` / `antMatchers` | Gone in Security 6/7 | `authorizeHttpRequests` + `requestMatchers` |
+| `csrf().disable()` with no rationale | Silently opens cookie-session apps | disable only for stateless token APIs; comment why |
+| `@SpringBootTest` for one controller | Slow, loads everything | `@WebMvcTest` + `@MockitoBean` |
+| One 800-line `@Service` | Untestable, tangled transactions | split per use case / aggregate |
+| `catch (Exception e)` and echo `e.getMessage()` | Leaks internals, swallows bugs | `@RestControllerAdvice` + typed error envelope |
+| Serialize a lazy collection after the tx closes | `LazyInitializationException` / N+1 | fetch join or `@EntityGraph`, map in-tx |
+
+`scripts/verify.sh` greps a project for the legacy idioms above (read-only, best effort).
+
+## Quick reference
+
+| Task | Idiom |
+|---|---|
+| Inject a dependency | constructor arg, `final` field |
+| Expose an endpoint | `@RestController` + `@GetMapping`/`@PostMapping(version=)` |
+| Validate input | `@Valid @RequestBody` + `jakarta.validation` annotations |
+| Get by id | `repo.findById(id).orElseThrow(...)` in a `readOnly` tx |
+| Paginate | `Page<T> findBy...(..., Pageable page)` |
+| Custom query | `@Query("select ... join fetch ...")` |
+| Transaction boundary | `@Transactional` on the service method |
+| Hash a password | `PasswordEncoder` bean (`BCryptPasswordEncoder`) |
+| Lock down routes | `SecurityFilterChain` + `authorizeHttpRequests`/`requestMatchers` |
+| JWT API | `oauth2ResourceServer(o -> o.jwt(...))`, stateless session |
+| Mock a collaborator in a test | `@MockitoBean` |
+| Integration DB | Testcontainers `@Bean` + `@ServiceConnection` |
+
+## Project grounding
+
+If the repo has a `docs/` wiki, record stack decisions (Boot version, security posture,
+test strategy, migration tool) in `docs/wiki/stack/spring-boot.md` and link it from the
+`CLAUDE.md` Knowledge map. This is recorded, not gated — if there is no `docs/`, skip
+silently; you may suggest the project harness if the user wants persistent docs.

package/skills/spring-boot/evals/README.md

@@ -0,0 +1,11 @@
+# Evals — spring-boot
+
+These cases are LLM-graded routing and capability checks, not a runtime test harness. Run them
+through the repo's eval runner against this skill's `description` + body. `should_trigger`
+asserts the router selects `spring-boot` (including the non-obvious symptom prompts like the
+`@Transactional` rollback and `LazyInitializationException` cases and the Spanish/Catalan
+phrasings); `should_not_trigger` asserts it prefers the named sibling instead (`java`,
+`fastapi`, `postgresdb`, `deployment`, `secure-coding`). The `capability` case is graded by
+checking the produced solution against the `must_include` rubric — each bullet is a modern
+Boot 4 idiom that must appear (and the corresponding legacy idiom must be absent). There is no
+compilation step here; `scripts/verify.sh` is the static lint that complements these grades.

package/skills/spring-boot/evals/cases.yaml

@@ -0,0 +1,49 @@
+skill: spring-boot
+
+should_trigger:
+  - prompt: "Add a REST endpoint to create an order in our Spring Boot service."
+    why: "Core controller/service work — the central job of the skill."
+  - prompt: "My @Transactional method isn't rolling back when it throws, why?"
+    why: "Non-obvious proxy self-invocation + checked-exception-no-rollback trap; documented in the service/transactions section."
+  - prompt: "I get LazyInitializationException when the JSON serializer reads the response."
+    why: "Classic JPA fetch/session-boundary symptom; the fix is map-to-DTO-in-tx, a core rule here."
+  - prompt: "Migra esta config de seguridad, usa WebSecurityConfigurerAdapter y está deprecada."
+    why: "Spanish; SecurityFilterChain migration is an explicit modern-surface concern of the skill."
+  - prompt: "Set up a @WebMvcTest for the controller and mock the service."
+    why: "Slice testing + @MockitoBean — non-obvious that @MockBean is the wrong (removed) idiom."
+  - prompt: "Configura @ConfigurationProperties con perfiles para esta app."
+    why: "Catalan/Spanish; typed @ConfigurationProperties + profiles is a documented config surface."
+  - prompt: "We have N+1 selects on a lazy collection — how do I fetch-join it?"
+    why: "JPA fetch strategy / @EntityGraph, a documented depth area."
+
+should_not_trigger:
+  - prompt: "Refactor this instanceof ladder into a pattern-matching switch."
+    route_to: java
+    why: "Pure Java language feature, no Spring wiring involved."
+  - prompt: "Build the same API in FastAPI with async SQLAlchemy."
+    route_to: fastapi
+    why: "Structural twin but a different framework/ecosystem."
+  - prompt: "Design the Postgres indexes and run EXPLAIN on this slow query."
+    route_to: postgresdb
+    why: "Engine-level SQL; this skill drives the JPA layer above it, not index design."
+  - prompt: "Write the Dockerfile and GitHub Actions pipeline to deploy this jar."
+    route_to: deployment
+    why: "Container/CI mechanics, not Spring framework code."
+  - prompt: "Explain how SQL injection defenses work in general."
+    route_to: secure-coding
+    why: "Language-agnostic security theory, not the Spring security surface."
+
+capability:
+  - scenario: >
+      Implement a POST /api/v1/users endpoint backed by JPA: validate the request, run the
+      write in a service-layer transaction, add a SecurityFilterChain that permits the route,
+      and add a @WebMvcTest for the controller.
+    must_include:
+      - "Constructor injection with final fields (no field @Autowired)."
+      - "DTO records for request and response (never the @Entity exposed)."
+      - "@Transactional on the service method, not the controller."
+      - "SecurityFilterChain bean using authorizeHttpRequests + requestMatchers."
+      - "@WebMvcTest with the service supplied via @MockitoBean (not @MockBean)."
+      - "jakarta.* imports (validation/persistence), never javax.*."
+      - "@Valid at the controller edge."
+      - "ResponseEntity 201 Created with a Location header."

package/skills/spring-boot/references/jpa.md

@@ -0,0 +1,94 @@
+# JPA persistence depth
+
+The SKILL.md covers entities, `JpaRepository`, derived/`@Query`, paging, and the N+1 /
+`LazyInitializationException` headline. This is the depth: relationships, fetch strategy,
+projections, Specifications, optimistic locking, and migrations. Engine-level SQL (index
+design, `EXPLAIN`, partitioning) is `../postgresdb/SKILL.md`'s job — this file stays on the
+JPA/Hibernate layer above it.
+
+## Relationships, cascade, fetch type
+
+- Default `@ManyToOne` is **EAGER**, `@OneToMany`/`@ManyToMany` are **LAZY**. Make
+  `@ManyToOne` lazy explicitly when you don't always need the parent:
+  `@ManyToOne(fetch = FetchType.LAZY)`.
+- Never put `CascadeType.ALL` on a `@ManyToOne` — you'll cascade-delete shared parents. Cascade
+  belongs on the owning side of a true parent/child aggregate (`@OneToMany`).
+- Map the relationship on **one** side and mark the other `mappedBy`. Two owning sides write
+  the join column twice.
+
+```java
+@Entity
+class Order {
+    @ManyToOne(fetch = FetchType.LAZY) @JoinColumn(name = "user_id")
+    private User user;
+    @OneToMany(mappedBy = "order", cascade = CascadeType.ALL, orphanRemoval = true)
+    private List<OrderLine> lines = new ArrayList<>();
+}
+```
+
+## N+1 detection and fixes
+
+**Detect.** Turn on SQL logging in a test profile and watch for a query repeated once per
+parent:
+
+```yaml
+logging.level.org.hibernate.SQL: DEBUG
+spring.jpa.properties.hibernate.generate_statistics: true   # logs query counts per session
+```
+
+**Fix, in order of preference:**
+
+1. **`join fetch`** in a `@Query` — best when you always need the association for that path.
+2. **`@EntityGraph`** on the repository method — declarative, reusable, no JPQL.
+   ```java
+   @EntityGraph(attributePaths = {"orders"})
+   Optional<User> findById(Long id);
+   ```
+3. **`@BatchSize(size = 50)`** on the collection/entity — turns N+1 into N/50 IN-queries when
+   you can't fetch-join (e.g. multiple bags).
+
+Do **not** "fix" N+1 by making everything EAGER — that just moves the cost to every query and
+risks cartesian-product blowups when fetch-joining two collections at once.
+
+## Projections — don't fetch what you won't return
+
+- **Interface projection:** declare an interface of getters; Spring builds a proxy selecting
+  only those columns.
+  ```java
+  interface UserSummary { Long getId(); String getName(); }
+  List<UserSummary> findByActiveTrue();
+  ```
+- **DTO/record projection** via constructor expression:
+  `@Query("select new com.acme.UserSummary(u.id, u.name) from User u")`.
+
+Projections sidestep `LazyInitializationException` entirely — there is no lazy proxy to touch.
+
+## Specifications (dynamic queries)
+
+For optional filters, prefer `JpaSpecificationExecutor` over building JPQL strings:
+
+```java
+interface OrderRepository extends JpaRepository<Order, Long>, JpaSpecificationExecutor<Order> {}
+
+Specification<Order> byStatus(Status s) {
+    return (root, q, cb) -> s == null ? null : cb.equal(root.get("status"), s);
+}
+// repo.findAll(byStatus(status).and(byUser(userId)), pageable);
+```
+
+## Optimistic locking
+
+Add a `@Version` field to detect concurrent updates; Hibernate increments it and throws
+`OptimisticLockingFailureException` on a stale write. Cheaper than pessimistic locks for
+low-contention web apps.
+
+```java
+@Version private long version;
+```
+
+## Migrations
+
+Let **Flyway** (`V1__init.sql`, `V2__add_index.sql`) or **Liquibase** own the schema; set
+`spring.jpa.hibernate.ddl-auto=validate` so Hibernate verifies but never mutates the schema.
+Never ship `ddl-auto=update` to production — it makes uncontrolled, unordered changes. The
+actual DDL/index design for those migration files is `../postgresdb/SKILL.md`.