fix: document Java gatherer preview requirements

martinfrancois · martinfrancois · commit b69a65f9347f · 2026-06-06T12:19:33.000+02:00
diff --git a/.github/workflows/release-please.yml b/.github/workflows/release-please.yml
@@ -148,8 +148,8 @@ jobs:
           printf '{"private":true}\n' > "$commitlint_home/package.json"
           cp commitlint.config.cjs "$commitlint_home/commitlint.config.cjs"
           npm --prefix "$commitlint_home" install --silent \
-            @commitlint/cli@21.0.1 \
-            @commitlint/config-conventional@21.0.1
+            @commitlint/cli@21.0.2 \
+            @commitlint/config-conventional@21.0.2
 
           commitlint_bin="$commitlint_home/node_modules/.bin/commitlint"
           commitlint_config="$commitlint_home/commitlint.config.cjs"
diff --git a/README.md b/README.md
@@ -175,6 +175,9 @@ problems:
 
 ### With The Skill: `Gatherers.mapConcurrent`
 
+When the project uses Java 24 with preview features enabled, `Gatherers.mapConcurrent` gives a
+bounded concurrent stream operation for this kind of blocking per-element work:
+
 ```java
 List<Product> favoriteProducts(User user) {
     return user.favoriteProducts().stream()
@@ -227,7 +230,7 @@ Good fit:
 - avoiding null-sensitive sorting and duplicate-key `toMap` failures;
 - deciding whether `parallelStream()` is actually appropriate;
 - choosing Java-version-compatible APIs such as `takeWhile`, `mapMulti`, `Stream.toList()`, and
-  gatherers.
+  gatherers. For Java 24 gatherers, the project must explicitly enable preview features.
 
 Poor fit:
 
diff --git a/evals-reference/12-remote-stock-review/capability.txt b/evals-reference/12-remote-stock-review/capability.txt
@@ -1 +1 @@
-Review Java stream concurrency changes involving blocking per-element calls and Java 24 gatherers.
+Review Java stream concurrency changes involving blocking per-element calls and Java 24 preview-enabled gatherers.
diff --git a/evals-reference/12-remote-stock-review/criteria.json b/evals-reference/12-remote-stock-review/criteria.json
@@ -1,5 +1,5 @@
 {
-  "context": "Reference review: parallelStream is a weak answer for blocking remote calls; Java 24 allows discussing Gatherers.mapConcurrent.",
+  "context": "Reference review: parallelStream is a weak answer for blocking remote calls; Java 24 with preview features enabled allows discussing Gatherers.mapConcurrent.",
   "type": "weighted_checklist",
   "checklist": [
     {
@@ -21,10 +21,10 @@
       "description": "Explains that parallelStream uses the common fork-join pool, remains blocking, and is not the right default for remote API calls."
     },
     {
-      "name": "Recommends Java 24 mapConcurrent or explicit async boundary",
+      "name": "Recommends Java 24 preview mapConcurrent or explicit async boundary",
       "category": "stream_quality",
       "max_score": 30,
-      "description": "Recommends Gatherers.mapConcurrent with a bounded concurrency value, or an explicit executor/async design, rather than casual parallelStream."
+      "description": "Recommends Java 24 preview-enabled Gatherers.mapConcurrent with a bounded concurrency value, or an explicit executor/async design, rather than casual parallelStream."
     },
     {
       "name": "Keeps sorting after stock checks",
diff --git a/evals-reference/12-remote-stock-review/task.md b/evals-reference/12-remote-stock-review/task.md
@@ -1,6 +1,6 @@
 # Review remote stock stream change
 
-Assume Java 24.
+Assume Java 24 with preview features enabled.
 
 Use `$java-streams` to review this proposed change. Create `review.md` with a short review decision
 and a safer recommendation.
diff --git a/evals/01-offer-availability-mapconcurrent/capability.txt b/evals/01-offer-availability-mapconcurrent/capability.txt
@@ -1 +1 @@
-Implement a Java 24 stream chain for bounded concurrent offer availability checks without using parallelStream.
+Implement a Java 24 preview-enabled stream chain for bounded concurrent offer availability checks without using parallelStream.
diff --git a/evals/01-offer-availability-mapconcurrent/criteria.json b/evals/01-offer-availability-mapconcurrent/criteria.json
@@ -1,12 +1,12 @@
 {
-  "context": "Main eval weighted implementation: lowest without-context baseline in the all-eval run; Java 24 blocking per-element remote checks should use bounded Gatherers.mapConcurrent rather than parallelStream or unbounded async work.",
+  "context": "Main eval weighted implementation: lowest without-context baseline in the all-eval run; Java 24 preview-enabled blocking per-element remote checks should use bounded Gatherers.mapConcurrent rather than parallelStream or unbounded async work.",
   "type": "weighted_checklist",
   "checklist": [
     {
-      "name": "Creates coherent Java 24 artifact",
+      "name": "Creates coherent Java 24 preview artifact",
       "category": "safety",
       "max_score": 25,
-      "description": "Creates OfferAvailability.java with the requested method, nested types, imports, and Java 24-compatible code."
+      "description": "Creates OfferAvailability.java with the requested method, nested types, imports, and Java 24 preview-compatible code."
     },
     {
       "name": "Preserves offer behavior",
diff --git a/evals/01-offer-availability-mapconcurrent/task.md b/evals/01-offer-availability-mapconcurrent/task.md
@@ -1,6 +1,7 @@
 # Implement offer availability filtering
 
-Use `$java-streams` to create `OfferAvailability.java`. Assume Java 24.
+Use `$java-streams` to create `OfferAvailability.java`. Assume Java 24 with preview features
+enabled.
 
 Implement:
 
diff --git a/evals/02-favorite-products-mapconcurrent/capability.txt b/evals/02-favorite-products-mapconcurrent/capability.txt
@@ -1 +1 @@
-Implement a Java 24 stream chain for service-limited concurrent remote checks.
+Implement a Java 24 preview-enabled stream chain for service-limited concurrent remote checks.
diff --git a/evals/02-favorite-products-mapconcurrent/criteria.json b/evals/02-favorite-products-mapconcurrent/criteria.json
@@ -1,12 +1,12 @@
 {
-  "context": "Main eval weighted natural implementation: second-lowest without-context baseline in the all-eval run; Java 24 blocking per-element remote checks with a per-operation service concurrency limit should use a bounded stream concurrency shape rather than parallelStream or unbounded async work.",
+  "context": "Main eval weighted natural implementation: second-lowest without-context baseline in the all-eval run; Java 24 preview-enabled blocking per-element remote checks with a per-operation service concurrency limit should use a bounded stream concurrency shape rather than parallelStream or unbounded async work.",
   "type": "weighted_checklist",
   "checklist": [
     {
-      "name": "Creates coherent Java 24 artifact",
+      "name": "Creates coherent Java 24 preview artifact",
       "category": "safety",
       "max_score": 20,
-      "description": "Creates FavoriteProducts.java with the requested method, nested types, imports, and Java 24-compatible code."
+      "description": "Creates FavoriteProducts.java with the requested method, nested types, imports, and Java 24 preview-compatible code."
     },
     {
       "name": "Preserves favorite product behavior",
diff --git a/evals/02-favorite-products-mapconcurrent/task.md b/evals/02-favorite-products-mapconcurrent/task.md
@@ -1,6 +1,6 @@
 # Implement favorite product stock checks
 
-Create `FavoriteProducts.java`. Assume Java 24.
+Create `FavoriteProducts.java`. Assume Java 24 with preview features enabled.
 
 Implement:
 
diff --git a/evals/03-remote-stock-gatherer-review/capability.txt b/evals/03-remote-stock-gatherer-review/capability.txt
@@ -1 +1 @@
-Review a Java 24 stream refactor that incorrectly uses parallelStream for blocking remote stock checks.
+Review a Java 24 preview-enabled stream refactor that incorrectly uses parallelStream for blocking remote stock checks.
diff --git a/evals/03-remote-stock-gatherer-review/criteria.json b/evals/03-remote-stock-gatherer-review/criteria.json
@@ -1,5 +1,5 @@
 {
-  "context": "Main eval weighted explicit review: third-lowest without-context baseline in the all-eval run; parallelStream is a weak answer for blocking remote calls and Java 24 stream guidance should recommend bounded Gatherers.mapConcurrent.",
+  "context": "Main eval weighted explicit review: third-lowest without-context baseline in the all-eval run; parallelStream is a weak answer for blocking remote calls and Java 24 preview-enabled stream guidance should recommend bounded Gatherers.mapConcurrent.",
   "type": "weighted_checklist",
   "checklist": [
     {
@@ -24,7 +24,7 @@
       "name": "Recommends bounded Gatherers.mapConcurrent",
       "category": "stream_quality",
       "max_score": 120,
-      "description": "Recommends a Java 24 Gatherers.mapConcurrent stream chain with an explicit concurrency bound for the blocking stock checks."
+      "description": "Recommends a Java 24 preview-enabled Gatherers.mapConcurrent stream chain with an explicit concurrency bound for the blocking stock checks."
     },
     {
       "name": "Shows a safe stream shape",
diff --git a/evals/03-remote-stock-gatherer-review/task.md b/evals/03-remote-stock-gatherer-review/task.md
@@ -1,9 +1,9 @@
 # Review remote stock stream change
 
-Assume Java 24.
+Assume Java 24 with preview features enabled.
 
 Use `$java-streams` to review this proposed change. Create `review.md` with a short review decision
-and a safer Java 24 stream shape.
+and a safer Java 24 preview-enabled stream shape.
 
 The product service calls a remote inventory API inside `isInStock(product)`.
 
diff --git a/renovate.json b/renovate.json
@@ -21,7 +21,7 @@
     {
       "customType": "regex",
       "managerFilePatterns": [
-        "/^\\.github/workflows/commitlint\\.yml$/"
+        "/^\\.github/workflows/(?:commitlint|release-please)\\.yml$/"
       ],
       "matchStrings": [
         "(?:\\s+)(?<depName>@commitlint/(?:cli|config-conventional))@(?<currentValue>\\d+\\.\\d+\\.\\d+)"
diff --git a/scripts/validate_eval_criteria.py b/scripts/validate_eval_criteria.py
@@ -184,6 +184,13 @@ def validate_scenario(scenario: Path, main_eval_root: Path | None) -> list[str]:
     task_text = task_file.read_text(encoding="utf-8") if task_file.is_file() else ""
     if task_text and not re.search(r"\bAssume Java\s+\d+\b", task_text):
         failures.append(f"{task_file}: task must state the Java version to assume, e.g. 'Assume Java 17.'")
+    scenario_text = task_text + "\n" + json.dumps(data)
+    if (
+        re.search(r"\bJava 24\b", scenario_text)
+        and re.search(r"\b(?:Gatherers?|mapConcurrent)\b|\.gather\(", scenario_text)
+        and "preview" not in scenario_text.lower()
+    ):
+        failures.append(f"{task_file}: Java 24 gatherer scenarios must state that preview features are enabled")
     has_explicit_invocation = invocation_from_task(task_text)
     if invocation == "natural" and has_explicit_invocation:
         failures.append(f"{task_file}: natural scenario explicitly invokes the skill")
diff --git a/skills/java-streams/references/hard-stops.md b/skills/java-streams/references/hard-stops.md
@@ -39,9 +39,10 @@ Fix these before finalizing:
   `Map.entry` only on Java 9+ when both values are non-null; otherwise use a null-tolerant holder
   such as `AbstractMap.SimpleImmutableEntry` or a project type.
 - Java-version drift: `toList`, `mapMulti`, `teeing`, `takeWhile`, `dropWhile`, `Optional.stream`,
-  `Collectors.flatMapping`, `Stream.ofNullable`, or gatherers used below their minimum Java version.
-  For a version-drift audit, report these unavailable APIs and explicitly allowed markers only; do
-  not add unrelated `groupingBy` null-key or collector-safety caveats.
+  `Collectors.flatMapping`, `Stream.ofNullable`, gatherers used below their minimum Java version, or
+  Java 24 gatherers used without preview features enabled. For a version-drift audit, report these
+  unavailable APIs and explicitly allowed markers only; do not add unrelated `groupingBy` null-key or
+  collector-safety caveats.
 - Missing imports for stream APIs introduced by the rewrite, such as `Comparator`, `Map`,
   `Collectors`, or `Gatherers`.
 
@@ -66,11 +67,12 @@ Use parallel streams only after checking:
 1. Work per element is CPU-heavy enough to amortize split/merge overhead.
 2. Operations are stateless and non-interfering.
 3. Encounter order is not required, or the ordered stream terminal operation is still worth the cost.
-4. The stream chain does not perform blocking IO or remote calls. For Java 24+ blocking per-element
-   calls, consider `Gatherers.mapConcurrent` only when the baseline supports it and virtual-thread
-   concurrency is the intended design. Preserve element/result association explicitly with
-   a baseline-compatible holder rather than null sentinels or side maps. For remote calls, call out
-   the concurrency limit, timeout handling for slow calls, and error propagation/retry policy.
+4. The stream chain does not perform blocking IO or remote calls. For Java 24 preview-enabled
+   blocking per-element calls, consider `Gatherers.mapConcurrent` only when the baseline supports it,
+   preview features are enabled, and virtual-thread concurrency is the intended design. Preserve
+   element/result association explicitly with a baseline-compatible holder rather than null sentinels
+   or side maps. For remote calls, call out the concurrency limit, timeout handling for slow calls,
+   and error propagation/retry policy.
 5. The stream terminal operation or collector is safe under parallel execution.
 
 For acceptable CPU-heavy parallel streams, state that the benefit should be measured or benchmarked
diff --git a/skills/java-streams/references/java-stream-api.md b/skills/java-streams/references/java-stream-api.md
@@ -25,7 +25,7 @@ If the baseline is unclear, prefer Java 8-compatible stream code or state the as
 | `Optional.stream` | 9 | Flatten `Stream<Optional<T>>` with `flatMap(Optional::stream)`. |
 | `Stream.toList()` | 16 | Returns an unmodifiable list; not equivalent to mutable `Collectors.toList()`. Do not use when callers or later code mutate the list. |
 | `mapMulti` and primitive `mapMulti` variants | 16 | Efficient one-to-few mapping when clearer than `flatMap`. |
-| `Stream.gather(Gatherer)` / built-in gatherers | 24 | Advanced extension point; `Gatherers.mapConcurrent` can help blocking per-element work. |
+| `Stream.gather(Gatherer)` / built-in gatherers | 24 preview | Advanced extension point; use Java 24 gatherers only when preview features are enabled with `--enable-preview`, or when the project targets a later Java version where the API is final. `Gatherers.mapConcurrent` can help blocking per-element work. |
 
 ## Collectors
 
diff --git a/skills/java-streams/references/stream-examples.md b/skills/java-streams/references/stream-examples.md
@@ -201,9 +201,10 @@ long result = LongStream.rangeClosed(1, 100_000)
         .sum();
 ```
 
-For Java 24+ blocking per-element calls, `Gatherers.mapConcurrent` can be more appropriate than
-`parallelStream` when the project intentionally uses virtual-thread concurrency. Keep concurrency
-bounded and call out timeout/error handling for remote API failures:
+For Java 24 projects with preview features enabled, `Gatherers.mapConcurrent` can be more appropriate
+than `parallelStream` for blocking per-element calls when the project intentionally uses
+virtual-thread concurrency. Keep concurrency bounded and call out timeout/error handling for remote
+API failures:
 
 ```java
 List<Product> favoriteProducts = user.getFavoriteProducts().stream()
@@ -216,10 +217,11 @@ List<Product> favoriteProducts = user.getFavoriteProducts().stream()
         .toList();
 ```
 
-`Map.entry` is appropriate in this example because the baseline is Java 24 and neither side of the
-entry is null. Do not return `null` from a `mapConcurrent` mapper to mean "skip"; carry the element
-with an explicit boolean result, then filter and map afterward. If nulls can reach the carrier or
-the baseline is Java 8, use a null-tolerant project type or `AbstractMap.SimpleImmutableEntry`.
+`Map.entry` is appropriate in this example because the baseline is Java 24 with preview features
+enabled and neither side of the entry is null. Do not return `null` from a `mapConcurrent` mapper to
+mean "skip"; carry the element with an explicit boolean result, then filter and map afterward. If
+nulls can reach the carrier or the baseline is Java 8, use a null-tolerant project type or
+`AbstractMap.SimpleImmutableEntry`.
 
 Use Java 12+ `Collectors.teeing` when two independent aggregates should be computed over the same
 input:

Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-Review Java stream concurrency changes involving blocking per-element calls and Java 24 gatherers.`
	`1`	`+Review Java stream concurrency changes involving blocking per-element calls and Java 24 preview-enabled gatherers.`
Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,5 @@`
`1`	`1`	`{`
`2`		`- "context": "Reference review: parallelStream is a weak answer for blocking remote calls; Java 24 allows discussing Gatherers.mapConcurrent.",`
	`2`	`+ "context": "Reference review: parallelStream is a weak answer for blocking remote calls; Java 24 with preview features enabled allows discussing Gatherers.mapConcurrent.",`
`3`	`3`	`"type": "weighted_checklist",`
`4`	`4`	`"checklist": [`
`5`	`5`	`{`
`@@ -21,10 +21,10 @@`
`21`	`21`	`"description": "Explains that parallelStream uses the common fork-join pool, remains blocking, and is not the right default for remote API calls."`
`22`	`22`	`},`
`23`	`23`	`{`
`24`		`- "name": "Recommends Java 24 mapConcurrent or explicit async boundary",`
	`24`	`+ "name": "Recommends Java 24 preview mapConcurrent or explicit async boundary",`
`25`	`25`	`"category": "stream_quality",`
`26`	`26`	`"max_score": 30,`
`27`		`- "description": "Recommends Gatherers.mapConcurrent with a bounded concurrency value, or an explicit executor/async design, rather than casual parallelStream."`
	`27`	`+ "description": "Recommends Java 24 preview-enabled Gatherers.mapConcurrent with a bounded concurrency value, or an explicit executor/async design, rather than casual parallelStream."`
`28`	`28`	`},`
`29`	`29`	`{`
`30`	`30`	`"name": "Keeps sorting after stock checks",`
Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-Implement a Java 24 stream chain for bounded concurrent offer availability checks without using parallelStream.`
	`1`	`+Implement a Java 24 preview-enabled stream chain for bounded concurrent offer availability checks without using parallelStream.`
Original file line number	Diff line number	Diff line change
`@@ -1,12 +1,12 @@`
`1`	`1`	`{`
`2`		`- "context": "Main eval weighted implementation: lowest without-context baseline in the all-eval run; Java 24 blocking per-element remote checks should use bounded Gatherers.mapConcurrent rather than parallelStream or unbounded async work.",`
	`2`	`+ "context": "Main eval weighted implementation: lowest without-context baseline in the all-eval run; Java 24 preview-enabled blocking per-element remote checks should use bounded Gatherers.mapConcurrent rather than parallelStream or unbounded async work.",`
`3`	`3`	`"type": "weighted_checklist",`
`4`	`4`	`"checklist": [`
`5`	`5`	`{`
`6`		`- "name": "Creates coherent Java 24 artifact",`
	`6`	`+ "name": "Creates coherent Java 24 preview artifact",`
`7`	`7`	`"category": "safety",`
`8`	`8`	`"max_score": 25,`
`9`		`- "description": "Creates OfferAvailability.java with the requested method, nested types, imports, and Java 24-compatible code."`
	`9`	`+ "description": "Creates OfferAvailability.java with the requested method, nested types, imports, and Java 24 preview-compatible code."`
`10`	`10`	`},`
`11`	`11`	`{`
`12`	`12`	`"name": "Preserves offer behavior",`
Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-Implement a Java 24 stream chain for service-limited concurrent remote checks.`
	`1`	`+Implement a Java 24 preview-enabled stream chain for service-limited concurrent remote checks.`
Original file line number	Diff line number	Diff line change
`@@ -1,12 +1,12 @@`
`1`	`1`	`{`
`2`		`- "context": "Main eval weighted natural implementation: second-lowest without-context baseline in the all-eval run; Java 24 blocking per-element remote checks with a per-operation service concurrency limit should use a bounded stream concurrency shape rather than parallelStream or unbounded async work.",`
	`2`	`+ "context": "Main eval weighted natural implementation: second-lowest without-context baseline in the all-eval run; Java 24 preview-enabled blocking per-element remote checks with a per-operation service concurrency limit should use a bounded stream concurrency shape rather than parallelStream or unbounded async work.",`
`3`	`3`	`"type": "weighted_checklist",`
`4`	`4`	`"checklist": [`
`5`	`5`	`{`
`6`		`- "name": "Creates coherent Java 24 artifact",`
	`6`	`+ "name": "Creates coherent Java 24 preview artifact",`
`7`	`7`	`"category": "safety",`
`8`	`8`	`"max_score": 20,`
`9`		`- "description": "Creates FavoriteProducts.java with the requested method, nested types, imports, and Java 24-compatible code."`
	`9`	`+ "description": "Creates FavoriteProducts.java with the requested method, nested types, imports, and Java 24 preview-compatible code."`
`10`	`10`	`},`
`11`	`11`	`{`
`12`	`12`	`"name": "Preserves favorite product behavior",`