refactor(skill): document functional style companion boundary

AGENTS.md

@@ -19,6 +19,7 @@ that correction durable in the relevant file under `docs/agents/`.
 - [Project Identity](docs/agents/project-identity.md)
 - [README Guidance](docs/agents/readme.md)
 - [Skill Behavior](docs/agents/skill-behavior.md)
+- [Ownership Boundaries](docs/agents/ownership-boundaries.md)
 - [Eval Guidance](docs/agents/evals.md)
 - [Public Metadata And OSS Readiness](docs/agents/public-metadata.md)
 - [Maintaining Agent Docs](docs/agents/maintaining-agent-docs.md)

README.md

@@ -15,12 +15,17 @@ use a plain branch when checked IO makes that clearer.
 It also tells the agent to check the project Java version first. The right Optional code for a
 Java 8 project may be different from the right code for Java 17 or Java 21.
 
+For general lambda, method-reference, identity-function, no-op functional stage, supplier/callback
+style, and callback readability guidance, install the companion package
+`martinfrancois/java-functional-style` together with this Optional package.
+
 ## Contents
 
 - [Getting Started](#getting-started)
 - [Why This Exists](#why-this-exists)
 - [What Good Looks Like](#what-good-looks-like)
 - [What It Helps With](#what-it-helps-with)
+- [Ownership Boundaries](#ownership-boundaries)
 - [Examples](#examples)
 - [How It's Evaluated](#how-its-evaluated)
 - [Contributing](#contributing)
@@ -214,6 +219,21 @@ Poor fit:
 - changing business behavior just to make code look more functional;
 - replacing every readable branch with a method chain.
 
+## Ownership Boundaries
+
+`java-optionals` owns Optional behavior: absence and fallback handling, Optional API choice,
+fallback laziness as Optional behavior, checked IO and prompt boundaries, primitive Optionals,
+Optional Java-version compatibility, and present/empty/error contract preservation.
+
+`java-functional-style` owns general Java lambda and functional-interface style: identity
+functions, no-op functional stages, method references, callback readability, supplier/callback
+style, and callback side-effect boundaries.
+
+`java-streams` owns stream and collector behavior.
+
+Install `java-optionals` and `java-functional-style` together for Optional cleanup involving
+non-trivial callbacks or generic functional-interface style.
+
 ## Examples
 
 Simple fallback:

docs/agents/ownership-boundaries.md

@@ -0,0 +1,39 @@
+# Ownership Boundaries
+
+## Scope
+
+Use this when changing runtime guidance, README wording, evals, or companion-package documentation
+for Java Optionals.
+
+## Rules
+
+- `java-optionals` owns Optional behavior: absence handling, fallback behavior, Optional API choice,
+  fallback laziness as Optional behavior, Java-version compatibility, primitive Optionals, checked
+  IO and prompt boundaries, parser boundaries, and present/empty/error contract preservation.
+- `java-functional-style` owns general Java lambda and functional-interface style: method
+  references, identity functions, no-op functional stages, callback readability, helper extraction,
+  supplier/callback style, and callback side-effect boundaries.
+- `java-streams` owns stream and collector behavior: terminal operation choice, collector choice,
+  duplicate-key and null behavior, encounter order, primitive streams, parallel streams, gatherers,
+  and stream-specific behavior preservation.
+- Do not add generic `Function.identity()`, no-op callback-stage, or broad callback-readability
+  rules to `java-optionals` just to cover companion-package behavior.
+- It is fine for Optional examples to use concise lambdas or suppliers when needed to demonstrate
+  Optional behavior. Do not present those examples as the canonical source for general functional
+  style.
+- The expected high-quality setup for Optional cleanup involving non-trivial callbacks or generic
+  functional-interface style is both `java-optionals` and `java-functional-style`.
+- Before opening a PR that changes Optional runtime guidance or evals as part of this split, prove:
+
+```text
+current java-optionals behavior <= slimmed java-optionals + java-functional-style behavior
+```
+
+- The comparison must use the existing Optional evals unchanged until the composed setup is equal or
+  better at criterion level. Local validation alone is not enough for that quality gate.
+
+## References
+
+- [Skill Behavior](skill-behavior.md)
+- [README Guidance](readme.md)
+- [Eval Guidance](evals.md)

docs/agents/readme.md

@@ -26,6 +26,9 @@ Use this when editing `README.md`, examples, motivation wording, or user-facing
   regression safety-net scenarios. Say that broader Optional coverage in `evals-reference/` and
   solved safety-net coverage in `evals-regression/` should be reported separately from the main
   score.
+- Keep the ownership boundary visible: `java-optionals` owns Optional behavior, and
+  `java-functional-style` owns generic lambda, method-reference, identity-function, no-op
+  functional-stage, supplier/callback style, and callback-readability guidance.
 - Use `main score` and `main eval set` consistently in public and maintainer docs.
 - Preserve maintainer-approved package-runner install examples such as `npx`, `yarn dlx`, `pnpx`,
   and `bunx` when they remain valid. Tessl's deprecated global npm install is a separate issue.
@@ -101,6 +104,7 @@ Use this when editing `README.md`, examples, motivation wording, or user-facing
 ## References
 
 - [Skill Behavior](skill-behavior.md)
+- [Ownership Boundaries](ownership-boundaries.md)
 - [Public Metadata And OSS Readiness](public-metadata.md)
 - [Maintaining Agent Docs](maintaining-agent-docs.md)
 - Runtime reference: `skills/java-optionals/references/hard-stops.md` lists replacement

docs/agents/skill-behavior.md

@@ -26,6 +26,9 @@ auto-selection wording.
 - Checked IO and prompt boundaries must not be hidden behind generic Optional helpers such as
   `OptionalSupport`, `OptionalIo`, `CheckedOptionals`, throwing suppliers, or supplier `.get()`
   tricks. Prefer a narrow plain branch at the actual boundary.
+- Generic lambda, method-reference, identity-function, no-op functional stage, and broad callback
+  readability guidance belongs to `java-functional-style`. Keep `java-optionals` focused on
+  Optional behavior and fallback semantics.
 - The skill must make the `optional.stream().toList()` rule operational. Agents should scan touched
   code before finalizing and rewrite any fake one-Optional collection or `for` loop over
   `optional.stream().toList()`.
@@ -57,3 +60,4 @@ auto-selection wording.
 
 - [README Guidance](readme.md)
 - [Eval Guidance](evals.md)
+- [Ownership Boundaries](ownership-boundaries.md)