mustflow 2.108.3 → 2.112.1

package/templates/default/locales/en/.mustflow/skills/java-code-change/SKILL.md

@@ -0,0 +1,499 @@
+---
+mustflow_doc: skill.java-code-change
+locale: en
+canonical: true
+revision: 3
+lifecycle: mustflow-owned
+authority: procedure
+name: java-code-change
+description: Apply this skill when Java source, Spring Boot or JPA transaction code, Maven or Gradle metadata, JVM toolchains, bytecode targets, binary compatibility surfaces, modules, nullability, Optional, records, sealed classes, reflection, serialization, final-field mutation, virtual threads, executors, ThreadLocal or ScopedValue context, structured concurrency, dependency resolution, multi-module boundaries, HTTP clients, applets or legacy desktop APIs, GC choice, allocation pressure, JVM flags, JFR, JMH, container memory or CPU behavior, tests, benchmarks, public APIs, or Java/JDK version-gated features are created or changed.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.java-code-change
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - mustflow_check
+---
+
+# Java Code Change
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Preserve Java API, JVM runtime, concurrency, reflection, serialization, module, build-tool,
+container, observability, GC, and performance boundaries while making a focused change.
+
+Java changes fail when the patch treats the JDK as only language syntax. The real contract includes
+the JDK track, bytecode target, framework reflection behavior, class loading, native memory, thread
+lifecycle, GC pause and throughput tradeoffs, and evidence from JFR, GC logs, or JMH.
+
+Modern-looking Java can still lie when `null`, `Optional`, records, sealed hierarchies, Maven, or
+Gradle hide domain states and module boundaries instead of making them explicit contracts.
+
+Spring and open-source Java changes also fail when a clean patch betrays already deployed users:
+transaction proxies, existing database flows, already compiled consumers, service provider loading,
+test discovery, and serialized payloads are compatibility contracts, not implementation details.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- `.java`, `.kt` Java interop surfaces, `pom.xml`, `build.gradle`, `build.gradle.kts`,
+  `gradle.properties`, Maven or Gradle wrapper files, toolchains, module descriptors, public Java
+  APIs, tests, benchmarks, generated code, serialization shapes, reflection, bytecode targets,
+  annotation processors, JVM flags, or deployment runtime metadata change.
+- The task touches virtual threads, thread pools, `ThreadLocal`, `ScopedValue`, structured
+  concurrency, cancellation, blocking I/O, CPU-bound work, locks, request context propagation,
+  servlet or HTTP client behavior, nullability, `Optional`, final fields, reflection, records,
+  sealed classes, modules, applets or legacy Swing APIs, native images, AOT caches, GC, JFR, JMH,
+  container memory, CPU limits, or startup and warmup behavior.
+- The task touches Spring `@Transactional`, JPA entity or repository behavior, Spring Security
+  matchers, Actuator exposure, OSIV, request binding, async execution, transactional events, bulk
+  updates, locking, pagination, exports, or mass-assignment-sensitive request models.
+- The task changes public or protected Java members, constants, interfaces, generic bounds, service
+  providers, SPI files, module descriptors, test framework baselines, Surefire or Failsafe discovery
+  patterns, binary compatibility checks, serialized classes, or consumer-facing library artifacts.
+- The task changes Maven or Gradle dependency declarations, `api` versus `implementation`, Maven
+  scopes, parent or aggregator POMs, BOM or dependency management, version catalogs, convention
+  plugins, exclusions, dynamic versions, publishing metadata, or multi-module boundaries.
+- Code or docs use Java-version-gated features such as module import declarations, compact source
+  files, instance main methods, flexible constructor bodies, `ScopedValue`, structured concurrency,
+  primitive pattern matching, final-field reflection restrictions, applet API removal, HTTP/3 in
+  `java.net.http.HttpClient`, AOT cache or method profiling, Compact Object Headers, Generational
+  Shenandoah, JFR method timing, KDF APIs, PEM APIs, Vector API, or other preview/incubator APIs.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- Java or JVM files are read-only context and no Java, build, test, runtime, or documentation surface
+  changes.
+- A generated Java file should be regenerated by a declared command rather than edited.
+- The task only compares runtime targets without changing Java surfaces; use
+  `runtime-target-selection` first.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Maven or Gradle metadata, wrapper versions, toolchain declarations, source and target release,
+  annotation processors, generated-code markers, test configuration, benchmark configuration, and
+  CI or container runtime hints.
+- The minimum supported Java version, intended JDK vendor, current GA versus LTS policy, bytecode
+  compatibility target, repository runtime matrix, and whether preview or incubator APIs are allowed.
+- Relevant modules, packages, public exports, serialized forms, reflection entry points, framework
+  adapters, generated bindings, tests, benchmarks, and docs examples.
+- Spring context when present: proxy mode, transaction owner, propagation, rollback rules, async
+  boundaries, event listener phase, JPA persistence context, OSIV policy, entity exposure, security
+  filter chains, CORS, CSRF, Actuator, and request DTO mapping.
+- Public-library compatibility context: supported source and runtime floor, old consumer binaries,
+  previous released jar, japicmp or Revapi availability, ServiceLoader or SPI discovery, test
+  discovery pattern, and serialized payload compatibility expectations.
+- Domain meanings for absent values, such as not loaded, not found, forbidden, deleted, lookup
+  failed, backend unavailable, defaulted, redacted, or intentionally empty.
+- Dependency graph and module-boundary evidence: Maven parent versus aggregator role, Gradle
+  project boundaries, public dependency surface, runtime scopes, transitive dependency expectations,
+  lockfiles, BOMs, version catalogs, and publication metadata.
+- Runtime and deployment context when the change touches server startup, HTTP clients, thread
+  pools, virtual threads, containers, GC, memory flags, JFR, JMH, native memory, class loading,
+  direct buffers, or CPU limits.
+- Runtime pressure evidence when performance is involved: allocation rate, TLAB and outside-TLAB
+  allocation, humongous objects, boxed primitive churn, collection resizing, string or regex churn,
+  executor queue length, rejection behavior, downstream pool limits, and cancellation propagation.
+- Configured verification intents.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- Inspect build metadata before using newer Java syntax, APIs, preview features, or JVM flags.
+- Determine whether the change affects public API, binary compatibility, serialized shape,
+  reflection, module access, thread ownership, shutdown, resource cleanup, performance, or
+  deployment runtime behavior.
+- If a Java release, latest Java, latest LTS, support status, JEP status, JVM flag, GC behavior,
+  preview or incubator feature, framework minimum Java version, or toolchain claim is written
+  durably, use `version-freshness-check` with official Java, OpenJDK, vendor, or build-tool sources.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Preserve repository bytecode, source, and runtime compatibility unless the task explicitly asks
+  for a migration and the affected surfaces can be synchronized.
+- Keep public API, serialized forms, and module exports compatible unless a breaking-change plan is
+  explicit.
+- Use virtual threads for blocking I/O concurrency, not as CPU parallelism. Do not pool virtual
+  threads.
+- Prefer immutable scoped context through `ScopedValue` when the supported Java version allows it
+  and the context is truly scoped and read-only.
+- Keep JFR, GC logs, JMH, or representative runtime evidence ahead of JVM flag tuning or performance
+  claims.
+- Do not add preview, incubator, vendor-specific, or experimental JVM features to public APIs or
+  durable examples without an explicit support policy and fallback.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Read build metadata, wrapper files, toolchain declarations, module descriptors, generated-file
+   markers, public API entry points, tests, benchmarks, and deployment hints.
+2. Classify the change as source syntax, public API, binary compatibility, serialized form, build
+   metadata, dependency, reflection, module access, concurrency, HTTP, startup, GC or JVM tuning,
+   container behavior, observability, benchmark, or test-only.
+3. Review null and absence semantics:
+   - do not use one `null` or `Optional.empty()` bucket for not loaded, not found, forbidden,
+     deleted, lookup failed, backend unavailable, redacted, or intentionally empty;
+   - validate required values before writes, events, cache updates, or other side effects;
+   - reject `null` elements inside collections unless a legacy boundary explicitly documents them;
+   - prefer domain result types for meaningful absence and failure states.
+4. Review `Optional` boundaries:
+   - use `Optional` mainly as a return protocol, not as DTO, entity, or long-lived object state;
+   - remember an `Optional` field can itself be `null` and can complicate JSON, ORM, and framework
+     mapping;
+   - treat `Optional` as a value-based class: avoid identity equality, identity hash, and
+     synchronization on it;
+   - distinguish `Optional.of()` as a non-null assertion from `Optional.ofNullable()` at uncertain
+     boundaries;
+   - reject `isPresent()` plus `get()` null-check cosplay, eager `orElse(expensive())`, and
+     `map()` paths that silently convert buggy mapper `null` results into empty values.
+5. Review records and sealed classes as contracts:
+   - records are shallowly immutable; mutable components need defensive copies in constructors and
+     accessors;
+   - a record header is public API for construction, accessors, equality, hashing, and string output;
+   - array record components use reference equality in generated `equals` and `hashCode`;
+   - do not leak secrets through generated `toString()` or parse it as a stable format;
+   - sealed classes control inheritance, not plugin extension; `non-sealed` reopens the hierarchy;
+   - check package or module placement, permitted subclasses, and exhaustive switch behavior when a
+     hierarchy changes without every consumer recompiling.
+6. Build the Java version ledger before changing code:
+   - current repository source and target release;
+   - minimum supported runtime;
+   - CI and container runtime versions;
+   - current GA, latest LTS, and vendor-support track when the patch mentions "latest",
+     "current", "recommended", "LTS", "deprecated", or "removed";
+   - preview, incubator, experimental, product, and default-enabled status for every JDK feature
+     mentioned.
+7. Do not collapse JDK tracks:
+   - latest GA is not automatically the production baseline;
+   - latest LTS is not automatically the repository runtime;
+   - a JEP being delivered, preview, incubator, product, or removed changes how safe it is to write
+     code or docs;
+   - vendor support and licensing can matter for deployment even when OpenJDK source status is clear.
+8. Check source and bytecode compatibility:
+   - use `--release` or the build tool equivalent when compiling for older runtimes;
+   - avoid APIs unavailable on the target runtime even if the local JDK compiles them without
+     `--release`;
+   - treat records, sealed classes, pattern matching, module imports, compact source files, instance
+     main methods, flexible constructor bodies, and primitive patterns as version-gated features.
+9. Treat preview and incubator APIs as migration-sensitive:
+   - do not expose structured concurrency preview types in public APIs unless the project explicitly
+     accepts preview churn;
+   - keep Vector API, Lazy Constants, primitive patterns, and other preview or incubator features
+     behind tests, flags, internal adapters, or fallback paths;
+   - report the exact JDK floor and preview flag requirement when used.
+10. Preserve public Java contracts:
+   - exported classes, interfaces, methods, fields, annotations, exceptions, generic signatures,
+     module exports, service providers, records, sealed hierarchy members, enum constants, and
+     serialized forms can be compatibility surfaces;
+   - adding a method to an interface can break implementers;
+   - changing `equals`, `hashCode`, `compareTo`, nullability, exception types, or annotation
+     retention can break callers without changing signatures.
+11. Review binary compatibility for already compiled consumers:
+   - do not trust repository search to prove a public or protected member, constructor, field,
+     interface method, class modifier, or constant is safe to remove or change;
+   - use `--release` or equivalent toolchain checks to protect the library's minimum runtime API,
+     not only source and target class-file versions;
+   - distinguish the JDK that runs Maven or Gradle from the JDK that compiles, tests, and runs the
+     published artifact;
+   - treat test dependencies such as JUnit majors as contributor baseline changes even when runtime
+     artifacts are unaffected;
+   - verify Surefire, Failsafe, JUnit Platform, nested tests, integration-test phases, and naming
+     patterns so added tests actually run;
+   - keep deprecated wrappers, adapters, sub-interfaces, or major-version boundaries when changing
+     public/protected methods, fields, constructors, `static`, `final`, access levels, return types,
+     generic bounds, bridge-sensitive signatures, or compile-time constants;
+   - test ServiceLoader, `META-INF/services`, module `provides` and `uses`, public no-arg provider
+     constructors, reflection entry points, and sample consumer jar loading when SPI behavior moves;
+   - protect `Serializable`, exception classes, enum shapes, record shapes, `serialVersionUID`, and
+     golden serialized payloads when stored or cross-version data may exist.
+12. Review reflection and final fields:
+   - treat deep reflection into private or final fields as a framework, serializer, test, or module
+     contract;
+   - if code mutates `final` fields reflectively, check JDK final-field restriction status, required
+     flags, warnings, serializer behavior, and test helpers;
+   - prefer constructors, builders, factories, records, or explicit deserialization hooks over
+     mutating finals after construction;
+   - when modules are present, keep `exports`, `opens`, and command-line open flags deliberate and
+     narrow.
+13. Check legacy API removal before migrating runtime:
+   - scan direct and transitive legacy surfaces when raising to a newer JDK, especially `java.applet`
+     and `javax.swing.JApplet` dependencies;
+   - direct use, generated code, old vendor SDKs, classroom code, or legacy Swing helpers can fail
+     even when the application no longer has browser applets.
+14. Design concurrency by workload:
+    - use virtual threads for high-concurrency blocking I/O paths, not CPU-bound parallelism;
+    - do not hide CPU work behind virtual threads when a bounded executor, work queue, or
+      parallelism limit is the real policy;
+    - do not pool virtual threads; create them per task through the supported executor or framework
+      integration;
+    - keep pinning risks visible for native calls, foreign functions, class initialization, monitor
+      usage, and blocking sections that cannot unmount.
+15. Review executor and backpressure behavior:
+    - treat virtual-thread-per-task executors as cheap thread creation, not unlimited downstream
+      capacity;
+    - put concurrency limits at the scarce resource boundary: database pools, HTTP clients, Redis,
+      file descriptors, rate limits, semaphores, bounded queues, or bulkheads;
+    - do not send blocking I/O to `CompletableFuture` default async methods, `ForkJoinPool`
+      `commonPool`, or `parallelStream` without an explicit executor decision;
+    - remember fixed thread pools can hide overload behind unbounded queues and cached thread pools
+      can create unbounded platform threads;
+    - review `ThreadPoolExecutor` core size, max size, queue type, timeout, rejection policy, and
+      `CallerRunsPolicy` or abort behavior as one saturation contract;
+    - keep parent ownership, timeout, cancellation, and result-write rules explicit when `Future`,
+      `CompletableFuture`, executor submissions, or structured concurrency fan-out are used.
+16. Review scoped context:
+    - treat `ThreadLocal` as a memory and lifecycle risk in virtual-thread-heavy paths;
+    - use `ScopedValue` for immutable request, auth, tenant, tracing, or audit context only when the
+      JDK support matrix allows it;
+    - do not use scoped context as dependency injection or a mutable configuration bag;
+    - clear or bound `ThreadLocal` values in platform-thread pools and framework callbacks.
+17. Structure task lifetimes:
+    - when using structured concurrency, name the owner, failure policy, cancellation rule, timeout,
+      and join boundary;
+    - do not leak preview structured-concurrency types into public library contracts without an
+      explicit compatibility plan;
+    - avoid fire-and-forget threads unless a long-lived owner starts, stops, joins, and reports them.
+18. Check HTTP clients and server behavior:
+    - reuse clients and connection pools instead of creating them per request;
+    - set connect, request, read, and overall operation timeouts at the owner boundary;
+    - treat Java `HttpClient` HTTP/3 support as client-side and opt-in unless current official docs
+      say otherwise;
+    - do not imply Java HTTP/3 provides a generic QUIC API, server API, or automatic protocol change.
+19. Review Spring Boot, JPA, and security boundaries when present:
+    - verify `@Transactional` is reached through the proxy; self-invocation such as `this.save()`
+      does not prove a transaction boundary;
+    - make rollback rules explicit for checked exceptions when rollback, not commit, is required;
+    - treat `REQUIRES_NEW` as a connection-pool and deadlock risk, especially inside loops or
+      request-per-item auxiliary writes;
+    - keep external API calls, S3, email, Kafka sends, payment providers, and blocking network waits
+      outside long database transactions; prefer outbox or after-commit handoff with clear semantics;
+    - do not assume `@Async`, `CompletableFuture`, executor work, or `parallelStream` inherits the
+      transaction context; pass IDs and value objects rather than live entities;
+    - treat `@TransactionalEventListener(AFTER_COMMIT)` database writes as requiring an intentional
+      new transaction or an outbox record created before commit;
+    - after JPA bulk update or delete, decide whether to flush and clear the persistence context
+      before reusing loaded entities;
+    - protect inventory, points, coupons, credits, balances, and ownership changes with optimistic
+      locking, conditional updates, pessimistic locks, idempotency keys, or database constraints;
+    - avoid returning entities directly when OSIV or lazy loading can move queries into controller
+      rendering or JSON serialization;
+    - cap page sizes, `IN` lists, exports, offsets, and request-driven repository reads; use jobs,
+      cursors, fetch sizes, timeouts, and rate limits for heavy paths;
+    - bind external requests to DTOs or allowlisted fields, not entities with privileged fields;
+    - review Spring Security filter-chain matchers, unprotected paths, Actuator, Swagger, H2 console,
+      CORS ordering, and CSRF decisions instead of assuming URL patterns protect everything.
+20. Separate AOT cache from native image:
+    - Java AOT cache and method profiling reduce JVM startup or warmup by recording JVM-visible
+      state from training runs;
+    - do not describe JVM AOT cache as producing a standalone native binary;
+    - check training-run representativeness, classpath stability, CDS or AOT cache invalidation, GC
+      compatibility, and deployment reproducibility before enabling it.
+21. Tune GC only from evidence:
+    - G1 pause targets are goals, not SLAs. Lowering `MaxGCPauseMillis` can reduce young-gen size,
+      increase GC frequency, and hurt throughput;
+    - inspect humongous objects, allocation rate, evacuation failures, remembered sets, Full GC, and
+      old-region growth before changing G1 flags;
+    - ZGC and Shenandoah trade CPU and headroom for lower pauses; they are not free latency switches;
+    - Generational Shenandoah, Compact Object Headers, and similar features may be product features
+      without being default-enabled;
+    - explicit `System.gc()` calls, `DisableExplicitGC`, and concurrent explicit GC flags are
+      observable runtime policy, not formatting.
+22. Reduce allocation pressure from evidence, not folklore:
+    - optimize allocation rate, live set, peak memory, and object lifetime before chanting "avoid
+      `new`";
+    - inspect JFR allocation events such as new-TLAB, outside-TLAB, and thread allocation statistics
+      before rewriting hot paths;
+    - avoid pooling ordinary short-lived DTOs, builders, lists, or event objects when that only
+      promotes them into longer-lived state and adds locks or stale-data cleanup risk;
+    - prefer primitive arrays, packed values, primitive-specialized collections, or structure-of-array
+      layouts for dense hot-loop data where object headers and pointer chasing dominate;
+    - watch boxed primitives, generic callbacks, varargs, `Stream<Integer>`, and `Optional<Integer>`
+      on hot paths;
+    - size collections from realistic p95 counts rather than defaults or oversized guesses;
+    - cache or reuse regex `Pattern`s and avoid repeated string split, case conversion, substring,
+      JSON-path construction, and concat loops in request hot paths;
+    - treat large arrays and buffers as G1 humongous-object risks and prefer chunking, streaming,
+      paging, buffer caps, or region-size review over simply raising heap;
+    - do not pin G1 young-generation sizing unless evidence shows that overriding pause-time control
+      is the intended tradeoff;
+    - consider compressed-oops thresholds, multiple JVMs versus one large heap, and compact object
+      header experiments only with JFR, GC log, RSS, CPU, and latency evidence.
+23. Budget container memory and CPU explicitly:
+    - heap is only part of RSS. Account for direct buffers, metaspace, code cache, thread stacks, JNI,
+      native allocations, GC native memory, memory-mapped files, and libc allocator behavior;
+    - do not set `-Xmx` equal to the container limit without headroom;
+    - review `MaxRAMPercentage`, `InitialRAMPercentage`, `MaxDirectMemorySize`, metaspace, code
+      cache, and thread-count effects together;
+    - review `ActiveProcessorCount`, CPU quota, cpuset, ForkJoinPool sizing, GC thread counts, and
+      multiple JVMs per node before explaining throughput or latency changes.
+24. Keep performance measurement honest:
+    - use JMH for microbenchmarks instead of hand-rolled `System.nanoTime` loops;
+    - include warmup, forks, dead-code elimination guards, representative data, and allocation
+      metrics when benchmark claims matter;
+    - use JFR, GC logs, native memory tracking, heap dumps, thread dumps, async-profiler or
+      equivalent profiler evidence according to the symptom;
+    - do not call a JVM flag or GC change successful from a local warm-cache run, empty dataset,
+      debug logging path, or startup-only timing unless that is the actual product metric.
+25. Review serialization and data compatibility:
+    - Java serialization, Jackson, Gson, Kryo, protobuf, Avro, Hibernate, and reflection-heavy
+      frameworks can depend on constructors, final-field mutation, modules, annotations, records,
+      parameter names, sealed classes, default values, and no-arg constructors;
+    - keep unknown-field, defaulting, enum, and schema evolution behavior explicit when data crosses
+      process or storage boundaries.
+26. Keep build tooling synchronized:
+    - Maven compiler plugin, Gradle toolchains, wrapper versions, annotation processors, test
+      engines, bytecode instrumentation, shading, jlink, jpackage, and native-image tasks can each
+      have their own JDK support boundary;
+    - do not raise a toolchain, source level, target release, dependency bytecode floor, or plugin
+      major without checking CI, container, IDE, and downstream consumers.
+27. Review Maven, Gradle, and multi-module dependency boundaries:
+    - treat modules as compile, dependency, and deploy boundaries, not folder cleanup;
+    - reject `common`, `shared`, `core`, or `util` sink modules that erase ownership and import
+      direction;
+    - keep Maven parent inheritance separate from aggregator reactor membership;
+    - avoid Gradle `allprojects` and `subprojects` cross-project magic for real build policy; prefer
+      convention plugins or `build-logic` when shared behavior is intentional;
+    - use Gradle `api` only for public types and `implementation` for internal dependencies;
+    - remember Maven `dependencyManagement` manages versions but does not add dependencies and does
+      not govern plugin transitive dependencies;
+    - account for Maven nearest-wins resolution, optional dependencies, and path-local exclusions;
+    - do not treat a Gradle version catalog as a BOM or enforced constraint;
+    - use `force`, broad excludes, and `transitive = false` only as last-resort masking tools;
+    - check `compileOnly`, `provided`, `runtimeOnly`, and `testImplementation` against the runtime
+      provider, not just local test success;
+    - lock or avoid dynamic versions and snapshots when reproducible builds matter;
+    - check Gradle variant-aware resolution versus Maven POM publication metadata when publishing
+      Java libraries.
+28. Choose configured verification intents that cover compilation, tests, docs, package output,
+    benchmarks, runtime flags, and template or release metadata when available.
+
+<!-- mustflow-section: rejection-criteria -->
+## Review Rejection Criteria
+
+Reject or revise the patch when any of these appear without strong local justification:
+
+- A latest-GA or LTS Java claim written without a current source ledger.
+- New preview, incubator, or vendor-specific APIs in public APIs or durable examples without a
+  support policy.
+- Public or protected API, `static`, `final`, access, return type, generic-bound, constant, SPI,
+  `ServiceLoader`, test-baseline, or serialized-form changes without old-consumer or compatibility
+  review.
+- Spring self-invoked `@Transactional` methods, checked-exception rollback assumptions,
+  `REQUIRES_NEW` fan-out, external calls inside transactions, async transaction-context assumptions,
+  after-commit DB writes, stale persistence-context reuse after bulk updates, or entity request
+  binding.
+- Security config that narrows Spring Security matchers while leaving Actuator, internal, Swagger,
+  H2, CORS, or CSRF behavior unreviewed.
+- Executor changes that hide overload in unbounded queues, send blocking work to common pools, lack
+  rejection policy, or miss downstream backpressure.
+- One `null` or `Optional.empty()` path standing for multiple domain states such as not found,
+  forbidden, deleted, lookup failed, or backend unavailable.
+- `Optional` stored as DTO, entity, or mutable state, `isPresent()` plus `get()`, eager
+  `orElse(expensive())`, or `Optional.map()` hiding a mapper `null` bug.
+- Record components with mutable collections or arrays and no defensive-copy or equality decision.
+- Sealed hierarchy changes that ignore `non-sealed`, package or module restrictions, permitted
+  subclasses, or exhaustive switch compatibility.
+- Maven or Gradle module changes that create sink modules, hidden cross-project configuration,
+  accidental `api` leakage, Maven nearest-wins surprises, version-catalog-as-BOM confusion, or
+  runtime scope gaps.
+- New virtual-thread use for CPU-bound work, virtual-thread pooling, or unbounded task fan-out.
+- New `ThreadLocal` request context in high-concurrency or virtual-thread paths without cleanup,
+  memory accounting, or a scoped alternative.
+- New structured-concurrency preview types exported from a library boundary.
+- New reflective mutation of final fields, broad module `opens`, or serializer magic without a JDK
+  compatibility plan.
+- New JVM flags that change GC, heap, direct memory, CPU count, explicit GC, or AOT behavior without
+  JFR, GC log, benchmark, or runtime evidence.
+- Allocation rewrites based on `new` folklore instead of allocation rate, live set, TLAB, humongous
+  object, boxing, collection sizing, or string/regex evidence.
+- New `-Xmx` or `MaxRAMPercentage` settings that ignore native memory, direct buffers, metaspace,
+  code cache, stacks, and container headroom.
+- New G1, ZGC, Shenandoah, Compact Object Headers, or AOT claims that treat opt-in or goal-based
+  behavior as default or guaranteed.
+- New hand-rolled microbenchmarks that can be optimized away by the JIT.
+- New applet, removed API, or legacy `javax.swing.JApplet` dependency on a runtime where the API is
+  gone.
+- Public API, serialized form, module exports, annotation contracts, or bytecode floor changes
+  without compatibility review.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Java version, source target, runtime target, and preview/incubator status are explicit where
+  relevant.
+- Public API, bytecode, module, reflection, serialization, and framework compatibility are preserved
+  or the breaking-change requirement is reported.
+- Spring transaction, JPA persistence, security matcher, request binding, pagination, and entity
+  exposure risks are explicit where touched.
+- Binary compatibility, old compiled consumers, test discovery, SPI, ServiceLoader, and serialized
+  payload compatibility are preserved or the breaking-change requirement is reported.
+- Absence semantics, nullability, `Optional`, record, and sealed hierarchy contracts are explicit
+  where touched.
+- Maven or Gradle dependency, scope, module, and publication boundaries are explicit where touched.
+- Virtual-thread, `ThreadLocal`, `ScopedValue`, structured-concurrency, cancellation, and thread
+  ownership choices are explicit where touched.
+- Executor saturation, downstream backpressure, allocation rate, object lifetime, GC choice, JVM
+  flags, AOT cache, container memory, CPU count, JFR, JMH, and profiling claims are evidence-backed
+  or downgraded.
+- Missing runtime matrix, JMH, JFR, GC-log, native-memory, container, or framework verification is
+  reported.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `lint`
+- `build`
+- `test_related`
+- `test`
+- `docs_validate_fast`
+- `mustflow_check`
+
+For Java-version-gated features, report whether the repository has a configured JDK matrix, bytecode
+target check, preview-enabled check, or framework compatibility check. For performance or JVM flag
+changes, report whether configured JMH, JFR, GC-log, container-smoke, native-memory, startup, or load
+verification exists.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If the supported Java version is unclear, do not use newer APIs or claims; preserve the existing
+  code style and report the missing version policy.
+- If a build passes locally but bytecode target, runtime image, or CI runtime is lower, treat the
+  change as unverified until the target runtime is checked.
+- If reflection, serialization, or module access fails after a JDK change, inspect framework
+  compatibility before broadening `opens` or adding command-line escapes.
+- If virtual-thread changes hang, leak, or slow CPU work, revisit workload classification and owner
+  cancellation before adding pools or timeouts.
+- If JVM tuning worsens tests or benchmarks, do not loosen assertions or invent flags; revert or
+  narrow the tuning decision unless the behavior change is intentional.
+- If generated code must change but no generator intent exists, report the missing command contract.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Java boundary checked
+- Version, toolchain, source target, runtime target, and preview/incubator notes
+- Public API, module, reflection, serialization, and bytecode impact
+- Nullability, Optional, record, sealed hierarchy, Maven, Gradle, dependency, and multi-module impact
+- Spring transaction, JPA, security, binary compatibility, SPI, test discovery, executor, allocation,
+  and backpressure notes when relevant
+- Virtual-thread, scoped context, structured concurrency, HTTP, GC, JVM flag, AOT, container, JFR,
+  JMH, and profiling notes when relevant
+- Files changed
+- Command intents run
+- Skipped checks and reasons
+- Remaining Java risk

package/templates/default/locales/en/.mustflow/skills/routes.toml

@@ -36,6 +36,12 @@ route_type = "primary"
 priority = 40
 applies_to_reasons = ["code_change", "behavior_change"]
 
+[routes."split-refactor-residual-path-review"]
+category = "architecture_patterns"
+route_type = "adjunct"
+priority = 79
+applies_to_reasons = ["unknown_change", "code_change", "behavior_change", "test_change", "public_api_change", "performance_change", "ui_change", "data_change"]
+
 [routes."composition-over-inheritance"]
 category = "architecture_patterns"
 route_type = "primary"
@@ -456,6 +462,12 @@ route_type = "primary"
 priority = 78
 applies_to_reasons = ["unknown_change", "code_change", "behavior_change", "migration_change", "package_metadata_change", "release_risk"]
 
+[routes."technology-stack-selection"]
+category = "architecture_patterns"
+route_type = "primary"
+priority = 79
+applies_to_reasons = ["unknown_change", "code_change", "behavior_change", "docs_change", "product_change", "cross_cutting_code_change", "data_change", "migration_change", "performance_change", "security_change", "privacy_change", "package_metadata_change", "release_risk"]
+
 [routes."structure-first-engineering"]
 category = "general_code"
 route_type = "adjunct"
@@ -534,6 +546,12 @@ route_type = "primary"
 priority = 85
 applies_to_reasons = ["code_change", "public_api_change", "test_change"]
 
+[routes."java-code-change"]
+category = "general_code"
+route_type = "primary"
+priority = 85
+applies_to_reasons = ["code_change", "behavior_change", "public_api_change", "test_change", "docs_change", "data_change", "performance_change", "security_change", "privacy_change", "package_metadata_change", "release_risk"]
+
 [routes."python-code-change"]
 category = "general_code"
 route_type = "primary"
@@ -738,6 +756,18 @@ route_type = "primary"
 priority = 86
 applies_to_reasons = ["code_change", "data_change", "migration_change", "behavior_change", "public_api_change", "test_change", "docs_change", "security_change", "performance_change"]
 
+[routes."clickhouse-code-change"]
+category = "data_external"
+route_type = "primary"
+priority = 86
+applies_to_reasons = ["code_change", "data_change", "migration_change", "behavior_change", "public_api_change", "test_change", "docs_change", "security_change", "performance_change"]
+
+[routes."duckdb-code-change"]
+category = "data_external"
+route_type = "primary"
+priority = 86
+applies_to_reasons = ["code_change", "data_change", "migration_change", "behavior_change", "public_api_change", "test_change", "docs_change", "security_change", "performance_change"]
+
 [routes."search-index-integrity-review"]
 category = "data_external"
 route_type = "primary"
@@ -990,6 +1020,12 @@ route_type = "adjunct"
 priority = 80
 applies_to_reasons = ["ui_change", "behavior_change", "code_change", "performance_change", "data_change", "test_change", "public_api_change"]
 
+[routes."ui-state-resurrection-review"]
+category = "ui_assets"
+route_type = "adjunct"
+priority = 83
+applies_to_reasons = ["unknown_change", "ui_change", "behavior_change", "code_change", "performance_change", "data_change", "test_change", "public_api_change", "docs_change", "package_metadata_change", "release_risk"]
+
 [routes."frontend-stress-layout-review"]
 category = "ui_assets"
 route_type = "adjunct"
@@ -1176,6 +1212,12 @@ route_type = "primary"
 priority = 60
 applies_to_reasons = ["docs_change", "copy_change", "product_change"]
 
+[routes."writing-elegance"]
+category = "docs_release"
+route_type = "primary"
+priority = 62
+applies_to_reasons = ["docs_change", "copy_change", "workflow_change", "release_risk", "unknown_change"]
+
 [routes."docs-prose-review"]
 category = "docs_release"
 route_type = "adjunct"